<!-- vale Canonical.007-Headings-sentence-case = NO -->

<a id="index"></a>

# osquery operator

<!-- vale Canonical.007-Headings-sentence-case = YES -->

A [Juju](https://juju.is/) [charm](https://canonical.com/juju/docs/juju-cli/3.6/reference/charm/#charm)
deploying and managing [osquery](https://www.osquery.io/) on virtual machines and bare-metal hosts.

<!-- TODO: Replace the upstream link above if a Canonical SecOps osquery product
page becomes available. -->

The osquery agent exposes an operating system as a high-performance relational
database, letting security and operations teams query the state of a host with
SQL. This charm deploys the Canonical SecOps fork of osquery as a
[subordinate](https://canonical.com/juju/docs/juju-cli/3.6/reference/charm/#subordinate-charm)
agent that runs alongside a principal application on the same machine. It
installs osquery from the [c-osquery snap](https://snapcraft.io/c-osquery),
runs it in daemon mode, and connects it over TLS to a centrally managed osquery controller that supplies the
agent’s configuration and collects its logs.

Like any Juju charm, this charm supports one-line deployment, configuration,
integration, scaling, and more. For osquery, this includes:

* Installing and running the `osqueryd` daemon on any principal machine.
* Translating Juju configuration into the osquery flagfile and reconciling the
  daemon whenever the configuration changes.
* Enrolling the agent with an osquery controller over TLS, with the enrollment
  secret and client certificates delivered through Juju secrets.

This charm makes operating osquery fleets simple and consistent for security,
DevOps, and SRE teams through Juju’s clean interface.

## In this documentation

|                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Get started        | [Deploy the osquery charm](https://canonical.com/juju/docs/osquery-charm/latest/tutorial/basic-deployment/index.html.md#tutorial-basic-deployment) | [Enroll an osquery controller](https://canonical.com/juju/docs/osquery-charm/latest/tutorial/advanced-deployment/index.html.md#tutorial-advanced-deployment)                                                                                                                                                                                                                                                                         |
| Deployment         | [Configurations](https://canonical.com/juju/docs/osquery-charm/latest/reference/configurations/index.html.md#reference-configurations) | [Relation endpoints](https://canonical.com/juju/docs/osquery-charm/latest/reference/relation-endpoints/index.html.md#reference-relation-endpoints)                                                                                                                                                                                                                                                                                              |
| Operations         | [Upgrade](https://canonical.com/juju/docs/osquery-charm/latest/how-to/upgrade/index.html.md#how-to-upgrade) | [Redeploy](https://canonical.com/juju/docs/osquery-charm/latest/how-to/redeploy/index.html.md#how-to-redeploy) | [Back up and restore](https://canonical.com/juju/docs/osquery-charm/latest/how-to/back-up-restore/index.html.md#how-to-back-up-restore) | [Troubleshoot](https://canonical.com/juju/docs/osquery-charm/latest/how-to/troubleshoot/index.html.md#how-to-troubleshoot) | [Metrics](https://canonical.com/juju/docs/osquery-charm/latest/reference/metrics/index.html.md#reference-metrics) | [Terraform](https://canonical.com/juju/docs/osquery-charm/latest/how-to/terraform/index.html.md#how-to-terraform) |
| osquery controller | [Overview](https://canonical.com/juju/docs/osquery-charm/latest/reference/osquery-controller/index.html.md#reference-osquery-controller) | [Enroll the agent](https://canonical.com/juju/docs/osquery-charm/latest/how-to/enroll-with-controller/index.html.md#how-to-enroll-with-controller)                                                                                                                                                                                                                                                                                                 |
| Design             | [Architecture](https://canonical.com/juju/docs/osquery-charm/latest/reference/charm-architecture/index.html.md#reference-charm-architecture) | [Design](https://canonical.com/juju/docs/osquery-charm/latest/explanation/charm-design/index.html.md#explanation-charm-design)                                                                                                                                                                                                                                                                                                            |
| Security           | [Overview](https://canonical.com/juju/docs/osquery-charm/latest/explanation/security/index.html.md#explanation-security) | [Cryptography](https://canonical.com/juju/docs/osquery-charm/latest/reference/cryptographic-overview/index.html.md#reference-cryptographic-overview)                                                                                                                                                                                                                                                                                                          |

## How this documentation is organized

This documentation uses the [Diátaxis documentation structure](https://diataxis.fr/).

- The [Tutorial](https://canonical.com/juju/docs/osquery-charm/latest/tutorial/index.html.md#tutorial-index) takes you step-by-step through a basic deployment of the osquery charm.
- [How-to guides](https://canonical.com/juju/docs/osquery-charm/latest/how-to/index.html.md#how-to-index) assume you have basic familiarity with the osquery charm. Learn more about setting up, using, maintaining, and contributing to this charm.
- [Reference](https://canonical.com/juju/docs/osquery-charm/latest/reference/index.html.md#reference-index) provides a guide to configurations, relations, and other technical details.
- [Explanation](https://canonical.com/juju/docs/osquery-charm/latest/explanation/index.html.md#explanation-index) includes topic overviews, background and context and detailed discussion.
- [Release notes](https://canonical.com/juju/docs/osquery-charm/latest/release-notes/index.html.md#release-notes-index) holds all the release notes for the charm, including any system or upgrade requirements.

### Contributing to this documentation

Documentation is an important part of this project, and we take the same open-source approach
to the documentation as the code. As such, we welcome community contributions, suggestions, and
constructive feedback on our documentation.
See [How to contribute](https://canonical.com/juju/docs/osquery-charm/latest/how-to/contribute/index.html.md#how-to-contribute) for more information.

If there’s a particular area of documentation that you’d like to see that’s missing, please
[file a bug](https://github.com/canonical/osquery-operator/issues).

## Project and community

The osquery Operator is a member of the Ubuntu family. It’s an open-source project that warmly welcomes community
projects, contributions, suggestions, fixes, and constructive feedback.

### Governance and policies

- [Code of conduct](https://ubuntu.com/community/code-of-conduct)

### Get involved

- [Get support](https://discourse.charmhub.io/)
- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
- [Contribute](https://canonical.com/juju/docs/osquery-charm/latest/how-to/contribute/index.html.md#how-to-contribute)

### Releases

- [Release notes](https://canonical.com/juju/docs/osquery-charm/latest/release-notes/index.html.md#release-notes-index)

Thinking about using the osquery Operator for your next project?
[Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)!

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