Skip to main content
Mole probing

muti-metroo probe

Check if you can reach a listener before deploying an agent. Useful for testing firewall rules and TLS configuration without running a full agent.

Quick test:

# Test a QUIC listener
muti-metroo probe server.example.com:4433

# Test different transports to find what's not blocked
muti-metroo probe --transport quic server.example.com:4433   # UDP
muti-metroo probe --transport h2 server.example.com:443      # HTTPS
muti-metroo probe --transport ws server.example.com:443      # WebSocket

Synopsis​

muti-metroo probe [flags] <address>

What It Tests​

  1. Transport-level connection - Establishes a TCP/TLS connection using the specified transport (QUIC, HTTP/2, or WebSocket)
  2. Protocol handshake - Performs a PEER_HELLO exchange to verify it's a real Muti Metroo listener

The probe operates standalone - no running agent needed.

Flags​

FlagShortDefaultDescription
--transport-TquicTransport type: quic, h2, ws
--path/meshHTTP path for h2/ws transports
--timeout-t10sConnection timeout
--caCA certificate file for TLS verification
--certClient certificate file for mTLS
--keyClient key file for mTLS
--insecurefalseSkip TLS certificate verification
--plaintextfalsePlaintext mode (no TLS) for WebSocket behind reverse proxy
--jsonfalseOutput results as JSON
-h, --helpShow help

Examples​

Test a QUIC Listener​

QUIC is the default transport:

muti-metroo probe server.example.com:4433

Output on success:

Probing quic://server.example.com:4433...

[OK] Connection successful!
  Transport:    quic
  Address:      server.example.com:4433
  Remote ID:    abc123def456789012345678
  Display Name: Agent-B
  RTT:          23ms

Test an HTTP/2 Listener​

muti-metroo probe --transport h2 server.example.com:443 --path /mesh

Test a WebSocket Listener​

muti-metroo probe --transport ws server.example.com:443 --path /mesh

Test Plaintext WebSocket (Behind Reverse Proxy)​

When the listener is behind a reverse proxy that handles TLS termination:

muti-metroo probe --transport ws --plaintext localhost:8080 --path /mesh

Test with Self-Signed Certificate​

When testing against a listener with a self-signed certificate:

muti-metroo probe --insecure server.example.com:4433

Test with Specific CA Certificate​

When using a private CA:

muti-metroo probe --ca ./certs/ca.crt server.example.com:4433

Test with mTLS (Mutual TLS)​

When the listener requires client authentication:

muti-metroo probe --ca ./certs/ca.crt --cert ./certs/client.crt --key ./certs/client.key server.example.com:4433

JSON Output for Scripting​

muti-metroo probe --json server.example.com:4433

Output:

{
  "success": true,
  "transport": "quic",
  "address": "server.example.com:4433",
  "remote_id": "abc123def456789012345678",
  "remote_display_name": "Agent-B",
  "rtt_ms": 23
}

Failed Connection Example​

muti-metroo probe server.example.com:4433

Output on failure:

Probing quic://server.example.com:4433...

[FAILED] Connection failed
  Transport:  quic
  Address:    server.example.com:4433
  Error:      Connection timed out - firewall may be blocking

Error Messages​

The probe provides helpful error messages for common failure scenarios:

Error MessageLikely Cause
Could not resolve hostnameDNS lookup failed
Connection refused - listener not running or port blockedNo process listening on the port
Connection timed out - firewall may be blockingFirewall dropping packets
TLS error - certificate signed by unknown authorityNeed --ca or --insecure
TLS error - certificate has expiredListener certificate expired
Connected but handshake failed - not a Muti Metroo listener?Port is open but not a Muti Metroo listener
Connected but received invalid responseProtocol mismatch

Use Cases​

Pre-deployment Verification​

Before deploying an agent to a remote machine, verify the listener is reachable:

# On the remote machine (or a machine with similar network access)
muti-metroo probe --insecure relay.example.com:4433

Firewall Troubleshooting​

Test different transports to identify what's blocked:

# Test QUIC (UDP)
muti-metroo probe --transport quic server.example.com:4433

# Test HTTP/2 (TCP, HTTPS)
muti-metroo probe --transport h2 server.example.com:443

# Test WebSocket (TCP, HTTPS)
muti-metroo probe --transport ws server.example.com:443

TLS Configuration Validation​

Verify TLS is configured correctly:

# Should work with proper CA
muti-metroo probe --ca ./certs/ca.crt server.example.com:4433

# Should fail without CA (unless using --insecure)
muti-metroo probe server.example.com:4433

Wizard Integration​

The setup wizard automatically tests peer connectivity when configuring peer connections. After entering peer details, the wizard will probe the listener and show results:

[INFO] Testing connectivity to peer...
[OK] Connected successfully!
[INFO] Remote agent: Agent-B (abc123def456)
[INFO] Round-trip time: 23ms

If the connection fails, you can choose to:

  1. Continue anyway (set up the listener later)
  2. Retry the connection test
  3. Re-enter peer configuration
  4. Skip this peer

Exit Codes​

CodeMeaning
0Probe successful
1Probe failed or error

muti-metroo probe listen

Start a test listener to validate transport configurations before deploying a full agent. The listener accepts probe connections and responds to handshakes, making it useful for testing TLS certificates, firewall rules, and transport settings.

Synopsis​

muti-metroo probe listen [flags]

What It Does​

  1. Starts a minimal listener - Binds to the specified address using the chosen transport
  2. Accepts probe connections - Waits for incoming connections from muti-metroo probe
  3. Responds to handshakes - Performs PEER_HELLO/PEER_HELLO_ACK exchange
  4. Reports connection events - Displays information about each connection attempt

The listener runs until interrupted (Ctrl+C).

Flags​

FlagShortDefaultDescription
--transport-TquicTransport type: quic, h2, ws
--address-a0.0.0.0:4433Listen address
--path/meshHTTP path for h2/ws transports
--certTLS certificate file (ephemeral cert if not provided)
--keyTLS private key file (ephemeral key if not provided)
--caCA certificate for client verification (mTLS)
--plaintextfalsePlaintext mode (no TLS) for WebSocket behind reverse proxy
--name-nprobe-listenerDisplay name for this listener
--jsonfalseOutput connection events as JSON
--alpnCustom ALPN protocol
--http-headerCustom HTTP header for h2 transport
--ws-subprotocolCustom WebSocket subprotocol
-h, --helpShow help

Examples​

Basic QUIC Listener​

Start a listener with ephemeral self-signed certificates (no cert files needed):

muti-metroo probe listen -T quic -a 0.0.0.0:4433

Output:

Probe Listener
==============
Transport:  quic
Address:    0.0.0.0:4433
Name:       probe-listener
TLS:        enabled (ephemeral certificates)

Listening for connections... (Ctrl+C to stop)

[2026-01-21 10:30:45] [OK] 192.168.1.100:54321
  Remote ID:   abc123def456789012345678
  Remote Name: probe
  RTT:         5ms

HTTP/2 Listener​

muti-metroo probe listen -T h2 -a 0.0.0.0:443 --path /mesh

WebSocket Listener​

muti-metroo probe listen -T ws -a 0.0.0.0:443 --path /mesh

Plaintext WebSocket (Behind Reverse Proxy)​

When running behind nginx, Caddy, or another reverse proxy that handles TLS:

muti-metroo probe listen -T ws -a 127.0.0.1:8080 --path /mesh --plaintext

With Static TLS Certificates​

muti-metroo probe listen -T quic -a 0.0.0.0:4433 \
  --cert ./certs/server.crt \
  --key ./certs/server.key

With mTLS (Require Client Certificates)​

muti-metroo probe listen -T quic -a 0.0.0.0:4433 \
  --cert ./certs/server.crt \
  --key ./certs/server.key \
  --ca ./certs/ca.crt

JSON Output for Scripting​

muti-metroo probe listen --json -T quic -a 0.0.0.0:4433

Each connection event is output as a JSON line:

{"timestamp":"2026-01-21T10:30:45Z","remote_addr":"192.168.1.100:54321","remote_id":"abc123def456","remote_name":"probe","success":true,"rtt_ms":5}

Custom Display Name​

muti-metroo probe listen --name "test-server-east" -T quic -a 0.0.0.0:4433

Use Cases​

TLS Certificate Validation​

Test that your certificates work correctly before deploying:

# Terminal 1: Start listener with your certificates
muti-metroo probe listen -T quic -a 0.0.0.0:4433 \
  --cert ./certs/server.crt --key ./certs/server.key

# Terminal 2: Test connection with CA verification
muti-metroo probe --ca ./certs/ca.crt localhost:4433

mTLS Configuration Testing​

Verify mutual TLS is configured correctly:

# Terminal 1: Listener requiring client certs
muti-metroo probe listen -T quic -a 0.0.0.0:4433 \
  --cert ./certs/server.crt --key ./certs/server.key \
  --ca ./certs/ca.crt

# Terminal 2: Client with certificate
muti-metroo probe --ca ./certs/ca.crt \
  --cert ./certs/client.crt --key ./certs/client.key \
  localhost:4433

Reverse Proxy Testing​

Test WebSocket configuration behind a reverse proxy:

# Start plaintext listener (proxy handles TLS)
muti-metroo probe listen -T ws -a 127.0.0.1:8080 --path /mesh --plaintext

# Test through the proxy
muti-metroo probe -T ws proxy.example.com:443 --path /mesh

Network Path Verification​

Test that a specific port/protocol is reachable:

# On server: start listener
muti-metroo probe listen -T quic -a 0.0.0.0:4433

# On client: verify connectivity
muti-metroo probe --insecure server.example.com:4433