NAME

Net::sFlow - decode sFlow datagrams.

SYNOPSIS

use Net::sFlow;
use IO::Socket::INET;

my $sock = IO::Socket::INET->new( LocalPort => '6343',
                                  Proto     => 'udp')
                             or die "Can't bind : $@\n";

while ($sock->recv($packet,1548)) {
  &processPacket($packet);
}
die "Socket recv: $!";

sub processPacket {

  my $sFlowPacket = shift;

  my ($sFlowDatagramRef, $sFlowSamplesRef, $errorsRef) = Net::sFlow::decode($sFlowPacket);

  # print errors
    foreach my $error (@{$errorsRef}) {
    warn "$error";
  }

  # print sflow data
  print "===Datagram===\n";
  print "sFlow version: $sFlowDatagramRef->{sFlowVersion}\n";
  print "datagram sequence number: $sFlowDatagramRef->{datagramSequenceNumber}\n";

  foreach my $sFlowSample (@{$printSamplesRef}) {
    print "\n";
    print "---Sample---\n";
    print "sample sequence number: $sFlowSample->{sampleSequenceNumber}\n";
  }

}

DESCRIPTION

The sFlow module provides a mechanism to parse and decode sFlow datagrams. It supports sFlow version 2/4 (RFC 3176 - http://www.ietf.org/rfc/rfc3176.txt) and sFlow version 5 (Memo - http://sflow.org/sflow_version_5.txt).

The module's functionality is provided by a single (exportable) function, decode().

FUNCTIONS

decode( UDP_PAYLOAD )

($datagram, $samples, $error) = Net::sFlow::decode($udp_data);

Returns a HASH reference containing the datagram data, an ARRAY reference with the sample data (each array element contains a HASH reference for one sample) and in case of an error a reference to an ARRAY containing the error messages.

Return Values

A HASH reference containing information about the sFlow datagram, with the following keys:

sFlowVersion
AgentIpVersion
AgentIp
datagramSequenceNumber
agentUptime
samplesInPacket

In the case of sFlow v5, there is an additional key:

subAgentId

$samples

Reference to a list of HASH references, each one representing one sample. Depending on the type, the hash contains the following additional keys:

In case of sFlow <= 4:

sampleType
sampleSequenceNumber
sourceIdType
sourceIdIndex

If it's a sFlow <= 4 flowsample you will get the following additional keys:

samplingRate
samplePool
drops
inputInterface
outputInterface
packetDataType
extendedDataInSample

If it's a sFlow <= 4 countersample you will get these additional keys:

counterSamplingInterval
countersVersion

In case of sFlow >= 5 you will first get enterprise, format and length information:

sampleTypeEnterprise
sampleTypeFormat
sampleLength

In case of a flowsample (enterprise == 0 and format == 1):

sampleSequenceNumber
sourceIdType
sourceIdIndex
samplingRate
samplePool
drops
inputInterface
outputInterface
flowRecordsCount

If it's an expanded flowsample (enterprise == 0 and format == 3) you will get these additional keys instead of inputInterface and outputInterface:

inputInterfaceFormat
inputInterfaceValue
outputInterfaceFormat
outputInterfaceValue

In case of a countersample (enterprise == 0 and format == 2) or an expanded countersample (enterprise == 0 and format == 4):

sampleSequenceNumber
sourceIdType
sourceIdIndex
counterRecordsCount
counterDataLength

Depending on what kind of samples the hardware is taking you will get the following additional keys:

Header data:

HEADERDATA
HeaderProtocol
HeaderFrameLength 
HeaderStrippedLength
HeaderSizeByte
HeaderSizeBit

HeaderEtherSrcMac
HeaderEtherDestMac
HeaderVer
HeaderDatalen

Ethernet frame data:

ETHERNETFRAMEDATA
EtherMacPacketlength
EtherSrcMac
EtherDestMac
EtherPackettype

IPv4 data:

IPv4DATA
IPv4Packetlength
IPv4NextHeaderProtocol
IPv4srcIp
IPv4destIp
IPv4srcPort
IPv4destPort
IPv4tcpFlags
IPv4tos

IPv6 data:

IPv6DATA
IPv6Packetlength
IPv6NextHeaderProto
IPv6srcIp
IPv6destIp
IPv6srcPort
IPv6destPort
IPv6tcpFlags
IPv6Priority

Switch data:

SWITCHDATA
SwitchSrcVlan
SwitchSrcPriority
SwitchDestVlan
SwitchDestPriority  

Router data:

ROUTERDATA
RouterIpVersionNextHopRouter
RouterIpAddressNextHopRouter
RouterSrcMask
RouterDestMask

Gateway data:

GATEWAYDATA
GatewayIpVersionNextHopRouter (only in case of sFlow v5)
GatewayIpAddressNextHopRouter (only in case of sFlow v5)
GatewayAsRouter
GatewayAsSource
GatewayAsSourcePeer
GatewayDestAsPathsCount

GatewayDestAsPaths (arrayreference)
  each enty contains a hashreference:
    asPathSegmentType
    lengthAsList
    AsPath (arrayreference, asNumbers as entries)

GatewayLengthCommunitiesList (added in sFlow v4)
GatewayCommunities (arrayreference, added in sFlow v4)
  each enty contains a community (added in sFlow v4)

localPref

User data:

USERDATA
UserSrcCharset (only in case of sFlow v5)
UserLengthSrcString
UserSrcString
UserDestCharset (only in case of sFlow v5)
UserLengthDestString
UserDestString

Url data (added in sFlow v3):

URLDATA
UrlDirection
UrlLength
Url
UrlHostLength (only in case of sFlow v5)
UrlHost (only in case of sFlow v5)

The following keys can be only available in sFlow v5:

Mpls data:

MPLSDATA
MplsIpVersionNextHopRouter
MplsIpAddressNextHopRouter
MplsInLabelStackCount
MplsInLabelStack (arrayreference containing MplsInLabels)
MplsOutLabelStackCount
MplsOutLabelStack (arrayreference containing MplsOutLabels)  

Nat data:

NATDATA
NatIpVersionSrcAddress
NatSrcAddress
NatIpVersionDestAddress
NatDestAddress

Mpls tunnel:

MPLSTUNNEL
MplsTunnelLength
MplsTunnelName
MplsTunnelId
MplsTunnelCosValue  

Mpls vc:

MPLSVC
MplsVcInstanceNameLength
MplsVcInstanceName
MplsVcId
MplsVcLabelCosValue

Mpls fec:

MPLSFEC
MplsFtnDescrLength
MplsFtnDescr
MplsFtnMask

Mpls lpv fec:

MPLSLPVFEC
MplsFecAddrPrefixLength

Vlan tunnel:

VLANTUNNEL
VlanTunnelLayerStackCount
VlanTunnelLayerStack (arrayreference containing VlanTunnelLayer entries)

The following keys are also available in sFlow < 5:

Counter generic:

COUNTERGENERIC
ifIndex
ifType
ifSpeed
ifDirection
ifAdminStatus
ifOperStatus
idInOctets
ifInUcastPkts
ifInMulticastPkts
ifInBroadcastPkts
idInDiscards
ifInErrors
ifInUnknownProtos
ifOutOctets
ifOutUcastPkts
ifOutMulticastPkts
ifOutBroadcastPkts
ifOutDiscards
ifOutErrors
ifPromiscuousMode

Counter ethernet:

COUNTERETHERNET
dot3StatsAlignmentErrors
dot3StatsFCSErrors
dot3StatsSingleCollisionFrames
dot3StatsMultipleCollisionFrames
dot3StatsSQETestErrors
dot3StatsDeferredTransmissions
dot3StatsLateCollisions
dot3StatsExcessiveCollisions
dot3StatsInternalMacTransmitErrors
dot3StatsCarrierSenseErrors
dot3StatsFrameTooLongs
dot3StatsInternalMacReceiveErrors
dot3StatsSymbolErrors

Counter tokenring:

COUNTERTOKENRING
dot5StatsLineErrors
dot5StatsBurstErrors
dot5StatsACErrors
dot5StatsAbortTransErrors
dot5StatsInternalErrors
dot5StatsLostFrameErrors
dot5StatsReceiveCongestions
dot5StatsFrameCopiedErrors
dot5StatsTokenErrors
dot5StatsSoftErrors
dot5StatsHardErrors
dot5StatsSignalLoss
dot5StatsTransmitBeacons
dot5StatsRecoverys
dot5StatsLobeWires
dot5StatsRemoves
dot5StatsSingles
dot5StatsFreqErrors

Counter vg:

COUNTERVG
dot12InHighPriorityFrames
dot12InHighPriorityOctets
dot12InNormPriorityFrames
dot12InNormPriorityOctets
dot12InIPMErrors
dot12InOversizeFrameErrors
dot12InDataErrors
dot12InNullAddressedFrames
dot12OutHighPriorityFrames
dot12OutHighPriorityOctets
dot12TransitionIntoTrainings
dot12HCInHighPriorityOctets
dot12HCInNormPriorityOctets
dot12HCOutHighPriorityOctets

Counter vlan:

COUNTERVLAN
vlan_id
octets
ucastPkts
multicastPkts
broadcastPkts
discards

Counter processor (only in sFlow v5):

COUNTERPROCESSOR
cpu5s
cpu1m
cpu5m
memoryTotal
memoryFree 

$error

Reference to a list of error messages.

CAVEATS

The decode function will blindly attempt to decode the data you provide. There are some tests for the appropriate values at various places (where it is feasible to test - like enterprises, formats, versionnumbers, etc.), but in general the GIGO principle still stands: Garbage In / Garbage Out.

SEE ALSO

sFlow v4 http://www.ietf.org/rfc/rfc3176.txt

Format Diagram v4: http://jasinska.de/sFlow/sFlowV4FormatDiagram/

sFlow v5 http://sflow.org/sflow_version_5.txt

Format Diagram v5: http://jasinska.de/sFlow/sFlowV5FormatDiagram/

Math::BigInt http://search.cpan.org/~tels/Math-BigInt-1.77/lib/Math/BigInt.pm

AUTHOR

Elisa Jasinska <elisa.jasinska@ams-ix.net>

CONTACT

Please send comments or bug reports to <sflow@ams-ix.net>

COPYRIGHT

Copyright (c) 2006 AMS-IX B.V.

This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)