initial commit

2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
@@ -0,0 +1,119 @@
+---
+name: samba-nas
+description: "Set up Samba/CIFS network shares on a self-hosted Linux server — install, configure, test, and connect from Windows/macOS/Linux clients."
+version: 1.1.0
+category: self-hosting
+tags: [samba, nas, network-storage, smb, cifs, file-sharing, homelab]
+platforms: [linux, ubuntu, debian]
+---
+
+# Samba NAS (Network File Shares)
+
+Set up network-accessible file shares on a self-hosted Linux server using Samba (SMB/CIFS). Covers installation, configuration, testing, and client connectivity.
+
+## Quick Setup
+
+### 1. Install
+
+```bash
+sudo apt update && sudo apt install -y samba smbclient
+```
+
+### 2. Configure /etc/samba/smb.conf
+
+**Guest access (trusted LAN)** — no password, full read/write:
+
+```ini
+[global]
+workgroup = WORKGROUP
+server string = <hostname>
+netbios name = <hostname>
+security = user
+map to guest = Bad User
+guest account = nobody
+server min protocol = SMB2
+client min protocol = SMB2
+
+[share-name]
+path = /mnt/<path>
+browseable = yes
+read only = no
+guest ok = yes
+force user = <username>
+create mask = 0777
+directory mask = 0777
+```
+
+**Key directives:**
+- `map to guest = Bad User` — anonymous connections get guest access instead of being rejected
+- `force user = <username>` — all file operations run as this user (avoids permission mismatches with pre-existing files)
+- `create mask / directory mask = 0777` — full rwx for everyone (safe on trusted LAN only)
+- `server min protocol = SMB2` — disables the ancient SMB1 protocol (security)
+
+### 3. Start
+
+```bash
+sudo systemctl restart smbd
+sudo systemctl enable smbd
+```
+
+### 4. Test locally
+
+```bash
+smbclient -L //localhost -N
+```
+Should list all configured shares. Then test write:
+
+```bash
+smbclient //localhost/<share> -N -c "put /etc/hostname test.txt; ls; rm test.txt"
+```
+
+### 5. Check firewall
+
+If `ufw` is active:
+
+```bash
+sudo ufw allow samba
+```
+
+## Client Connection Guide
+
+| OS | How to connect |
+|----|---------------|
+| **Windows** | File Explorer → `\\<server-ip>` or `\\<hostname>` |
+| **macOS** | Finder → Go → Connect to Server → `smb://<server-ip>` |
+| **Linux** | File manager → `smb://<server-ip>/` or mount via `mount -t cifs` |
+
+## Password-Protected (vs Guest)
+
+If guest access is not desired, replace the share config with:
+
+```ini
+[share-name]
+path = /mnt/<path>
+browseable = yes
+read only = no
+valid users = <username>
+```
+
+Then set a Samba password:
+
+```bash
+sudo smbpasswd -a <username>
+```
+
+Note: this creates a **separate Samba password** — it does not need to match the system login password.
+
+## Pitfalls
+
+- **`/usr/share/cockpit/` is NOT for Samba** — common confusion. Samba config is in `/etc/samba/smb.conf`, not Cockpit package directories.
+- **NTFS/exFAT drives** — already mounted with `uid=1000,gid=1000,umask=000`, so guest + force user works fine. For ext4 drives, verify the mount point has world-readable/writable permissions.
+- **SMB1 disabled warning** on `smbclient -L` is normal — ignore it. This means the server correctly requires SMB2+.
+- **Firewall on other machines**: Windows/macOS clients may need network discovery enabled to see the server in the file browser. Connecting directly via IP always works.
+- **CGNAT**: These shares are LAN-only. For external access, use a VPN (Tailscale, WireGuard) — never expose SMB directly to the internet.
+- **Restart after config changes**: Always `sudo systemctl restart smbd` after editing smb.conf. No reload — restart.
+- **Testing checklist after changes**:
+  1. `systemctl is-active smbd` — service running?
+  2. `smbclient -L //localhost -N` — shares visible?
+  3. `smbclient //localhost/<share> -N -c "ls"` — contents readable?
+  4. `smbclient //localhost/<share> -N -c "put /etc/hostname _test; rm _test"` — writable?