[dns-operations] ncap docs?

[Paul Vixie]

> Okay..  Here's some sample data I've anonymized.  I don't that should
> make a difference for the things I'm wondering about.. but let me know if
> it does.
> 
> [66 nf -] 2009-01-07 16:25:00.689139000 [00000002 cd9ff643] \
> 	[xxx.xxx.xxx.xxx].53 [xxx.xxx.xxx.xxx].27969 udp \
> 	dns QUERY,NOERROR,19019,qr|aa|ra \
> 	1 example.dom,IN,MX \
> 	1 example.dom,IN,MX,1800,10,mail.example.dom 0 \
> 	1 mail.example.dom,IN,A,1800,xxx.xxx.xxx.xxx
> 
> In the first line, the date and time is obvious.  The first and last  
> sets of data enclosed in square braces escape me, though.

that's user1 and user2, which are mentioned in ncap(3).  you must have
got this sample from ISC SIE since our custom is to use user2 to contain
the hash of the submitter's authorized_keys file.  therefore i know which
member's data that was before you anonymized it.  :-).  in a normal ncap
file that didn't come through SIE, user1 and user2 will both be zero.  you
can set them to anything you want with the -1 and -2 command line options
of ncaptool, as explained in very little detail by "ncaptool -h".

> In the flags line, can the 'dns' at the beginning be anything else?   

yes.  icmp for example.

> I'm assuming it signifies that ncap is decoding DNS protocol, but I  
> thought that's all it did, which would make that field a constant,  
> which would seem redundant.  So I suspect my assumption is either  
> wrong or incomplete.

dnscap was dns-specific.  ncaptool is not.  i fully anticipate that it will
sprout a lot of other decoders, like tcpdump did in the early days.

> In the same line, between NOERROR and the flags, I'm assuming that's  
> the QID.

yes.  in dump_dns.c, as contained in both the dnscap and ncap tarballs,
the function dump_dns() looks like this:

        fprintf(trace, " %sdns ", endline);
        if (ns_initparse(payload, paylen, &msg) < 0) {
                fputs(strerror(errno), trace);
                return;
        }
        opcode = ns_msg_getflag(msg, ns_f_opcode);
        rcode = ns_msg_getflag(msg, ns_f_rcode);
        id = ns_msg_id(msg);
        if ((rcp = dump_dns_rcode(rcode)) == NULL) {
                sprintf(rct, "CODE%u", rcode);
                rcp = rct;
        }
        fprintf(trace, "%s,%s,%u", _res_opcodes[opcode], rcp, id);
        sep = ",";
#define FLAG(t,f) if (ns_msg_getflag(msg, f)) { \
                        fprintf(trace, "%s%s", sep, t); \
                        sep = "|"; \
                  }
        FLAG("qr", ns_f_qr);
        FLAG("aa", ns_f_aa);
        FLAG("tc", ns_f_tc);
        FLAG("rd", ns_f_rd);
        FLAG("ra", ns_f_ra);
        FLAG("z", ns_f_z);
        FLAG("ad", ns_f_ad);
        FLAG("cd", ns_f_cd);
#undef FLAG
        dump_dns_sect(&msg, ns_s_qd, trace, endline);
        dump_dns_sect(&msg, ns_s_an, trace, endline);
        dump_dns_sect(&msg, ns_s_ns, trace, endline);
        dump_dns_sect(&msg, ns_s_ar, trace, endline);

> In the answer, what's the zero at the end of the line?

each dump_dns_sect() as shown above emits a number which is the count of
records in a section.  the 0 you're seeing after the answer is telling you
that the authority section is empty.  dump_dns_sect() looks like this:

        rrmax = ns_msg_count(*msg, sect);
        if (rrmax == 0) {
                fputs(" 0", trace);
                return;
        }
        fprintf(trace, " %s%d", endline, rrmax);
        sep = "";
        for (rrnum = 0; rrnum < rrmax; rrnum++) {
                if (ns_parserr(msg, sect, rrnum, &rr)) {
                        fputs(strerror(errno), trace);
                        return;
                }
                fprintf(trace, " %s", sep);
                dump_dns_rr(msg, &rr, sect, trace);
                sep = endline;
        }

i did it this way deliberately so that i wouldn't waste a newline on an
empty section.  obviously this whole format is designed to be read by a
perl script rather than a human.  the "ncaptool-dnsparse.pl" script in
the ncap source tarball is such a script if you want a starting point.

> And finally, when there are only three sections, is there a way to  
> determine from format the difference between authority and additional,  
> or does one just have to assume that a third section with NS records  
> in it is authority, and without is additional?

every section has a count, then that number of space-separated records,
with the fields of each record separated by commas.

> Thanks Paul!
>     Matt

sorry the documentation's weak.  it's on the to-do list of someone who
shall remain nameless.