Agent Auto-Update and Version Management

The Server Scout agent includes a robust auto-update mechanism that ensures your monitoring infrastructure stays current with the latest features, security patches, and bug fixes. This guide covers how the update system works and how to manage it effectively.

How Agent Auto-Updates Work

The Server Scout agent performs a daily version check by contacting the /api/agent-version.php endpoint. This lightweight check compares your current agent version against the latest available release. If a newer version is detected, the update process begins automatically.

The update process follows these steps:

1. Version Check: The agent queries the API endpoint to determine if an update is available
2. Download: The new agent binary is downloaded to a temporary location
3. Integrity Verification: SHA-256 checksums are verified to ensure the download is authentic and uncorrupted
4. Atomic Replacement: The old binary is replaced with the new one in a single atomic operation
5. Process Restart: The agent uses exec to restart itself, loading the new code without service interruption

Plugin Auto-Updates

Plugins are automatically updated alongside the main agent binary. When the agent updates, it ensures all installed plugins are compatible with the new version and updates them as necessary. This maintains consistency across your monitoring setup and prevents compatibility issues.

Configuring Auto-Updates

Auto-updates are controlled by the auto_update configuration flag in your agent configuration file:

# Enable auto-updates (default)
auto_update=true

# Disable auto-updates
auto_update=false

To modify this setting, edit your configuration file and restart the agent:

sudo nano /opt/scout-agent/agent.conf
sudo systemctl restart scout-agent

Manual Update Procedures

For environments requiring manual control over updates, disable auto-updates and use these procedures:

Manual Agent Update

1. Download the latest agent version:

wget https://releases.serverscout.ie/agent/latest/scout-agent

1. Verify the download integrity:

wget https://releases.serverscout.ie/agent/latest/scout-agent.sha256
sha256sum -c scout-agent.sha256

1. Replace the existing binary:

sudo systemctl stop scout-agent
sudo cp scout-agent /opt/scout-agent/scout-agent.sh
sudo chmod +x /opt/scout-agent/scout-agent.sh
sudo systemctl start scout-agent

Version Pinning

For change-controlled environments, you can pin the agent to a specific version by modifying the update endpoint configuration:

# Pin to version 2.1.5
update_endpoint="https://app.serverscout.ie/agent-version.php?pin=2.1.5"

This prevents automatic updates beyond the specified version whilst maintaining the update mechanism for security patches within that version.

Troubleshooting Failed Updates

Permission Issues

If updates fail due to permission problems, ensure the agent process has write access to its binary location:

sudo chown root:root /opt/scout-agent/scout-agent.sh
sudo chmod 755 /opt/scout-agent/scout-agent.sh

Check the agent's running user and adjust ownership accordingly.

Disk Space Problems

Monitor available disk space in the agent's working directory:

df -h /tmp
df -h /usr/local/bin

The update process requires temporary space for downloading and verifying the new binary. Ensure at least 50MB is available.

Network Connectivity

Test connectivity to the update servers:

curl -I https://app.serverscout.ie/agent-version.php
curl -I https://releases.serverscout.ie/agent/latest/

Configure proxy settings in the agent configuration if your environment requires it:

http_proxy="http://proxy.example.com:8080"
https_proxy="https://proxy.example.com:8080"

Update Logs

Check the agent logs for detailed update information:

sudo journalctl -u scout-agent -f
tail -f journalctl -u scout-agent

Failed updates are logged with specific error messages to help identify the root cause.

Best Practices

• Keep auto-updates enabled in development and testing environments
• Use version pinning in production environments with formal change control
• Monitor update logs regularly to ensure successful updates
• Test manual update procedures in non-production environments first
• Maintain adequate disk space and network connectivity for reliable updates

The Server Scout auto-update system is designed for reliability and minimal disruption, ensuring your monitoring infrastructure remains current and secure.