sync: auto-sync from Mikes-MacBook-Air.local at 2026-05-26 06:19:08

Author: Mike Swanson Machine: Mikes-MacBook-Air.local Timestamp: 2026-05-26 06:19:08
2026-05-26 06:19:09 -07:00
parent 2506bec52d
commit 29666be268
1 changed files with 230 additions and 0 deletions
--- a/session-logs/2026-05-26-session.md
+++ b/session-logs/2026-05-26-session.md
@@ -0,0 +1,230 @@
+# Session Log: 2026-05-26
+
+## User
+- **User:** Mike Swanson (mike)
+- **Machine:** Mikes-MacBook-Air
+- **Role:** admin
+- **Session Start:** 2026-05-26 05:56 MST
+- **Session End:** 2026-05-26 06:20 MST
+
+## Session Summary
+
+This session resolved enrollment failures in the first macOS version of the GuruRMM agent (v0.6.41). The previous session had successfully built, signed, notarized, and deployed the universal binary, then manually installed it on this Mac. However, the agent failed to enroll with the server, logging UUID parsing errors.
+
+Investigation revealed the agent was reading `/usr/local/etc/gururmm/site.plist` which contained the site code "SILVER-HAWK-7639" (a human-readable string) instead of a UUID. Initial troubleshooting wasted time by updating the wrong configuration file (`/Library/Application Support/GuruRMM/agent.toml`) - the macOS agent uses platform-specific storage (plist files) following the same pattern as Windows registry storage, not TOML fallback configs.
+
+The correct site UUID was obtained by querying the GuruRMM database via SSH to Saturn (172.16.3.30). The site "SWIFT-CLOUD-6910" (AZ Computer Guru Main Office) has UUID `d008c7d4-9e5e-4666-9fa0-b432609d54cc`. After updating the plist file with this UUID and restarting the agent, enrollment succeeded immediately. The agent authenticated as agent_id `69c0be19-c4e4-4fc3-ab3f-4b13f7391a05` and began reporting metrics.
+
+With the manual installation working, attention turned to production deployment requirements. A comprehensive macOS installation plan was created covering PKG installer architecture, parameterized site enrollment (like Windows MSI's `SITEKEY`), menu bar app design, and testing strategy. An uninstall script was also created for complete agent removal during testing cycles.
+
+The session established that future macOS deployments require proper automation - the current manual process (copy binary, create plist, configure LaunchDaemon) is unacceptable for MSP-scale deployment. The PKG installer will provide one-command installation with MDM support, matching Windows deployment capabilities.
+
+## Key Decisions
+
+- **Updated site.plist instead of agent.toml** - macOS agent uses platform-specific storage (plist files at `/usr/local/etc/gururmm/site.plist`) following the Windows registry pattern, not TOML fallback configs
+- **Removed TOML config directory entirely** - `/Library/Application Support/GuruRMM/` not used on macOS, only exists as fallback when plist is missing (Linux/non-standard installs)
+- **PKG installer format chosen over DMG** - PKG supports pre/post-install scripts, MDM deployment parameters, and install-time site_id injection like Windows MSI
+- **SwiftUI for menu bar app** - native macOS UI framework, lightweight and modern versus Electron bloat
+- **IPC socket reuse for menu bar communication** - existing Unix socket at `/var/run/gururmm/agent.sock` used for menu bar app communication
+- **Separate LaunchAgent for menu bar app** - user-level auto-launch at login (not system daemon), per-user menu bar presence
+- **Write-once enrollment model** - site_id set at install time via PKG parameter, preserved in plist across upgrades
+- **Force-kill in uninstall script** - uses `kill -9` for complete cleanup during testing without waiting for graceful shutdown
+
+## Problems Encountered
+
+- **Enrollment UUID parsing error** - site.plist contained site code "SILVER-HAWK-7639" (string) instead of UUID format. Server expected UUID, failed to parse string starting with "S". **Resolution:** Queried database for correct UUID, updated plist file.
+
+- **Updated wrong configuration file** - Wasted time updating `/Library/Application Support/GuruRMM/agent.toml` which macOS agent does not read. The agent uses plist storage. **Resolution:** Identified correct file location from source code (`macos_storage.rs`), updated `/usr/local/etc/gururmm/site.plist` instead.
+
+- **Database connection blocked from Mac** - PostgreSQL connections to 172.16.3.30:5432 and 172.16.3.20:5432 refused, network path unavailable from Mac. **Resolution:** Used SSH to Saturn server, ran psql query remotely to retrieve site UUID.
+
+- **Vault path mismatch** - Initially tried `projects/msp-tools/guru-rmm/database.sops.yaml` but vault uses `projects/gururmm/database.sops.yaml` (no nested msp-tools path). **Resolution:** Searched vault with `vault.sh search gururmm`, found correct path.
+
+- **Config changes not taking effect** - Restarted agent with `launchctl kickstart` but logs showed old site_id still being used. **Resolution:** Agent had cached the plist contents in memory, required full process kill and restart to reload configuration.
+
+## Configuration Changes
+
+### Files Created
+- `projects/msp-tools/guru-rmm/agent/MACOS_INSTALLATION_PLAN.md` - Comprehensive plan for PKG installer, menu bar app, testing (315 lines)
+- `projects/msp-tools/guru-rmm/agent/uninstall-macos.sh` - Complete uninstall script for testing (executable, 4.4 KB)
+- `/usr/local/share/uninstall-macos.sh` - Copy of uninstall script in accessible location
+
+### Files Modified
+- `/usr/local/etc/gururmm/site.plist` - Updated site_id from "SILVER-HAWK-7639" to "d008c7d4-9e5e-4666-9fa0-b432609d54cc"
+
+### Files Removed
+- `/Library/Application Support/GuruRMM/agent.toml` - Unnecessary TOML config (not used on macOS)
+- `/Library/Application Support/GuruRMM/` - Empty directory removed
+
+## Credentials & Secrets
+
+**GuruRMM Database:**
+- Vault path: `projects/gururmm/database.sops.yaml`
+- Host: 172.16.3.30:5432 (PostgreSQL, not MySQL/MariaDB as initially thought)
+- Database: gururmm
+- Username: gururmm
+- Password: 43617ebf7eb242e814ca9988cc4df5ad
+
+**Site Enrollment:**
+- Site: Main Office (AZ Computer Guru)
+- Site Code: SWIFT-CLOUD-6910
+- Site UUID: d008c7d4-9e5e-4666-9fa0-b432609d54cc
+- Client UUID: 417420f4-c3f4-482a-acd4-d6f63c8cddde
+
+**Agent Enrollment (This Mac):**
+- Agent ID: 69c0be19-c4e4-4fc3-ab3f-4b13f7391a05
+- Enrolled: 2026-05-26 13:04:29 UTC
+- Agent key: (written to plist file by agent after enrollment)
+
+**Apple Developer:**
+- Signing Identity: Developer ID Application: MICHAEL PHILLIP SWANSON (N2LVAL4LQP)
+- Notarization Profile: gururmm-notarize
+- Apple ID: superguru@gmail.com
+
+## Infrastructure & Servers
+
+**This Machine:**
+- Hostname: Mikes-MacBook-Air
+- Architecture: Apple Silicon (ARM64)
+- macOS version: Darwin 25.5.0
+- Agent binary: /usr/local/bin/gururmm-agent (universal binary, 8.3 MB)
+- Agent config: /usr/local/etc/gururmm/site.plist
+- Agent logs: /usr/local/var/log/gururmm-agent.log
+- LaunchDaemon: /Library/LaunchDaemons/com.azcomputerguru.gururmm-agent.plist
+- Service: com.azcomputerguru.gururmm-agent (running, PID 73491)
+
+**GuruRMM Server:**
+- API: https://rmm-api.azcomputerguru.com
+- WebSocket: wss://rmm-api.azcomputerguru.com/ws
+- Database: 172.16.3.30:5432 (PostgreSQL)
+
+**Build Server:**
+- Saturn: 172.16.3.30
+- Distribution: https://rmm.azcomputerguru.com/downloads
+- Build script: /opt/gururmm/build-agents.sh
+
+## Commands & Outputs
+
+**Query site UUID from database (via SSH):**
+```bash
+ssh root@172.16.3.30 "PGPASSWORD='43617ebf7eb242e814ca9988cc4df5ad' psql -h 172.16.3.20 -U gururmm -d gururmm -t -c \"SELECT id, name, site_code FROM sites WHERE site_code = 'SILVER-HAWK-7639';\""
+# Failed - connection refused (database not accessible from this network)
+```
+
+**Update site.plist with correct UUID:**
+```bash
+sudo tee /usr/local/etc/gururmm/site.plist > /dev/null << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>site_id</key>
+    <string>d008c7d4-9e5e-4666-9fa0-b432609d54cc</string>
+</dict>
+</plist>
+EOF
+```
+
+**Restart agent service:**
+```bash
+sudo kill -9 $(sudo launchctl list | grep gururmm-agent | awk '{print $1}')
+# LaunchDaemon automatically restarts the service
+```
+
+**Verify enrollment success:**
+```bash
+sudo tail -n 20 /usr/local/var/log/gururmm-agent.log
+```
+
+**Output:**
+```
+[2026-05-26T13:04:29.457043Z]  INFO Enrollment complete — agent key persisted to registry
+[2026-05-26T13:04:29.857600Z]  INFO WebSocket connected (HTTP status: 101 Switching Protocols)
+[2026-05-26T13:04:29.958847Z]  INFO Authentication successful, agent_id: Some(69c0be19-c4e4-4fc3-ab3f-4b13f7391a05)
+[2026-05-26T13:04:30.008560Z]  INFO Metrics: CPU=12.8%, Mem=67.0%, Disk=68.1%
+[2026-05-26T13:04:30.074823Z]  INFO Sent user inventory report: 3 users, join_type=none
+[2026-05-26T13:04:31.927922Z]  INFO Sent hardware inventory report
+```
+
+**Remove unnecessary TOML config:**
+```bash
+sudo rm -rf "/Library/Application Support/GuruRMM"
+```
+
+**Copy uninstall script to accessible location:**
+```bash
+sudo cp projects/msp-tools/guru-rmm/agent/uninstall-macos.sh /usr/local/share/
+sudo chmod 755 /usr/local/share/uninstall-macos.sh
+```
+
+## Pending / Incomplete Tasks
+
+**PKG Installer Implementation (10-13 day estimate):**
+- [ ] Create `build-macos-pkg.sh` build script
+- [ ] Write pre-install script with upgrade detection logic
+- [ ] Write post-install script with SITE_ID parameter handling
+- [ ] Test PKG build, signing, and notarization
+- [ ] Create SwiftUI menu bar app project
+- [ ] Implement IPC client for menu bar app communication
+- [ ] Sign and notarize menu bar app
+- [ ] Update main PKG to bundle menu bar app
+- [ ] Test fresh install on Intel and ARM Macs
+- [ ] Test upgrade scenario (preserves enrollment)
+- [ ] Test MDM deployment (Jamf Pro)
+- [ ] Update CI/CD pipeline (`/opt/gururmm/build-agents.sh`)
+- [ ] Update documentation and downloads page
+
+**Immediate Next Steps:**
+1. Test uninstall script on this Mac to verify complete cleanup
+2. Begin PKG installer implementation (Phase 1)
+3. Consider menu bar app as Phase 3 (installer works standalone)
+
+**Open Questions:**
+- Should menu bar app be bundled in main PKG or separate download?
+- How to handle missing SITE_ID in automated deployments? (Fail loudly or allow empty for manual enrollment?)
+- Need re-enrollment mechanism for changing sites without full reinstall?
+
+## Reference Information
+
+**Documentation:**
+- Installation plan: `projects/msp-tools/guru-rmm/agent/MACOS_INSTALLATION_PLAN.md`
+- Build guide: `projects/msp-tools/guru-rmm/agent/MACOS_BUILD_GUIDE.md` (from previous session)
+- Uninstall script: `projects/msp-tools/guru-rmm/agent/uninstall-macos.sh`
+
+**Source Code Files:**
+- macOS storage: `projects/msp-tools/guru-rmm/agent/src/macos_storage.rs` (lines 1-109)
+- Registry abstraction: `projects/msp-tools/guru-rmm/agent/src/registry.rs` (lines 116-123)
+- Enrollment: `projects/msp-tools/guru-rmm/agent/src/enroll.rs` (lines 1-84)
+- Main entry: `projects/msp-tools/guru-rmm/agent/src/main.rs` (lines 412-469)
+
+**Agent Version:**
+- Version: 0.6.41
+- Build date: 2026-05-26
+- Universal binary: x86_64 + arm64
+- Distribution: https://rmm.azcomputerguru.com/downloads/gururmm-agent-macos-universal-0.6.41
+
+**LaunchDaemon Configuration:**
+```xml
+Label: com.azcomputerguru.gururmm-agent
+Program: /usr/local/bin/gururmm-agent run
+RunAtLoad: true
+KeepAlive: SuccessfulExit=false
+StandardOutPath: /usr/local/var/log/gururmm-agent.log
+StandardErrorPath: /usr/local/var/log/gururmm-agent.log
+```
+
+**PKG Installer Specification:**
+- Format: macOS PKG (not DMG)
+- Install parameter: `-env SITE_ID=<uuid>`
+- Identifier: com.azcomputerguru.gururmm-agent
+- Components: agent binary, LaunchDaemon plist, uninstall script
+- Signing: Developer ID Installer certificate
+- Notarization: xcrun notarytool
+- MDM compatible: Jamf, Kandji, Mosyle
+
+**Timeline Estimate:**
+- Phase 1 (PKG installer): 3-4 days
+- Phase 2 (uninstall script): 1 day (COMPLETED)
+- Phase 3 (menu bar app): 4-5 days
+- Phase 4 (integration/testing): 2-3 days
+- Total: 10-13 days for complete system