admin/Linux_post_install
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: pos share smb server + smb client — Samba share tools (samba/cifs-utils deps, systemd automount units)

Browse Source
This commit is contained in:
Your Name
2026-08-11 16:15:02 -04:00
parent 384ed4bf90
commit a4849616d9
10 changed files with 545 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DOC/AGENT_Context_Project.md
+21 -14
View File
@@ -10,19 +10,19 @@
<!-- GEN:START docmap -->
| ## 1. Project Overview | 28–43 |
| ## 2. Directory Structure | 44–186 |
| ## 3. Installation Flow | 187–239 |
| ## 4. The `pos` CLI System | 240–306 |
| ## 5. Shared Library — `lib/common.sh` | 307–338 |
| ## 6. Docker Compose / ScaleTail | 339–381 |
| ## 7. Optional Apps (`apps/`) | 382–411 |
| ## 8. Entertainment Module | 412–425 |
| ## 9. Systemd Services | 426–438 |
| ## 10. Configuration Files | 439–465 |
| ## 11. Coding Conventions | 466–498 |
| ## 12. Development Workflow | 499–551 |
| ## 13. Key File Quick Reference | 552–605 |
| ## 14. Common Tasks for Agents | 606–632 |
| ## 2. Directory Structure | 44–188 |
| ## 3. Installation Flow | 189–241 |
| ## 4. The `pos` CLI System | 242–310 |
| ## 5. Shared Library — `lib/common.sh` | 311–342 |
| ## 6. Docker Compose / ScaleTail | 343–385 |
| ## 7. Optional Apps (`apps/`) | 386–415 |
| ## 8. Entertainment Module | 416–429 |
| ## 9. Systemd Services | 430–442 |
| ## 10. Configuration Files | 443–469 |
| ## 11. Coding Conventions | 470–502 |
| ## 12. Development Workflow | 503–555 |
| ## 13. Key File Quick Reference | 556–611 |
| ## 14. Common Tasks for Agents | 612–639 |
<!-- GEN:END docmap -->
## 1. Project Overview
@@ -81,6 +81,8 @@ Linux_post_install/
│ ├── pos-network-scan # Parallel ping sweep of CIDR
│ ├── pos-share-nfs-client # Mount NFS shares (ephemeral or persistent systemd mount units)
│ ├── pos-share-nfs-server # Manage the NFS kernel server (status, share/unshare exports, enable/disable)
│ ├── pos-share-smb-client # Mount SMB/CIFS shares (ephemeral or persistent systemd mount units)
│ ├── pos-share-smb-server # Manage the Samba server (status, share/unshare exports, users, enable/disable)
│ ├── pos-share-usb-server # USB Redirector server control (--ls, --share; prompts when args omitted)
│ ├── pos-ssh-load-keys # Load all SSH keys into the agent
│ ├── pos-system-backup # Encrypted (AES-256) folder snapshots (tar + gpg)
@@ -279,6 +281,8 @@ All non-interactive `pos` commands log output to `~/.local/share/linux_post_inst
| network | scan | `pos-network-scan` | Parallel ping sweep of CIDR |
| share | nfs-client | `pos-share-nfs-client` | Mount NFS shares (ephemeral or persistent systemd mount units) |
| share | nfs-server | `pos-share-nfs-server` | Manage the NFS kernel server (status, share/unshare exports, enable/disable) |
| share | smb-client | `pos-share-smb-client` | Mount SMB/CIFS shares (ephemeral or persistent systemd mount units) |
| share | smb-server | `pos-share-smb-server` | Manage the Samba server (status, share/unshare exports, users, enable/disable) |
| share | usb-server | `pos-share-usb-server` | USB Redirector server control (--ls, --share; prompts when args omitted) |
| ssh | load-keys | `pos-ssh-load-keys` | Load all SSH keys into the agent |
| system | backup | `pos-system-backup` | Encrypted (AES-256) folder snapshots (tar + gpg) |
@@ -566,7 +570,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
| `bin/flag-clear` | 21 | Unset a flag |
| `features/autostart.sh` | 14 | Boot-time feature (moved from `bin/`, flag-gated service) |
<!-- GEN:START filetable -->
| `bin/pos` | 286 | CLI dispatcher with smart arg matching + logging + category help |
| `bin/pos` | 290 | CLI dispatcher with smart arg matching + logging + category help |
| `bin/pos-ai-gemini` | 311 | Chat with Google Gemini (ask, chat, models, sessions) |
| `bin/pos-communication-matrix-listener` | 565 | Matrix listener: map /command → bash, run them on room messages |
| `bin/pos-communication-matrix-sender` | 224 | Send messages to a Matrix room via the client-server API (send, test, login) |
@@ -590,6 +594,8 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
| `bin/pos-network-scan` | 271 | Parallel ping sweep of CIDR |
| `bin/pos-share-nfs-client` | 138 | Mount NFS shares (ephemeral or persistent systemd mount units) |
| `bin/pos-share-nfs-server` | 134 | Manage the NFS kernel server (status, share/unshare exports, enable/disable) |
| `bin/pos-share-smb-client` | 183 | Mount SMB/CIFS shares (ephemeral or persistent systemd mount units) |
| `bin/pos-share-smb-server` | 226 | Manage the Samba server (status, share/unshare exports, users, enable/disable) |
| `bin/pos-share-usb-server` | 218 | USB Redirector server control (--ls, --share; prompts when args omitted) |
| `bin/pos-ssh-load-keys` | 31 | Load all SSH keys into the agent |
| `bin/pos-system-backup` | 126 | Encrypted (AES-256) folder snapshots (tar + gpg) |
@@ -624,6 +630,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
| Modify vbox (Docker VM) logic | Edit `bin/pos-docker-vbox` |
| Modify USB forwarding logic | Edit `bin/pos-share-usb-server` |
| Modify NFS share logic | Edit `bin/pos-share-nfs-server` / `bin/pos-share-nfs-client` |
| Modify SMB share logic | Edit `bin/pos-share-smb-server` / `bin/pos-share-smb-client` |
| Modify AI/Gemini logic | Edit `bin/pos-ai-gemini` (config scope `ai` via `pos config ai`; `AI_GEMINI_API_KEY`/`AI_GEMINI_MODEL` in `~/.config/linux_post_install/ai.env`) |
| Modify UFW/firewall logic | Edit `bin/pos-system-firewall` |
| Modify pos logging | Edit log setup in `bin/pos` |
DOC/HOWTO.md
+1 -1
View File
@@ -16,7 +16,7 @@ authoritative one-line reference (every command + flag), see
| `pos system` | Backups, firewall, health dashboard | [system](howto/system.md) |
| `pos system event-trigger` | Threshold-rule monitors that alert on crossing | [event-trigger](howto/event-trigger.md) |
| `pos ssh` | Load keys into the agent | [ssh](howto/ssh.md) |
| `pos share` | Share USB devices & filesystems over the network (USB, NFS) | [share](howto/share.md) |
| `pos share` | Share USB devices & filesystems over the network (USB, NFS, SMB) | [share](howto/share.md) |
| `pos communication` | Send Telegram/Matrix messages & alerts, /command listeners | [communication](howto/communication.md) |
| `pos entertainment` | Scheduled auto-messages from public APIs | [entertainment](howto/entertainment.md) |
DOC/POS.md
+3 -1
View File
@@ -197,7 +197,7 @@ The standalone `vbox` command still works and forwards to `pos docker vbox` (see
### share
Share files and devices over the network (USB over network, NFS; SMB planned).
Share files and devices over the network (USB over network, NFS, SMB/Samba).
**File:** `bin/pos-share-usb-server`
**Purpose:** control the USB Redirector server (`usbsrv`) — share local USB devices over the network and manage connected clients. Requires `usbsrv` (manual install from incentivespro.com — not in `PACKAGES`).
@@ -224,6 +224,8 @@ Subcommands that need input prompt interactively when args are omitted.
|---------|------|---------|---------------|
| `pos share nfs server <cmd>` | `bin/pos-share-nfs-server` | Manage the NFS kernel server: `status`, `share <path> [client]`, `unshare <path>`, `list`, `reload`, `enable`, `disable` | Requires `nfs-kernel-server` (added to `preinstall.sh` PACKAGES). Exports live in `/etc/exports`; `share` is idempotent (replaces any existing line for the path) and runs `exportfs -ra`. Default client `*(rw,sync,no_subtree_check)` — the tool warns you to restrict it; help prints Tailscale CGNAT (`100.64.0.0/10`), WireGuard (`10.10.0.0/24`) and LAN examples. Mutating commands announce via `lib/notify.sh` |
| `pos share nfs client <cmd>` | `bin/pos-share-nfs-client` | Mount and manage NFS shares: `mount <server:export> <local-dir>`, `unmount <local-dir>`, `list`, `persist <server:export> <local-dir>`, `unpersist <local-dir>` | Requires `nfs-common` (added to `preinstall.sh` PACKAGES). `persist` writes a systemd `.mount` unit (`systemd-escape --path --suffix=mount`) with `After=network-online.target` / `Wants=network-online.target` — mounts only once all interfaces are up, no fstab edits to break boot — then `daemon-reload` + `enable --now`. `unpersist` stops/disables/removes the unit. `mount`/`persist` announce via `lib/notify.sh` |
| `pos share smb server <cmd>` | `bin/pos-share-smb-server` | Manage the Samba server: `status`, `share <path> [name] [--read-only|--guest|--users u1,u2]`, `unshare <name>`, `list`, `adduser <user>`, `deluser <user>`, `reload`, `enable`, `disable` | Requires `samba` (added to `preinstall.sh` PACKAGES). Shares are idempotent marker blocks (`# >>> pos-managed share: <name>` … `# <<< end pos-managed share`) in `/etc/samba/smb.conf` — hand edits outside the markers survive; `share` validates with `testparm` before applying and hot-reloads via `smbcontrol smbd reload-config`. Defaults rw + browsable; warns when unrestricted (guest or no `valid users`). `adduser`/`deluser` manage Samba accounts via `smbpasswd`. Mutating commands announce via `lib/notify.sh` |
| `pos share smb client <cmd>` | `bin/pos-share-smb-client` | Mount and manage SMB/CIFS shares: `mount <//server/share> <local-dir> [user]`, `unmount <local-dir>`, `list`, `persist <//server/share> <local-dir> [user]`, `unpersist <local-dir>` | Requires `cifs-utils` (added to `preinstall.sh` PACKAGES). With a user you are prompted for the Samba password — one-shot mounts use a throwaway chmod-600 credentials file, `persist` keeps one at `/etc/samba/credentials/<name>` (chmod 600). `persist` writes a systemd `.mount` unit (`systemd-escape --path --suffix=mount`) with `x-systemd.automount` + `_netdev` — mounts on first access, never blocks boot — then `daemon-reload` + `enable --now`. `unpersist` stops/disables/removes the unit + credentials. `mount`/`persist` announce via `lib/notify.sh` |
### communication
DOC/howto/share.md
+102 -1
View File
@@ -1,13 +1,15 @@
# How-To: `pos share`
Share files and devices over the network: USB devices via the USB Redirector
server, filesystems via NFS (SMB planned). Tools: `usb`, `nfs`.
server, filesystems via NFS and SMB/Samba. Tools: `usb`, `nfs`, `smb`.
| Tool | What it does |
|------|--------------|
| `pos share usb server` | Control `usbsrv`: share USB devices, manage clients, callbacks, nicknames |
| `pos share nfs server` | Manage the NFS kernel server (exports, enable/disable) |
| `pos share nfs client` | Mount NFS shares (ephemeral or persistent systemd units) |
| `pos share smb server` | Manage the Samba server (shares, users, enable/disable) |
| `pos share smb client` | Mount SMB/CIFS shares (ephemeral or persistent systemd units) |
---
@@ -149,6 +151,105 @@ up — a down/unreachable NFS server can't break boot (with fstab it could).
---
## `pos share smb server` — Samba server
Requires `samba` (in `preinstall.sh` PACKAGES). Writes idempotent share blocks
to `/etc/samba/smb.conf` (between `# >>> pos-managed share: <name>` /
`# <<< end pos-managed share` markers — anything outside the markers survives),
validates with `testparm`, and hot-reloads via `smbcontrol smbd reload-config`.
Mutating commands announce via `notify_send`.
```bash
pos share smb server status # smbd active? + shares + users
pos share smb server share /mnt/hdd media # share (default name: basename)
pos share smb server share /mnt/hdd media --users bob,alice # restrict to Samba users
pos share smb server share /mnt/hdd/backups --read-only # read-only
pos share smb server share /mnt/public --guest # guest access (warns)
pos share smb server list # current shares
pos share smb server unshare media # remove a share
pos share smb server adduser bob # create a Samba user (prompts)
pos share smb server deluser bob # remove a Samba user
pos share smb server reload # validate + reload after hand edits
pos share smb server enable / disable # start + boot-persist smbd / stop it
```
New shares default to read-write + browsable. `--guest` and shares without
`--users` both **warn** — any Samba account (or any network user with guest)
can then access them; print the restricted form with `--users`.
SMB shares need Samba accounts, not just system users: `adduser <user>`
(prompts for the password via `smbpasswd -a`) after the system user exists.
**Recipes:**
- **Share the media drive to the tailnet (users bob + alice):**
```bash
sudo adduser bob # system user first
pos share smb server adduser bob # then a Samba password
pos share smb server share /mnt/hdd media --users bob,alice
pos share smb server enable
```
- **Public read-only download share:** `pos share smb server share /srv/pub pub --read-only --guest`
- **Change a share's access later:** re-run `share` with the same name — the
block is replaced, not duplicated.
**Troubleshooting:**
- "smbd not found" → `samba` isn't installed; `sudo apt install samba`
- Windows can't connect → check the client is in `--users` / has a Samba
password (`adduser`), and that `smbd` is running (`status`)
- `valid users` users can't log in → their Samba password differs from the
system one; re-run `pos share smb server adduser <user>`
- After editing `/etc/samba/smb.conf` by hand, run `pos share smb server reload`
- SMB is blocked → allow Samba in `pos system firewall` (or `ufw allow samba`)
---
## `pos share smb client` — mount SMB/CIFS shares
Requires `cifs-utils` (in `preinstall.sh` PACKAGES).
```bash
pos share smb client mount //100.100.100.1/media /mnt/smb/media # guest
pos share smb client mount //100.100.100.1/media /mnt/smb/media bob # prompts for password
pos share smb client persist //100.100.100.1/media /mnt/smb/media bob # persistent (systemd)
pos share smb client list # active SMB mounts
pos share smb client unmount /mnt/smb/media
pos share smb client unpersist /mnt/smb/media # remove the unit
```
With no user, a **guest** mount is attempted (only works if the server allows
guest access). With a user you are prompted for the Samba password: one-shot
mounts use a throwaway chmod-600 credentials file, `persist` keeps one at
`/etc/samba/credentials/<name>` (chmod 600) and references it from the unit.
**Persistent mounts use systemd, not fstab.** `persist` writes a
`/etc/systemd/system/<mnt-name>.mount` unit (`systemd-escape`) with
`x-systemd.automount` + `_netdev`: the share is mounted **on first access**
instead of at boot, so an unreachable SMB server can never hang boot (with
fstab it could). `enable --now` arms the automount immediately.
**Recipes:**
- **Mount the server's media share and keep it across reboots:**
```bash
pos share smb client persist //100.100.100.1/media /mnt/smb/media bob
```
- **One-off guest mount (no persistence):**
`pos share smb client mount //10.0.0.5/pub /mnt/pub`
- **Check what a server shares before mounting:** `smbclient -L //10.0.0.5 -N`
(or with `-U bob`)
**Troubleshooting:**
- "mount.cifs not found" → `cifs-utils` isn't installed; `sudo apt install cifs-utils`
- Mount fails with `Permission denied` / `NT_STATUS_LOGON_FAILURE` → wrong Samba
user/password; verify the account with `pos share smb server list` on the
server and re-run with the right user
- Mount fails with `NT_STATUS_ACCESS_DENIED` on a guest mount → the server
share has no `guest ok`; use a user or add `--guest` on the server
- Persistent mount doesn't appear until accessed → intended (`x-systemd.automount`);
`pos share smb client list` only shows actively mounted shares, access the
directory to trigger the mount
---
## Related
- Reference: [DOC/POS.md → share](../POS.md)