forked from osmocom/wireshark
d14bdd492e
svn path=/trunk/; revision=34590
508 lines
18 KiB
Text
508 lines
18 KiB
Text
|
|
=head1 NAME
|
|
|
|
rawshark - Dump and analyze raw libpcap data
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<rawshark>
|
|
S<[ B<-d> E<lt>encap:dltE<gt>|E<lt>proto:protonameE<gt> ]>
|
|
S<[ B<-F> E<lt>field to displayE<gt> ]>
|
|
S<[ B<-h> ]>
|
|
S<[ B<-l> ]>
|
|
S<[ B<-n> ]>
|
|
S<[ B<-N> E<lt>name resolving flagsE<gt> ]>
|
|
S<[ B<-o> E<lt>preference settingE<gt> ] ...>
|
|
S<[ B<-p> ]>
|
|
S<[ B<-r> E<lt>pipeE<gt>|- ]>
|
|
S<[ B<-R> E<lt>read (display) filterE<gt> ]>
|
|
S<[ B<-s> ]>
|
|
S<[ B<-S> E<lt>field formatE<gt> ]>
|
|
S<[ B<-t> ad|a|r|d|e ]>
|
|
S<[ B<-v> ]>
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
B<Rawshark> reads a stream of packets from a file or pipe, and prints a line
|
|
describing its output, followed by a set of matching fields for each packet
|
|
on stdout.
|
|
|
|
=head1 INPUT
|
|
|
|
Unlike B<TShark>, B<Rawshark> makes no assumptions about encapsulation or
|
|
input. The B<-d> and B<-r> flags must be specified in order for it to run.
|
|
One or more B<-F> flags should be specified in order for the output to be
|
|
useful. The other flags listed above follow the same conventions as
|
|
B<Wireshark> and B<TShark>.
|
|
|
|
B<Rawshark> expects input records with the following format by default. This
|
|
matches the format of the packet header and packet data in a libpcap-formatted
|
|
file on disk.
|
|
|
|
struct rawshark_rec_s {
|
|
uint32_t ts_sec; /* Time stamp (seconds) */
|
|
uint32_t ts_usec; /* Time stamp (microseconds) */
|
|
uint32_t caplen; /* Length of the packet buffer */
|
|
uint32_t len; /* "On the wire" length of the packet */
|
|
uint8_t data[caplen]; /* Packet data */
|
|
};
|
|
|
|
If B<-p> is supplied B<rawshark> expects the following format. This matches the
|
|
pcap_pkthdr struct and packet data used in libpcap. Note that the time stamp
|
|
value will match the previous format on some systems but not others.
|
|
|
|
struct rawshark_rec_s {
|
|
struct timeval ts; /* Time stamp */
|
|
uint32_t caplen; /* Length of the packet buffer */
|
|
uint32_t len; /* "On the wire" length of the packet */
|
|
uint8_t *data; /* Packet data */
|
|
};
|
|
|
|
In either case, the endianness (byte ordering) of each integer must match the
|
|
system on which B<rawshark> is running.
|
|
|
|
=head1 OUTPUT
|
|
|
|
If one or more fields are specified via the B<-F> flag, B<Rawshark> prints
|
|
the number, field type, and display format for each field on the first line
|
|
as "packet number" 0. For each record, the packet number, matching fields,
|
|
and a "1" or "0" are printed to indicate if the field matched any supplied
|
|
display filter. A "-" is used to signal the end of a field description and
|
|
at the end of each packet line. For example, the flags B<-F ip.src -F
|
|
dns.qry.type> might generate the following output:
|
|
|
|
0 FT_IPv4 BASE_NONE - 1 FT_UINT16 BASE_HEX -
|
|
1 1="1" 0="192.168.77.10" 1 -
|
|
2 1="1" 0="192.168.77.250" 1 -
|
|
3 0="192.168.77.10" 1 -
|
|
4 0="74.125.19.104" 1 -
|
|
|
|
Note that packets 1 and 2 are DNS queries, and 3 and 4 are not. Adding B<-R "not dns"> still prints each line, but there's an indication
|
|
that packets 1 and 2 didn't pass the filter:
|
|
|
|
0 FT_IPv4 BASE_NONE - 1 FT_UINT16 BASE_HEX -
|
|
1 1="1" 0="192.168.77.10" 0 -
|
|
2 1="1" 0="192.168.77.250" 0 -
|
|
3 0="192.168.77.10" 1 -
|
|
4 0="74.125.19.104" 1 -
|
|
|
|
Also note that the output may be in any order, and that multiple matching
|
|
fields might be displayed.
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item -d E<lt>encapsulationE<gt>
|
|
|
|
Specify how the packet data should be dissected. The encapsulation is of the
|
|
form I<type>B<:>I<value>, where I<type> is one of:
|
|
|
|
B<encap>:I<name> Packet data should be dissected using the libpcap data
|
|
link type I<name>, e.g. B<encap:EN10MB> for Ethernet.
|
|
|
|
B<encap>:I<name> Packet data should be dissected using the libpcap data link
|
|
type (DLT) I<name>, e.g. B<encap:EN10MB> for Ethernet. Names are converted
|
|
using pcap_datalink_name_to_val().
|
|
|
|
B<encap>:I<number> Packet data should be dissected using the libpcap DLT
|
|
I<number>, e.g. B<encap:105> for raw IEEE 802.11. A complete list of DLTs
|
|
can be found in pcap-bpf.h in the libpcap sources.
|
|
|
|
B<proto>:I<protocol> Packet data should be passed to the specified Wireshark
|
|
protocol dissector, e.g. B<proto:http> for HTTP data.
|
|
|
|
=item -F E<lt>field to displayE<gt>
|
|
|
|
Add the matching field to the output. Fields are any valid display filter
|
|
field. More than one B<-F> flag may be specified, and each field can match
|
|
multiple times in a given packet. A single field may be specified per B<-F>
|
|
flag. If you want to apply a display filter, use the B<-R> flag.
|
|
|
|
=item -h
|
|
|
|
Print the version and options and exits.
|
|
|
|
=item -l
|
|
|
|
Flush the standard output after the information for each packet is
|
|
printed. (This is not, strictly speaking, line-buffered if B<-V>
|
|
was specified; however, it is the same as line-buffered if B<-V> wasn't
|
|
specified, as only one line is printed for each packet, and, as B<-l> is
|
|
normally used when piping a live capture to a program or script, so that
|
|
output for a packet shows up as soon as the packet is seen and
|
|
dissected, it should work just as well as true line-buffering. We do
|
|
this as a workaround for a deficiency in the Microsoft Visual C++ C
|
|
library.)
|
|
|
|
This may be useful when piping the output of B<TShark> to another
|
|
program, as it means that the program to which the output is piped will
|
|
see the dissected data for a packet as soon as B<TShark> sees the
|
|
packet and generates that output, rather than seeing it only when the
|
|
standard output buffer containing that data fills up.
|
|
|
|
=item -n
|
|
|
|
Disable network object name resolution (such as hostname, TCP and UDP port
|
|
names), the B<-N> flag might override this one.
|
|
|
|
=item -N E<lt>name resolving flagsE<gt>
|
|
|
|
Turn on name resolving only for particular types of addresses and port
|
|
numbers, with name resolving for other types of addresses and port
|
|
numbers turned off. This flag overrides B<-n> if both B<-N> and B<-n> are
|
|
present. If both B<-N> and B<-n> flags are not present, all name resolutions are
|
|
turned on.
|
|
|
|
The argument is a string that may contain the letters:
|
|
|
|
B<m> to enable MAC address resolution
|
|
|
|
B<n> to enable network address resolution
|
|
|
|
B<t> to enable transport-layer port number resolution
|
|
|
|
B<C> to enable concurrent (asynchronous) DNS lookups
|
|
|
|
=item -o E<lt>preferenceE<gt>:E<lt>valueE<gt>
|
|
|
|
Set a preference value, overriding the default value and any value read
|
|
from a preference file. The argument to the option is a string of the
|
|
form I<prefname>B<:>I<value>, where I<prefname> is the name of the
|
|
preference (which is the same name that would appear in the preference
|
|
file), and I<value> is the value to which it should be set.
|
|
|
|
=item -p
|
|
|
|
Assume that packet data is preceded by a pcap_pkthdr struct as defined in
|
|
pcap.h. On some systems the size of the timestamp data will be different from
|
|
the data written to disk. On other systems they are identical and this flag has
|
|
no effect.
|
|
|
|
=item -r E<lt>pipeE<gt>|-
|
|
|
|
Read packet data from I<input source>. It can be either the name of a FIFO
|
|
(named pipe) or ``-'' to read data from the standard input, and must have
|
|
the record format specified above.
|
|
|
|
=item -R E<lt>read (display) filterE<gt>
|
|
|
|
Cause the specified filter (which uses the syntax of read/display filters,
|
|
rather than that of capture filters) to be applied before printing the output.
|
|
|
|
=item -s
|
|
|
|
Allows standard pcap files to be used as input, by skipping over the 24
|
|
byte pcap file header.
|
|
|
|
=item -S
|
|
|
|
Use the specified format string to print each field. The following formats
|
|
are supported:
|
|
|
|
=over 4
|
|
|
|
B<%D> Field name or description, e.g. "Type" for dns.qry.type
|
|
|
|
B<%N> Base 10 numeric value of the field.
|
|
|
|
B<%S> String value of the field.
|
|
|
|
=back
|
|
|
|
For something similar to Wireshark's standard display ("Type: A (1)") you
|
|
could use B<%D: %S (%N)>.
|
|
|
|
=item -t ad|a|r|d|e
|
|
|
|
Set the format of the packet timestamp printed in summary lines, the default
|
|
is relative. The format can be one of:
|
|
|
|
B<ad> absolute with date: The absolute date and time is the actual time and
|
|
date the packet was captured
|
|
|
|
B<a> absolute: The absolute time is the actual time the packet was captured,
|
|
with no date displayed
|
|
|
|
B<r> relative: The relative time is the time elapsed between the first packet
|
|
and the current packet
|
|
|
|
B<d> delta: The delta time is the time since the previous packet was
|
|
captured
|
|
|
|
B<e> epoch: The time in seconds since epoch (Jan 1, 1970 00:00:00)
|
|
|
|
=item -v
|
|
|
|
Print the version and exit.
|
|
|
|
=back
|
|
|
|
=head1 READ FILTER SYNTAX
|
|
|
|
For a complete table of protocol and protocol fields that are filterable
|
|
in B<TShark> see the wireshark-filter(4) manual page.
|
|
|
|
=head1 FILES
|
|
|
|
These files contains various B<Wireshark> configuration values.
|
|
|
|
=over 4
|
|
|
|
=item Preferences
|
|
|
|
The F<preferences> files contain global (system-wide) and personal
|
|
preference settings. If the system-wide preference file exists, it is
|
|
read first, overriding the default settings. If the personal preferences
|
|
file exists, it is read next, overriding any previous values. Note: If
|
|
the command line option B<-o> is used (possibly more than once), it will
|
|
in turn override values from the preferences files.
|
|
|
|
The preferences settings are in the form I<prefname>B<:>I<value>,
|
|
one per line,
|
|
where I<prefname> is the name of the preference
|
|
and I<value> is the value to
|
|
which it should be set; white space is allowed between B<:> and
|
|
I<value>. A preference setting can be continued on subsequent lines by
|
|
indenting the continuation lines with white space. A B<#> character
|
|
starts a comment that runs to the end of the line:
|
|
|
|
# Capture in promiscuous mode?
|
|
# TRUE or FALSE (case-insensitive).
|
|
capture.prom_mode: TRUE
|
|
|
|
The global preferences file is looked for in the F<wireshark> directory
|
|
under the F<share> subdirectory of the main installation directory (for
|
|
example, F</usr/local/share/wireshark/preferences>) on UNIX-compatible
|
|
systems, and in the main installation directory (for example,
|
|
F<C:\Program Files\Wireshark\preferences>) on Windows systems.
|
|
|
|
The personal preferences file is looked for in
|
|
F<$HOME/.wireshark/preferences> on
|
|
UNIX-compatible systems and F<%APPDATA%\Wireshark\preferences> (or, if
|
|
%APPDATA% isn't defined, F<%USERPROFILE%\Application
|
|
Data\Wireshark\preferences>) on Windows systems.
|
|
|
|
=item Disabled (Enabled) Protocols
|
|
|
|
The F<disabled_protos> files contain system-wide and personal lists of
|
|
protocols that have been disabled, so that their dissectors are never
|
|
called. The files contain protocol names, one per line, where the
|
|
protocol name is the same name that would be used in a display filter
|
|
for the protocol:
|
|
|
|
http
|
|
tcp # a comment
|
|
|
|
The global F<disabled_protos> file uses the same directory as the global
|
|
preferences file.
|
|
|
|
The personal F<disabled_protos> file uses the same directory as the
|
|
personal preferences file.
|
|
|
|
=item Name Resolution (hosts)
|
|
|
|
If the personal F<hosts> file exists, it is
|
|
used to resolve IPv4 and IPv6 addresses before any other
|
|
attempts are made to resolve them. The file has the standard F<hosts>
|
|
file syntax; each line contains one IP address and name, separated by
|
|
whitespace. The same directory as for the personal preferences file is
|
|
used.
|
|
|
|
Capture filter name resolution is handled by libpcap on UNIX-compatible
|
|
systems and WinPCAP on Windows. As such the Wireshark personal F<hosts> file
|
|
will not be consulted for capture filter name resolution.
|
|
|
|
=item Name Resolution (ethers)
|
|
|
|
The F<ethers> files are consulted to correlate 6-byte hardware addresses to
|
|
names. First the personal F<ethers> file is tried and if an address is not
|
|
found there the global F<ethers> file is tried next.
|
|
|
|
Each line contains one hardware address and name, separated by
|
|
whitespace. The digits of the hardware address are separated by colons
|
|
(:), dashes (-) or periods (.). The same separator character must be
|
|
used consistently in an address. The following three lines are valid
|
|
lines of an F<ethers> file:
|
|
|
|
ff:ff:ff:ff:ff:ff Broadcast
|
|
c0-00-ff-ff-ff-ff TR_broadcast
|
|
00.00.00.00.00.00 Zero_broadcast
|
|
|
|
The global F<ethers> file is looked for in the F</etc> directory on
|
|
UNIX-compatible systems, and in the main installation directory (for
|
|
example, F<C:\Program Files\Wireshark>) on Windows systems.
|
|
|
|
The personal F<ethers> file is looked for in the same directory as the personal
|
|
preferences file.
|
|
|
|
Capture filter name resolution is handled by libpcap on UNIX-compatible
|
|
systems and WinPCAP on Windows. As such the Wireshark personal F<ethers> file
|
|
will not be consulted for capture filter name resolution.
|
|
|
|
=item Name Resolution (manuf)
|
|
|
|
The F<manuf> file is used to match the 3-byte vendor portion of a 6-byte
|
|
hardware address with the manufacturer's name; it can also contain well-known
|
|
MAC addresses and address ranges specified with a netmask. The format of the
|
|
file is the same as the F<ethers> files, except that entries of the form:
|
|
|
|
00:00:0C Cisco
|
|
|
|
can be provided, with the 3-byte OUI and the name for a vendor, and
|
|
entries such as:
|
|
|
|
00-00-0C-07-AC/40 All-HSRP-routers
|
|
|
|
can be specified, with a MAC address and a mask indicating how many bits
|
|
of the address must match. The above entry, for example, has 40
|
|
significant bits, or 5 bytes, and would match addresses from
|
|
00-00-0C-07-AC-00 through 00-00-0C-07-AC-FF. The mask need not be a
|
|
multiple of 8.
|
|
|
|
The F<manuf> file is looked for in the same directory as the global
|
|
preferences file.
|
|
|
|
=item Name Resolution (ipxnets)
|
|
|
|
The F<ipxnets> files are used to correlate 4-byte IPX network numbers to
|
|
names. First the global F<ipxnets> file is tried and if that address is not
|
|
found there the personal one is tried next.
|
|
|
|
The format is the same as the F<ethers>
|
|
file, except that each address is four bytes instead of six.
|
|
Additionally, the address can be represented as a single hexadecimal
|
|
number, as is more common in the IPX world, rather than four hex octets.
|
|
For example, these four lines are valid lines of an F<ipxnets> file:
|
|
|
|
C0.A8.2C.00 HR
|
|
c0-a8-1c-00 CEO
|
|
00:00:BE:EF IT_Server1
|
|
110f FileServer3
|
|
|
|
The global F<ipxnets> file is looked for in the F</etc> directory on
|
|
UNIX-compatible systems, and in the main installation directory (for
|
|
example, F<C:\Program Files\Wireshark>) on Windows systems.
|
|
|
|
The personal F<ipxnets> file is looked for in the same directory as the
|
|
personal preferences file.
|
|
|
|
=back
|
|
|
|
=head1 ENVIRONMENT VARIABLES
|
|
|
|
=over 4
|
|
|
|
=item WIRESHARK_DEBUG_EP_NO_CHUNKS
|
|
|
|
Normally per-packet memory is allocated in large "chunks." This behavior
|
|
doesn't work well with debugging tools such as Valgrind or ElectricFence.
|
|
Export this environment variable to force individual allocations.
|
|
Note: disabling chunks also disables canaries (see below).
|
|
|
|
=item WIRESHARK_DEBUG_SE_NO_CHUNKS
|
|
|
|
Normally per-file memory is allocated in large "chunks." This behavior
|
|
doesn't work well with debugging tools such as Valgrind or ElectricFence.
|
|
Export this environment variable to force individual allocations.
|
|
Note: disabling chunks also disables canaries (see below).
|
|
|
|
=item WIRESHARK_DEBUG_EP_NO_CANARY
|
|
|
|
Normally per-packet memory allocations are separated by "canaries" which
|
|
allow detection of memory overruns. This comes at the expense of some extra
|
|
memory usage. Exporting this environment variable disables these canaries.
|
|
|
|
=item WIRESHARK_DEBUG_SE_USE_CANARY
|
|
|
|
Exporting this environment variable causes per-file memory allocations to be
|
|
protected with "canaries" which allow for detection of memory overruns.
|
|
This comes at the expense of significant extra memory usage.
|
|
|
|
=item WIRESHARK_DEBUG_SCRUB_MEMORY
|
|
|
|
If this environment variable is exported, the contents of per-packet and
|
|
per-file memory is initialized to 0xBADDCAFE when the memory is allocated
|
|
and is reset to 0xDEADBEEF when the memory is freed. This functionality is
|
|
useful mainly to developers looking for bugs in the way memory is handled.
|
|
|
|
=item WIRESHARK_RUN_FROM_BUILD_DIRECTORY
|
|
|
|
This environment variable causes the plugins and other data files to be loaded
|
|
from the build directory (where the program was compiled) rather than from the
|
|
standard locations. It has no effect when the program in question is running
|
|
with root (or setuid) permissions on *NIX.
|
|
|
|
=item WIRESHARK_DATA_DIR
|
|
|
|
This environment variable causes the various data files to be loaded from
|
|
a directory other than the standard locations. It has no effect when the
|
|
program in question is running with root (or setuid) permissions on *NIX.
|
|
|
|
=item WIRESHARK_PYTHON_DIR
|
|
|
|
This environment variable points to an alternate location for Python.
|
|
It has no effect when the program in question is running with root (or setuid)
|
|
permissions on *NIX.
|
|
|
|
=item ERF_RECORDS_TO_CHECK
|
|
|
|
This environment variable controls the number of ERF records checked when
|
|
deciding if a file really is in the ERF format. Setting this environment
|
|
variable a number higher than the default (20) would make false positives
|
|
less likely.
|
|
|
|
=item IPFIX_RECORDS_TO_CHECK
|
|
|
|
This environment variable controls the number of IPFIX records checked when
|
|
deciding if a file really is in the IPFIX format. Setting this environment
|
|
variable a number higher than the default (20) would make false positives
|
|
less likely.
|
|
|
|
=item WIRESHARK_ABORT_ON_DISSECTOR_BUG
|
|
|
|
If this environment variable is set, B<Rawshark> will call abort(3)
|
|
when a dissector bug is encountered. abort(3) will cause the program to
|
|
exit abnormally; if you are running B<Rawshark> in a debugger, it
|
|
should halt in the debugger and allow inspection of the process, and, if
|
|
you are not running it in a debugger, it will, on some OSes, assuming
|
|
your environment is configured correctly, generate a core dump file.
|
|
This can be useful to developers attempting to troubleshoot a problem
|
|
with a protocol dissector.
|
|
|
|
=item WIRESHARK_EP_VERIFY_POINTERS
|
|
|
|
This environment variable, if exported, causes certain uses of pointers to be
|
|
audited to ensure they do not point to memory that is deallocated after each
|
|
packet has been fully dissected. This can be useful to developers writing or
|
|
auditing code.
|
|
|
|
=item WIRESHARK_SE_VERIFY_POINTERS
|
|
|
|
This environment variable, if exported, causes certain uses of pointers to be
|
|
audited to ensure they do not point to memory that is deallocated after when
|
|
a capture file is closed. This can be useful to developers writing or
|
|
auditing code.
|
|
|
|
=back
|
|
|
|
=head1 SEE ALSO
|
|
|
|
wireshark-filter(4), wireshark(1), tshark(1), editcap(1), tcpdump(8),
|
|
pcap(3), dumpcap(1), text2pcap(1)
|
|
|
|
=head1 NOTES
|
|
|
|
B<Rawshark> is part of the B<Wireshark> distribution. The latest version of
|
|
B<Wireshark> can be found at L<http://www.wireshark.org>.
|
|
|
|
HTML versions of the Wireshark project man pages are available at:
|
|
L<http://www.wireshark.org/docs/man-pages>.
|
|
|
|
=head1 AUTHORS
|
|
|
|
B<Rawshark> uses the same packet dissection code that B<Wireshark> does, as
|
|
well as using many other modules from B<Wireshark>; see the list of authors
|
|
in the B<Wireshark> man page for a list of authors of that code.
|
|
|