How to enroll the agent with a controller¶

The osquery charm runs the osqueryd agent, but an agent is only useful once it’s enrolled with an osquery controller, which supplies its configuration and collects its logs. This guide covers the end-to-end flow: provisioning an environment on the controller, obtaining the credentials the agent needs, applying them to the charm, and rotating them later.

Deploying and operating the controller itself is out of scope for this guide. This charm targets osctrl, and the guide assumes you already have a running osctrl deployment and can run osctrl-cli against it (either directly against its database or through the osctrl API).

Prerequisites¶

A deployed osquery charm. See the tutorial.
Access to a running osctrl deployment, with osctrl-cli configured to reach it and permission to manage environments.

Provision an environment on the controller¶

An environment in osctrl is a TLS endpoint that groups a set of nodes and holds their enrollment secret, certificate, and configuration. From it you need two values:

the controller’s hostname, for controller-uri, and
the environment UUID, for controller-env-uuid.

Create an environment with osctrl-cli, then read back its UUID:

osctrl-cli environment add --name corp --hostname <controller-uri> --config --logger --query
osctrl-cli environment show --name corp

environment show prints the environment’s details, including the UUID you pass to controller-env-uuid. See the osctrl environment commands for the full set of options.

For background on how the agent uses these values — the TLS hostname and the per-environment enrollment, configuration, logging, and distributed-query endpoints — see the upstream osquery remote server (TLS) API documentation and the Configurations reference.

Obtain an enrollment secret¶

The enrollment secret is a shared secret the agent presents to the controller’s enroll endpoint. The agent uses it once to negotiate a per-node key, which it then uses to authenticate subsequent requests. osctrl generates a secret for each environment; print it with osctrl-cli:

osctrl-cli environment node-actions secret --name corp

See Simple shared secret enrollment upstream for how the secret is used during enrollment.

Apply the configuration to the charm¶

Point the agent at the controller and environment:

juju config osquery \
  controller-uri=<controller-uri> \
  controller-env-uuid=<controller-env-uuid>

Provide the enrollment secret through a Juju secret so it isn’t stored in plain-text configuration:

secret_id=$(juju add-secret osquery-enroll enroll-secret=<enrollment-secret>)
juju grant-secret osquery-enroll osquery
juju config osquery enroll-secret="$secret_id"

If your controller requires mutual TLS, also provide the certificates:

juju config osquery \
  tls-server-certs="$(cat server-ca.pem)" \
  tls-client-cert="$(cat client.pem)" \
  tls-client-key="$(cat client-key.pem)"

See Providing secrets for more on the secret-backed options.

Verify enrollment¶

Watch the deployment until it settles into active:

juju status --watch 2s

If a required option is missing, the unit reports blocked with a message naming it. For deeper checks, see how to troubleshoot.

Rotate credentials¶

Rotate the enrollment secret and TLS credentials periodically, and immediately if you suspect they’re compromised. Rotation has two sides: issue new credentials on osctrl, then update the charm’s configuration to match.

On osctrl, rotate the environment’s enrollment URL and read back the new secret:

osctrl-cli environment node-actions rotate-enroll --name corp
osctrl-cli environment node-actions secret --name corp

Then update the Juju secret so the charm reconciles the agent on its next configuration change:

juju update-secret osquery-enroll enroll-secret=<new-enrollment-secret>

If you also pin the controller’s certificate, re-apply tls-server-certs with the new PEM after rotating it on osctrl. The charm re-renders the flagfile and restarts the agent on the next reconcile. See how to manage secrets for working with Juju secrets.