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 root@host
5. Writes execution logs to ~/netupgrade.log
6. Opens the log in nano, then optionally removes it

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 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

2. Shell robustness concerns

• Node parsing relies on replacing ; with spaces and re-splitting: this is fragile if values contain spaces or special characters
• Quoting is inconsistent across the script
• Config files are sourced directly, which is flexible but implies arbitrary code execution
• The script does not use a stricter shell safety baseline

3. Remote execution correctness and safety

• SSH user is hardcoded to root
• cmd:<...> intentionally allows arbitrary remote command execution, which should be treated as a powerful unsafe feature
• Some remote command constructions are brittle
• The pacman orphan-removal command appears incorrect because command substitution is evaluated locally instead of remotely
• 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
• 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

• 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

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

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