Skip to main content
Mole with ICMP

ICMP Relay

Ping remote hosts through your mesh network. Test connectivity, measure latency, and diagnose network issues - all through your encrypted tunnel.

# Ping through the mesh
muti-metroo ping 8.8.8.8

# Continuous ping
muti-metroo ping -c 0 192.168.1.1

# IPv6 ping
muti-metroo ping 2001:4860:4860::8888

How It Works​

ICMP echo requests flow through your mesh just like TCP and UDP - encrypted end-to-end from ingress to exit.

All ICMP payloads are encrypted end-to-end between ingress and exit using ChaCha20-Poly1305. Transit nodes cannot decrypt the traffic.

Requirements​

ICMP relay requires:

  1. Agent with ICMP enabled (enabled by default)
  2. A route from ingress to the target agent
  3. Supported platform on the target agent (see Platform Support below)

Platform Support​

ICMP uses unprivileged sockets and platform support varies:

PlatformSupportedRequirements
LinuxYesping_group_range sysctl must be configured
macOSYesWorks out of the box (no configuration needed)
WindowsNoNot supported - Windows lacks unprivileged ICMP socket support
Windows Agents

ICMP relay does not work when the target agent runs on Windows. Use Linux or macOS agents for ICMP functionality.

Configuration

See ICMP Configuration for all options including session limits and timeouts.

Linux System Requirements​

On Linux, unprivileged ICMP sockets require kernel configuration:

# Check current setting
sysctl net.ipv4.ping_group_range

# Enable for all groups (run as root)
sudo sysctl -w net.ipv4.ping_group_range="0 65535"

# Make persistent
echo "net.ipv4.ping_group_range=0 65535" | sudo tee -a /etc/sysctl.conf

Without this setting, ICMP will fail with permission errors.

No Root Required

Unlike traditional ping, Muti Metroo uses unprivileged ICMP sockets. Once the sysctl is configured, no root privileges are needed.

Usage​

Basic Ping​

# Ping a host
muti-metroo ping 8.8.8.8

# Output:
# PING 8.8.8.8 via agent abc123def456
# 64 bytes from 8.8.8.8: seq=1 time=12.3ms
# 64 bytes from 8.8.8.8: seq=2 time=11.8ms

Continuous Ping​

# Ping indefinitely (Ctrl+C to stop)
muti-metroo ping -c 0 192.168.1.1

IPv6 Ping​

# Ping IPv6 addresses
muti-metroo ping 2001:4860:4860::8888

Via Specific Agent​

# Ping through a specific agent's API
muti-metroo ping -a 192.168.1.10:8080 8.8.8.8

IPv4 and IPv6 Support​

ICMP supports both IP versions automatically:

VersionProtocolEcho RequestEcho Reply
IPv4ICMPv4 (1)Type 8Type 0
IPv6ICMPv6 (58)Type 128Type 129

The agent detects the IP version from the destination address and uses the appropriate socket type.

End-to-End Encryption​

ICMP traffic is encrypted between ingress and exit:

  1. Ingress generates ephemeral X25519 keypair
  2. Exit generates ephemeral X25519 keypair
  3. Both derive shared secret via ECDH
  4. Each echo request/reply encrypted with ChaCha20-Poly1305

Transit nodes cannot decrypt ICMP payloads.

Troubleshooting​

Permission Denied (Linux)​

Error: socket: operation not permitted

Configure the ping_group_range sysctl:

sudo sysctl -w net.ipv4.ping_group_range="0 65535"

ICMP Disabled​

Error: ICMP not enabled
  • Verify the target agent has icmp.enabled: true
  • Check that a route exists to the target agent
  • Ensure the target agent is connected to the mesh

Session Timeout​

Sessions expire after idle_timeout (default 60 seconds) of inactivity. Each ping request resets the timer.

Security Considerations​

  1. E2E encryption: All ICMP data is encrypted through the mesh
  2. Session limits: Use max_sessions to prevent resource exhaustion
  3. No DNS resolution: Only IP addresses are accepted (no domain names)