<a id="how-to-troubleshoot"></a>

# How to troubleshoot

This guide covers common issues you might encounter when operating the osquery
charm, and how to diagnose them.

<!-- vale Canonical.013-Spell-out-numbers-below-10 = NO -->
<!-- vale Canonical.500-Repeated-words = NO -->

## Inspect the charm status

Start with the Juju status, which reports the charm’s current state and any
blocking condition:

```bash
juju status
```

The charm sets a descriptive status message when it can’t proceed, for example
when a required configuration value is missing.

## The charm is blocked

The charm blocks until it has everything it needs to configure the agent. The
most common cause is a missing required configuration value, such as
`controller-env-uuid`. The status message names the missing value; set it with
`juju config` as described in the [advanced tutorial](https://canonical.com/juju/docs/osquery-charm/latest/tutorial/advanced-deployment/index.html.md#tutorial-advanced-deployment).

## Read the charm logs

Use `juju debug-log` to see what the charm did during its most recent
reconcile:

```bash
juju debug-log --include osquery --replay
```

## The daemon isn’t running

If the charm reports `active` but osquery doesn’t appear to be working, e.g.
it’s not visible from the osquery controller, check the snap’s
`c-osquery.osqueryd` service (systemd unit `snap.c-osquery.osqueryd.service`)
on the unit’s machine:

```bash
juju ssh <principal>/0 snap services c-osquery
juju ssh <principal>/0 systemctl status snap.c-osquery.osqueryd
juju ssh <principal>/0 sudo journalctl -u snap.c-osquery.osqueryd --no-pager
```

The flagfile the charm rendered is at
`/var/snap/c-osquery/common/etc/osquery/osquery.flags`, and `snap list
c-osquery` shows the installed revision and the channel it tracks.

The charm renders an osquery flagfile from the Juju configuration and restarts
the daemon whenever the configuration changes. If the daemon fails to start,
these logs usually explain why — for example, an invalid flag value or an
unreadable certificate.

## The agent won’t enroll

If the daemon is running but the agent doesn’t enroll with the controller,
enrollment failures are typically logged by `osqueryd` and visible in the
`journalctl` output shown above.

In the event of an enrollment failure, verify the controller-related configuration:

- `controller-uri` points at the correct hostname.
- `controller-env-uuid` matches the environment assigned to your fleet.
- `enroll-secret` references a Juju secret that the charm has been granted
  access to.
- `tls-server-certs`, `tls-client-cert`, and `tls-client-key` contain the
  correct certificates and key.
