ICMP Ping library for Go
Go to file
Xie Zhenye 667d0a66f2 remove signal handler, add Stop method (#10)
* remove signal handler, add Stop method

* Added ICMP Packet ID to distinguish ICMP replies
2018-11-06 10:48:48 +00:00
cmd/ping Update doc on privileged ping and install 2016-02-01 15:28:30 -07:00
.gitignore uncommit ping binary 2016-02-01 15:52:45 -07:00
circle.yml Add integration tests in circle 2016-02-08 09:29:08 -07:00
LICENSE Initial commit 2016-02-01 15:06:45 -07:00
ping_test.go Add integration tests in circle 2016-02-08 09:29:08 -07:00
ping.go remove signal handler, add Stop method (#10) 2018-11-06 10:48:48 +00:00
README.md Update README.md (#21) 2018-08-29 18:10:52 +01:00

go-ping

GoDoc Circle CI

ICMP Ping library for Go, inspired by go-fastping

Here is a very simple example that sends & receives 3 packets:

pinger, err := ping.NewPinger("www.google.com")
if err != nil {
        panic(err)
}
pinger.Count = 3
pinger.Run() // blocks until finished
stats := pinger.Statistics() // get send/receive/rtt stats

Here is an example that emulates the unix ping command:

pinger, err := ping.NewPinger("www.google.com")
if err != nil {
        panic(err)
}

pinger.OnRecv = func(pkt *ping.Packet) {
        fmt.Printf("%d bytes from %s: icmp_seq=%d time=%v\n",
                pkt.Nbytes, pkt.IPAddr, pkt.Seq, pkt.Rtt)
}
pinger.OnFinish = func(stats *ping.Statistics) {
        fmt.Printf("\n--- %s ping statistics ---\n", stats.Addr)
        fmt.Printf("%d packets transmitted, %d packets received, %v%% packet loss\n",
                stats.PacketsSent, stats.PacketsRecv, stats.PacketLoss)
        fmt.Printf("round-trip min/avg/max/stddev = %v/%v/%v/%v\n",
                stats.MinRtt, stats.AvgRtt, stats.MaxRtt, stats.StdDevRtt)
}

fmt.Printf("PING %s (%s):\n", pinger.Addr(), pinger.IPAddr())
pinger.Run()

It sends ICMP packet(s) and waits for a response. If it receives a response, it calls the "receive" callback. When it's finished, it calls the "finish" callback.

For a full ping example, see cmd/ping/ping.go

Installation:

go get github.com/sparrc/go-ping

To install the native Go ping executable:

go get github.com/sparrc/go-ping/...
$GOPATH/bin/ping

Note on Linux Support:

This library attempts to send an "unprivileged" ping via UDP. On linux, this must be enabled by setting

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

If you do not wish to do this, you can set pinger.SetPrivileged(true) and use setcap to allow your binary using go-ping to bind to raw sockets (or just run as super-user):

setcap cap_net_raw=+ep /bin/goping-binary

Note on Windows Support:

You have to use "SetPrivileged(true)" like "pinger.SetPrivileged(true)", otherwise you will receive an error: "Error listening for ICMP packets: socket: The requested protocol has not been configured into the system, or no implementation for it exists." This even works without admin privileges. Tested on Windows 10

See this blog and the Go icmp library for more details.