diff --git a/README.md b/README.md index 2326e4e..3141a16 100644 --- a/README.md +++ b/README.md @@ -45,12 +45,16 @@ myf5-cli/ │ ├── ihealth/ # F5 iHealth QKView multipart upload and status client │ ├── bigip/ # BIG-IP & BIG-IQ client (iControl REST chunking, bash promotion, native SCP, failover) │ │ ├── client.go # Appliance HTTP client, readiness, QKView automation, REST download +│ │ ├── info.go # TMOS system, platform, and chassis serial inspection │ │ ├── upload.go # iControl REST chunked file transfer & bash promotion │ │ ├── scp.go # Native Go SCP streaming (upload & download) over SSH │ │ ├── geoip.go # TMOS GeoIP extraction, RPM installation, and reload engine │ │ ├── lifecycle.go # TMOS software (K5903) and hardware (K4309 / K13144) lifecycle evaluation │ │ └── failover.go # Dual-protocol automatic failover engine -│ └── completion/ # Zero-dependency shell tab completion generator (bash, zsh, fish) +│ ├── logger/ # Structured audit & debug logging with automatic secret scrubbing +│ └── progress/ # Terminal progress bar and spinner rendering +├── scripts/ +│ └── gen-sbom.sh # CycloneDX 1.5 SBOM generator with SPDX license metadata ├── .github/ │ ├── workflows/ # GitHub Actions CI, Release, and Security workflows │ ├── ISSUE_TEMPLATE/ # Structured Bug Report & Feature Request templates @@ -61,7 +65,6 @@ myf5-cli/ │ ├── appliance_push.md # Appliance software deployment, hotfix, and GeoDB push guide │ ├── downloads.md # Downloads catalog taxonomy, GeoDB automation & direct push │ ├── credentials.md # Zero-Secret policy & credential management -│ ├── shell_completion.md # Shell tab autocompletion guide (zsh, bash, fish) │ └── network_and_firewall.md # Egress firewall rules, proxy routing, and cloud endpoint architecture ├── Makefile # Developer build, test, and release automation ├── SECURITY.md # Security & vulnerability reporting policy @@ -261,6 +264,12 @@ Works with local management IPs, lab appliances, or cloud/UDF external access pr # Check BIG-IQ management plane readiness ./bin/myf5 bigiq ready 192.0.2.50 +# Inspect BIG-IQ system version, edition, and build details +./bin/myf5 bigiq info 192.0.2.50 --user admin + +# Retrieve BIG-IQ chassis/system serial number +./bin/myf5 bigiq serial 192.0.2.50 --user admin + # Push software ISO to BIG-IQ central repository (auto failover) ./bin/myf5 bigiq push 192.0.2.50 /var/tmp/BIGIP-17.1.1.iso --dest /shared/images @@ -318,30 +327,20 @@ Launch a guided terminal interface that validates input at every step: - Multiline description text buffer supports live editing with undo (`Ctrl+Z`) and redo (`Ctrl+Y`). - Pre-submission dry-run safety review ensures you never open an accidental case against production. -### 11. Interactive Console REPL -Launch an interactive shell session for continuous operation without repeated binary invocations: +### 11. Interactive Console REPL & Tab Completion +Launch an interactive Read-Eval-Print-Loop (REPL) shell with built-in `TAB` autocompletion (for commands, subcommands, and flags), command history, and isolated per-command `Ctrl+C` handling: ```bash ./bin/myf5 interactive +# Or aliases (or invoke `./bin/myf5` with no arguments in a terminal TTY): +./bin/myf5 shell +./bin/myf5 repl ``` - -### 12. Shell Tab Autocompletion (`bash`, `zsh`, `fish`) -Enable fast tab autocompletion for commands, subcommands, flags, and product families: - -```bash -# Zsh (current session) -source <(myf5 completion zsh) - -# Zsh (persistent setup) -myf5 completion zsh > "${fpath[1]}/_myf5" - -# Bash (current session) -source <(myf5 completion bash) - -# Bash (persistent setup on Linux) -myf5 completion bash | sudo tee /etc/bash_completion.d/myf5 > /dev/null - -# Fish (persistent setup) -myf5 completion fish > ~/.config/fish/completions/myf5.fish +Within the interactive shell, run commands directly without the `myf5` prefix and press `TAB` at any prompt to autocomplete commands, subcommands, or flags: +```text +myf5> doctor +myf5> downloads families +myf5> bigip info 10.1.1.4 +myf5> exit ``` --- @@ -393,7 +392,6 @@ myf5 completion fish > ~/.config/fish/completions/myf5.fish | **[Appliance Push & Deployment Guide](docs/appliance_push.md)** | Direct streaming of ISOs, hotfixes, and GeoDB updates to BIG-IP and BIG-IQ via iControl REST and SCP. | | **[MyF5 Downloads & GeoDB Guide](docs/downloads.md)** | Catalog hierarchy, automated GeoDB updates, and end-to-end download & push workflows. | | **[Zero-Secret Security Architecture](docs/credentials.md)** | Process isolation, credentials file permissions, SSH keys, and environment setup. | -| **[Shell Tab Autocompletion](docs/shell_completion.md)** | Setup instructions and completion features for Zsh, Bash, and Fish. | | **[Network, DNS & Firewall Architecture](docs/network_and_firewall.md)** | Egress firewall requirements (TCP 443), proxy routing, and F5 cloud service endpoints. | ### Reference F5 Knowledge Base Articles diff --git a/docs/cli.md b/docs/cli.md index 9757e84..e9ee0e8 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -25,18 +25,17 @@ In accordance with enterprise DevSecOps standards, **passing credentials or toke | :--- | :--- | | [`downloads`](#1-myf5-downloads) | Browse the MyF5 software catalog and stream multi-GB images | | [`cases`](#2-myf5-cases) | Inspect, query, and comment on MyF5 support cases | -| [`wizard`](#11-myf5-wizard) | Interactive guided support case creation wizard with live appliance auto-fill | +| [`wizard`](#10-myf5-wizard) | Interactive guided support case creation wizard with live appliance auto-fill | | [`ihealth`](#3-myf5-ihealth) | Upload and audit QKView diagnostic bundles on F5 iHealth | -| [`bigip`](#4-myf5-bigip) | Orchestrate BIG-IP TMOS appliances (readiness, QKView generation, push, GeoIP) | -| [`bigiq`](#5-myf5-bigiq) | Orchestrate BIG-IQ Centralized Management appliances (readiness, push) | +| [`bigip`](#4-myf5-bigip) | Orchestrate BIG-IP TMOS appliances (readiness, info, serial, QKView generation, push, GeoIP) | +| [`bigiq`](#5-myf5-bigiq) | Orchestrate BIG-IQ Centralized Management appliances (readiness, info, serial, push, download) | | [`push`](#6-myf5-push) | Push downloads or files to BIG-IP / BIG-IQ via iControl REST or SCP | | [`pull`](#7-myf5-pull) | Pull files or diagnostics from BIG-IP / BIG-IQ via iControl REST or SCP | -| [`geoip`](#12-myf5-geoip) | Apply GeoIP updates directly to BIG-IP appliances (alias: `bigip geoip`) | -| [`proxy`](#13-myf5-proxy) | View or configure HTTP/HTTPS/SOCKS5 outbound egress proxy | +| [`geoip`](#11-myf5-geoip) | Apply GeoIP updates directly to BIG-IP appliances (alias: `bigip geoip`) | +| [`proxy`](#12-myf5-proxy) | View or configure HTTP/HTTPS/SOCKS5 outbound egress proxy | | [`doctor`](#8-myf5-doctor) | Run connectivity, DNS, egress, and credential diagnostics | -| [`interactive`](#14-myf5-interactive) | Launch interactive REPL shell with tab completion (`shell`, `repl`) | -| [`completion`](#9-myf5-completion) | Generate native shell autocompletion scripts (`bash`, `zsh`, `fish`) | -| [`version`](#10-myf5-version) | Display application version and toolchain info | +| [`interactive`](#13-myf5-interactive-alias-shell-repl) | Launch interactive REPL shell with tab completion (`shell`, `repl`, `i`) | +| [`version`](#9-myf5-version) | Display application version and toolchain info | --- @@ -309,6 +308,18 @@ Checks BIG-IQ management plane availability against `/mgmt/tm/sys/ready` or `/mg myf5 bigiq ready 192.0.2.50 ``` +#### `info [--user ] [--port ] [--json]` +Inspects a live BIG-IQ appliance to extract system version, edition, build, platform model, and serial number. +```bash +myf5 bigiq info 192.0.2.50 --user admin +``` + +#### `serial [--user ] [--port ] [--json]` +Retrieves and prints the BIG-IQ system serial number. +```bash +myf5 bigiq serial 192.0.2.50 --user admin +``` + #### `push [--method auto|icontrol|scp] [--dest ] [--user ] [--port ] [-i ]` Uploads software images, hotfixes, or files to BIG-IQ central software repositories with automatic failover. ```bash @@ -396,36 +407,7 @@ Output audits: --- -## 9. `myf5 completion` - -Generates tab autocompletion scripts for the specified shell. - -```bash -myf5 completion [bash | zsh | fish] -``` - -### Examples - -```bash -# Zsh (current session) -source <(myf5 completion zsh) - -# Zsh (persistent configuration) -myf5 completion zsh > "${fpath[1]}/_myf5" - -# Bash (current session) -source <(myf5 completion bash) - -# Bash (persistent on Linux) -myf5 completion bash | sudo tee /etc/bash_completion.d/myf5 > /dev/null - -# Fish (persistent) -myf5 completion fish > ~/.config/fish/completions/myf5.fish -``` - ---- - -## 10. `myf5 version` +## 9. `myf5 version` Prints the compiled application version and target architecture. ```bash @@ -434,7 +416,7 @@ myf5 version --- -## 11. `myf5 wizard` +## 10. `myf5 wizard` Top-level alias for `myf5 cases wizard`. Launches an interactive, multi-step terminal wizard to guide you through creating an F5 Support Case with zero memorization of product schema strings: @@ -451,7 +433,7 @@ myf5 wizard --- -## 12. `myf5 geoip` +## 11. `myf5 geoip` Top-level alias for `myf5 bigip geoip`. Uploads, unpacks, installs, and reloads F5 GeoIP database packages directly on a BIG-IP appliance in a single automated command: @@ -468,7 +450,7 @@ myf5 geoip [--keep-extracted] [--method auto|icontrol|scp] [-- --- -## 13. `myf5 proxy` +## 12. `myf5 proxy` Manage outbound HTTP, HTTPS, and SOCKS5 proxy settings for routing API traffic through corporate forward proxies, bastion hosts, or air-gapped jump boxes. @@ -490,28 +472,35 @@ If no `--proxy` flag or persistent configuration is found, `myf5` respects `MYF5 --- -## 14. `myf5 interactive` (alias: `shell`, `repl`) +## 13. `myf5 interactive` (alias: `shell`, `repl`, `i`) -Launches an interactive Read-Eval-Print-Loop (REPL) shell environment with built-in tab autocompletion, command history, and session state: +Launches an interactive Read-Eval-Print-Loop (REPL) shell environment with built-in `TAB` autocompletion, command history, and session state (also launched automatically when invoking `myf5` with no arguments in an interactive terminal TTY): ```bash myf5 interactive # Or shortcuts: myf5 shell myf5 repl +myf5 i ``` +### Interactive Features: +- **Built-In `TAB` Autocompletion**: Press `TAB` at the `myf5>` prompt to autocomplete primary commands (`downloads`, `cases`, `wizard`, `ihealth`, `bigip`, `bigiq`, `push`, `pull`, `geoip`, `proxy`, `doctor`, `interactive`, `version`, `help`, `clear`, `exit`, `quit`), subcommands, and command-specific flags. +- **In-Process Command Isolation**: Failed commands or `Ctrl+C` interrupts cancel only the active command and return cleanly to the `myf5>` prompt without terminating your interactive session. +- **Built-In Shell Commands**: Type `clear` / `cls` to clear the terminal screen, or `exit` / `quit` / `q` (or `Ctrl+D`) to exit. + Within the interactive shell, execute commands directly without the `myf5` prefix: ``` myf5> doctor myf5> downloads families myf5> cases list +myf5> bigip info 10.1.1.4 myf5> exit ``` --- -## 15. Signal Handling & Interruption Safety (CTRL+C) +## 14. Signal Handling & Interruption Safety (CTRL+C) All long-running network connections, streaming file transfers, and appliance operations in `myf5-cli` implement robust interrupt and cancellation handling: - **Clean Signal Traps**: Intercepts `SIGINT` (Ctrl+C) and `SIGTERM` via isolated command contexts (`signal.NotifyContext`). @@ -521,7 +510,7 @@ All long-running network connections, streaming file transfers, and appliance op --- -## 16. Process Exit Codes +## 15. Process Exit Codes `myf5` returns standard POSIX exit codes to support reliable shell script branching and CI/CD pipelines: diff --git a/docs/shell_completion.md b/docs/shell_completion.md deleted file mode 100644 index caf42cb..0000000 --- a/docs/shell_completion.md +++ /dev/null @@ -1,104 +0,0 @@ -# Shell Tab Autocompletion Guide - -`myf5` includes built-in autocompletion generator support for **Zsh**, **Bash**, and **Fish** shells. Shell autocompletion provides tab completion for all commands, subcommands, flags, and file filters. - ---- - -## Installation by Shell - -### 1. Zsh (Default on macOS) - -> [!IMPORTANT] -> **The zsh completion system must be initialised first.** The generated script uses `_arguments`, `_describe`, `_files` and `_hosts`, which do not exist until `compinit` has run. Sourcing it in a shell without `compinit` fails with: -> -> ``` -> _myf5:16: command not found: _arguments -> ``` -> -> Most interactive zsh setups (Oh My Zsh, prezto, the macOS default `~/.zshrc`) already run `compinit`. If yours does not, run `autoload -Uz compinit && compinit` first, or add it to `~/.zshrc` **above** any line that sources completions. - -#### Current Terminal Session -To test autocompletion immediately in the current terminal: -```zsh -autoload -Uz compinit && compinit # only if your shell has not already run it -source <(myf5 completion zsh) -``` - -If `myf5` is not yet on your `PATH`, invoke the binary by path — note that the inner command must still resolve: -```zsh -source <(./bin/myf5 completion zsh) -``` - -#### Persistent Setup (Recommended) -Add autocompletion to `~/.zshrc`: - -```zsh -# Option A: Sourced dynamically in ~/.zshrc -# Must appear AFTER compinit, or the completion functions will not exist yet. -echo 'source <(myf5 completion zsh)' >> ~/.zshrc -source ~/.zshrc - -# Option B: Placed in your zsh completion functions directory (preferred) -# zsh autoloads it on demand, so ordering relative to compinit does not matter. -mkdir -p "${fpath[1]}" -myf5 completion zsh > "${fpath[1]}/_myf5" -``` - ---- - -### 2. Bash - -#### Current Terminal Session -```bash -source <(myf5 completion bash) -``` - -#### Persistent Setup - -##### Linux (Ubuntu / Debian / CentOS / RHEL) -Ensure the `bash-completion` package is installed, then save the completion script to the system completions directory: -```bash -myf5 completion bash | sudo tee /etc/bash_completion.d/myf5 > /dev/null -``` - -##### macOS (with Homebrew Bash) -```bash -myf5 completion bash > $(brew --prefix)/etc/bash_completion.d/myf5 -``` - -##### User Profile (`~/.bashrc`) -```bash -echo 'source <(myf5 completion bash)' >> ~/.bashrc -source ~/.bashrc -``` - ---- - -### 3. Fish - -#### Persistent Setup -Fish automatically loads completions placed in `~/.config/fish/completions/`: - -```fish -mkdir -p ~/.config/fish/completions -myf5 completion fish > ~/.config/fish/completions/myf5.fish -``` - ---- - -## Autocompletion Features - -| Scope | Autocompletion Behavior | -| :--- | :--- | -| **Primary Commands** | Tab completes `downloads`, `cases`, `wizard`, `ihealth`, `bigip`, `bigiq`, `push`, `pull`, `geoip`, `proxy`, `doctor`, `interactive`, `completion`, `version`, `help` with contextual descriptions. | -| **Download Actions** | Tab completes `browse`, `families`, `lines`, `versions`, `containers`, `files`, `get`. | -| **Product Families** | Suggests common F5 product families: `BIG-IP`, `NGINX`, `BIG-IQ`. | -| **Case Actions** | Tab completes `list`, `metadata`, `get`, `comment`, `create`, `wizard`, plus `--all` on `cases list`. | -| **iHealth Actions** | Tab completes `list`, `upload`. | -| **BIG-IP Actions** | Tab completes `ready`, `info`, `serial`, `qkview`, `push`, `download`, `geoip`. | -| **BIG-IQ Actions** | Tab completes `ready`, `push`, `download`. | -| **File Filtering** | When running `myf5 ihealth upload `, autocompletion automatically filters directory listings to `*.qkview`, `*.tar.gz`, `*.tgz` files. | -| **Appliance Push Flags** | Suggests `-m`, `--method` (`auto`, `icontrol`, `scp`), `-d`, `--dest`, `-t`, `--target` (`BIG-IP`, `BIG-IQ`), `-u`, `--user`, `-p`, `--port`, `-i`, `--identity`, `--apply-geoip`. | -| **Download Push Flags** | Suggests `--push`, `--push-method` (`auto`, `icontrol`, `scp`), `--push-dest`, `--push-target`, `--push-user`, `--push-port`, `--push-key`, `--apply-geoip`. | -| **Global Flags** | Suggests `--profile`, `--proxy`, `--insecure`, `-o`, `--output`. | -