feat: netssh multi — several hosts side by side in tmux or zellij

netssh multi opens one pane per host in a tmux window or zellij tab. Hosts come from names, tag:TAG (NetBox and static hosts), cluster:NAME (NetBox virtualization clusters; devices by default, --kind vm|all), and groups from the config (@name, nested, with cycle detection). Every pane runs netssh HOST, so lookup, rules, and jump hosts apply. - tmux: a new window inside tmux, else a new session that is attached; tiled layout, pane borders with the host and a [SYNC] marker. - zellij: a generated grid layout; a new tab inside zellij, else a new session. - --sync broadcasts typing to all panes; netssh sync toggles it in the current tmux window or zellij tab. - TUI: Space marks hosts, Ctrl+A marks all, Enter opens them together. - Configurator: multiplexer, panes per window, groups. NetBox SearchAll gains a cluster filter (name to cluster IDs per instance), and cache entries keep the host's cluster for completion and an offline fallback. Panes skip the 24-hour background refresh (checked once by multi) and get HOME/XDG paths but no NETSSH_* values, which would expose tokens in the process list. testenv/tests/15-multi.sh checks real tmux and zellij sessions, including a broadcast command arriving on all three cluster nodes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 12:45:05 +01:00
1 parent dbb99bdded
commit a31aab4110
@@ -21,7 +21,7 @@ The same lookup drives `netssh sftp`, `netssh scp`, and `netssh tunnel`, the int
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [Configuration](#configuration) — [wizard](#interactive-wizard), [manual config](#manual-config), [reference](#configuration-reference), [environment variables](#environment-variables), [files](#files-and-directories), [multiple instances](#multiple-netbox-instances)
- [Usage](#usage) — [command overview](#command-overview), [SSH options](#ssh-options), [SFTP & SCP](#sftp-and-scp), [port forwarding](#port-forwarding), [static hosts](#static-hosts), [shortcuts](#host-shortcuts), [TUI](#interactive-tui), [notes](#server-notes), [cache](#cache-management)
+- [Usage](#usage) — [command overview](#command-overview), [SSH options](#ssh-options), [SFTP & SCP](#sftp-and-scp), [port forwarding](#port-forwarding), [static hosts](#static-hosts), [multiple servers](#multiple-servers-in-one-window), [shortcuts](#host-shortcuts), [TUI](#interactive-tui), [notes](#server-notes), [cache](#cache-management)
 - [Recipes](#recipes)
 - [IP Resolution Strategies](#ip-resolution-strategies)
 - [Shell Completion](#shell-completion) and [Shell Hook](#shell-hook)
@@ -50,6 +50,7 @@ The same lookup drives `netssh sftp`, `netssh scp`, and `netssh tunnel`, the int
 - **Automatic 24h cache refresh** — the cache is refreshed in the background every 24 hours
 - **Jump hosts and SSH options** — `proxy_jump`, host key checking, connection target, and free `-o` options per netssh, per NetBox instance, or per tag/name rule — without touching `~/.ssh/config`
 - **SFTP & SCP** — `netssh sftp host` and `netssh scp file host:/tmp/` with the same host lookup, shortcuts, and SSH options as ssh
+- **Several servers in one window** — `netssh multi` opens hosts, a tag, a NetBox cluster, or a saved group side by side in tmux or zellij, with optional typing into all of them
 - **Port forwarding** — named forwards in the config (`netssh tunnel host web`, `netssh --forward web host`), ad hoc specs, and `Ctrl+T` in the TUI
 - **Dry run** — `netssh --dry-run host` prints the final `ssh` command instead of connecting
 - **Clean uninstall** — `netssh uninstall` removes the binary, profile entries of all versions, completions, cache, and config
@@ -149,6 +150,7 @@ A menu then gives access to every other setting; open only the sections you want
 | SSH options | `proxy_jump`, `host_key_checking`, `target`, `address_family`, `extra_args` (one per line), `options` (`Key=Value` per line), `forwards` (`NAME L\|R\|D SPEC` per line) |
 | SSH rules | add, edit, remove `ssh.rules` — match by tag, instance, kind, name pattern, each with its own SSH options |
 | Static hosts | add, edit, remove hosts that are not in NetBox, each with user, port, tags, and SSH options |
+| Multi-session | multiplexer (auto, tmux, zellij), panes per window, groups (`NAME: sel1, sel2` per line) |
 | Resolver & cache | strategies, management subnets, interface name, hostname domain, cache TTL, cache file |
 | Shortcuts & command alias | domain suffixes, hyphen stripping, rewrite rules (`REGEX => REPLACEMENT` per line), `shell.alias` |
 | Completion | `completion.max_results` |
@@ -232,10 +234,13 @@ Every key, its default, and the section that explains it. Keys marked *layered*
 | `completion.max_results` | int | `0` | Hostnames offered per `<Tab>`; `0` = unlimited. |
 | `shell.alias` | string | — | Short command name for netssh, e.g. `j` — see [Short command alias](#short-command-alias). |
 | `hosts[]` | list | `[]` | Static hosts with `name`, `address`, `user`, `port`, `tags`, `ssh` — see [Static hosts](#static-hosts). |
+| `groups` | map of lists | `{}` | Named host lists for `netssh multi @NAME`; entries are hosts or selectors. |
+| `multi.multiplexer` | `auto` \| `tmux` \| `zellij` | `auto` | Which multiplexer `netssh multi` uses. |
+| `multi.panes_per_window` | int | `9` | More hosts open in further tmux windows or zellij tabs. |

 ### Environment variables

-These variables override the file. Lists are comma-separated (`NETSSH_SHORTCUTS_DOMAINS=.example.com,.example.de`). Settings without a variable (`extra_args`, `options`, `forwards`, `rules`, `rewrites`, `netboxes`, `hosts`) can only be set in the file.
+These variables override the file. Lists are comma-separated (`NETSSH_SHORTCUTS_DOMAINS=.example.com,.example.de`). Settings without a variable (`extra_args`, `options`, `forwards`, `rules`, `rewrites`, `netboxes`, `hosts`, `groups`) can only be set in the file.

 | Variable | Key |
 |---|---|
@@ -246,6 +251,7 @@ These variables override the file. Lists are comma-separated (`NETSSH_SHORTCUTS_
 | `NETSSH_SSH_PROXY_JUMP`, `NETSSH_SSH_HOST_KEY_CHECKING`, `NETSSH_SSH_TARGET`, `NETSSH_SSH_ADDRESS_FAMILY` | global `ssh.*` options |
 | `NETSSH_SHORTCUTS_DOMAINS`, `NETSSH_SHORTCUTS_STRIP_HYPHENS` | `shortcuts.*` |
 | `NETSSH_COMPLETION_MAX_RESULTS` | `completion.max_results` |
+| `NETSSH_MULTI_MULTIPLEXER`, `NETSSH_MULTI_PANES_PER_WINDOW` | `multi.*` |
 | `NETSSH_SHELL_ALIAS` | `shell.alias` |

 netssh also respects `XDG_CONFIG_HOME`, `XDG_CACHE_HOME`, `ZDOTDIR`, and `SHELL` (for `hook install`, `completion install`, and `alias` without `--shell`).
@@ -359,6 +365,8 @@ A hint is shown during `netssh configure` if a legacy v1 token is entered.
 | `netssh scp [netssh flags] [scp options] SOURCE... TARGET` | Copy files — see [SFTP and SCP](#sftp-and-scp). |
 | `netssh tunnel [netssh flags] [ssh options] HOST FORWARD...` | Port forwards without a shell — see [Port forwarding](#port-forwarding). |
 | `netssh hosts [list] \| add NAME ADDRESS [--user U] [--port P] [--tag T]... [--replace] \| remove NAME` | Manage static hosts — see [Static hosts](#static-hosts). |
+| `netssh multi [--sync] [--kind K] [--tmux\|--zellij] [-l U] [--jump H\|--no-jump] HOST\|tag:T\|cluster:C\|@GROUP...` | Several hosts side by side — see [Multiple servers](#multiple-servers-in-one-window). |
+| `netssh sync` | Toggle typing into all panes of the current tmux window or zellij tab. |
 | `netssh configure` | Setup wizard. |
 | `netssh cache list \| refresh [--tag T] [--kind device\|vm] [--instance I] \| clear` | Inspect and manage the host cache. |
 | `netssh search QUERY` | Print matching cached hostnames, one per line. |
@@ -513,7 +521,7 @@ netssh --forward web fsnbx1               # shell plus forward (repeatable)

 A value that is no configured name but a port spec (`[bind:]port:host:hostport`) becomes a local forward. `netssh tunnel` adds `-o ExitOnForwardFailure=yes`, so a port already in use fails instead of leaving a silent session. Without forward names it lists the forwards configured for the host. Forward names are completed after the host (`netssh tunnel fsnbx1 <Tab>`) and after `--forward`. In the TUI, `Ctrl+T` on a host opens an input with its configured forwards.

-`sftp`, `scp`, `tunnel`, and `hosts` are subcommands; to connect to a host with one of these names, use `netssh -- sftp`.
+`sftp`, `scp`, `tunnel`, `hosts`, `multi`, and `sync` are subcommands; to connect to a host with one of these names, use `netssh -- sftp`.

 ### Static hosts

@@ -547,6 +555,47 @@ Static hosts behave like NetBox hosts everywhere: `netssh router`, `sftp`, `scp`
 - Static hosts never expire and are not touched by `cache refresh` or `cache clear`; removing one from the config removes it everywhere.
 - `--netbox` notes and NetBox comments are not available for static hosts; local notes work.

+### Multiple servers in one window
+
+`netssh multi` opens one pane per host in tmux or zellij — for example every node of a Proxmox or Kubernetes cluster — and can send your typing to all of them at once.
+
+```sh
+netssh multi web01 web02 db01              # hosts, shortcuts, instance/host, static hosts
+netssh multi tag:k8s-worker                # all hosts with a NetBox tag (and static hosts with it)
+netssh multi cluster:pve-fsn1              # the devices (nodes) of a NetBox virtualization cluster
+netssh multi --kind vm cluster:pve-fsn1    # the cluster's VMs; --kind all for both
+netssh multi @k8s                          # a saved group
+netssh multi --sync @k8s                   # start with typing sent to every pane
+netssh multi --dry-run cluster:pve-fsn1    # show the hosts and tmux/zellij commands
+```
+
+Each pane runs `netssh HOST`, so lookup, shortcuts, user and port, jump hosts, and rules work as for a single connection. `-l USER`, `--jump HOST`, and `--no-jump` apply to every pane. A pane whose connection fails stays open with the error until you press Enter.
+
+**Groups** collect hosts and selectors under a name (or use `netssh configure` → *Multi-session*):
+
+```yaml
+groups:
+  k8s: [k8s-master1, "tag:k8s-worker"]
+  pve: ["cluster:pve-fsn1"]
+  all-web: ["@k8s", "tag:web", legacy-box]
+multi:
+  multiplexer: auto        # auto | tmux | zellij
+  panes_per_window: 9      # more hosts open in further windows/tabs
+```
+
+**tmux and zellij.** With `auto`, netssh uses the multiplexer you are in; otherwise tmux, then zellij, whichever is installed (`--tmux` / `--zellij` choose explicitly).
+
+| | tmux | zellij |
+|---|---|---|
+| Inside a session | new window in the current session | new tab in the current session |
+| Outside | new session `netssh-NAME`, attached | new session from a generated layout |
+| Layout | tiled; pane borders show the host | grid; pane titles show the host |
+| Broadcast | `--sync`, or `netssh sync` / `Ctrl+b :setw synchronize-panes` to toggle; borders show `[SYNC]` | `--sync` inside zellij, or `Ctrl+t` then `s` (also `netssh sync`) |
+
+**In the TUI**, mark hosts with `Space` (or all listed hosts with `Ctrl+A`) and press `Enter` to open them together.
+
+`tag:` and `cluster:` ask NetBox (all instances); if NetBox is unreachable, netssh uses the cached hosts and prints a warning. More than 24 hosts need `--yes`. The 24-hour background cache refresh runs once, not in every pane.
+
 ### Default username

 Set `ssh.default_user` in the config to avoid typing a username every time:
@@ -664,6 +713,8 @@ The TUI opens with your 10 most-recently-connected hosts. Start typing to search
 | `Tab` | autocomplete top result into the search field |
 | `↑` / `↓` | navigate results |
 | `Enter` | connect to selected host |
+| `Space` | mark/unmark the host; with marks, `Enter` opens them side by side (`netssh multi`) |
+| `Ctrl+A` | mark all listed hosts (again: unmark all) |
 | `Ctrl+O` | open an SFTP session to the selected host |
 | `Ctrl+T` | start a tunnel: enter forward names or specs (`web, 8080:localhost:80`) |
 | `Ctrl+E` | open inline editor to override user/port before connecting |
@@ -827,6 +878,14 @@ netssh cache refresh && netssh alias --test fsn1-bx1.hoster.de
 netssh fsnbx1                   # also works as shell alias: fsnbx1
 ```

+**Maintenance on all nodes of a cluster at once**
+
+```sh
+netssh multi --sync cluster:pve-fsn1     # every node in one window, typing goes to all
+# … run apt upgrade on all nodes, then turn broadcast off for per-node work:
+netssh sync                              # from another pane, or Ctrl+b :setw synchronize-panes
+```
+
 **Deploy a file and restart a service**

 ```sh
@@ -1024,7 +1083,10 @@ Both are non-blocking — the refresh runs as a background process and never del
 | Saving notes with `--netbox` fails with a permission error | The API token is read-only. Local notes work without write permission. |
 | `<Tab>` completes files instead of hosts | Run `netssh completion install` and open a new terminal; for zsh also `rm -f ~/.zcompdump*`. |
 | Aliases missing in a new shell | `netssh hook install`, then a new terminal. The cache must not be empty. |
-| A host is named `sftp`, `scp`, `tunnel`, `hosts`, or like another subcommand | Use `netssh -- sftp`. |
+| A host is named `sftp`, `scp`, `tunnel`, `hosts`, `multi`, `sync`, or like another subcommand | Use `netssh -- sftp`. |
+| `netssh multi needs tmux or zellij` | Install one of them (`apt install tmux`, `brew install tmux`). |
+| `cluster:x matches no hosts` | Clusters select devices by default; VMs need `--kind vm` or `--kind all`. The name is matched case-insensitively. |
+| `netssh multi` panes use another config | Inside an existing tmux/zellij session, panes get your `HOME` and `XDG_*` paths, but not `NETSSH_*` variables (they would be visible to other users in the process list). Put such settings in the config file. |

 ## Uninstall

@@ -1059,7 +1121,7 @@ End-to-end tests run against real services in a local Docker environment — two

 ```sh
 testenv/up.sh        # build and start (first start ~6 min)
-testenv/test.sh      # 141 checks: connect, strategies, instances, shortcuts, rules, sftp/scp, tunnels, notes, shells, TUI, configurator
+testenv/test.sh      # 160 checks: connect, strategies, instances, shortcuts, rules, sftp/scp, tunnels, notes, shells, TUI, configurator, multi with tmux and zellij
 testenv/down.sh
 ```

@@ -1075,6 +1137,7 @@ Project layout:
 | `internal/resolver` | IP resolution strategies. |
 | `internal/cache` | Host cache. |
 | `internal/ssh` | Argument parsing and option injection for ssh, sftp, scp. |
+| `internal/multiplex` | tmux and zellij layouts for `netssh multi`. |
 | `internal/shortcuts` | Shortcut normalization. |
 | `internal/tui` | Interactive search. |
 | `internal/setup` | Setup wizard. |
@@ -1087,7 +1150,7 @@ This is a **vibe-coded** project: the entire codebase — architecture, implemen

 ## How it works

-1. `netssh` checks whether the first argument is a known subcommand (`configure`, `cache`, `sftp`, `scp`, `tunnel`, `notes`, …). If not, it enters SSH wrapper mode; without arguments it starts the TUI.
+1. `netssh` checks whether the first argument is a known subcommand (`configure`, `cache`, `sftp`, `scp`, `tunnel`, `multi`, `notes`, …). If not, it enters SSH wrapper mode; without arguments it starts the TUI.
 2. On first run, or when neither a NetBox nor static hosts are configured, the interactive setup wizard starts automatically.
 3. It removes its own long options (`--dry-run`, `--jump`, `--no-jump`, `--forward`) and parses the remaining arguments with the flag table of the program it will run (ssh, sftp, or scp differ, e.g. in `-l` and `-P`) to find the destination: `[user@]host` for ssh, `[user@]host[:path]` for sftp, and every `host:path` operand for scp.
 4. It resolves the host: first the static hosts from `hosts:` (by name or shortcut), then an exact cache lookup, a shortcut match against the cache (domains, rewrites, hyphen folding), and finally NetBox (`/api/dcim/devices/` and `/api/virtualization/virtual-machines/`, all instances in parallel) with the resolver chain. A fresh cache entry needs no network request; new results are cached.