gotr

README

Gotr: Traceroute Package for Go

Overview

Gotr is a Go package for performing traceroute operations, allowing you to track the path packets take across a network and identify routers and the time it takes to reach each hop. This package leverages goroutines to execute traceroute operations concurrently, leading to faster results.

Features

• Concurrent execution for efficient traceroute operations.
• Customizable configurations, allowing you to set the maximum number of hops, timeout, delay, and retries.
• Retrieve information about network hops, including address, round-trip time (RTT), and Time To Live (TTL).

Usage

To use Gotr with the default configuration, create a Gotr instance with a target address and call the Trace method. This performs each hop concurrently, providing faster traceroute results. It returns a list of hops with their round-trip times and other relevant information.

package main

import (
    "fmt"
    "github.com/denizydmr07/gotr" 
)

func main() {
    // Create an instance
    traceroute := gotr.NewGotr("example.com")
    
    // Perform traceroute
    route := traceroute.Trace()
    
    // Display the results
    for _, hop := range route.Hops {
        fmt.Printf("Hop %d: Address = %v, RTT = %.2f ms\n", hop.TTL, hop.Addr, hop.RTT)
    }
}

You can create a custom configuration for Gotr by specifying the maximum number of hops, timeout duration, delay between attempts, and the number of retries.

package main

import (
    "fmt"
    "time"
    "github.com/denizydmr07/gotr"
)

func main() {
    // Create a custom configuration
    customConfig := gotr.NewConfig(20, 2*time.Second, 100*time.Millisecond, 3)
    
    // Create an instance
    traceroute := gotr.NewGotr("example.com", customConfig)
    
    // Perform traceroute
    results := traceroute.Trace()
    
    // Display the results
    for _, hop := range route.Hops {
        fmt.Printf("Hop %d: Address = %v, RTT = %.2f ms\n", hop.TTL, hop.Addr, hop.RTT)
    }
}

Administrative Privileges

This package uses ICMP and raw sockets, which may require administrative privileges. Ensure your Go environment and system permissions allow the use of raw sockets and ICMP traffic. If you're running into permission-related issues, try running your program with administrative or superuser rights.

Documentation

Overview

Package gotr provides functionality to perform traceroute operations. Traceroute is a diagnostic tool used to track the path packets take across a network, identifying the routers and the time it takes to reach each hop.

The package allows users to create a traceroute instance with customizable configurations, such as maximum hops, timeout, delay, and retries.

To use this package, create a `Gotr` instance with a target address and, optionally, a configuration. The `Trace` method can then be used to perform the traceroute, returning a list of hops and their round-trip times.

This package requires network access and might require administrative privileges to send ICMP packets. Ensure your environment allows ICMP traffic for proper functionality.

Index

• func NewConfig(maxHops int, timeout time.Duration, delay time.Duration, retries int) *config
• type Gotr
  • func NewGotr(addr string, opts ...*config) *Gotr
  • func (g *Gotr) Trace() Route
• type Route
  • func (r Route) Len() int
• type RouteHop

Functions

func NewConfig

func NewConfig(maxHops int, timeout time.Duration, delay time.Duration, retries int) *config

NewConfig creates a new configuration for the traceroute process. Takes the following parameters: - maxHops: The maximum number of hops the traceroute will attempt. - timeout: The timeout duration for each hop in seconds. - delay: The delay between each traceroute attempt in milliseconds. - retries: The number of retries for each hop that receives no response. Returns a pointer to the `config` struct with the specified values.

Types

type Gotr

type Gotr struct {
	Addr string // Target address for the traceroute
	// contains filtered or unexported fields
}

Gotr represents the traceroute process. It contains the following fields: - Config: The configuration for the traceroute process, containing maxHops, timeout, delay, and retries. - Hops: A slice of `Hop` structs representing each hop in the traceroute. - Mutex: A mutex for synchronizing access to the `Hops` slice. - Addr: The target address for the traceroute.

The `Gotr` struct is used to perform traceroutes to a specified address with the given configuration. To create a new `Gotr` instance, use the `NewGotr` function with the desired address and optional configuration parameters.

func NewGotr

func NewGotr(addr string, opts ...*config) *Gotr

NewGotr creates a new instance of the `Gotr` struct for the traceroute process. It takes the following parameters: - addr: The target address for the traceroute (e.g., a domain name or IP address). - opts: An optional configuration (`config`) for customizing the traceroute process, such as maximum hops, timeout, delay, and retries.

If no configuration is provided in `opts`, the function uses a default configuration with: - MaxHops: 30 - Timeout: 1 second - Delay: 50 milliseconds - Retries: 3

The function returns a pointer to the `Gotr` struct with the specified configuration and target address.

func (*Gotr) Trace

func (g *Gotr) Trace() Route

Trace initiates the traceroute process to the specified target address. It utilizes the configuration set in the `Gotr` instance to determine the number of hops, timeout, delay, and retries.

This function concurrently sends ICMP Echo Requests with increasing TTL values and listens for responses, recording the elapsed time and address of each hop. It constructs and returns a `Route` struct containing information about each hop in ascending order of TTL. Each `RouteHop` struct includes the address of the responding hop, the round-trip time (RTT), and the TTL value.

If a hop fails to respond after the configured number of retries, its address will be nil, indicating that the hop was unreached even after the specified number of attempts.

The function returns an error if the traceroute process encounters any problems. The function returns an empty `Route` struct if the traceroute process fails to complete.

type Route

type Route struct {
	Hops []*RouteHop // A list of `RouteHop` instances representing individual hops in the route
}

Route represents a sequence of network hops obtained from a traceroute operation. It comprises a collection of `RouteHop` instances, each representing a distinct hop along the route.

If a hop fails to respond after the configured number of retries, its address will be nil, indicating that the hop was unreached even after the specified number of attempts.

func (Route) Len

func (r Route) Len() int

Len returns the number of hops in the route.

This method provides the length of the route, indicating the total number of hops traversed during the traceroute operation. It calculates and returns the count of `RouteHop` instances stored within the `Hops` slice of the `Route` struct.

Returns: - The number of hops in the route as an integer.

type RouteHop

type RouteHop struct {
	Addr net.Addr // The network address that responded to the ICMP request
	RTT  float64  // The round-trip time measured in milliseconds
	TTL  int      // The Time To Live value representing the hop's position within the route
}

RouteHop represents information gathered from a single hop during a network traceroute operation. It encapsulates details about the responding network address, the round-trip time (RTT) in milliseconds, and the Time To Live (TTL) value for the corresponding hop in the route.

This struct is commonly utilized to convey results obtained during the execution of traceroute procedures and is returned as part of the response by the `Trace` method within the `Gotr` struct.