claude-code-termux/docs/03-samba.md

# 04 — Samba server on Termux (port 4450)

Optional but useful: expose a few folders over SMB so other devices on the LAN can read/write files without ADB.

## Why port 4450

Ports below 1024 require root. Samba on Termux runs unprivileged, so we use a high port (`4450`) and configure clients to point at it explicitly.

```
\\<device-ip>:4450
```

Most file managers accept `smb://<ip>:4450/`.

## Install

```bash
pkg install -y samba
mkdir -p ~/.config/samba/lock ~/.config/samba/private
```

## Configuration

Copy `config/smb.conf.example` to `~/.config/samba/smb.conf` and edit the share paths to match your device. Then add a Samba user:

```bash
smbpasswd -a YOUR_USER
```

This creates `~/.config/samba/private/passdb.tdb`.

## Start / stop

```bash
smbd -D -s ~/.config/samba/smb.conf 2>>~/.config/samba/samba-startup.log
pkill smbd
```

The aliases in `config/bashrc.snippet` (`smb-start`, `smb-stop`, `smb-restart`, `smb-status`, `smb-log`) wrap these.

## Critical gotcha — `msg.lock` permissions after restore

If you restore `~/.config/samba/` from a `tar` backup, the `lock/msg.lock` directory ends up with mode `0700` because `tar` preserves the source attributes. `smbd` requires `0755` on this directory and refuses to start with:

```
invalid permissions on directory '.../msg.lock': has 0700 should be 0755
```

**Fix:**

```bash
chmod 0755 ~/.config/samba/lock/msg.lock
```

This must be re-run after every restore from a backup that includes the samba lock dir.

## Connecting from another machine

```bash
# Linux
smbclient -L //<device-ip> -p 4450 -U YOUR_USER
mount -t cifs //<device-ip>/Home /mnt -o port=4450,username=YOUR_USER

# Windows: \\<device-ip>:4450  in Explorer

# macOS: Finder → Go → Connect to Server → smb://<device-ip>:4450
```

## Discovery via mDNS

If you also install the companion repo [**mdns-termux**](https://devops.ingeniumcodex.com/andresgarcia0313/mdns-termux) and run its `mdns-publish.py`, the device shows up as `movil.local` and SMB clients can use that name directly.

## Don't bind to `0.0.0.0` if you don't need to

The default `smb.conf` example binds to all interfaces. If the device roams across hostile WiFi networks, restrict `interfaces =` and `bind interfaces only = yes` to the LAN interface (`wlan0` on most devices).