admin/Linux_post_install
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
35eb90a58b4cf00e5c3e58486117c05be6a18d1b
Linux_post_install/DOC/howto/share.md
T
Your Name 35eb90a58b
gates / consistency-and-conventions (push) Successful in 22s
Details
feat: share clients — t=type manual mountpoint (existing path without create) 
User report: smb-client/nfs-client mountpoint step could only auto-suggest
candidates, or create a fresh dir behind a hidden 'n=new' key — no way to
type an arbitrary existing path as the mountpoint, so the manual option
was effectively invisible (candidates from /media etc. always populated
the picker, hiding the typing path entirely). Designer framing: capability
gap + discoverability gap; backend already handled arbitrary paths (CLI
cmd_mount + ensure_mountpoint), only the interactive menu blocked it.

Change (identical in bin/pos-share-smb-client and bin/pos-share-nfs-client):
- pick_mountpoint hint 'n=new' -> 't=type'; key arm n -> t
- ask_new_mountpoint generalized to ask_mountpoint: an existing
  directory is now used AS-IS (no create, no confirm); a non-existent
  path keeps the 'Create mountpoint?' confirm + sudo mkdir flow; existing
  non-directory rejected ('has a file there'); shape checks and system-path
  refusal unchanged; stream contract (display->stderr, path->stdout) kept
- menu_ask_mountpoint empty-candidate fall-through now routes through the
  same ask_mountpoint validator (single source of truth)

Docs: DOC/howto/share.md NFS+SMB mountpoint sections updated from n=new to
t=type and describe existing-path-without-create behavior.

Scoped to the two client files + howto doc; persistence/automount units,
unmount/remove flows, cmd_* CLIs, share_folder_candidates, and
lib/menu-lib.sh untouched.

Verified: 9-scenario smoke matrix x2 files (~19 assertions each: existing
dir as-is, new-dir confirm+create, decline, relative/trailing-slash/system/
empty rejections, non-dir reject, mkdir-fail), make gen idempotent, make
check OK, make lint 0 FAIL/0 WARN, make test 17 files / 299 checks green,
bash -n clean, git diff --check clean. Designer ACCEPT framing+spec;
Reviewer ACCEPT after doc fix.
2026-09-07 08:08:02 -04:00

15 KiB
Raw Blame History

How-To: pos share

Share files and devices over the network: USB devices via the USB Redirector 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)

pos share usb server — USB over network

Share local USB devices over the network with the USB Redirector server.

Requires usbsrv (the USB Redirector server binary) — a manual install from incentivespro.com, not an apt package. Point to it and it's picked up by command -v usbsrv; install.sh copies any precompiled x64_bin//arm64_bin/ binaries to /usr/local/bin.

pos share usb server --ls                # host devices + connected clients
pos share usb server --ls-shared         # only shared/in-use devices
pos share usb server --share             # interactive picker
pos share usb server --share 0-1 3       # share device 0-1 to client 3
pos share usb server --unshare 0-1       # stop sharing a device
pos share usb server --auto-share on|off # auto-share new devices
pos share usb server --callback 192.168.1.5:8080   # callback connection to a client
pos share usb server --close-callback 192.168.1.5:8080   # close it
pos share usb server --auto-connect on|off [client]      # remote auto-connect
pos share usb server --disconnect 0-1     # disconnect a device from clients
pos share usb server --disconnect all
pos share usb server --nickname 0-1 myprinter   # friendly name (empty = remove)
pos share usb server --timeout 0-1 300    # auto-unshare after inactivity (0=off)
pos share usb server --port 32032         # server TCP port (restart to apply)
pos share usb server --info               # server info
pos share usb server --version            # server version

Subcommands that need input (e.g. --share) prompt interactively when args are omitted.

Recipes:

  • Attach a device and connect to one client, in one step: 
    pos share usb server --ls                          # note device + client IDs
pos share usb server --share 0-1 3
  • Keep the USB printer always available: --auto-share on + a nickname (--nickname 0-1 printer) so clients see a friendly name.
  • Dedicated USB-over-network box: set --port once, then clients connect to that port.

Interactive menu: run pos share usb server with no args for a menu (list / share / unshare / auto-share / disconnect …). The share flow lists devices and clients from the server as pickers — no IDs to memorize; if the server listing can't be read, it prints the raw output and falls back to manual ID entry.

Troubleshooting:

  • usbsrv: command not found → the binary isn't installed; get it from incentivespro.com and drop it in x64_bin/ (or arm64_bin/) then re-run ./install.sh, or sudo install -m 755 usbsrv /usr/local/bin/.
  • Device shared but client can't see it → check the client connects to the right host:port (see --info/--port); verify a callback/auto-connect is not required for your topology.
  • Nickname/timeout don't apply → usbsrv persists them on the server; restart the server after --port changes.

pos share nfs server — NFS kernel server

Requires nfs-kernel-server (in preinstall.sh PACKAGES). Writes to /etc/exports and reloads via exportfs -ra; mutating commands announce via notify_send.

pos share nfs server status                    # server active? + current exports
pos share nfs server share /mnt/hdd            # export (generic, warns)
pos share nfs server share /mnt/hdd '100.64.0.0/10(rw,sync,no_subtree_check)'
pos share nfs server list                      # exportfs -v
pos share nfs server unshare /mnt/hdd          # remove the export
pos share nfs server reload                    # re-apply /etc/exports after hand edits
pos share nfs server enable                    # start + boot-persist the server
pos share nfs server disable

share <path> [client] is idempotent: an existing line for the same path is replaced. With no client it uses *(rw,sync,no_subtree_check) and warns you to restrict it — print the restricted form:

  • Tailscale (CGNAT): pos share nfs server share /mnt/hdd '100.64.0.0/10(rw,sync,no_subtree_check)'
  • WireGuard: pos share nfs server share /mnt/hdd '10.10.0.0/24(rw,sync,no_subtree_check)'
  • LAN: pos share nfs server share /mnt/backups '192.168.1.0/24(ro,sync,no_subtree_check)'

Recipes:

  • Share the media drive to the tailnet: 
    pos share nfs server share /mnt/hdd '100.64.0.0/10(rw,sync,no_subtree_check)'
pos share nfs server enable
  • Read-only backups to a LAN host: use (ro,sync,no_subtree_check) and only enable the server where it's needed.

Interactive menu: run pos share nfs server with no args for a menu (share / unshare / list / reload / enable / disable / status). The share flow offers mounted folders as a picker and client-spec presets (open, WireGuard, LAN, single IP) so you don't hand-type export specs; an inactive nfs-server service or a UFW conflict is offered as a one-key fix.

Troubleshooting:

  • "exportfs not found" → nfs-kernel-server isn't installed; sudo apt install nfs-kernel-server
  • Client sees "mount.nfs: Permission denied" → your /etc/exports client rule doesn't cover the client's IP (check with pos share nfs server list); use showmount -e <server> on the client to see what's exported
  • After editing /etc/exports by hand, run pos share nfs server reload
  • NFS is blocked → allow the ports in pos system firewall (or ufw)
  • Changes to /etc/exports are root-required → the tool uses sudo

pos share nfs client — mount NFS shares

Requires nfs-common (in preinstall.sh PACKAGES).

pos share nfs client mount <server:export> <local-dir>   # one-shot (mkdir -p first)
pos share nfs client persist <server:export> <local-dir> # persistent systemd mount
pos share nfs client list                                # active NFS mounts
pos share nfs client unmount <local-dir>
pos share nfs client unpersist <local-dir>               # remove the systemd unit

Persistent mounts use systemd, not fstab. persist writes a /etc/systemd/system/<mnt-nfs-name>.mount unit ordered after network-online.target, so the share is mounted only once all interfaces are up — a down/unreachable NFS server can't break boot (with fstab it could). enable --now mounts it immediately too.

Recipes:

  • Mount the server's media share and keep it across reboots: 
    pos share nfs client persist 100.100.100.1:/mnt/hdd /mnt/nfs/media
pos share nfs client list
  • One-off mount (no persistence): pos share nfs client mount 10.0.0.5:/srv/data /mnt/data

Interactive menu: run pos share nfs client with no args for a menu (mount / persist / unmount / unpersist / list). Mountpoints are offered from existing mount-layout candidates with manual entry as fallback — the picker also accepts the server-side export path as a "(as on server)" pick when it differs from your local layout, and t=type lets you type an absolute mountpoint — an existing directory is used as-is, a non-existent path creates it in place (y/N confirmed; a failure just returns to the picker). Unmount lists the active NFS mounts as <mountpoint> ← <source> picks and asks for confirmation before unmounting (with a typed fallback when nothing is mounted); unmount and unpersist tolerate already-absent targets instead of erroring.

Troubleshooting:

  • "mount.nfs not found" → nfs-common isn't installed; sudo apt install nfs-common
  • Mount hangs → check the server export (pos share nfs server list on the server) and that the client IP is allowed; showmount -e <server> lists exports; NFS timeouts take ~2min by default, add timeo=50,retrans=2 via the unit if needed
  • Persistent mount fails at boot when the server is off → intended: the unit waits for network-online and fails cleanly, and boot continues (unlike fstab); pos share nfs client unpersist removes it

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.

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. share --users u1,u2 checks the list against the Samba passdb and warns about any missing account (pointing at adduser) — plus it walks the path's parent dirs and warns when one lacks other:+x traversal (e.g. a 700 home dir blocks Samba clients with NT_STATUS_ACCESS_DENIED; fix with chmod o+x). Both are warnings only — the share is still written.

Recipes:

  • Share the media drive to the tailnet (users bob + alice): 
    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.

Interactive menu: run pos share smb server with no args for a menu (share / unshare / list / users / reload / enable / disable / status). The share flow offers mounted folders as a picker and walks through read-only / guest / valid-users confirms; a UFW conflict is offered as a one-key fix.

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)
  • NT_STATUS_ACCESS_DENIED → two causes, share warns about both at share time: the user is not in the Samba passdb (pos share smb-server adduser <user>), or a parent dir of the share path lacks other:+x traversal (chmod o+x <dir> — typical for 700 home dirs)
  • 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).

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 + persistent 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 (and a matching <mnt-name>.automount unit, both systemd-escaped) with _netdev: the automount is enabled and armed, and 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: 
    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 under "Active mounts" until accessed → intended (x-systemd.automount); pos share smb client list now also lists persistent units under "Persistent (automount)", so the configured shares are visible even before their first access

Interactive menu: run pos share smb client with no args for a menu (enumerate / mount / persist / unmount / unpersist / list). Enter the server, an empty user tries guest enumeration first (with an auth retry on denial), then shares and mountpoints are offered as pickers with manual fallback — the account you authenticated with is reused for the mount. The mountpoint picker accepts t=type to type an absolute mountpoint — an existing directory is used as-is, a non-existent path creates it in place (y/N confirmed; a failure just returns to the picker); when the server is this machine, its underlying share directory is offered as a "(as on server)" pick too. Unmount lists the active CIFS mounts as <mountpoint> ← <source> picks and asks for confirmation before unmounting (typed fallback when nothing is mounted).

Related

Reference in New Issue View Git Blame Copy Permalink