> For the complete documentation index, see [llms.txt](https://docs.linuxguard.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.linuxguard.io/troubleshooting.md).

# 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:

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

To view the last 100 lines:

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

To search for errors:

```bash
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:

   ```bash
   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:

   ```bash
   sudo systemctl status linuxguard-agent
   ```
2. Check if the agent process is running:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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 <support@linuxguard.io> 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](/support.md) | [Configuration](/configure/configure.md)