tsdump

#!/usr/bin/env python 
#
# Copyright (c) 2013, Arista Networks, Inc.
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are
# met:
#  - Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
#  - Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
#  - Neither the name of Arista Networks nor the names of its
# contributors may be used to endorse or promote products derived from
# this software without specific prior written permission.
# 
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ARISTA NETWORKS
# BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
# WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
# OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
# IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# Timestamp Dump
#
#    Version 3.2 16/03/2015
#    Written by: 
#       Matt Murray, Arista Networks
#       Andrei Dvornic, Arista Networks
#
#    Revision history:
#       1.0 - initial release
#       2.0 - skipped
#       3.0 - simplified decoding algorithm
#           - decode error vs. previous versions: max 150ns in 0.04% of cases
#       3.1 - cover all corner cases
#       3.2 - minor enhancements
#       3.3 - bug fixes

'''
   DESCRIPTION
      Timestamp Dump enables users to intercept and decode the
      timestamps applied by the Arista 7150 series switches.

   INSTALLATION
      Requirements: 
         - Python 2.6 or later: http://www.python.org/
         - dpkt: http://code.google.com/p/dpkt/

      In order to install Timestamp Dump, copy 'tsdump' to your
      filesystem.

      Then define the mapping between the device id (in the key
      frames) and the VLANs corresponding to the packets timestamped
      through that device in the highlighted section below (at the
      beginning of the script).

      Once the mapping is configured, the Timestamp Dump can then be
      started using:
      
         (bash:root)# <path-to-script>/tsdump [<options>] <intf>

   CONFIGURATION 
      The following options can be used in order to control the
      details generated by the script:

         -d, --delta           show delta between consecutive packets
         -p, --pcap-timestamps show pcap timestamps
         -r, --recover-utc     show UTC time
         -s, --src-ip          show source IP
         -t, --ticks           show hw timestamps as ticks

      The 'Notes' column can have one of the following values:
        - R:       rollover
        - KEY:     key frame
   
   COMPATIBILITY 
      Version 3.3 has been developed and tested using Python 2.7,
      but should work on any system supporting Python 2.6 or
      later. Please reach out to support@aristanetworks.com for
      assistance if needed.

   LIMITATIONS
      The tool tries to detect a counter rollover (by checking if a
      subsequent timestamp has a lower tick value than it
      predecessor). However, this mechanism does not uncover periods
      where the inter-timestamp delta is > 6.15s. This can result in
      undetected rollovers, if:

            6.15s < delta < (2 * 6.15 - previous timestamp)

      Multiple rollovers cannot be tracked and may go undetected.

      One or two keyframes in advance are required for decoding UTC in
      a packet. If they are not available, then decoding the
      timestamp in packets will not be performed.

      The decoder only works for timestamps which wer added before 
      the FCS.
         e.g.
         (config-if-Et<>): mac timestamp before-fcs
'''

vlanToDevId = {}
# ------------------------------------------------------------
# !!! INSERT VLAN->deviceId mapping below !!!
# ------------------------------------------------------------
# vlanToDevId[ <vlan> ] = <devId>
# e.g. 
#    VLAN10 timestamped through device 1
#    VLAN20 and VLAN30 timestamped through device 2
#
#    vlanToDevId[ 10 ] = 1
#    vlanToDevId[ 20 ] = 2
#    vlanToDevId[ 30 ] = 2
#
# If the inspected traffic is untagged and timestamped on a single 
# switch, you can use:
#
#    vlanToDevId[ '*' ] = <devId>
#
# e.g.
#    Untagged traffic timestamped through device 1
#
#    vlanToDevId[ '*' ] = 1
#-------------------------------------------------------------

import struct
import dpkt
import fcntl
import optparse
import os
import select
import socket
import subprocess
import sys

from datetime import datetime
from collections import namedtuple

Timestamp = namedtuple( 'Timestamp', 'pcapTs pcapDelta hwTicks '
                        'hwDelta utc utcDelta rollover' )
Pcap = namedtuple( 'Pcap', 'timestamp keyframe srcIp vlanOrDevId' )

KeyframeData = namedtuple( 'KeyframeData', 'asicTs utc' )
PacketData = namedtuple( 'PacketData', 'pcapTs hwTicks vlan srcIp' )

# Based on the clock rate (350Mhz)
TICK_LENGTH = 20.0/7.0
MAX_TICKS = 2**31 - 1

# { deviceId : <value> }
prevHwTicks = {}
prevPcapTime = {}
prevUtc = {}

#                    two kf in adv.       prev. kf.
# { <deviceId> : [ [ asicTime, utc ], [ asicTime, utc ] ] }
keyframes = {}

debug = None
def _trace( msg ):
   if debug:      
      print( msg )

class VLANEthernet( dpkt.ethernet.Ethernet ):
   __hdr__ = (
       ( 'dst', '6s', '' ),
       ( 'src', '6s', '' ),
       ( '__VLAN__', 'H', dpkt.ethernet.ETH_TYPE_8021Q ),
       ( 'vlan', 'H', 1 ),
       ( 'type', 'H', dpkt.ethernet.ETH_TYPE_IP )
       )
   _typesw = {}

def _untaggedTraffic():
   return len( vlanToDevId ) == 1 and '*' in vlanToDevId

def _devId( key ):
   if _untaggedTraffic():
      key = '*'
   return vlanToDevId[ key ]

def _printHeader():
   units = 'ticks'
   if not showTicks:
      units = 'ns'

   header = [ 'PCAP tstamp(s)'.rjust( 18 ) 
                 if showPcap else '',
              'PCAP delta(ns)'.rjust( 18 ) 
                 if showPcap and showDelta else '',
              'HW tstamp(%s)' % units.rjust( 18 ),
              'HW delta(%s)' % units.rjust( 18 ) 
                 if showDelta else '',
              'UTC(ns)'.rjust( 20 ) 
                 if showUTC else '',
              'UTC delta(ns)'.rjust( 15 ) 
                 if showUTC and showDelta else '',
              'UTC'.rjust( 30 ) 
                 if showUTC and showUTC else '',
              'Source IP'.rjust( 15 ) 
                 if showSourceIp else '',
              'VLAN/DeviceId(VLANs)'.rjust( 20 ),
              'Note'.rjust( 5 ) ]

   print( '%s' % ' '.join( header ) )

def _printTimestamp( pcap ):
   note = ''
   if pcap.timestamp.rollover:
      note = 'R'
   elif pcap.keyframe:
      note = 'KEY'

   utcString = datetime.utcfromtimestamp( 
                  pcap.timestamp.utc / 10.0**9 ).strftime( 
                  '%Y-%m-%d %H:%M:%S.%f' )

   if showTicks:
      hwString = '%d' % pcap.timestamp.hwTicks
      hwDeltaString = '%d' % pcap.timestamp.hwDelta
   else: 
      hwString = '%1.2f' % ( pcap.timestamp.hwTicks * TICK_LENGTH )
      hwDeltaString = '%1.2f' % ( pcap.timestamp.hwDelta * TICK_LENGTH )
      
   if pcap.keyframe:
      vlanOrDevIdString = '%d' % pcap.vlanOrDevId
      if not _untaggedTraffic():
         vlanOrDevIdString += '(%s)' % ( 
            ','.join( [ str( x ) 
                        for x in vlanToDevId 
                        if vlanToDevId[ x ] == pcap.vlanOrDevId ] ) )
      else:
         vlanOrDevIdString += '(untagged)'
   else:
      vlanOrDevIdString = 'VLAN%s' % pcap.vlanOrDevId \
                          if pcap.vlanOrDevId is not None \
                          else 'Untagged'

   row = [ ( '%1.6f' % pcap.timestamp.pcapTs
             if pcap.timestamp.pcapTs else '' ).rjust( 18 ) 
           if showPcap else '',
           ( '%1.6f' % pcap.timestamp.pcapDelta 
             if pcap.timestamp.pcapDelta else '' ).rjust( 18 ) 
           if showPcap and showDelta else '',
           hwString.rjust( 18 ),
           ( hwDeltaString if pcap.timestamp.hwDelta else '' ).rjust( 18 )
           if showDelta else '',
           ( '%d' % pcap.timestamp.utc 
             if pcap.timestamp.utc else '' ).rjust( 20 ) 
           if showUTC else '',
           ( ( '%1.0f' % pcap.timestamp.utcDelta 
               if pcap.timestamp.utcDelta else '' ) 
             if pcap.timestamp.utc else '' ).rjust( 15 ) 
           if showUTC  and showDelta else '',
           ( utcString if pcap.timestamp.utc else '' ).rjust( 30 ) 
              if showUTC else '',
           ( socket.inet_ntoa( pcap.srcIp ) 
             if pcap.srcIp else '' ).rjust( 15 ) 
           if showSourceIp else '',
           vlanOrDevIdString.rjust( 20 ),
           note.rjust( 5 ) ]

   print( ' '.join( row ) )

def _decodeValue( timestamp, keyframe ):
   if keyframe is None:
      return 0

   diff = timestamp - keyframe.asicTs
   if diff < 0:
      diff += MAX_TICKS
   return keyframe.utc + long( round( diff * TICK_LENGTH ) )

def _decodeTimestamp( pcapTs, hwTicks, devId ):
   kf = None
   prevKf = None

   kframes = len( keyframes[ devId ] )
   if kframes > 0:
      assert kframes < 3
      kf = keyframes[ devId ][ -1 ]
      if kframes == 2:
         prevKf = keyframes[ devId ][ 0 ]         

   k1 = kf[ 0 ] if kf else None
   utc = 0
   if k1:
      if k1 < hwTicks:
         if hwTicks - k1 > 2**31 / 2:
            utc = _decodeValue( hwTicks, prevKf )
         else:
            utc = _decodeValue( hwTicks, kf )
      elif k1 > hwTicks:
         if k1 - hwTicks < 2**31 / 2:
            utc = _decodeValue( hwTicks, prevKf )            
         else:
            utc = _decodeValue( hwTicks, kf )
      else:
         utc = kf.utc

   rollover = False
   hwDelta = 0
   pcapDelta = 0
   utcDelta = 0

   if devId in prevHwTicks:
      hwDelta = hwTicks - prevHwTicks[ devId ]
      if hwDelta < 0:
         hwDelta += MAX_TICKS
         rollover = True
   prevHwTicks[ devId ] = hwTicks

   if devId in prevPcapTime and prevPcapTime[ devId ]:
      pcapDelta = ( pcapTs - prevPcapTime[ devId ] ) * 10**9
   prevPcapTime[ devId ] = pcapTs

   if utc and devId in prevUtc and prevUtc[ devId ]:
      utcDelta = ( utc - prevUtc[ devId ] )
   prevUtc[ devId ] = utc

   return Timestamp( pcapTs, pcapDelta, hwTicks, hwDelta, 
                     utc, utcDelta, rollover )

tmpFilename = '.temp'
def _monitorIntf( intf ):
   for devId in set( vlanToDevId.values() ):
      keyframes[ devId ] = []

   p = subprocess.Popen( [ 'tcpdump', 
                           '-i', intf, 
                           '-U',                 # make stdout packet buffered
                           '-w', '-' ],          # redirect output to stdout
                         stdout=subprocess.PIPE,
                         stderr=subprocess.PIPE )
   fcntl.fcntl( p.stdout.fileno(), 
                fcntl.F_SETFL, 
                ( os.O_NDELAY | os.O_NONBLOCK ) )
   _printHeader()

   # In order to create a tcpdump header on every pass through the
   # loop, we simply use the output of the first pass as a prefix and
   # ignore the packets in it.
   tcpdumpHeader = ''
   ignorePackets = 0

   while True:
      _trace( 'Reading tcpdump...' )

      readReady, _, _ = select.select( [ p.stdout.fileno() ], [], [], 1 )
      if not len( readReady ):
         _trace( 'Nothing to read...' )
         continue

      f = open( tmpFilename, 'w' )
      contents = p.stdout.read()
      f.write( '%s%s' % ( tcpdumpHeader, contents ) )
      f.close()

      if not tcpdumpHeader:
         tcpdumpHeader = contents

      pcapInfo = None
      f = open( tmpFilename )
      pcapInfo = [ x for x in dpkt.pcap.Reader( f ) ]
      f.close()

      _trace( 'Reading packets...' )
      for pcapEntry in pcapInfo:
         pcapTs, buf = pcapEntry
         if not buf:
            continue

         eth = dpkt.ethernet.Ethernet( buf )
         if( hasattr( eth, 'ip' ) and 
             eth.ip.p == 253 and eth.ip.ttl == 64 ):
            _trace( 'Reading keyframe...' )

            (asicTs, utc, deviceId) = \
                struct.unpack('>2Q%ixH4x' % ( len( eth.ip.data ) - 22 ), 
                              eth.ip.data)

            if deviceId not in keyframes:
               sys.exit( 'ERROR: Keyframe from device %d '
                         'seen in the capture, but '
                         'device not configured in the '
                         'VLAN->deviceId mapping! ' %
                         deviceId )

            if len( keyframes[ deviceId ] ) == 2:
               keyframes[ deviceId ] = keyframes[ deviceId ][ 1: ]
               
            hwTicks = asicTs & 0x7FFFFFFF
            keyframes[ deviceId ].append( KeyframeData( hwTicks, utc ) )
               
            _printTimestamp( 
               Pcap( Timestamp( pcapTs=pcapTs, 
                                pcapDelta=0,  
                                hwTicks=hwTicks, 
                                hwDelta=0, 
                                utc=utc, 
                                utcDelta=0, 
                                rollover=False ), 
                     keyframe=True, 
                     srcIp=eth.ip.src, 
                     vlanOrDevId=deviceId ) )
         else:
            _trace( 'Reading data packet...' )            

            vlan = None
            if not _untaggedTraffic():
               # Ignore packets which don't belong to the configured VLANs
               try:
                  vlan = VLANEthernet( buf ).vlan
               except Exception:
                  continue

               if vlan not in vlanToDevId:
                  _trace( 'Skipping packet because VLAN %s not configured in '
                          'VLAN->deviceId mapping!' % vlan )
                  continue

            (stamp,) = struct.unpack('>L', buf[ -4 : ])

            hwTicks = ( ( stamp & 0xffffff00 ) >> 1 ) | ( stamp & 0x7f )
            devId = _devId( vlan )
            ts =  _decodeTimestamp( pcapTs, hwTicks, devId )

            _printTimestamp( 
               Pcap( timestamp=ts, 
                     keyframe=False, 
                     srcIp=eth.ip.src if hasattr( eth, 'ip' ) else None, 
                     vlanOrDevId=vlan ) )

      if not ignorePackets:
         ignorePackets = len( pcapInfo )

showPcap = None 
showUTC = None 
showTicks = None 
showDelta = None 
showSourceIp = None
def main():
   global debug, showPcap, showUTC, showTicks, showDelta, showSourceIp

   # Create help string and parse cmd line
   usage = 'usage: %prog [options] <interface>'
   op = optparse.OptionParser(usage=usage)
   op.add_option( '-d', '--delta', dest='delta', 
                  action='store_true', help='show delta between consecutive '
                                            'packets in UTC decode details' )
   op.add_option( '-p', '--pcap-timestamps', dest='pcap', 
                  action='store_true', 
                  help='show pcap timestamps in UTC decode details' )
   op.add_option( '-r', '--recover-utc', dest='utc', 
                  action='store_true', 
                  help='show UTC time in UTC decode details' )
   op.add_option( '-s', '--src-ip', dest='src', 
                  action='store_true', 
                  help='show source IP in UTC decode details' )
   op.add_option( '-t', '--ticks', dest='ticks', 
                  action='store_true', 
                  help='show hw timestamps as ticks in UTC decode details' )
   op.add_option( '-v', '--verbose', dest='verbose', 
                  action='store_true', help='show debug info' )
   
   opts, arguments = op.parse_args()

   if not vlanToDevId:
      sys.exit( 'ERROR: Please configure the deviceId->VLAN mapping at the '
                'top of the script!' )
 
   # Check cmd line options
   if not arguments:
      op.error( 'You need to specify an interface to monitor.' )
   if len( arguments ) > 1:
      op.error( 'Too many input arguments.' )

   debug = opts.verbose
   showPcap = opts.pcap
   showUTC = opts.utc
   showTicks = opts.ticks
   showDelta = opts.delta
   showSourceIp = opts.src

   try:
      _monitorIntf( arguments[ 0 ] )
   except KeyboardInterrupt:
      os.remove( tmpFilename )

if __name__ == '__main__':
   main()