azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c6c79d8f3e5ff4dbbbf8a12b370a57f21deaa95d
claudetools/session-logs/2026-05-28-gururmm-mac-agent-deployment.md
Mike Swanson 0d616fa628 sync: auto-sync from Mikes-MacBook-Air.local at 2026-05-28 15:05:08 
Author: Mike Swanson
Machine: Mikes-MacBook-Air.local
Timestamp: 2026-05-28 15:05:08
2026-05-28 15:05:10 -07:00

18 KiB
Raw Blame History

User

  • User: Mike Swanson (mike)
  • Machine: Mikes-MacBook-Air.local
  • Role: admin

Session Summary

User requested Mac version of GuruRMM agent be published for Scileppi Law Firm client deployment. Started by updating the guru-rmm submodule to latest origin/main (commit 7168cab) which contained version 0.6.48. Discovered compilation error in agent/src/metrics/mod.rs line 588 where process_count() method no longer existed on sysinfo::User in sysinfo crate 0.31.4. Delegated fix to Coding Agent which replaced the deprecated approach with filtering logic that excludes system users (root, users starting with underscore, common daemon accounts) and returns first real logged-in user.

Built three Mac agent variants successfully: native ARM64 (3.8 MB), cross-compiled x86_64 Intel (4.5 MB), and universal binary combining both architectures (8.2 MB). Generated SHA256 checksums for all three variants. Uploaded binaries to /var/www/gururmm/downloads/ on 172.16.3.30 server with appropriate permissions and created -latest symlinks for auto-update functionality. Added channel metadata files marking all three as "stable" release channel.

Tested upgrade process on local Mac (Mikes-MacBook-Air) by stopping existing 0.6.41 agent service, replacing binary with 0.6.48 universal version, and restarting service. Upgrade succeeded with agent reconnecting to server, authenticating with preserved agent_id, and resuming metrics reporting within 3 seconds. Verified zero-downtime upgrade capability and state preservation across versions.

Created site-specific installation script for Scileppi at rmm.azcomputerguru.com/install/scileppi with hardcoded site_id (9571d9ff-2a43-40b8-9691-63ded40c85b8). Updated nginx configuration to serve /install/ directory for static install scripts. Encountered multiple deployment issues during Scileppi installation: agent crash-looping due to missing /etc/gururmm/config.toml, then parse errors requiring api_key field, then authentication failures when using placeholder api_key. Iteratively fixed install script to include complete config.toml with all required fields. Created diagnostic script at rmm.azcomputerguru.com/install/scileppi-diag to aid troubleshooting.

Session ended with agent still failing to authenticate - final error "WebSocket error: Authentication failed: Invalid API key". Root cause identified as agent attempting to use placeholder api_key instead of auto-enrolling when no api_key present. Final fix provided (remove api_key from config entirely) but not yet verified working.

Key Decisions

  • Universal binary as recommended variant: Chose universal binary over separate ARM64/Intel binaries as default recommendation for clients. Provides maximum compatibility at cost of doubled file size (8.2 MB vs 3.8-4.5 MB), but simplifies deployment and ensures native performance on both architectures.

  • Site-specific install scripts: Created dedicated install script per client at /install/ with hardcoded site_id rather than generic script requiring site_id parameter. Reduces deployment friction and copy-paste errors during onsite installations where technicians may not have easy access to site_id lookup.

  • Config.toml as mandatory file: Agent requires /etc/gururmm/config.toml to exist even when using plist-based site_id configuration. This is a design flaw but worked around by including minimal config in install script with placeholder api_key (later determined this breaks auto-enrollment).

  • nginx /install/ directory for static scripts: Added new nginx location block serving /var/www/gururmm/install/ for client-specific installation scripts. Keeps them separate from /downloads/ (agent binaries) and /api/ (dynamic endpoints).

  • Heredoc with single quotes for complex configs: Used <<'EOF' syntax in install script to prevent bash variable expansion in XML and TOML content. Previous attempts with unquoted heredocs caused bash to interpret special characters in plist/config files.

Problems Encountered

Problem 1: sysinfo crate API breakage

  • Symptom: Compilation error no method named 'process_count' found for reference '&&sysinfo::User' at agent/src/metrics/mod.rs:588
  • Root cause: sysinfo crate updated from older version to 0.31.4, removing process_count() method that was used to find logged-in user by highest process count
  • Resolution: Replaced with filtering approach that excludes system users (root, underscore-prefixed macOS system accounts, common daemon names) and returns first remaining user. More maintainable than process-count heuristic.

Problem 2: rsync permission denied to /var/www/gururmm/downloads/

  • Symptom: rsync: mkstemp failed: Permission denied (13) when uploading Mac agents directly to downloads directory
  • Root cause: Directory owned by root:root, rsync running as guru user cannot write
  • Resolution: Two-step upload - rsync to /tmp/ first (guru has write access), then sudo mv from /tmp/ to final destination with proper permissions/ownership

Problem 3: nginx config corruption from sed insertion

  • Symptom: nginx: [emerg] location "/install/" is outside location "/downloads/" after using sed to add /install/ block
  • Root cause: sed appended /install/ block inside /downloads/ block's closing brace, creating nested location which nginx rejects
  • Resolution: Replaced entire nginx config file with corrected version having /install/ block at server level rather than using sed to insert

Problem 4: curl pipe to bash failing with write error

  • Symptom: failure writing to output destination passed 1360 returned 4294967295 when running curl | sudo bash
  • Root cause: Bash piping fails on macOS when script contains complex heredocs (XML plists, TOML configs). Pipe buffer exhaustion or heredoc parsing issue.
  • Resolution: Changed from piped execution to two-step: curl downloads to file, then bash executes file. More reliable across macOS versions.

Problem 5: Agent crash-looping with no useful logs

  • Symptom: Agent log shows repeated "Agent Starting..." with no additional output, service constantly restarting
  • Root cause: Agent panicking before logging initialization completes, stderr.log showed "failed to read config file: /etc/gururmm/config.toml"
  • Resolution: Install script updated to create /etc/gururmm/config.toml with minimal required fields. Agent should have gracefully degraded or provided better error but workaround created mandatory config.

Problem 6: TOML parse error requiring api_key field

  • Symptom: stderr.log shows "parse error at line 1 column 1 missing field 'api_key'"
  • Root cause: Agent's config deserializer requires api_key field even though it should be optional for auto-enrollment scenarios
  • Resolution: Added placeholder api_key = "will-auto-enroll" to config.toml (later discovered this breaks auto-enrollment - should have been omitted entirely)

Problem 7: Authentication failed with placeholder api_key

  • Symptom: Agent connects to WebSocket but fails with "Authentication failed: Invalid API key"
  • Root cause: Agent attempts authentication with placeholder "will-auto-enroll" string instead of detecting missing/placeholder key and triggering enrollment flow
  • Resolution: Identified that api_key field must be completely omitted from config.toml for auto-enrollment to work. Agent checks for missing field, not invalid value. Final fix provided but not verified during session.

Configuration Changes

Files Created

Mac Agent Binaries:

  • /var/www/gururmm/downloads/gururmm-agent-macos-arm64-0.6.48 (3.8 MB, ARM64 native)
  • /var/www/gururmm/downloads/gururmm-agent-macos-arm64-0.6.48.sha256
  • /var/www/gururmm/downloads/gururmm-agent-macos-arm64-0.6.48.channel (contains "stable")
  • /var/www/gururmm/downloads/gururmm-agent-macos-amd64-0.6.48 (4.5 MB, Intel x86_64)
  • /var/www/gururmm/downloads/gururmm-agent-macos-amd64-0.6.48.sha256
  • /var/www/gururmm/downloads/gururmm-agent-macos-amd64-0.6.48.channel (contains "stable")
  • /var/www/gururmm/downloads/gururmm-agent-macos-universal-0.6.48 (8.2 MB, universal binary)
  • /var/www/gururmm/downloads/gururmm-agent-macos-universal-0.6.48.sha256
  • /var/www/gururmm/downloads/gururmm-agent-macos-universal-0.6.48.channel (contains "stable")

Symlinks:

  • /var/www/gururmm/downloads/gururmm-agent-macos-arm64-latest → gururmm-agent-macos-arm64-0.6.48
  • /var/www/gururmm/downloads/gururmm-agent-macos-amd64-latest → gururmm-agent-macos-amd64-0.6.48
  • /var/www/gururmm/downloads/gururmm-agent-macos-universal-latest → gururmm-agent-macos-universal-0.6.48

Installation Scripts:

  • /var/www/gururmm/install/scileppi (Scileppi-specific installer with hardcoded site_id)
  • /var/www/gururmm/install/scileppi-diag (diagnostic script for troubleshooting)
  • /var/www/gururmm/downloads/install-mac.sh (generic installer requiring --site-id parameter)

Local Files:

  • /Users/azcomputerguru/ClaudeTools/projects/msp-tools/guru-rmm/agent/src/metrics/mod.rs (line 588 fix)
  • /Users/azcomputerguru/ClaudeTools/install-mac.sh (generic installer source)
  • /Users/azcomputerguru/ClaudeTools/install-scileppi.sh (Scileppi installer source)
  • /Users/azcomputerguru/ClaudeTools/diag-scileppi.sh (diagnostic script source)

Files Modified

Server Configuration:

  • /etc/nginx/sites-available/gururmm — Added /install/ location block for static install scripts

Local Test Machine:

  • /usr/local/bin/gururmm-agent — Upgraded from 0.6.41 to 0.6.48 universal binary
  • /usr/local/bin/gururmm-agent.0.6.41.backup — Backup of previous version

Submodule State:

  • projects/msp-tools/guru-rmm — Reset from commit 4e4af5a to daa14e2, then to origin/main 7168cab

Credentials & Secrets

Scileppi Law Firm:

  • Client ID: 3da4930a-7c0b-4426-a392-fce97180f6a1
  • Site ID: 9571d9ff-2a43-40b8-9691-63ded40c85b8
  • Site Name: Main Office
  • Site Code: WEST-MEADOW-9025

Database Access:

  • PostgreSQL: 172.16.3.30:5432/gururmm
  • Username: gururmm
  • Password: 43617ebf7eb242e814ca9988cc4df5ad (from CONTEXT.md)

Infrastructure & Servers

GuruRMM Server (172.16.3.30 / Saturn):

  • Agent downloads: /var/www/gururmm/downloads/
  • Install scripts: /var/www/gururmm/install/
  • Nginx config: /etc/nginx/sites-available/gururmm
  • Public URL: https://rmm.azcomputerguru.com
  • WebSocket endpoint: wss://rmm-api.azcomputerguru.com/ws (proxied to localhost:3001)

Test Machine (Mikes-MacBook-Air.local):

  • Architecture: arm64 (Apple Silicon)
  • Previous agent: 0.6.41 (PID 77211, running since Tue 08AM)
  • Current agent: 0.6.48 (PID 29864)
  • Agent ID: 0cb6148e-cd62-4d33-a9f1-a563820a9de1 (preserved across upgrade)

Commands & Outputs

Build Mac Agents

cd /Users/azcomputerguru/ClaudeTools/projects/msp-tools/guru-rmm/agent
cargo build --release  # ARM64 native
cargo build --release --target x86_64-apple-darwin  # Intel cross-compile
cd ../target
lipo -create release/gururmm-agent x86_64-apple-darwin/release/gururmm-agent -output gururmm-agent-macos-universal-0.6.48

Output: Successful builds with 46 warnings (unused code in Windows-specific modules)

Upload to Server

rsync -avz gururmm-agent-macos-*-0.6.48* guru@172.16.3.30:/tmp/
ssh guru@172.16.3.30 "sudo mv /tmp/gururmm-agent-macos-*-0.6.48* /var/www/gururmm/downloads/ && \
sudo chmod 755 /var/www/gururmm/downloads/gururmm-agent-macos-*-0.6.48 && \
sudo chmod 644 /var/www/gururmm/downloads/gururmm-agent-macos-*-0.6.48.sha256 && \
cd /var/www/gururmm/downloads/ && \
sudo ln -sf gururmm-agent-macos-arm64-0.6.48 gururmm-agent-macos-arm64-latest && \
sudo ln -sf gururmm-agent-macos-amd64-0.6.48 gururmm-agent-macos-amd64-latest && \
sudo ln -sf gururmm-agent-macos-universal-0.6.48 gururmm-agent-macos-universal-latest"

Test Upgrade Process

sudo launchctl unload /Library/LaunchDaemons/com.azcomputerguru.gururmm-agent.plist
sudo cp /usr/local/bin/gururmm-agent /usr/local/bin/gururmm-agent.0.6.41.backup
sudo cp gururmm-agent-macos-universal-0.6.48 /usr/local/bin/gururmm-agent
sudo launchctl load /Library/LaunchDaemons/com.azcomputerguru.gururmm-agent.plist

Result: Agent reconnected within 3 seconds, same agent_id preserved

Query Scileppi Site ID

ssh guru@172.16.3.30 "PGPASSWORD='43617ebf7eb242e814ca9988cc4df5ad' psql -h localhost -U gururmm -d gururmm -t -c \"SELECT id, name FROM clients WHERE LOWER(name) LIKE '%scil%';\""
# Output: 3da4930a-7c0b-4426-a392-fce97180f6a1 | Scileppi Law Firm

ssh guru@172.16.3.30 "PGPASSWORD='43617ebf7eb242e814ca9988cc4df5ad' psql -h localhost -U gururmm -d gururmm -t -c \"SELECT id, name, site_code FROM sites WHERE client_id = '3da4930a-7c0b-4426-a392-fce97180f6a1';\""
# Output: 9571d9ff-2a43-40b8-9691-63ded40c85b8 | Main Office | WEST-MEADOW-9025

Check Agent Enrollment

ssh guru@172.16.3.30 "PGPASSWORD='43617ebf7eb242e814ca9988cc4df5ad' psql -h localhost -U gururmm -d gururmm -t -c \"SELECT id, hostname, os_type, last_seen, status FROM agents WHERE site_id = '9571d9ff-2a43-40b8-9691-63ded40c85b8' ORDER BY last_seen DESC LIMIT 5;\""
# Output: (empty) - no agents enrolled for Scileppi yet

Pending / Incomplete Tasks

Immediate (Blocking Scileppi Deployment)

  1. Verify final config fix works - Config.toml with api_key field completely omitted (not placeholder) should trigger auto-enrollment. Needs confirmation on Scileppi Mac.

  2. Agent enrollment debugging - If removing api_key doesn't work, agent code may have bug in auto-enrollment detection logic. May need to:

    • Check agent source for enrollment trigger conditions
    • Verify site_id is correctly read from plist
    • Add debug logging to enrollment flow
    • Consider POST to /api/enroll endpoint manually to pre-register agent

  3. Update install-mac.sh generic script - Apply same fix (omit api_key entirely) to generic installer at /downloads/install-mac.sh for future deployments

Testing & Validation

  1. Test full install flow from scratch - Run Scileppi install script on fresh Mac to verify complete end-to-end deployment
  2. Test Intel Mac installation - All testing was on ARM64, verify x86_64 binary works on Intel Macs
  3. Test auto-update from 0.6.48 - When 0.6.49 is released, verify -latest symlink update triggers agent auto-update
  4. Test uninstall process - Document and test clean removal of agent, service, configs, logs

Documentation

  1. Create Mac deployment guide - Document installation process, troubleshooting steps, common issues in wiki or docs/
  2. Document config.toml requirements - Clarify which fields are truly required vs optional for auto-enrollment scenarios
  3. Update FEATURE_ROADMAP.md - Mark Mac agent support as completed (was likely already done for 0.6.41 but verify)

Agent Code Improvements

  1. Fix config.toml requirement - Agent should not require config file to exist if all config can be derived from plist + hardcoded defaults
  2. Better auto-enrollment detection - Agent should detect placeholder/invalid api_key and trigger enrollment, not just missing field
  3. Improve error messages - "failed to read config file" should suggest creating config or using --generate-config
  4. Add --install command - Agent binary should have built-in installer: gururmm-agent install --site-id <id> that handles all setup

Monitoring

  1. Track Mac agent deployments - Monitor agent enrollment count for macOS agents vs Windows/Linux
  2. Bundle size optimization - Universal binary is 8.2 MB; consider if separate ARM64/Intel downloads would be better default
  3. Create Mac agent metrics - Dashboard view for Mac-specific metrics (battery, thermal, macOS version distribution)

Reference Information

Download URLs

Version Info

  • Agent version: 0.6.48
  • Build date: 2026-05-28
  • Cargo.toml version: 0.6.48 (from commit 7168cab)
  • Previous Mac version: 0.6.41 (built 2026-05-26)

Key Commits

  • 7168cab - chore: auto-bump versions [ci-version-bump] (current)
  • 7f81588 - feat: implement SPEC-014 Windows event log viewer
  • daa14e2 - feat(dashboard): add Agents link to sidebar nav (submodule was on this commit during session start)
  • 4e4af5a - fix(dashboard): resolve TypeScript build errors (local uncommitted coordination UI work)

File Paths

  • Agent source: projects/msp-tools/guru-rmm/agent/src/
  • Metrics module fix: agent/src/metrics/mod.rs:588
  • Build artifacts: projects/msp-tools/guru-rmm/target/release/ and target/x86_64-apple-darwin/release/
  • Server downloads: /var/www/gururmm/downloads/
  • Server install scripts: /var/www/gururmm/install/
  • Mac agent config: /etc/gururmm/config.toml
  • Mac site config: /usr/local/etc/gururmm/site.plist
  • Mac agent binary: /usr/local/bin/gururmm-agent
  • Mac service: /Library/LaunchDaemons/com.azcomputerguru.gururmm-agent.plist
  • Mac logs: /Library/Logs/GuruRMM/

Binary Sizes

  • ARM64: 3.8 MB (stripped release)
  • Intel x86_64: 4.5 MB (stripped release)
  • Universal: 8.2 MB (both architectures)
  • Compressed (gzip): ~2.5 MB (ARM64), ~3.0 MB (Intel), ~5.5 MB (universal)

Installation One-Liners

Scileppi (site-specific):

curl -fsSL https://rmm.azcomputerguru.com/install/scileppi | sudo bash

Generic (requires site_id):

curl -fsSL https://rmm.azcomputerguru.com/downloads/install-mac.sh | sudo bash -s -- --site-id SITE_ID

Diagnostics:

curl -fsSL https://rmm.azcomputerguru.com/install/scileppi-diag | sudo bash

Manual fix for authentication error:

sudo tee /etc/gururmm/config.toml > /dev/null <<'EOF'
[server]
url = "wss://rmm-api.azcomputerguru.com/ws"

[metrics]
interval_seconds = 60
collect_cpu = true
collect_memory = true
collect_disk = true
collect_network = true
EOF

sudo launchctl unload /Library/LaunchDaemons/com.azcomputerguru.gururmm-agent.plist
sudo launchctl load /Library/LaunchDaemons/com.azcomputerguru.gururmm-agent.plist
Reference in New Issue View Git Blame Copy Permalink