'\" t .TH PCAT-DIFF 1 "08 Mar 2006" "pcat utils" .SH NAME pcat-diff \- show the difference between two pcat files. .SH SYNOPSIS .B pcat-diff .IR PCAT_FILE1 .IR PCAT_FILE2 .SH DESCRIPTION \fBpcat-diff\fR reads in two pcat files and show the differences between them. Its output is another pcat stream which can then be interpreted by pcat-print. pcat-diff can also do advanced checking against a number of specification, for instance to count the number of known differences between two implementations. You can let pcat-diff do more intelligent checking on the differences between two outputs of pcat. In this mode, pcat-diff takes an argument specifying a directory containing files whose name end in .match. These files specify 'Known' differences. It works like this: If a difference between two answer packets is found, the packet is first normalized; the packet dates is changed to match, and each section is sorted. If these changes still don't make the packets equal, the match-specifications in the specified directory are consulted. These specifications contain 3 elements; a 1-line description of the type of difference, a specification the question must match, and a specification that both answer packets must match. The first line contains the specification, the following lines the specifications, separated by a line starting with an exclamation mark. A specification looks like the normal output of drill and dig. It is based on the text representation format from the DNS RFCs. It can contain the following special characters: * whitespace: whitespace is skipped and ignored * ?: Following a question mark, all characters up to the next whitespace are optional, so they can either exist or not in the answer * []: Square brackets contain a list of words/values of which exactly one must be present in the packets. * *: A star specifies that the packets may contain everything until it matches the next character in the specification. You can use multiple stars in a row, the number of stars specify the number of next characters that must match before continuing. * &: The ampersand works the same as the *, but in this case the value that matches must be exactly the same in both packets. There are 2 special cases that can be used instead of a packet description: * BADPACKET: if you use this as the complete description of the query packet, this matches any query that cannot be parsed * NOANSWER: if you use this as the complete description of the answer packet, this matches *both* packets if *one* had no answer (the other packet is ignored, if both packets had no answer, they were equal anyway) Example: Different additional section * ! ;; ->>HEADER<<- opcode: &, rcode: &, id: & ;; flags: & ; QUERY: &, ANSWER: &, AUTHORITY: &, ADDITIONAL: & ;; QUESTION SECTION: ;; &&&&& ;; ANSWER SECTION: &&&&& ;; AUTHORITY SECTION: &&&&& ;; ADDITIONAL SECTION: ***** ;; Query time: & msec &&&&& ;; WHEN: & ;; MSG SIZE rcvd: & The description of this examples is 'Different additional section'. The query specification contains only one *, so every query matches this. The answer specification specifies that the packets must be completely equal, except for the additional part. The additional part must, however, contain an equal amount of entries (see the & after ADDITIONAL in line 2). In the question section, 5 &'s are used, so that everything passes until the packets contain the text ';; AU'. This could of course be expanded to completely match the text ';; AUTHORITY SECTION', by using even more ampersands. If pcat-diff in advanced mode encounters a difference which is not known, it prints the index number, query, and both answers, and then quits. It is expected that the user studies the new and unexpected difference, captures it in a match specification, and runs pcat-diff again. To speed up the process of finding all differences, you can start from the index number that was printed by using the option -s . If you want to know a bit more about why the packets did not match, you can specify verbose mode with -v. It is not advisable to do this on the complete input, but rather use -s to start with the offending packet. Verbose mode produces a LOT of output. If the complete files have been read, and no unknown differences have been found, statistics are printed about the known differences encountered. Because this can take a long time, you can use '-p ' to print preliminary results every nr packets. .PP If PCAT_FILE2 is not given, standard input is read. .SH OPTIONS .TP \fB-d\fR \fIdirectory\fR Directory containing match files, this options sets the advanced checking mode, see manpage .TP \fB-h\fR Show usage .TP \fB-m\fR \fInumber\fR only check up to packets .TP \fB-o\fR show original packets when printing diffs (by default, packets are normalized) .TP \fB-p\fR \fInumber\fR show intermediate results every packets .TP \fB-s\fR \fInumber\fR only start checking after packets .TP \fB-v\fR verbose mode .SH OUTPUT FORMAT The default output of \fBpcat-diff\fR consists "records". Each record has four lines: .PP 1. xxx - (decimal) sequence number 2. hex dump - query in hex, network order 3. hex dump - answer of FILE1 in hex, network order 4. hex dump - answer of FILE2 in hex, network order. The advanced output only prints statistics about the types of differences found and their percentages. If an unknown difference is found it prints the relevant packets and exits. .SH ALSO SEE Also see pcat(1) and pcat-print(1). .SH AUTHOR Written by Miek Gieben for NLnet Labs. .SH REPORTING BUGS Report bugs to . .SH COPYRIGHT Copyright (C) 2005, 2006 NLnet Labs. This is free software. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. .PP Licensed under the BSD License.