docs: document DNS suggestions, dns settings and links (v1.3.0)
Test / test (pull_request) Successful in 4m16s

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Sebastian UnterschützandClaude Opus 5.5 committed 2026-11-18 13:07:09 +01:00
1 parent e905a39068
commit 080e52b437
2 files changed
+84

No files matched your search

+76
View File
@@ -58,6 +58,7 @@ The same lookup drives `netssh sftp`, `netssh scp`, and `netssh tunnel`, the int
- **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
- **Host details** — `netssh info host` (and `Ctrl+L` in the TUI) shows site, the nested locations down to rack and rack units, role, platform, tenant, status and all IP addresses per interface; `netssh open host` (`Ctrl+G`) opens the NetBox page
- **DNS names and links** — `netssh mx123.webseite.de` (or `netssh mx123`) for a name that is only in DNS: netssh finds the host owning the address in NetBox, suggests it, and can save `mx123` as a link — `netssh mx123` and the shell alias `mx123` then connect directly
- **Reverse lookup** — `netssh whois 10.1.2.3` names the device or VM, interface, DNS name and prefixes of an address
- **Status warning** — asks before connecting to hosts that are `offline`, `planned`, `decommissioning` …; TUI badge and `status:` filter
- **Configurable TUI** — choose what is shown next to each host (`tui.columns`: IP, source, status, site, location path, role, platform, tenant, cluster, tags, kind, alias); the optional `reachability` column marks hosts ✓/✗ after a quick TCP check of their SSH port; `resolver.fallback` connects to another known address when the chosen one does not answer
@@ -258,6 +259,10 @@ Every key, its default, and the section that explains it. Keys marked *layered*
| `hosts[]` | list | `[]` | Static hosts with `name`, `address`, `user`, `port`, `tags`, `ssh` — see [Static hosts](#static-hosts). |
| `commands` | map | `{}` | Local command rules with `alias_prefix` and argument list `args`; see [Custom host commands](#custom-host-commands). |
| `groups` | map of lists | `{}` | Named host lists for `netssh multi @NAME`; entries are hosts or selectors. |
| `dns.suggest` | `ask` \| `always` \| `never` | `ask` | Unknown names: suggest the host owning the DNS address (`ask`), take the first suggestion without asking, also in scripts (`always`), or do no DNS lookup (`never`) — see [DNS names and links](#dns-names-and-links). |
| `dns.save_link` | `ask` \| `always` \| `never` | `ask` | Save a link after a suggestion: ask, always, or never. |
| `dns.domains[]` | list | `[]` | `match` (glob on the typed name, e.g. `mx*`; empty = all) and `domain` appended to names without a dot. |
| `links` | map | `{}` | Short names for hosts, `mx123: prod/web07`: `netssh mx123` and the shell alias `mx123` connect to the host — see [DNS names and links](#dns-names-and-links). |
| `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. |
| `multi.sync_key`, `multi.solo_key` | tmux key \| `none` | `S`, `e` | Keys after the tmux prefix: broadcast to all panes, exclude/include the current pane. |
@@ -280,6 +285,7 @@ These variables override the file. Lists are comma-separated (`NETSSH_SHORTCUTS_
| `NETSSH_COMPLETION_MAX_RESULTS` | `completion.max_results` |
| `NETSSH_MULTI_MULTIPLEXER`, `NETSSH_MULTI_PANES_PER_WINDOW` | `multi.*` |
| `NETSSH_SHELL_ALIAS` | `shell.alias` |
| `NETSSH_DNS_SUGGEST`, `NETSSH_DNS_SAVE_LINK` | `dns.suggest`, `dns.save_link` |
netssh also respects `XDG_CONFIG_HOME`, `XDG_CACHE_HOME`, `ZDOTDIR`, and `SHELL` (for `hook install`, `completion install`, and `alias` without `--shell`).
@@ -429,6 +435,7 @@ To keep tokens out of the config file, store them in the system keyring with
| `netssh scp [netssh flags] [scp options] SOURCE... TARGET` | Copy files — see [SFTP and SCP](#sftp-and-scp). |
| `netssh doctor [--online]` / `netssh explain HOST` | Diagnose configuration and explain effective settings. |
| `netssh info [--json] HOST` / `netssh open [--print] HOST` | Show NetBox details of a host / open its NetBox page — see [Host details](#host-details-and-netbox-page). |
| `netssh link list \| add NAME HOST \| remove NAME` | Short names for hosts — see [DNS names and links](#dns-names-and-links). |
| `netssh whois [--json] ADDRESS\|HOSTNAME` | Find the host, interface and prefix of an address — see [Reverse lookup](#reverse-lookup). |
| `netssh copy-id [-i KEY] [-l U] [--dry-run] HOST\|tag:T\|cluster:C\|@GROUP...` | Install your public key with ssh-copy-id — see [ssh-copy-id](#ssh-copy-id). |
| `netssh known-hosts reset [--yes] [--dry-run] HOST...` | Remove stored host keys of re-deployed hosts — see [known_hosts cleanup](#known_hosts-cleanup). |
@@ -1401,6 +1408,75 @@ All NetBox instances are queried; prefixes are listed from the widest to the
most specific. The exit code is 1 when nothing is found. A failing instance is
reported as a warning without hiding the answers of the others.
### DNS names and links
Customers and colleagues often know a host by a DNS name such as
`mx123.webseite.de` that is not the device or VM name in NetBox. When netssh
finds a name neither in NetBox nor in the cache, it resolves it through DNS,
looks the addresses up in NetBox (and the cache) and suggests the hosts that
own them:
```
$ netssh mx123.webseite.de
netssh: "mx123.webseite.de" is not in NetBox or the cache. DNS: mx123.webseite.de → 203.0.113.5
1) prod/web07 203.0.113.5 on eth0 (NetBox)
2) connect directly to mx123.webseite.de
Choose [1-2, Enter = 1, q = cancel]:
Save shortcut "mx123" → prod/web07 (netssh mx123, shell alias mx123)? [y/N or another name]: y
```
- Short names get their domain from `dns.domains` (see below), so `netssh mx123`
looks up `mx123.easysahre.de`. `shortcuts.domains` are not used here.
- Choosing a host connects with all of its settings (user, port, jump host,
rules). "Directly" connects to the DNS name with the global settings.
- The shortcut offer saves a **link** under `links:` in the config: from then on
`netssh mx123` connects to `prod/web07` without asking, and new shells get
the alias `mx123` (it also completes with `<Tab>`). Answer with another name
to choose it, or `n` to skip.
- Without a terminal (scripts) netssh does not choose, unless `dns.suggest:
always`: the error lists the suggestions, e.g.
`netssh prod/web07 # 203.0.113.5 on eth0 (NetBox)`.
- `netssh info` and `netssh open` use the same suggestion, and `netssh whois mx123`
also uses `dns.domains`.
```yaml
dns:
suggest: ask # ask | always (first suggestion, also in scripts) | never (no DNS lookup)
save_link: ask # ask | always (save the shortcut without asking) | never
domains: # tried in order for names without a dot
- match: "mx*" # shell glob on the typed name
domain: easysahre.de
- match: "ah*"
domain: jhfduwia.de
# - domain: example.com # without match: every name
```
A name without a dot gets the domain of every matching rule (`mx123` →
`mx123.easysahre.de`); only when no rule matches is the bare name looked up,
using the system resolver's search domains. A name with a dot is looked up as
typed. With `suggest: always` netssh connects to the first suggestion (NetBox
hosts first), or directly to the DNS name when no host owns the address. All
three settings are also in `netssh configure` → **Resolver & cache**.
Manage links directly:
```sh
netssh link add mx123 prod/web07 # or: netssh link add mx123 mx123.webseite.de
netssh link list
netssh link remove mx123
```
```yaml
links:
mx123: "prod/web07"
shop: "lab/web1"
```
A link points to a host netssh knows (NetBox or static host), not to another
link; its name must not be a static host. Links take precedence over NetBox
names. The target is fixed: if the DNS name later points elsewhere, update the
link.
### Status warning
Connecting to a host whose NetBox status is listed in `ssh.warn_status` asks first: