README
¶
Traceroute in Go
A traceroute library written in Go.
Features:
- blocking and non blocking mode
- structured output, in text or JSON
- configurable options like: resolve domain names, startTTL, payloadSize, timeouts, retries
- works correctly when launching in multiple concurrent processes
- doesn't catch ICMP replies from someone's else processes
To perform network operations, syscalls and RAW_SOCKETS are used.
Therefore, in Linux, executing the command requires root privileges,
or sudo, or you can set the SET_CAP_RAW flag on the executable file using the setcap command:
setcap cap_net_raw+ep /path_to_exec_file
This library uses BPF (Berkley packet filter) connected to the socket in order to filter network packets at the kernel side. BPF isn't supported on Windows and is not tested on Mac. I have no test environment to check this cases. BPF can be disabled on Windows/Mac with the loss of the opportunity to work in a competitive mode.
Only 1024 concurrent 'traceroutes' at the same time is supported. More concurrent traceroutes is allowed, but it leads to some packets would be lost.
CLI App
go build cmd/gotraceroute
sudo ./gotraceroute example.com
Library
See traceroute_test.go for an example of how to use the library from within your application.
The gotraceroute.Run() function accepts a domain name and an options struct and immediately returns with a channel where a Hop data struct should be reading from. When traceroute is finished, the channel will be closed.
The gotraceroute.RunBlock() function accepts a domain name and an options struct, perform a traceroute and returns an array of Hop structs with traceroute result.
Resources
Useful resources:
- http://en.wikipedia.org/wiki/Traceroute
- http://tools.ietf.org/html/rfc792
- http://en.wikipedia.org/wiki/Internet_Control_Message_Protocol
Notes
- https://code.google.com/p/go/source/browse/src/pkg/net/ipraw_test.go
- http://godoc.org/code.google.com/p/go.net/ipv4
- http://golang.org/pkg/syscall/
Thanks
Based on traceroute implementation https://github.com/aeden/traceroute which was fully reworked and as a result several annoying bugs was fixed, error handling was added, and it was adopted to concurrent execution.
Some ideas about packet construction and decoding also was get from https://github.com/Syncbak-Git/traceroute
How to apply BPF to a raw socket in golang, thanks to: https://riyazali.net/posts/berkeley-packet-filter-in-golang/
Documentation
¶
Index ¶
Constants ¶
const DefaultMaxHops = 32
const DefaultPort = 33434
const DefaultRetries = 2
const DefaultStartTTL = 1
const DefaultTimeoutMs = 200
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run uses the given dest (hostname) and options to execute a traceroute to the remote host. Run is unblocked and returns a communication channel where the caller should read the Hop data On finish or error the communication channel will be closed Outbound packets are UDP packets and inbound packets are ICMP.
Types ¶
type Addr ¶
type Addr struct {
// Host is the host (ie, DNS) name of the node.
Host string
// IP is the IP address of the node.
IP net.IP
}
Addr is a network address stored as a pair of domain name and ip address
func (*Addr) HostOrAddr ¶
type BPF ¶
type BPF []bpf.Instruction
type Hop ¶
type Hop struct {
// Success is a boolean value was the response received or not
Success bool
// Src is the source (ie, local) address.
Src Addr
// Dst is the destination (ie, remote) address.
Dst Addr
// Node is the node at this step of the route.
Node Addr
// Step is the location of this node in the route, ie the TTL value used.
Step int
// ID is a unique ID that is used to match the original request with the ICMP response.
// It can be derived from either the request or the response.
ID int
// DstPort is the destination port targeted.
DstPort int
// Sent is the time the query began.
Sent time.Time
// Received is the time the query completed.
Received time.Time
// Elapsed is the duration of the query.
Elapsed time.Duration
// IcmpType is the received ICMP packet type value.
IcmpType int
}
Hop is a step in the network route between a source and destination address.
func RunBlock ¶
RunBlock uses the given dest (hostname) and options to execute a traceroute to the remote host. RunBlock is blocked until traceroute finished and returns a Result which contains an array of hops. Each hop includes the elapsed time and its IP address. Outbound packets are UDP packets and inbound packets are ICMP.
Source Files
Directories