feat: NetBox insights, host tools and configurable TUI
Test / test (pull_request) Successful in 4m15s
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:
1 parent
e5bde9c61f
commit
1660bb3098
39 files changed
+4868
-96
No files matched your search
@@ -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**
|
||||
|
||||
Reference in new issue
Block a user