README
¶
ping
Simple (ICMP) library patterned after net/http.
Originally inspired by sparrc/go-ping
Installation
go get -du github.com/glinton/ping
To install an all-go iputils patterned ping binary
go get github.com/glinton/ping/cmd/ping
# to run:
$GOPATH/bin/ping localhost
Example
package main
import (
"context"
"fmt"
"github.com/glinton/ping"
)
func main() {
res, err := ping.IPv4(context.Background(), "google.com")
if err != nil {
panic(err)
}
fmt.Printf("Completed one ping to google.com with %d bytes in %v\n",
res.TotalLength, res.RTT)
}
Notes Regarding ICMP Socket Permissions
System installed ping binaries generally have setuid attributes set, thus allowing them to utilize privileged ICMP sockets. This should work for applications built with this library as well, but a better approach would be to give the application the capability to create privileged ICMP sockets. To do so, run the following as the root user (not applicable to Windows).
setcap cap_net_raw=eip /path/to/your/application
This library tries to initialize a privileged ICMP socket before falling back to unprivileged raw sockets on Linux and Darwin (udp4 or udp6 as the network). On Linux, the system group of the user running the application must be allowed to create unprivileged ICMP sockets if desired. See man pages icmp(7) for ping_group_range.
To allow a range of groups access to create unprivileged icmp sockets on linux (ipv4 or ipv6), run:
sudo sysctl -w net.ipv4.ping_group_range="GROUPID_START GROUPID_END"
If you plan to run your application as root, the aforementioned commmand is not necessary.
On Windows, running a terminal as admin should not be necessary.
Known Issues
There is currently no support for TTL on windows, track progress at https://github.com/golang/go/issues/7175 and https://github.com/golang/go/issues/7174
Report any other issues you may find here
Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultClient = &Client{}
DefaultClient is the default client used by Do.
Functions ¶
This section is empty.
Types ¶
type Request ¶
type Request struct {
ID int // ID is the ICMP ID. It is an identifier to aid in matching echos and replies when using privileged datagrams, may be zero.
Seq int // Seq is the ICMP sequence number.
Data []byte // Data is generally an arbitrary byte string of size 56. It is used to set icmp.Echo.Data.
Dst net.IP // The address of the host to which the message should be sent.
Src net.IP // The address of the host that composes the ICMP message.
// contains filtered or unexported fields
}
A Request represents an icmp echo request to be sent by a client.
func NewRequest ¶
NewRequest resolves dst as an IPv4 address and returns a pointer to a request using that as the destination.
Example (WithSource) ¶
package main
import (
"context"
"fmt"
"net"
"github.com/glinton/ping"
)
func main() {
req, err := ping.NewRequest("localhost")
if err != nil {
panic(err)
}
// If you have multiple interfaces spanning different networks
// and want to ping from a specific interface, set the source.
req.Src = net.ParseIP("127.0.0.2")
res, err := ping.Do(context.Background(), req)
if err != nil {
panic(err)
}
// RTT is the time from an ICMP echo request to the time a reply is received.
fmt.Println(res.RTT)
}
Output:
func NewRequest6 ¶
NewRequest6 resolves dst as an IPv6 address and returns a pointer to a request using that as the destination.
type Response ¶
type Response struct {
TotalLength int // Length of internet header and data of the echo response in octets.
RTT time.Duration // RTT is the round-trip time it took to ping.
TTL int // Time to live in seconds; as this field is decremented at each machine in which the datagram is processed, the value in this field should be at least as great as the number of gateways which this datagram will traverse. Maximum possible value of this field is 255.
ID int // ID is the ICMP ID. It is an identifier to aid in matching echos and replies when using privileged datagrams, may be zero.
Seq uint // Seq is the ICMP sequence number.
Data []byte // Data is the body of the ICMP response.
Dst net.IP // The local address of the host that composed the echo request.
Src net.IP // The address of the host to which the message was received from.
Req *Request // Req is the request that elicited this response.
// contains filtered or unexported fields
}
Response represents an icmp echo response received by a client.
func Do ¶
Do sends a ping request using the default client and returns a ping response.
Example ¶
package main
import (
"context"
"fmt"
"github.com/glinton/ping"
)
func main() {
req, err := ping.NewRequest("localhost")
if err != nil {
panic(err)
}
res, err := ping.Do(context.Background(), req)
if err != nil {
panic(err)
}
// RTT is the time from an ICMP echo request to the time a reply is received.
fmt.Println(res.RTT)
}
Output:
func IPv4 ¶
IPv4 resolves dst as an IPv4 address and pings using DefaultClient, returning the response and error.
Example ¶
package main
import (
"context"
"fmt"
"github.com/glinton/ping"
)
func main() {
res, err := ping.IPv4(context.Background(), "google.com")
if err != nil {
panic(err)
}
// RTT is the time from an ICMP echo request to the time a reply is received.
fmt.Println(res.RTT)
}
Output:
Source Files
Directories