Developing lightweight computation at the DSG edge

README.md 2.86 KB
Newer Older
Cameron Sparr's avatar
Cameron Sparr committed
1
# go-ping
2
[![GoDoc](https://godoc.org/github.com/sparrc/go-ping?status.svg)](https://godoc.org/github.com/sparrc/go-ping)
Cameron Sparr's avatar
Cameron Sparr committed
3
[![Circle CI](https://circleci.com/gh/sparrc/go-ping.svg?style=svg)](https://circleci.com/gh/sparrc/go-ping)
4
5
6
7
8
9
10

ICMP Ping library for Go, inspired by
[go-fastping](https://github.com/tatsushid/go-fastping)

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

```go
Cameron Sparr's avatar
Cameron Sparr committed
11
12
13
14
15
16
17
pinger, err := ping.NewPinger("www.google.com")
if err != nil {
        panic(err)
}
pinger.Count = 3
pinger.Run() // blocks until finished
stats := pinger.Statistics() // get send/receive/rtt stats
18
19
20
21
22
```

Here is an example that emulates the unix ping command:

```go
Cameron Sparr's avatar
Cameron Sparr committed
23
24
25
26
27
pinger, err := ping.NewPinger("www.google.com")
if err != nil {
        panic(err)
}

28
29
30
31
32
33
34
35
36
// listen for ctrl-C signal
c := make(chan os.Signal, 1)
signal.Notify(c, os.Interrupt)
go func() {
	for _ = range c {
		pinger.Stop()
	}
}()

Cameron Sparr's avatar
Cameron Sparr committed
37
38
39
40
41
42
43
44
45
46
47
48
49
50
pinger.OnRecv = func(pkt *ping.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 *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())
pinger.Run()
51
52
53
54
55
56
```

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.

57
For a full ping example, see
Cameron Sparr's avatar
Cameron Sparr committed
58
[cmd/ping/ping.go](https://github.com/sparrc/go-ping/blob/master/cmd/ping/ping.go)
59
60
61
62
63
64
65
66
67
68
69
70
71

## Installation:

```
go get github.com/sparrc/go-ping
```

To install the native Go ping executable:

```bash
go get github.com/sparrc/go-ping/...
$GOPATH/bin/ping
```
72
73
74
75
76
77
78

## Note on Linux Support:

This library attempts to send an
"unprivileged" ping via UDP. On linux, this must be enabled by setting

```
Cameron Sparr's avatar
Cameron Sparr committed
79
sudo sysctl -w net.ipv4.ping_group_range="0   2147483647"
80
81
82
```

If you do not wish to do this, you can set `pinger.SetPrivileged(true)` and
Cameron Sparr's avatar
Cameron Sparr committed
83
84
85
86
use setcap to allow your binary using go-ping to bind to raw sockets
(or just run as super-user):

```
87
setcap cap_net_raw=+ep /bin/go-ping
Cameron Sparr's avatar
Cameron Sparr committed
88
```
89

90
91
92
See [this blog](https://sturmflut.github.io/linux/ubuntu/2015/01/17/unprivileged-icmp-sockets-on-linux/)
and [the Go icmp library](https://godoc.org/golang.org/x/net/icmp) for more details.

mapl's avatar
mapl committed
93
94
## Note on Windows Support:

95
96
97
98
99
100
101
You must use `pinger.SetPrivileged(true)`, otherwise you will receive an error:

```
Error listening for ICMP packets: socket: The requested protocol has not been configured into the system, or no implementation for it exists.
```

This should without admin privileges. Tested on Windows 10.
mapl's avatar
mapl committed
102