You've got two or three machines at home — maybe a laptop, a desktop, an old Mac Mini gathering dust — and every time you need to move a file between them you're emailing it to yourself or plugging in a USB stick like it's 2008. If that sounds familiar, you don't need a dedicated NAS box. You already have a Proxmox VE server running, and that's enough to build a proper file share in about fifteen minutes.
This guide walks you through installing Samba inside a lightweight LXC container on Proxmox VE, so you end up with a network share that Windows, macOS, and Linux machines can all connect to without installing any extra software on the client side. No NAS hardware, no separate box under the desk, no monthly cloud storage bill.
What You Will Learn
- What Samba is and why it's the protocol Windows, macOS, and Linux all understand natively
- How to create a small, unprivileged LXC container just for file sharing
- How to install and configure Samba from scratch, including a real
smb.confshare definition - How to create a Samba user that's separate from your Linux login
- How to connect from Windows, macOS, and a Linux desktop
- The specific error messages you'll hit and what actually causes them
- A short list of habits that will save you a headache six months from now
What Is This Feature?
Samba is an open-source implementation of SMB (Server Message Block), the file-sharing protocol Windows has used since the 1990s. When you type \\servername\sharename into Windows Explorer, or connect to smb:// on a Mac, that's SMB doing the work. Samba lets a Linux machine — in this case, an LXC container — speak that same protocol, so it looks like a normal network drive to every device on your LAN.
An LXC container, if you haven't used one yet, is a lightweight form of virtualization that shares the host's Linux kernel instead of emulating its own hardware like a full VM does. That makes it start faster and use a fraction of the RAM and disk a VM would need for the same job. For something as simple as a file server, a container is the right tool — you don't need 4 GB of RAM and a virtual BIOS just to run Samba.
Why Would You Use It?
A few reasons this setup is worth the fifteen minutes:
- It's isolated. Samba runs in its own container, so a misconfigured share or a crashed
smbdprocess can't touch anything else on your Proxmox host. - Snapshots make it forgiving. Take a snapshot before you mess with permissions or the config file. Broke something? Roll back in seconds instead of troubleshooting at 11 p.m.
- It's cheap on resources. A Samba container runs comfortably on 512 MB of RAM and a single vCPU. You could run a dozen of these on hardware that would choke running a couple of full NAS VMs.
- You already own the hardware. If your Proxmox box has a second drive or some free space on local-lvm, you don't need to buy a Synology to get a usable network share.
Honestly, if you're just sharing a folder for two or three household devices, this is overkill-proof. You don't need TrueNAS or a full NAS OS for that job — Samba in a small container does it fine.
Prerequisites
Before you start, make sure you have:
- A working Proxmox VE 9.2 host (Debian 13 "Trixie" based) with at least one bridge, typically
vmbr0, configured for your LAN - The Debian 13 LXC template downloaded — if it's not there yet, run
pveam updatefollowed bypveam available --section systemto see it - Some free space on a storage volume for the container's root disk and the shared data — 8 GB is plenty to start
- SSH or console access to the Proxmox host, and basic comfort typing commands in a terminal
- Devices on the same LAN to test the share from once it's up
You don't need a static IP configured yet — we'll set one during container creation — and you don't need any prior Samba experience. We'll explain every setting as it comes up.
Step-by-Step Tutorial
Step 1: Download the Debian 13 template
On the Proxmox host, refresh the template list and grab the current Debian template:
pveam update
pveam available --section system | grep debian-13
pveam download local debian-13-standard_13.5-1_amd64.tar.zstThat last command downloads the actual template archive to local storage. It's a few hundred megabytes, so on a typical home connection this takes a minute or two.
Step 2: Create the container
You can do this in the web GUI (Datacenter → your node → Create CT), or straight from the shell:
pct create 200 local:vztmpl/debian-13-standard_13.5-1_amd64.tar.zst \
--hostname samba01 \
--cores 1 \
--memory 512 \
--swap 512 \
--rootfs local-lvm:8 \
--net0 name=eth0,bridge=vmbr0,ip=192.168.1.50/24,gw=192.168.1.1 \
--unprivileged 1 \
--features nesting=0Swap out 192.168.1.50/24 and the gateway for something that matches your own network. Container ID 200 is arbitrary — pick anything not already in use. Leave unprivileged checked (it's the default) unless you have a specific reason not to; we'll get into why that matters in the troubleshooting section.
Start the container and drop into its console:
pct start 200
pct enter 200Step 3: Update the container and install Samba
Inside the container:
apt update && apt full-upgrade -y
apt install samba samba-common-bin acl -yThe acl package isn't strictly required, but it lets you set finer-grained permissions later if more than one person needs different access levels to the same folder. Worth having from the start.
Step 4: Create the shared folder
mkdir -p /srv/share
chmod 2775 /srv/share
chown root:sambashare /srv/share 2>/dev/null || groupadd sambashare && chown root:sambashare /srv/shareThe 2775 permission mode sets the setgid bit, so new files created inside /srv/share inherit the sambashare group instead of whatever group the creating user happens to be in. Skip that bit and you'll end up with a folder full of files owned by five different groups within a week.
Step 5: Create a Samba user
Samba keeps its own password database, separate from the Linux system. Create a system user first (with no shell login, since it only needs to authenticate to Samba), then set its Samba password:
useradd -M -s /usr/sbin/nologin -G sambashare fileuser
smbpasswd -a fileuserIt'll prompt you twice for a password. Use something you don't reuse elsewhere — this password travels over the local network in the SMB handshake, and while modern SMB encrypts it, there's no reason to take chances with a password you use for anything important.
Step 6: Configure the share
Open /etc/samba/smb.conf in your editor of choice (nano is already installed) and add this to the bottom of the file:
[share]
path = /srv/share
browseable = yes
read
guest ok = no
valid users = fileuser
create mask = 0664
directory mask = 2775
force group = sambashareCheck the file for typos before restarting anything — a single misplaced bracket will stop Samba from loading the config at all:
testparmIf it prints your share definition back without complaining, you're good.
Step 7: Restart and enable Samba
systemctl enable --now smbd nmbdsmbd handles the actual file sharing and authentication. nmbd handles NetBIOS name resolution — the part that lets older Windows tools find your server by name instead of IP. You want both running.
Step 8: Connect from a client
From Windows, open File Explorer and type \\192.168.1.50\share into the address bar. You'll be prompted for a username and password — use fileuser and the password you set with smbpasswd.
From a Mac, open Finder, press Cmd+K, and enter smb://192.168.1.50/share.
From Linux, most file managers accept smb://192.168.1.50/share directly in the location bar, or you can mount it from the terminal with mount -t cifs if you'd rather have it as a proper mount point.
Commands Explained
| Command | What it actually does |
|---|---|
pveam update | Refreshes the list of container templates Proxmox knows about from the online repository. |
pct create | Builds a new LXC container from a template, with the resource and network options you pass as flags. |
pct enter 200 | Drops you straight into container 200's shell from the Proxmox host, without needing SSH set up first. |
useradd -M -s /usr/sbin/nologin | Creates a user with no home directory (-M) and no ability to log in via SSH or console (-s /usr/sbin/nologin) — it exists only for Samba to authenticate against. |
smbpasswd -a | Adds a user to Samba's own password database. This is separate from the Linux password entirely. |
testparm | Validates smb.conf syntax and prints the parsed configuration, so you catch mistakes before restarting the service. |
systemctl enable --now smbd nmbd | Starts both Samba services immediately and sets them to launch automatically on every container boot. |
Common Errors
A few messages come up often enough that it's worth knowing them before you hit them:
- NT_STATUS_LOGON_FAILURE — the username or password Windows sent doesn't match what Samba has on file. Nine times out of ten this means you're typing your Linux password instead of the one you set with
smbpasswd. They're not the same thing. - NT_STATUS_ACCESS_DENIED — the credentials are correct, but the filesystem permissions on
/srv/sharedon't allow that user to write. Double-check ownership withls -la /srv/share. - "Windows cannot access \\192.168.1.50\share" with no login prompt at all — usually a network path issue, not a Samba issue. Ping the container's IP from the Windows machine first to rule out routing or firewall problems.
- Share doesn't show up when browsing the network, but connects fine by IP — this is almost always
nmbdnot running, or your Windows machine having network discovery turned off. Connecting directly by IP sidesteps it entirely.
Troubleshooting
Start with testparm any time something feels off — it catches config typos before they cost you a restart cycle. If the config is clean but clients still can't connect, check what Samba itself thinks is going on:
smbstatusThis lists active connections and locked files. If nothing shows up when a client tries to connect, the problem is likely network-level, not Samba-level.
Next, check that the container can actually be reached:
ping 192.168.1.50If that fails from a client machine, look at the Proxmox firewall settings for the container — if you enabled the firewall on net0 during creation, make sure ports 445 (SMB) and 139 (NetBIOS) are allowed, or just disable the per-container firewall for now if you're only serving your trusted LAN.
One more thing that trips people up: unprivileged containers map the container's root user to an unprivileged UID on the Proxmox host for security reasons. This is almost never a problem for Samba specifically, since Samba manages its own user database anyway — but if you're bind-mounting a folder from the Proxmox host into the container instead of using local container storage, ownership can look wrong from the host's perspective. If that happens, check the UID mapping in /etc/pve/lxc/200.conf rather than assuming the permissions are broken.
Best Practices
- Don't turn on
guest ok = yesunless you genuinely want anyone on your network to read and write the share with no login at all. It's tempting for convenience, but it's also how "temporary" shares turn into permanent security gaps. - Give each person their own Samba user rather than sharing one login across the household. It costs you thirty extra seconds per person and makes it obvious who deleted what later.
- Snapshot the container before any change to
smb.confyou're not 100% sure about.pct snapshot 200 before-config-changetakes a few seconds and saves you from rebuilding the whole thing if a change breaks the service. - Back it up. A Samba container is still just a container — run it through your normal vzdump schedule like everything else. The data inside
/srv/shareis not magically safe just because it's "just a file share." - Keep SMB on your LAN only. Don't forward ports 445 or 139 through your router to the internet — SMB was never designed to be internet-facing, and it's a frequent target for scanning. If you need remote access to your files, put a VPN in front of it instead.
Frequently Asked Questions
Do I need a full VM instead of an LXC container for this?
No. Samba has no special hardware requirements, so a container is not just adequate, it's the better choice — faster to start, lighter on RAM, and easier to snapshot.
Should I use Samba or NFS for my home network?
If you have Windows or macOS machines involved, use Samba — both speak SMB natively. NFS is a better fit for an all-Linux setup, particularly one where you care about raw throughput more than cross-platform compatibility.
Can I share more than one folder from the same container?
Yes. Add another [sharename] block to smb.conf pointing at a different path, then restart smbd. There's no practical limit to how many shares one Samba instance can serve.
My container lost its IP after a reboot. What happened?
Check that you assigned a static IP during creation rather than dhcp. If you did use DHCP, either reserve that address on your router or switch the container's net0 config to a static IP with pct set 200 -net0 name=eth0,bridge=vmbr0,ip=192.168.1.50/24,gw=192.168.1.1.
Is it safe to run this as an unprivileged container?
Yes, and it's the recommended default. Samba doesn't need any of the extra kernel access a privileged container grants, so there's no reason to accept that added risk here.
Conclusion
You now have a working file share running in a container that costs you next to nothing in resources and takes seconds to snapshot or roll back. It won't replace a dedicated NAS if you need RAID arrays and hot-swap bays, but for sharing files between the machines on your desk, it does the job without extra hardware or extra cost. Next time you're tempted to email yourself a file, drag it into \\192.168.1.50\share instead.