Skip to main content
Mole pinging

ICMP Ping WebSocket API

Send ICMP echo requests through agents to test connectivity and measure latency. The CLI handles this automatically - this reference is for building custom integrations.

Using the CLI (recommended):

muti-metroo ping abc123 8.8.8.8
muti-metroo ping -c 10 abc123 192.168.1.1

WebSocket endpoint for custom clients:

ws://localhost:8080/agents/{agent-id}/icmp

WebSocket Endpoint​

GET /agents/{agent-id}/icmp

Subprotocol​

The WebSocket uses the muti-metroo-icmp subprotocol.

Message Protocol​

All messages use JSON text format.

Message Types​

TypeDirectionDescription
initClient -> ServerInitialize session with destination IP
init_ackServer -> ClientAcknowledge session start
echoClient -> ServerSend echo request
replyServer -> ClientEcho reply received
errorServer -> ClientError response

Session Flow​

1. Connect​

WebSocket: ws://localhost:8080/agents/abc123/icmp
Subprotocol: muti-metroo-icmp

2. Initialize Session​

Send init message with destination IP:

{
  "type": "init",
  "dest_ip": "8.8.8.8"
}
FieldTypeDescription
typestringMust be "init"
dest_ipstringDestination IP address (IPv4)

3. Receive Acknowledgment​

Success:

{
  "type": "init_ack",
  "success": true
}

Failure:

{
  "type": "init_ack",
  "success": false,
  "error": "ICMP session failed: icmp not enabled"
}

4. Send Echo Requests​

{
  "type": "echo",
  "sequence": 1,
  "payload": "optional payload data"
}
FieldTypeDescription
typestringMust be "echo"
sequencenumberSequence number for tracking
payloadstringOptional payload data

5. Receive Replies​

Success:

{
  "type": "reply",
  "sequence": 1
}

Timeout or error:

{
  "type": "error",
  "sequence": 1,
  "error": "timeout"
}

Error Handling​

Common init errors:

ErrorCause
invalid destination IPdest_ip is not a valid IP address
ICMP session failed: icmp not enabledTarget agent has ICMP disabled
failed to open ICMP sessionNetwork or routing error

Custom Client Example​

const ws = new WebSocket(
  'ws://localhost:8080/agents/abc123/icmp',
  'muti-metroo-icmp'
);

ws.onopen = () => {
  // Initialize session
  ws.send(JSON.stringify({
    type: 'init',
    dest_ip: '8.8.8.8'
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  if (msg.type === 'init_ack' && msg.success) {
    // Send echo request
    ws.send(JSON.stringify({
      type: 'echo',
      sequence: 1,
      payload: ''
    }));
  } else if (msg.type === 'reply') {
    console.log(`Reply seq=${msg.sequence}`);
  } else if (msg.type === 'error') {
    console.log(`Error seq=${msg.sequence}: ${msg.error}`);
  }
};

Requirements​

The target agent must have ICMP enabled:

icmp:
  enabled: true

See Also​