Mirrors/ProxMenux
1
0
Fork 0
mirror of https://github.com/MacRimi/ProxMenux.git synced 2026-06-14 12:27:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

complete i18n migration to /[locale]/ with EN+ES content

Browse Source 
Full rewrite of the docs site under app/[locale]/ with next-intl
in localePrefix:"always" mode. Every page now exists at both
/en/<path> and /es/<path>; the root / shows a meta-refresh + JS
redirect to /<defaultLocale>/ so GitHub Pages serves something
on the apex URL.

Highlights:
- 107 doc pages migrated to file-per-page JSON namespaces under
  messages/en/ and messages/es/. Spanish content is fully
  translated (no copy-of-English placeholders).
- New documentation for the Active Suppressions section in the
  Settings tab and the per-event Dismiss dropdown in the Health
  Monitor modal.
- New screenshots: dismiss-duration-dropdown.png and an updated
  health-suppression-settings.png.
- Pagefind integrated for client-side search; index is built on
  every CI deploy (not committed).
- RSS feeds: per-locale at /<locale>/rss.xml plus root /rss.xml
  for backward compat.
- Removed the dead app/[locale]/guides/[slug]/ route — every
  guide now has its own static page and no markdown source
  remains.
- Fixed orphan link /guides/nvidia -> /guides/nvidia-manual in
  docs/hardware/nvidia-host.
- Removed obsolete components (footer2, calendar, drawer).

Verified locally with `npm ci && npm run build`: 2804 files in
out/, 231 pages indexed by pagefind, root redirect intact, both
locale roots and the new Active Suppressions docs render OK.
This commit is contained in:
MacRimi
2026-05-31 12:41:10 +02:00
parent 875910b4d7
commit 5ca3463bf6
649 changed files with 83958 additions and 11096 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
web/messages/en/docs/storage-share/host-iscsi.json Normal file
View File

@@ -0,0 +1,123 @@
{
"meta": {
"title": "Host: Add iSCSI target as Proxmox storage | ProxMenux Documentation",
"description": "Register an iSCSI target as Proxmox storage using ProxMenux. Handles open-iscsi install, portal discovery via sendtargets, target selection and pvesm add iscsi. Provides raw block devices for VM disk images.",
"ogTitle": "Host: Add iSCSI target as Proxmox storage | ProxMenux Documentation",
"ogDescription": "Register an iSCSI target as Proxmox storage with guided discovery. Uses pvesm add iscsi and provides raw block devices for VM disks."
},
"header": {
"title": "Host: Add iSCSI target as Proxmox storage",
"description": "Register an iSCSI target (from a SAN, TrueNAS / FreeNAS, Synology, a Windows Server target, any array that speaks iSCSI) as Proxmox storage. The exported LUNs appear as block devices and can host VM disk images at near-local performance over the network.",
"section": "Storage & Share · Host"
},
"intro": {
"title": "What this does",
"body": "ProxMenux wraps <code>pvesm add iscsi</code> with a guided flow: it installs <code>open-iscsi</code> if needed, asks for the iSCSI portal (IP:port), runs <code>iscsiadm --mode discovery --type sendtargets</code> against it, lets you pick a target IQN, and registers the iSCSI storage in Proxmox. The <code>iscsid</code> service then keeps the iSCSI session alive across reboots."
},
"vocab": {
"heading": "iSCSI vocabulary (quick reference)",
"headerTerm": "Term",
"headerMeaning": "Meaning",
"rows": [
{
"term": "Portal",
"meaningRich": "The iSCSI service endpoint on the target server — an IP (or hostname) plus a TCP port. Default port is <code>3260</code>; ProxMenux assumes it if you do not specify one."
},
{
"term": "Target",
"meaningRich": "A single exported \"server\" inside the portal, identified by its IQN (<em>iSCSI Qualified Name</em>). One portal can host many targets."
},
{
"term": "IQN",
"meaningRich": "Canonical form is <code>iqn.YYYY-MM.reverse.domain:identifier</code>, for example <code>iqn.2024-08.com.truenas:proxmox-pool</code>. Both the target and the initiator have their own IQN."
},
{
"term": "LUN",
"meaningRich": "A block device inside a target (Logical Unit Number). A single target can expose several LUNs; each LUN appears as its own disk in Proxmox and can become a VM disk."
},
{
"term": "Initiator",
"meaningRich": "The client that connects to a target — in this case, your Proxmox host. The initiator has its own IQN stored in <code>/etc/iscsi/initiatorname.iscsi</code>. Targets typically only accept sessions from pre-authorised initiator IQNs."
}
]
},
"opening": {
"heading": "Opening the tool",
"body": "From ProxMenux's main menu, open <strong>Storage &amp; Share Manager → Add iSCSI Target as Proxmox Storage</strong>. You will see this sub-menu with four options:",
"imageAlt": "iSCSI Host Manager menu — Add / View / Remove / Test connectivity"
},
"howRuns": {
"heading": "How the script runs (Add flow)",
"body": "The flow has two phases with clear separation between \"setting up the initiator, discovering targets\" and \"actually registering storage in Proxmox\". Unlike NFS / Samba, there is no auto-discovery on the subnet — you must know the portal address (iSCSI is not broadcast-friendly)."
},
"add": {
"heading": "Add iSCSI target as Proxmox storage",
"items": [
"<strong>Portal entry</strong> — type the IP or hostname of the iSCSI target server. Port <code>3260</code> is assumed unless you type <code>host:port</code>.",
"<strong>Target discovery</strong> — ProxMenux calls <code>iscsiadm --mode discovery --type sendtargets --portal &lt;ip:port&gt;</code>. The server responds with every IQN it allows this initiator to see. If discovery fails, the script shows the exact error from <code>iscsiadm</code> and lists common causes (wrong IP, firewall, initiator IQN not authorised).",
"<strong>Target selection</strong> — single target is auto-selected; multiple targets show a menu.",
"<strong>Storage ID</strong> — default is <code>iscsi-&lt;last IQN segment, 20 chars max&gt;</code>. Only letters, digits, <code>-</code> and <code>_</code>.",
"<strong>Content type</strong> — unlike NFS / Samba, iSCSI content is <strong>fixed to <code>images</code></strong>. iSCSI exposes raw block devices, not a filesystem, so Proxmox only lets you host VM disks on it."
],
"authTitle": "Authorise the Proxmox initiator on the target",
"authBody1": "Before the Add flow works end-to-end, the iSCSI target needs to know your Proxmox host. Get your initiator IQN:",
"authBody2": "Then add that IQN to the target's access list (in TrueNAS: <em>Sharing → Block → Initiators Groups</em>; in Synology: <em>SAN Manager → iSCSI → Target → Edit → Initiators</em>; etc.). If the initiator is not authorised, <code>iscsiadm</code> discovery returns an empty list or an authentication error."
},
"manual": {
"heading": "Manual equivalent",
"body": "The whole flow maps to these commands:"
},
"view": {
"heading": "View configured iSCSI storages",
"body": "Lists every iSCSI entry in Proxmox (<code>pvesm status | awk ''$2 == \"iscsi\"''</code>) with portal, target IQN, content type and live status."
},
"remove": {
"heading": "Remove iSCSI storage",
"body": "Runs <code>pvesm remove &lt;storage-id&gt;</code> after confirming portal, target and content. Only the Proxmox registration is removed — <strong>the iSCSI target itself is not touched</strong> and existing sessions on the kernel side may linger until the next reboot.",
"warnTitle": "Existing VM disks on this iSCSI first",
"warnBody": "Removing an iSCSI storage while VMs still have disks on it leaves those VMs pointing at a disappeared store. Proxmox will flag the error, but the LUN data is untouched on the target — you can re-register the storage later to get the disks back. Still, move or back up the VMs first to be safe."
},
"test": {
"heading": "Test iSCSI connectivity",
"body": "Runs a diagnostic pass: checks that <code>iscsiadm</code> is installed, prints your initiator IQN, confirms <code>iscsid</code> is running, pings each registered portal, probes its port, and reports <code>pvesm status</code> plus whether an iSCSI session is currently active (<code>iscsiadm --mode session</code>). Active session plus reachable portal but \"inactive\" in Proxmox usually means a stale state — try <code>pvesm set &lt;id&gt; --disable 0</code>."
},
"troubleshoot": {
"heading": "Troubleshooting",
"portalTitle": "\"Cannot reach portal\" but the server IP responds elsewhere",
"portalBody": "Ping failed on the portal address. Check you are reaching the <em>storage network</em> interface (iSCSI often lives on a separate VLAN / subnet from the management network). Also verify DNS if you typed a hostname.",
"discoverTitle": "\"iSCSI discovery failed\" from iscsiadm",
"discoverIntro": "The script shows the exact error. Most common causes:",
"discoverItems": [
"Portal IP / port wrong (double-check, default is 3260).",
"iSCSI service not running on the target server.",
"Firewall blocks 3260 between Proxmox and the target.",
"<strong>Initiator IQN is not authorised on the target.</strong> Most frequent cause on enterprise arrays. Add your Proxmox IQN to the target's initiator ACL first."
],
"noTargetTitle": "No targets found but discovery succeeded",
"noTargetBody": "The server accepted your initiator but does not expose any target to it. Review the target's authentication / access controls — some arrays allow discovery for all IQNs but filter which targets each IQN can see.",
"noLunTitle": "LUNs do not appear in /dev/disk/by-path after registering",
"noLunBody": "<code>pvesm add iscsi</code> succeeded but the kernel is not seeing block devices. Check <code>iscsiadm --mode session</code> — if no session is active, start one manually with <code>iscsiadm --mode node --login</code>. If a session exists but no LUNs appear, force a rescan: <code>iscsiadm --mode session --rescan</code>. If still nothing, the target probably has no LUNs assigned to this IQN yet (configure LUN mapping on the target).",
"chapTitle": "CHAP authentication",
"chapBody": "ProxMenux does not expose the CHAP username / password fields in the interactive flow. If your target requires CHAP, register with ProxMenux first (discovery with CHAP may fail, but <code>pvesm add</code> will still write the entry), then add credentials manually: <code>pvesm set &lt;id&gt; --username &lt;chap-user&gt;</code> and edit <code>/etc/iscsi/iscsid.conf</code> with the password, then <code>systemctl restart iscsid</code>. This is a gap in the current script — documented here so you know what to do."
},
"related": {
"heading": "Related",
"items": [
{
"href": "/docs/storage-share/host-nfs",
"label": "NFS share as Proxmox storage",
"tail": " — file-level alternative. Simpler to set up, more flexible (backup / ISO / tmpl / images), slightly slower for live VM disks."
},
{
"href": "/docs/storage-share/host-samba",
"label": "Samba / CIFS as Proxmox storage",
"tail": " — another file-level option; avoid for live VM disks due to locking semantics."
},
{
"href": "/docs/storage-share/host-local-disk",
"label": "Add local disk as Proxmox storage",
"tail": " — when the disk is local to the Proxmox host, not on another box over the network."
}
]
}
}

186
web/messages/en/docs/storage-share/host-local-disk.json Normal file
View File

@@ -0,0 +1,186 @@
{
"meta": {
"title": "Host: Add local disk as Proxmox storage | ProxMenux Documentation",
"description": "Format a local SATA / SAS / NVMe disk on a Proxmox host and register it as Proxmox directory or ZFS pool storage. Safe disk detection, destructive-op confirmation gate, UUID-based fstab, ZFS pool creation and pvesm add dir / zfspool under the hood.",
"ogTitle": "Host: Add local disk as Proxmox storage | ProxMenux Documentation",
"ogDescription": "Format a local disk and register it as Proxmox directory or ZFS pool storage with a guided, safety-filtered flow."
},
"header": {
"title": "Host: Add local disk as Proxmox storage",
"description": "Take a physical disk on the Proxmox host, optionally format it (ext4 / xfs / btrfs / zfs) and register it as Proxmox storage — either as a directory (pvesm add dir) or a ZFS pool (pvesm add zfspool). ProxMenux filters the disk list so you cannot pick the root disk or anything in use, and makes every destructive step explicit before running it.",
"section": "Storage & Share · Host"
},
"intro": {
"title": "What this does",
"body": "Other <em>Host</em> tools in this section deal with <strong>network</strong> storage (NFS / Samba / iSCSI). This one deals with <strong>local</strong> disks — spare drives physically attached to your Proxmox host that you want to use for VM disks, backups, ISOs or templates. ProxMenux prepares the disk (partition + format + mount) and registers it in Proxmox so the UI can place content there."
},
"destructive": {
"title": "Destructive tool for the 'format' path",
"body": "The <em>Format</em> path <strong>erases every partition and byte on the selected disk</strong>. ProxMenux shows the disk list with a warning banner, filters out disks already in use, and requires an explicit confirmation before any <code>wipefs</code> / <code>sgdisk</code> / <code>mkfs</code> runs. Still — read the device path aloud twice before typing \"yes\"."
},
"compare": {
"heading": "Directory vs ZFS pool — which to pick",
"headerDir": "Directory (ext4 / xfs / btrfs)",
"headerZfs": "ZFS pool",
"rows": [
{
"label": "Proxmox storage type",
"dirRich": "<code>dir</code>",
"zfsRich": "<code>zfspool</code>"
},
{
"label": "VM disk format",
"dir": "qcow2 / raw file on a filesystem",
"zfs": "Native ZFS dataset (zvol) per disk"
},
{
"label": "Snapshots",
"dir": "qcow2 snapshots; btrfs snapshots if fs=btrfs",
"zfs": "Native, instant, copy-on-write"
},
{
"label": "Thin provisioning",
"dir": "Yes (qcow2 default)",
"zfs": "Yes (ZFS default)"
},
{
"label": "RAM needs",
"dir": "Low",
"zfs": "High — ZFS uses free RAM as ARC cache"
},
{
"label": "Supports content types",
"dir": "images, backup, iso, vztmpl, snippets, rootdir",
"zfs": "images, rootdir only (block storage)"
},
{
"label": "Best for",
"dir": "General-purpose disk: mix of VM disks, backups, ISOs",
"zfs": "Pure VM / LXC data disk with snapshot + integrity needs"
}
]
},
"opening": {
"heading": "Opening the tool",
"body": "From ProxMenux's main menu, open <strong>Storage &amp; Share Manager → Add Local Disk as Proxmox Storage</strong>. You will see this sub-menu with four options:",
"imageAlt": "Local Disk Manager menu — Add / View / Remove / List available disks"
},
"howRuns": {
"heading": "How the script runs (Add flow)",
"body": "The flow has two phases with a triple-gate safety filter. Phase 1 discovers safe disks, decides what to do with the chosen one and collects storage parameters; Phase 2 does the destructive work. Until the final confirmation the disk is untouched."
},
"format": {
"heading": "Format a blank disk",
"intro": "The path for a fresh disk or one whose contents you do not care about.",
"items": [
"Pick the disk (system / in-use disks are hidden).",
"Pick \"Format disk (ERASE all data)\".",
"Pick the filesystem — see the table above for trade-offs.",
"Storage ID (default <code>disk-&lt;device&gt;</code>), mount path, content-type preset.",
"Confirm at the <strong>FINAL CONFIRMATION — DATA WILL BE ERASED</strong> dialog.",
"ProxMenux wipes the partition table, creates one partition spanning the whole disk, runs <code>mkfs.&lt;fs&gt;</code> (or <code>zpool create</code>), mounts it, adds it to <code>/etc/fstab</code> by UUID with <code>defaults,nofail</code>, and registers it in Proxmox via <code>pvesm add dir</code> or <code>pvesm add zfspool</code>."
],
"tipTitle": "Why UUID + nofail in /etc/fstab",
"tipBody": "The script writes <code>UUID=… /mnt/&lt;id&gt; &lt;fs&gt; defaults,nofail 0 2</code>. UUID survives device reordering across reboots (so <code>/dev/sdc</code> becoming <code>/dev/sdd</code> does not break boot). <code>nofail</code> means that if the disk ever disappears (hardware failure, unplugged), Proxmox still boots — storage will just show as inactive until the disk comes back."
},
"reuse": {
"heading": "Reuse an existing filesystem",
"intro": "The path for a disk you want to keep the data on — maybe you moved it from another Proxmox host, or the disk already has backups / ISOs you want to keep accessible.",
"items": [
"Pick the disk.",
"Pick \"Use existing filesystem\".",
"Storage ID, mount path, content-type preset.",
"ProxMenux does <strong>not</strong> touch the data: it creates the mount point, mounts the disk, adds a UUID entry to <code>/etc/fstab</code>, and registers it as a Proxmox <code>dir</code> storage."
],
"warnTitle": "Reuse path does not handle ZFS pools",
"warnBody": "If the disk already contains a ZFS pool, the <em>reuse</em> path here just tries to mount it as a regular filesystem — which fails. To import an existing ZFS pool use <code>zpool import &lt;name&gt;</code> on the command line and then register it manually with <code>pvesm add zfspool</code>."
},
"presets": {
"heading": "Content-type presets",
"intro": "Instead of a long checklist, ProxMenux offers 4 presets plus a custom option. The preset string is passed to <code>pvesm add … --content &lt;csv&gt;</code>:",
"headerPreset": "Preset",
"headerContent": "Content string",
"headerUse": "Use case",
"rows": [
{
"preset": "VM Storage",
"content": "images,backup",
"use": "A dedicated VM disk store that also keeps backups of those VMs nearby."
},
{
"preset": "Standard NAS",
"content": "backup,iso,vztmpl",
"use": "An archive / media disk — backups, ISOs and LXC templates. No live VM disks here."
},
{
"preset": "All types",
"content": "images,backup,iso,vztmpl,snippets",
"use": "\"Let the host decide\" — allows every content type Proxmox supports on this storage."
},
{
"preset": "Custom",
"content": "(free input)",
"useRich": "Type the exact CSV yourself, e.g. <code>images</code> alone, or <code>rootdir,images</code>."
}
],
"zfsTitle": "ZFS pool content is narrower",
"zfsBody": "If you picked <strong>zfs</strong> as the filesystem, Proxmox only accepts <code>images</code> and <code>rootdir</code> as content types on a <code>zfspool</code> (it is block storage, not a filesystem for ISOs). The presets above will still work but Proxmox silently drops the content types it cannot use — check <code>pvesm status</code> afterwards."
},
"manual": {
"heading": "Manual equivalent",
"extIntro": "Format + register a disk as ext4 directory storage:",
"zfsIntro": "Or as a ZFS pool:"
},
"view": {
"heading": "View disk storages",
"body": "Lists every disk-backed Proxmox storage (both <code>dir</code> and <code>zfspool</code> that are user-created — system pools like <code>rpool</code> are hidden). Shows the mount path / pool name, content types and live status."
},
"remove": {
"heading": "Remove disk storage",
"body": "Unregisters the storage from Proxmox (<code>pvesm remove</code>) and offers to clean up the matching entry in <code>/etc/fstab</code>. For ZFS pools the script does <strong>not</strong> automatically destroy the pool — that is a separate <code>zpool destroy &lt;name&gt;</code> step you do by hand when you are sure.",
"warnTitle": "Data and existing VM dependencies",
"warnBody": "Removing the storage does not touch the filesystem or the pool — the data stays on the disk. But VMs / CTs that reference this storage by ID will fail to start after removal. Move those VM disks to another storage (or take a backup) before removing."
},
"list": {
"heading": "List available disks",
"body": "A read-only diagnostic view: prints the output of <code>lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINT,MODEL</code> followed by the <code>dir</code> / <code>zfspool</code> storages Proxmox already knows about. Good first stop when you open the tool and want to see \"what is on this host?\" before adding anything."
},
"troubleshoot": {
"heading": "Troubleshooting",
"noDisksTitle": "\"No available disks found\"",
"noDisksIntro": "The safety filter hid every disk. Common reasons:",
"noDisksItems": [
"Only the root disk is present.",
"Every other disk is part of an active ZFS / LVM / RAID array.",
"Every other disk is referenced by a VM or LXC config (passthrough).",
"The disk is in read-only mode (failing hardware or write-blocker)."
],
"noDisksOutro": "Use <em>List Available Disks</em> from the menu to see the raw <code>lsblk</code> output and understand what's happening.",
"mountedTitle": "Format fails with \"device is mounted\"",
"mountedBody": "Something auto-mounted the disk (udisksd, a desktop manager, a lingering systemd unit). Unmount it: <code>umount /dev/sdX?*</code> or <code>systemctl stop &lt;whatever-mounts-it&gt;</code>, then retry. The script's safety filter should have hidden mounted disks, so if you reached this error the mount happened between the menu showing and you confirming.",
"zpoolTitle": "zpool create fails \"invalid vdev specification\"",
"zpoolBody": "Usually means the disk still has stale GPT / LVM / ZFS signatures that <code>zpool</code> refuses to overwrite without force. The script runs <code>wipefs</code> and <code>sgdisk --zap-all</code> before format, but a very stubborn disk may still have a stale label. Force a clean wipe manually: <code>zpool labelclear -f /dev/sdX</code> or <code>dd if=/dev/zero of=/dev/sdX bs=1M count=10</code> and retry.",
"inactiveTitle": "Storage shows as inactive after reboot",
"inactiveBody": "Check <code>findmnt &lt;mount-path&gt;</code> — if the mount is missing, something in <code>/etc/fstab</code> failed. <code>dmesg | tail</code> usually points at the reason (UUID mismatch, filesystem corruption, <code>nofail</code> dropped the retry). A <code>mount -a</code> usually reactivates the storage once the cause is fixed."
},
"related": {
"heading": "Related",
"items": [
{
"href": "/docs/disk-manager/format-disk",
"label": "Disk Manager: Format / Wipe Physical Disk",
"tail": " — low-level alternative when you just want to prepare a disk without registering it as Proxmox storage."
},
{
"href": "/docs/storage-share/host-iscsi",
"label": "Add iSCSI target as Proxmox storage",
"tail": " — network equivalent when the block device lives on another box."
},
{
"href": "/docs/storage-share/host-local-shared",
"label": "Add Shared Directory on Host",
"tail": " — prepare a directory on the host for LXC bind mounts (does not register a Proxmox storage)."
}
]
}
}

103
web/messages/en/docs/storage-share/host-local-shared.json Normal file
View File

@@ -0,0 +1,103 @@
{
"meta": {
"title": "Host: Add shared directory on Host | ProxMenux Documentation",
"description": "Create a host directory ready for LXC bind mounts, with permissions that work for privileged and unprivileged containers at once. Sticky bit + world-rwx + ACLs for default inheritance.",
"ogTitle": "Host: Add shared directory on Host | ProxMenux Documentation",
"ogDescription": "Prepare a host directory for LXC bind mounts with permissions compatible with privileged and unprivileged CTs."
},
"header": {
"title": "Host: Add shared directory on Host",
"description": "Create a host directory designed to be bind-mounted into one or more LXC containers. ProxMenux applies a set of permissions that works for both privileged and unprivileged CTs at once — no shifted UID headache, no per-container chowns — and registers the directory so the LXC Mount Manager can pick it up later.",
"section": "Storage & Share · Host"
},
"intro": {
"title": "What this is (and is NOT)",
"body": "This tool does <strong>not</strong> register anything in Proxmox (no <code>pvesm add</code> here). It just prepares a directory on the host — <code>/mnt/shared</code>, by default — with permissions that any LXC container can read and write, regardless of whether the CT is privileged or unprivileged. The usual next step is to bind-mount it into each CT with the <mountLink>LXC Mount Manager</mountLink>."
},
"why": {
"heading": "Why a dedicated tool for this",
"intro": "When you bind-mount a host directory into an LXC container, permissions depend on:",
"items": [
"Whether the CT is <strong>privileged</strong> (UID 0 in CT = UID 0 on host) or <strong>unprivileged</strong> (UID 0 in CT = UID 100000 on host — everything is shifted by +100000).",
"The ownership of the host directory (a file owned by UID 1000 on the host appears as \"others\" from the perspective of an unprivileged CT, because no CT user maps to host UID 1000).",
"Whether multiple CTs share the same directory (different CTs may have different UID ranges)."
],
"outro": "The pragmatic trick ProxMenux uses here is to <strong>give everybody access</strong> at the filesystem level: world-rwx plus the sticky bit, plus ACLs so new files inherit the same permissions. Any mapped UID can read and write; no UID / GID alignment is required."
},
"howRuns": {
"heading": "How the script runs",
"body": "The script has no main menu — it runs a single action, <strong>Create shared directory</strong>. Phase 1 collects the target path; Phase 2 creates the directory and applies permissions."
},
"bits": {
"heading": "What each permission bit does",
"intro": "The number <strong>1777</strong> is not arbitrary — it's the same mode Linux uses for <code>/tmp</code>. Three properties combined:",
"headerBit": "Bit",
"headerEffect": "Effect",
"headerWhy": "Why it matters here",
"rows": [
{
"bit": "1 (sticky)",
"effect": "Only the file owner can delete / rename a file.",
"why": "Prevents CT-A from deleting files created by CT-B in the same directory."
},
{
"bit": "777 (rwx-rwx-rwx)",
"effect": "Everyone can read, write and traverse.",
"why": "Unprivileged CT UIDs (100000+) appear as \"others\" from the host, so world-rwx gives them access."
},
{
"bit": "ACLs (default)",
"effect": "Inherited on every newly created file / subdir.",
"why": "The permissions apply forever — new content keeps the open profile without re-running the script."
}
],
"privTitle": "Privileged CTs see the same thing, just without the shift",
"privBody": "For a privileged CT, UID 0 in the CT is UID 0 on the host, so <code>root</code> inside the CT can read / write the host directory directly. <code>1777</code> is still fine — it just means non-root users inside the CT can also use the directory. The same permissions cover both cases."
},
"where": {
"heading": "Where to put the shared directory",
"intro": "The location picker offers four options:",
"opt1Title": "1. Create new folder in /mnt",
"opt1Body": "The usual choice. ProxMenux auto-suggests the first free name (<code>shared</code>, <code>shared2</code>, <code>shared3</code>, …). You just confirm or type a different name.",
"opt2Title": "2. Enter custom path",
"opt2Body": "For directories outside <code>/mnt</code>. Any absolute path works (e.g. <code>/srv/media</code>, <code>/data/family</code>). The script applies the same permissions.",
"opt3Title": "3. View existing folders in /mnt",
"opt3Body": "Read-only diagnostic: lists every directory under <code>/mnt</code> with its permissions, owner and available space. Useful before creating a new one to avoid name collisions.",
"opt4Title": "4. Cancel",
"opt4Body": "Exits without creating anything. Same as pressing <kbd>Esc</kbd>.",
"tipTitle": "Where does /mnt live?",
"tipBody": "By default <code>/mnt</code> sits on the Proxmox root filesystem. If you want the shared directory on a different disk (a data disk, a ZFS pool), mount that disk under <code>/mnt/&lt;name&gt;</code> first (Disk Manager or <diskLink>Add local disk as Proxmox storage</diskLink>), and then create the shared directory as a subfolder inside it — or pick \"Enter custom path\" here and point to the mounted disk."
},
"manual": {
"heading": "Manual equivalent",
"body": "The whole flow can be replayed by hand:"
},
"next": {
"heading": "Next step: bind-mount into containers",
"body": "Creating the directory only prepares it — no container sees it yet. To make it visible inside one or more LXCs, use the <mountLink>LXC Mount Manager</mountLink> to bind-mount <code>/mnt/&lt;name&gt;</code> into the CTs. Because the permissions are already open, the Mount Manager will <strong>not</strong> offer to change them — the directory is ready to use as-is."
},
"troubleshoot": {
"heading": "Troubleshooting",
"mkdirTitle": "\"Failed to create directory\"",
"mkdirBody": "Usually a filesystem issue: <code>/mnt</code> is on a read-only filesystem, the path contains a component that is not a directory (e.g. you typed <code>/etc/passwd/sub</code>), or disk is full. Check with <code>df -h /mnt</code> and <code>mount | grep /mnt</code>.",
"writeTitle": "Container cannot write despite open permissions",
"writeBody": "Double-check the CT is actually using the bind mount (<code>pct config &lt;ctid&gt; | grep ^mp</code>). Inside the CT, run <code>touch /mnt/data/test-$(date +%s)</code> — if this fails with permission denied, the mount may be on a host filesystem that does not honour ACLs (some older <code>ext3</code> or <code>vfat</code> mounts). Move the shared directory to an ext4 / xfs / btrfs / zfs backing.",
"aclTitle": "ACL commands silently unavailable",
"aclBody": "On a minimal Proxmox install <code>setfacl</code> / <code>getfacl</code> may not be installed. The script falls back gracefully (<code>command -v setfacl</code> check) and applies POSIX permissions only — which is often enough, but new files will not automatically inherit the permissive profile. Install <code>acl</code> with <code>apt-get install -y acl</code> and re-run the script on the directory."
},
"related": {
"heading": "Related",
"items": [
{
"href": "/docs/storage-share/lxc-mount-points",
"label": "LXC Mount Manager",
"tail": " — the natural next step: bind-mount this directory into one or more containers."
},
{
"href": "/docs/storage-share/host-local-disk",
"label": "Add local disk as Proxmox storage",
"tailRich": " — if you want the shared directory on a dedicated disk, prepare the disk first, mount it under <code>/mnt</code>, then create the shared subfolder here."
}
]
}
}

174
web/messages/en/docs/storage-share/host-nfs.json Normal file
View File

@@ -0,0 +1,174 @@
{
"meta": {
"title": "Host: Mount NFS share on Host | ProxMenux Documentation",
"description": "Mount an external NFS export on the Proxmox host — either as Proxmox storage (pvesm add nfs), as a plain host fstab mount (NOT visible in Datacenter > Storage), or both. The fstab method is ideal for bind-mounting the share into LXC containers without exposing it as a Proxmox storage.",
"ogTitle": "Host: Mount NFS share on Host | ProxMenux Documentation",
"ogDescription": "Mount an external NFS export on the Proxmox host via pvesm, fstab, or both. fstab path is ideal for LXC bind-mounts."
},
"header": {
"title": "Host: Mount NFS share on Host",
"description": "Mount an external NFS export (from a NAS, another server, a homelab share…) 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 (useful for bind-mounting the share into LXC containers without exposing it as a Proxmox storage).",
"section": "Storage & Share · Host"
},
"intro": {
"title": "What this does",
"body": "ProxMenux offers two mount methods for any NFS export: <strong>(1) Proxmox storage</strong> via <code>pvesm add nfs</code> — the share shows up in Datacenter > Storage and Proxmox manages the mount at <code>/mnt/pve/&lt;id&gt;</code>; <strong>(2) Host fstab mount</strong> at a path you pick — persistent via <code>/etc/fstab</code>, NOT visible as Proxmox storage, ideal for bind-mounting to LXC containers (Proxmox UI stays clean). You can run one method, the other, or both."
},
"opening": {
"heading": "Opening the tool",
"body": "From ProxMenux's main menu, open <strong>Storage &amp; Share Manager → Mount NFS Share on Host</strong>. You will see this sub-menu with four options:",
"imageAlt": "NFS Host Manager menu — Mount / View / Remove / Test connectivity"
},
"howRuns": {
"heading": "How the script runs",
"body": "The flow has two phases with clear separation between \"discovering, validating and choosing\" and \"actually mounting / writing config\". After selecting an export, you pick mount method(s) via a checklist; the rest of the dialogs only ask for params for the methods you selected. 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 and validating the export, 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.",
"imageAlt": "Mount method checklist with pvesm and fstab options",
"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": "VM disk images, backups, ISOs, LXC templates — anything that needs to appear in the Proxmox UI."
},
{
"method": "<strong>Host fstab only</strong>",
"mountRich": "<code>/mnt/&lt;path&gt;</code> (you pick the path)",
"ui": "No",
"useCaseRich": "Bind-mounting the share into one or more LXCs <em>without</em> exposing it as a Proxmox storage. Keeps the Datacenter UI clean."
},
{
"method": "<strong>Both</strong>",
"mount": "Both paths above (two independent NFS connections to the server)",
"ui": "Yes",
"useCase": "You want UI integration AND a stable host-side path with open permissions for LXC bind-mounts. Server sees two connections from the host."
}
],
"bothTitle": "\"Both\" creates two independent NFS mounts",
"bothBody": "Marking both options runs each method independently — pvesm mounts at <code>/mnt/pve/&lt;id&gt;</code>, fstab mounts at <code>/mnt/&lt;path&gt;</code>. The server sees two TCP connections from the Proxmox host. This is intentional: it lets you keep the pvesm storage clean (default Proxmox options) while having a separate host-side mount with open permissions for LXC bind-mounts."
},
"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> — what Proxmox will call this storage. Default is <code>nfs-&lt;server-ip-with-dashes&gt;</code>. Only letters, digits, <code>-</code> and <code>_</code> are accepted.",
"<strong>Content types</strong> — Proxmox ties content categories to storage volumes; pick what this NFS is allowed to hold:"
],
"headerType": "Content type",
"headerAllows": "What it allows",
"rows": [
{
"type": "import",
"allowsRich": "Disk image imports (selected by default). Needed for <em>Import Disk Image to VM</em>."
},
{
"type": "backup",
"allowsRich": "VM and CT backup files (<code>vzdump</code>)."
},
{
"type": "iso",
"allows": "Installation ISO images."
},
{
"type": "vztmpl",
"allows": "LXC templates."
},
{
"type": "images",
"allows": "Live VM disk images (this turns the NFS into a VM disk store)."
},
{
"type": "rootdir",
"allows": "LXC root filesystems (rare for NFS — read the note below)."
},
{
"type": "snippets",
"allows": "Hook scripts and cloud-init snippets."
}
],
"warnTitle": "images and rootdir on NFS",
"warnBody": "Marking <code>images</code> on an NFS storage lets Proxmox place live VM disks there. It works, but NFS latency + its lock semantics make this noticeably slower than local storage (and a network outage pauses every VM backed by that store). Marking <code>rootdir</code> means you will host LXC root filesystems over NFS, which historically has trouble with unprivileged containers (overlay / chown interactions). Prefer keeping <code>images</code> / <code>rootdir</code> on local or iSCSI storage and using NFS for <code>backup</code> / <code>iso</code> / <code>vztmpl</code>.",
"result": "The result is <code>pvesm add nfs &lt;id&gt; --server &lt;srv&gt; --export &lt;path&gt; --content &lt;csv&gt;</code> and Proxmox auto-mounts at <code>/mnt/pve/&lt;id&gt;</code>."
},
"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, then mounts and writes the entry to <code>/etc/fstab</code>:",
"items": [
"<strong>Host mount path</strong> — default <code>/mnt/&lt;export-basename&gt;</code>. Must be an absolute path. If something is already mounted there, or a fstab entry exists for the same path, ProxMenux warns you and offers to replace it.",
"<strong>Mount options</strong> — pick <em>Read/Write</em> (default with <code>rw,hard,nofail,_netdev,rsize=131072,wsize=131072,timeo=600,retrans=2</code>), <em>Read-only</em>, or <em>Custom</em> (type your own option string)."
],
"appliesIntro": "Once you confirm, the script:",
"applies": [
"<code>mkdir -p</code> the mount path.",
"<code>mount -t nfs -o &lt;opts&gt; &lt;srv&gt;:&lt;export&gt; &lt;path&gt;</code>.",
"Writes a one-line entry to <code>/etc/fstab</code>: <code>&lt;srv&gt;:&lt;export&gt; &lt;path&gt; nfs &lt;opts&gt; 0 0</code>.",
"Runs <code>systemctl daemon-reload</code> so systemd picks up the new fstab entry.",
"Attempts <code>chmod 1777</code> + <code>setfacl o::rwx</code> on the mount point (silent best-effort — only succeeds if the NFS server allows it; many NAS exports already serve world-writable paths)."
],
"lxcTitle": "Using the fstab mount from an LXC",
"lxcBody": "The script prints the exact <code>pct set</code> command at the end to bind-mount the path into a container, e.g. <code>pct set &lt;ctid&gt; -mp0 /mnt/&lt;path&gt;,mp=/mnt/&lt;ct-path&gt;,shared=1,backup=0</code>. Or use the <mountLink>LXC Mount Manager</mountLink>, which detects the fstab mount automatically. <strong>No changes are made inside the container</strong> — for unprivileged LXCs to read/write the NFS data, the script relies on server-side world-writable export semantics (typical for Synology, TrueNAS, OMV defaults). If your NFS server squashes root or restricts perms, see Troubleshooting.",
"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:",
"fstabIntro": "Method B (fstab) maps to:"
},
"view": {
"heading": "View configured NFS storages",
"body": "Lists every NFS entry in Proxmox (<code>pvesm status | awk ''$2 == \"nfs\"''</code>) with server, export, content types, mount path and live status. <strong>Note:</strong> this view only shows pvesm-registered storages — fstab-only mounts are not listed here. Check those with <code>findmnt -t nfs</code> or <code>grep nfs /etc/fstab</code>."
},
"remove": {
"heading": "Remove NFS storage",
"body": "Runs <code>pvesm remove &lt;storage-id&gt;</code> after a confirmation that shows the server / export / content. Only the Proxmox-side registration is removed — <strong>the remote NFS server itself is never touched</strong>, no files are deleted. To remove a fstab-only mount, edit <code>/etc/fstab</code> by hand and run <code>umount &lt;path&gt;</code>.",
"warnTitle": "Back up dependencies first",
"warnBody": "If VMs, CTs or backup jobs still reference this storage (by ID), removing it leaves them pointing at a disappeared store. Proxmox will flag the error but not clean up. Move or drop those references first, then remove the storage."
},
"test": {
"heading": "Test NFS connectivity",
"body": "Runs a diagnostic pass over every NFS storage registered in Proxmox: checks that <code>showmount</code> is available, that <code>rpcbind</code> is running, pings each server, probes port 2049, calls <code>showmount -e</code>, and finally reports Proxmox's own view (<code>pvesm status</code>). Good first stop when a storage shows as <em>inactive</em> in the Proxmox UI."
},
"troubleshoot": {
"heading": "Troubleshooting",
"noServersTitle": "\"No NFS servers found on the network\"",
"noServersBody": "Auto-discover uses <code>nmap -p 2049 --open &lt;subnet&gt;/24</code>. The server may not respond if: it is on a different VLAN / subnet, its firewall blocks nmap probes (many do) or port 2049 is intentionally closed on that interface. Use the <em>Manual</em> option with the server's IP or hostname instead.",
"portTitle": "\"NFS port (2049) is not accessible\"",
"portBody": "Ping succeeded but <code>nc -z -w 3 &lt;server&gt; 2049</code> failed. Check the NFS service is running on the server (<code>systemctl status nfs-server</code> on Linux, Control Panel → File Services on Synology, NFS plugin on OMV / TrueNAS), and that the firewall allows 2049 from the Proxmox host.",
"showmountTitle": "\"Failed to connect\" from showmount",
"showmountBody": "The server refused the export-list query. Common causes: the server enforces strict client ACLs (your Proxmox IP is not on the allowed list), <code>rpcbind</code> is not running on the server, or the server exposes only NFSv4 with <code>showmount</code> disabled. The export path can still be added manually if you know it.",
"inactiveTitle": "Storage shows as inactive in the Proxmox UI",
"inactiveBody": "Run <em>Test NFS Connectivity</em> first — 99 % of the time this flags the exact hop that breaks (DNS, port, mount permissions). If connectivity is fine but Proxmox still flags inactive, check <code>journalctl -u pvestatd</code> on the Proxmox node; intermittent DNS or slow NFS mounts on boot can leave storages in an inactive state until <code>pvesm set &lt;id&gt; --disable 0</code> is re-applied.",
"lxcNoWriteTitle": "fstab mount works but unprivileged LXC can't write through a bind-mount",
"lxcNoWriteBody": "NFS permissions are enforced server-side, not by the host. The fstab options (<code>uid=</code>, <code>file_mode=</code>) that work for CIFS do <strong>not</strong> apply to NFS. If your unprivileged LXC (root inside CT = UID 100000 on host, mapped to NFS as \"others\") cannot write, the NFS server is either squashing root or has restrictive perms. Fix on the server: change the export to <code>no_root_squash</code> if you trust the host, or set the export world-writable (Synology, TrueNAS, OMV all expose this in the UI). The script tries <code>chmod 1777</code> on the mount but that only succeeds when the server permits it.",
"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>, and verify the entry is valid with <code>mount -fav | grep nfs</code>. <code>mount -a</code> after boot mounts everything that is currently missing."
},
"related": {
"heading": "Related",
"items": [
{
"href": "/docs/storage-share/host-samba",
"label": "Samba / CIFS as Proxmox storage",
"tail": " — same flow pattern (Method A pvesm + Method B fstab) for SMB/CIFS shares."
},
{
"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-nfs-client",
"label": "NFS client in LXC",
"tail": " — alternative: mount NFS directly from inside a privileged container (skips the host)."
}
]
}
}

172
web/messages/en/docs/storage-share/host-samba.json Normal file
View File

@@ -0,0 +1,172 @@
{
"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 any Samba share: <strong>(1) Proxmox storage</strong> via <code>pvesm add cifs</code> — visible in Datacenter > Storage, mounted at <code>/mnt/pve/&lt;id&gt;</code>, credentials stored encrypted in <code>/etc/pve/priv/storage/&lt;id&gt;.pw</code>; <strong>(2) Host fstab mount</strong> at a path you pick — persistent via <code>/etc/fstab</code>, mounted with <code>uid=0,gid=0,file_mode=0777,dir_mode=0777</code> so unprivileged LXC bind-mounts can write, credentials stored in a root-only <code>/etc/samba/credentials/</code> file (password never in <code>fstab</code>). You can run one method, the other, or both."
},
"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-mounting the share into one or more LXCs <em>without</em> exposing it as a Proxmox storage. Open perms guarantee unprivileged CTs can write through the bind-mount."
},
{
"method": "<strong>Both</strong>",
"mount": "Both paths above (two independent CIFS connections to the server)",
"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 independent CIFS connections",
"bothBody": "pvesm and fstab mount the same share twice with different options. The pvesm mount at <code>/mnt/pve/&lt;id&gt;</code> uses Proxmox defaults (no open uid/gid) — Proxmox UI is happy. The fstab mount at <code>/mnt/&lt;path&gt;</code> uses <code>uid=0,gid=0,file_mode=0777,dir_mode=0777</code> — unprivileged LXC bind-mounts to it can write. Two TCP connections to the SMB server from the same Proxmox host."
},
"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> — CIFS exposes <strong>6</strong> options (same as NFS minus <code>rootdir</code>, which Proxmox does not allow on CIFS because the locking semantics cannot hold a live LXC rootfs):"
],
"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": "If you tick <code>images</code>, ProxMenux pops up a warning before continuing. CIFS uses an advisory locking model that interacts badly with KVM disk operations (snapshots, live migration, I/O under contention). A backup or ISO store on CIFS is perfectly fine; a live-disk store is asking for trouble. Use NFS (or local storage) for <code>images</code> when you can.",
"credsTitle": "Where pvesm stores credentials",
"credsBody": "When you use User authentication, the password is NOT written in <code>/etc/pve/storage.cfg</code>. Proxmox keeps it in <code>/etc/pve/priv/storage/&lt;storage-id&gt;.pw</code> — mode <code>0600</code>, owner <code>root</code>, member of the cluster sync. If you later change the password on the Samba server, 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> — pick <em>Read/Write</em> (default with <code>rw,uid=0,gid=0,file_mode=0777,dir_mode=0777,iocharset=utf8,nofail,_netdev</code>), <em>Read-only</em> (read-only variant with <code>file_mode=0555,dir_mode=0555</code>), or <em>Custom</em> (type your own option string). Open uid/gid/file_mode are always recommended for LXC bind-mount writes."
],
"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": "Because the CIFS client applies <code>uid=0,gid=0,file_mode=0777,dir_mode=0777</code>, every file in the mount is owned by host UID 0 with mode 0777. An unprivileged LXC bind-mounting the path sees \"others\" perms on every entry (CT root = host UID 100000 = others on the host filesystem), so reads and writes succeed. <strong>No changes are made inside the container</strong> — no <code>chown</code> in the CT, no group setup, nothing modified in <code>/etc/lxc</code> beyond the single <code>mp</code> bind-mount line. The script prints the exact <code>pct set</code> command at the end, or use the <mountLink>LXC Mount Manager</mountLink> to attach the path.",
"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",
"body": "Lists every CIFS entry in Proxmox (<code>pvesm status | awk ''$2 == \"cifs\"''</code>) with server, share, content types, username (or <em>Guest</em>), mount path and live status. Password is <strong>never printed</strong>. <strong>Note:</strong> this view only shows pvesm-registered storages — fstab-only mounts are not listed. Check those with <code>findmnt -t cifs</code> or <code>grep cifs /etc/fstab</code>."
},
"remove": {
"heading": "Remove CIFS storage",
"body": "Runs <code>pvesm remove &lt;storage-id&gt;</code> after a confirmation that shows the server / share / content. Only the Proxmox-side registration is removed — <strong>the remote Samba server is not touched</strong>. Proxmox also deletes the paired credentials file. To remove a fstab-only mount, edit <code>/etc/fstab</code> by hand, run <code>umount &lt;path&gt;</code>, and remove the file from <code>/etc/samba/credentials/</code>.",
"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": "Confirm the mount uses the open options: <code>findmnt /mnt/&lt;path&gt;</code> should show <code>uid=0,gid=0,file_mode=0777,dir_mode=0777</code>. If a Custom option string omits those, an unprivileged LXC will get permission denied (CT UIDs map to host \"others\", which without open file_mode have no write bit). Re-mount with the default RW preset or add the four options back to your custom string.",
"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)."
}
]
}
}

135
web/messages/en/docs/storage-share/index.json Normal file
View File

@@ -0,0 +1,135 @@
{
"meta": {
"title": "Proxmox NFS, Samba, iSCSI & LXC Mount Points — Storage & Share | ProxMenux",
"description": "Integrate external and local storage into Proxmox VE and share folders between host and LXC containers. Add NFS shares, Samba (CIFS) shares and iSCSI targets as Proxmox storage, set up LXC bind mounts (Mount Manager) and run NFS / Samba clients and servers inside containers.",
"ogTitle": "Proxmox NFS, Samba, iSCSI & LXC Mount Points — Storage & Share",
"ogDescription": "Integrate external / local storage into Proxmox VE — NFS, Samba, iSCSI registration plus LXC bind mounts and network sharing.",
"twitterTitle": "Proxmox NFS, Samba, iSCSI | ProxMenux",
"twitterDescription": "Add NFS / Samba / iSCSI as Proxmox storage and share folders between host and LXC."
},
"header": {
"title": "Storage & Share Manager",
"description": "Integrate external or local storage into Proxmox VE and share folders between the host and LXC containers. Three blocks of tools: Host storage integration (register storage in Proxmox itself), the LXC Mount Manager (bind mounts with pragmatic permission handling), and LXC network sharing (NFS / Samba client and server flows for specific use cases).",
"section": "Storage & Share"
},
"intro": {
"title": "What this menu is for",
"body": "The Disk Manager works at the level of <em>individual physical disks</em>. Storage &amp; Share Manager works one level up — it <strong>registers storage pools and network shares in Proxmox</strong> (so the UI and the VM creator can use them) and <strong>sets up file sharing between the host and your containers</strong>."
},
"opening": {
"heading": "Opening the menu",
"body": "From ProxMenux's main menu, select <strong>Storage &amp; Share Manager</strong>. You will see this:",
"imageAlt": "Storage & Share Manager menu with HOST and LXC blocks"
},
"groups": {
"heading": "Three tool groups",
"intro": "The menu is split into three blocks. <strong>Host storage integration</strong> registers external or local storage in Proxmox itself. The <strong>LXC Mount Manager</strong> is the primary tool for sharing folders with containers — a pragmatic bind-mount flow that handles unprivileged UID mapping on the host side. <strong>LXC network sharing</strong> covers four additional scenarios where a container needs to <em>consume</em> or <em>expose</em> NFS / Samba shares directly.",
"hostTitle": "Host storage",
"hostBody": "Register external and local storage in Proxmox via <code>pvesm add …</code>. Once registered, the storage appears in the Proxmox UI and is available to the VM and CT creators.",
"hostItems": [
"External NFS / Samba / iSCSI → Proxmox storage",
"Local disk → Proxmox directory or ZFS storage",
"Local shared directory (for cross-CT bind mounts)"
],
"lxcMountTitle": "LXC Mount Manager",
"lxcMountBody": "The primary LXC sharing tool. Bind-mounts host directories into containers via <code>pct set -mpN</code> and handles the permission quirks of unprivileged CTs without creating any group or user inside the container.",
"lxcMountItems": [
"Works with privileged and unprivileged CTs",
"Offers to set <code>o+rwx</code> on the host dir for unprivileged UIDs",
"Fixes existing CIFS / NFS mounts if needed"
],
"lxcNetTitle": "LXC network sharing",
"lxcNetBody": "Four additional flows for scenarios where a container needs to consume or expose NFS / Samba shares directly. All require a <strong>privileged</strong> container.",
"lxcNetItems": [
"NFS / Samba <strong>client</strong> (consume external shares)",
"NFS / Samba <strong>server</strong> (expose CT folders)"
]
},
"host": {
"heading": "Host storage integration",
"intro": "Register storage in Proxmox. Every option calls <code>pvesm add …</code> under the hood, so the storage shows up in <strong>Datacenter → Storage</strong> and becomes available to the VM / CT creators.",
"options": [
{
"href": "/docs/storage-share/host-nfs",
"icon": "Network",
"title": "Add NFS share as Proxmox storage",
"description": "Register an external NFS export as Proxmox storage via pvesm add nfs. Proxmox handles the mount — no fstab entries needed."
},
{
"href": "/docs/storage-share/host-samba",
"icon": "Share2",
"title": "Add Samba share as Proxmox storage",
"description": "Register an external Samba / CIFS share as Proxmox storage via pvesm add cifs. Proxmox handles the mount and credentials."
},
{
"href": "/docs/storage-share/host-iscsi",
"icon": "Database",
"title": "Add iSCSI target as Proxmox storage",
"description": "Connect to an external iSCSI target and register it as Proxmox storage (block device) for VM disk images."
},
{
"href": "/docs/storage-share/host-local-disk",
"icon": "HardDrive",
"title": "Add local disk as Proxmox storage",
"description": "Format a local SATA / SAS / NVMe disk and register it as a Proxmox directory or ZFS pool storage."
},
{
"href": "/docs/storage-share/host-local-shared",
"icon": "FolderOpen",
"title": "Add shared directory on Host",
"description": "Create a host directory meant to be bind-mounted into multiple CTs. Not a Proxmox storage — purely a host-side resource for LXC bind mounts."
}
]
},
"lxcMount": {
"heading": "LXC Mount Manager",
"intro": "The primary tool for sharing folders between the Proxmox host and LXC containers. It uses <code>pct set -mpN</code> to bind-mount a host directory into the container, and handles the permission quirks of unprivileged CTs on the host side (no groups or users are created inside the container).",
"card": {
"title": "LXC mount points (Host ↔ CT)",
"description": "Bind-mount any host directory into an LXC container via pct set -mpN. Works with both privileged and unprivileged CTs; offers chmod o+rwx / ACLs on the host dir and fixes existing CIFS / NFS mounts when needed."
}
},
"lxcNet": {
"heading": "LXC network sharing",
"intro": "Use these flows when a container needs to <em>be</em> an NFS / Samba endpoint — either consuming an external share (client) or exposing its own folders (server). For most file-sharing needs (host ↔ CT bind mounts), the <mountLink>LXC Mount Manager</mountLink> is simpler and does not require privileged containers.",
"options": [
{
"href": "/docs/storage-share/lxc-nfs-client",
"icon": "Download",
"title": "NFS client in LXC",
"description": "Mount external NFS shares from inside a privileged LXC container. Supports auto-discovery, /etc/fstab persistence and clean unmounts."
},
{
"href": "/docs/storage-share/lxc-samba-client",
"icon": "Download",
"title": "Samba client in LXC",
"description": "Mount Samba / CIFS shares from inside a privileged LXC container. Credentials stored securely, auto-discovery available."
},
{
"href": "/docs/storage-share/lxc-nfs-server",
"icon": "Upload",
"title": "NFS server in LXC",
"description": "Export folders over NFS from inside a privileged LXC container."
},
{
"href": "/docs/storage-share/lxc-samba-server",
"icon": "Upload",
"title": "Samba server in LXC",
"description": "Expose folders over SMB / CIFS from inside a privileged LXC container."
}
]
},
"privReq": {
"title": "Privileged container requirement",
"body": "The four <strong>LXC network sharing</strong> flows above require a <strong>privileged</strong> container — the kernel modules (<code>nfs-kernel-server</code>, <code>smbd</code>, <code>mount.nfs</code>, <code>mount.cifs</code>) need capabilities that unprivileged CTs do not expose. If you only need to share files between the host and an unprivileged CT, use the <mountLink>LXC Mount Manager</mountLink> instead — it bind-mounts from the host and adjusts permissions on the host side so the container can read and write without any kernel-module magic."
},
"unprivExplain": {
"title": "How ProxMenux handles unprivileged CT permissions",
"body": "Unprivileged LXC containers shift their UIDs by <strong>+100000</strong> on the host (container UID 0 = host UID 100000, container UID 1000 = host UID 101000, …). A file created by a container user therefore appears on the host as <em>others</em> — not belonging to any real host user or group. The LXC Mount Manager addresses this pragmatically: instead of trying to align UIDs / GIDs between host and CT, it offers to apply <code>chmod o+rwx</code> (plus matching ACLs) on the host directory, so any mapped UID can read and write. For CIFS it remounts with <code>uid=0,gid=0,file_mode=0777,dir_mode=0777</code>; for NFS it sets a sticky world-writable directory and, if the server squashes root, guides you to the right server-side fix."
},
"scripts": {
"heading": "Scripts involved",
"intro": "Each individual page links to the script that drives its flow. The file below is a shared helper that is not documented as its own page but is used by several of the LXC network-sharing flows:",
"itemTail": " — CT validation, mount point selection, privileged check and universal group setup helpers shared across the LXC client / server flows."
}
}

174
web/messages/en/docs/storage-share/lxc-mount-points.json Normal file
View File

@@ -0,0 +1,174 @@
{
"meta": {
"title": "LXC Mount Points (Host ↔ Container) | ProxMenux Documentation",
"description": "The LXC Mount Manager — bind-mount any host directory into one or more LXC containers via pct set -mpN. Handles permission quirks of unprivileged containers, fixes existing CIFS / NFS mounts on the host side, and never modifies anything inside the container.",
"ogTitle": "LXC Mount Points (Host ↔ Container) | ProxMenux Documentation",
"ogDescription": "Bind-mount host directories into LXC containers. Handles unprivileged UID mapping pragmatically, fixes CIFS / NFS access on the host side."
},
"header": {
"title": "LXC Mount Points (Host ↔ Container)",
"description": "The primary tool for sharing folders between the Proxmox host and LXC containers. Bind-mounts any host directory into one or more containers using Proxmox's native pct set -mpN syntax. The smart bit: it solves the permission headaches of unprivileged containers on the host side — it never modifies anything inside the container.",
"section": "Storage & Share · LXC"
},
"intro": {
"title": "What this does",
"body": "Take a directory that lives on the Proxmox host (a local folder, a mounted NAS share, a Proxmox-managed storage…) and make it appear inside an LXC container at a path you choose, with permissions that work even for unprivileged containers — without touching anything inside the container."
},
"bigPicture": {
"heading": "How it works (the big picture)",
"intro": "A bind mount is exactly what the name says: Proxmox tells the kernel \"the host directory <code>X</code> should also appear at path <code>Y</code> inside this container\". There's no copy, no sync, no network — both sides see the <em>same files</em> at the same time.",
"sourceLabel": "Proxmox Host",
"sourceDetail": "/mnt/data\n(your folder)",
"targetLabel": "LXC Container",
"targetDetail": "/mnt/data\n(shows up here)",
"arrowLabel": "bind mount",
"outro": "The host path on the left and the container path on the right can be different — for example, <code>/mnt/nas-films</code> on the host can become <code>/media/films</code> inside the container. The script adds the entry to the container config (<code>/etc/pve/lxc/&lt;ctid&gt;.conf</code>) using the next free <code>mpN</code> index, with two safe-defaults baked in:",
"items": [
"<code>shared=1</code> — tells Proxmox the data is shared storage, so it does not try to migrate the disk when you migrate the container.",
"<code>backup=0</code> — excludes the bind mount from <code>vzdump</code> backups (the data lives on the host, you back it up separately)."
]
},
"perms": {
"heading": "Permission handling — the smart part",
"intro": "Bind mounts are easy in principle. The hard part is permissions: an <strong>unprivileged</strong> LXC container shifts every UID by <strong>+100000</strong>, so a file created inside the container by user 1000 appears on the host as UID 101000 — a UID nobody on the host owns. To make this work without aligning UIDs across hosts and containers, ProxMenux applies the right \"open up permissions\" trick on the <em>host</em> side, depending on what kind of directory you picked:",
"headerType": "Host directory type",
"headerAction": "What the script offers to do",
"localType": "Local folder",
"localTypeSub": "e.g. /mnt/data",
"localActionRich": "<code>chmod o+rwx</code> + <code>setfacl o::rwx</code> on the host directory. Only offered if the CT is unprivileged and current permissions are insufficient.",
"cifsType": "Mounted CIFS / SMB",
"cifsTypeSub": "e.g. /mnt/pve/cifs-…",
"cifsActionRich": "Remount with <code>uid=0, gid=0, file_mode=0777, dir_mode=0777</code> so the CT (any UID) can read and write the share. <code>/etc/fstab</code> is updated.",
"nfsType": "Mounted NFS",
"nfsTypeSub": "e.g. /mnt/pve/nfs-…",
"nfsActionRich": "<code>chmod 1777</code> + <code>setfacl o::rwx</code> on the NFS mount. Cannot override server-side squashing — if even host root can't write, you are guided to fix the export on the NFS server.",
"privTitle": "Privileged containers don't need any of this",
"privBody": "For privileged containers, UID 0 in the CT is UID 0 on the host — root inside the CT can read and write the host directory directly without any permission tricks. The script detects this and skips the \"open up permissions\" step entirely.",
"noCtTitle": "The script never modifies anything inside the container",
"noCtBody": "All permission tweaks happen on the <strong>host filesystem</strong>. No <code>pct exec</code> chowns, no groups created in the CT, no fstab inside the container. If you reuse the bind-mounted directory in a different CT later, the same permissions apply automatically — no per-container setup."
},
"writes": {
"heading": "What ProxMenux writes — and what it doesn't",
"intro": "A common confusion when bind-mounting into an unprivileged CT: people assume ProxMenux must be writing <code>lxc.idmap</code> entries into <code>/etc/pve/lxc/&lt;CTID&gt;.conf</code>. <strong>It does not.</strong> Only one line is appended to that file — the bind mount itself:",
"outro": "The output line you see at the end of the run, <em>\"Unprivileged container — UID offset: 100000\"</em>, is purely informational — it just tells you the CT is using Proxmox's default unprivileged mapping (root in CT = UID 100000 on host). The script does not configure anything around it.",
"twoWaysHeading": "The two ways to make permissions work — and why ProxMenux picks one",
"headerApproach": "Approach",
"headerChanges": "What it changes",
"headerWhen": "When it fits",
"hostType": "Host-side perms",
"hostTypeSub": "(what this script does)",
"hostChangesRich": "<code>chmod o+rwx</code> + <code>setfacl o::rwx</code> on the host directory. The CT's mapped UIDs (100000+) fall into the \"others\" bucket, so opening <em>others</em> is enough.",
"hostWhen": "Generic shared-folder access from any CT. Multiple CTs sharing the same host directory. Simple and reusable.",
"idmapTypeRich": "<code>lxc.idmap</code>",
"idmapTypeSub": "(not used by this script)",
"idmapChangesRich": "Custom UID/GID mapping in <code>/etc/pve/lxc/&lt;CTID&gt;.conf</code> plus matching <code>/etc/subuid</code> + <code>/etc/subgid</code> entries on the host. CT must be restarted on every change.",
"idmapWhenRich": "You need a <em>specific</em> UID inside the CT to map to a <em>specific</em> UID on the host (e.g. <code>media:1000</code> in the CT must own files as <code>media:1000</code> on the host so NFS doesn't squash). A more rigid setup, normally only worth it for that exact scenario.",
"idmapTipTitle": "When you actually need lxc.idmap",
"idmapTipBody": "If the LXC Mount Manager doesn't cover your case — typically because you need files written from inside the CT to land on the host as a specific UID/GID (NFS exports with <code>all_squash</code>, Samba shares with strict ownership, sharing a directory with a host user that has the same name as someone inside the CT) — that is the moment to add <code>lxc.idmap</code> entries by hand. The Mount Manager won't fight you: the bind-mount line it wrote is independent of any idmap configuration you add later."
},
"opening": {
"heading": "Opening the tool",
"body": "From ProxMenux's main menu, open <strong>Storage &amp; Share Manager → Configure LXC Mount Points (Host ↔ Container)</strong>. You will see this sub-menu with three options:",
"imageAlt": "LXC Mount Manager menu — Add / View / Remove"
},
"addFlow": {
"heading": "Add a mount — full flow",
"intro": "The technical view, for when you want to know exactly what each dialog does:"
},
"sources": {
"heading": "What you can pick as a host directory",
"intro": "The host-directory picker is the most thorough one in the Storage &amp; Share section. It scans four sources and presents a deduplicated list:",
"headerSource": "Source",
"headerWhere": "Where it comes from",
"headerLabel": "Label in the menu",
"rows": [
{
"source": "Active network mounts",
"whereRich": "CIFS / NFS shares currently mounted, parsed from <code>/proc/mounts</code>.",
"labelRich": "<code>NFS [used/size]</code> or <code>CIFS/SMB [used/size]</code>"
},
{
"source": "Inactive fstab mounts",
"whereRich": "Defined in <code>/etc/fstab</code> but not currently mounted.",
"labelRich": "<code>fstab(off)-NFS</code> / <code>fstab(off)-CIFS/SMB</code>"
},
{
"source": "Local directories",
"whereRich": "Sub-directories under <code>/mnt</code> that are not network mounts.",
"labelRich": "<code>Local [size]</code>"
},
{
"source": "Proxmox storages",
"whereRich": "Storage paths under <code>/mnt/pve/*</code> (NFS / CIFS registered via <code>pvesm</code>).",
"labelRich": "<code>PVE-NFS</code> / <code>PVE-CIFS/SMB</code> / <code>Proxmox-Storage</code>"
},
{
"source": "Manual entry",
"where": "Anything else — type the absolute path yourself.",
"labelRich": "<em>Enter path manually</em>"
}
],
"tipTitle": "Internal Proxmox paths are filtered out",
"tipBody": "The picker explicitly skips internal Proxmox paths (<code>/mnt/pve/local</code>, <code>/mnt/pve/local-lvm</code>, <code>/mnt/pve/backup</code>, …) — those are reserved for Proxmox internals and you should not bind-mount them. Only user-added storages show up."
},
"manual": {
"heading": "Manual equivalent",
"privIntro": "For a privileged container — the simplest case, no permission tricks:",
"unprivLocalIntro": "For an unprivileged container with a local host directory — open up permissions on the host first:",
"unprivCifsIntro": "For an unprivileged container with a CIFS share already mounted on the host:"
},
"view": {
"heading": "View mount points",
"body": "Lists every <code>mpN</code> entry across every container on this Proxmox host, grouped by CT id and showing host path → container path plus any extra options. Read-only — useful as a sanity check before you add or remove anything."
},
"remove": {
"heading": "Remove a mount point",
"body": "Pick the container, pick the <code>mpN</code> entry, confirm. The script runs <code>pct set --delete mpN</code> to drop the entry from the CT config and offers to restart the container if it's running. The host directory and its contents are <strong>not touched</strong> — you can re-add the mount later (or attach the same directory to a different CT).",
"warnTitle": "Live-running containers need a restart for changes to take effect",
"warnBody": "Both adding and removing mount points only become visible inside the container after a restart. The script offers a one-click <code>pct reboot</code> at the end of each operation; you can decline and reboot manually later."
},
"troubleshoot": {
"heading": "Troubleshooting",
"noMountTitle": "Mount appears in pct config but not inside the container",
"noMountBody": "Bind mounts only attach when the container starts. If you added the mount while the CT was running, restart it (<code>pct reboot &lt;ctid&gt;</code>). If it's already restarted and still missing, check <code>pct config &lt;ctid&gt;</code> to confirm the entry exists and the host path actually contains a directory.",
"noWriteTitle": "Container can see the directory but cannot write",
"noWriteBody": "Almost always a permissions issue. For unprivileged containers, run the script's permission fix again — the host directory's ACLs may have been reset by another tool (rsync, restore from backup, manual <code>chmod</code>). For CIFS, double-check the mount options on the host: <code>findmnt /mnt/pve/cifs-…</code>, look for <code>uid=</code> / <code>gid=</code> / <code>file_mode=</code> values.",
"alreadyTitle": "\"This path is already used as a mount point in this container\"",
"alreadyBody": "You picked the same container path that's already wired to a different host directory. Either pick a different container path, or remove the existing mount point first.",
"nfsTitle": "NFS access blocked even after applying the host fix",
"nfsIntro": "Your NFS server is squashing root or all connections. The script can detect this (it tries to write a test file from the host) and shows server-side guidance. Two common server-side fixes for the export:",
"nfsItems": [
"<code>no_root_squash</code> — privileged CTs can write directly.",
"<code>all_squash,anonuid=65534,anongid=65534</code> — for unprivileged CTs."
],
"nfsOutro": "These changes happen on the NFS server (TrueNAS, Synology, your custom export, …), not on Proxmox.",
"fstabOffTitle": "Mounting \"fstab(off)\" entries does nothing",
"fstabOffBody": "The picker shows <code>fstab(off)-</code> entries when a network mount is defined in fstab but not currently mounted. The script lets you bind-mount the path, but the directory will be empty until you actually mount the share (<code>mount &lt;path&gt;</code> on the host). Mount it first, then bind it into the CT."
},
"related": {
"heading": "Related",
"items": [
{
"href": "/docs/storage-share/host-local-shared",
"label": "Add Shared Directory on Host",
"tailRich": " — typical first step: prepare a <code>/mnt/shared</code> on the host before bind-mounting it into one or more CTs here."
},
{
"href": "/docs/storage-share/host-nfs",
"label": "Add NFS share as Proxmox storage",
"extraHref": "/docs/storage-share/host-samba",
"extraLabel": "Add Samba share as Proxmox storage",
"joiner": " / ",
"tailRich": " — register an external share in Proxmox first, then bind-mount its <code>/mnt/pve/&lt;id&gt;</code> path into the CT here."
},
{
"href": "/docs/storage-share/lxc-nfs-client",
"label": "NFS client in LXC",
"extraHref": "/docs/storage-share/lxc-samba-client",
"extraLabel": "Samba client in LXC",
"joiner": " / ",
"tail": " — the alternative when you want the CT itself to mount the share (requires a privileged container)."
}
]
}
}

128
web/messages/en/docs/storage-share/lxc-nfs-client.json Normal file
View File

@@ -0,0 +1,128 @@
{
"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."
}
]
}
}

159
web/messages/en/docs/storage-share/lxc-nfs-server.json Normal file
View File

@@ -0,0 +1,159 @@
{
"meta": {
"title": "NFS server in LXC | ProxMenux Documentation",
"description": "Expose folders over NFS from inside a Proxmox LXC container with ProxMenux. Auto-installs nfs-kernel-server, sets up a universal sharedfiles group convention, manages /etc/exports, network ACL and uninstall. Requires a privileged container.",
"ogTitle": "NFS server in LXC | ProxMenux Documentation",
"ogDescription": "Run an NFS server inside a privileged LXC container. Universal sharedfiles group, network ACL and full uninstall."
},
"header": {
"title": "NFS server in LXC",
"description": "Run an NFS kernel server inside a Proxmox LXC container and expose folders to other machines on the network. ProxMenux installs nfs-kernel-server, sets up a universal sharedfiles group convention so multiple privileged CTs can share files cleanly, manages /etc/exports and offers a full uninstall path.",
"section": "Storage & Share · LXC"
},
"privReq": {
"title": "Privileged container required",
"body": "<code>nfs-kernel-server</code> needs to mount the kernel filesystem <code>nfsd</code> at <code>/proc/fs/nfsd</code>, which requires <code>CAP_SYS_ADMIN</code> in the host kernel namespace — not just in the container's user namespace. Unprivileged LXC does not expose that capability. In practice, the service simply fails to start with <code>rpc.nfsd: Unable to access /proc/fs/nfsd errno 2 (No such file or directory)</code> and systemd marks <code>nfs-server.service</code> as a failed dependency. The script enforces a privileged CT and <strong>aborts if it is unprivileged</strong>. If you cannot use a privileged CT, run the NFS server inside a VM."
},
"what": {
"heading": "What this does",
"body": "This is the <em>opposite</em> of the NFS client page. The container becomes an NFS <strong>server</strong>: it exposes a folder of its filesystem to clients on the network. Other CTs, the Proxmox host, VMs or physical machines can then mount that folder.",
"diagramServerLabel": "LXC (privileged) — NFS server",
"diagramServerDetail": "/mnt/data\n(folder you expose)\n\nchown root:sharedfiles\nchmod 2775 (SGID)\n\nnfs-kernel-server\n+ rpcbind running",
"diagramClientLabel": "Any client on the network",
"diagramClientDetail": "another CT, the host,\na VM, a physical machine…",
"diagramArrow": "NFS export"
},
"shared": {
"heading": "The \"sharedfiles\" group convention",
"body": "Before exporting the folder, ProxMenux creates a group called <code>sharedfiles</code> with <strong>GID 101000</strong> inside the container, adds every regular user to it, then sets the export directory to <code>root:sharedfiles</code> with mode <code>2775</code>. The <code>2</code> at the front is the SGID bit — every file or folder created inside automatically inherits the <code>sharedfiles</code> group.",
"gidTitle": "Why GID 101000 specifically",
"gidBody": "It maps to host GID <strong>1000</strong> when an unprivileged container reads the same file (LXC default idmap shifts everything by +100000). In the current ProxMenux flow the NFS server itself runs in a <strong>privileged</strong> CT (no shift on its side), but the convention keeps the group ID numerically consistent with unprivileged client CTs that may mount this share later. Two privileged CTs both using <code>sharedfiles</code> at GID 101000 can read / write each other's files cleanly because the GID numbers match end-to-end.",
"remapTitle": "The script also creates 'remap_*' users — they are vestigial here",
"remapBody": "For every regular user in the CT (and for common UIDs like 33 = www-data, 1000, 1001, 1002), the script creates a parallel <code>remap_&lt;uid&gt;</code> user with UID = <code>&lt;uid&gt; + 100000</code>, all members of <code>sharedfiles</code>. The <code>+100000</code> shift mimics the LXC unprivileged idmap, but since this script enforces a <strong>privileged</strong> CT (no shift), those <code>remap_*</code> users are shadow accounts with no real-world counterpart on the host. They are harmless leftovers from a more ambitious design intent. If you don't see them in <code>getent passwd</code>, nothing breaks."
},
"defaults": {
"heading": "Default export options — read this first",
"warnTitle": "Default options include no_root_squash",
"warnBody": "ProxMenux defaults to <code>rw,sync,no_subtree_check,'<'strong'>'no_root_squash'<'/strong'>'</code>. This means <strong>any client root user can write as root on the export</strong> — appropriate for a trusted home LAN but never for an untrusted network. If your CT is reachable from an untrusted segment (a public network, a VPS, a hostile VLAN), <strong>change the export options to <code>root_squash</code></strong> in the custom-options dialog."
},
"opening": {
"heading": "Opening the tool",
"body": "From ProxMenux's main menu, open <strong>Storage &amp; Share Manager → Configure NFS Server in LXC (only privileged)</strong>. ProxMenux first asks you to pick the target CT (and starts it if stopped); aborts if unprivileged. Once the CT is selected you see this sub-menu with five options:",
"imageAlt": "NFS Server Manager menu — Create / View / Delete / Status / Uninstall"
},
"howRuns": {
"heading": "How the script runs (Create flow)"
},
"network": {
"heading": "Network ACL — who can mount the share",
"intro": "The network field in <code>/etc/exports</code> filters which clients are allowed to mount. ProxMenux offers three modes:",
"headerMode": "Mode",
"headerValue": "Value written to /etc/exports",
"headerWhen": "When to pick it",
"rows": [
{
"mode": "Local network",
"value": "192.168.0.0/16",
"whenRich": "Standard home / SOHO LAN. Covers every <code>192.168.*.*</code> address."
},
{
"mode": "Custom subnet",
"value": "your CIDR (e.g. 10.0.0.0/24)",
"when": "When your LAN is not in 192.168.x.x or you want a tighter scope."
},
{
"mode": "Single host",
"value": "your IP (e.g. 10.0.0.42)",
"when": "Only one specific machine should mount. Most restrictive."
}
]
},
"options": {
"heading": "Export options explained",
"headerOption": "Option",
"headerEffect": "What it does",
"rows": [
{
"option": "rw / ro",
"effect": "Allow read-write or read-only access for connecting clients."
},
{
"option": "sync",
"effectRich": "Reply to write requests only after the data is on disk. Safer than <code>async</code> at the cost of throughput."
},
{
"option": "no_subtree_check",
"effect": "Skip the per-request check that the file is still inside the exported subtree. Faster and avoids issues when files are renamed mid-flight."
},
{
"option": "no_root_squash",
"effectRich": "<strong>Trust client root.</strong> A client mounting as root writes as root on the server. Good for trusted LANs (e.g. backup tooling needs to preserve ownership). Replace with <code>root_squash</code> if you don't fully trust every machine on the network ACL."
}
]
},
"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 <code>pct enter &lt;ctid&gt;</code>:"
},
"view": {
"heading": "View current exports",
"body": "Cats <code>/etc/exports</code> from inside the CT (skipping comments / blanks) and prints each export with its network ACL and option string. Useful to check which folders are exposed before sharing the CT's IP with someone."
},
"delete": {
"heading": "Delete an export",
"body": "Lists every line in <code>/etc/exports</code> for selection, removes the chosen one (<code>sed -i</code>), runs <code>exportfs -ra</code> and restarts <code>nfs-kernel-server</code>. The folder itself and its contents are left intact."
},
"status": {
"heading": "Check NFS status",
"body": "Diagnostic pass: confirms <code>nfs-kernel-server</code> and <code>rpcbind</code> are installed and active, prints <code>exportfs -v</code> output, lists active NFS sessions (<code>showmount -a</code>) and current client connections."
},
"uninstall": {
"heading": "Uninstall NFS server",
"body": "Full clean-up after confirmation: stops + disables <code>nfs-kernel-server</code> and <code>rpcbind</code>, clears <code>/etc/exports</code>, <code>apt-get purge</code> the NFS packages, removes the <code>sharedfiles</code> group and the <code>remap_*</code> users, kills any leftover processes. The exported <strong>folders themselves are not deleted</strong> — only the NFS configuration and packages.",
"warnTitle": "The script stops at the export line, not at the data",
"warnBody": "Both <em>Delete export</em> and <em>Uninstall NFS server</em> remove the export configuration. The data on the exported folder is preserved. To delete the data too, do it explicitly with <code>rm -rf</code> after the script finishes — and back it up first if anyone might still need it."
},
"troubleshoot": {
"heading": "Troubleshooting",
"privTitle": "Privileged container required (script aborts)",
"privBody": "The selected CT is unprivileged. <code>nfs-kernel-server</code> cannot start there because mounting <code>/proc/fs/nfsd</code> needs <code>CAP_SYS_ADMIN</code> in the host kernel namespace, and the <code>nfsd</code> module is not exposed to the container's namespace either (<code>modprobe nfsd</code> from inside returns <code>FATAL: Module nfsd not found</code>). If you bypass the gate, you will see <code>rpc.nfsd: Unable to access /proc/fs/nfsd errno 2 (No such file or directory)</code> in the journal and no NFS ports will ever open. The only workable options are: convert the CT to privileged, or move the NFS server to a VM.",
"aptTitle": "apt-get install fails",
"aptIntro": "The script assumes a Debian-family CT. On Alpine / Arch / Rocky / Alma, install the NFS server packages by hand:",
"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.",
"aclTitle": "Client cannot mount: 'access denied by server'",
"aclBody": "The client's IP is outside the network ACL you configured. Re-create the export with a wider subnet, or add the client's exact IP. Common gotcha: clients connecting through a router NAT may appear with the router's WAN IP, not the client's LAN IP — check on the server with <code>tcpdump -n port 2049</code>.",
"ownTitle": "Files written by the client appear with weird ownership on the server",
"ownIntro": "Two possibilities:",
"ownItems": [
"With <code>no_root_squash</code> (default), client root writes as root on the server. Files are owned by <code>root:sharedfiles</code> thanks to the SGID on the folder.",
"Non-root client users write as their own UID/GID. If their UID does not exist on the server, files appear with raw numbers (e.g. <code>1234:1234</code>). Use the <code>sharedfiles</code> group on the client too, or align UIDs across the systems that share files."
],
"noShowTitle": "Server reachable but showmount returns nothing",
"noShowBody": "After editing <code>/etc/exports</code>, you must reload the export table with <code>exportfs -ra</code> and restart <code>nfs-kernel-server</code> — the script does both, but if you edited the file by hand, do it yourself. Also confirm the firewall on the CT (and on the Proxmox host) allows TCP/UDP 2049 and the rpcbind port (111)."
},
"related": {
"heading": "Related",
"items": [
{
"href": "/docs/storage-share/lxc-nfs-client",
"label": "NFS client in LXC",
"tail": " — the inverse: mount external NFS shares from inside a CT."
},
{
"href": "/docs/storage-share/lxc-samba-server",
"label": "Samba server in LXC",
"tail": " — sibling page, same pattern with SMB / CIFS instead of NFS."
},
{
"href": "/docs/storage-share/host-nfs",
"label": "NFS share as Proxmox storage",
"tailRich": " — once your CT is exporting, register that NFS share in Proxmox so it appears under <em>Datacenter → Storage</em>."
}
]
}
}

155
web/messages/en/docs/storage-share/lxc-samba-client.json Normal file
View File

@@ -0,0 +1,155 @@
{
"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>never stores the password in plain text</strong> in the mount command or in <code>/etc/fstab</code>. Instead it writes a credentials file inside the CT:",
"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": "Your container always boots, even if the Samba 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>:",
"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."
}
]
}
}

132
web/messages/en/docs/storage-share/lxc-samba-server.json Normal file
View File

@@ -0,0 +1,132 @@
{
"meta": {
"title": "Samba server in LXC | ProxMenux Documentation",
"description": "Run a Samba (SMB / CIFS) server inside a Proxmox LXC container with ProxMenux. Auto-installs samba, manages /etc/samba/smb.conf, smbpasswd users, sharedfiles group for bind-mounted folders. Requires a privileged container.",
"ogTitle": "Samba server in LXC | ProxMenux Documentation",
"ogDescription": "Expose folders over SMB/CIFS from inside a privileged LXC container. Auto-install, smbpasswd user, bind-mount aware permissions."
},
"header": {
"title": "Samba server in LXC",
"description": "Run a Samba (SMB / CIFS) server inside a Proxmox LXC container and expose folders to Windows / macOS / Linux clients on the network. ProxMenux installs samba, creates a Samba user with smbpasswd, manages /etc/samba/smb.conf, and applies bind-mount aware permissions when the shared folder comes from the host.",
"section": "Storage & Share · LXC"
},
"privReq": {
"title": "Privileged container required",
"body": "Samba impersonates the connecting user with <code>setgroups()</code> on every tree connection (the moment a client opens a share). In an unprivileged LXC, the kernel rejects that syscall because the container's user namespace is created with <code>setgroups=deny</code> — and <code>smbd</code> responds by aborting the worker process with <code>PANIC: sys_setgroups failed</code>. The result is that <code>smbd</code> starts and binds ports 139/445, but every client connection fails with <code>NT_STATUS_CONNECTION_DISCONNECTED</code>. The script enforces a privileged CT for this reason and <strong>aborts if it is unprivileged</strong>. There is no clean fix on the server side; use a privileged CT, or run Samba inside a VM."
},
"what": {
"heading": "What this does",
"body": "The container becomes an SMB/CIFS server: it runs <code>smbd</code>, exposes a folder via <code>/etc/samba/smb.conf</code> and accepts client connections on ports <code>139</code> / <code>445</code>. Clients see the share at <code>\\\\&lt;ct-ip&gt;\\&lt;share-name&gt;</code> in Windows Explorer, <code>smb://&lt;ct-ip&gt;/&lt;share-name&gt;</code> in macOS Finder, or via <code>mount.cifs</code> on Linux.",
"diagramServerLabel": "LXC (privileged) — Samba server",
"diagramServerDetail": "/mnt/data\n(folder you expose)\n\nsmbd + nmbd running\n\nUser: <username>\n(via smbpasswd)\n\nForce group:\nsharedfiles",
"diagramClientLabel": "Any client on the network",
"diagramClientDetail": "Windows: \\\\<ip>\\<share>\nmacOS: smb://<ip>/<share>\nLinux: mount.cifs",
"diagramArrow": "SMB / CIFS"
},
"perms": {
"heading": "Two permission paths depending on the folder type",
"body": "Before adding the share to <code>smb.conf</code>, the script checks whether the chosen folder is a <strong>bind mount from the host</strong> or a regular <strong>local folder inside the CT</strong> — and applies different ownership / permissions accordingly:",
"headerType": "Folder type",
"headerAction": "What the script does",
"bindType": "Bind-mount from host",
"bindTypeSubRich": "detected via <code>mount</code> output",
"bindActionRich": "Creates group <code>sharedfiles</code> (default GID 999, dynamic if taken), adds the Samba user to it, then <code>chown root:sharedfiles</code> + <code>chmod 2775</code> (SGID — new files inherit the group). If the user still cannot write, applies <code>setfacl -m u:&lt;user&gt;:rwx</code>.",
"localType": "Local folder inside CT",
"localTypeSub": "no bind mount detected",
"localActionRich": "Standard ownership: <code>chown -R &lt;user&gt;:&lt;user&gt;</code> + <code>chmod -R 755</code>. No shared group needed because no other CT writes to this folder. Falls back to <code>setfacl</code> if write access is still missing.",
"gidTitle": "GID for 'sharedfiles' differs from the NFS server flow",
"gidBody": "The Samba server script uses GID <strong>999</strong> for <code>sharedfiles</code>, while the <nfsLink>NFS server flow</nfsLink> uses GID <strong>101000</strong>. If you run both servers in the same CT and want a single shared group across both protocols, edit one of them to match the other after the install (e.g. <code>groupmod -g 101000 sharedfiles</code>) and re-apply ownership on the affected folders. This is a known inconsistency in the current scripts."
},
"opening": {
"heading": "Opening the tool",
"body": "From ProxMenux's main menu, open <strong>Storage &amp; Share Manager → Configure Samba Server in LXC (only privileged)</strong>. ProxMenux first asks you to pick the target CT (and starts it if stopped); aborts if unprivileged. Once the CT is selected you see this sub-menu with five options:",
"imageAlt": "Samba Server Manager menu — Create / View / Delete / Status / Uninstall"
},
"howRuns": {
"heading": "How the script runs (Create flow)"
},
"modes": {
"heading": "The three share modes",
"intro": "Each mode writes a different stanza to <code>smb.conf</code>. All three include <code>valid users = &lt;username&gt;</code> (no anonymous), <code>force group = sharedfiles</code> (so new files belong to the shared group) and <code>veto files = /lost+found/</code> (hides it from clients).",
"headerMode": "Mode",
"headerBlock": "Block written to smb.conf",
"rwMode": "Read-Write",
"roMode": "Read-Only",
"customMode": "Custom",
"customBodyRich": "You type your own directives in a free-text box. ProxMenux still wraps them in a <code>[share]</code> block with the standard <code>path</code>, <code>valid users</code>, <code>force group</code> and <code>veto files</code>."
},
"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 <code>pct enter &lt;ctid&gt;</code>:"
},
"connect": {
"heading": "Connecting from clients",
"headerOs": "Client OS",
"headerHow": "How to connect",
"windowsOs": "Windows",
"windowsHowRich": "File Explorer → address bar: <code>\\\\&lt;ct-ip&gt;\\&lt;share-name&gt;</code>. Or <em>Map Network Drive</em> → check \"Connect using different credentials\".",
"macosOs": "macOS",
"macosHowRich": "Finder → <em>Go → Connect to Server…</em> → <code>smb://&lt;ct-ip&gt;/&lt;share-name&gt;</code>. Or <code>mount_smbfs //user@&lt;ct-ip&gt;/&lt;share&gt; /mountpoint</code>.",
"linuxOs": "Linux",
"linuxHowRich": "<code>mount -t cifs //&lt;ct-ip&gt;/&lt;share&gt; /mnt/x -o username=&lt;u&gt;,password=&lt;p&gt;,iocharset=utf8</code>. Or use the <clientLink>Samba client in LXC</clientLink> page if the client is another Proxmox CT."
},
"view": {
"heading": "View current shares",
"body": "Parses <code>/etc/samba/smb.conf</code> inside the CT and lists every <code>[share]</code> block (skipping <code>[global]</code>, <code>[homes]</code>, <code>[printers]</code>) with its path. Useful as a quick inventory."
},
"delete": {
"heading": "Delete a share",
"body": "Lets you pick a share by name, removes the block from <code>smb.conf</code> (<code>sed</code> deletes from <code>[share]</code> down to the next blank line), and restarts <code>smbd</code>. The folder itself and its contents are left intact."
},
"status": {
"heading": "Check Samba status",
"body": "Reports whether <code>smbd</code> and <code>nmbd</code> are installed and active, lists Samba users (<code>pdbedit -L</code>) and prints active sessions (<code>smbstatus</code>)."
},
"uninstall": {
"heading": "Uninstall Samba server",
"body": "Full clean-up after confirmation: stops + disables <code>smbd</code> and <code>nmbd</code>, backs up <code>smb.conf</code> to <code>smb.conf.backup.YYYYMMDD_HHMMSS</code>, removes Samba users with <code>smbpasswd -x</code>, and <code>apt-get purge</code> the Samba packages. The exported <strong>folders themselves are not deleted</strong>.",
"warnTitle": "Folders survive — back up data separately",
"warnBody": "Both <em>Delete share</em> and <em>Uninstall Samba server</em> remove the share configuration. The data on the exported folders is preserved. To delete the data too, do it explicitly with <code>rm -rf</code> after the script finishes."
},
"troubleshoot": {
"heading": "Troubleshooting",
"privTitle": "Privileged container required (script aborts)",
"privBody": "The selected CT is unprivileged and <code>smbd</code> cannot serve files there. If you bypass the gate and configure Samba by hand, <code>smbd</code> starts and the ports open, but the first client connection panics with <code>PANIC: sys_setgroups failed</code> in <code>/var/log/samba/log.&lt;client&gt;</code> and the client sees <code>NT_STATUS_CONNECTION_DISCONNECTED</code>. The cause is the unprivileged user namespace having <code>setgroups=deny</code>, which blocks Samba's per-connection impersonation. Neither <code>features=keyctl=1</code> nor removing <code>force user</code> / <code>force group</code> changes this. The only workable options are: convert the CT to privileged, or move Samba to a VM.",
"aptTitle": "apt-get install fails",
"aptIntro": "The script assumes a Debian-family CT. On Alpine / Arch / Rocky / Alma, install Samba by hand:",
"aptItems": [
"Alpine: <code>apk add samba</code>",
"Arch: <code>pacman -S samba</code>",
"Rocky / Alma: <code>dnf install samba</code>"
],
"aptOutro": "Then re-run the ProxMenux script — the install step skips when the tools are already present.",
"noShareTitle": "Client connects but cannot see the share",
"noShareBody": "Check that <code>browseable = yes</code> is set in the share block (default for rw / ro modes; may be missing in custom). Also check the CT firewall and the Proxmox host firewall allow TCP 445 (SMB) and 139 (NetBIOS). Some Windows clients also require name resolution — try the IP directly first.",
"authTitle": "Authentication fails (NT_STATUS_LOGON_FAILURE)",
"authBody": "Either the wrong password (Samba passwords are <em>separate</em> from system passwords — see them with <code>pdbedit -L</code>) or the user is not in <code>valid users</code> for that share. Reset the password with <code>smbpasswd &lt;user&gt;</code> inside the CT.",
"groupTitle": "Files written by the client appear with wrong group on the server",
"groupBody": "The script sets <code>force group = sharedfiles</code> in the share block, so new files should be group <code>sharedfiles</code>. If they aren't, the SGID bit on the parent directory may have been lost (someone ran <code>chmod</code> by hand). Reapply: <code>chmod 2775 /mnt/&lt;share&gt;</code>.",
"bothTitle": "Sharing the same folder over both NFS and Samba",
"bothBody": "ProxMenux uses different GIDs for <code>sharedfiles</code> in each script (Samba: 999, NFS: 101000). If you serve the same folder via both, decide on one GID and align both. The simplest fix: after running both scripts, edit the smaller GID:"
},
"related": {
"heading": "Related",
"items": [
{
"href": "/docs/storage-share/lxc-samba-client",
"label": "Samba client in LXC",
"tail": " — the inverse: mount external Samba shares from inside a CT."
},
{
"href": "/docs/storage-share/lxc-nfs-server",
"label": "NFS server in LXC",
"tail": " — sibling page, same pattern with NFS instead of CIFS."
},
{
"href": "/docs/storage-share/host-samba",
"label": "Samba / CIFS as Proxmox storage",
"tailRich": " — once your CT is exposing, register that share in Proxmox so it appears under <em>Datacenter → Storage</em>."
}
]
}
}