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