ping

README

ping.go is modified after the go-ping library.

Documentation

Overview

Package ping is a simple but powerful ICMP echo (ping) library. This file is a modification of one of the elements in the go-ping library. for the purposes of writing raw UDP packets over a VPN tunnel.

Index

• type Packet
• type PingReply
• type Pinger
  • func New(addr string, conn net.Conn) *Pinger
  • func NewFromSharedConnection(addr string, conn net.Conn) *Pinger
  • func (p *Pinger) PacketLoss() int
  • func (p *Pinger) PrintStats()
  • func (p *Pinger) Run(ctx context.Context) (err error)
  • func (p *Pinger) Statistics() *Statistics
  • func (p *Pinger) Stop()
• type Statistics

Types

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

	SrcIP *net.IP

	// 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

	// Data is the packet payload
	Data []byte
}

Packet represents a received and processed ICMP echo packet.

type PingReply

type PingReply struct {
	Seq int
	TTL int
	Rtt time.Duration
}

type Pinger

type Pinger struct {
	// Target is a string with the target host IP.
	Target string

	// 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, omit all output during measurement.
	Silent bool

	// If true, keep a record of replies of all received packets.
	// Set to false to avoid memory bloat for long running pings.
	RecordReplies 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

	// Source is the source IP address
	Source string

	TTL int
	// contains filtered or unexported fields
}

Pinger represents a packet sender/receiver.

func New

func New(addr string, conn net.Conn) *Pinger

New returns a new Pinger struct pointer. This function TAKES OWNERSHIP of the conn argument and closes it when Run terminates.

func NewFromSharedConnection

func NewFromSharedConnection(addr string, conn net.Conn) *Pinger

NewFromSharedConnection returns a new Pinger struct pointer. This function TAKES OWNERSHIP of the conn argument, BUT it DOES NOT CLOSE IT when Run terminates.

func (*Pinger) PacketLoss

func (p *Pinger) PacketLoss() int

PacketLoss calculates the ratio of packets lost (per cent).

func (*Pinger) PrintStats

func (p *Pinger) PrintStats()

PrintStats outputs statistics similar to the ones produced by the ping command.

func (*Pinger) Run

func (p *Pinger) Run(ctx context.Context) (err error)

Run runs the pinger. Accepts a single argument that is a Context. This is a blocking function that will exit when it's done (or when the context expires). If Count or Interval are not specified, it will run continuously until it is interrupted or the context expires.

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 its finished statistics.

func (*Pinger) Stop

func (p *Pinger) Stop()

Stop stops the pinger run.

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

	Replies []PingReply

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