# 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](/how-to-guides/how-to/configuration.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.linuxguard.io/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.