How to troubleshoot

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

Inspect the charm status

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

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.

Read the charm logs

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

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:

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.