122 lines
5.2 KiB
Markdown
122 lines
5.2 KiB
Markdown
# 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
|