ping

Documentation

Overview

Package ping implements the ping builtin command.

ping — send ICMP echo requests to a network host

Usage: ping [OPTION]... HOST

Sends ICMP echo requests to HOST and reports round-trip statistics. Uses github.com/prometheus-community/pro-bing for ICMP operations.

This command always attempts unprivileged mode first (SetPrivileged(false), UDP-based ICMP) and automatically falls back to privileged raw-socket mode (SetPrivileged(true), SOCK_RAW) if the OS returns a permission error.

Platform compatibility

Linux:

Unprivileged ICMP (SOCK_DGRAM) requires the process GID to fall within the
kernel sysctl net.ipv4.ping_group_range (default 1–0, i.e. disabled on
many distributions). When that range excludes the GID, the kernel returns
EPROTONOSUPPORT and the command retries with a raw socket (SOCK_RAW), which
requires root or CAP_NET_RAW. CAP_NET_RAW is the preferred deployment
approach in containers; alternatively, widen ping_group_range to allow
unprivileged operation without any capability.

macOS:

Unprivileged ICMP (SOCK_DGRAM) is permitted by default for all users on
macOS 10.15+. The privileged fallback (SOCK_RAW) requires root. In normal
operation the fallback is never needed on macOS.

Windows:

Both SOCK_DGRAM and SOCK_RAW ICMP sockets on Windows require the process to
run as Administrator. Standard user processes receive WSAEACCES ("access is
denied") or WSAEPROTONOSUPPORT (10043) when creating the socket. The command
attempts the unprivileged path first and retries with privileged mode, but
both attempts will fail for non-elevated processes. Run the shell as
Administrator (or grant SeNetworkLogonRight) to enable ping on Windows.

Accepted flags:

-c, --count N
    Number of ICMP echo requests to send (default 4, clamped to 1–20).

-W, --wait DURATION
    Time to wait for each reply (default 1s, clamped to 100ms–30s).

-i, --interval DURATION
    Interval between sending packets (default 1s, clamped to 200ms–60s).

-q, --quiet
    Quiet output: suppress per-packet lines; print only statistics.

-4
    Use IPv4 only.

-6
    Use IPv6 only.

-h, --help
    Print usage to stdout and exit 0.

Dangerous flags NOT implemented (rejected by pflag as unknown):

-f           Flood ping — sends packets as fast as possible (DoS vector).
-b           Allow pinging broadcast addresses (network DoS vector).
-s SIZE      Set packet payload size (not needed; default size is used).
-I IFACE     Bind to specific network interface.
-p PATTERN   Fill packet with pattern.
-R           Record route.

Exit codes:

0  At least one ICMP echo reply was received.
1  No replies received, or the host was unreachable, or bad arguments.

Output format:

PING host (ip): N data bytes
N bytes from ip: icmp_seq=S ttl=T time=R ms
...
--- host ping statistics ---
S packets transmitted, R received, X% packet loss
round-trip min/avg/max/stddev = min/avg/max/stddev ms

Index

• Variables

Variables

var Cmd = builtins.Command{
	Name:        "ping",
	Description: "send ICMP echo requests to a network host",
	MakeFlags:   registerFlags,
}

Cmd is the ping builtin command descriptor.