Agent Installation Fails — Common Causes and Fixes

When the Server Scout agent installation fails, it's usually due to one of several common system configuration issues. This guide walks you through diagnosing and fixing the most frequent causes of installation failures.

Basic Installation Requirements

The Server Scout agent installer is a Bash script that requires root privileges and several system dependencies. Before troubleshooting specific issues, ensure you're running the installation command correctly:

curl -s https://app.serverscout.ie/install.sh | sudo bash -s YOUR_INSTALL_TOKEN

Common Causes and Fixes

1. Not Running as Root

Symptom: Permission denied errors during installation

Diagnosis: Check if you're running with sufficient privileges

whoami
id

Fix: The installer requires root access. Use sudo with the installation command, or switch to root:

# Using sudo (recommended)
curl -s https://app.serverscout.ie/install.sh | sudo bash -s YOUR_INSTALL_TOKEN

# Or switch to root first
su -
curl -s https://app.serverscout.ie/install.sh | bash -s YOUR_INSTALL_TOKEN

2. curl Not Installed

Symptom: "command not found: curl" error

Diagnosis: Test if curl is available

which curl
curl --version

Fix: Install curl using your distribution's package manager:

# Debian/Ubuntu
sudo apt update && sudo apt install curl

# RHEL/CentOS/AlmaLinux/Rocky
sudo dnf install curl
# or on older versions: sudo yum install curl

3. Firewall Blocking Outbound HTTPS

Symptom: Connection timeouts or "couldn't connect to server" errors

Diagnosis: Test connectivity to Server Scout

curl -I https://app.serverscout.ie
telnet app.serverscout.ie 443

Fix: Allow outbound HTTPS traffic (TCP port 443):

# UFW (Ubuntu)
sudo ufw allow out 443

# iptables
sudo iptables -A OUTPUT -p tcp --dport 443 -j ACCEPT

# firewalld (RHEL/CentOS)
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Don't forget to check cloud security groups if you're using AWS, Azure, or similar platforms.

4. DNS Resolution Failure

Symptom: "Could not resolve host" errors

Diagnosis: Test DNS resolution

nslookup app.serverscout.ie
dig app.serverscout.ie
curl -I https://app.serverscout.ie

Fix: Check your DNS configuration:

cat /etc/resolv.conf

Ensure you have working nameservers configured. If needed, add public DNS servers:

echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf
echo "nameserver 8.8.4.4" | sudo tee -a /etc/resolv.conf

5. SELinux Blocking the Agent

Symptom: Installation succeeds but agent fails to start on RHEL-family systems

Diagnosis: Check SELinux status and recent denials

getenforce
sudo ausearch -m avc -ts recent

Fix: If SELinux is in enforcing mode and blocking the agent:

# Temporary fix - set to permissive mode
sudo setenforce 0

# Permanent fix - create SELinux policy or disable
sudo sed -i 's/SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config

6. Insufficient Disk Space

Symptom: "No space left on device" errors

Diagnosis: Check available disk space

df -h /opt
df -h /

Fix: The agent needs approximately 2 MB in /opt/scout-agent/. Free up space or clean temporary files:

sudo apt autoremove && sudo apt autoclean  # Debian/Ubuntu
sudo dnf clean all  # RHEL/CentOS

7. Systemd Not Available

Symptom: Service installation fails with systemctl errors

Diagnosis: Check if systemd is running

systemctl --version
ps -p 1

Fix: Server Scout requires systemd for service management. Older init systems (SysV, Upstart) are not supported. Consider upgrading to a modern Linux distribution with systemd support.

8. Proxy Configuration Required

Symptom: Connection failures in corporate environments

Diagnosis: Check if HTTP proxy is required for outbound connections

Fix: Configure proxy settings before installation:

export http_proxy=http://proxy.company.com:8080
export https_proxy=http://proxy.company.com:8080
curl -s https://app.serverscout.ie/install.sh | sudo -E bash -s YOUR_INSTALL_TOKEN

Getting Additional Help

If these steps don't resolve your installation issue, contact Server Scout support through the dashboard. Our AI support bot responds within approximately 1 minute with relevant troubleshooting steps, and human escalation is available during business hours for complex issues.

Include the specific error messages and your Linux distribution details when requesting help for faster resolution.