gotraceroute

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
• func Run(ctx context.Context, dest string, options Options) (c chan Hop, err error)
• type Addr
  • func (a *Addr) HostOrAddr() string
  • func (a *Addr) String() string
• type BPF
• type Hop
  • func RunBlock(dest string, options Options) (hops []Hop, err error)
  • func (h *Hop) Fields() map[string]interface{}
  • func (h *Hop) String() string
  • func (h *Hop) StringHuman() string
  • func (h *Hop) StringJSON(formatted bool) string
• type Options

Constants

const DefaultMaxHops = 32

const DefaultPort = 33434

const DefaultRetries = 2

const DefaultStartTTL = 1

const DefaultTimeoutMs = 200

Functions

func Run

func Run(ctx context.Context, dest string, options Options) (c chan Hop, err error)

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

func (a *Addr) HostOrAddr() string

func (*Addr) String

func (a *Addr) String() string

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

func RunBlock(dest string, options Options) (hops []Hop, err error)

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.

func (*Hop) Fields

func (h *Hop) Fields() map[string]interface{}

func (*Hop) String

func (h *Hop) String() string

func (*Hop) StringHuman

func (h *Hop) StringHuman() string

func (*Hop) StringJSON

func (h *Hop) StringJSON(formatted bool) string

type Options

type Options struct {
	Port             int
	MaxHops          int
	StartTTL         int
	Timeout          time.Duration
	Retries          int
	PayloadSize      int
	NetworkInterface string
	DontResolve      bool
}

Options type