.\" @(#) $Id: tcpshow.1, v 1.31 1998/02/02 10:50:40 mike Exp $
.\"
.\" #if !defined(MAY_NOT_MODIFY)
.\"
.\" Copyright (c) 1996, 1997, 1998 I.T. NetworX Ltd.  All rights reserved.
.\"
.\" The conditions applying to the use of this manual page are the same as
.\" those conditions applying to the file "tcpshow.c".  See that file for
.\" the conditions.
.\"
.\"
.\" Mike Ryan, 02feb98.
.\"
.\" #endif
.TH TCPSHOW 1  "2 Feb 1998"
.SH NAME
tcpshow \- decode a \fBtcpdump\fP savefile
.SH SYNOPSIS
.na
.B tcpshow
[
.B \-b
] [
.B \-sb
] [
.B \-w
.I width
] [
.B \-noLink
] [
.B \-noIp
]
.br
.ti +8
[
.B \-noHostNames
] [
.B \-fqdn
] [
.B \-noEtherNames
]
.br
.ti +8
[
.B \-noPortNames
] [
.B \-noData
] [
.B \-minDecode
]
.br
.ti +8
[
.B \-track
] [
.B \-terse
] [
.B \-verbose
] [
.B \-cooked
]
.br
.ti +8
[
.B \-pp
] [
.B \-s
] [
.B \-h
] [
.B expression
]
.br
.ad
.SH DESCRIPTION
.LP
\fBtcpshow\fP reads a \fBtcpdump\fP(1) savefile and provides a
reasonably complete decode
of Ethernet, ARP, RARP, IP, ICMP, UDP and TCP headers, in packets that match
the boolean \fIexpression\fP.  The data belonging to these packets is
displayed in ASCII.
.LP
Currently, protocol data is not decoded.  This is not considered a
serious problem for applications that use ASCII data streams.
.LP
Also, IP and TCP options are not decoded.
.LP
The input file must be in the format produced by
\fItcpdump -enx\fP.  This file can be generated from
.br
1. a prior run of
.B tcpdump -w
.I file
.br
2. a live run of
.B tcpdump
(without -w)
.br
3. any other program that produces a correctly formatted
.br
   trace
.br
See under EXAMPLES for each of these different methods, plus a
description of the format the input file needs to be in.
.LP
Except when \fI-cooked\fP is used, \fBtcpdump\fP(1) is required
to be on your PATH, to process the raw savefile.
.SH OPTIONS
The following options can be used in just about any sane combination.
.TP
.B \-b
Do not break long lines.  If this option is off (the
default), then lines are wrapped at column 60.  The column at which
wrapping occurs may be changed with the \fI-w\fP flag.  If this option
is on, then wrapping does not occur.
.IP
Leaving this flag off produces a neater, more readable display of the
application data in most cases.
.TP
.B \-sb
show line breaks
.IP
When \fI-b\fP is not used, it may be useful to see exactly where
\fBtcpshow\fP wrapped each line, in its display of application data.
This option causes the string ``<br>'' to be displayed at the
end of each wrapped line.  (Lines which were not wrapped, but
terminated before the page width, are not so marked.)
.TP
.B \-w \fIwidth\fP
.br
set pagewidth to \fIwidth\fP columns
.IP
This determines where \fBtcpshow\fP will fold long lines, when the
\fI-b\fP switch is not used.  The default is at column 60.
.TP
.B \-noLink
don't decode the link header
.IP
The data link header (Ethernet header) is not decoded and displayed.
.TP
.B \-noIp
don't decode the IP header
.IP
The IP header is not decoded and displayed.
.TP
.B \-noHostNames
don't map IP addresses into host names
.IP
Normally, host names are displayed if they can be resolved; otherwise, the
IP address is displayed.  This flag prevents the attempt to resolve the name.
(See \fI-fqdn\fP.)
.TP
.B \-fqdn
show host names as fully-qualified
.IP
Normally, short host names are displayed, i.e. the domain part is omitted.
If the name can't be resolved, the IP address is displayed.
.TP
.B \-noEtherNames
don't map Ethernet addresses into host names
.IP
Normally, host Ethernet names are displayed if they can be resolved;
otherwise, the Ethernet address is displayed.  This flag prevents the attempt
to resolve the name.
.TP
.B \-noPortNames
don't map port numbers into port names
.IP
Normally, protocol port names are displayed if they can be resolved;
otherwise, the port number is displayed.  This flag prevents the attempt
to resolve the name.
.TP
.B \-noData
don't show the data
.IP
The protocol data is not displayed (a count of data bytes is shown).
.TP
.B \-minDecode
display only a minimal decode of the protocol headers.
.IP
Essentially, the header decode shows only the hostnames and ports involved.
.TP
.B \-track
track TCP sequence numbers
.IP
An additional field is produced in the output which shows the TCP
acknowledgement number which this side of the connection should
receive once the current packet has been received by its peer.
.TP
.B \-terse
show the header decode in compact format
.IP
This option, which is on by default, produces a display of the decoded
headers in a compact format, allowing more information to be assimilated
with less eye movement.
.TP
.B \-verbose
show the header decode in expanded format
.IP
With this option, the display of the decoded headers is verbose,
occupying a lot of display-space real-estate.  This is meant for users
not entirely familiar with the fields in the various headers.
.TP
.B \-cooked
don't run \fBtcpdump\fP(1) to pre-process the input
.IP
If the input file is already in the expected format, this option
must be used.  See EXAMPLES below of where this flag is appropriate.
.TP
.B \-pp
point-to-point link
.IP
If the input file was collected from data travelling over a
point-to-point link (one which doesn't make an Ethernet header available),
this option needs to be used.
.TP
.B \-s
also display a hex dump of spurious data at packet-end
.IP
For a reason unknown to the author, \fBtcpdump\fP(1) output sometimes
contains data at the end of packets which don't belong to those packets.
This spurious data is suppressed from the output, except when this
option is used.
.TP
.B \-h
display a help summary
.IP
This list of options is displayed, with one-liner descriptions.
.TP
.B expression
filter the input file using a \fBtcpdump\fP(1) expression
.IP
If the \fI-cooked\fP option is not used, then \fBtcpdump\fP(1) is
required to be on your PATH.  It is used to read the raw savefile,
producing output in the format \fBtcpshow\fP expects.  The
\fIexpression\fP should be a valid \fBtcpdump\fP(1) expression.
It is not parsed or interpreted by \fBtcpshow\fP, but passed on
to \fBtcpdump\fP(1) for its consumption.
.SH EXAMPLES
In the following examples, where \fBtcpdump\fP(1) is used, the
flag \fI-s 1518\fP is used to be sure of saving the complete Ethernet
frame.
.LP
Also, where \fBtcpdump\fP(1) expressions are used, these could equally
have been given to \fBtcpdump\fP(1) directly, if it was known at this
time what data you're interested in.
.LP
Capture a raw savefile and decode it later.
.IP
# tcpdump -s 1518 -w savefile
.br
# tcpshow < savefile
.LP
Decode the data as quickly as \fBtcpdump\fP(1) gives it to us.
.IP
# tcpdump -s 1518 -lenx | tcpshow -cooked
.LP
Display headers only.
.IP
# tcpshow -noData < savefile
.LP
Display data only (minimal header decode).
.IP
# tcpshow -minDecode
.LP
Display a decode of Telnet traffic only, omitting the link and IP headers.
.IP
# tcpdump -s 1518 -w savefile
.br
# tcpshow -noLink -noIp tcp port telnet < savefile
.LP
Give a verbose display of the headers, and a full display of
the data, for all packets going into or coming from the host "sam"
-- this host is on a LAN accessible through a PPP link (interface "ppp0").
.IP
# tcpdump -i ppp0 -s 1518 -w savefile
.br
# tcpshow -pp -verbose host sam < savefile
.LP
Show all SMTP mail transfers, omitting the headers (you're not supposed to
do this).
.IP
# tcpdump -s 1518 -w savefile
.br
# tcpshow -minDecode port smtp < savefile
.LP
To display a decode of data not captured via \fBtcpdump\fP(1), you
would typically use the application that captured the trace to dump
that trace into a file in ASCII-hex format.  You feed that file into
a Perl/sh/awk script (that you write), which produces a file in the
format \fBtcpshow\fP expects.  Such scripts are easy to write.  For
example, if your application is "capture" and your script
is "convert", then \fBtcpshow\fP might be used as follows.
.IP
# capture -hexoutput | convert | tcpshow -cooked
.LP
Note that \fI-cooked\fP is required, to prevent \fBtcpdump\fP(1) from
being spawned.
.LP
A loose definition of the format \fBtcpshow\fP expects is:
.IP
The 1st line of each packet must begin in column 1 and contains the
following whitespace-separated fields: timestamp, Ethernet source address,
Ethernet destination address, Ethernet type.  The Ethernet addresses
must be in the form aa:bb:cc:dd:ee:ff.  If \fI-pp\fP is used, only
the timestamp is required.  The format of the timestamp is hh:mm:ss:fff...
where hh=hourOfDay, mm=minOfHour, ss=secOfMin and the 'f' digits are the
fraction of a second at which the packet arrived (resolution varies from
machine to machine).  If timestamp information isn't available, any text
string will do (no embedded whitespace and it shouldn't look like a valid
timestamp).  The Ethernet type field is an ASCII-hex string; for example,
"0800" means an IP packet is encapsulated.
.IP
The 2nd and subsequent lines of each packet must begin with a TAB.
They consist of an ASCII-hex dump of the Ethernet data field.  The
hex bytes can be separated from each other by any amount of
whitespace, including none.
.SH FILES
\fBtcpshow\fP reads from standard input and writes to standard
output.
.SH SEE ALSO
tcpdump(1), nit(4P), bpf(4)
.\"
.\" #if !defined(MAY_NOT_MODIFY)
.\"
.SH AUTHOR
Mike Ryan <mike@NetworX.ie>
.SH RESTRICTIONS
This program and its source code are freely available.  See the
Conditions governing their use in the source code.
.\"
.\" #endif
.\"
.SH BUGS
It should decode IP and TCP options.
.LP
It should decode data from application protocols that don't send their
data in ASCII (e.g. DNS/BIND).
.LP
It should not depend on \fBtcpdump\fP(1) as much as it does.  It should
be modified to use pcap(3) directly.