subping

package module
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 29, 2023 License: MIT Imports: 8 Imported by: 0

README

subping

subping is a powerful and user-friendly command-line tool that allows you to perform ICMP ping operations on all IP addresses within a specified subnet range. With subping, you can effortlessly discover and monitor the availability of devices within a network by systematically pinging each IP address within the defined subnet.

Dependencies

Subping depends on the following third-party libraries:

Documentation

The documentation for the Subping library can be found at https://pkg.go.dev/github.com/fadhilyori/subping. It includes detailed information on how to use the library, and examples.

The library consists of the following packages:

Please refer to the documentation for the respective packages to understand how to use them in your applications.

Usage

To use subping, follow these steps:

  1. Install subping by downloading the latest release from the releases page.

  2. Open a terminal or command prompt and navigate to the directory where subping is installed.

  3. Run the subping command with the specified subnet range:

    subping [flags] [network subnet]

The following flags are available for the subping command:

  • -c, --count int: Specifies the number of ping attempts for each IP address. (default 1)
  • -h, --help: Displays help information for the subping command.
  • -i, --interval string: Specifies the time duration between each ping request. (default "300ms")
  • -n, --job int: Specifies the number of maximum concurrent jobs spawned to perform ping operations. (default 128)
  • --offline: Specify whether to display the list of offline hosts.
  • -t, --timeout string: Specifies the maximum ping timeout duration for each ping request. (default "80ms")
  • -v, --version: Displays the version information for subping.

Import as Go Package

To use the Subping library, follow these steps:

  1. Import the Subping package:

    import (
    "github.com/fadhilyori/subping"
)

  2. Create an instance of Subping by calling NewSubping with the desired options:

    opts := &subping.Options{
    LogLevel: "debug",
    Subnet: "172.17.0.0/24",
    Count:   3,
    Interval: 1 * time.Second,
    Timeout: 3 * time.Second,
    MaxWorkers: 8,
}

sp, err := subping.NewSubping(opts)
if err != nil {
    log.Fatal(err)
}

Note: Ensure that you have imported the necessary packages, such as "time" and "log".

  1. Run the Subping process by calling the Run method:

    sp.Run()

This will initiate the ICMP ping operations on the specified IP addresses.

  1. Retrieve the results:

    results := sp.Results

    The results variable will contain a map where the keys are the IP addresses, and the values are *subping.Result representing the ping statistics for each IP address.

  2. Optionally, you can use the GetOnlineHosts method to filter the results and obtain only the IP addresses that responded to the ping:

    onlineHosts := sp.GetOnlineHosts()

    The onlineHosts variable will contain a map of the online IP addresses and their corresponding ping statistics.

  3. You can also call the RunPing function directly to perform a ping operation on a single IP address:

    ipAddress := net.ParseIP("192.168.1.1")
count := 3
timeout := 300 * time.Millisecond

stats := subping.RunPing(ipAddress, count, timeout)

    The stats variable will contain the ping statistics for the specified IP address.

Examples

Here are a few examples of how to use subping:

Ping all IP addresses in the subnet range 172.17.0.0/24:

subping -t 300ms -c 3 -n 100 172.17.0.0/24

Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request. For more details, see our contribution guidelines.

License

This project is licensed under the MIT License.

Documentation

Overview

Package subping provides a utility for concurrently pinging multiple IP addresses and collecting the results.

The package includes functionality for running ping operations on multiple IP addresses concurrently, calculating ping statistics, and partitioning data for parallel processing.

Example usage: 

// Create options for Subping
opts := &subping.Options{
    LogLevel:   "info",
    Subnet:     "192.168.0.0/24",
    Count:      5,
    Interval:   time.Second,
    Timeout:    2 * time.Second,
    MaxWorkers: 10,
}

// Create a new Subping instance
sp, err := subping.NewSubping(opts)
if err != nil {
    log.Fatalf("Failed to create Subping instance: %v", err)
}

// Run the Subping process
sp.Run()

// Get the online hosts and their statistics
onlineHosts, total := sp.GetOnlineHosts()
fmt.Printf("Online Hosts: %v\n", onlineHosts)
fmt.Printf("Total Online Hosts: %d\n", total)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RunPing 

func RunPing(ipAddress string, count int, interval time.Duration, timeout time.Duration) ping.Statistics

RunPing performs a ping operation to the specified IP address. It sends the specified number of ping requests with the given interval and timeout.

Types

type Options 

type Options struct {
	// LogLevel sets the log levels for the Subping instance.
	LogLevel string

	// Subnet is the subnet to scan for IP addresses to ping.
	Subnet string

	// Count is the number of ping requests to send for each target.
	Count int

	// Interval is the time duration between each ping request.
	Interval time.Duration

	// Timeout specifies the timeout duration before exiting each target.
	Timeout time.Duration

	// MaxWorkers specifies the maximum number of concurrent workers to use.
	MaxWorkers int
}

Options holds the configuration options for creating a new Subping instance.

type Result added in v1.0.0 

type Result struct {
	// AvgRtt is the average round-trip time of the ping requests.
	AvgRtt time.Duration

	// PacketLoss is the percentage of packets lost during the ping operation.
	PacketLoss float64

	// PacketsSent is the number of packets sent for the ping operation.
	PacketsSent int

	// PacketsRecv is the number of packets received for the ping operation.
	PacketsRecv int

	// PacketsRecvDuplicates is the number of duplicate packets received.
	PacketsRecvDuplicates int
}

Result contains the statistics and metrics for a single ping operation.

type Subping 

type Subping struct {
	// TargetsIterator is an iterator for the target IP addresses to ping.
	TargetsIterator *network.SubnetHostsIterator

	// Count is the number of ping requests to send for each target.
	Count int

	// Interval is the time duration between each ping request.
	Interval time.Duration

	// Timeout specifies the timeout duration before exiting each target.
	Timeout time.Duration

	// BatchSize is the number of concurrent ping jobs to execute.
	BatchSize int64

	// Results stores the ping results for each target IP address.
	Results map[string]Result

	// TotalResults represents the total number of ping results collected.
	TotalResults int

	// MaxWorkers specifies the maximum number of concurrent workers to use.
	MaxWorkers int
	// contains filtered or unexported fields
}

Subping is a utility for concurrently pinging multiple IP addresses and collecting the results.

func NewSubping 

func NewSubping(opts *Options) (*Subping, error)

NewSubping creates a new Subping instance with the provided options.

func (*Subping) GetOnlineHosts 

func (s *Subping) GetOnlineHosts() (map[string]Result, int)

GetOnlineHosts returns a map of online hosts and their corresponding ping results, as well as the total number of online hosts.

func (*Subping) Run 

func (s *Subping) Run()

Run starts the Subping process, concurrently pinging the target IP addresses. It spawns worker goroutines, assigns tasks to them, waits for them to finish, and collects the results.

Source Files

View all Source files

Directories

Path Synopsis
cmd
subping command
pkg
network
Package network provides functionality for working with IP networks and subnet hosts.
 Package network provides functionality for working with IP networks and subnet hosts.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.