Run OBI as a standalone process

OBI can run as a standalone Linux OS process with elevated privileges that can inspect other running processes.

Download and verify

OBI provides pre-built binaries for Linux (amd64 and arm64). Download the latest release from the releases page. Each release includes:

• obi-v<version>-linux-amd64.tar.gz - Linux AMD64/x86_64 archive
• obi-v<version>-linux-arm64.tar.gz - Linux ARM64 archive
• obi-v<version>-linux-amd64.cyclonedx.json - CycloneDX SBOM for the AMD64 archive
• obi-v<version>-linux-arm64.cyclonedx.json - CycloneDX SBOM for the ARM64 archive
• obi-v<version>-source-generated.cyclonedx.json - CycloneDX SBOM for the source-generated archive
• obi-java-agent-v<version>.cyclonedx.json - CycloneDX SBOM for the embedded Java agent and its Java dependencies
• SHA256SUMS - Checksums for verification of the release archives and SBOM assets

Container images for the same release are also published. For image pull and signature verification instructions, see Run OBI as a Docker container.

Set your desired version and architecture:

# Set your desired version (find latest at
# https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases)
VERSION=0.6.0

# Determine your architecture
# For Intel/AMD 64-bit: amd64
# For ARM 64-bit: arm64
ARCH=amd64

# Download the archive for your architecture
wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/obi-v${VERSION}-linux-${ARCH}.tar.gz

# Download checksums
wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/SHA256SUMS

# Verify the archive
sha256sum -c SHA256SUMS --ignore-missing

# Extract the archive
tar -xzf obi-v${VERSION}-linux-${ARCH}.tar.gz

Successful verification prints an OK result for each downloaded file:

obi-v${VERSION}-linux-${ARCH}.tar.gz: OK

If verification fails, sha256sum reports FAILED. When that happens:

• confirm that VERSION matches the archive and SHA256SUMS you downloaded
• remove any partially downloaded files and fetch them again
• verify only the files you actually downloaded from that release

The archive contains:

• obi - Main OBI binary
• k8s-cache - Kubernetes cache binary
• LICENSE - Project license
• NOTICE - Legal notices
• NOTICES/ - Third-party licenses and attributions

SBOMs

CycloneDX SBOM files are optional metadata for supply-chain review and automation. They are not required to install or run OBI.

The published SBOMs describe the contents of the binary archives and embedded components in CycloneDX JSON format. They can be used with standard SBOM tooling to inspect dependencies, licenses, and components without executing the binaries.

Download the SBOMs you want to inspect:

# SBOM for the binary archive you downloaded
wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/obi-v${VERSION}-linux-${ARCH}.cyclonedx.json

# SBOM for the embedded Java agent and its Java dependencies
wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/obi-java-agent-v${VERSION}.cyclonedx.json

# Optional: verify the downloaded SBOM files against SHA256SUMS too
sha256sum -c SHA256SUMS --ignore-missing

Example inspection commands:

# List component names and versions from the archive SBOM
jq '.components[] | {name, version}' obi-v${VERSION}-linux-${ARCH}.cyclonedx.json

# Scan the SBOM with Grype
grype sbom:obi-v${VERSION}-linux-${ARCH}.cyclonedx.json

# Inspect the Java agent dependency graph
jq '.components[] | {name, version}' obi-java-agent-v${VERSION}.cyclonedx.json

Install to system

After extracting the archive, you can install the binaries to a location in your PATH so they can be used from any directory.

The following example installs to /usr/local/bin, which is a standard location on most Linux distributions. You can install to any other directory in your PATH:

# Move binaries to a directory in your PATH
sudo cp obi /usr/local/bin/

# Verify installation
obi --version

Set up OBI

1. Create a configuration file following the configuration options documentation. You can start with the OBI configuration YAML example.

2. Run OBI as a privileged process:

   sudo obi --config=<path to config file>
   

   If you did not install OBI to your PATH, you can run it from the extracted directory:

   sudo ./obi --config=<path to config file>
   

Permissions

OBI requires elevated privileges to function properly. For more information about the specific capabilities required, see the security documentation.