201 lines
6.9 KiB
Markdown
201 lines
6.9 KiB
Markdown
# Documentation Corrections Summary
|
|
|
|
This document lists all corrections made to the socktop documentation to align with the actual implementation as documented in the official README.
|
|
|
|
## Date: 2025-01-XX
|
|
|
|
## Critical Corrections Made
|
|
|
|
### 1. Missing GPU Dependencies ✅ FIXED
|
|
|
|
**Issue:** Documentation failed to mention required GPU support libraries.
|
|
|
|
**Fix:** Added `libdrm-dev` and `libdrm-amdgpu1` to:
|
|
- `docs/src/installation/prerequisites.md`
|
|
- `docs/src/installation/quick-start.md`
|
|
- `docs/src/installation/apt.md`
|
|
- `docs/src/installation/cargo.md`
|
|
|
|
**Reason:** These libraries are explicitly required in the README for GPU metrics support on Raspberry Pi, Ubuntu, and PopOS.
|
|
|
|
---
|
|
|
|
### 2. TLS Certificate Auto-Generation ✅ FIXED
|
|
|
|
**Issue:** Documentation incorrectly instructed users to manually generate certificates with OpenSSL.
|
|
|
|
**Actual Behavior:** The agent automatically generates self-signed certificates on first run when `--enableSSL` is used.
|
|
|
|
**Files Updated:**
|
|
- `docs/src/security/tls.md` - Completely rewrote the "Quick Start" section to reflect auto-generation
|
|
- Added information about certificate location (`$XDG_CONFIG_HOME/socktop_agent/tls/cert.pem`)
|
|
- Added information about `SOCKTOP_AGENT_EXTRA_SANS` environment variable
|
|
- Updated certificate renewal section to explain simple deletion and restart process
|
|
|
|
**Key Changes:**
|
|
- Changed from manual OpenSSL commands to simple `socktop_agent --enableSSL --port 8443`
|
|
- Documented that certificate is auto-generated and location is printed on first run
|
|
- Updated expiry information (~397 days)
|
|
- Moved manual generation to "Manual Certificate Generation" section for advanced users only
|
|
|
|
---
|
|
|
|
### 3. Fabricated Command-Line Options ✅ FIXED
|
|
|
|
**Issue:** Documentation extensively referenced non-existent options.
|
|
|
|
**Fabricated Options:**
|
|
- `--refresh-rate` (does not exist)
|
|
- `--ca-cert` (actual flag is `--tls-ca`)
|
|
- `--no-verify-tls` (does not exist in this form)
|
|
|
|
**Correct Options:**
|
|
- `--metrics-interval-ms` (default: 500ms) - Controls fast metrics polling
|
|
- `--processes-interval-ms` (default: 2000ms) - Controls process list polling
|
|
- `--tls-ca` - Specify CA certificate for TLS verification
|
|
- `--verify-hostname` - Enable strict hostname verification
|
|
|
|
**Files Updated:**
|
|
- `docs/src/usage/general.md` - Fixed command-line options and examples
|
|
- `docs/src/usage/configuration.md` - Fixed interval examples
|
|
- `docs/src/usage/connection-profiles.md` - Fixed override examples
|
|
- `docs/src/security/tls.md` - Fixed TLS option references
|
|
- `docs/src/security/token.md` - Fixed CA cert flag
|
|
|
|
---
|
|
|
|
### 4. Profile Format Fabrication ✅ FIXED
|
|
|
|
**Issue:** Documentation claimed profiles are stored in TOML format.
|
|
|
|
**Actual Format:** Profiles are stored as JSON in `~/.config/socktop/profiles.json`
|
|
|
|
**Correct Structure:**
|
|
```json
|
|
{
|
|
"profiles": {
|
|
"prod": {
|
|
"url": "ws://prod-host:3000/ws",
|
|
"tls_ca": "/path/to/cert.pem",
|
|
"metrics_interval_ms": 500,
|
|
"processes_interval_ms": 2000
|
|
}
|
|
},
|
|
"version": 0
|
|
}
|
|
```
|
|
|
|
**Files Updated:**
|
|
- `docs/src/usage/connection-profiles.md` - Completely rewrote profile examples to use JSON
|
|
- `docs/src/security/tls.md` - Fixed profile examples
|
|
- `docs/src/security/token.md` - Fixed profile examples and file paths
|
|
|
|
**Note:** Many examples in connection-profiles.md still need updating (see "Remaining Issues" below).
|
|
|
|
---
|
|
|
|
### 5. Protocol Description ✅ FIXED
|
|
|
|
**Issue:** Documentation claimed WebSocket protocol uses Protocol Buffers.
|
|
|
|
**Actual Protocol:** JSON over WebSocket (as stated in README: "Remote monitoring via WebSocket (JSON over WS)")
|
|
|
|
**Files Updated:**
|
|
- `docs/src/introduction.md` - Changed "Protocol Buffers" to "JSON"
|
|
|
|
---
|
|
|
|
### 6. Demo Mode Documentation ✅ ADDED
|
|
|
|
**Issue:** Documentation did not mention the built-in demo mode feature.
|
|
|
|
**Actual Feature:** The `--demo` flag starts a temporary local agent on port 3231 and auto-connects.
|
|
|
|
**Files Updated:**
|
|
- `docs/src/installation/quick-start.md` - Added "Option 3: Demo Mode" section
|
|
- `docs/src/usage/general.md` - Added "Demo Mode" as first usage option
|
|
- `docs/src/introduction.md` - Added demo mode to features and quick start section
|
|
|
|
**Key Information Added:**
|
|
- `socktop --demo` launches temporary agent on port 3231
|
|
- Agent stops automatically when you quit
|
|
- Interactive profile selection menu includes built-in `demo` option
|
|
- Perfect for testing, learning, and demos without agent setup
|
|
|
|
---
|
|
|
|
## Remaining Issues (Known)
|
|
|
|
### Connection Profiles Documentation
|
|
|
|
The file `docs/src/usage/connection-profiles.md` still contains many TOML examples that should be JSON:
|
|
|
|
- Lines ~233-243: Production server examples
|
|
- Lines ~265-274: Refresh rate examples (also using wrong option names)
|
|
- Lines ~280-287: Environment variable examples
|
|
- Lines ~293-302: Template examples
|
|
- Lines ~309-319: Raspberry Pi cluster examples
|
|
- Lines ~329-339: AWS examples
|
|
- Lines ~349-359: Datacenter examples
|
|
- Lines ~372-401: Troubleshooting section references
|
|
|
|
**Recommendation:** These should be converted to JSON format or removed in favor of simpler examples.
|
|
|
|
### Configuration Documentation
|
|
|
|
The file `docs/src/usage/configuration.md` may reference TOML in the configuration hierarchy section (line ~9).
|
|
|
|
---
|
|
|
|
## Verification Checklist
|
|
|
|
Before deploying documentation:
|
|
|
|
- [ ] All `--refresh-rate` references removed
|
|
- [ ] All `--ca-cert` changed to `--tls-ca`
|
|
- [ ] All `--no-verify-tls` references updated to explain proper behavior
|
|
- [ ] All TOML profile examples converted to JSON
|
|
- [ ] All file paths reference `.json` not `.toml`
|
|
- [ ] GPU dependencies mentioned in all installation paths
|
|
- [ ] TLS documentation explains auto-generation as primary method
|
|
- [ ] Protocol description says JSON, not Protocol Buffers
|
|
|
|
---
|
|
|
|
## Testing Recommendations
|
|
|
|
1. **Verify actual command-line options:**
|
|
```bash
|
|
socktop --help
|
|
socktop_agent --help
|
|
```
|
|
|
|
2. **Verify profile format:**
|
|
- Create a profile using `--profile` flag
|
|
- Check `~/.config/socktop/profiles.json` format
|
|
|
|
3. **Verify TLS auto-generation:**
|
|
- Run `socktop_agent --enableSSL --port 8443` on a fresh system
|
|
- Confirm certificate is auto-generated
|
|
- Check certificate location matches documentation
|
|
|
|
4. **Verify GPU dependencies:**
|
|
- Test installation without `libdrm-dev libdrm-amdgpu1`
|
|
- Confirm whether GPU metrics fail or if they're truly required
|
|
|
|
---
|
|
|
|
## Lessons Learned
|
|
|
|
1. **Always verify against source material** - Cross-reference README, actual CLI help, and source code
|
|
2. **Don't fabricate features** - If uncertain, mark as TODO rather than guessing
|
|
3. **Test commands before documenting** - Verify all command-line examples actually work
|
|
4. **Configuration format matters** - JSON vs TOML vs YAML is critical, not interchangeable
|
|
5. **Auto-generated features should be documented as such** - Don't make users do manual work when automation exists
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- Official README: https://github.com/jasonwitty/socktop/blob/master/README.md
|
|
- Actual implementation should always take precedence over documentation |