Elisa Jasinska

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)

1 POD Error

The following errors were encountered while parsing the POD:

Around line 2176:

=over should be: '=over' or '=over positive_number'

You can't have =items (as at line 2195) unless the first thing after the =over is an =item