PingX

🇬🇧 English ⇌ 🇨🇳 中文

PingX is a simple and practical network diagnostic tool designed to replace system ping and ping6 commands. It supports ICMP Ping, TCP Ping (via SYN handshake), and HTTP Ping (via HEAD requests), allowing for comprehensive connectivity testing across IPv4 and IPv6.

Features

1. Multi-Protocol: ICMP, TCP, and HTTP probing.
2. Dual Stack: Full support for IPv4, IPv6, and domain resolution.
3. Concurrency: Probe multiple targets simultaneously.
4. GeoIP: Retrieve geographical location (country, region, city, coordinates) for IP addresses.
5. JSON Output: Export results to JSON for machine readability.

Installation

Install with Cargo

cargo install pingx

Linux Permissions

On Linux systems, pingx attempts to use unprivileged DGRAM sockets first, which work without root privileges if net.ipv4.ping_group_range covers the user's group.

If that fails, it falls back to RAW sockets, which require CAP_NET_RAW capability. To enable this:

sudo setcap cap_net_raw+ep $(which pingx)

Note: The permissions will be lost if you reinstall or recompile pingx. You'll need to run the command again.

Usage

Basic Usage (ICMP)

# IPv4
pingx 1.1.1.1

# IPv6
pingx 2400:3200::1

# Domain (IPv6 preferred)
pingx example.com

Protocol Modes

Auto-Detection Mode

PingX automatically selects the protocol based on the target format:

• Starts with http:// or https://: Uses HTTP protocol.
• Format <host>:<port>: Uses TCP protocol.
• Others: Defaults to ICMP protocol.

# Auto-detected as HTTP
pingx https://www.google.com

# Auto-detected as TCP (port 80)
pingx 1.1.1.1:80

Forced Mode

Use flags to force specific protocols (target must match required format):

• -4: Force IPv4 ICMP.
• -6: Force IPv6 ICMP.
• -T / --tcp: Force TCP protocol (Target must include port, e.g., ip:port).
• -H / --http: Force HTTP protocol.

# Force IPv4
pingx -4 example.com

# Force TCP
pingx -T example.com:443

Concurrent Probing

Supports probing multiple targets simultaneously. Results are displayed interleaved unless quiet mode (-q) is enabled.

pingx 1.1.1.1 www.github.com

GeoIP Lookup

Retrieve geographical information for IP addresses. The first run will guide you through downloading the IP2Location database.

# Lookup physical location
pingx -g 1.1.1.1 8.8.8.8

# Manually fetch/update database
pingx --fetch-geo

JSON Output

Export results in structured JSON format. If one target, outputs an object; if multiple targets, outputs an array.

# Print JSON to stdout
pingx 1.1.1.1 --json

# Write JSON to file
pingx 1.1.1.1 8.8.8.8 -c 5 --json result.json

# JSON for GeoIP
pingx -g 8.8.8.8 --json

Common Options

• -c <COUNT>: Stop after sending count packets.
• -i <INTERVAL>: Wait interval seconds between sending each packet (default 1.0s).
• -w <DEADLINE>: Stop running after deadline seconds.
• -W <TIMEOUT>: Time to wait for a response, in seconds (default 1.0s).
• -t <TTL>: Set the IP Time to Live (default 64).
• -s <SIZE>: Size of ICMP payload in bytes (default 56).
• -q: Quiet output. Only displays summary statistics.

---

PingX (中文)

🇨🇳 中文 ⇌ 🇬🇧 English

PingX 是一款简单实用的网络诊断工具，旨在替代系统的 ping 和 ping6 命令。它不仅支持标准的 ICMP Ping，还支持 TCP Ping（发送 SYN 握手报文）和 HTTP Ping（发送 HEAD 请求），可对 IPv4 和 IPv6 目标进行全面的连通性测试。

特性

1. 多协议支持: 支持 ICMP、TCP 和 HTTP 协议探测。
2. 双栈支持: 完美支持 IPv4、IPv6 地址及域名解析。
3. 并发探测: 支持同时对多个目标发起探测。
4. GeoIP 信息: 获取 IP 地址的物理地理位置（国家、地区、城市、经纬度）。
5. JSON 输出: 支持将探测或定位结果以 JSON 格式输出，方便集成。

安装

使用 Cargo 安装

cargo install pingx

Linux 权限设置

在 Linux 系统上，PingX 会优先尝试使用非特权 DGRAM socket。如果系统配置了 net.ipv4.ping_group_range，则无需 root 权限即可运行。

如果 DGRAM 模式不可用，程序会回退到 RAW socket 模式，此时需要 CAP_NET_RAW 权限：

sudo setcap cap_net_raw+ep $(which pingx)

注意：如果重新安装或重新编译 pingx，权限将会丢失，需要重新运行上述命令。

用法

基础用法 (ICMP)

# IPv4
pingx 1.1.1.1

# IPv6
pingx 2400:3200::1

# 域名 (优先使用 IPv6)
pingx example.com

指定协议模式

自动识别模式

PingX 会根据目标格式自动选择协议：

• http:// 或 https:// 开头：使用 HTTP 协议。
• <host>:<port> 格式：使用 TCP 协议。
• 其他：默认为 ICMP 协议。

# 自动识别为 HTTP
pingx https://www.google.com

# 自动识别为 TCP (端口 80)
pingx 1.1.1.1:80

强制模式

使用参数强制指定协议（此时参数必须符合特定格式）：

• -4: 强制使用 ICMP 协议检测 IPv4 目标。
• -6: 强制使用 ICMP 协议检测 IPv6 目标。
• -T / --tcp: 强制使用 TCP 协议 (目标必须包含端口，如 ip:port)。
• -H / --http: 强制使用 HTTP 协议。

# 检测 IPv4
pingx -4 example.com

# 强制使用 TCP 协议
pingx -T example.com:443

并发探测

pingx 可以并发对多个目标以不同协议进行检测。结果将交替显示，除非开启安静模式 (-q)。

pingx 1.1.1.1 www.github.com

GeoIP 位置查询

获取 IP 地址的物理地理位置信息。第一次运行会引导你下载 IP2Location 数据库。

# 查询物理位置
pingx -g 1.1.1.1 8.8.8.8

# 手动更新/下载数据库
pingx --fetch-geo

JSON 格式输出

将结果以结构化的 JSON 格式输出。单个目标输出对象 {...}，多个目标输出列表 [{...}, ...]。

# 打印 JSON 到屏幕
pingx 1.1.1.1 --json

# 保存 JSON 到文件
pingx 1.1.1.1 8.8.8.8 -c 5 --json result.json

# GeoIP 模式输出 JSON
pingx -g 8.8.8.8 --json

常用参数

• -c <COUNT>: 发送数据包的数量。
• -i <INTERVAL>: 发包间隔（秒），默认 1.0 秒。
• -w <DEADLINE>: 持续运行的时间限制（秒）。
• -W <TIMEOUT>: 等待响应的超时时间（秒），默认 1.0 秒。
• -t <TTL>: 设置 IP 生存时间 (TTL)，默认 64。
• -s <SIZE>: ICMP 数据包大小（默认 56 字节）。
• -q: 安静模式，不显示逐个包的详细信息，仅显示统计结果。