sflow

package
v0.2.2 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2022 License: MIT Imports: 17 Imported by: 0

README

SFlow Input Plugin

The SFlow Input Plugin provides support for acting as an SFlow V5 collector in accordance with the specification from sflow.org.

Currently only Flow Samples of Ethernet / IPv4 & IPv4 TCP & UDP headers are turned into metrics. Counters and other header samples are ignored.

Series Cardinality Warning

This plugin may produce a high number of series which, when not controlled for, will cause high load on your database. Use the following techniques to avoid cardinality issues:

Configuration
[[inputs.sflow]]
  instance_id = "" # unique instance identifier (REQUIRED)

  ## Address to listen for sFlow packets.
  ##   example: service_address = "udp://:6343"
  ##            service_address = "udp4://:6343"
  ##            service_address = "udp6://:6343"
  service_address = "udp://:6343"

  ## Set the size of the operating system's receive buffer.
  ##   example: read_buffer_size = "64KiB"
  # read_buffer_size = ""
Metrics
  • sflow
    • tags:
      • agent_address (IP address of the agent that obtained the sflow sample and sent it to this collector)
      • source_id_type(source_id_type field of flow_sample or flow_sample_expanded structures)
      • source_id_index(source_id_index field of flow_sample or flow_sample_expanded structures)
      • input_ifindex (value (input) field of flow_sample or flow_sample_expanded structures)
      • output_ifindex (value (output) field of flow_sample or flow_sample_expanded structures)
      • sample_direction (source_id_index, netif_index_in and netif_index_out)
      • header_protocol (header_protocol field of sampled_header structures)
      • ether_type (eth_type field of an ETHERNET-ISO88023 header)
      • src_ip (source_ipaddr field of IPv4 or IPv6 structures)
      • src_port (src_port field of TCP or UDP structures)
      • src_port_name (src_port)
      • src_mac (source_mac_addr field of an ETHERNET-ISO88023 header)
      • src_vlan (src_vlan field of extended_switch structure)
      • src_priority (src_priority field of extended_switch structure)
      • src_mask_len (src_mask_len field of extended_router structure)
      • dst_ip (destination_ipaddr field of IPv4 or IPv6 structures)
      • dst_port (dst_port field of TCP or UDP structures)
      • dst_port_name (dst_port)
      • dst_mac (destination_mac_addr field of an ETHERNET-ISO88023 header)
      • dst_vlan (dst_vlan field of extended_switch structure)
      • dst_priority (dst_priority field of extended_switch structure)
      • dst_mask_len (dst_mask_len field of extended_router structure)
      • next_hop (next_hop field of extended_router structure)
      • ip_version (ip_ver field of IPv4 or IPv6 structures)
      • ip_protocol (ip_protocol field of IPv4 or IPv6 structures)
      • ip_dscp (ip_dscp field of IPv4 or IPv6 structures)
      • ip_ecn (ecn field of IPv4 or IPv6 structures)
      • tcp_urgent_pointer (urgent_pointer field of TCP structure)
    • fields:
      • bytes (integer, the product of frame_length and packets)
      • drops (integer, drops field of flow_sample or flow_sample_expanded structures)
      • packets (integer, sampling_rate field of flow_sample or flow_sample_expanded structures)
      • frame_length (integer, frame_length field of sampled_header structures)
      • header_size (integer, header_size field of sampled_header structures)
      • ip_fragment_offset (integer, ip_ver field of IPv4 structures)
      • ip_header_length (integer, ip_ver field of IPv4 structures)
      • ip_total_length (integer, ip_total_len field of IPv4 structures)
      • ip_ttl (integer, ip_ttl field of IPv4 structures or ip_hop_limit field IPv6 structures)
      • tcp_header_length (integer, size field of TCP structure. This value is specified in 32-bit words. It must be multiplied by 4 to produce a value in bytes.)
      • tcp_window_size (integer, window_size field of TCP structure)
      • udp_length (integer, length field of UDP structures)
      • ip_flags (integer, ip_ver field of IPv4 structures)
      • tcp_flags (integer, TCP flags of TCP IP header (IPv4 or IPv6))
Troubleshooting

The sflowtool utility can be used to print sFlow packets, and compared against the metrics produced by agent.

sflowtool -p 6343

If opening an issue, in addition to the output of sflowtool it will also be helpful to collect a packet capture. Adjust the interface, host and port as needed:

sudo tcpdump -s 0 -i eth0 -w circonus-unified-agent-sflow.pcap host 127.0.0.1 and port 6343
Example Output
sflow,agent_address=0.0.0.0,dst_ip=10.0.0.2,dst_mac=ff:ff:ff:ff:ff:ff,dst_port=40042,ether_type=IPv4,header_protocol=ETHERNET-ISO88023,input_ifindex=6,ip_dscp=27,ip_ecn=0,output_ifindex=1073741823,source_id_index=3,source_id_type=0,src_ip=10.0.0.1,src_mac=ff:ff:ff:ff:ff:ff,src_port=443 bytes=1570i,drops=0i,frame_length=157i,header_length=128i,ip_flags=2i,ip_fragment_offset=0i,ip_total_length=139i,ip_ttl=42i,sampling_rate=10i,tcp_header_length=0i,tcp_urgent_pointer=0i,tcp_window_size=14i 1584473704793580447
Reference Documentation

This sflow implementation was built from the reference document sflow.org/sflow_version_5.txt

Documentation

Index

Constants

View Source
const (
	AddressTypeIPv6 uint32 = 2 // sflow_version_5.txt line: 1384
	AddressTypeIPv4 uint32 = 1 // sflow_version_5.txt line: 1383

	IPProtocolTCP uint8 = 6
	IPProtocolUDP uint8 = 17
)

Variables

View Source
var ETypeMap = map[uint16]string{
	0x0800: "IPv4",
	0x86DD: "IPv6",
}
View Source
var HeaderProtocolMap = map[HeaderProtocolType]string{
	HeaderProtocolTypeEthernetISO88023: "ETHERNET-ISO88023",
}
View Source
var IPvMap = map[uint32]string{
	1: "IPV4",
	2: "IPV6",
}

Functions

This section is empty.

Types

type AddressType

type AddressType uint32 // must be uint32
const (
	AddressTypeUnknown AddressType = 0
	AddressTypeIPV4    AddressType = 1
	AddressTypeIPV6    AddressType = 2
)

type ContainsMetricData

type ContainsMetricData interface {
	GetTags() map[string]string
	GetFields() map[string]interface{}
}

type EthHeader

type EthHeader struct {
	DestinationMAC        [6]byte
	SourceMAC             [6]byte
	TagProtocolIdentifier uint16
	TagControlInformation uint16
	EtherTypeCode         uint16
	EtherType             string
	IPHeader              IPHeader
}

func (EthHeader) GetFields

func (h EthHeader) GetFields() map[string]interface{}

func (EthHeader) GetTags

func (h EthHeader) GetTags() map[string]string

type FlowData

type FlowData ContainsMetricData

type FlowFormatType

type FlowFormatType uint32
const (
	FlowFormatTypeRawPacketHeader FlowFormatType = 1 // sflow_version_5.txt line: 1938
)

type FlowRecord

type FlowRecord struct {
	FlowFormat FlowFormatType
	FlowData   FlowData
}
type Header ContainsMetricData

type HeaderProtocolType

type HeaderProtocolType uint32
const (
	HeaderProtocolTypeEthernetISO88023  HeaderProtocolType = 1
	HeaderProtocolTypeISO88024TokenBus  HeaderProtocolType = 2
	HeaderProtocolTypeISO88025TokenRing HeaderProtocolType = 3
	HeaderProtocolTypeFDDI              HeaderProtocolType = 4
	HeaderProtocolTypeFrameRelay        HeaderProtocolType = 5
	HeaderProtocolTypeX25               HeaderProtocolType = 6
	HeaderProtocolTypePPP               HeaderProtocolType = 7
	HeaderProtocolTypeSMDS              HeaderProtocolType = 8
	HeaderProtocolTypeAAL5              HeaderProtocolType = 9
	HeaderProtocolTypeAAL5IP            HeaderProtocolType = 10 /* e.g. Cisco AAL5 mux */
	HeaderProtocolTypeIPv4              HeaderProtocolType = 11
	HeaderProtocolTypeIPv6              HeaderProtocolType = 12
	HeaderProtocolTypeMPLS              HeaderProtocolType = 13
	HeaderProtocolTypePOS               HeaderProtocolType = 14 /* RFC 1662, 2615 */
)

type IPHeader

type IPHeader ContainsMetricData

type IPV4Header

type IPV4Header struct {
	Version              uint8 // 4 bit
	InternetHeaderLength uint8 // 4 bit
	DSCP                 uint8
	ECN                  uint8
	TotalLength          uint16
	Identification       uint16
	Flags                uint8
	FragmentOffset       uint16
	TTL                  uint8
	Protocol             uint8 // https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers
	HeaderChecksum       uint16
	SourceIP             [4]byte
	DestIP               [4]byte
	ProtocolHeader       ProtocolHeader
}

https://en.wikipedia.org/wiki/IPv4#Header

func (IPV4Header) GetFields

func (h IPV4Header) GetFields() map[string]interface{}

func (IPV4Header) GetTags

func (h IPV4Header) GetTags() map[string]string

type IPV6Header

type IPV6Header struct {
	DSCP            uint8
	ECN             uint8
	PayloadLength   uint16
	NextHeaderProto uint8 // tcp/udp?
	HopLimit        uint8
	SourceIP        [16]byte
	DestIP          [16]byte
	ProtocolHeader  ProtocolHeader
}

https://en.wikipedia.org/wiki/IPv6_packet

func (IPV6Header) GetFields

func (h IPV6Header) GetFields() map[string]interface{}

func (IPV6Header) GetTags

func (h IPV6Header) GetTags() map[string]string

type InterfaceFormatType

type InterfaceFormatType uint8 // sflow_version_5.txt line 1497
const (
	InterfaceFormatTypeSingleInterface InterfaceFormatType = 0
	InterfaceFormatTypePacketDiscarded InterfaceFormatType = 1
)

type PacketDecoder

type PacketDecoder struct {
	Log cua.Logger
	// contains filtered or unexported fields
}

func NewDecoder

func NewDecoder() *PacketDecoder

func (*PacketDecoder) Decode

func (d *PacketDecoder) Decode(r io.Reader) error

func (*PacketDecoder) DecodeOnePacket

func (d *PacketDecoder) DecodeOnePacket(r io.Reader) (*V5Format, error)

func (*PacketDecoder) OnPacket

func (d *PacketDecoder) OnPacket(f func(p *V5Format))

type ProtocolHeader

type ProtocolHeader ContainsMetricData

type RawPacketHeaderFlowData

type RawPacketHeaderFlowData struct {
	HeaderProtocol HeaderProtocolType
	FrameLength    uint32
	Bytes          uint32
	StrippedOctets uint32
	HeaderLength   uint32
	Header         Header
}

func (RawPacketHeaderFlowData) GetFields

func (h RawPacketHeaderFlowData) GetFields() map[string]interface{}

func (RawPacketHeaderFlowData) GetTags

func (h RawPacketHeaderFlowData) GetTags() map[string]string

type SFlow

type SFlow struct {
	ServiceAddress string        `toml:"service_address"`
	ReadBufferSize internal.Size `toml:"read_buffer_size"`

	Log cua.Logger `toml:"-"`
	// contains filtered or unexported fields
}

func (*SFlow) Address

func (s *SFlow) Address() net.Addr

func (*SFlow) Description

func (s *SFlow) Description() string

Description answers a description of this input plugin

func (*SFlow) Gather

func (s *SFlow) Gather(_ context.Context, _ cua.Accumulator) error

Gather is a NOOP for sFlow as it receives, asynchronously, sFlow network packets

func (*SFlow) Init

func (s *SFlow) Init() error

func (*SFlow) SampleConfig

func (s *SFlow) SampleConfig() string

SampleConfig answers a sample configuration

func (*SFlow) Start

func (s *SFlow) Start(ctx context.Context, acc cua.Accumulator) error

Start starts this sFlow listener listening on the configured network for sFlow packets

func (*SFlow) Stop

func (s *SFlow) Stop()

type Sample

type Sample struct {
	SampleType SampleType
	SampleData SampleDataFlowSampleExpanded
}

type SampleData

type SampleData interface{}

type SampleDataFlowSampleExpanded

type SampleDataFlowSampleExpanded struct {
	SequenceNumber  uint32
	SourceIDType    uint32
	SourceIDIndex   uint32
	SamplingRate    uint32
	SamplePool      uint32
	Drops           uint32
	SampleDirection string // ingress/egress
	InputIfFormat   uint32
	InputIfIndex    uint32
	OutputIfFormat  uint32
	OutputIfIndex   uint32
	FlowRecords     []FlowRecord
}

type SampleType

type SampleType uint32
const (
	SampleTypeFlowSample         SampleType = 1 // sflow_version_5.txt line: 1614
	SampleTypeFlowSampleExpanded SampleType = 3 // sflow_version_5.txt line: 1698
)

type TCPHeader

type TCPHeader struct {
	SourcePort       uint16
	DestinationPort  uint16
	Sequence         uint32
	AckNumber        uint32
	TCPHeaderLength  uint8
	Flags            uint16
	TCPWindowSize    uint16
	Checksum         uint16
	TCPUrgentPointer uint16
}

https://en.wikipedia.org/wiki/Transmission_Control_Protocol

func (TCPHeader) GetFields

func (h TCPHeader) GetFields() map[string]interface{}

func (TCPHeader) GetTags

func (h TCPHeader) GetTags() map[string]string

type UDPHeader

type UDPHeader struct {
	SourcePort      uint16
	DestinationPort uint16
	UDPLength       uint16
	Checksum        uint16
}

func (UDPHeader) GetFields

func (h UDPHeader) GetFields() map[string]interface{}

func (UDPHeader) GetTags

func (h UDPHeader) GetTags() map[string]string

type V5Format

type V5Format struct {
	Version        uint32
	AgentAddress   net.IPAddr
	SubAgentID     uint32
	SequenceNumber uint32
	Uptime         uint32
	Samples        []Sample
}

V5Format answers and decoder.Directive capable of decoding sFlow v5 packets in accordance with SFlow v5 specification at https://sflow.org/sflow_version_5.txt

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL