From 4d5ce8e915ed167998e0c0decb87c47a03720382 Mon Sep 17 00:00:00 2001 From: Kaloyan Danchev Date: Tue, 3 Nov 2026 23:56:04 +0200 Subject: [PATCH] docs: put hc on PATH for non-desktop Herdr clients hc connect speaks the protocol over stdin/stdout, so clients attach with ssh hc connect. That failed with "hc: command not found": the binary installs to /root/.local/bin/herdr-core, which is neither on PATH in a non-interactive shell nor named hc. The desktop app was unaffected since it calls the absolute path it installed. Symlinks both names into /usr/local/bin, restored by the go script, and records the connection details a mobile client or app builder needs. Co-Authored-By: Claude Opus 5 --- docs/14-HERDR-REMOTE-MACHINES.md | 41 +++++++++++++++++++++++++++++--- docs/CHANGELOG.md | 1 + 2 files changed, 39 insertions(+), 3 deletions(-) diff --git a/docs/14-HERDR-REMOTE-MACHINES.md b/docs/14-HERDR-REMOTE-MACHINES.md index 6ad83f9..62747bd 100644 --- a/docs/14-HERDR-REMOTE-MACHINES.md +++ b/docs/14-HERDR-REMOTE-MACHINES.md @@ -106,6 +106,7 @@ on reboot and is restored by `/boot/config/go`: | Path | Lost on reboot | Restored by | |------|----------------|-------------| | `/root/.local/bin/herdr-core` | yes | `install -m 755` from `/boot/config/herdr/herdr-core` | +| `/usr/local/bin/hc`, `/usr/local/bin/herdr-core` | yes | `ln -sf` to the restored binary | | `/var/lib/elogind/linger/root` | yes | `loginctl enable-linger root` | | `/run/user/0` | yes | recreated by pam_elogind at first login, then held open by linger | @@ -117,6 +118,12 @@ The `go` block: mkdir -p /root/.local/bin install -m 755 /boot/config/herdr/herdr-core /root/.local/bin/herdr-core 2>/dev/null +# Put it on PATH under both names. ~/.local/bin is not on PATH in a +# non-interactive shell, and clients speak the protocol with `ssh box hc connect`, +# so without this they get "hc: command not found". +ln -sf /root/.local/bin/herdr-core /usr/local/bin/hc +ln -sf /root/.local/bin/herdr-core /usr/local/bin/herdr-core + # Keep /run/user/0 alive across logouts. pam_elogind creates and destroys it per # login session, and the hc core's socket lives there, so without linger the # socket disappears with the session that started the core and every later @@ -135,10 +142,38 @@ hand: it came back `-rwxr-xr-x` reporting `hc 0.1.17`. ## Notes -- `~/.local/bin` is not on `PATH` in a non-interactive shell on Unraid, so - `herdr-core` resolves only by absolute path there. Herdr itself always uses - the absolute path, so this does not affect normal use. +- The binary installs to `/root/.local/bin/herdr-core`, which is not on `PATH` + in a non-interactive shell and is not named `hc`. The desktop app works + regardless because it uses the absolute path it installed, but any other + client fails. Symlinks in `/usr/local/bin` fix that (restored by the go + script above). - Adding a machine that `hc` already knows is refused as a duplicate — it keys on the core id (`3d4a2397fcb6…`), not the address. Re-pointing an existing machine means `machine rm` then `machine add`, since there is no command to change a target in place. + +## Other clients (mobile, app builders) + +`hc connect` speaks the protocol over stdin/stdout, so any client attaches with +`ssh hc connect`. `hc schema` prints the API as JSON Schema. What a client +needs for this server: + +| Field | Value | +|-------|-------| +| Host | `100.100.208.69`, or `xtrm-unraid.tailf789e1.ts.net` | +| Port | **22** — not 422; sshd binds only 192.168.10.20 and 192.168.31.250, so 422 is closed on the Tailscale address | +| User | `root` | +| Password / key | none — Tailscale SSH authenticates by tailnet identity | +| Command | `hc connect` | + +The client device must itself be an active node in the tailnet +(`tailf789e1.ts.net`), because Tailscale SSH authorises by source node. The ACL +is `accept` for `autogroup:member` -> `autogroup:self`, so the owner's own +devices are covered once they are online and logged in. + +Before the `/usr/local/bin` symlinks existed, this failed at the first hurdle: + +``` +ssh root@100.100.208.69 'hc connect' +-> /bin/bash: line 1: hc: command not found +``` diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index c7dc1b1..e97710d 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -23,6 +23,7 @@ - **[SERVICE]** Root cause of `core did not start within 5 s` was the hc core socket living under `XDG_RUNTIME_DIR` = `/run/user/0`, which `pam_elogind.so` creates and destroys per login session. Fixed properly with `loginctl enable-linger root`, which keeps that directory alive so every client agrees on the default socket path. An earlier Mac-side `XDG_RUNTIME_DIR` pin fixed the CLI but broke the GUI's plain-ssh "Add a machine"; linger supersedes it and the wrapper is retained but unused. - **[SERVICE]** `/boot/config/go` now restores the hc binary **and** re-applies linger at boot, since `/`, `/run` and `/var/lib` are all RAM on Unraid. `sh -n` clean, backups at `/boot/config/go.bak-*`. - **[SERVICE]** Corrected a stale `~/.ssh/config` entry that still pointed `unraid` at the deleted node `100.100.208.70` on port 422 — an address and port combination that never worked, since sshd binds only 192.168.10.20 and 192.168.31.250. Replaced with `unraid` (LAN, key, 422) and `unraid-ts` (100.100.208.69, Tailscale SSH, 22). This stale entry was also what the Herdr GUI was listing. +- **[SERVICE]** Symlinked `/usr/local/bin/hc` and `/usr/local/bin/herdr-core` to the installed binary, and added the links to the go script. `~/.local/bin` is not on PATH in a non-interactive shell and the binary is not named `hc`, so clients using the documented `ssh box hc connect` (the mobile client, anything built on `hc schema`) got "hc: command not found". The desktop app was unaffected because it calls the absolute path it installed. - **[SERVICE]** Unraid added to Herdr as the machine `unraid` (`hc` 0.1.17 on the remote). `herdr-core machine add` had been failing with `core did not start within 5 s`: `hc` puts its core socket under `XDG_RUNTIME_DIR`, which on Unraid is `/run/user/0` — a directory elogind creates and destroys per login session, so the socket disappeared the moment the session that started the core ended. The core kept running with an unlinked socket, and `core.log` stayed empty because the failure is client side. - **[SERVICE]** Fixed from the Mac only, via `~/.local/bin/herdr-via-unraid`, a `--via` transport that exports `XDG_RUNTIME_DIR=/var/run/herdr-rt` on every connection. Nothing on the server was changed. Uses key auth on 192.168.10.20:422 rather than Tailscale SSH, because `--via` needs a transport that asks nothing and the default tailnet ACL `check` would demand periodic browser re-auth. - **[SERVICE]** Reboot caveat: `/` is rootfs (RAM) and `/run` is tmpfs on Unraid, so `/root/.local/bin/herdr-core` is lost at every boot and needs `herdr-core machine update` to restore. A `/boot/config/go` entry now restores it at boot from `/boot/config/herdr/herdr-core` (`install -m 755`, because /boot is FAT32 and carries no execute bit). Applied 2026-11-03, with the go script backed up to `go.bak-20261103-203916` and verified by deleting the binary and running the line by hand. Detail in `docs/14-HERDR-REMOTE-MACHINES.md`.