GitHub

Certstream quick start

Run the server, connect to the stream, and configure persistent state.

Run the server

Docker 
docker run -d -p 8080:8080 ghcr.io/reloading01/certstream-server-rust:latest

# or from Docker Hub
docker run -d -p 8080:8080 reloading01/certstream-server-rust:latest
Script Linux, macOS 
curl -fsSL https://raw.githubusercontent.com/\
reloading01/certstream-server-rust/main/install.sh | sh
Homebrew 
brew install reloading01/tap/certstream-server-rust
Debian, Ubuntu 
sudo dpkg -i certstream-server-rust_*_amd64.deb
sudo systemctl enable --now certstream-server-rust
Fedora, RHEL 
sudo rpm -i certstream-server-rust-*.x86_64.rpm
sudo systemctl enable --now certstream-server-rust
Cargo 
cargo install certstream-server-rust

The stream is now on ws://localhost:8080/. Packages and signed checksums are on the releases page. The .deb and .rpm packages install a systemd service and keep log positions across restarts.

Connect

Full certificate stream

Python 
import certstream

def callback(message, context):
    if message["message_type"] == "certificate_update":
        cert = message["data"]["leaf_cert"]
        print(cert["all_domains"])

certstream.listen_for_events(
    callback, url="ws://localhost:8080/")
JavaScript 
const ws = new WebSocket("ws://localhost:8080/");

ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);
    if (msg.message_type === "certificate_update") {
        console.log(msg.data.leaf_cert.all_domains);
    }
};
Command line 
# WebSocket
websocat ws://localhost:8080/

# Server-Sent Events
curl -N http://localhost:8080/sse

Domain names only

JavaScript 
const ws = new WebSocket(
    "ws://localhost:8080/domains-only");

ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);
    if (msg.message_type === "dns_entries") {
        console.log(msg.data);
        // ["example.com", "www.example.com"]
    }
};
Command line 
# WebSocket
websocat ws://localhost:8080/domains-only

# Server-Sent Events
curl -N "http://localhost:8080/sse?stream=domains"

The /domains-only stream sends message_type: "dns_entries", and its data is a flat array of domain names instead of a nested certificate object.

Persist state

Docker with state persistence 
docker run -d \
  --name certstream \
  --restart unless-stopped \
  -p 8080:8080 \
  -v certstream-state:/data \
  -e CERTSTREAM_CT_LOG_STATE_FILE=/data/state.json \
  ghcr.io/reloading01/certstream-server-rust:latest

The state file records how far each CT log has been read, so the server resumes after a restart. The full configuration reference is in the API documentation.