netupgrade/state.md

Repository analysis

Project overview

• Project name: netupgrade
• Primary language: Bash
• Main entrypoint: bin/netupgrade
• Project type: interactive CLI administration tool
• Main purpose: orchestrate remote upgrade and maintenance actions on multiple hosts over SSH
• Configuration model: Bash-based configuration files sourced from ~/.config/netupgrade/*.cfg

Repository structure

• bin/netupgrade: main executable script containing CLI parsing, node selection, remote execution, and logging
• config/netupgrade/*.cfg: sample configuration files defining host groups and action sequences
• README.md: installation and usage documentation
• docs/: project documentation

Functional behavior

The tool:

1. Loads a Bash configuration file
2. Expects a NODES array populated with entries formatted like: host;display-name;action1;action2;...
3. Displays an interactive multi-select checklist using whiptail
4. Executes the selected actions on each selected host through SSH, using root@host by default or SSH_USER@host when configured
5. Writes execution logs to ~/netupgrade.log
6. Opens the log with $EDITOR when available, otherwise nano, vi, or less; if none is available, it prints the log path, then optionally removes the log file

Supported action types currently include:

• apt
• yum
• pkg
• pacman
• apk
• reboot
• cmd:<remote command>
• docker-stacks:<directory>

Architecture notes

• The project is intentionally lightweight and script-based
• Configuration is code-driven rather than declarative, since config files are sourced as shell files
• The entire execution flow currently lives in a single Bash script
• Remote operations are performed sequentially, not in parallel
• Logging is file-based and coupled directly to command execution

Strengths

• Very small and easy to deploy
• Clear practical purpose for system administration workflows
• Flexible host/action configuration model
• Supports several Linux/BSD package managers
• Suitable for use from a bastion host or admin workstation

Main issues identified

1. Documentation accuracy problems

• 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

• Config files are sourced directly, which is flexible but implies arbitrary code execution
• The script still has some quoting-sensitive areas and does not use a stricter shell safety baseline
• The NODES parsing was hardened to split on ; with IFS/read -r -a, which now preserves spaces in action values such as cmd:...

3. Remote execution correctness and safety

• SSH execution now goes through a dedicated runSSH helper and the SSH user is configurable via SSH_USER, defaulting to root
• cmd:<...> intentionally allows arbitrary remote command execution and is now executed through a remote shell, which improves support for shell operators but remains a powerful unsafe feature
• The pacman orphan-removal command was corrected so orphan detection happens on the remote host instead of locally
• The docker-stacks remote loop was rewritten to pass the stack root as an argument to a remote shell script, improving quoting and path handling

4. UX and dependency issues

• Required runtime dependencies are now checked at startup (ssh, whiptail, sed, tee, rm, touch)
• Log viewing no longer depends strictly on nano; the script now falls back to $EDITOR, then nano, vi, or less
• If no supported log viewer is available, execution continues and the log path is shown
• 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

5. Error handling limitations

• Error propagation is inconsistent depending on the action type
• Cleanup commands often do not affect the final failure state
• The script continues through action sequences without a documented policy
• The advertised “break on error” behavior does not exist yet

6. Maintainability limitations

• Most logic is concentrated in one script
• There is duplication in package-manager handling
• No tests or validation tooling are present in the repository
• Some wording, typos, and naming inconsistencies reduce clarity

Recommended direction

Short term

• Review the remaining quoting-sensitive areas, especially around remote shell command construction
• Consider making log path and editor configurable
• Revisit the log summary insertion method, which still relies on sed -i string interpolation

Medium term

• Improve parsing of node entries to avoid whitespace-splitting issues
• Make SSH user, log path, and editor configurable
• Improve non-interactive usage options
• Standardize error handling and exit codes

Long term

• Refactor the script into smaller functions with less duplication
• Add shell linting guidance (for example ShellCheck)
• 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
• Log viewer selection was made more flexible: $EDITOR is preferred, then nano, vi, or less
• nano is no longer a strict runtime dependency
• The unsupported -b option remains unimplemented and is no longer shown in help output
• NODES parsing was hardened to preserve spaces in action values by splitting on ; with IFS and read -r -a
• SSH calls were centralized through a runSSH helper and SSH_USER is now configurable, defaulting to root
• The pacman orphan cleanup now runs entirely on the remote host instead of evaluating orphan detection locally
• The docker-stacks action was rewritten to use a remote shell script with the stack directory passed as an argument
• Unknown actions and reboot SSH failures now propagate error status more consistently

Change guidance

• Preserve backward compatibility for existing config files where possible
• Prefer incremental hardening over a full rewrite
• Keep the tool simple and admin-friendly
• Be cautious with changes to remote command construction, as quoting changes can introduce regressions

Suggested review focus for future changes

• Correctness of remote command execution
• Safe quoting and shell expansion behavior
• Compatibility of config format with existing user setups
• Usability in both interactive and semi-automated contexts