Troubleshooting

This guide helps you diagnose and resolve common issues with the LinuxGuard agent.

Agent Logs

The primary source of information for troubleshooting is the agent log file. The LinuxGuard agent writes detailed logs that can help identify issues.

Log File Location

The agent log file is located at:

/var/log/linuxguard/agent.log

Viewing Logs

To view the agent logs:

sudo tail -f /var/log/linuxguard/agent.log

To view the last 100 lines:

sudo tail -n 100 /var/log/linuxguard/agent.log

To search for errors:

sudo grep -i error /var/log/linuxguard/agent.log

Common Issues

Enrollment Failures

Problem: Agent fails to enroll with error messages.

Solutions:

1. Verify your API key and Tenant ID are correct

2. Check network connectivity:

   curl -v https://api.linuxguard.io/v1/

3. Ensure the agent has proper permissions (run with sudo)

4. Check firewall rules allow outbound HTTPS connections

5. Review the agent log file for specific error messages

Agent Not Sending Data

Problem: Agent enrolled successfully but no data appears in the console.

Solutions:

1. Verify the agent service is running:

   sudo systemctl status linuxguard-agent

2. Check if the agent process is running:

   ps aux | grep linuxguard-agent

3. Review agent logs for connection errors

4. Verify network connectivity to api.linuxguard.io

5. Check system time is synchronized (NTP)

Installation Issues

Problem: Unable to install the agent package.

Solutions:

1. Ensure the repository was added successfully

2. Update your package manager cache:

   • Debian/Ubuntu: sudo apt update

   • RedHat/CentOS: sudo dnf makecache or sudo yum makecache

   • Alpine: sudo apk update

3. Verify repository signing keys are installed

4. Check for conflicting packages

5. Review system package manager logs

Permission Errors

Problem: Permission denied errors when running agent commands.

Solutions:

1. Ensure you're using sudo for agent commands

2. Verify your user has sudo privileges

3. Check file permissions on agent binaries and configuration files

4. Review SELinux/AppArmor policies if applicable

Network Connectivity Issues

Problem: Agent cannot connect to LinuxGuard API.

Solutions:

1. Test connectivity:

   curl -v https://api.linuxguard.io/v1/

2. Check firewall rules (allow outbound HTTPS on port 443)

3. Verify proxy settings if behind a corporate proxy

4. Check DNS resolution:

   nslookup api.linuxguard.io

5. Review network security group rules (cloud environments)

Getting Help

If you're unable to resolve an issue using this guide:

1. Check the logs: Review /var/log/linuxguard/agent.log for detailed error messages

2. Gather information: Note the error messages, your distribution version, and any relevant system information

3. Contact Support: Reach out to [email protected] with:

   • Description of the issue

   • Relevant log excerpts

   • Your distribution and version

   • Steps you've already tried

Our support team is available 24/7 and will help you resolve any issues.

---

Related: Support | Configuration