sar

package
v8.0.0-rc6 Latest Latest
Warning

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

 Go to latest Published: Jan 24, 2024 License: Apache-2.0, BSD-2-Clause, BSD-3-Clause, + 1 more Imports: 10 Imported by: 0

Documentation

Overview

package sar implements a syn-ack-rst health ping. It sends a TCP SYN, waits for an ACK, then immediately sends an RST to kill the connection. The primary purpose of this is as a health check, to verify the remote host is reachable, and able and willing to respond.

package sar implements a syn-ack-rst health ping. It sends a TCP SYN, waits for an ACK, then immediately sends an RST to kill the connection. The primary purpose of this is as a health check, to verify the remote host is reachable, and able and willing to respond.

Index

Constants

View Source 
const ProtocolNumberTCP = 6

ProtocolNumberTCP is the protocol number for TCP. See IANA Protocol Numbers, RFC791.

View Source 
const TCPHdrOptionEndOfOptionList = 0
View Source 
const TCPHdrOptionNoOperation = 1

Variables

This section is empty.

Functions

func FindNetInterfaceAddr 

func FindNetInterfaceAddr() (string, net.Addr, error)

FindNetInterfaceAddr selects a local network interface to use. It picks the first interface that isn't loopback, is up, and has addresses. It then picks the first address in that interface. Returns the selected interface name, the selected address, and any error.

func GetLocalAddr 

func GetLocalAddr() (string, error)

GetLocalAddr gets a local IP, which this package will set as the TCP packet source, and then listen on this address to get the syn-ack response.

func MakeTCPChecksum 

func MakeTCPChecksum(data []byte, sourceIP []byte, destIP []byte) uint16

MakeTCPChecksum creates the TCP packet checksum. See RFC9293§3.1 TODO handle IPv6

func SAR 

func SAR(log llog.Log, host string, port int, timeout time.Duration) (time.Duration, error)

SAR calls SARAddr if host is an IP address, or SARHost if host is an FQDN.

func SARAddr 

func SARAddr(log llog.Log, addr string, port int, timeout time.Duration) (time.Duration, error)

SARAddr sends a syn-ack-reset to the given addr. The addr must be an IP. On success, the round-trip time to receive the Ack is returned, with a nil error. The addr is a string representation of an IPv4 or IPv6 address. TODO add optional local addr param

func SARHost 

func SARHost(log llog.Log, host string, port int, timeout time.Duration) (time.Duration, error)

SARHost sends a syn-ack-reset to the given hostname. It looks up the hostname, and calls SendAddr on the first returned address. See SendAddr.

func SendPacket 

func SendPacket(packet TCPHdr, addr string) (time.Time, error)

SendPacket sends the given packet to the given address and port.

Note this doesn't take the local IP:port, which will be the source, which the destination will reply to, Because those must already be included in the packet.

Returns the time immediately before the packet was sent, and any error.

func SplitLast 

func SplitLast(str string, delim string) []string

SplitLast splits on the last occurence of delim. The returned slice will always have at least one element. If str contains delim, the returned slice will have 2 elements.

Types

type EphemeralPortHolder 

type EphemeralPortHolder struct {
	// contains filtered or unexported fields
}

EphemeralPortHolder serves 2 purposes: it gets an ephemeral TCP port, and it holds onto the port so the OS doesn't assign it to any other app.

It listens on :0 thereby getting a socket on an ephemeral port. It continues listening but never reading from the socket until Close is called.

func GetAndHoldEphemeralPort 

func GetAndHoldEphemeralPort(addr string) (*EphemeralPortHolder, error)

GetAndHoldEphemeralPort gets an ephemeral port, and listens on it to prevent the OS assigning the port to other apps. Close must be called on the returned EphemeralPortHolder to stop listening.

func (*EphemeralPortHolder) Addr 

func (ph *EphemeralPortHolder) Addr() net.Addr

func (*EphemeralPortHolder) Close 

func (ph *EphemeralPortHolder) Close() error

func (*EphemeralPortHolder) Port 

func (ph *EphemeralPortHolder) Port() int

type HostPort 

type HostPort struct {
	Host string
	Port int
}

type SARResult 

type SARResult struct {
	Host string
	Port int
	RTT  time.Duration
	Err  error
}

func MultiSAR 

func MultiSAR(log llog.Log, hosts []HostPort, timeout time.Duration) ([]SARResult, error)

MultiSAR is like SAR for multiple requests. SAR has to listen on a raw IP port without a TCP socket, which is relatively inexpensive for a single request, but expensive for large numbers of requests. MultiSAR uses a single listener on an ephemeral local port for all SAR requests, significantly reducing resource costs.

type TCPHdr 

type TCPHdr []byte

TCPHdr is a TCP header

TCPHdr should always be constructed with at least 20 bytes, the minimum TCP header size. Users constructing a TCPHdr and giving it to a trusting caller must ensure it is at least 20 bytes and valid. Users receiving an untrusted TCPHdr must check it is at least 20 bytes. This type and its functions do not check size or validity, for performance reasons, and therefore may panic if the TCPHdr is too small or otherwise malformed.

Note TCPHdr does no validation of any kind, and is completely unaware of the contents of the packet, including the semantics of any TCP Options.

For a more convenient but slower implementation, use TCPHdrDecoded (TODO implement)

See Valid.

func TCPHdrFromNative 

func TCPHdrFromNative(native TCPHdrNative) (TCPHdr, error)

TCPHdrFromNative creates a TCPHdr bytes from a TCPHdrNative. The created TCPHdr is ready to send over the wire.

func (TCPHdr) ACK 

func (th TCPHdr) ACK() bool

ACK is the Acknowledgement flag. See RFC9293§3.1.

func (TCPHdr) AckNum 

func (th TCPHdr) AckNum() uint32

func (TCPHdr) CWR 

func (th TCPHdr) CWR() bool

CWR is the Congestion Window Reduced flag, part of the ECN Explicit Congestion Notification. See RFC3168§6.1, RFC9293§3.1.

func (TCPHdr) Checksum 

func (th TCPHdr) Checksum() uint16

func (TCPHdr) Control 

func (th TCPHdr) Control() uint8

Control is the control flag TCP fields: CWR, ECE, URG, ACK, PSH, RST, SYN, FIN.

This provided for convenience and performance, when bit-shifting is faster or more convenient than using booleans. Each control flag is also available via individual boolean funcs.

func (TCPHdr) DataOffset 

func (th TCPHdr) DataOffset() uint8

DataOffset is the DOffset TCP field. See RFC9293§3.1.

Note the Data Offset field is 4 bits; unfortunately, uint8 is the smallest Go type. Therefore, the most significant 4 bits will be unused and are not part of the field.

func (TCPHdr) DestPort 

func (th TCPHdr) DestPort() uint16

func (TCPHdr) ECE 

func (th TCPHdr) ECE() bool

ECE is the ECN-Echo flag, part of the ECN Explicit Congestion Notification. See RFC3168§6.1, RFC9293§3.1.

func (TCPHdr) FIN 

func (th TCPHdr) FIN() bool

FIN is the finish connection flag. See RFC9293§3.1.

func (TCPHdr) OptionData 

func (th TCPHdr) OptionData(prevSize int, optionLen int, n int) []byte

OptionData returns the data of the nth option. See RFC9293§3.2.

The prevSize is the sum of the sizes of all options less than n. This is necessary to find the next option.

Note per RFC9293§3.2 all options except kind 0 (End of Option) and kind 1 (No Operation) have lengths. Callers must detect this and not query OptionLength or OptionData for Kind 0 or 1. Note the Option Length includes the Kind and Length fields, each 1 octet. Therefore, options of length 2 have no data. Options of length <=2 must not call OptionData.

The optionLen is the Length field. Note the Option Length includes the Kind and Length. The optionLen must not be the length of the data, it must be the Option Length field. Therefore, the returned data will be 2 octets less than optionLen.

Note the OptionLength includes padding. Therefore, the data returned by this func will include padding, in addition to the semantic option data. This func is unaware of the semantics of any options.

Note the OptionsData bytes are returned in network byte order (Big Endian), not machine byte order (frequently Little Endian). Because TCPHdr doesn't know about options, it lacks the context to know the sizes and locations of integers inside particular options, and therefore cannot convert byte order. Callers must convert byte order as necessary. See the binary package.

See RFC9293§3.2 for more details.

func (TCPHdr) OptionKind 

func (th TCPHdr) OptionKind(prevSize int, n int) uint8

OptionKind returns the kind of the nth option. See RFC9293§3.2.

The prevSize is the sum of the sizes of all options less than n. This is necessary to find the next option.

Note the End of Option List the last option is of kind 0. So to iterate over all options, continuously request Option(prevSize, n) (tracking the sum of the previous sizes) until the returned option Kind is 0.

Note per RFC9293§3.2 all options except kind 0 (End of Option) and kind 1 (No Operation) have lengths. Callers must detect this and not query OptionLength for Kind 0 or 1.

See RFC9293§3.2 for more details.

func (TCPHdr) OptionLen 

func (th TCPHdr) OptionLen(prevSize int, n int) uint8

OptionLen returns the kind of the nth option. See RFC9293§3.2.

The prevSize is the sum of the sizes of all options less than n. This is necessary to find the next option.

Note per RFC9293§3.2 all options except kind 0 (End of Option) and kind 1 (No Operation) have lengths. Callers must detect this and not query OptionLen for Kind 0 or 1.

See RFC9293§3.2 for more details.

func (TCPHdr) PSH 

func (th TCPHdr) PSH() bool

PSH is the Push flag. See RFC9293§3.1, RFC9293§3.9.1

func (TCPHdr) RST 

func (th TCPHdr) RST() bool

RST is the connection Reset flag. See RFC9293§3.1.

func (TCPHdr) Reserved 

func (th TCPHdr) Reserved() uint8

Reserved is the reserved TCP field. See RFC9293§3.1.

Note the Reserved field is 4 bits; unfortunately, uint8 is the smallest Go type. Therefore, the most significant 4 bits will be unused and are not part of the field.

func (TCPHdr) SYN 

func (th TCPHdr) SYN() bool

SYN is the synchronize sequence numbers flag. See RFC9293§3.1.

func (TCPHdr) SeqNum 

func (th TCPHdr) SeqNum() uint32

func (TCPHdr) SetChecksum 

func (th TCPHdr) SetChecksum(cs uint16)

func (TCPHdr) SrcPort 

func (th TCPHdr) SrcPort() uint16

func (TCPHdr) URG 

func (th TCPHdr) URG() bool

URG is the Urgent flag. See RFC9293§3.1.

func (TCPHdr) Urgent 

func (th TCPHdr) Urgent() uint16

func (TCPHdr) Window 

func (th TCPHdr) Window() uint16

type TCPHdrNative 

type TCPHdrNative struct {
	SrcPort    uint16
	DestPort   uint16
	SeqNum     uint32
	AckNum     uint32
	DataOffset uint8 // 4 bits
	Reserved   uint8 // 4 bits
	CWR        bool
	ECE        bool
	URG        bool
	ACK        bool
	PSH        bool
	RST        bool
	SYN        bool
	FIN        bool
	Window     uint16
	Checksum   uint16 // Kernel will set this if it's 0
	Urgent     uint16
	Options    []TCPHdrNativeOption
}

TCPHdrNative is a convenience struct containing deserialized TCP Header data. This is more convenient but less efficient than TCPHdr.

func TCPHdrToNative 

func TCPHdrToNative(hdr TCPHdr) (TCPHdrNative, error)

TCPHdrToNative creates a TCPHdrNative from a TCPHdr.

type TCPHdrNativeOption 

type TCPHdrNativeOption struct {
	Kind int
	Len  int
	Data []byte
}

Source Files

View all Source files

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.