git.stella-ops.org/docs/reachability/deployment-guide.md

Deployment Guide

Prerequisites

Kernel Requirements

Minimum: Linux 4.14 with eBPF support Recommended: Linux 5.8+ with BTF and ring buffer support

Verify Kernel Configuration

# Check eBPF support
zcat /proc/config.gz 2>/dev/null | grep -E "CONFIG_BPF|CONFIG_DEBUG_INFO_BTF" || \
cat /boot/config-$(uname -r) | grep -E "CONFIG_BPF|CONFIG_DEBUG_INFO_BTF"

# Required settings:
# CONFIG_BPF=y
# CONFIG_BPF_SYSCALL=y
# CONFIG_BPF_JIT=y (recommended)
# CONFIG_DEBUG_INFO_BTF=y (for CO-RE)

Verify BTF Availability

# Check for BTF in kernel
ls -la /sys/kernel/btf/vmlinux

# If missing, check BTFHub or kernel debug packages

Container Runtime

Supported runtimes:

• containerd 1.4+
• Docker 20.10+
• CRI-O 1.20+

Verify cgroup v2 is available (recommended):

mount | grep cgroup2
# Expected: cgroup2 on /sys/fs/cgroup type cgroup2

Permissions

The collector requires elevated privileges:

Option 1: Root

sudo stella signals start

Option 2: Capabilities (preferred)

# Grant required capabilities
sudo setcap cap_bpf,cap_perfmon,cap_sys_ptrace+ep /usr/bin/stella

# Or run with specific capabilities
sudo capsh --caps="cap_bpf,cap_perfmon,cap_sys_ptrace+eip" -- -c "stella signals start"

Required capabilities:

• CAP_BPF: Load and manage eBPF programs
• CAP_PERFMON: Access performance monitoring (ring buffer)
• CAP_SYS_PTRACE: Attach uprobes to processes

Installation

Standard Installation

# Install StellaOps CLI
curl -fsSL https://stella.ops/install.sh | bash

# Verify installation
stella version
stella signals --help

Air-Gap Installation

For disconnected environments, use the offline bundle:

# Download bundle (on connected machine)
stella bundle create --include-probes ebpf-reachability \
  --output stellaops-offline.tar.gz

# Transfer to air-gapped system
scp stellaops-offline.tar.gz airgap-host:

# Install on air-gapped system
tar -xzf stellaops-offline.tar.gz
cd stellaops-offline
./install.sh

The bundle includes:

• Pre-compiled eBPF probes for common kernel versions
• BTF files for kernels without built-in BTF
• All runtime dependencies

Pre-Compiled Probes

If CO-RE probes fail to load, use kernel-specific probes:

# List available pre-compiled probes
stella signals probes list

# Install probes for specific kernel
stella signals probes install --kernel $(uname -r)

# Verify probe compatibility
stella signals probes verify

Configuration

Basic Configuration

Create /etc/stellaops/signals.yaml:

signals:
  enabled: true

  # Output directory for evidence files
  output_directory: /var/lib/stellaops/evidence

  # Ring buffer size (default 256KB)
  ring_buffer_size: 262144

  # Maximum events per second (0 = unlimited)
  max_events_per_second: 0

  # Rotation settings
  rotation:
    max_size_mb: 100
    max_age_hours: 1

  # Signing configuration
  signing:
    enabled: true
    key_id: fulcio  # or KMS key ARN
    submit_to_rekor: true

Probe Selection

Enable specific probes:

signals:
  probes:
    # Tracepoints
    sys_enter_openat: true
    sched_process_exec: true
    inet_sock_set_state: true

    # Uprobes
    libc_connect: true
    libc_accept: true
    openssl_read: false  # Disable if not needed
    openssl_write: false

Filtering

Configure what to capture:

signals:
  filters:
    # Target specific containers (empty = all)
    target_containers: []

    # Target specific namespaces
    target_namespaces: []

    # File path filtering
    paths:
      allowlist:
        - /etc/**
        - /var/lib/**
        - /home/**
      denylist:
        - /proc/**
        - /sys/**
        - /dev/**

    # Network filtering
    networks:
      # Capture connections to these CIDRs
      allowlist:
        - 10.0.0.0/8
        - 172.16.0.0/12
      # Exclude these destinations
      denylist:
        - 127.0.0.0/8

Resource Limits

Prevent runaway resource usage:

signals:
  resources:
    # Maximum memory for caches
    max_cache_memory_mb: 256

    # Symbol cache entries
    symbol_cache_max_entries: 100000

    # Container cache TTL
    container_cache_ttl_seconds: 300

    # Event rate limiting
    max_events_per_second: 50000

Starting the Collector

Systemd Service

# Enable and start
sudo systemctl enable stellaops-signals
sudo systemctl start stellaops-signals

# Check status
sudo systemctl status stellaops-signals

# View logs
sudo journalctl -u stellaops-signals -f

Manual Start

# Start with default configuration
stella signals start

# Start with custom config
stella signals start --config /path/to/signals.yaml

# Start with verbose logging
stella signals start --verbose

# Start in foreground (for debugging)
stella signals start --foreground

Docker Deployment

FROM stellaops/signals-collector:latest

# Mount host systems
VOLUME /sys/kernel/debug
VOLUME /sys/fs/cgroup
VOLUME /proc

# Evidence output
VOLUME /var/lib/stellaops/evidence

# Run with required capabilities
# docker run --privileged or with specific caps

docker run -d \
  --name stellaops-signals \
  --privileged \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -v /sys/fs/cgroup:/sys/fs/cgroup:ro \
  -v /proc:/host/proc:ro \
  -v /var/lib/stellaops/evidence:/evidence \
  stellaops/signals-collector:latest

Kubernetes DaemonSet

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: stellaops-signals
  namespace: stellaops
spec:
  selector:
    matchLabels:
      app: stellaops-signals
  template:
    metadata:
      labels:
        app: stellaops-signals
    spec:
      hostPID: true
      hostNetwork: true
      containers:
      - name: collector
        image: stellaops/signals-collector:latest
        securityContext:
          privileged: true
        volumeMounts:
        - name: sys-kernel-debug
          mountPath: /sys/kernel/debug
          readOnly: true
        - name: sys-fs-cgroup
          mountPath: /sys/fs/cgroup
          readOnly: true
        - name: proc
          mountPath: /host/proc
          readOnly: true
        - name: evidence
          mountPath: /var/lib/stellaops/evidence
      volumes:
      - name: sys-kernel-debug
        hostPath:
          path: /sys/kernel/debug
      - name: sys-fs-cgroup
        hostPath:
          path: /sys/fs/cgroup
      - name: proc
        hostPath:
          path: /proc
      - name: evidence
        hostPath:
          path: /var/lib/stellaops/evidence
          type: DirectoryOrCreate

Verification

Verify Probes Attached

# List attached probes
stella signals status

# Expected output:
# Probes:
#   tracepoint/syscalls/sys_enter_openat: attached
#   tracepoint/sched/sched_process_exec: attached
#   tracepoint/sock/inet_sock_set_state: attached
#   uprobe/libc.so.6:connect: attached
#   uprobe/libc.so.6:accept: attached

Verify Events Flowing

# Watch live events
stella signals watch

# Check event counts
stella signals stats

# Expected output:
# Events collected: 15234
# Events/second: 847
# Ring buffer usage: 12%

Verify Evidence Files

# List evidence chunks
ls -la /var/lib/stellaops/evidence/

# Verify chain integrity
stella signals verify-chain /var/lib/stellaops/evidence/

Troubleshooting

See operator-runbook.md for detailed troubleshooting procedures.

Quick Checks

# Check kernel support
stella signals check-kernel

# Verify permissions
stella signals check-permissions

# Test probe loading
stella signals test-probes

# Validate configuration
stella signals validate-config --config /etc/stellaops/signals.yaml