Deploy the osquery charm for the first time¶

The osquery charm installs and runs the osqueryd endpoint security monitoring agent on a machine. Because it’s a subordinate charm, it doesn’t run on its own: it attaches to a principal application that occupies the machine. In this tutorial you’ll deploy a simple principal application, add the osquery charm as a subordinate, and confirm that the agent is running.

What you’ll need¶

You will need a working station, e.g., a laptop, with AMD64 architecture. Your working station should have at least 2 CPU cores, 4 GB of RAM, and 20 GB of disk space.

Tip

You can use Multipass to create an isolated environment by running:

multipass launch 24.04 --name charm-tutorial-vm --cpus 4 --memory 8G --disk 50G

What you’ll do¶

Set up an isolated environment.
Deploy a principal application.
Deploy the osquery charm as a subordinate.
Integrate the two charms.
Verify the deployment.
Clean up the environment.

Set up an isolated environment¶

For this tutorial, use a clean Juju model inside a local LXD cloud. This keeps your environment isolated and easy to remove afterwards.

The fastest way to bootstrap Juju on LXD is with concierge:

sudo snap install --classic concierge
sudo concierge prepare -p machine

Alternatively, if you already have Juju (3.6 or newer) and LXD (5.21 or newer) installed, bootstrap a controller manually:

juju bootstrap localhost lxd tutorial-controller

Then, regardless of how you bootstrapped, create a dedicated model for this tutorial:

juju add-model osquery-tutorial

Deploy a principal application¶

Because the osquery charm is a subordinate, it needs a principal to attach to. The ubuntu charm is a minimal principal application that provisions a bare Ubuntu machine, which is ideal for this tutorial. Let’s deploy it now:

juju deploy ubuntu --base ubuntu@24.04

The --base flag pins the machine to Ubuntu 24.04, ensuring it matches a base the osquery subordinate supports.

Deploy the osquery charm¶

Deploy the osquery charm:

juju deploy osquery

Because it’s a subordinate, it stays in a waiting state until it’s integrated with a principal.

Integrate the charms¶

Integrate the osquery charm with the principal application over the general-info endpoint:

juju integrate ubuntu osquery

This command tells Juju to place the osquery agent on the same machine as the ubuntu unit.

Verify the deployment¶

Watch the deployment settle with:

juju status --watch 2s

Wait until the ubuntu application is active and the osquery subordinate reaches a settled state. The osquery charm blocks until it’s told which osquery controller to enroll with, so it’s expected to report a blocked status such as controller-env-uuid is required at this stage. Connecting the agent to a controller is covered in the advanced tutorial.

To confirm the subordinate is attached to the principal, view the relation with:

juju status --relations

You should see the osquery unit nested under ubuntu/0 and the general-info relation listed at the bottom:

Model             Controller           Cloud/Region         Version  SLA          Timestamp
osquery-tutorial  tutorial-controller  localhost/localhost  3.6.0    unsupported  12:00:00Z

App      Version  Status   Scale  Charm    Channel        Rev  Exposed  Message
osquery           blocked      1  osquery  latest/stable   12  no       controller-env-uuid is required
ubuntu   24.04    active       1  ubuntu   latest/stable   26  no

Unit          Workload  Agent  Machine  Public address  Ports  Message
ubuntu/0*     active    idle   0        10.1.0.10
  osquery/0*  blocked   idle            10.1.0.10               controller-env-uuid is required

Machine  State    Address    Inst id        Base          AZ  Message
0        started  10.1.0.10  juju-abc123-0  ubuntu@24.04       Running

Integration provider  Requirer              Interface  Type         Message
ubuntu:juju-info       osquery:general-info  juju-info  subordinate

You can confirm that the c-osquery snap was installed on the machine by running a command inside the unit:

juju ssh ubuntu/0 snap list c-osquery

If the snap is installed, it’s listed with its version and the channel it tracks (your revision may differ):

Name       Version  Rev  Tracking     Publisher                Notes
c-osquery  5.21.0   2    latest/edge  secops-service-account   classic

The same snap ships the osqueryi interactive shell, as c-osquery.osqueryi, which lets you query the host’s state with SQL. For example, let’s list a few of the machine’s running processes to see it in action:

juju ssh ubuntu/0 c-osquery.osqueryi "SELECT pid, name FROM processes ORDER BY pid LIMIT 5;"

osquery answers straight from the live system (your exact output will vary):

+-----+---------+
| pid | name    |
+-----+---------+
| 1   | systemd |
| ... | ...     |
+-----+---------+

Note that the osqueryi shell is just a convenience for testing. Typically the agent runs in the background as a daemon and is controlled by the osquery controller. See the advanced tutorial for instructions on enrolling the agent with a controller.

Clean up the environment¶

Once you’re done, you can remove the model and everything in it:

juju destroy-model osquery-tutorial --destroy-storage

If you used concierge, you can tear down the whole environment with:

concierge restore

Next steps¶

Now that you have a basic deployment, continue to the advanced tutorial to connect the agent to an osquery controller.