Overview 💥
Linux-based Liongard Agents may occasionally stop checking in to the Liongard platform and display a “No Heartbeat” status.
One known cause of this behavior is an unsupported or improperly defined HTTP proxy configuration, where the agent logs report an error similar to:
Unsupported GLOBAL_AGENT.HTTP_PROXY
Symptoms 🤒
You may observe one or more of the following:
The Linux Agent appears Offline or No Heartbeat in the Liongard platform
Inspectors associated with the agent fail or stop returning data
Heartbeat-related errors appear in the agent logs
Common Log Location
/opt/liongard/logs/heartbeat.log
Example Log Entry
‼️ Note: The exact wording may vary slightly depending on agent version.
Unsupported GLOBAL_AGENT.HTTP_PROXY
or
Unsupported GLOBAL_AGENT_HTTP_PROXY value
Why Does This Happen 🤔
The Liongard Linux Agent supports outbound HTTP/HTTPS proxy configuration using environment variables defined in the following file:
/opt/liongard/.config
The setting involved in this issue is:
GLOBAL_AGENT_HTTP_PROXY
Internally, this value is referenced by the agent as GLOBAL_AGENT.HTTP_PROXY, which is why the log message uses dot notation.
Common Failure Scenario
In some environments, this variable is incorrectly set to a placeholder value such as:
GLOBAL_AGENT_HTTP_PROXY=undefined
This typically occurs when:
An automation or deployment script inserts a placeholder value
A proxy configuration is partially applied but never finalized
Environment variables are inherited incorrectly during installation
When the agent attempts to use this invalid value, it fails to establish secure outbound communication with the Liongard platform, causing heartbeat failures.
Steps to Resolve 🧑🏫
Step 1: (Optional but Recommended) Back Up the Current Configuration
Before making changes, create a backup of the agent configuration file:
sudo cp /opt/liongard/.config /opt/liongard/.config.bak
Step 2: Remove the Invalid Proxy Value
This step assumes the value is exactly GLOBAL_AGENT_HTTP_PROXY=undefined.
Run the following command to safely replace it with an empty (valid) value:
sudo sed -i 's/^GLOBAL_AGENT_HTTP_PROXY=undefined$/GLOBAL_AGENT_HTTP_PROXY=/g' /opt/liongard/.config
This command is intentionally anchored (^ and $) to avoid modifying unintended content.
Step 3: Restart the Liongard Agent Service
Apply the configuration change by restarting the agent service:
sudo systemctl restart liongard-agent
Verification Steps 👨🔧
After restarting the service:
Check the service status:
systemctl status liongard-agent
Monitor the heartbeat log:
tail -f /opt/liongard/logs/heartbeat.log
Confirm in the Liongard platform that:
The agent transitions from No Heartbeat to Online
Associated inspectors resume normal execution
Valid vs Invalid Proxy Configuration Examples 🧐
Valid Configuration (Proxy Required)
GLOBAL_AGENT_HTTP_PROXY=http://user:password@proxy.example.com:3128
Valid Configuration (No Proxy Required)
GLOBAL_AGENT_HTTP_PROXY=
❌ Invalid / Problematic Configuration
GLOBAL_AGENT_HTTP_PROXY=undefined
Additional Troubleshooting (If the Issue Persists) 👨💻
Confirm Network Connectivity
Verify the system can reach your Liongard instance:
curl -I https://<your-instance>.app.liongard.com
Proxy-Required Environments
If your environment requires a proxy:
Ensure a valid proxy URL is defined in
/opt/liongard/.configSave the file
Restart the agent service again:
sudo systemctl restart liongard-agent
Restart the Updater Service (Optional)
sudo systemctl restart liongard-agent-updater
Best Practices 🙌
Only configure
GLOBAL_AGENT_HTTP_PROXYwhen a proxy is explicitly requiredAvoid using placeholder values (such as
undefined) in automation scriptsValidate environment variables after deploying Linux agents
Document proxy requirements as part of standard Linux agent deployment procedures
When to Contact Support 🦁
If the agent continues to report No Heartbeat after completing the steps above, contact Liongard Support for further assistance.
Include the Following When Opening a Support Ticket
Linux distribution and version
Liongard Agent version
Whether a proxy is required in your environment
Output of:
systemctl status liongard-agent
Relevant log excerpts from:
/opt/liongard/logs/heartbeat.log
/opt/liongard/logs/error.log
Providing this information upfront helps expedite investigation and resolution.