ping

README

go-ping

ICMP Ping library for Go, inspired by go-fastping

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

pinger, err := ping.NewPinger(false)
if err != nil {
  panic(err)
}

stats, err := pinger.ping("www.google.com", 3, 1*time.Second, 10 * time.Second)
if err != nil {
  panic(err)
}

Additional Features

• Low CPU usage
• Allows pinging different destinations in parallel

Installation:

go get github.com/cdrx/go-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

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

Documentation

Overview

Package ping is an ICMP ping library seeking to emulate the unix "ping" command.

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

	pinger, err := ping.NewPinger(false)
	if err != nil {
		panic(err)
	}

 stats, err := pinger.ping("www.google.com", 3, 1*time.Second, 10 * time.Second)
	if err != nil {
		panic(err)
	}

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".

Index

• Variables
• type Pinger
  • func NewPinger(privileged bool) (*Pinger, error)
  • func (pr *Pinger) Close()
  • func (pr *Pinger) Loop(addr string, minBatch int, maxBatch int, interval time.Duration, ...)
  • func (pr *Pinger) Ping(addr string, count int, interval time.Duration, timeout time.Duration) (*Statistics, error)
  • func (pr *Pinger) SetSize(size int)
• type Statistics

Variables

var (
	// ErrPingerClosed is returned when the pinger is closed while still running
	// pings.
	ErrPingerClosed = errors.New("pinger closed")
)

Types

type Pinger

type Pinger struct {
	// contains filtered or unexported fields
}

Pinger processes pings

func NewPinger

func NewPinger(privileged bool) (*Pinger, error)

func (*Pinger) Close

func (pr *Pinger) Close()

func (*Pinger) Loop

func (pr *Pinger) Loop(addr string, minBatch int, maxBatch int, interval time.Duration, timeoutRTT time.Duration, onBatch func(stats *Statistics, err error) bool)

Loop pings the given addr continuously in batches, starting at minBatch and exponentially increasing to maxBatch. The results of each batch are sent to onBatch. If onBatch returns false, looping terminates.

interval is the wait time between each packet send.

timeoutRTT specifies the timeout for a single round-trip. The timeout for for each batch is set to batchSize * timeoutRTT.

func (*Pinger) Ping

func (pr *Pinger) Ping(addr string, count int, interval time.Duration, timeout time.Duration) (*Statistics, error)

Ping pings the given addr.

count tells pinger how many echo packets to send.

interval is the wait time between each packet send.

timeout specifies an overall timeout for the entire operation.

func (*Pinger) SetSize

func (pr *Pinger) SetSize(size int)

type Statistics

type Statistics struct {
	// PacketsRecv is the number of packets received.
	PacketsRecv int

	// PacketsSent is the number of packets sent.
	PacketsSent int

	// PacketLoss is the percentage of packets lost.
	PacketLoss float64

	// IPAddr is the address of the host being pinged.
	IPAddr *net.IPAddr

	// Addr is the string address of the host being pinged.
	Addr string

	// Rtts is all of the round-trip times sent via this pinger.
	Rtts []time.Duration

	// MinRtt is the minimum round-trip time sent via this pinger.
	MinRtt time.Duration

	// MaxRtt is the maximum round-trip time sent via this pinger.
	MaxRtt time.Duration

	// AvgRtt is the average round-trip time sent via this pinger.
	AvgRtt time.Duration

	// StdDevRtt is the standard deviation of the round-trip times sent via
	// this pinger.
	StdDevRtt time.Duration

	// BytesSent tracks the number of bytes sent in pings (including envelope)
	BytesSent int

	// BytesRecv tracks the number of bytes received in pings (including envelope)
	BytesRecv int
}

Statistics represent the stats of a currently running or finished pinger operation.