Skip to main content

Installation on Ubuntu & Debian

This guide covers installing the PatchCTL agent on Debian-based distributions.

Supported Versions​

DistributionVersions
Ubuntu20.04 LTS, 22.04 LTS, 24.04 LTS
Debian11 (Bullseye), 12 (Bookworm)

Quick Install​

Run the automated installer:

curl -fsSL https://downloads.patchctl.com/install.sh | sudo bash -s -- --key=YOUR_LICENSE_KEY

Manual Installation​

If you prefer manual installation or need more control:

Step 1: Download the Binary​

# Create directory
sudo mkdir -p /opt/patchctl/bin

# Download the binary
sudo curl -fsSL -o /opt/patchctl/bin/patchctl-agent \
  https://downloads.patchctl.com/latest/patchctl-agent-linux-amd64

# Make executable
sudo chmod +x /opt/patchctl/bin/patchctl-agent

Step 2: Create Configuration​

# Create config directory
sudo mkdir -p /etc/patchctl

# Create configuration file
sudo tee /etc/patchctl/config.json > /dev/null << 'EOF'
{
  "license_key": "YOUR_LICENSE_KEY",
  "api_endpoint": "https://api.patchctl.com",
  "heartbeat_interval": 300,
  "log_level": "info"
}
EOF

# Secure the config file
sudo chmod 600 /etc/patchctl/config.json

Step 3: Create Systemd Service​

sudo tee /etc/systemd/system/patchctl.service > /dev/null << 'EOF'
[Unit]
Description=PatchCTL Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/opt/patchctl/bin/patchctl-agent
Restart=always
RestartSec=10
User=root
WorkingDirectory=/opt/patchctl

# Hardening
NoNewPrivileges=no
ProtectSystem=full
ProtectHome=read-only

[Install]
WantedBy=multi-user.target
EOF

Step 4: Start the Service​

# Reload systemd
sudo systemctl daemon-reload

# Enable and start the agent
sudo systemctl enable patchctl
sudo systemctl start patchctl

# Verify status
sudo systemctl status patchctl

Verification​

Check Service Status​

sudo systemctl status patchctl

Expected output:

● patchctl.service - PatchCTL Agent
     Loaded: loaded (/etc/systemd/system/patchctl.service; enabled)
     Active: active (running) since ...
   Main PID: 12345 (patchctl-agent)

Check Logs​

sudo journalctl -u patchctl -f

Look for successful heartbeat messages:

INFO: Heartbeat sent successfully
INFO: Package scan completed: 234 packages found

Verify in Dashboard​

Your server should appear in the PatchCTL dashboard within 5 minutes.

Ubuntu-Specific Notes​

APT Configuration​

The agent uses the system's APT configuration. Ensure your repositories are properly configured:

# Update package lists
sudo apt update

# Check for available updates
apt list --upgradable

Unattended Upgrades​

If you're using unattended-upgrades, consider disabling it to avoid conflicts with PatchCTL-managed patching:

sudo dpkg-reconfigure unattended-upgrades

Or configure PatchCTL schedules to complement your existing automation.

Troubleshooting​

"GLIBC not found" Error​

If you see GLIBC version errors, you may be running an older system. Check your GLIBC version:

ldd --version

Ubuntu 20.04+ and Debian 11+ should have compatible GLIBC versions.

Network Issues​

Test connectivity to the API:

curl -I https://api.patchctl.com/health

If this fails, check:

  • Firewall rules (sudo ufw status)
  • Proxy configuration
  • DNS resolution

Permission Issues​

Ensure the agent runs as root for package management:

sudo ls -la /opt/patchctl/bin/patchctl-agent
# Should show: -rwxr-xr-x 1 root root

Next Steps​