iperf

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 15, 2024 License: BSD-2-Clause Imports: 22 Imported by: 1

README

go-iperf

A Go based wrapper around iperf3

This fork removes the embedded iperf3 binary. Whilst the idea is nice, its easier and more convenient when using multiple platforms and architectures etc, to use an external binary.

Basic Usage

basic client setup

func main() {
	
	c := iperf.NewClient("192.168.0.10")
	c.SetJSON(true)
	c.SetIncludeServer(true)
	c.SetStreams(4)
	c.SetTimeSec(30)
	c.SetInterval(1)
	
	err := c.Start()
	if err != nil {
        fmt.Printf("failed to start client: %v\n", err)
        os.Exit(-1)
	}
	
	<- c.Done
	
	fmt.Println(c.Report().String())
}

basic server setup

func main() {
	
	s := iperf.NewServer()
	err := s.Start()
	if err != nil {
        fmt.Printf("failed to start server: %v\n", err)
        os.Exit(-1)
    }
    
    for s.Running {
    	time.Sleep(100 * time.Millisecond)
    }
    
    fmt.Println("server finished")
}

client with live results printing

func main() {
	
	c := iperf.NewClient("192.168.0.10")
	c.SetJSON(true)
	c.SetIncludeServer(true)
	c.SetStreams(4)
	c.SetTimeSec(30)
	c.SetInterval(1)
	liveReports := c.SetModeLive()
	
	go func() {
	    for report := range liveReports {
	        fmt.Println(report.String())	
            }   	
        }   
	
	err := c.Start()
	if err != nil {
            fmt.Printf("failed to start client: %v\n", err)
            os.Exit(-1)
	}
	
	<- c.Done
	
	fmt.Println(c.Report().String())
}

Documentation

Index

Constants

View Source 
const (
	PROTO_TCP = "tcp"
	PROTO_UDP = "udp"
)

Variables

View Source 
var (
	Debug = false
)

Functions

func ExecuteAsync 

func ExecuteAsync(cmd string) (outPipe io.ReadCloser, errPipe io.ReadCloser, exitCode chan int, err error)

func ExecuteAsyncWithCancel 

func ExecuteAsyncWithCancel(cmd string) (stdOut io.ReadCloser, stdErr io.ReadCloser, exitCode chan int, cancelToken context.CancelFunc, pid int, err error)

func ExecuteAsyncWithCancelReadIndicator 

func ExecuteAsyncWithCancelReadIndicator(cmd string, readIndicator chan interface{}) (stdOut io.ReadCloser, stdErr io.ReadCloser, exitCode chan int, cancelToken context.CancelFunc, pid int, err error)

func GetConnectedClient 

func GetConnectedClient(addr string, port int) (client api.CommandClient, err error)

func GetUnusedTcpPort 

func GetUnusedTcpPort() (int, error)

Types

type Client 

type Client struct {
	Id      string         `json:"id" yaml:"id" xml:"id"`
	Running bool           `json:"running" yaml:"running" xml:"running"`
	Done    chan bool      `json:"-" yaml:"-" xml:"-"`
	Options *ClientOptions `json:"options" yaml:"options" xml:"options"`
	Debug   bool           `json:"-" yaml:"-" xml:"-"`
	StdOut  bool           `json:"-" yaml:"-" xml:"-"`
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(host string) *Client

func (*Client) Bandwidth 

func (c *Client) Bandwidth() string

func (*Client) BlockCount 

func (c *Client) BlockCount() string

func (*Client) Bytes 

func (c *Client) Bytes() string

func (*Client) ExitCode 

func (c *Client) ExitCode() *int

func (*Client) Format 

func (c *Client) Format() rune

func (*Client) Host 

func (c *Client) Host() string

func (*Client) IncludeServer 

func (c *Client) IncludeServer() bool

func (*Client) Interval 

func (c *Client) Interval() int

func (*Client) JSON 

func (c *Client) JSON() bool

func (*Client) Length 

func (c *Client) Length() string

func (*Client) LoadOptions 

func (c *Client) LoadOptions(options *ClientOptions)

func (*Client) LoadOptionsJSON 

func (c *Client) LoadOptionsJSON(jsonStr string) (err error)

func (*Client) LogFile 

func (c *Client) LogFile() string

func (*Client) MSS 

func (c *Client) MSS() int

func (*Client) Mode 

func (c *Client) Mode() TestMode

func (*Client) NoDelay 

func (c *Client) NoDelay() bool

func (*Client) OmitSec 

func (c *Client) OmitSec() int

func (*Client) Port 

func (c *Client) Port() int

func (*Client) Prefix 

func (c *Client) Prefix() string

func (*Client) Proto 

func (c *Client) Proto() Protocol

func (*Client) Report 

func (c *Client) Report() *TestReport

func (*Client) Reverse 

func (c *Client) Reverse() bool

func (*Client) SetBandwidth 

func (c *Client) SetBandwidth(bandwidth string)

func (*Client) SetBlockCount 

func (c *Client) SetBlockCount(blockCount string)

func (*Client) SetBytes 

func (c *Client) SetBytes(bytes string)

func (*Client) SetFormat 

func (c *Client) SetFormat(format rune)

func (*Client) SetHost 

func (c *Client) SetHost(host string)

func (*Client) SetIncludeServer 

func (c *Client) SetIncludeServer(set bool)

func (*Client) SetInterval 

func (c *Client) SetInterval(interval int)

func (*Client) SetJSON 

func (c *Client) SetJSON(set bool)

func (*Client) SetLength 

func (c *Client) SetLength(length string)

func (*Client) SetLogFile 

func (c *Client) SetLogFile(logfile string)

func (*Client) SetMSS 

func (c *Client) SetMSS(mss int)

func (*Client) SetModeJson 

func (c *Client) SetModeJson()

func (*Client) SetModeLive 

func (c *Client) SetModeLive() <-chan *StreamIntervalReport

func (*Client) SetNoDelay 

func (c *Client) SetNoDelay(noDelay bool)

func (*Client) SetOmitSec 

func (c *Client) SetOmitSec(value int)

func (*Client) SetPort 

func (c *Client) SetPort(port int)

func (*Client) SetPrefix 

func (c *Client) SetPrefix(prefix string)

func (*Client) SetProto 

func (c *Client) SetProto(proto Protocol)

func (*Client) SetReverse 

func (c *Client) SetReverse(reverse bool)

func (*Client) SetStreams 

func (c *Client) SetStreams(streamCount int)

func (*Client) SetTOS 

func (c *Client) SetTOS(value int)

func (*Client) SetTimeSec 

func (c *Client) SetTimeSec(timeSec int)

func (*Client) SetVersion4 

func (c *Client) SetVersion4(set bool)

func (*Client) SetVersion6 

func (c *Client) SetVersion6(set bool)

func (*Client) SetWindow 

func (c *Client) SetWindow(window string)

func (*Client) SetZeroCopy 

func (c *Client) SetZeroCopy(set bool)

func (*Client) Start 

func (c *Client) Start() (err error)

func (*Client) StartEx 

func (c *Client) StartEx() (pid int, err error)

func (*Client) Stop 

func (c *Client) Stop()

func (*Client) Streams 

func (c *Client) Streams() int

func (*Client) TOS 

func (c *Client) TOS() int

func (*Client) TimeSec 

func (c *Client) TimeSec() int

func (*Client) Version4 

func (c *Client) Version4() bool

func (*Client) Version6 

func (c *Client) Version6() bool

func (*Client) Window 

func (c *Client) Window() string

func (*Client) ZeroCopy 

func (c *Client) ZeroCopy() bool

type ClientOptions 

type ClientOptions struct {
	Port          *int      `json:"port" yaml:"port" xml:"port"`
	Format        *rune     `json:"format" yaml:"format" xml:"format"`
	Interval      *int      `json:"interval" yaml:"interval" xml:"interval"`
	JSON          *bool     `json:"json" yaml:"json" xml:"json"`
	LogFile       *string   `json:"log_file" yaml:"log_file" xml:"log_file"`
	Host          *string   `json:"host" yaml:"host" xml:"host"`
	Proto         *Protocol `json:"proto" yaml:"proto" xml:"proto"`
	Bandwidth     *string   `json:"bandwidth" yaml:"bandwidth" xml:"bandwidth"`
	TimeSec       *int      `json:"time_sec" yaml:"time_sec" xml:"time_sec"`
	Bytes         *string   `json:"bytes" yaml:"bytes" xml:"bytes"`
	BlockCount    *string   `json:"block_count" yaml:"block_count" xml:"block_count"`
	Length        *string   `json:"length" yaml:"length" xml:"length"`
	Streams       *int      `json:"streams" yaml:"streams" xml:"streams"`
	Reverse       *bool     `json:"reverse" yaml:"reverse" xml:"reverse"`
	Window        *string   `json:"window" yaml:"window" xml:"window"`
	MSS           *int      `json:"mss" yaml:"mss" xml:"mss"`
	NoDelay       *bool     `json:"no_delay" yaml:"no_delay" xml:"no_delay"`
	Version4      *bool     `json:"version_4" yaml:"version_4" xml:"version_4"`
	Version6      *bool     `json:"version_6" yaml:"version_6" xml:"version_6"`
	TOS           *int      `json:"tos" yaml:"tos" xml:"tos"`
	ZeroCopy      *bool     `json:"zero_copy" yaml:"zero_copy" xml:"zero_copy"`
	OmitSec       *int      `json:"omit_sec" yaml:"omit_sec" xml:"omit_sec"`
	Prefix        *string   `json:"prefix" yaml:"prefix" xml:"prefix"`
	IncludeServer *bool     `json:"include_server" yaml:"include_server" xml:"include_server"`
}

type ConnectingToInfo 

type ConnectingToInfo struct {
	Host string `json:"host"`
	Port int    `json:"port"`
}

func (*ConnectingToInfo) String 

func (cti *ConnectingToInfo) String() string

type ConnectionInfo 

type ConnectionInfo struct {
	Socket     int    `json:"socket"`
	LocalHost  string `json:"local_host"`
	LocalPort  int    `json:"local_port"`
	RemoteHost string `json:"remote_host"`
	RemotePort int    `json:"remote_port"`
}

func (*ConnectionInfo) String 

func (ci *ConnectionInfo) String() string

type Controller 

type Controller struct {
	api.UnimplementedCommandServer
	Port int
	// contains filtered or unexported fields
}

Controller is a helper in the go-iperf package that is designed to run on both the client and the server side. On the server side it listens for new gRPC connections, when a connection is made by a client the client can tell it to start a new iperf server instance. It will start a instance on an unused port and return the port number to the client. This allows the entire iperf setup and session to be performed from the client side.

func NewController 

func NewController(port int) (controller *Controller, err error)

func (*Controller) GrpcRequestServer 

func (c *Controller) GrpcRequestServer(context.Context, *api.StartServerRequest) (*api.StartServerResponse, error)

StartServer is the handler for the gRPC function StartServer()

func (*Controller) NewClient 

func (c *Controller) NewClient(serverAddr string) (client *Client, err error)

NewClient gets a new instance of an iperf client and also starts up a matched iperf server instance on the specified serverAddr. If it fails to connect to the gRPC interface of the controller on the remote side it will return an error

func (*Controller) NewServer 

func (c *Controller) NewServer() (server *Server, err error)

NewServer gets a new instance of an iperf server on a free port

func (*Controller) StopClient 

func (c *Controller) StopClient(id string) (err error)

StopClient will clean up the server side connection and shut down any actively used resources

func (*Controller) StopServer 

func (c *Controller) StopServer(id string) (err error)

StopServer shuts down an iperf server and frees any actively used resources

type CpuUtilizationReport 

type CpuUtilizationReport struct {
	HostTotal    float32 `json:"host_total"`
	HostUser     float32 `json:"host_user"`
	HostSystem   float32 `json:"host_system"`
	RemoteTotal  float32 `json:"remote_total"`
	RemoteUser   float32 `json:"remote_user"`
	RemoteSystem float32 `json:"remote_system"`
}

func (*CpuUtilizationReport) String 

func (cur *CpuUtilizationReport) String() string

type DebugScanner 

type DebugScanner struct {
	Silent bool
}

func (*DebugScanner) Scan 

func (ds *DebugScanner) Scan(buff io.ReadCloser)

type EndInfo 

type EndInfo struct {
	Streams     []*StreamEndReport   `json:"streams"`
	SumSent     StreamEndSumReport   `json:"sum_sent"`
	SumReceived StreamEndSumReport   `json:"sum_received"`
	CpuReport   CpuUtilizationReport `json:"cpu_utilization_percent"`
}

func (*EndInfo) String 

func (ei *EndInfo) String() string

type Protocol 

type Protocol string

type Reporter 

type Reporter struct {
	ReportingChannel chan *StreamIntervalReport
	LogFile          string
	// contains filtered or unexported fields
}

func (*Reporter) Start 

func (r *Reporter) Start()

func (*Reporter) Stop 

func (r *Reporter) Stop()

type Server 

type Server struct {
	Id       string         `json:"id" yaml:"id" xml:"id"`
	Running  bool           `json:"running" yaml:"running" xml:"running"`
	Options  *ServerOptions `json:"-" yaml:"-" xml:"-"`
	ExitCode *int           `json:"exit_code" yaml:"exit_code" xml:"exit_code"`
	Debug    bool           `json:"-" yaml:"-" xml:"-"`
	StdOut   bool           `json:"-" yaml:"-" xml:"-"`
	// contains filtered or unexported fields
}

func NewServer 

func NewServer() *Server

func (*Server) Format 

func (s *Server) Format() rune

func (*Server) Interval 

func (s *Server) Interval() int

func (*Server) JSON 

func (s *Server) JSON() bool

func (*Server) LoadOptions 

func (s *Server) LoadOptions(options *ServerOptions)

func (*Server) LoadOptionsJSON 

func (s *Server) LoadOptionsJSON(jsonStr string) (err error)

func (*Server) LogFile 

func (s *Server) LogFile() string

func (*Server) OneOff 

func (s *Server) OneOff() bool

func (*Server) Port 

func (s *Server) Port() int

func (*Server) SetFormat 

func (s *Server) SetFormat(format rune)

func (*Server) SetJSON 

func (s *Server) SetJSON(json bool)

func (*Server) SetLogFile 

func (s *Server) SetLogFile(filename string)

func (*Server) SetOneOff 

func (s *Server) SetOneOff(oneOff bool)

func (*Server) SetPort 

func (s *Server) SetPort(port int)

func (*Server) Start 

func (s *Server) Start() (err error)

func (*Server) StartEx 

func (s *Server) StartEx() (pid int, err error)

func (*Server) Stop 

func (s *Server) Stop()

type ServerOptions 

type ServerOptions struct {
	OneOff   *bool   `json:"one_off" yaml:"one_off" xml:"one_off"`
	Port     *int    `json:"port" yaml:"port" xml:"port"`
	Format   *rune   `json:"format" yaml:"format" xml:"format"`
	Interval *int    `json:"interval" yaml:"interval" xml:"interval"`
	JSON     *bool   `json:"json" yaml:"json" xml:"json"`
	LogFile  *string `json:"log_file" yaml:"log_file" xml:"log_file"`
}

type ServerReport 

type ServerReport struct {
	Start     StartInfo         `json:"start"`
	Intervals []*StreamInterval `json:"intervals"`
	End       EndInfo           `json:"end"`
	Error     string            `json:"error"`
}

func (*ServerReport) String 

func (sr *ServerReport) String() string

type StartInfo 

type StartInfo struct {
	Connected     []*ConnectionInfo `json:"connected"`
	Version       string            `json:"version"`
	SystemInfo    string            `json:"system_info"`
	Timestamp     TimestampInfo     `json:"timestamp"`
	ConnectingTo  ConnectingToInfo  `json:"connecting_to"`
	Cookie        string            `json:"cookie"`
	TcpMssDefault int               `json:"tcp_mss_default"`
	TestStart     TestStartInfo     `json:"test_start"`
}

func (*StartInfo) String 

func (si *StartInfo) String() string

type StreamEndReport 

type StreamEndReport struct {
	Sender   TcpStreamEndReport `json:"sender"`
	Receiver TcpStreamEndReport `json:"receiver"`
	Udp      UdpStreamEndReport `json:"udp"`
}

func (*StreamEndReport) String 

func (ser *StreamEndReport) String() string

type StreamEndSumReport 

type StreamEndSumReport struct {
	Start         float32 `json:"start"`
	End           float32 `json:"end"`
	Seconds       float32 `json:"seconds"`
	Bytes         int     `json:"bytes"`
	BitsPerSecond float64 `json:"bits_per_second"`
}

func (*StreamEndSumReport) String 

func (sesr *StreamEndSumReport) String() string

type StreamInterval 

type StreamInterval struct {
	Streams []*StreamIntervalReport  `json:"streams"`
	Sum     *StreamIntervalSumReport `json:"sum"`
}

func (*StreamInterval) String 

func (si *StreamInterval) String() string

type StreamIntervalReport 

type StreamIntervalReport struct {
	Socket           int     `json:"socket"`
	StartInterval    float32 `json:"start"`
	EndInterval      float32 `json:"end"`
	Seconds          float32 `json:"seconds"`
	Bytes            int     `json:"bytes"`
	BitsPerSecond    float64 `json:"bits_per_second"`
	Retransmissions  int     `json:"retransmissions"`
	CongestionWindow int     `json:"congestion_window"`
	Omitted          bool    `json:"omitted"`
}

func (*StreamIntervalReport) String 

func (sir *StreamIntervalReport) String() string

type StreamIntervalSumReport 

type StreamIntervalSumReport struct {
	StartInterval float32 `json:"start"`
	EndInterval   float32 `json:"end"`
	Seconds       float32 `json:"seconds"`
	Bytes         int     `json:"bytes"`
	BitsPerSecond float64 `json:"bits_per_second"`
	Omitted       bool    `json:"omitted"`
}

func (*StreamIntervalSumReport) String 

func (sisr *StreamIntervalSumReport) String() string

type TcpStreamEndReport 

type TcpStreamEndReport struct {
	Socket        int     `json:"socket"`
	Start         float32 `json:"start"`
	End           float32 `json:"end"`
	Seconds       float32 `json:"seconds"`
	Bytes         int     `json:"bytes"`
	BitsPerSecond float64 `json:"bits_per_second"`
}

func (*TcpStreamEndReport) String 

func (tser *TcpStreamEndReport) String() string

type TestMode 

type TestMode string
const (
	MODE_JSON TestMode = "json"
	MODE_LIVE TestMode = "live"
)

type TestReport 

type TestReport struct {
	Start            StartInfo         `json:"start"`
	Intervals        []*StreamInterval `json:"intervals"`
	End              EndInfo           `json:"end"`
	Error            string            `json:"error"`
	ServerOutputJson ServerReport      `json:"server_output_json"`
}

func Load 

func Load(filename string) (report *TestReport, err error)

func Loads 

func Loads(jsonStr string) (report *TestReport, err error)

func (*TestReport) String 

func (tr *TestReport) String() string

type TestStartInfo 

type TestStartInfo struct {
	Protocol   string `json:"protocol"`
	NumStreams int    `json:"num_streams"`
	BlkSize    int    `json:"blksize"`
	Omit       int    `json:"omit"`
	Duration   int    `json:"duration"`
	Bytes      int    `json:"bytes"`
	Blocks     int    `json:"blocks"`
	Reverse    int    `json:"reverse"`
}

func (*TestStartInfo) String 

func (tsi *TestStartInfo) String() string

type TimestampInfo 

type TimestampInfo struct {
	Time     string `json:"time"`
	TimeSecs int    `json:"timesecs"`
}

func (*TimestampInfo) String 

func (tsi *TimestampInfo) String() string

type UdpStreamEndReport 

type UdpStreamEndReport struct {
	Socket        int     `json:"socket"`
	Start         float32 `json:"start"`
	End           float32 `json:"end"`
	Seconds       float32 `json:"seconds"`
	Bytes         int     `json:"bytes"`
	BitsPerSecond float64 `json:"bits_per_second"`
	JitterMs      float32 `json:"jitter_ms"`
	LostPackets   int     `json:"lost_packets"`
	Packets       int     `json:"packets"`
	LostPercent   float32 `json:"lost_percent"`
	OutOfOrder    int     `json:"out_of_order"`
}

func (*UdpStreamEndReport) String 

func (user *UdpStreamEndReport) String() string

Source Files

View all Source files

Directories

Path Synopsis
api
go
tests
client
controller
extract
server

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.