Getting started

Omicron Tools

This directory is home to a number of tools related to Omicron development. There are some additional developer tools implemented as xtasks: Run cargo xtask -h from the root of the repository for details.

Note

This document is intended to be an overview of the lay of the land here. The source of truth is always the tools themselves: That said, if you notice anything out of date, incorrect, or otherwise confusing, please file an issue (or fix it!).

Top-Level Directories

There are several top-level directories, including:

dtrace/: a collection of dtrace scripts
include/: scripts used by other scripts
populate/: scripts to populate a running Omicron with useful guest images
reflector/: related to oxide-reflector-bot
scrimlet/: related to the setup of softnpu

Miscellaneous Scripts

There are a fair number of scripts in the root directory, but many of them are related to (or literally dependent on) each other.

Dependency Management

One class of scripts is related to downloading miscellaneous dependencies. These dependencies are not Rust dependencies, but instead various binaries depended upon by Omicron.

Some of these dependencies are services we are using in the control plane but didn’t write ourselves (e.g., cockroachdb, clickhouse), and some are software we wrote internally and fetch as artifacts from buildomat (e.g., dendrite, maghemite, console).

There are many scripts here related to each other, but they share some common naming. At a high-level:

\*\_checksums contain known checksums against which cargo xtask download will verify a dependency when it is downloaded.
\*\_version files (such as console_version) specify a version that is used by the cargo xtask download scripts.
scripts of the form install_*.sh are intended to install specific dependencies (or collections of dependencies) onto a development machine of some kind, for running or deploying Omicron. A current example is install_prerequisites.sh and the associated install_{builder,runner}_prerequisites.sh pair. See Running Omicron for details.

Updating Depedencies (Rust or otherwise)

The update_*.sh scripts are intended to help update the current supported version of a specific dependency. Some of these operate on Rust dependencies (such as propolis and crucible), while others are related to the binaries downloaded by the cargo xtask download scripts.

"Virtual Hardware" Management

Another class of scripts is related to the setup and teardown of "virtual hardware", which can be useful when deploying omicron with a real sled agent. Current examples includes the cargo xtask virtual-hardware task. See Running Omicron for details.

Oxide CLI

Control plane architecture