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;
  # now we actually call the Net::sFlow::decode() function
  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 (@{$sFlowSamplesRef}) {
    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().

For more examples have a look into the 'examples' directory.

FUNCTIONS

decode()

($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

$datagram

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 sFlow version and type of hardware where the data comes from (router, switch, etc.), 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
            
          

If the sample is a Foundry ACL based sample (enterprise == 1991 and format == 1) you will receive the following information:

            

              
              
FoundryFlags
FoundryGroupID
            
          

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 the hardware you can get the following additional keys:

Header data (sFlow format):

            

              
              
HEADERDATA
HeaderProtocol
HeaderFrameLength
HeaderStrippedLength
HeaderSizeByte
HeaderSizeBit
HeaderBin
            
          

Additional Header data decoded from the raw packet header:

            

              
              
HeaderEtherSrcMac
HeaderEtherDestMac
HeaderType (ether type)
HeaderDatalen (of the whole packet including ethernet header)
            
          

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
MplsTunnelNameLength
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
ifInOctets
ifInUcastPkts
ifInMulticastPkts
ifInBroadcastPkts
ifInDiscards
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 lag:

            

              
              
COUNTERLAG
dot3adAggPortActorSystemID
dot3adAggPortPartnerOperSystemID
dot3adAggPortAttachedAggID
dot3adAggPortActorAdminState
dot3adAggPortActorOperState
dot3adAggPortPartnerAdminState
dot3adAggPortPartnerOperState
dot3adAggPortStatsLACPDUsRx
dot3adAggPortStatsMarkerPDUsRx
dot3adAggPortStatsMarkerResponsePDUsRx
dot3adAggPortStatsUnknownRx
dot3adAggPortStatsIllegalRx
dot3adAggPortStatsLACPDUsTx
dot3adAggPortStatsMarkerPDUsTx
dot3adAggPortStatsMarkerResponsePDUsTx
            
          

Counter processor (only in sFlow v5):

            

              
              
COUNTERPROCESSOR
cpu5s
cpu1m
cpu5m
memoryTotal
memoryFree
            
          

Counter HTTP:

            

              
              
COUNTERHTTP
methodOptionCount
methodGetCount
methodHeadCount
methodPostCount
methodPutCount
methodDeleteCount
methodTraceCount
methodConnectCount
methodOtherCount
status1xxCount
status2xxCount
status3xxCount
status4xxCount
status5xxCount
statusOtherCount
            
          

$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

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

Math::BigInt

AUTHOR

Elisa Jasinska <elisa@bigwaveit.org>

CONTACT

Please send comments or bug reports to <elisa@bigwaveit.org> and/or <sflow@ams-ix.net>

COPYRIGHT

Copyright (c) 2006 - 2015 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)