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

```bash
# 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

```bash
# 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):
```bash
mount | grep cgroup2
# Expected: cgroup2 on /sys/fs/cgroup type cgroup2
```

### Permissions

The collector requires elevated privileges:

**Option 1: Root**
```bash
sudo stella signals start
```

**Option 2: Capabilities (preferred)**
```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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`:

```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:

```yaml
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:

```yaml
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:

```yaml
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

```bash
# 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

```bash
# 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

```dockerfile
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
```

```bash
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

```yaml
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

```bash
# 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

```bash
# 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

```bash
# 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](operator-runbook.md) for detailed troubleshooting procedures.

### Quick Checks

```bash
# 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
```