11 KiB

Raw Blame History

mdns-termux

mDNS + Tailscale hostname resolution for Termux (Android).

Termux runs on Android's Bionic libc, which does not resolve .local names and lacks getent. This repo ships small, dependency-light helpers that fix that — without root, and without a custom system resolver.

Works on any network: LAN via multicast, off-LAN via Tailscale MagicDNS.

What's in here

Unified CLI: mdns with five subcommands (resolve, browse, publish, reverse, cache). Backed by zeroconf for RFC-complete behavior — TTL cache, IPv4 + IPv6, service discovery, probing on publish, goodbye packets on exit.

Script	Role
`mdns`	Unified CLI (zeroconf-backed). Preferred entry point.
`mdns-resolve`	Standalone stdlib fallback: works with zero dependencies.
`mdns-publish.py`	Compat shim over `mdns publish` for existing aliases.
`ssh-mdns-proxy`	SSH `ProxyCommand`: mDNS → Tailscale DNS → cached IP.
`ssh-fallback`	SSH `ProxyCommand`: Tailscale → LAN, for flaky Tailscale.
`resolve`	Bash wrapper: `mdns` → stdlib → Tailscale → cache, usable in any command.

Python library under lib/mdns_tools/ (each module < 100 lines): resolve.py, browse.py, publish.py, reverse.py, cache.py, _stdlib_resolve.py (dep-free A-record resolver).

Install

git clone https://devops.ingeniumcodex.com/andresgarcia0313/mdns-termux.git
cd mdns-termux
bash install.sh          # or --dry-run first

Then follow the printed reminders (append bashrc.snippet, set your TAILSCALE_DOMAIN, optionally merge ssh_config.example).

Usage

`mdns` CLI

mdns resolve <host> [--family v4|v6] [--timeout 1.5] [--stale] [--no-cache]
mdns reverse <ip>                            # PTR: IP -> hostname
mdns browse [--type _svc._tcp.local.] [--json] [--list-types]
mdns browse --watch [--type ...] [--no-resolve]   # live monitor (avahi-browse -a)
mdns publish [--config PATH] [--hostname NAME]     # services from JSON (foreground)
mdns publish --daemon                              # singleton daemon, re-announce on IP change
mdns publish --address <name> <ip>                 # bare A record (avahi-publish -a)
mdns status | stop                                 # inspect / stop the daemon
mdns sync-hosts [--dry-run] [--duration N]         # write discovered hosts into hosts file
mdns cache list | clear [host]

Running the publisher as a background service

mdns publish --daemon is the robust way to keep movil.local reachable:

Singleton — a PID lock (~/.cache/mdns/publisher.pid) refuses a second instance. (This is what prevents the "Termux SMB" / "Termux SMB-2" duplicates you get when several publishers race for the same name.)
Re-announce on IP change — polls the local IP; on WiFi<->data / roaming it unregisters and re-registers with the new address, so the record never goes stale.
Clean shutdown — handles SIGTERM and SIGINT, sending mDNS goodbye packets so clients drop the entry immediately instead of waiting for the TTL.

mdns publish --daemon &     # or wire it into termux-services / a boot script
mdns status                 # running (pid ...), host, ip, services, since
mdns stop                   # graceful goodbye

`sync-hosts` — native `.local` without the wrapper

Writes a managed block into the hosts file so ping, curl, kubectl, etc. resolve .local names natively (the closest you get to nss-mdns without root):

mdns sync-hosts --dry-run    # preview the block
mdns sync-hosts              # write it into $PREFIX/etc/hosts (Termux) or /etc/hosts
ping dell-latitude3400.local # now works in any tool, no `resolve` needed

Only the block between the mdns-termux managed markers is touched; the rest of the file is preserved.

Examples:

mdns browse --list-types                     # every service type on the LAN
mdns browse --type _ssh._tcp.local.          # every SSH host on the LAN
mdns resolve lenovo-ideapad                  # -> 192.168.1.106  (LAN, fast stdlib path)
mdns resolve lenovo-ideapad --family v6      # -> fe80::...      (via zeroconf)
mdns reverse 192.168.1.17                    # -> dell-latitude3400.local
mdns publish                                 # advertise services from ~/.config/mdns/services.json
mdns publish --address printer 192.168.1.50  # publish printer.local -> that IP
mdns browse --watch                          # live +/=/- events, all types
mdns cache list                              # inspect TTL-aware cache

`resolve` (bash) — for any command

resolve lenovo                       # -> 100.69.236.16
ping   $(resolve hp62a)
curl   "http://$(resolve dell):8080"
kubectl --server="https://$(resolve master):6443" get nodes

Environment knobs:

TAILSCALE_DOMAIN — defaults to tailb0bb74.ts.net. Set to your own tailnet.
MDNS_TIMEOUT — seconds waiting for multicast (default 2).
MDNS_CACHE_PATH — override cache location (default ~/.cache/mdns/hosts.json).

Shell helpers (from `config/bashrc.snippet`)

alias r='resolve'
pingr <host>              # ping -c 3 to resolved IP
curlr <host> [flags]      # curl http://<resolved-ip>
sshr  <host> [cmd...]     # ssh via resolved IP with correct HostKeyAlias
whor  <ip>                # PTR reverse: IP -> hostname
mdns-types                # list all service types advertised on LAN
mdns-ssh / mdns-smb / mdns-http   # browse specific service types
mdns-cache / mdns-forget          # inspect / clear the resolver cache

SSH by hostname (via `ProxyCommand`)

Drop config/ssh_config.example into ~/.ssh/config. Then:

ssh lenovo                # resolves via mDNS then Tailscale, connects
ssh lenovo.local          # forces mDNS-first path

Publishing this device on the LAN

Edit ~/.config/mdns/services.json (the installer seeds a template), then:

mdns publish                                          # foreground
nohup mdns publish >>~/.cache/mdns.log 2>&1 & disown  # background

The publisher registers <hostname>.local (_workstation._tcp) plus every service listed in the config. On Ctrl+C it sends proper mDNS goodbye packets. Example services.json:

{
  "hostname": "movil",
  "services": [
    {"type": "_ssh._tcp", "port": 8022, "name": "Termux SSH"},
    {"type": "_smb._tcp", "port": 4450, "name": "Termux SMB"}
  ]
}

Behavior by network

Scenario	Path	Typical latency
On home LAN	stdlib multicast → zeroconf (IPv6 or miss)	< 1 s (IPv4)
Mobile data / away	multicast times out → Tailscale MagicDNS	< 2 s
No Tailscale	all fail → TTL-aware cache → legacy flat cache	instant

Cache honors real mDNS TTL (default 30 – 3600 s) and stores IPv4 + IPv6 separately. mdns resolve --stale <host> accepts expired entries as a last-resort fallback.

RFC coverage (what's implemented)

Feature	Status	Notes
A / AAAA hostname resolution	✓	stdlib for A, zeroconf for AAAA
PTR reverse lookup	✓	stdlib multicast, IPv4 + IPv6
DNS-SD service browsing	✓	`mdns browse`, all types or one
Live service monitor	✓	`mdns browse --watch` (like avahi-browse)
Publisher (hostname + services)	✓	via `zeroconf`, with probing + goodbye
Bare hostname->IP publish	✓	`mdns publish --address` (avahi-publish -a)
Name-conflict handling	✓	RFC 6762 probe + auto-rename
Multicast group membership	✓	`IP_ADD_MEMBERSHIP` on all sockets
Retries with backoff	✓	2 attempts, split timeout
TTL-honoring cache	✓	JSON at `~/.cache/mdns/hosts.json`
Publisher daemon (singleton)	✓	PID lock, re-announce on IP change
Clean goodbye on shutdown	✓	SIGTERM + SIGINT handled
Hosts-file sync (nss-mdns-lite)	✓	`mdns sync-hosts`, managed block
Legacy unicast queries	—	Not implemented (rarely needed)
Known-answer suppression	—	zeroconf handles internally

Tests

Parser/logic tests run offline (no network), via pytest:

pip install -e ".[test]"   # or: pip install pytest
pytest                     # 20 tests: query build/parse, address pick, cache TTL, reverse, hosts block

Interoperability (Avahi / Bonjour)

Because publishing goes through zeroconf (a full RFC 6762 / 6763 implementation), anything you advertise is visible to standard mDNS stacks — no special client needed on the other end.

Verified on a real LAN:

Termux → Avahi (Linux): with mdns publish running on the phone, a Linux box with nss-mdns resolved movil.local and pinged it, with no extra config:
```
$ getent hosts movil.local
192.168.1.112   movil.local
$ ping movil.local            # 64 bytes ... time=3.84 ms
```
Avahi → Termux: mdns browse on the phone sees services published by Avahi/Bonjour hosts (SMB, SSH, _workstation, Chromecast, AirPlay, …).

So a Mac (Bonjour), a Linux box (Avahi), or a Windows machine (Bonjour Print Services) will all discover and resolve what this tool publishes, and vice versa.

Gotchas found the hard way

getent doesn't exist on Termux. Scripts that shell out to it silently fail. This repo uses python -c "import socket; socket.gethostbyname(...)" as the portable fallback on Bionic.
Shebang matters. #!/data/data/com.termux/files/usr/bin/bash is required for declare -A. A stray backslash (#\!) makes the kernel fall through to sh, which rejects bash-only syntax with Syntax error: "(" unexpected.
mDNS off-LAN is a no-op. Multicast (224.0.0.251) does not cross networks. Over mobile data, only Tailscale resolves.
zeroconf is not pkg-managed. After restoring Termux from a tar backup, re-run pip install zeroconf or mdns-publish.py will silently die with ModuleNotFoundError.
Silent failures are the enemy. The .bashrc snippet deliberately logs to ~/.cache/mdns.log instead of /dev/null. Keep it that way.

Tailscale on Termux

Tailscale runs as the Android app, not as a Termux CLI — tailscale up inside a shell won't work. The app provides MagicDNS for *.<your-tailnet>.ts.net, which Bionic-libc resolves fine (it's just a regular DNS lookup).

claude-code-termux — Claude Code CLI setup for Termux. Uses this repo for SSH/host resolution.

License

MIT — see LICENSE.

11 KiB Raw Blame History Unescape Escape