README
¶
pro-bing
A simple but powerful ICMP echo (ping) library for Go, inspired by go-ping & go-fastping.
Here is a very simple example that sends and receives three packets:
pinger, err := probing.NewPinger("www.google.com")
if err != nil {
panic(err)
}
pinger.Count = 3
err = pinger.Run() // Blocks until finished.
if err != nil {
panic(err)
}
stats := pinger.Statistics() // get send/receive/duplicate/rtt stats
Here is an example that emulates the traditional UNIX ping command:
pinger, err := probing.NewPinger("www.google.com")
if err != nil {
panic(err)
}
// Listen for Ctrl-C.
c := make(chan os.Signal, 1)
signal.Notify(c, os.Interrupt)
go func() {
for _ = range c {
pinger.Stop()
}
}()
pinger.OnRecv = func(pkt *probing.Packet) {
fmt.Printf("%d bytes from %s: icmp_seq=%d time=%v\n",
pkt.Nbytes, pkt.IPAddr, pkt.Seq, pkt.Rtt)
}
pinger.OnDuplicateRecv = func(pkt *probing.Packet) {
fmt.Printf("%d bytes from %s: icmp_seq=%d time=%v ttl=%v (DUP!)\n",
pkt.Nbytes, pkt.IPAddr, pkt.Seq, pkt.Rtt, pkt.Ttl)
}
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())
err = pinger.Run()
if err != nil {
panic(err)
}
It sends ICMP Echo Request packet(s) and waits for an Echo Reply in
response. If it receives a response, it calls the OnRecv callback
unless a packet with that sequence number has already been received,
in which case it calls the OnDuplicateRecv callback. When it's
finished, it calls the OnFinish callback.
For a full ping example, see cmd/ping/ping.go.
Installation
go get -u github.com/prometheus-community/pro-bing
To install the native Go ping executable:
go get -u github.com/prometheus-community/pro-bing/...
$GOPATH/bin/ping
Supported Operating Systems
Linux
This library attempts to send an "unprivileged" ping via UDP. On Linux, this must be enabled with the following sysctl command:
sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"
If you do not wish to do this, you can call pinger.SetPrivileged(true)
in your code and then use setcap on your binary to allow it to bind to
raw sockets (or just run it as root):
setcap cap_net_raw=+ep /path/to/your/compiled/binary
See this blog and the Go x/net/icmp package for more details.
Windows
You must use pinger.SetPrivileged(true), otherwise you will receive
the following error:
socket: The requested protocol has not been configured into the system, or no implementation for it exists.
Despite the method name, this should work without the need to elevate privileges and has been tested on Windows 10. Please note that accessing packet TTL values is not supported due to limitations in the Go x/net/ipv4 and x/net/ipv6 packages.
Plan 9 from Bell Labs
There is no support for Plan 9. This is because the entire x/net/ipv4
and x/net/ipv6 packages are not implemented by the Go programming
language.
Maintainers and Getting Help:
This repo was originally in the personal account of sparrc, but is now maintained by the Prometheus Community.
Contributing
Refer to CONTRIBUTING.md
Documentation
¶
Overview ¶
Package probing is a simple but powerful ICMP echo (ping) library.
Here is a very simple example that sends and receives three packets:
pinger, err := probing.NewPinger("www.google.com")
if err != nil {
panic(err)
}
pinger.Count = 3
err = pinger.Run() // blocks until finished
if err != nil {
panic(err)
}
stats := pinger.Statistics() // get send/receive/rtt stats
Here is an example that emulates the traditional UNIX ping command:
pinger, err := probing.NewPinger("www.google.com")
if err != nil {
panic(err)
}
// Listen for Ctrl-C.
c := make(chan os.Signal, 1)
signal.Notify(c, os.Interrupt)
go func() {
for _ = range c {
pinger.Stop()
}
}()
pinger.OnRecv = func(pkt *probing.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 *probing.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())
err = pinger.Run()
if err != nil {
panic(err)
}
It sends ICMP Echo Request packet(s) and waits for an Echo Reply in response. If it receives a response, it calls the OnRecv callback. When it's finished, it calls the OnFinish callback.
For a full ping example, see "cmd/ping/ping.go".
Index ¶
- type Logger
- type NoopLogger
- type Packet
- type Pinger
- func (p *Pinger) Addr() string
- func (p *Pinger) ID() int
- func (p *Pinger) IPAddr() *net.IPAddr
- func (p *Pinger) Privileged() bool
- func (p *Pinger) Resolve() error
- func (p *Pinger) Run() error
- func (p *Pinger) SetAddr(addr string) error
- func (p *Pinger) SetID(id int)
- func (p *Pinger) SetIPAddr(ipaddr *net.IPAddr)
- func (p *Pinger) SetLogger(logger Logger)
- func (p *Pinger) SetNetwork(n string)
- func (p *Pinger) SetPrivileged(privileged bool)
- func (p *Pinger) Statistics() *Statistics
- func (p *Pinger) Stop()
- type Statistics
- type StdLogger
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type NoopLogger ¶
type NoopLogger struct {
}
func (NoopLogger) Debugf ¶
func (l NoopLogger) Debugf(format string, v ...interface{})
func (NoopLogger) Errorf ¶
func (l NoopLogger) Errorf(format string, v ...interface{})
func (NoopLogger) Fatalf ¶
func (l NoopLogger) Fatalf(format string, v ...interface{})
func (NoopLogger) Infof ¶
func (l NoopLogger) Infof(format string, v ...interface{})
func (NoopLogger) Warnf ¶
func (l NoopLogger) Warnf(format string, v ...interface{})
type Packet ¶
type Packet struct {
// Rtt is the round-trip time it took to ping.
Rtt time.Duration
// IPAddr is the address of the host being pinged.
IPAddr *net.IPAddr
// Addr is the string address of the host being pinged.
Addr string
// NBytes is the number of bytes in the message.
Nbytes int
// Seq is the ICMP sequence number.
Seq int
// TTL is the Time To Live on the packet.
TTL int
// ID is the ICMP identifier.
ID int
}
Packet represents a received and processed ICMP echo packet.
type Pinger ¶
type Pinger struct {
// Interval is the wait time between each packet send. Default is 1s.
Interval time.Duration
// Timeout specifies a timeout before ping exits, regardless of how many
// packets have been received.
Timeout time.Duration
// Count tells pinger to stop after sending (and receiving) Count echo
// packets. If this option is not specified, pinger will operate until
// interrupted.
Count int
// Debug runs in debug mode
Debug bool
// Number of packets sent
PacketsSent int
// Number of packets received
PacketsRecv int
// Number of duplicate packets received
PacketsRecvDuplicates int
// If true, keep a record of rtts of all received packets.
// Set to false to avoid memory bloat for long running pings.
RecordRtts bool
// OnSetup is called when Pinger has finished setting up the listening socket
OnSetup func()
// OnSend is called when Pinger sends a packet
OnSend func(*Packet)
// OnRecv is called when Pinger receives and processes a packet
OnRecv func(*Packet)
// OnFinish is called when Pinger exits
OnFinish func(*Statistics)
// OnDuplicateRecv is called when a packet is received that has already been received.
OnDuplicateRecv func(*Packet)
// Size of packet being sent
Size int
// Tracker: Used to uniquely identify packets - Deprecated
Tracker uint64
// Source is the source IP address
Source string
TTL int
// contains filtered or unexported fields
}
Pinger represents a packet sender/receiver.
func (*Pinger) Privileged ¶
Privileged returns whether pinger is running in privileged mode.
func (*Pinger) Run ¶
Run runs the pinger. This is a blocking function that will exit when it's done. If Count or Interval are not specified, it will run continuously until it is interrupted.
func (*Pinger) SetAddr ¶
SetAddr resolves and sets the ip address of the target host, addr can be a DNS name like "www.google.com" or IP like "127.0.0.1".
func (*Pinger) SetNetwork ¶
SetNetwork allows configuration of DNS resolution. * "ip" will automatically select IPv4 or IPv6. * "ip4" will select IPv4. * "ip6" will select IPv6.
func (*Pinger) SetPrivileged ¶
SetPrivileged sets the type of ping pinger will send. false means pinger will send an "unprivileged" UDP ping. true means pinger will send a "privileged" raw ICMP ping. NOTE: setting to true requires that it be run with super-user privileges.
func (*Pinger) Statistics ¶
func (p *Pinger) Statistics() *Statistics
Statistics returns the statistics of the pinger. This can be run while the pinger is running or after it is finished. OnFinish calls this function to get it's finished statistics.
type Statistics ¶
type Statistics struct {
// PacketsRecv is the number of packets received.
PacketsRecv int
// PacketsSent is the number of packets sent.
PacketsSent int
// PacketsRecvDuplicates is the number of duplicate responses there were to a sent packet.
PacketsRecvDuplicates 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
}
Statistics represent the stats of a currently running or finished pinger operation.
Source Files
Directories