 









 Digital Trace Facility (DTF)
 Version V1.1



 Abstract

 DTF is a utility which traces packets as they traverse through the pro-
 tocol layers within a router. DTF is a superset of Digital's CTF (Com-
 mon Trace Facility), supporting multiple platforms and TCP/IP networks.

 

 September 1995

 The information in this document is subject to change without notice
 and should not be construed as a commitment by Digital Equipment Cor-
 poration. Digital Equipment Corporation assumes no responsibility for
 any errors that may appear in this document.

 The software described in this document is furnished under a license
 and may be used or copied only in accordance with the terms of such
 license.

 No responsibility is assumed for the use or reliability of software
 on equipment that is not supplied by Digital Equipment Corporation or
 its affiliated companies.

 Restricted Rights: Use, duplication, or disclosure by the U.S. Gov-
 ernment is subject to restrictions as set forth in subparagraph (c)(1)(ii)
 of the Rights in Technical Data and Computer Software clause at DFARS
 252.227-7013.

 Digital Equipment Corporation 1995.

 All Rights Reserved.

 The following are trademarks of Digital Equipment Corporation: DBMS,
 DECdfs, DECdns, DECnet, Digital, OpenVMS, PATHWORKS, Rdb/VMS ULTRIX,
 VAX, VAX-11 RSX, VAX DOCUMENT, VMS, VMScluster, VMS POSIX, and the DIGITAL logo.
























 Digital Equipment Corporation
 Maynard, Massachusetts


 ii

 


                               CONTENTS

     1 What is DTF ?............................................    1

     2 Tracepoints..............................................    2

      2.1 Example Tracepoints...................................    2

      2.2 Events................................................    3

     3 Installation and Platform Differences....................    4

      3.1 OpenVMS and OpenVMS AXP...............................    4

       3.1.1 Installation.......................................    4

       3.1.2 Command Line Interface.............................    5

       3.1.3 Restrictions.......................................    6

      3.2 Digital UNIX, ULTRIX and Linux........................    7

      3.3 Windows NT............................................    7

       3.3.1 Restrictions.......................................    8

     4 Common Command Line Interface and Configuration..........    9

      4.1 Example Command Lines.................................   12

      4.2 Supplying Node Names and Addresses....................   13

      4.3 Output Coloring.......................................   14

     5 What Does The Output Mean ?..............................   16

      5.1 Brief Mode............................................   16

      5.2 Verbose Mode..........................................   17

     6 Release Notes............................................   19

      6.1 V1.1..................................................   19

  Appendix A  COMPATIBILITY WITH CTF............................   21

  Appendix B  REGULAR EXPRESSION SYNTAX.........................   23

      B.0.1 AMBIGUITY...........................................   23

  TABLES

    1     OpenVMS File List.....................................    5

    2     VMS Command Line Syntax...............................    6

    3     ULTRIX, OSF and Linux File List.......................    7

    4     Windows NT File List..................................    8

    5     Unix Command Line Parameters..........................    9

    6     Unix Command Line Options.............................    9

    7     Supported Colors......................................   14

    8     Default Coloring......................................   15

                                                                  iii

 

 1  What is DTF ?

 DTF is a host based facility which allows the tracing of packets as
 they traverse through the protocol layers within a DTF capable router.
 The packets can be analysed "live" as they are processed by each router
 software module, or they can be recorded in a data file and analysed
 later.

 DTF can be used in either DECnet or TCP/IP networks and supports the
 following host platforms:

 o  Digital UNIX Alpha (formerly called DEC OSF/1)

 o  ULTRIX V4.3

 o  Linux V1.2.8

 o  OpenVMS VAX V6.0

 o  OpenVMS Alpha V6.1

 o  Windows NT 3.5

 DTF supports the following routers:

 o  DECNIS 500/600 (Software version V3.1 or later required for TCP ac-
    cess).

 o  DEC WANRouter 90

    There is a bug in versions V1.3.2 and earlier of the WANrouter soft-
    ware, such that only a capture size of 188 and a buffer size of 512
    are garaunteed to work (other sizes may or may not work). Since by
    default DTF uses larger sizes than these, you will need to set the
    capture and buffer size explicitly when tracing a WANrouter 90.




















                                                                   1

 

 2  Tracepoints

 The points within a router which can be traced are known as Tracepoints.
 Each protocol module within the router may have 0 or more tracepoints,
 for example, the PPP data link module may have a tracepoint for each
 link. A tracepoint is either active or inactive. Whenever a packet passes
 through an active tracepoint it is traced. The tracepoints specified
 by a user are activated when DTF connects to the router, and de-activated
 when DTF disconnects from the router.

 Tracepoints are named according to a class/instance scheme. The gen-
 eral form of a tracepoint name is:

    class [instance] [ [sub-class instance]...]

 where:

 o  class is the node class. Typically this is the name of the proto-
    col module, for example, ROUTING, PPP, MODEM_CONNECT

 o  sub-class is a specific subclass of the node class (typically this
    might be a LINE or CIRCUIT)

 o  instance is the entity instance name that uniquely identifies the
    particular tracepoint from others in the same sub-class. The node
    class may have a null instance name but each sub-class must be fol-
    lowed by a sub-class instance name.

 For example, to trace the packets passing through the ROUTING module
 on the interface named interface-0, the tracepoint would be named:

    class     = ROUTING
    sub-class = CIRCUIT
    instance  = Interface-0

 That is, ROUTING CIRCUIT Interface-0

 The instance name can contain the wildcard character *, which will cause
 any tracepoint with a matching instance name to be traced. All known
 tracepoints for the sub-class can be traced by specifying a single *
 as the instance name. The class and sub-class names can be abbrevi-
 ated; DTF will take the first matching valid name it finds.

 The tracepoints are defined in the DTF_TRACEPOINTS.DAT file. Note that
 this filename may be different on other platforms.

 2.1  Example Tracepoints

 The following are some example tracepoints. The wildcard forms are shown
 but you could substitute a specific tracepoint name for the * char-
 acter.




 2

 


 ___________________________________________________________________

 ROUTING CIRCUIT *        Trace all the routing circuits on the router

 PPP LINK *               Trace all the PPP links on the router

 NSP PORT *               Trace all the NSP Ports on the router. Since
                          NSP ports are created dynamically when an NSP
                          connection is created these tracepoints may
                          appear after the DTF trace session has started
 _________________________and_may_be_deleted_during_the_session.____

 2.2  Events

 Each tracepoint defines a number of events (up to 64) and each packet
 traced is marked with one of these events by the router. When DTF ini-
 tially connects to the router it can optionally instruct the router
 to filter the packets passing through the specified tracepoint and only
 trace the ones which match the specified events list. Typically a tra-
 cepoint would define an event for a transmitted packet and another for
 a received packet; but it may also define events for particular packet
 types (e.g. the "ROUTING CIRCUIT *" tracepoint has a unique event for
 OSPF, ARP, OSI and RIP packets).

 The events for each tracepoint are defined in the DTF_EVENTS.xxx files
 (where xxx is the id of the router, by default an id of 000 is assumed).
 Note that this filename may be different on other platforms. All the
 events files (including the router identifier to name mapping file DTF_
 EVENTS.DAT) must be in the same directory.

























                                                                   3

 

 3  Installation and Platform Differences

 This section documents the installation procedure for DTF on each plat-
 form, and also any platform specific differences. This section assumes
 some knowledge of the platform on which the software is to be installed.

 3.1  OpenVMS and OpenVMS AXP

 3.1.1  Installation

 DTF is supplied as a saveset (DTFVMS.A for OpenVMS VAX and DTFAXP.A
 for OpenVMS Alpha). This saveset contains the files described in the
 table below. The OpenVMS kit supplies a CLD file which provides a stan-
 dard DCL style command line interface to DTF. The common UNIX style
 interface can still be accessed by supplying the /UNIX qualifier im-
 mediately after the DTF command, as follows:

    $ DTF/UNIX unix-command-line





































 4

 

 ___________________________________________________________________

 Table_1:_OpenVMS_File_List_________________________________________

 Filename______________Location__________Description________________

 DTF.EXE               SYS$SYSTEM        DTF image, activated by the
                                         DCL DTF command. You may place
                                         this file in another direc-
                                         tory, provided that you de-
                                         fine the DTF logical to point
                                         to it.

 DTF.CLD               SYS$SYSTEM        DTF CLI definition.

 DTF_TRACEPOINTS.DAT   SYS$LIBRARY       Tracepoints file, containing
                                         the list of supported trace-
                                         point names. You may place this
                                         file in another directory pro-
                                         vided that you define the DTF_
                                         TRACEPOINTS logical to point
                                         to it.

 DTF_EVENTS.DAT        SYS$LIBRARY       Events file, contains the map-
                                         ping between router identfiers
                                         and names. You may place this
                                         file in another directory pro-
                                         vided that you define the DTF_
                                         EVENTS logical to point to it.

 DTF_EVENTS.000        SYS$LIBRARY       Events file, contains the list
                                         of supported events for each
                                         tracepoint for the DECNIS and
                                         WANrouter 90 routers (router
                                         identifier 000). You may place
                                         this file in another direc-
                                         tory provided that you define
                                         the DTF_EVENTS_000 logical to
                                         point to it, otherwise this
                                         file must reside in the same
                                         directory as the DTF_EVENTS.DAT
                                         file.

 DTF.TXT_______________SYS$HELP__________DTF_User_Guide.____________

                                NOTE

   DTF can be installed in a private directory (rather than system
   wide), provided that the DTF, DTF_TRACEPOINTS and DTF_EVENTS log-
   icals are defined to point to the corresponding EXE and DAT files.

 3.1.2  Command Line Interface

 The DCL command line interface to DTF maps the internal Unix style op-
 tions to command line qualifiers and parameters. The following table
 describes the mapping. See section Section 4 for a description of the
 corresponding UNIX options.

 The general format for a 'live' trace is:

    $ DTF/LIVE [qualifiers] node-name"username password"::"tracepoint"

                                                                   5

 

 and for an analysis of a pre-recorded data file:

    $ DTF/ANALYZE [qualifiers] [data-file]

 and for pipe mode:

    $ DTF/PIPE/TYPE=packet-type ["hex-string" | /INPUT=input-file]

 ___________________________________________________________________

 Table_2:_VMS_Command_Line_Syntax___________________________________

 VMS________________________Corresponding_Option____________________

 /UNIX                      Rest of the line is in internal Unix for-
                            mat.

 /ANALYZE                   -a

 /BACKWARDS                 -B

 /BUFFER=number             -b

 /CAPTURE=size              -c

 /{NO}COLORING              -C

 /DATA={ASCII|HEX} (D=HEX)  -z

 /EXCLUDE="regexp"          -x

 /FILTER="filter-list"      -f

 /FULL                      -v

 /{NO}HEADERS               -H

 /{NO}HIGHLIGHT             -D

 /INPUT=input-file          -I

 /LIVE                      -l

 /MAXIMUM_BUFFERS=number    -m

 /NARROW                    -N

 /OUTPUT=file               -o

 /PAGE=number (D=0)         -w

 /PIPE                      -P

 /RAW                       -r

 /RECORD=file               data-file parameter

 /SEARCH="regexp"           -s

 /TYPE=packet-type          -T

 /TRANSLATE_________________-t______________________________________

 3.1.3  Restrictions

 The following restrictions apply to the OpenVMS version of DTF:

 1. Translation of DECnet addresses to node names is not supported.

 6

 

 3.2  Digital UNIX, ULTRIX and Linux

 DTF is supplied as a tar file, DTFULTRIX.TAR, DTFOSF.TAR or DTFLINUX.TAR,
 which contains the files described in the table below.

 ___________________________________________________________________

 Table_3:_ULTRIX,_OSF_and_Linux_File_List___________________________

 Filename______________Location__________Description________________

 dtf                   /usr/dtf/         DTF image

 dtf_tracepoints.dat   /usr/dtf/         Tracepoints file, contains the
                                         list of supported tracepoint
                                         names. You may place this file
                                         in another directory provided
                                         that you define the DTF_TRACEPOINTS
                                         environment variable to point
                                         to it.

 dtf_events.dat        /usr/dtf/         Events file, contains the map-
                                         ping between router identfiers
                                         and names. You may place this
                                         file in another directory pro-
                                         vided that you define the DTF_
                                         EVENTS environment variable
                                         to point to it.

 dtf_events.000        /usr/dtf/         Events file, contains the list
                                         of supported events for each
                                         tracepoint for the DECNIS and
                                         WANrouter 90 routers (router
                                         identifier 000). You may place
                                         this file in another direc-
                                         tory provided that you define
                                         the DTF_EVENTS_000 environ-
                                         ment variable to point to it,
                                         otherwise this file must re-
                                         side in the same directory as
                                         the dtf_events.dat file.

 dtf.txt_______________/usr/dtf/_________DTF_User_Guide.____________

                                NOTE

   DTF can be installed in a private directory (rather than system
   wide) provided that the DTF_TRACEPOINTS and DTF_EVENTS environ-
   ment variables are defined to point to the corresponding DAT files.

 3.3  Windows NT

 DTF is supplied as a ZIP file, DTFW32.ZIP, which contains the files
 described in the table below. DTF runs as a console application on Win-
 dows NT.

                                                                   7

 

 ___________________________________________________________________

 Table_4:_Windows_NT_File_List______________________________________

 Filename______________Location__________Description________________

 dtf                   current           DTF image

 dtftrace.dat          current           Tracepoints file, containing
                                         the list of supported trace-
                                         point names. You may place this
                                         file in another directory pro-
                                         vided that you define the DTF_
                                         TRACEPOINTS environment vari-
                                         able to point to it.

 dtfevent.dat          current           Events file, contains the map-
                                         ping between router identfiers
                                         and names. You may place this
                                         file in another directory pro-
                                         vided that you define the DTF_
                                         EVENTS environment variable
                                         to point to it.

 dtfevent.000          current           Events file, contains the list
                                         of supported events for each
                                         tracepoint for the DECNIS and
                                         WANrouter 90 routers (router
                                         identifier 000). You may place
                                         this file in another direc-
                                         tory provided that you define
                                         the DTF_EVENTS_000 environ-
                                         ment variable to point to it,
                                         otherwise this file must re-
                                         side in the same directory as
                                         the dtfevent.dat file.

 dtf.txt_______________current___________DTF_User_Guide.____________

 3.3.1  Restrictions

 The following restrictions apply to the Windows NT platform version
 of DTF:

 1. DECnet access is not supported. The DTF connection must be made us-
    ing TCP/IP.

 2. Translation of DECnet addresses to node names is not supported.

 3. Highlighting and coloring are not supported.





 8

 

 4  Common Command Line Interface and Configuration

 DTF uses an UNIX style command line interface internally. For the Dig-
 ital UNIX (OSF), ULTRIX and Windows NT platforms, this is also the in-
 terface which is presented to the user. For OpenVMS, the user is pre-
 sented with a DCL command line interface. This section documents the
 UNIX command line interface.

 DTF performs two main functions:

 o  Analysis of trace data. This function analyses the data from ei-
    ther the 'live' system or from a previously recorded data file.

 o  Recording of trace data. This function saves the trace data in a
    file so that it can be analysed later.

 These functions can be performed simultaneously.

 The format for the command line changes depending on whether the source
 of the trace is a router or a previously recorded data file. When the
 source is the router the format is:

    dtf [options] nodename[/username/password]:[:]"tracepoint" [data-file]

 When the source is a data file the format is:

    dtf -a [options] [data-file]

 When the source is an input file or a pipe, the format is:

    dtf -P -T"packet-type" [options] ["hex-string" | -I"input-file"]

 ___________________________________________________________________

 Table_5:_Unix_Command_Line_Parameters______________________________

 Parameter________Default___________Description_____________________

 nodename                           Nodename or address of the router
                                    including username/password access
                                    control and the tracepoint name.
                                    The format is described in Section 4.2.
                                    Not required when analysing a data
                                    file.

 data-file        dtf.dat           Name of the file in which to record
                                    the trace data. This parameter is
                                    optional when analysing a 'live'
                                    system, so if it is not supplied,
 ___________________________________then_the_trace_data_will_not_be_recorded.

 ___________________________________________________________________

 Table_6:_Unix_Command_Line_Options_________________________________

 Option_Parameter_________Description_______________________________

 -a                       Analyse data file. The data file name is sup-
                          plied as the first parameter.

                                                                   9

 


 ___________________________________________________________________

 Option_Parameter_________Description_______________________________

 -b     size              Buffer size the router is to use for its trace
                          buffers. The default is 1569

 -c     size              Capture size the router is to use. This is
                          the number of bytes in each packet which should
                          be traced. The buffer size (-b option) will
                          be adjusted accordingly. The default is 1500.

 -f     "f1 f2 f3..."     Filter list. This is a space (or comma) sep-
                          arated list of the filters to apply. By de-
                          fault, no filters are applied and so all pack-
                          ets passing through the tracepoint are traced.
                          Filter names may be abbreviated; DTF will take
                          the first matching filter name it finds in
                          the Events file.

 -h                       output brief help information.

 -l                       Live tracing. This option causes the trace
                          data to be analysed and displayed as it is
                          received. This option and the -a option are
                          mutually exclusive.

 -m     size              Maximum number of trace buffers the router
                          should allocate. The default is 5.

 -o     file              Output filename. The default is to display
                          the analysed data to stdout.

 -r                       Raw data mode. The output data isn't format-
                          ted when this option is supplied.

 -s     regexp            Regular expression match. Only if the out-
                          put data matches the regexp is it displayed;
                          otherwise the trace output is discarded.

 -t                       Translate addresses. Any IP or DECnet addresses
                          in the output data will be translated to node
                          names before being displayed.

 -v                       Verbose mode. When supplied, the packet is
                          analysed fully and a detailed output produced.
                          When absent, the output is brief and restricted
                          to a single line for each packet.

 -w     number            Wait mode. Causes the output to pause between
                          packets (and prompt the user for a <RET> be-
                          fore continuing). In brief mode, the param-
                          eter specifies the number of lines to be out-
                          put before the prompt is issued; in verbose
                          mode the parameter is ignored and the prompt
                          is issued after every packet. Supplying a value
                          of 0 in brief mode is equivalent to supply-
                          ing a value of 22.

 10

 


 ___________________________________________________________________

 Option_Parameter_________Description_______________________________

 -x     regexp            Regular expression no-match. Only if the out-
                          put data fails to match the regexp is it dis-
                          played; otherwise the trace output is dis-
                          carded. This option and the -s option act in
                          conjunction, so if both are supplied then the
                          output is only displayed if the -s regular
                          expression matches AND the -x regular expres-
                          sion fails.

 -z                       Print undecoded data as ASCII rather than hex.

 -B                       The data from the input stream is presented
                          backwards (i.e. the last byte in the packet
                          is first and the first byte in the packet is
                          last). (Pipe mode only)

 -C                       Suppresses coloring of output. If coloring
                          is suppressed then the output (some portions
                          of the output which would otherwise have been
                          coloured) will be bolded. Use this option if
                          your terminal does not support ANSI colors
                          since that will cause the headers to be high-
                          lighted instead. Colors can be modified us-
                          ing the DTF_COLORS environment variable.

 -D                       Suppresses highlighting and coloring of out-
                          put.

 -H                       Suppresses the DTF headers on output.

 -I     input-file        Source of the hex string data is the input-
                          file. The data is stored as hex strings in
                          the input-file. (Pipe mode only)

 -N                       Output is in narrow form. The default is wide
                          which assumes a 132 column output display.

 -P                       Pipe mode. In this mode the data is presented
                          as hex strings, either as the first param-
                          eter on the command line or in the input-file
                          (see -I switch). End of packet is denoted by
                          the end of the file or a newline. Packets may
                          be continued onto another line by specify-
                          ing a '






                                                                  11

 


 ___________________________________________________________________

 Option_Parameter_________Description_______________________________

 -T     packet-type       The type of packet presented in the hex data
                          string. The type name can be abbreviated; DTF
                          will take the first matching type it finds
                          (the valid types are searched alphabetically).
                          The following types are supported:

                             ARP
                             ASN1
                             BRIDGE
                             CMIP
                             CSMA-CD
                             DDCMP
                             FDDI
                             HDLC
                             ICMP
                             IP
                             IPX
                             LAPB
                             LAPBE
                             MOP
                             NSP
                             OSI
                             OSPF
                             PPP
                             PhaseIV
                             RIP
                             SNMP
                             TCP
                             UDP
                             X25L3

 _________________________(Pipe_mode_only)__________________________

 4.1  Example Command Lines

 The following are example command lines and their use:

 o  dtf -l nis100:"routing circuit *"

    Trace all Routing circuits on node NIS100 (use TCP as the trans-
    port protocol), analyse the data (in brief mode) as it arrives and
    display it on the standard output device.

 o  dtf -l -f"ospfTx,ospfRx" nis100:"routing circuit *"

    As above, but now apply a filter set which excludes all packets ex-
    cept transmitted and received OSPF packets.

 o  dtf -l -f"ospftx,ospfrx" nis100/x/y:"routing circuit *" ospf.dat

    As above, but now supply a username and password of x and y and also
    record the trace records to a file called ospf.dat.

 o  dtf -lvw0 -o output.txt 1.100::"ppp link l601-8-0"

 12

 

    Trace all PPP links on node 1.100 (use DECnet as the transport pro-
    tocol), analyse the data (in verbose mode) as it arrives and write
    it to the file output.txt.

 o  dtf nis100:"ppp link *" ppp.dat

    Trace all PPP links on node NIS100 (use TCP as the transport pro-
    tocol), and record the data in the file ppp.dat.

 o  dtf -avtw0 ppp.dat

    Analyse the data in the previously recorded ppp.dat file, use ver-
    bose format output, translate addresses to names and pause between
    every 22 lines of output.

 o  dtf -a

    Analyse the data in the previously recorded dtf.dat file, use brief
    format output.

 o  dtf -a -s"BGP:"

    As above, but now filter the output such that only packets contain-
    ing the string "BGP:" are displayed.

 o  dtf -a -s"BGP:" -x"KEEPALIVE"

    As above, but now filter the output further to exclude packets which
    contain the string KEEPALIVE.

 o  dtf -P -T"ip" "45C0005400170000"

    Pipe mode. The supplied hex string is decoded as an IP packet.

 o  dtf -P -T"ip" -I"in.txt"

    As above, but now the hex strings are contained in the file in.txt.

 4.2  Supplying Node Names and Addresses

 The format of the router node name supplied determines which trans-
 port protocol is used to connect to the router, what the username and
 password is and also the tracepoint to be traced. The general format
 is shown below ...

    node[/username/password]:[:]"tracepoint"

 When an address is supplied (DECnet or IP) DTF determines from the num-
 ber of dots (.) present whether to use DECnet or TCP. When a node name
 is supplied, DTF uses TCP by default if the name is followed by a sin-
 gle colon character, and DECnet if the name is followed by a double
 colon.

 For example, the following formats will cause the connection to be made
 via DECnet.

    1.100
    nis100::

                                                                  13

 

 and the following will cause the connection to be made via TCP.

    16.36.16.100
    nis100.reo.dec.com
    nis100:
    nis100

 The following example shows a complete nodename specifier for trac-
 ing the tracepoint "ROUTING CIRCUIT *" on node nis100 using TCP as the
 transport protocol.

    nis100:"routing circuit *"

 The next example is the same as the one above but this time and user-
 name and password are supplied and the transport used is DENCET.

    nis100/me/hushhush::"routing circuit *"

 4.3  Output Coloring

 On terminals which support ANSI color escape sequences, DTF will color
 various fields in the output. The supported colors (and highlighting
 options) are listed in the table below.

 ___________________________________________________________________

 Table_7:_Supported_Colors__________________________________________

 Color_(Option)___ANSI_value________________________________________

 Default          0

 Bold             1

 Underline        4

 Flashing         5

 Reverse          7

 Black            30

 Red              31

 Green            32

 Yellow           33

 Blue             34

 Purple           35

 Cyan             36

 White____________37________________________________________________

 The DTF output can be grouped into named fields, each field can have
 a different color associated with it. The following table describes
 the output field names and the default color used for that field.

 14

 

 ___________________________________________________________________

 Table_8:_Default_Coloring__________________________________________

 Field_________________Default______Description_____________________

 Headers               Green        The DTF header, from the -DTF- pre-
                                    fix through to the underline.

 Protocol-headers      Cyan         The protocol section headers.

 Search-strings        Reverse      Highlighted search strings.

 Comments              Green        Comments (used in PIPE mode).

 Tx-events             Normal       The body of the output for all event
                                    names which end with the tx string,
                                    e.g. OspfTx.

 Rx-events             Normal       The body of the output for all event
                                    names which end with the rx string,
                                    e.g. OspfRx.

 Strings               Normal       The body of the output which does
 ___________________________________not_come_under_any_of_the_above_catagories.

 The colors can be modified by defining the DTF_COLORS environment vari-
 able. The variable is defined to be a string of the form...

    "field1=foreground-color;background-color;option1;option2,field2=..."

 where field is one of the field names described in Table 8 and foreground-
 color,background-color,option1,option2 are; one of the color or op-
 tion names defined in Table 7; or the numerical ANSI value for the color
 or option. Only the foreground color need be defined, the others can
 be omitted. The example below shows the string required to color all
 rx events in white and to remove the coloring of protocol headers.

    "rx-events=white,protocol=0"

 Both the field and color names may be abbreviated.














                                                                  15

 

 5  What Does The Output Mean ?

 DTF uses two forms of output, brief and verbose.

 o  Brief mode uses a single line for each traced packet and displays
    a minimum amount of information about each.

 o  Verbose mode uses multiple lines for each traced packet and for-
    mats all the fields.

 5.1  Brief Mode

 The following is an example of the brief mode output. This output was
 generated using the following command line:

    dtf -lw0 -c188 nis100:"routing circuit *"

     09:30:51.75|  41|      Rx|PIV LAN Router Hello AA-00-04-00-BF-04
     09:30:51.75|  33|      Rx|PIV LAN End Node Hello AA-00-04-00-1B-04
     09:30:51.76|1492|      Rx|OSI L1 LAN hello 08-00-2B-B2-0A-30
     09:30:51.79|1492|      Rx|OSI L1 LAN hello 08-00-2B-A1-0E-90
     09:30:51.80|1492|      Rx|OSI L2 LAN hello 08-00-2B-A1-0E-90
     09:30:51.83|  47|    ipRx|IP 16.36.16.118 224.0.0.2 UDP vrc vrc
     09:30:51.88|1492|      Rx|OSI L1 LAN hello 08-00-2B-20-08-20
     09:30:51.94|  64|  ospfRx|IP 16.39.64.102 224.0.0.5 OSPF HELLO 192.208.32.102 16.39.64.102

 The output shows eight packets which passed through the tracepoints
 in the Routing Circuits on node NIS100. Each trace record is times-
 tamped (by the router) and lists the filter name applied to the trace
 record by the router (this name can be used in a filter list to re-
 strict the traced packets). The fields for the eighth packet are de-
 scribed in detail below.

 09:30:51.94|     Timestamp applied to the trace record by the router.

 64|              Original size of the packet in bytes. Note that the ac-
                  tual number of bytes captured may be less than this de-
                  pending on the capture size in use. The command specified
                  a capture size of 188 bytes, so we know that all of this
                  packet was captured. However, the third packet had an orig-
                  inal size of 1492 of which we would only have captured 188
                  bytes.

 ospfRx|          Filter name. This particular packet has been tagged with
                  the "ospfRx" filter.

 IP ...           Body of the packet. This particular packet is an OSPF HELLO
                  packet, sent with a source IP address of 16.39.64.102 to
                  the multicast address 224.0.0.5; the router-id was 16.39.64.102
                  and the Designated router was 192.208.32.102





 16

 

 5.2  Verbose Mode

 The following is an example of the verbose mode output. This output
 was generated using the command line:

    dtf -NDlvw0 -f"ospftx" nis100:"routing circuit *"

    -DTF- ospfTx         84 of 84   at  09:53:03.46          L601-8-0        3
          Status: 8063DAE0         Context: 00000002        Function: 8000B685
          --------------------------------------------------------------------

          routing context: IP
          -------------------

          IP: Common
          ----------
          type of service               0xC0
          total length                  84
          packet identifier             0x002D
          time to live                  1
          Source Address                16.36.16.100
          Destination Address           224.0.0.5

          IP protocol: OSPF
          -----------------
          Version                       V2
          Packet Length                 64
          Router ID                     16.36.16.100
          Area ID                       1.1.1.1
          Checksum                      0xF406
          Authentication type           None
          Authentication                0x0000000000000000

          OSPF type: HELLO
          ----------------
          Options                       0x02 E
          Designated router             16.36.16.118
          Backup router                 16.36.16.223
          Network mask                  255.255.255.0
          Hello interval                10
          Router priority               1
          Dead interval                 40
          OSPF neighbors ...            5
                                        16.36.16.118
                                        16.36.16.182
                                        16.36.16.206
                                        16.36.16.207
                                        16.36.16.223

 The output shows an OSPF Hello packet transmitted on the L601-8-0 tra-
 cepoint. The output consists of two parts, the header and the body:

 o  The header is above the dashed line and contains general informa-
    tion about the traced record.

 o  The body is below the dashed line and contains the formatted packet.

                                                                  17

 

 The fields for the header are described in detail below (reading from
 top to bottom and left to right).

 ospfTx            Filter name. This particular packet has been tagged
                   with the "ospfTx" filter indicating that it is a trans-
                   mitted OSPF packet.

 84 of 84          This field shows the number of bytes captured ver-
                   sus the original packet size (the first number is the
                   captured size and the second the original size). This
                   example indicates that all of the original 84 bytes
                   were captured.

 at 09:53:03.46    Timestamp applied by the router. This example shows
                   that this packet was captured at 9:53 am.

 L601-8-0          Tracepoint name.

 3                 Sequence number. This number is incremented for ev-
                   ery packet traced on a particular tracepoint for this
                   session. In this example, this is the third packet
                   traced on this tracepoint.

 Status: 8063DAE0  Status field. This value is returned by the router
                   as part of the trace record, and is used by the de-
                   code routines to help correctly identify the packet.

 Context: 00000002 Context field. This value is returned by the router
                   as part of the trace record, and is used by the de-
                   code routines to help correctly identify the packet.

 Function: 8000B685 Function field. This value is returned by the router
                   as part of the trace record, and is used by the de-
                   code routines to help correctly identify the packet.

 The body of the output is separated into sections for each Protocol
 header in the packet. In this example, the first protocol header is
 IP; this in turn encapsulates an OSPF protocol header, which is fol-
 lowed by the OSPF HELLO packet.
















 18

 

 6  Release Notes

 6.1  V1.1

 1. DTF_EVENTS.DAT File

    The events file has been split into a common file which maps a router
    identifiers to names and a set of router specific files. This al-
    lows router specific filters to be supported.

 2. Highlighting

    The various portions of the output are now highlighted in the out-
    put display. Highlighting can be disabled using the "-D" switch.
    Highlighting is automatically disabled if the output is being sent
    to an output file (i.e. the "-o" switch is used).

 3. Coloring

    The various portions of the output are now colored in the output
    display. Coloring can be disabled using the "-C" switch. Coloring
    is automatically disabled if the output is being sent to an out-
    put file (i.e. the "-o" switch is used).
































                                                                  19

 




                             APPENDIX  A


                       COMPATIBILITY WITH CTF


 DTF uses the same protocol as CTF; therefore any router which supports
 CTF should also work with DTF. The format of the data file used is the
 same for DTF and CTF so DTF can read a CTF$TRACE.DAT file produced by
 CTF (although the converse is not necessarily true).










































                                          Compatibility with CTF  21

 




                             APPENDIX  B


                      REGULAR EXPRESSION SYNTAX


 A regular expression is zero or more branches, separated by `|'. It
 matches anything that matches one of the branches.

 A branch is zero or more pieces, concatenated. It matches a match for
 the first, followed by a match for the second, etc.

 A piece is an atom possibly followed by `*', `+', or `?'. An atom fol-
 lowed by `*' matches a sequence of 0 or more matches of the atom. An
 atom followed by `+' matches a sequence of 1 or more matches of the
 atom. An atom followed by `?' matches a match of the atom, or the null
 string.

 An atom is a regular expression in parentheses (matching a match for
 the regular expression), a range (see below), `.' (matching any sin-
 gle character), `^' (matching the null string at the beginning of the
 input string), `$' (matching the null string at the end of the input
 string), a `\' followed by a single character (matching that charac-
 ter), or a single character with no other significance (matching that
 character).

 A range is a sequence of characters enclosed in `[]'. It normally matches
 any single character from the sequence. If the sequence begins with
 `^', it matches any single character not from the rest of the sequence.
 If two characters in the sequence are separated by `-', this is short-
 hand for the full list of ASCII characters between them (e.g. `[0-9]'
 matches any decimal digit). To include a literal `]' in the sequence,
 make it the first character (following a possible `^'). To include a
 literal `-', make it the first or last character.

 B.0.1  AMBIGUITY

 If a regular expression could match two different parts of the input
 string, it will match the one which begins earliest. If both begin in
 the same place but match different lengths, or match the same length
 in different ways, life gets messier, as follows.

 In general, the possibilities in a list of branches are considered in
 left-to-right order, the possibilities for `*', `+', and `?' are con-
 sidered longest-first, nested constructs are considered from the out-
 ermost in, and concatenated constructs are considered leftmost-first.
 The match that will be chosen is the one that uses the earliest pos-
 sibility in the first choice that has to be made. If there is more than
 one choice, the next will be made in the same manner (earliest pos-
 sibility) subject to the decision on the first choice. And so forth.


                                       REGULAR EXPRESSION SYNTAX  23

 

 For example, `(ab|a)b*c' could match `abc' in one of two ways. The first
 choice is between `ab' and `a'; since `ab' is earlier, and does lead
 to a successful overall match, it is chosen. Since the `b' is already
 spoken for, the `b*' must match its last possibility -the empty string-
 since it must respect the earlier choice.

 In the particular case where no `|'s are present and there is only one
 `*', `+', or `?', the net effect is that the longest possible match
 will be chosen. So `ab*', presented with `xabbbby', will match `abbbb'.
 Note that if `ab*' is tried against `xabyabbbz', it will match `ab'
 just after `x', due to the begins-earliest rule. (In effect, the de-
 cision on where to start the match is the first choice to be made, hence
 subsequent choices must respect it even if this leads them to less-
 preferred alternatives.)









































 24  REGULAR EXPRESSION SYNTAX
