ping

README

go-ping

A simple ICMP Echo implementation, based on golang.org/x/net/icmp.

Some sample programs are provided in cmd/:

• ping-test is a really simple ping clone
• multiping provides an interactive TUI to ping multiple hosts
• ping-monitor pings multiple hosts in parallel, but just prints the summary every so often
• pingnet allows to ping every host in a CIDR range (e.g. 0.0.0.0/0 :-))

Features

• IPv4 and IPv6 support
• Unicast and multicast support
• configurable retry amount and timeout duration
• configurable payload size (and content)
• round trip time measurement

Contribute

Simply fork and create a pull-request. We'll try to respond in a timely fashion.

Software using this library

• Ping Exporter for Prometheus

Please create a pull request to get your software listed.

License

MIT License, Copyright (c) 2018 Digineo GmbH

https://www.digineo.de

Documentation

Index

• Constants
• Variables
• type Payload
  • func (p *Payload) Resize(size uint16)
• type Pinger
  • func New(bind4, bind6 string) (*Pinger, error)
  • func (pinger *Pinger) Close()
  • func (pinger *Pinger) PayloadSize() uint16
  • func (pinger *Pinger) Ping(destination *net.IPAddr, timeout time.Duration) (time.Duration, error)
  • func (pinger *Pinger) PingAttempts(destination *net.IPAddr, timeout time.Duration, attempts int) (rtt time.Duration, err error)
  • func (pinger *Pinger) PingContext(ctx context.Context, destination *net.IPAddr) (time.Duration, error)
  • func (pinger *Pinger) PingMulticast(destination *net.IPAddr, wait time.Duration) (<-chan Reply, error)
  • func (pinger *Pinger) PingMulticastContext(ctx context.Context, destination *net.IPAddr) (<-chan Reply, error)
  • func (pinger *Pinger) SetPayload(data []byte)
  • func (pinger *Pinger) SetPayloadSize(size uint16)
• type Reply

Constants

const (
	// ProtocolICMP is the number of the Internet Control Message Protocol
	// (see golang.org/x/net/internal/iana.ProtocolICMP)
	ProtocolICMP = 1

	// ProtocolICMPv6 is the IPv6 Next Header value for ICMPv6
	// see golang.org/x/net/internal/iana.ProtocolIPv6ICMP
	ProtocolICMPv6 = 58
)

Variables

var (

	// SetLogger allows updating the Logger. For details, see
	// "github.com/digineo/go-logwrap".Instance.SetLogger.
	SetLogger = log.SetLogger
)

Types

type Payload

type Payload []byte

Payload represents additional data appended to outgoing ICMP Echo Requests.

func (*Payload) Resize

func (p *Payload) Resize(size uint16)

Resize will assign a new payload of the given size to p.

type Pinger

type Pinger struct {
	LogUnexpectedPackets bool // increases log verbosity
	// contains filtered or unexported fields
}

Pinger is a instance for ICMP echo requests

func New

func New(bind4, bind6 string) (*Pinger, error)

New creates a new Pinger. This will open the raw socket and start the receiving logic. You'll need to call Close() to cleanup.

func (*Pinger) Close

func (pinger *Pinger) Close()

Close will close the ICMP socket.

func (*Pinger) PayloadSize

func (pinger *Pinger) PayloadSize() uint16

PayloadSize retrieves the current payload size.

func (*Pinger) Ping

func (pinger *Pinger) Ping(destination *net.IPAddr, timeout time.Duration) (time.Duration, error)

Ping sends a single Echo Request and waits for an answer. It returns the round trip time (RTT) if a reply is received in time.

func (*Pinger) PingAttempts

func (pinger *Pinger) PingAttempts(destination *net.IPAddr, timeout time.Duration, attempts int) (rtt time.Duration, err error)

PingAttempts sends ICMP echo requests with a timeout per request, retrying upto `attempt` times . Will finish early on success and return the round trip time of the last ping.

func (*Pinger) PingContext

func (pinger *Pinger) PingContext(ctx context.Context, destination *net.IPAddr) (time.Duration, error)

PingContext sends a single Echo Request and waits for an answer. It returns the round trip time (RTT) if a reply is received before cancellation of the context.

func (*Pinger) PingMulticast

func (pinger *Pinger) PingMulticast(destination *net.IPAddr, wait time.Duration) (<-chan Reply, error)

PingMulticast sends a single echo request and returns a channel for the responses. The channel will be closed on termination of the context. An error is returned if the sending of the echo request fails.

func (*Pinger) PingMulticastContext

func (pinger *Pinger) PingMulticastContext(ctx context.Context, destination *net.IPAddr) (<-chan Reply, error)

PingMulticastContext does the same as PingMulticast but receives a context

func (*Pinger) SetPayload

func (pinger *Pinger) SetPayload(data []byte)

SetPayload allows you to overwrite the current payload with your own data.

func (*Pinger) SetPayloadSize

func (pinger *Pinger) SetPayloadSize(size uint16)

SetPayloadSize resizes additional payload data to the given size. The payload will subsequently be appended to outgoing ICMP Echo Requests.

The default payload size is 56, resulting in 64 bytes for the ICMP packet.

type Reply

type Reply struct {
	Address  net.IP
	Duration time.Duration
}

Reply is a reply to a multicast echo request