feat: add pre_connect hook and optional shortcut alias display
Test / test (pull_request) Successful in 4m27s
Test / test (pull_request) Successful in 4m27s
- ssh.pre_connect: local shell command run before every connection, layered like proxy_jump (global, instance/static host, rules; "none" disables). Host details are passed as NETSSH_* env vars, a non-zero exit aborts the connection, --dry-run only prints it. - shortcuts.show: show shortcut aliases in the TUI host list, an ALIAS column in `cache list` / `hosts list` (also via --aliases) and in Tab completion. - Both editable in `netssh configure`; README and CHANGELOG updated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017GpWAuVpPncumMViLLc8N4
This commit is contained in:
1 parent
20d7a40543
commit
796925b1a2
15 files changed
+507
-23
No files matched your search
@@ -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), [multiple servers](#multiple-servers-in-one-window), [shortcuts](#host-shortcuts), [TUI](#interactive-tui), [notes](#server-notes), [cache](#cache-management)
|
||||
- [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)
|
||||
- [Hotkey cheat sheet](#hotkey-cheat-sheet) — search, editors, tmux and zellij
|
||||
- [Recipes](#recipes)
|
||||
- [IP Resolution Strategies](#ip-resolution-strategies)
|
||||
@@ -148,12 +148,12 @@ A menu then gives access to every other setting; open only the sections you want
|
||||
| Section | Settings |
|
||||
|---|---|
|
||||
| SSH defaults | `ssh.default_user`, `ssh.default_port` |
|
||||
| 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 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), `pre_connect` |
|
||||
| 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, tmux keys for broadcast and excluding a pane, 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` |
|
||||
| Shortcuts & command alias | domain suffixes, hyphen stripping, rewrite rules (`REGEX => REPLACEMENT` per line), show shortcuts (`shortcuts.show`), `shell.alias` |
|
||||
| Completion | `completion.max_results` |
|
||||
|
||||
The result is validated and saved to `~/.config/netssh.yaml`; Ctrl+C cancels without writing.
|
||||
@@ -228,10 +228,12 @@ Every key, its default, and the section that explains it. Keys marked *layered*
|
||||
| `ssh.extra_args` | list | `[]` | *Layered.* Extra ssh arguments; accumulate across layers; ssh only. |
|
||||
| `ssh.options` | map | `{}` | *Layered.* `-o Key=Value`; per key, the more specific layer wins. |
|
||||
| `ssh.forwards` | map | `{}` | *Layered.* Named port forwards (`local`, `remote`, `dynamic`) — see [Port forwarding](#port-forwarding). |
|
||||
| `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. |
|
||||
| `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). |
|
||||
| `shortcuts.show` | bool | `false` | Show each host's shortcut alias in the TUI, `netssh cache list` and `netssh hosts list`, and offer shortcuts in Tab completion even when the full name matches — see [Showing shortcuts](#showing-shortcuts). |
|
||||
| `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). |
|
||||
@@ -250,8 +252,8 @@ 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_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_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` |
|
||||
| `NETSSH_MULTI_MULTIPLEXER`, `NETSSH_MULTI_PANES_PER_WINDOW` | `multi.*` |
|
||||
| `NETSSH_SHELL_ALIAS` | `shell.alias` |
|
||||
@@ -508,7 +510,7 @@ Tags and kind are taken from the cache or the NetBox answer, so rules work offli
|
||||
|
||||
**How layers combine.** netssh merges global → instance (or the static host's own `ssh`) → matching rules:
|
||||
|
||||
- single values (`proxy_jump`, `host_key_checking`, `target`, `address_family`) — the most specific non-empty value wins;
|
||||
- single values (`proxy_jump`, `host_key_checking`, `target`, `address_family`, `pre_connect`) — the most specific non-empty value wins;
|
||||
- `options` and `forwards` — merged per key or name, the more specific layer wins;
|
||||
- `extra_args` — collected from all layers.
|
||||
|
||||
@@ -519,6 +521,46 @@ $ netssh --dry-run fw01.dmz.example.com
|
||||
ssh -A -l admin -J dmz-jump.example.com -o StrictHostKeyChecking=accept-new -o serveraliveinterval=60 192.0.2.10
|
||||
```
|
||||
|
||||
### Pre-connect hook
|
||||
|
||||
`pre_connect` runs a shell command (`sh -c`) on your machine right before netssh
|
||||
starts ssh, sftp, scp, or a tunnel — for example to check or bring up a VPN, or
|
||||
to log connections. If the command exits non-zero, netssh prints an error and
|
||||
does not connect.
|
||||
|
||||
```yaml
|
||||
ssh:
|
||||
pre_connect: 'wg show wg0 >/dev/null 2>&1 || { echo "VPN wg0 is down" >&2; exit 1; }'
|
||||
rules:
|
||||
- match: {tag: public}
|
||||
pre_connect: none # no VPN needed for these hosts
|
||||
netboxes:
|
||||
- name: lab
|
||||
url: "https://netbox-lab.example.com"
|
||||
ssh:
|
||||
pre_connect: 'lab-vpn up' # this instance needs its own VPN
|
||||
```
|
||||
|
||||
It is a layered setting like `proxy_jump`: global → instance or static host →
|
||||
matching rules, the most specific non-empty value wins, and `none` disables an
|
||||
inherited hook. The hook gets the target in environment variables:
|
||||
|
||||
| Variable | Value |
|
||||
|---|---|
|
||||
| `NETSSH_HOST` | Hostname without instance prefix (`web01.example.com`) |
|
||||
| `NETSSH_TARGET` | Name with instance prefix if any (`prod/web01.example.com`) |
|
||||
| `NETSSH_INSTANCE` | NetBox instance, empty for a single NetBox or static hosts |
|
||||
| `NETSSH_IP` | Resolved address netssh connects to |
|
||||
| `NETSSH_KIND` | `device`, `vm`, or `static` |
|
||||
| `NETSSH_TAGS` | Comma-separated tags |
|
||||
| `NETSSH_CLIENT` | `ssh`, `sftp`, or `scp` |
|
||||
|
||||
The hook's output goes to stderr, so it never mixes with the output of a remote
|
||||
command or an scp transfer; it can read from the terminal (e.g. a VPN password
|
||||
prompt). `--dry-run` prints the hook without running it. `netssh multi` runs it
|
||||
once per pane. It runs only for connections made through netssh, not for a plain
|
||||
`ssh` call.
|
||||
|
||||
### SFTP and SCP
|
||||
|
||||
`netssh sftp` and `netssh scp` look up the host exactly like a connection does: cache, shortcuts and rewrite rules, `instance/host`, default user and port, SSH options and rules, `--jump`/`--no-jump`, and `--dry-run`.
|
||||
@@ -708,6 +750,27 @@ Domains may be configured with or without a leading dot. If several cached hosts
|
||||
| `fsn1web01` | `domains: [.example.com]`, `strip_hyphens: true` | `fsn1-web01.example.com` (cache only) |
|
||||
| `fsnbx1` | `domains: [.hoster.de]`, rewrite `^([a-z]+)[0-9]+-` → `$1` | `fsn1-bx1.hoster.de` (cache only) |
|
||||
|
||||
#### Showing shortcuts
|
||||
|
||||
By default shortcuts work but stay out of sight. Set `shortcuts.show: true`
|
||||
(or **Show shortcuts** in `netssh configure`, or `NETSSH_SHORTCUTS_SHOW=true`)
|
||||
to see them:
|
||||
|
||||
- **TUI** — each host shows its alias next to the name: `fsn1-bx1.hoster.de → fsnbx1 10.0.0.5`.
|
||||
- **Lists** — `netssh cache list` and `netssh hosts list` get an `ALIAS` column. Without the setting, `--aliases` shows it for one call.
|
||||
- **Tab completion** — shortcuts are offered even when the full name matches what you typed: `fsn<Tab>` lists `fsn1-bx1.hoster.de` and `fsnbx1`.
|
||||
|
||||
The alias shown is the shell alias netssh generates for the host (see [Shell
|
||||
aliases](#shell-aliases)), so you can type it directly. Hosts whose alias would
|
||||
only replace dots (`web01_example_com`) show none.
|
||||
|
||||
```sh
|
||||
$ netssh cache list --aliases
|
||||
NAME ALIAS IP KIND CACHED AT
|
||||
fsn1-bx1.hoster.de fsnbx1 10.0.0.5 device 2026-11-17T07:30:00+01:00
|
||||
web01.other.de - 10.0.0.9 vm 2026-11-17T07:30:00+01:00
|
||||
```
|
||||
|
||||
### Shell aliases
|
||||
|
||||
Generate shell aliases for all cached hosts based on the shortcut settings:
|
||||
@@ -808,6 +871,7 @@ See the [NetBox REST API documentation](https://netbox.readthedocs.io/en/stable/
|
||||
|
||||
```sh
|
||||
netssh cache list # show all cached entries
|
||||
netssh cache list --aliases # … with each host's shortcut alias
|
||||
netssh cache refresh # re-fetch ALL hosts from NetBox (paginated)
|
||||
netssh cache refresh --tag prod # only hosts with the "prod" tag
|
||||
netssh cache refresh --kind vm # only virtual machines
|
||||
|
||||
Reference in new issue
Block a user