docs: document SSH options, uninstall, and zsh completion for v0.0.21
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Sebastian UnterschützandClaude Opus 5.5 committed
1 parent
c2e590bf52
commit
6711b610f1
2 files changed
+135
-12
No files matched your search
@@ -32,6 +32,9 @@ netssh -p 2222 admin@app-server-03 uptime
|
||||
- **Host shortcuts** — type `web01` instead of `web01.example.com`; configurable domain strip and hyphen folding
|
||||
- **Shell aliases** — `netssh alias` generates shell aliases for all cached hosts
|
||||
- **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`
|
||||
- **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
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -135,6 +138,11 @@ cache:
|
||||
ssh:
|
||||
default_user: admin # used when no user is specified on the command line
|
||||
default_port: 2222 # optional; injected as -p if not specified on the command line
|
||||
# See "SSH options" below for proxy_jump, host_key_checking, target,
|
||||
# address_family, extra_args, options, and rules.
|
||||
|
||||
completion:
|
||||
max_results: 0 # hostnames offered per <Tab>; 0 = unlimited
|
||||
|
||||
shortcuts:
|
||||
domains: # strip these suffixes to create short aliases
|
||||
@@ -240,6 +248,74 @@ netssh -i ~/.ssh/id_rsa -o StrictHostKeyChecking=no db-primary
|
||||
|
||||
The process is replaced by `ssh` with the resolved IP — your `~/.ssh/config`, agent, and keys all work as normal.
|
||||
|
||||
### Dry run and version
|
||||
|
||||
```sh
|
||||
netssh --dry-run web01 # print the final ssh command instead of connecting
|
||||
netssh --version # or: netssh version
|
||||
```
|
||||
|
||||
Long options (`--dry-run`, `--jump`, `--no-jump`) are netssh's own; OpenSSH has
|
||||
no long options. They must come before the hostname — everything after the
|
||||
hostname is the remote command.
|
||||
|
||||
### SSH options
|
||||
|
||||
All settings below go under `ssh:`. The same keys (except `rules`) can be set
|
||||
per NetBox instance under `netboxes[].ssh` (or `netbox.ssh`), and per rule.
|
||||
More specific settings win: global → instance → matching rules (in order) →
|
||||
command-line flags. Options you pass on the command line always take precedence
|
||||
over the config.
|
||||
|
||||
```yaml
|
||||
ssh:
|
||||
proxy_jump: "jumphost.example.com" # passed as -J; "none" disables an inherited jump host
|
||||
host_key_checking: accept-new # strict | accept-new | off; unset = ssh's own setting
|
||||
target: ip # ip (default) | name | hostname
|
||||
address_family: inet # any | inet (-4) | inet6 (-6)
|
||||
extra_args: ["-A"] # inserted before your own arguments
|
||||
options: # passed as -o Key=Value
|
||||
ServerAliveInterval: 60
|
||||
ServerAliveCountMax: 5
|
||||
rules: # every set match field must match
|
||||
- match: {tag: dmz} # tag name or slug
|
||||
proxy_jump: "dmz-jump.example.com"
|
||||
- match: {instance: lab, name: "*.lab.example.com", kind: vm}
|
||||
host_key_checking: off
|
||||
|
||||
netboxes:
|
||||
- name: prod
|
||||
url: "https://netbox.example.com"
|
||||
token: "nbt_…"
|
||||
ssh:
|
||||
proxy_jump: "jumphost.example.com"
|
||||
- name: staging
|
||||
url: "https://netbox-staging.example.com"
|
||||
token: "nbt_…"
|
||||
ssh:
|
||||
host_key_checking: off
|
||||
```
|
||||
|
||||
**Jump hosts.** Override the configured jump host for a single call with
|
||||
`--jump other.example.com` (or ssh's own `-J`), or disable all jump hosts —
|
||||
including `ProxyJump` from `~/.ssh/config` — with `--no-jump`.
|
||||
|
||||
**Host key checking.** `strict` sets `StrictHostKeyChecking=yes`, `accept-new`
|
||||
accepts keys of new hosts but rejects changed ones. `off` sets
|
||||
`StrictHostKeyChecking=no`, `UserKnownHostsFile=/dev/null`, and `LogLevel=ERROR`
|
||||
for netssh connections only and prints a short notice. Use it only for hosts
|
||||
that are reinstalled often, such as staging; it disables protection against
|
||||
man-in-the-middle attacks.
|
||||
|
||||
**Connection target.** By default netssh calls `ssh <ip>`. With `target: name`,
|
||||
it calls `ssh -o HostName=<ip> -o HostKeyAlias=<name> <name>`: the resolved IP
|
||||
is still used, but `Host *.example.com` rules in `~/.ssh/config` apply, and
|
||||
known_hosts entries belong to the device instead of an IP that may be reused.
|
||||
With `target: hostname`, ssh resolves the NetBox name itself (DNS or
|
||||
`~/.ssh/config`). Names that are not valid hostnames fall back to the IP.
|
||||
Switching to `name` stores new known_hosts entries under the device name, so
|
||||
ssh asks once to confirm each host key.
|
||||
|
||||
### Default username
|
||||
|
||||
Set `ssh.default_user` in the config to avoid typing a username every time:
|
||||
@@ -422,7 +498,7 @@ netssh hook install --shell zsh
|
||||
netssh hook install --shell fish
|
||||
```
|
||||
|
||||
This appends a single line (`netssh shell-init`) to your shell profile. To remove it:
|
||||
This adds a marked block (`# >>> netssh >>>` … `# <<< netssh <<<`) to your shell profile. To remove it:
|
||||
|
||||
```sh
|
||||
netssh hook uninstall
|
||||
@@ -465,14 +541,20 @@ netssh completion install --shell fish
|
||||
| zsh | `~/.zfunc/_netssh` |
|
||||
| fish | `~/.config/fish/completions/netssh.fish` |
|
||||
|
||||
For zsh, make sure `~/.zfunc` is in your `fpath` (add to `~/.zshrc`):
|
||||
For zsh, the netssh block in `~/.zshrc` (written by the installer and by
|
||||
`netssh hook install --shell zsh`) adds `~/.zfunc` to `fpath` and registers the
|
||||
completion with `compdef`, also when `compinit` already ran earlier — for
|
||||
example via oh-my-zsh. Without the block, add `fpath=(~/.zfunc $fpath)` before
|
||||
`compinit`. If `<Tab>` still completes files, clear the completion cache:
|
||||
|
||||
```zsh
|
||||
fpath=(~/.zfunc $fpath)
|
||||
autoload -Uz compinit && compinit
|
||||
rm -f ~/.zcompdump* && exec zsh
|
||||
```
|
||||
|
||||
Completions are served from the local cache — no network request on every `<Tab>`.
|
||||
The zsh script that `netssh completion zsh` prints is built for large caches:
|
||||
5000 hosts complete in well under a second. To limit the number of hostnames
|
||||
offered, set `completion.max_results`.
|
||||
|
||||
## Shell Hook
|
||||
|
||||
@@ -502,15 +584,25 @@ Reload with: source /home/user/.bashrc
|
||||
|
||||
What gets written to the profile:
|
||||
|
||||
**bash / zsh** (`~/.bashrc` or `~/.zshrc`):
|
||||
**bash** (`~/.bashrc`):
|
||||
```bash
|
||||
netssh shell-init # netssh cache auto-refresh
|
||||
source ~/.cache/netssh/aliases.sh 2>/dev/null # netssh aliases
|
||||
# >>> netssh >>>
|
||||
netssh shell-init
|
||||
[ ! -f '/home/user/.cache/netssh/aliases.sh' ] || . '/home/user/.cache/netssh/aliases.sh'
|
||||
# <<< netssh <<<
|
||||
```
|
||||
|
||||
**zsh** (`~/.zshrc`) additionally registers the completion:
|
||||
```zsh
|
||||
fpath=('/home/user/.zfunc' $fpath)
|
||||
if (( $+functions[compdef] )); then autoload -Uz _netssh && compdef _netssh netssh; fi
|
||||
```
|
||||
|
||||
**fish** (`~/.config/fish/config.fish`):
|
||||
```fish
|
||||
netssh shell-init # netssh cache auto-refresh
|
||||
# >>> netssh >>>
|
||||
netssh shell-init
|
||||
# <<< netssh <<<
|
||||
```
|
||||
|
||||
Fish alias file (`~/.config/fish/conf.d/netssh.fish`) is written automatically and sourced by fish on every shell start without any profile changes.
|
||||
@@ -521,7 +613,7 @@ Fish alias file (`~/.config/fish/conf.d/netssh.fish`) is written automatically a
|
||||
| zsh | `~/.zshrc` | `~/.cache/netssh/aliases.sh` |
|
||||
| fish | `~/.config/fish/config.fish` | `~/.config/fish/conf.d/netssh.fish` |
|
||||
|
||||
The install is idempotent — running it again changes nothing if the lines are already present.
|
||||
The install is idempotent — running it again changes nothing if the block is already present. Unmarked lines written by older versions are replaced by the block.
|
||||
|
||||
Reload your profile after installation to activate immediately:
|
||||
|
||||
@@ -550,7 +642,7 @@ netssh hook uninstall # auto-detects $SHELL
|
||||
netssh hook uninstall --shell zsh
|
||||
```
|
||||
|
||||
Removes both the `netssh shell-init` line and the `source aliases.sh` line from the profile. The alias files (`aliases.sh`, `netssh.fish`) are left on disk — delete them manually if desired.
|
||||
Removes the netssh block and unmarked entries of older versions from the profile. The alias files (`aliases.sh`, `netssh.fish`) are left on disk. To remove netssh completely, use `netssh uninstall`.
|
||||
|
||||
### Relation to the connect-time auto-refresh
|
||||
|
||||
@@ -563,6 +655,24 @@ The shell hook and the connect-time trigger (which fires on each `netssh` invoca
|
||||
|
||||
Both are non-blocking — the refresh runs as a background process and never delays your prompt or SSH connection. They share `~/.cache/netssh/last_refresh`, so only one background refresh runs per 24-hour window regardless of how many shells or connections are opened.
|
||||
|
||||
## Uninstall
|
||||
|
||||
```sh
|
||||
netssh uninstall --dry-run # show what would be removed
|
||||
netssh uninstall # asks for confirmation
|
||||
netssh uninstall --keep-config # keep config and notes for a reinstall
|
||||
```
|
||||
|
||||
`netssh uninstall` removes:
|
||||
|
||||
- netssh blocks and unmarked entries of older versions from `~/.bashrc`, `~/.bash_profile`, `~/.bash_login`, `~/.profile`, `~/.zshrc`, `~/.zprofile`, `~/.zshenv`, and `config.fish`
|
||||
- completion files for bash, zsh (also the oh-my-zsh cache), fish, and the command alias
|
||||
- the cache directory `~/.cache/netssh/` including per-instance caches and aliases
|
||||
- `~/.config/netssh.yaml` (a private backup `netssh.yaml.backup-<timestamp>` is kept, because it contains API tokens) and local notes
|
||||
- the netssh binary; if it is in a protected directory, netssh prints the `sudo rm` command to run
|
||||
|
||||
Afterwards open a new terminal; for zsh also run `rm -f ~/.zcompdump*`.
|
||||
|
||||
## Development
|
||||
|
||||
Renovate monitors the release workflow's actions, the Go version in `go.mod`, and
|
||||
@@ -582,9 +692,9 @@ 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`, `search`, `cache`, `completion`). If not, it enters SSH wrapper mode.
|
||||
1. `netssh` checks whether the first argument is a known subcommand (`configure`, `search`, `cache`, `completion`, `version`, `uninstall`, …). If not, it enters SSH wrapper mode.
|
||||
2. On first run or when `netbox.url` is empty, the interactive setup wizard starts automatically.
|
||||
3. It parses the SSH arguments to extract the destination hostname, handling all flags that consume an extra argument (`-p`, `-i`, `-J`, …).
|
||||
4. It resolves the destination: first an exact cache lookup, then shortcut expansion (domain append, hyphen folding) against the cache, and finally a fresh NetBox query with the expanded name. If the cache entry is within the TTL, no network request is made.
|
||||
5. Otherwise it queries NetBox (`/api/dcim/devices/` and `/api/virtualization/virtual-machines/` in parallel), runs the result through the resolver chain, and caches the IP.
|
||||
6. It calls `syscall.Exec` to replace itself with `ssh`, substituting the hostname with the resolved IP.
|
||||
6. It adds the configured SSH options for the host (jump host, host key checking, `-o` options) before the destination and calls `syscall.Exec` to replace itself with `ssh`, substituting the hostname with the resolved IP (or the name, with `ssh.target: name`).
|
||||
Reference in new issue
Block a user