Architecture

Overview

Connection Flow

1. Registration — Starla connects via SSH to a registration server (reg03.atlas.ripe.net:443), sends an INIT command with probe identity, and receives a controller assignment.
2. Controller INIT — Connects to the assigned controller via SSH, sends another INIT, and receives a SESSION_ID and REMOTE_PORT.
3. KEEP session — Opens a long-lived SSH connection to the controller running the KEEP command. This connection carries both measurement commands (inbound) and result uploads (outbound).

No Local Ports

All communication flows through the SSH tunnel — starla binds no local TCP ports.

• Measurement commands arrive via SSH reverse tunnel (forwarded-tcpip). The SSH handler pipes them directly to the telnet command parser through an in-process DuplexStream bridge.
• Result uploads go out via SSH direct-tcpip channels. Each upload opens a fresh channel to 127.0.0.1:8080 on the controller side and writes a raw HTTP/1.1 POST with the measurement results.

Crate Structure

starla-probe          Main binary — orchestrates everything
starla-common         Shared types, config, paths, logging
starla-controller     SSH connection, telnet parser, channel streams
starla-measurements   Ping, DNS, traceroute, HTTP, TLS, NTP implementations
starla-scheduler      Measurement scheduling and concurrent execution
starla-results        Result formatting, persistent queue, upload transport
starla-database       RocksDB measurement storage
starla-network        Raw sockets, source address detection
starla-metrics        Prometheus metrics export (optional)

Measurement Execution

The controller sends measurement schedules as CRONLINE or JSON commands over the telnet interface. The scheduler parses these into MeasurementJobs and executes them concurrently via tokio::spawn.

Each measurement type implements the Measurement trait:

pub trait Measurement: Send + Sync {
    async fn execute(&self) -> anyhow::Result<MeasurementResult>;
}

Results are formatted to match the official C probe's JSON output exactly (field order, spacing, numeric precision) and queued in the persistent RocksDB-backed result queue for upload.

Result Upload

The result handler periodically drains the queue and uploads batches via the UploadTransport trait. In production, this opens SSH direct-tcpip channels and writes raw HTTP/1.1:

POST /?PROBE_ID=12345&SESSION_ID=abc HTTP/1.1
Content-Type: application/x-www-form-urlencoded

P_TO_C_REPORT
RESULT { "id":"1001", "fw":5120, ... }
RESULT { "id":"1002", "fw":5120, ... }

SESSION_ID abc

Failed uploads are re-queued with exponential backoff. Results older than 1 hour or with more than 5 failed attempts are dropped.

State & Directories

State directory (persistent):
  probe_key         SSH private key (generated on first run)
  probe_key.pub     SSH public key (register this at atlas.ripe.net)
  probe_id          Assigned probe ID
  known_hosts       Controller SSH host keys (TOFU)

Runtime directory (ephemeral):
  measurements/     RocksDB measurement database
  result_queue/     RocksDB result upload queue

Path resolution priority: CLI flag > systemd env > container paths (/state, /config) > XDG > standard Linux paths. See paths module for details.

For the full protocol specification including all command formats, result line quirks, and known issues, see the Protocol Reference.