From 2ed34b97bef943a79a183a4abdc2aa8b71be5039 Mon Sep 17 00:00:00 2001 From: MatMoul Date: Sat, 25 Apr 2026 23:59:28 +0200 Subject: [PATCH] docs: expand netupgrade usage and configuration docs Update the README with installation, requirements, supported actions, config format, and usage details. Align the CLI help text with current behavior and add startup checks for required runtime dependencies. --- README.md | 97 +++++++++++++++++++++++++++++++++++++++++++------- bin/netupgrade | 19 +++++++--- state.md | 23 +++++++----- 3 files changed, 113 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 338c23d..9fcc652 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,105 @@ # netupgrade -Servers full upgrade script +Interactive CLI tool to run upgrade and maintenance actions on multiple remote hosts over SSH. ## Where to use -- On a dedicated server (bastion, ...) +- On a dedicated server (bastion, jump host, ...) - On your computer with an alias to your dedicated server -- On your computer (not recommended) +- On your computer directly (not recommended) + +## Features + +- Select one or more hosts from an interactive checklist +- Run predefined actions on each selected host +- Write execution logs to `~/netupgrade.log` + +Supported actions: + +- `apt` +- `yum` +- `pkg` +- `pacman` +- `apk` +- `reboot` +- `cmd:` +- `docker-stacks:` + +## Requirements + +- `bash` +- `ssh` +- `whiptail` +- `nano` +- `sed` +- `tee` ## Install -### Bin as root +### Install the executable -``` bash -cp bin/netupgrade to /usr/local/bin +```bash README.md +cp bin/netupgrade /usr/local/bin/netupgrade +chmod +x /usr/local/bin/netupgrade ``` -### Config as user +### Create the config directory -``` bash -mkdir -p ~/.config/netuprade -touch ~/.config/netuprade/index.cfg +```bash README.md +mkdir -p ~/.config/netupgrade +touch ~/.config/netupgrade/index.cfg ``` ### Alias on your computer with a dedicated server -You can save it in your .bashrc +You can save it in your `.bashrc` -``` bash +```bash README.md alias netupgrade='ssh -t user@10.0.0.10 netupgrade' ``` + +## Configuration + +The default config file is: + +```text README.md +~/.config/netupgrade/index.cfg +``` + +The script sources this file as Bash code. It must define a `NODES` array. + +Each entry uses this format: + +```text README.md +host;display-name;action1;action2;... +``` + +Example: + +```bash README.md +NODES=( + "192.168.1.10;web-01;apt;reboot" + "192.168.1.11;db-01;apt;cmd:systemctl restart postgresql" + "192.168.1.12;docker-01;docker-stacks:/opt/stacks" +) +``` + +## Usage + +```bash README.md +netupgrade [--help] [-f] [-y] [configfilename] +``` + +Options: + +- `--help`: show help +- `-f`: preselect all nodes +- `-y`: pass non-interactive confirmation flags to supported package managers +- `configfilename`: path to a config file + +## Notes + +- SSH connections currently use `root@host` +- The tool is interactive and intended for manual administration workflows +- After execution, the log file is opened in `nano` +- The configuration file is sourced as shell code, so only use trusted config files diff --git a/bin/netupgrade b/bin/netupgrade index fb8a6de..583b6db 100755 --- a/bin/netupgrade +++ b/bin/netupgrade @@ -1,12 +1,20 @@ #!/bin/bash showHelp() { - echo "netupgrade [-f] [-y] [configfilename]" + echo "netupgrade [--help] [-f] [-y] [configfilename]" echo "" - echo " -f : Select all nodes" - echo " -y : No confirmation" - echo " -b : Breack on error" - echo " configfilename : a cfg filename" + echo " --help Show this help message" + echo " -f Select all nodes" + echo " -y No confirmation for supported package managers" + echo " configfilename Path to a cfg file" +} + +checkDependencies() { + command -v ssh >/dev/null 2>&1 || { echo "Error: ssh is required"; exit 1; } + command -v whiptail >/dev/null 2>&1 || { echo "Error: whiptail is required"; exit 1; } + command -v nano >/dev/null 2>&1 || { echo "Error: nano is required"; exit 1; } + command -v sed >/dev/null 2>&1 || { echo "Error: sed is required"; exit 1; } + command -v tee >/dev/null 2>&1 || { echo "Error: tee is required"; exit 1; } } pressAnyKey(){ @@ -238,6 +246,7 @@ while [[ ${#} -gt 0 ]]; do esac done +checkDependencies loadConfig selectNodes diff --git a/state.md b/state.md index 09e9bce..62d318a 100644 --- a/state.md +++ b/state.md @@ -51,10 +51,10 @@ Supported action types currently include: ## Main issues identified ### 1. Documentation accuracy problems -- `README.md` contains a typo in the configuration path (`netuprade` instead of `netupgrade`) -- The CLI help mentions `-b` but that option is not implemented -- `--help` exists in code but is not documented in the displayed usage -- The configuration format is not documented in enough detail +- `README.md` and CLI help were updated to better match current behavior +- The previous typo in the configuration path (`netuprade`) has been fixed +- The unsupported `-b` option was removed from the displayed help +- The configuration format and supported actions are now documented in more detail ### 2. Shell robustness concerns - Node parsing relies on replacing `;` with spaces and re-splitting: @@ -71,8 +71,7 @@ Supported action types currently include: - The `docker-stacks` remote loop should be reviewed carefully for quoting and path safety ### 4. UX and dependency issues -- `whiptail` is required for selection but is not checked before use -- `nano` is required for log viewing but is not checked before use +- Required runtime dependencies are now checked at startup (`ssh`, `whiptail`, `nano`, `sed`, `tee`) - The workflow is highly interactive and not well suited for automation - `rm -i` introduces an extra prompt even when the rest of the flow is meant to be streamlined @@ -91,10 +90,10 @@ Supported action types currently include: ## Recommended direction ### Short term -- Fix documentation and help output to match actual behavior - Correct the remote command bugs, especially for `pacman` -- Add dependency checks for required external tools -- Either implement or remove unsupported CLI options such as `-b` +- Improve parsing of node entries to avoid whitespace-splitting issues +- Review `docker-stacks` remote command quoting and behavior +- Consider making SSH user, log path, and editor configurable ### Medium term - Improve parsing of node entries to avoid whitespace-splitting issues @@ -108,6 +107,12 @@ Supported action types currently include: - Consider a safer declarative configuration format if the project grows - Add test coverage for parsing and command construction +## Recent changes +- `README.md` was expanded to document installation, requirements, usage, configuration format, and supported actions +- `bin/netupgrade` help output was aligned with actual CLI behavior and now documents `--help` +- A startup dependency check was added before loading configuration or opening the interactive selector +- The unsupported `-b` option remains unimplemented and is no longer shown in help output + ## Change guidance - Preserve backward compatibility for existing config files where possible - Prefer incremental hardening over a full rewrite