mirror of
https://github.com/go-ping/ping.git
synced 2025-07-06 02:36:18 +00:00
Update LICENSE and README
This commit extensively copyedits the README and adds a nod to our contributors in the LICENSE file.
This commit is contained in:
parent
fe82a40fcd
commit
4db5733515
2
LICENSE
2
LICENSE
@ -1,6 +1,6 @@
|
|||||||
The MIT License (MIT)
|
The MIT License (MIT)
|
||||||
|
|
||||||
Copyright (c) 2016 Cameron Sparr
|
Copyright (c) 2016 Cameron Sparr and contributors.
|
||||||
|
|
||||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
of this software and associated documentation files (the "Software"), to deal
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
71
README.md
71
README.md
@ -1,11 +1,11 @@
|
|||||||
# go-ping
|
# go-ping
|
||||||
[](https://godoc.org/github.com/go-ping/ping)
|
[](https://pkg.go.dev/github.com/go-ping/ping)
|
||||||
[](https://circleci.com/gh/go-ping/ping)
|
[](https://circleci.com/gh/go-ping/ping)
|
||||||
|
|
||||||
ICMP Ping library for Go, inspired by
|
A simple but powerful ICMP echo (ping) library for Go, inspired by
|
||||||
[go-fastping](https://github.com/tatsushid/go-fastping)
|
[go-fastping](https://github.com/tatsushid/go-fastping)
|
||||||
|
|
||||||
Here is a very simple example that sends & receives 3 packets:
|
Here is a very simple example that sends and receives three packets:
|
||||||
|
|
||||||
```go
|
```go
|
||||||
pinger, err := ping.NewPinger("www.google.com")
|
pinger, err := ping.NewPinger("www.google.com")
|
||||||
@ -17,7 +17,7 @@ pinger.Run() // blocks until finished
|
|||||||
stats := pinger.Statistics() // get send/receive/rtt stats
|
stats := pinger.Statistics() // get send/receive/rtt stats
|
||||||
```
|
```
|
||||||
|
|
||||||
Here is an example that emulates the unix ping command:
|
Here is an example that emulates the traditional UNIX ping command:
|
||||||
|
|
||||||
```go
|
```go
|
||||||
pinger, err := ping.NewPinger("www.google.com")
|
pinger, err := ping.NewPinger("www.google.com")
|
||||||
@ -50,59 +50,74 @@ fmt.Printf("PING %s (%s):\n", pinger.Addr(), pinger.IPAddr())
|
|||||||
pinger.Run()
|
pinger.Run()
|
||||||
```
|
```
|
||||||
|
|
||||||
It sends ICMP packet(s) and waits for a response. If it receives a response,
|
It sends ICMP Echo Request packet(s) and waits for an Echo Reply in
|
||||||
it calls the "receive" callback. When it's finished, it calls the "finish"
|
response. If it receives a response, it calls the `OnRecv` callback.
|
||||||
callback.
|
When it's finished, it calls the `OnFinish` callback.
|
||||||
|
|
||||||
For a full ping example, see
|
For a full ping example, see
|
||||||
[cmd/ping/ping.go](https://github.com/go-ping/ping/blob/master/cmd/ping/ping.go)
|
[cmd/ping/ping.go](https://github.com/go-ping/ping/blob/master/cmd/ping/ping.go)
|
||||||
|
|
||||||
## Installation:
|
## Installation
|
||||||
|
|
||||||
```
|
```
|
||||||
go get github.com/go-ping/ping
|
go get -u github.com/go-ping/ping
|
||||||
```
|
```
|
||||||
|
|
||||||
To install the native Go ping executable:
|
To install the native Go ping executable:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
go get github.com/go-ping/ping/...
|
go get -u github.com/go-ping/ping/...
|
||||||
$GOPATH/bin/ping
|
$GOPATH/bin/ping
|
||||||
```
|
```
|
||||||
|
|
||||||
## Maintainers and Support:
|
## Supported Operating Systems
|
||||||
|
|
||||||
This repo was originally in the personal account of @sparrc, but is now maintained by the [go-ping organization](https://github.com/go-ping).
|
### Linux
|
||||||
|
This library attempts to send an "unprivileged" ping via UDP. On Linux,
|
||||||
For support and help, you usually find us in the #go-ping channel of Gophers slack. See https://invite.slack.golangbridge.org/ for an invite to the Gophers slack org.
|
this must be enabled with the following sysctl command:
|
||||||
|
|
||||||
## Note on Linux Support:
|
|
||||||
|
|
||||||
This library attempts to send an
|
|
||||||
"unprivileged" ping via UDP. On linux, this must be enabled by setting
|
|
||||||
|
|
||||||
```
|
```
|
||||||
sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"
|
sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"
|
||||||
```
|
```
|
||||||
|
|
||||||
If you do not wish to do this, you can set `pinger.SetPrivileged(true)` and
|
If you do not wish to do this, you can call `pinger.SetPrivileged(true)`
|
||||||
use setcap to allow your binary using go-ping to bind to raw sockets
|
in your code and then use setcap on your binary to allow it to bind to
|
||||||
(or just run as super-user):
|
raw sockets (or just run it as root):
|
||||||
|
|
||||||
```
|
```
|
||||||
setcap cap_net_raw=+ep /bin/go-ping
|
setcap cap_net_raw=+ep /path/to/your/compiled/binary
|
||||||
```
|
```
|
||||||
|
|
||||||
See [this blog](https://sturmflut.github.io/linux/ubuntu/2015/01/17/unprivileged-icmp-sockets-on-linux/)
|
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.
|
and the Go [x/net/icmp](https://godoc.org/golang.org/x/net/icmp) package
|
||||||
|
for more details.
|
||||||
|
|
||||||
## Note on Windows Support:
|
### Windows
|
||||||
|
|
||||||
You must use `pinger.SetPrivileged(true)`, otherwise you will receive an error:
|
You must use `pinger.SetPrivileged(true)`, otherwise you will receive
|
||||||
|
the following error:
|
||||||
|
|
||||||
```
|
```
|
||||||
Error listening for ICMP packets: socket: The requested protocol has not been configured into the system, or no implementation for it exists.
|
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.
|
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](https://github.com/sparrc), but is now maintained by the
|
||||||
|
[go-ping organization](https://github.com/go-ping).
|
||||||
|
|
||||||
|
For support and help, you usually find us in the #go-ping channel of
|
||||||
|
Gophers Slack. See https://invite.slack.golangbridge.org/ for an invite
|
||||||
|
to the Gophers Slack org.
|
||||||
|
Loading…
Reference in New Issue
Block a user