Add agent-id support to host agent installers (Related to #721)

Author: rcourtman

docs/HOST_AGENT.md

@@ -201,6 +201,18 @@ Start-Service -Name PulseHostAgent
 
 Run `pulse-host-agent --help` for the full list.
 
+## Avoiding ID collisions
+
+Pulse keys hosts on the identifier supplied by the agent (machine-id by default). Cloned systems frequently share `/etc/machine-id`, which makes Pulse alternate a single row between multiple machines. Keep the ID unique by regenerating the machine-id on each clone or by providing an explicit `--agent-id`/`PULSE_AGENT_ID` when installing:
+
+```bash
+sudo rm /etc/machine-id /var/lib/dbus/machine-id
+sudo systemd-machine-id-setup
+sudo systemctl restart pulse-host-agent
+```
+
+Re-running the installer with `--agent-id <unique-name>` achieves the same result if regenerating the machine-id is undesirable.
+
 ## Viewing Hosts
 
 - **Settings → Agents → Host agents** lists every reporting host and provides ready-made install commands.

scripts/install-host-agent.ps1

@@ -11,6 +11,7 @@ param(
     [string]$PulseUrl = $env:PULSE_URL,
     [string]$Token = $env:PULSE_TOKEN,
     [string]$Interval = $env:PULSE_INTERVAL,
+    [string]$AgentId = $env:PULSE_AGENT_ID,
     [string]$InstallPath = "C:\Program Files\Pulse",
     [string]$Arch = $env:PULSE_ARCH,
     [switch]$NoService
@@ -251,6 +252,7 @@ if (-not $Interval) {
 PulseInfo "Configuration:"
 Write-Host "  Pulse URL: $PulseUrl"
 Write-Host "  Token: $(if ($Token) { '***' + $Token.Substring([Math]::Max(0, $Token.Length - 4)) } else { 'none' })"
+Write-Host "  Agent ID: $(if ($AgentId) { $AgentId } else { 'machine-id (default)' })"
 Write-Host "  Interval: $Interval"
 Write-Host "  Install Path: $InstallPath"
 if ($Arch) {
@@ -381,6 +383,9 @@ try {
     if ($Token) {
         $agentArgs += @("--token", "`"$Token`"")
     }
+    if ($AgentId) {
+        $agentArgs += @("--agent-id", "`"$AgentId`"")
+    }
     $serviceBinaryPath = "`"$agentPath`" $($agentArgs -join ' ')"
     $manualCommand = "& `"$agentPath`" $($agentArgs -join ' ')"
 } catch {
@@ -397,6 +402,9 @@ $config = @{
 if ($Token) {
     $config.token = $Token
 }
+if ($AgentId) {
+    $config.agentId = $AgentId
+}
 
 $config | ConvertTo-Json | Set-Content $configPath
 PulseSuccess "Created configuration at $configPath"

scripts/install-host-agent.sh

@@ -71,6 +71,7 @@ KEYCHAIN_ENABLED=true
 KEYCHAIN_OPT_OUT=false
 KEYCHAIN_OPT_OUT_REASON=""
 USE_KEYCHAIN=false
+AGENT_ID="${PULSE_AGENT_ID:-}"
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
@@ -86,6 +87,10 @@ while [[ $# -gt 0 ]]; do
             INTERVAL="$2"
             shift 2
             ;;
+        --agent-id)
+            AGENT_ID="$2"
+            shift 2
+            ;;
         --platform)
             PLATFORM="$2"
             shift 2
@@ -162,9 +167,10 @@ fi
 
 if [[ -z "$PULSE_URL" ]]; then
     log_error "Pulse URL is required"
-    echo "Usage: $0 --url <pulse-url> --token <api-token> [--interval 30s] [--platform linux|darwin|windows] [--force] [--no-keychain]"
+    echo "Usage: $0 --url <pulse-url> --token <api-token> [--interval 30s] [--agent-id <id>] [--platform linux|darwin|windows] [--force] [--no-keychain]"
     echo ""
     echo "  --force       Skip interactive prompts and accept secure defaults (including Keychain storage)."
+    echo "  --agent-id    Override the identifier used to deduplicate hosts (defaults to machine-id)."
     echo "  --no-keychain Disable Keychain storage and embed the token in the launch agent plist instead."
     exit 1
 fi
@@ -234,6 +240,11 @@ if [[ -n "$PULSE_TOKEN" ]]; then
 else
     echo "  Token: none"
 fi
+if [[ -n "$AGENT_ID" ]]; then
+    echo "  Agent ID: $AGENT_ID"
+else
+    echo "  Agent ID: machine-id (default)"
+fi
 echo "  Interval: $INTERVAL"
 echo "  Platform: $PLATFORM/$ARCH"
 echo ""
@@ -406,6 +417,9 @@ if [[ -n "$PULSE_TOKEN" ]]; then
     AGENT_CMD="$AGENT_CMD --token $PULSE_TOKEN"
 fi
 AGENT_CMD="$AGENT_CMD --interval $INTERVAL"
+if [[ -n "$AGENT_ID" ]]; then
+    AGENT_CMD="$AGENT_CMD --agent-id $AGENT_ID"
+fi
 MANUAL_START_CMD="$AGENT_CMD"
 MANUAL_START_WRAPPED="nohup $MANUAL_START_CMD >$LINUX_LOG_FILE 2>&1 &"
 
@@ -529,6 +543,12 @@ elif [[ "$PLATFORM" == "darwin" ]] && command -v launchctl &> /dev/null; then
         USE_KEYCHAIN=false
     fi
 
+    LAUNCHD_AGENT_ID_ARGS=""
+    if [[ -n "$AGENT_ID" ]]; then
+        LAUNCHD_AGENT_ID_ARGS="        <string>--agent-id</string>
+        <string>$AGENT_ID</string>"
+    fi
+
     # Create wrapper script if using Keychain
     if [[ "$USE_KEYCHAIN" == true ]]; then
         WRAPPER_SCRIPT="/usr/local/bin/pulse-host-agent-wrapper.sh"
@@ -588,6 +608,7 @@ WRAPPER_EOF
         <string>$PULSE_URL</string>
         <string>--interval</string>
         <string>$INTERVAL</string>
+$LAUNCHD_AGENT_ID_ARGS
     </array>
     <key>RunAtLoad</key>
     <true/>
@@ -619,6 +640,7 @@ EOF
         <string>$PULSE_TOKEN</string>
         <string>--interval</string>
         <string>$INTERVAL</string>
+$LAUNCHD_AGENT_ID_ARGS
     </array>
     <key>RunAtLoad</key>
     <true/>