nifpan: Network Interface Packet Analyser

The 1st form represents the typical usage of nifpan, and is used to display a logfile that was created by niftap.
The 2nd form is used to parse a file representing a raw packet or data object, ie. a file that was not created by niftap. The most likely usage of this form is as an ASN.1 BER pretty-printer.
The 3rd form is less likely to be used, and it allows niftap logfiles to be converted to another format (eg. Snoop or Tcpdump).

The command-line options are as follows:

-n	Print IP addresses in numeric form. In the absence of this option, they are resolved to hostnames, before being printed. If nifpan is being used to display captured packets in real time, then this option may be required to prevent nifpan itself becoming a source of network traffic (eg. if it uses DNS or NIS to resolve hostnames). It does cache /etc/hosts at startup and it learns new addresses as it goes along, so the extra traffic caused by omitting -n would ease over time.
-N	Print all addresses and protocols in numeric form. This goes further than -n, by also bypassing the resolution of number-to-name for the network-database files, such as /etc/services, /etc/rpc, etc. This option is applicable to the same situations as -n, ie. you should use it on systems where NIS lookups would be needed to resolve any entries in the network-database files, and you don't want nifpan to become a source of extra traffic.
-v	Verbosity, ie. level of detail in the output file. Legal values are 1 to 4, and the default is 2. Levels 1 to 3 are referred to as the short-summary modes, and they generate a 1-line summary of each packet, in progressively greater levels of detail. Level 1 is designed to focus attention on IP addresses, TCP/UDP port numbers and a packet's top-level protocol. Level 2 mentions each protocol layer in the packet, and prints the packet's timestamp. It also shows extra IP and TCP parameters. Level 3 shows more info for any protocols layered below IP (eg. ethernet addresses). Level 4 is also known as the long-summary mode. It is an exhaustive dump, showing every single field, in every nested PDU that makes up the packet, followed by a tabular dump of user data. It can therefore run to dozens of lines for each packet (excl the user-data dump), and is usually used in conjunction with the -e switch, after using a short-summary mode to identify "interesting" packets.
-e	Print selected events only. Its argument is a comma-separated list, where each item is number or min-max. Event 0 is the log header, and a range with max=0 means no upper limit. eg. -e 3,5,7-9 prints events 3, 5, 7, 8 and 9. Each event in the log file is numbered consecutively, from 0 onwards. The term event can be understood as a packet 99.9% of the time, but can also refer to internal errors encountered by niftap.
-E	Similiar to -e, except that the items in the selection list are timestamps in the format YYMMDD:hhmmss, rather than an event number.
-b	Base time to use, when printing time intervals in short-summary mode. Defaults to start time of earliest session in log file. Each event in the log file is timestamped, and the base time is the time from which the time stamps are measured (ie. it is time zero). This option is useful when comparing events in log files that were started at marginally different times on different hosts (or, to compensate for known differences between the system times on different machines). The result of this correlation is that events which happened simultaneously on both computers can be printed with the same timestamp, even if their clocks were out of sync.
-d	Dump ASCII protocols in the format specified by the environment variable $NIF_DUMPFMT (cf below). This option is only relevant in long-summary mode. The term "ASCII protocols" refers to those layer 5 protocols which can simply be printed as a stream of text, with no internal binary structures (eg. SMTP, HTTP, Telnet, etc). By default, $NIF_DUMPFMT only affects the display of unrecognised protocols, but the -d option extends its influence to recognised ASCII ones.
-t	Print short-summary timestamps as a delta time. In the -v2 and -v3 modes, nifpan prints a timestamp for each packet, and by default, it represents the elapsed time since the start of the packet capture session. The -t option replaces that timestamp with an alternative format, that represents the no. of microseconds since the previous packet. This option has no effect on verbose mode (-v4), and obviously renders the -b option irrelevant.
-T	Like -t, this specifies an alternative format for the event timestamps. In this case however, the format is a time-of-day string, in the form HH:MM:SS.uuuuuu (ie. microseconds are shown).
-u	Interpret unrecognised TCP/UDP ports as protocols of the specified type. proto is either a numeric TCP/UDP port number, or else it is one of the special types: RPC, ASN1, X509CERT, X509CRL, TEXT (treat as text-based protocol, eg. HTTP). Mapping of port numbers might be useful if you were (say) running an experimental SNMP server on port 20161 rather than 161. Normally, SNMP traffic would have to appear on port 161 to be recognised as being SNMP, but -u 161 would cause all unrecognised traffic (and that includes port 20161) to be decoded as if it was on port 161, ie. as if it was SNMP packets. With the exception of NFS, RPC servers use dynamic ports which cannot be recognised by nifpan, so -u RPC can be used to force captured packets through nifpan's RPC parser, if you know (or simply suspect) that they are RPC packets. -u ASN1 is similiar, but would be used to display ASN.1 BER-encoded traffic (other than SNMP, which can be recognised by virtue of its well known port, namely 161). -u X509CERT and -u X509CRL indicate specific ASN.1 types (namely X.509 certificates and revocation lists), as opposed to -u ASN1, which invokes the generic ASN.1 parser.
-U	Similiar to -u, except that all traffic, including recognised TCP/UDP ports, is forced through the decoder associated with the proto argument. This might be useful if another service was running on a well-known port, for whatever reason.
-l	Length of ASCII layer-5 protocols to dump. This only applies to the 1-line summary modes, and the default is 15 characters. This simply refers to the leading fragment of the text-based protocols (SMTP, HTTP, Telnet, etc), which gets printed in square brackets after the TCP or UDP parameters.
-f	Same meaning as in niftap (specify a filter expression).
-F	Same meaning as in niftap (specify a filter-expression file).
-a	Specify a trigger-action string.
-A	Specify the name of a file containing a trigger action, ie. the contents of this file should be equivalent to a -a string.
-k	Various kludges/workarounds, to handle OS bugs, etc. Valid IDs are: 1: Byte-swap the Ethernet Type/Length field, before filtering the packet. As an example, the popular PPP package, dp, has a bug which requires this workaround, when running on Solaris x86.
-x	Export a Network-I log file to a different format. Valid arguments are: snoop, tcpdump, IP, Ethernet. The IP format simply reduces a Network-I logfile to a stream of IP packets, ie. all header info is lost. It dumps all packets without checking if they are IP, so it should be combined with a filter (eg. use -f IP), to make sure that any non-IP packets are omitted from the output file. The Ethernet format is similiar, but it reduces the niftap logfile to a stream of ethernet/802.3 frames. For both the Ethernet and IP export formats, the output file will obviously be unintelligible to any reader, if any of the packets in the niftap logfile had been truncated (because no header info is available to say that they are truncated). See nif_import for the more useful possibility of conversions in the opposite directions, ie. to the Network-I format.
-r	This form of the nifpan command is used to parse individual packets or data objects, as opposed to niftap log files. The format argument can be one of: layer.protocol: This allows you to display an arbitrary packet, which has previously been saved to file. The layer/protocol numbering scheme is as follows: Layer 2: Protocol numbers are: 1=Ethernet, 2=802.3, 6=FDDI, 7=802.2 (LLC), 8=SNAP, 9=PPP eg. -r2.1 means interpret the input as an Ethernet frame Layer 3: Protocol numbers are: 1=IP, 2=ARP, 3=RARP eg. -r3.2 means ARP Layer 4: Protocol numbers are IP protocols, as specified in /etc/protocols eg. -r4.89 means OSPF Layer 5: Protocol numbers are TCP and UDP ports, as specified in /etc/services eg. -r5.161 means SNMP One of the special -u types. They are described here again, in more detail: ASN1: BER-encoded ASN.1 object. This option enables nifpan to act as a general-purpose BER pretty-printer. X509CERT: X.509 digital certificate, as used by secure SSL-based websites. Apart from any X.509 files that might be lying around on your system, this option can also be used to analyse remote certificates, in greater detail than would be reported by your browser. eg. Using the public-domain OpenSSL package (www.openssl.org), you can connect to a secure webserver, server.com as follows: openssl s_client -connect server.com:443 This will make an SSL connection to the remote server, and print the certificate on stdout, in PEM format. If that was captured to a file called, pemfile, it can then be converted to BER form by these commands: openssl x509 -outform der -in pemfile -out berfile OR openssl base64 -in pemfile -d -out berfile The output file, berfile, can then be supplied as an argument to the command nifpan -rX509CERT. X509CRL: X.509 Certificate Revocation List.
-o	This option can only be used in conjunction with -r, and allows you to parse a packet which does not necessarily start at the beginning of the input file (which could be a pipe, or a regular file), or extend to the end of the input file. eg -o 128:500 means the packet begins at offset 128 (first byte is offset 0), and is 500 bytes long. -o 128 means the packet begins at offset 128, and extends to the end of the file. Making the max parameter too small will obviously result in wildly inaccurate printouts, but making it too large is harmless - you will simply get some spurious junk at the end.
-h	Display a usage synopsis.
shorthand filter-spec	Same meaning as in niftap (quick filter notation).

• NIF_DUMPFMT determines the format in which the PDUs of unrecognised protocols are dumped. It also applies to opaque fields within a known PDU. The possibilities are:

  DEC	Show each octet as a decimal value. 16 octets per row.
  HEX	Show each octet as a hexadecimal value. 25 octets per row.
  OCT	Show each octet as an octal value. 16 octets per row.
  ASC	Show ASCII values of each octet. 16 octets per row. What is meant by ASCII is that printable characters are shown as is, and values less than 32 are shown as the ASCII names for those control chars. 8-bit chars are shown as the 7-bit representation, preceded by a backslash.
  TXT	The PDU is dumped as plain text, with warnings of where it contains NULs. This is the mode used to display protocols like SMTP, HTTP, Telnet etc. It is the only mode in which the data is not dumped in a regular tabular form.

• NIF_DUMP_LONGS takes the values y or n, and qualifies the display of data which is being dumped in one of the numeric tabular modes (DEC, OCT or HEX, cf above). If active (value="y"), it causes the data to be dumped 4 octets per row, and on the right-hand side, it prints the values of the four octets as two 16-bit numbers, followed by their 32-bit value.
  The purpose of this option is simply to simplify the analysis of a protocol dump, where you know the fields are word-aligned. It saves you having to mentally combine adjacent octets into 16 or 32-bit integer values.
  It interprets the data stream as Big Endian.
• NIF_DUMP_LENDIAN also takes the values y or n, and it qualifies $NIF_DUMP_LONGS by byte-swapping the 16 and 32-bit integers, before printing them. It would be used where the dumped data is known to be in Little Endian byte order.
• NIF_HOSTS_CACHE controls the size of the hosts cache, and takes a numeric value.
  This is a DNS cache, designed to speed up IP address-to-name resolution, and nifpan learns the IP mappings as it goes along, up to a maximum of 500 addresses. After this table is filled up, it is forced to do a lookup each time it needs to resolve a given IP address. This variable simply lets you override that default value of 500.
• NIF_RPC_CACHE controls the size of the RPC cache, and takes a numeric value. nifpan caches each RPC request it sees, until it sees the associated response. If an RPC response cannot be matched up with its associated request, then less info can be displayed for it.
  This table contains 503 entries by default, and this variable simply lets you override that. It should be a prime number, so the recommended upgrade path is 257, 503, 1009, 2027).
• NIF_TRCINFO also takes the values y or n, and turns on some extra trace-level verbosity.