feat: NetBox insights, host tools and configurable TUI
Test / test (pull_request) Successful in 4m15s

- info/open/whois: NetBox details (site, nested locations, rack units,
  role, platform, tenant, IPs per interface), web page, reverse IP lookup
- cache status, site, role, platform, tenant, location chain and rack;
  ask before connecting to hosts in ssh.warn_status (--force skips)
- ssh rules and command restrictions match site/role/platform/tenant/status
- tui.columns selects what the TUI shows; optional TCP reachability column;
  detail view (Ctrl+L), NetBox page (Ctrl+G), status/location filters
- resolver.fallback tries other strategies' addresses when unreachable
- copy-id, known-hosts reset and address-change notices
- export ansible (YAML/INI) and export ssh-config
- token: keyring stores NetBox tokens in the system keyring
- fix stale menu number in testenv configure test

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 12:33:59 +01:00
1 parent e5bde9c61f
commit 1660bb3098
39 files changed
+4868 -96

No files matched your search

+330 -7
View File
@@ -23,6 +23,7 @@ The same lookup drives `netssh sftp`, `netssh scp`, and `netssh tunnel`, the int
- [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), [pre-connect hook](#pre-connect-hook), [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)
- [Operations](#operations) — post scripts, favorites, history, diagnostics, batch commands, configuration sharing
- [NetBox insights and host tools](#netbox-insights-and-host-tools) — `info`, `open`, `whois`, status warnings, TUI columns and reachability, address fallback, `copy-id`, `known-hosts`, `export`, keyring tokens
- [Custom host commands](#custom-host-commands) — automatic aliases for mtr, ping, and other programs
- [Hotkey cheat sheet](#hotkey-cheat-sheet) — search, editors, tmux and zellij
- [Recipes](#recipes)
@@ -56,6 +57,13 @@ The same lookup drives `netssh sftp`, `netssh scp`, and `netssh tunnel`, the int
- **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
- **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
- **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
- **Rules by NetBox attributes** — `ssh.rules` and command restrictions match `site`, `role`, `platform`, `tenant` and `status`, e.g. legacy ciphers for `platform: junos`
- **ssh-copy-id, known_hosts cleanup, exports** — `netssh copy-id tag:lab`, `netssh known-hosts reset host`, `netssh export ansible` (YAML or INI) and `netssh export ssh-config`
- **Keyring tokens** — `netssh token migrate` moves API tokens from the config into the system keyring
- **Clean uninstall** — `netssh uninstall` removes the binary, profile entries of all versions, completions, cache, and config
## Installation
@@ -212,17 +220,20 @@ Every key, its default, and the section that explains it. Keys marked *layered*
| Key | Type | Default | Description |
|---|---|---|---|
| `netbox.url` | string | — | NetBox base URL (single instance). Use either `netbox` or `netboxes`. |
| `netbox.token` | string | — | API token; `nbt_…` is v2, anything else v1. |
| `netbox.token` | string | — | API token; `nbt_…` is v2, anything else v1. `keyring` reads it from the system keyring — see [Keyring tokens](#keyring-tokens). |
| `netbox.token_version` | 1 \| 2 | auto | Detected from the token prefix. |
| `netboxes[]` | list | — | Named instances with `name`, `url`, `token`, `token_version`, `disable_prefix`, `ssh` — see [Multiple NetBox instances](#multiple-netbox-instances). |
| `resolver.strategies` | list | `[management_subnet, primary_ip]` | Tried in order, first IP wins — see [IP Resolution Strategies](#ip-resolution-strategies). The wizard suggests `primary_ip`. |
| `resolver.management_subnets` | list of CIDR | `[]` | Used by `management_subnet`. |
| `resolver.interface_name` | string | — | Used by `interface_name`, e.g. `mgmt0`. |
| `resolver.hostname_domain` | string | — | Used by `hostname`: appended to NetBox names without a dot. |
| `resolver.fallback` | bool | `false` | When the chosen address does not answer on the SSH port, connect to the first address of another strategy that does — see [Address fallback](#address-fallback). |
| `resolver.fallback_timeout` | milliseconds | `1000` | Connect timeout per address for the fallback check. |
| `cache.ttl` | seconds | `3600` | How long a cached IP is used without asking NetBox; `0` always asks NetBox when connecting. |
| `cache.path` | path | user cache dir `/netssh/hosts.json` | Cache file; named instances use a subdirectory next to it. |
| `ssh.default_user` | string | — | Login user when none is given (`-l` for ssh, `-o User=` for sftp/scp). |
| `ssh.default_port` | int | — | Port when none is given (`-p` for ssh, `-P` for sftp/scp). |
| `ssh.warn_status` | list | `[offline, planned, staged, failed, inventory, decommissioning]` | NetBox status values that ask before connecting; `[]` disables the question — see [Status warning](#status-warning). |
| `ssh.proxy_jump` | string | — | *Layered.* Jump host (`-J`); `none` disables an inherited one. |
| `ssh.host_key_checking` | `strict` \| `accept-new` \| `off` | ssh's own | *Layered.* See [SSH options](#ssh-options). |
| `ssh.target` | `ip` \| `name` \| `hostname` | `ip` | *Layered.* What is passed to ssh as destination. |
@@ -232,10 +243,12 @@ Every key, its default, and the section that explains it. Keys marked *layered*
| `ssh.forwards` | map | `{}` | *Layered.* Named port forwards (`local`, `remote`, `dynamic`) — see [Port forwarding](#port-forwarding). |
| `ssh.post_disconnect` | string | — | *Layered.* Local shell command after the client exits; `none` disables inheritance. |
| `tui.history_limit` | integer | `10` | Recent hosts shown; `0` means all, favorites are additional. |
| `tui.columns` | list | `[alias, ip, source, status]` | What the TUI shows next to each hostname (also `location`), in order; `[]` shows only names. Adding `reachability` enables the TCP check — see [TUI columns](#tui-columns-and-reachability). |
| `tui.reachability_timeout` | milliseconds | `300` | Timeout of the TCP check of the `reachability` column. |
| `activity.enabled` | boolean | `false` | Enable local execution metadata history. |
| `activity.retention_days` / `activity.max_entries` | integer | `30` / `1000` | History retention limits; `0` disables the respective limit. |
| `ssh.pre_connect` | string | — | *Layered.* Shell command run locally before connecting; a non-zero exit aborts; `none` disables an inherited one — see [Pre-connect hook](#pre-connect-hook). |
| `ssh.rules[]` | list | `[]` | `match` (`tag`, `instance`, `kind`, `name`) plus any layered key. |
| `ssh.rules[]` | list | `[]` | `match` (`tag`, `instance`, `kind`, `name`, `site`, `role`, `platform`, `tenant`, `status`) plus any layered key. |
| `shortcuts.domains` | list | `[]` | Suffixes stripped for shortcuts and tried when expanding a short name. |
| `shortcuts.strip_hyphens` | bool | `false` | Ignore hyphens when matching shortcuts. |
| `shortcuts.rewrites[]` | list | `[]` | `pattern` (Go regex) and `replace` — see [Host shortcuts](#host-shortcuts). |
@@ -259,6 +272,9 @@ These variables override the file. Lists are comma-separated (`NETSSH_SHORTCUTS_
| `NETSSH_RESOLVER_STRATEGIES`, `NETSSH_RESOLVER_MANAGEMENT_SUBNETS`, `NETSSH_RESOLVER_INTERFACE_NAME`, `NETSSH_RESOLVER_HOSTNAME_DOMAIN` | `resolver.*` |
| `NETSSH_CACHE_TTL`, `NETSSH_CACHE_PATH` | `cache.*` |
| `NETSSH_SSH_DEFAULT_USER`, `NETSSH_SSH_DEFAULT_PORT` | `ssh.default_*` |
| `NETSSH_SSH_WARN_STATUS` | `ssh.warn_status` |
| `NETSSH_TUI_COLUMNS`, `NETSSH_TUI_REACHABILITY_TIMEOUT` | `tui.columns`, `tui.reachability_timeout` |
| `NETSSH_RESOLVER_FALLBACK`, `NETSSH_RESOLVER_FALLBACK_TIMEOUT` | `resolver.fallback*` |
| `NETSSH_SSH_PROXY_JUMP`, `NETSSH_SSH_HOST_KEY_CHECKING`, `NETSSH_SSH_TARGET`, `NETSSH_SSH_ADDRESS_FAMILY`, `NETSSH_SSH_PRE_CONNECT` | global `ssh.*` options |
| `NETSSH_SHORTCUTS_DOMAINS`, `NETSSH_SHORTCUTS_STRIP_HYPHENS`, `NETSSH_SHORTCUTS_SHOW` | `shortcuts.*` |
| `NETSSH_COMPLETION_MAX_RESULTS` | `completion.max_results` |
@@ -398,6 +414,9 @@ NetBox supports two token formats:
`netssh` auto-detects the version from the token prefix and stores it as `token_version` in the config.
A hint is shown during `netssh configure` if a legacy v1 token is entered.
To keep tokens out of the config file, store them in the system keyring with
`netssh token set` or `netssh token migrate` — see [Keyring tokens](#keyring-tokens).
## Usage
### Command overview
@@ -409,6 +428,12 @@ A hint is shown during `netssh configure` if a legacy v1 token is entered.
| `netssh sftp [netssh flags] [sftp options] HOST[:PATH]` | SFTP session — see [SFTP and SCP](#sftp-and-scp). |
| `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 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). |
| `netssh export ansible [--format yaml\|ini] [--group-by …]` / `netssh export ssh-config` | Export cached hosts — see [Exports](#exports-ansible-inventory-and-ssh_config). |
| `netssh token set\|migrate\|delete\|status` | Keep NetBox tokens in the system keyring — see [Keyring tokens](#keyring-tokens). |
| `netssh favorites` / `netssh history` | Manage saved hosts and optional action records. |
| `netssh batch COMMAND HOST...` | Run a configured command with bounded parallelism and retry. |
| `netssh config export\|import FILE` | Share host configuration without secrets or executable settings. |
@@ -427,7 +452,7 @@ A hint is shown during `netssh configure` if a legacy v1 token is entered.
| `netssh uninstall [--dry-run] [--keep-config] [--yes]` | Remove netssh. |
| `netssh version` / `netssh --version` | Print the version. |
The netssh flags `--dry-run`, `--jump`, `--no-jump`, and `--forward` must come before the host. Everything after the host is passed to ssh as the remote command (for `tunnel`: forward names).
The netssh flags `--dry-run`, `--force`, `--jump`, `--no-jump`, and `--forward` must come before the host. `--force` connects without asking about the NetBox status. Everything after the host is passed to ssh as the remote command (for `tunnel`: forward names).
### SSH wrapper mode
@@ -940,13 +965,15 @@ The TUI opens with your most-recently-connected hosts (10 by default, configurab
See the [hotkey cheat sheet](#hotkey-cheat-sheet) for all search and editor keys.
**Tag and kind filter** — press `Ctrl+F` to open a second input line:
**Filter** — press `Ctrl+F` to open a second input line:
```
Filter: tag:prod kind:vm
Filter: tag:prod kind:vm status:active site:fsn1 location:building-a role:router platform:junos tenant:acme
```
Multiple `tag:` values are AND-combined. The filter is applied locally against the cache; when doing a live NetBox search the first tag is also forwarded as a query parameter.
`location:` matches any level of the location chain (name or slug), `rack:` the rack name.
Multiple `tag:` values are AND-combined. `site:`, `role:`, `platform:` and `tenant:` accept the NetBox name or slug; they need a cache written by this version (`netssh cache refresh`). The filter is applied locally against the cache; when doing a live NetBox search the first tag is also forwarded as a query parameter.
**User/port override** — press `Ctrl+E` on any highlighted host:
@@ -956,6 +983,10 @@ Connect as: admin@my-router:22
Edit the pre-filled value and press `Enter` to connect. `Esc` cancels. The configured default port is pre-filled. An explicit port 22 overrides a different configured default.
**Details and NetBox page** — `Ctrl+L` shows the host's NetBox details (site, rack, role, platform, status, IP addresses) without leaving the TUI; `Enter` connects from there. `Ctrl+G` opens the host's NetBox page in the browser.
**Columns** — by default each host shows its shortcut alias, IP, source and a badge such as `[offline]` when its NetBox status is not `active`. Choose other information, its order, and the optional `✓`/`✗` reachability check with `tui.columns` — see [TUI columns](#tui-columns-and-reachability).
### Server notes
Select a server in the TUI and press `Ctrl+N` for local notes, or `Ctrl+B` for
@@ -1055,7 +1086,9 @@ in the search, while tmux uses `Ctrl+b` as its default prefix.
| `Ctrl+E` | open inline editor to override user/port before connecting |
| `Ctrl+N` | edit local notes for the selected server |
| `Ctrl+B` | edit NetBox comments for the selected server |
| `Ctrl+F` | open/close tag and kind filter (`tag:prod kind:vm`) |
| `Ctrl+F` | open/close the filter (`tag:prod kind:vm status:active site:fsn1 platform:junos`) |
| `Ctrl+L` | show NetBox details of the selected host (`Enter` connects, `Ctrl+G` opens NetBox, `Esc` back) |
| `Ctrl+G` | open the NetBox page of the selected host in the browser |
| `Esc` | quit search |
| `Ctrl+C` | quit from any TUI mode, including editors |
@@ -1307,6 +1340,296 @@ the previous configuration as `netssh.yaml.before-import` with mode `0600`.
The preview does not modify files. Export/import is intended for shared host
configuration, not a complete backup of local executable settings or secrets.
## NetBox insights and host tools
These commands and settings use more of what NetBox knows about a host. Site,
role, platform, tenant, status and the NetBox ID are stored in the cache by
`netssh cache refresh` (and by every live lookup); caches written by older
versions get them with the next refresh.
### Host details and NetBox page
```sh
netssh info prod/sw1 # site, locations, rack/U, role, platform, tenant, type, serial, IPs per interface
netssh info --json web01 # the same as JSON
netssh open web01 # NetBox page in the browser ($BROWSER, open, or xdg-open)
netssh open --print web01 # only print the URL
```
```
sw1 (device, NetBox prod)
Status Active
Site FSN1
Location Building A › Floor 2 › Room 2.04
Rack R12 U20-21 (2U, front)
Path FSN1 › Building A › Floor 2 › Room 2.04 › R12 › U20
Role Core Switch
Platform Junos
Type Juniper QFX5120
Connect 10.0.0.7 (management_subnet, cache)
URL https://netbox.example.com/dcim/devices/7/
IP addresses
* 10.0.0.7/24 em0 sw1.example.com active
192.0.2.7/24 xe-0/0/1 active
```
`Location` lists every nested NetBox location from the one directly below the
site down to the device's own location (NetBox nests them through `parent`).
`Rack` shows the occupied units with the device height and mounting face.
`*` marks primary addresses. In the TUI, `Ctrl+L` shows the same view and
`Ctrl+G` opens the page. Static hosts have no NetBox record; `info` shows their
configured address, user and port.
### Reverse lookup
```sh
netssh whois 10.0.0.7
netssh whois mail.example.com # resolved through DNS first
netssh whois --json 10.0.0.7
```
```
10.0.0.7
IP 10.0.0.7/24 prod/sw1 (device) em0 active dns sw1.example.com
Prefix 10.0.0.0/8 (prod) "internal"
Prefix 10.0.0.0/24 (prod) active site FSN1 vlan 100 (mgmt)
Cache prod/sw1
```
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.
### Status warning
Connecting to a host whose NetBox status is listed in `ssh.warn_status` asks first:
```
prod/web03 has NetBox status "decommissioning" — connect anyway? [y/N]
```
```yaml
ssh:
warn_status: [offline, planned, staged, failed, inventory, decommissioning] # default
# warn_status: [] # never ask
```
`--force` skips the question (`netssh --force web03`). Without a terminal
(scripts, pipes) netssh only prints a warning and connects, so automation keeps
working. `--dry-run` prints the warning as a comment. `copy-id` asks the same
question; `--ignore-status` skips it.
### TUI columns and reachability
`tui.columns` chooses what the TUI shows next to each hostname, in this order:
```yaml
tui:
columns: [reachability, ip, status, site, platform, tags]
reachability_timeout: 300 # ms, only used with the reachability column
```
```
✓ ★ prod/sw1 10.0.0.7 site:fsn1 platform:junos #core
✗ prod/web03 10.0.2.3 [decommissioning] site:nbg1 platform:ubuntu-24-04
```
| Column | Shows |
|---|---|
| `alias` | shortcut alias (`→ fsnbx1`), with `shortcuts.show` |
| `ip` | the address from the cache or NetBox |
| `kind` | `[device]`, `[vm]` or `[static]` |
| `source` | `[live]`, `[static]`, `[cache 5m]`, `stale` |
| `status` | `[offline]` etc. — only when the NetBox status is not `active` |
| `site`, `role`, `platform`, `tenant`, `cluster` | `site:fsn1` — the slug, like in the `Ctrl+F` filter |
| `location` | `⌂ FSN1 › Building A › Room 2.04 › R12 › U20` — site, every nested location, rack and lowest rack unit |
| `tags` | `#prod #web` |
| `reachability` | `✓` / `✗` before the name: TCP check of the SSH port |
Without `tui.columns` the TUI shows `[alias, ip, source, status]`; `columns: []`
shows only the names. Empty values are left out. `netssh configure` →
**History & activity logging** offers the same choice.
The **reachability check is optional** and off by default, because it opens a
TCP connection to every listed host. With the `reachability` column, every host
in the result list is probed on its SSH port (default port, or the static host's
port), in parallel and with `tui.reachability_timeout`. `✓` means the port
answers, `✗` that it does not. Hosts behind a jump host (`proxy_jump`,
`ProxyCommand`) cannot be checked from your machine and get no mark. Each host
is probed once per TUI session.
### Address fallback
```yaml
resolver:
strategies: [management_subnet, primary_ip]
fallback: true
fallback_timeout: 1000 # ms per address
```
With `resolver.fallback`, netssh checks the chosen address before connecting
(ssh, sftp, scp, tunnel). If it does not answer on the SSH port, netssh asks
NetBox for the addresses of all strategies (plus the primary IPv4 and IPv6) and
connects to the first one that answers:
```
netssh: 10.10.0.7 does not answer on port 22, using 192.0.2.7 (primary_ip)
```
The fallback address is used for this connection only; the cache keeps the
address of the configured order. Static hosts, hosts behind a jump host and
`--dry-run` are not checked. When no address answers, netssh still tries the
original one, so ssh reports the actual error.
### Rules by site, role, platform, tenant and status
`ssh.rules[].match` and `commands.*.match` also select by NetBox attributes
(name or slug, case-insensitive; status by value):
```yaml
ssh:
rules:
- match: {platform: junos}
host_key_checking: accept-new
options:
KexAlgorithms: +diffie-hellman-group14-sha1
HostKeyAlgorithms: +ssh-rsa
- match: {site: fsn1, role: core-switch}
proxy_jump: jump-fsn1.example.com
- match: {tenant: customer-a}
options: {User: customer-a} # any layered key
commands:
junos-cli:
args: [ssh, -t, "{address}", cli]
match: {platform: junos, status: active}
```
All selectors of a match must apply. `netssh explain HOST` lists the matching
rule numbers and the host's attributes.
### ssh-copy-id
```sh
netssh copy-id web01
netssh copy-id -i ~/.ssh/id_ed25519.pub tag:lab
netssh copy-id -l root cluster:pve-fsn1 --kind vm
netssh copy-id --dry-run @k8s # print the ssh-copy-id commands
```
Runs `ssh-copy-id` for each host with the same address, user, port, jump host
and `-o` options as `netssh HOST` (a jump host is passed as `-o ProxyJump=`,
since ssh-copy-id has no `-J`). Selectors work like for `netssh multi`. Hosts
run one after another so password prompts stay readable; a failing host does
not stop the others, and the exit code is 1 if any failed. `-f` and `-n` are
passed on to ssh-copy-id.
### known_hosts cleanup
When a live lookup or `netssh cache refresh` finds a new address for a host,
netssh says so:
```
netssh: address of web01 changed from 10.0.0.5 to 10.0.0.9
Remove the known_hosts entry of the old address 10.0.0.5? [y/N]
```
After a host was re-installed (new host key, same address), remove its keys with:
```sh
netssh known-hosts reset web01 # asks first; --yes for scripts
netssh known-hosts reset --dry-run web01 # print the ssh-keygen -R commands
```
Removed are the hostname, the current address, the previously cached address,
and `[name]:port` / `[address]:port` for a non-standard port, using
`ssh-keygen -R` (which keeps `known_hosts.old`). A `UserKnownHostsFile` from
`ssh.options` is honoured.
### Exports: Ansible inventory and ssh_config
```sh
netssh export ansible > inventory.yml # YAML (default)
netssh export ansible --format ini -o hosts.ini # INI
netssh export ansible --group-by site,role,platform # choose groups
netssh export ansible --tag prod --status active --no-static
netssh export ssh-config -o ~/.ssh/netssh.conf # Host blocks for other tools
```
Exports read the cache (run `netssh cache refresh` first) including static hosts.
Filters: `--tag`, `--kind`, `--instance`, `--status`, `--no-static`. A hostname
that exists in several instances is exported as `instance-name`.
**Ansible.** Each host gets `ansible_host` (the address netssh connects to),
`ansible_user`, `ansible_port` (if not 22) and, with a jump host,
`ansible_ssh_common_args: -o ProxyJump=…`. NetBox hosts additionally get
`netbox_instance`, `netbox_kind`, `netbox_status`, `netbox_site`, `netbox_role`,
`netbox_platform`, `netbox_tenant`, `netbox_cluster`, `netbox_location`
(`Building A/Room 2.04`), `netbox_rack`, `netbox_position`, `netbox_id` and
`netbox_tags` (`--no-vars` leaves them out). Groups are named
`<attribute>_<value>` such as `tag_prod`, `site_fsn1`, `platform_junos`;
`--group-by` accepts `tag, site, location, rack, role, platform, tenant, kind,
instance, cluster, status` (default `tag,site,role,platform,kind`) or `none`.
`location` puts a host into a group for every level, e.g. `location_building_a`
and `location_room_2_04`.
```yaml
all:
hosts:
sw1:
ansible_host: 10.0.0.7
ansible_user: admin
ansible_ssh_common_args: -o ProxyJump=jump.example.com
netbox_site: FSN1
netbox_platform: Junos
children:
platform_junos:
hosts:
sw1: {}
```
```ini
[all]
sw1 ansible_host=10.0.0.7 ansible_user=admin ansible_ssh_common_args="-o ProxyJump=jump.example.com" netbox_site=FSN1
[platform_junos]
sw1
```
In INI, `netbox_tags` is a comma-separated string, since INI has no lists.
**ssh_config.** One `Host` block per host with `HostName`, `User`, `Port`,
`ProxyJump`, host key checking, `AddressFamily` and `ssh.options`; shortcut
aliases become extra Host names (`--no-aliases` to skip). Include the file once
from `~/.ssh/config` with `Include ~/.ssh/netssh.conf`. `extra_args`, forwards
and hooks have no ssh_config equivalent and are not exported.
### Keyring tokens
```sh
netssh token migrate # move all tokens from netssh.yaml into the keyring
netssh token set prod # store a token (asked without echo)
echo "$TOKEN" | netssh token set prod
netssh token status # where each instance's token comes from
netssh token delete prod
```
Tokens are stored in the system keyring — Secret Service (GNOME Keyring,
KWallet) on Linux, Keychain on macOS — under the service `netssh` with the
instance name as account (`default` for the unnamed `netbox:` instance). The
config then contains `token: keyring`:
```yaml
netboxes:
- name: prod
url: https://netbox.example.com
token: keyring
```
`netssh doctor` checks that every keyring token can be read. On machines without
a keyring (servers, containers) keep the token in the file or use
`NETSSH_NETBOX_TOKEN`.
## Recipes
**Everything through a bastion, except the bastion itself**