8f0f691312
The RDMA reply chunk is used for a large RPC reply which does not fit into a single SEND operation and does not have a single large opaque, e.g., NFS READDIR. The RPC call packet is used only to set up the RDMA reply chunk. The whole RPC reply is transferred via RDMA writes. Fragments are added on any RDMA write packet, RDMA_WRITE_ONLY, RDMA_WRITE_FIRST, etc., and the reassembly is done on the reply message. The RPC reply packet has no data (RDMA_NOMSG) but fragments are reassembled and the whole RPC reply is dissected. The RDMA read chunk list is used for a large RPC call which has at least one large opaque, e.g., NFS WRITE. The RPC call packet is used only to set up the RDMA read chunk list. It also has the reduced message data which includes the first fragment (XDR data up to and including the opaque length), but it could also have fragments between each read chunk and the last fragment after the last read chunk data. The reduced message is then broken down into fragments and inserted into the reassembly table. Since the RDMA read chunk list is set up in the RPC call then do not dissect the upper layer in this case and just label rest of packet as "Data" since the reassembly will be done on the last read response. The protocol gives the XDR position where each chunk must be inserted into the XDR stream thus as long as the maximum I/O size is known it is possible to know exactly where to insert these fragments. This maximum I/O size is set on the first READ_RESPONSE_FIRST or READ_RESPONSE_MIDDLE but in case where any of these packets have not been seen then a value of 100 is used (real value should be at least 1024) but in this case the message numbers are not consecutive between chunks but since the total size of all chunks is verified to make sure there is a complete message to reassemble then all fragments should be in the correct order. Fragments are added on any RDMA read packet: RDMA_READ_RESPONSE_ONLY, RDMA_READ_RESPONSE_FIRST, etc., and the reassembly is done on the last read response. Since there could be multiple chunks and each chunk could have multiple segments then the total size must be checked to complete the reassembly because in this case there will be multiple READ_RESPONSE_LAST. The RDMA write chunk list is used for a large RPC reply which has at least one large opaque, e.g., NFS READ. The RPC call packet is used only to set up the RDMA write chunk list. The opaque data is then transferred via RDMA writes and then the RPC reply packet is sent from the server. The RPC reply packet has the reduced message data which includes the first fragment (XDR data up to and including the opaque length), but it could also have fragments between each write chunk and the last fragment after the last write chunk data. The reduced message is then broken down into fragments and inserted into the reassembly table. Since the RPC reply is sent after all the RDMA writes then the fragments from these writes must be inserted in the correct order: the first RDMA write fragment is inserted with message number 1, since the first fragment (message number 0) will come from the very last packet (the RPC reply with RDMA_MSG). Also, the last packet could have fragments which must be inserted in between chunk data, therefore message numbers from one chunk to another are not consecutive. In contrast with the RDMA read chunk list, the protocol does not allow an XDR position in the RDMA write chunks, since the RPC client knows exactly where to insert the chunk's data because of the virtual address of the DDP (direct data placement) item. There is no way to map a virtual address with an XDR position, thus in order to reassemble the XDR stream a two pass approach is used. In the first pass (visited = 0), all RDMA writes are inserted as fragments leaving a gap in between each chunk. Then the dissector for the upper layer is called with a flag letting the dissector know that it is dealing with a reduced message so all DDP enabled operations handle the opaque data as having only the size of the opaque but not the data and reporting back the offset from the end of the message. Once the upper layer dissector returns, this layer now has a list of DDP eligible item's offsets which are then translated into XDR offsets and then the RPC reply packet is broken into fragments and inserted in the right places as in the case for the RDMA read chunk list. On the second pass (visited = 1), all fragments have already been inserted into the reassembly table so it just needs to reassembled the whole message and then call the upper layer dissector. RFC 8267 specifies the upper layer bindings to RPC-over-RDMA version 1 for NFS. Since RPC-over-RDMA version 1 specifies the XDR position for the read chunks then only the write chunk DDP eligible items are handled in the upper layer, in this case the NFS layer. These are the only procedures or operations eligible for write chunks: * The opaque data result in the NFS READ procedure or operation * The pathname or linkdata result in the NFS READLINK procedure or operation Two functions are defined to signal and report back the DDP eligible item's offset to be used by the upper layers. Function rpcrdma_is_reduced() is used to signal the upper layer that it is dealing with a reduced data message and thus should ignore DDP eligible item's opaque processing and just report back the offset where the opaque data should be. This reporting is done using the second function rpcrdma_insert_offset(). Reassembly is done for InfiniBand only. Reassemble fragments using the packet sequence number (PSN) of each RDMA I/O fragment to make sure the message is reassembled correctly when fragments are sent out of order. Also a unique message id is used for each message so fragments are reassembled correctly when fragments of different messages are sent in parallel. The reassembled message could be composed of multiple chunks and each chunk in turn could be composed of multiple segments in which each segment could be composed of multiple requests and of course each request is composed of one or more fragments. Thus in order to have all fragments for each segment belonging to the same message, a list of segments is created and all segments belonging to the same message are initialized with the same message id. These segments are initialized and added to the list on the call side on RDMA_MSG by calling process_rdma_lists. Bug: 13260 Change-Id: Icf57d7c46c3ba1de5d019265eb151a81d6019dfd Reviewed-on: https://code.wireshark.org/review/24613 Petri-Dish: Anders Broman <a.broman58@gmail.com> Tested-by: Petri Dish Buildbot Reviewed-by: Anders Broman <a.broman58@gmail.com> |
||
|---|---|---|
| .tx | ||
| capchild | ||
| caputils | ||
| cmake | ||
| codecs | ||
| debian | ||
| diameter | ||
| doc | ||
| docbook | ||
| dtds | ||
| epan | ||
| extcap | ||
| fix | ||
| help | ||
| idl | ||
| image | ||
| m4 | ||
| macosx-support-lib-patches | ||
| packaging | ||
| plugins | ||
| profiles | ||
| radius | ||
| randpkt_core | ||
| test | ||
| tools | ||
| tpncp | ||
| ui | ||
| wimaxasncp | ||
| wiretap | ||
| writecap | ||
| wsutil | ||
| .bzrignore | ||
| .editorconfig | ||
| .gitattributes | ||
| .gitignore | ||
| .gitlab-ci.yml | ||
| .gitreview | ||
| .mailmap | ||
| .travis.yml | ||
| AUTHORS | ||
| AUTHORS.src | ||
| CMakeLists.txt | ||
| CMakeListsCustom.txt.example | ||
| CMakeOptions.txt | ||
| COPYING | ||
| ChangeLog | ||
| ConfigureChecks.cmake | ||
| INSTALL | ||
| INSTALL.configure | ||
| Makefile.am | ||
| Makefile.am.inc | ||
| NEWS | ||
| README.DECT | ||
| README.aix | ||
| README.bsd | ||
| README.hpux | ||
| README.linux | ||
| README.macos | ||
| README.md | ||
| README.windows | ||
| Vagrantfile | ||
| abi-descriptor.template | ||
| acinclude.m4 | ||
| autogen.sh | ||
| capinfos.c | ||
| capture_info.c | ||
| capture_info.h | ||
| capture_opts.c | ||
| capture_opts.h | ||
| capture_stop_conditions.c | ||
| capture_stop_conditions.h | ||
| captype.c | ||
| cfile.c | ||
| cfile.h | ||
| cfilters | ||
| cmakeconfig.h.in | ||
| colorfilters | ||
| conditions.c | ||
| conditions.h | ||
| config.guess | ||
| config.sub | ||
| configure.ac | ||
| dfilter_macros | ||
| dfilters | ||
| dftest.c | ||
| doxygen.cfg.in | ||
| doxygen_global.cfg | ||
| dumpcap.c | ||
| editcap.c | ||
| enterprises.tsv | ||
| extcap.c | ||
| extcap.h | ||
| extcap_parser.c | ||
| extcap_parser.h | ||
| file.c | ||
| file.h | ||
| file_packet_provider.c | ||
| fileset.c | ||
| fileset.h | ||
| frame_tvbuff.c | ||
| frame_tvbuff.h | ||
| globals.h | ||
| log.h | ||
| make-version.pl | ||
| manuf | ||
| manuf.tmpl | ||
| mergecap.c | ||
| mmdbresolve.c | ||
| pdml2html.xsl | ||
| randpkt.c | ||
| rawshark.c | ||
| reordercap.c | ||
| ringbuffer.c | ||
| ringbuffer.h | ||
| services | ||
| sharkd.c | ||
| sharkd.h | ||
| sharkd_daemon.c | ||
| sharkd_session.c | ||
| smi_modules | ||
| sync_pipe.h | ||
| sync_pipe_write.c | ||
| text2pcap-scanner.l | ||
| text2pcap.c | ||
| text2pcap.h | ||
| tfshark.c | ||
| trigcap.c | ||
| tshark.c | ||
| vagrant_build.sh | ||
| vagrant_provision.sh | ||
| version_info.c | ||
| version_info.h | ||
| wireshark-gtk.desktop | ||
| wireshark-mime-package.xml | ||
| wireshark-qt.cpp | ||
| wireshark.appdata.xml | ||
| wireshark.desktop | ||
| wireshark.dox | ||
| wireshark.pc.in | ||
| wka | ||
| ws_attributes.h | ||
| ws_compiler_tests.h | ||
| ws_diag_control.h | ||
| ws_symbol_export.h | ||
README.md
General Information
Wireshark is a network traffic analyzer, or "sniffer", for Unix and Unix-like operating systems. It uses Qt, a graphical user interface library, and libpcap, a packet capture and filtering library.
The Wireshark distribution also comes with TShark, which is a line-oriented sniffer (similar to Sun's snoop, or tcpdump) that uses the same dissection, capture-file reading and writing, and packet filtering code as Wireshark, and with editcap, which is a program to read capture files and write the packets from that capture file, possibly in a different capture file format, and with some packets possibly removed from the capture.
The official home of Wireshark is https://www.wireshark.org.
The latest distribution can be found in the subdirectory https://www.wireshark.org/download
Installation
The Wireshark project builds and tests regularly on the following platforms:
- Linux (Ubuntu)
- Microsoft Windows
- macOS / {Mac} OS X
Official installation packages are available for Microsoft Windows and macOS.
It is available as either a standard or add-on package for many popular operating sytems and Linux distributions including Debian, Ubuntu, Fedora, CentOS, RHEL, Arch, Gentoo, openSUSE, FreeBSD, DragonFly BSD, NetBSD, and OpenBSD.
Additionaly it is available through many third-party packaging systems such as pkgsrc, OpenCSW, Homebrew, and MacPorts.
It should run on other Unix-ish systems without too much trouble.
In some cases the current version of Wireshark might not support your operating system. This is the case for Windows XP, which is supported by Wireshark 1.10 and earlier. In other cases the standard package for Wireshark might simply be old. This is the case for Solaris and HP-UX.
NOTE: The Makefile depends on GNU "make"; it doesn't appear to work with the "make" that comes with Solaris 7 nor the BSD "make".
Both Perl and Python are needed, the former for building the man pages.
If you decide to modify the yacc grammar or lex scanner, then
you need "flex" - it cannot be built with vanilla "lex" -
and either "bison" or the Berkeley "yacc". Your flex
version must be 2.5.1 or greater. Check this with flex -V.
You must therefore install Perl, Python, GNU "make", "flex", and either "bison" or Berkeley "yacc" on systems that lack them.
Full installation instructions can be found in the INSTALL file and in the Developer's Guide at https://www.wireshark.org/docs/wsdg_html_chunked/
See also the appropriate README.OS files for OS-specific installation instructions.
Usage
In order to capture packets from the network, you need to make the
dumpcap program set-UID to root, or you need to have access to the
appropriate entry under /dev if your system is so inclined (BSD-derived
systems, and systems such as Solaris and HP-UX that support DLPI,
typically fall into this category). Although it might be tempting to
make the Wireshark and TShark executables setuid root, or to run them as
root please don't. The capture process has been isolated in dumpcap;
this simple program is less likely to contain security holes, and thus
safer to run as root.
Please consult the man page for a description of each command-line option and interface feature.
Multiple File Types
The wiretap library is a packet-capture library currently under development parallel to wireshark. In the future it is hoped that wiretap will have more features than libpcap, but wiretap is still in its infancy. However, wiretap is used in wireshark for its ability to read multiple file types. See the Wireshark man page or the Wireshark User's Guide for a list of supported file formats.
In addition, it can read gzipped versions of any of those files
automatically, if you have the zlib library available when compiling
Wireshark. Wireshark needs a modern version of zlib to be able to use
zlib to read gzipped files; version 1.1.3 is known to work. Versions
prior to 1.0.9 are missing some functions that Wireshark needs and won't
work. ./configure should detect if you have the proper zlib version
available and, if you don't, should disable zlib support. You can always
use ./configure --disable-zlib to explicitly disable zlib support.
Although Wireshark can read AIX iptrace files, the documentation on
AIX's iptrace packet-trace command is sparse. The iptrace command
starts a daemon which you must kill in order to stop the trace. Through
experimentation it appears that sending a HUP signal to that iptrace
daemon causes a graceful shutdown and a complete packet is written
to the trace file. If a partial packet is saved at the end, Wireshark
will complain when reading that file, but you will be able to read all
other packets. If this occurs, please let the Wireshark developers know
at wireshark-dev@wireshark.org, and be sure to send us a copy of that trace
file if it's small and contains non-sensitive data.
Support for Lucent/Ascend products is limited to the debug trace output
generated by the MAX and Pipline series of products. Wireshark can read
the output of the wandsession wandisplay, wannext, and wdd
commands.
Wireshark can also read dump trace output from the Toshiba "Compact Router"
line of ISDN routers (TR-600 and TR-650). You can telnet to the router
and start a dump session with snoop dump.
CoSine L2 debug output can also be read by Wireshark. To get the L2
debug output, get in the diags mode first and then use
create-pkt-log-profile and apply-pkt-lozg-profile commands under
layer-2 category. For more detail how to use these commands, you
should examine the help command by layer-2 create ? or layer-2 apply ?.
To use the Lucent/Ascend, Toshiba and CoSine traces with Wireshark, you must
capture the trace output to a file on disk. The trace is happening inside
the router and the router has no way of saving the trace to a file for you.
An easy way of doing this under Unix is to run telnet <ascend> | tee <outfile>.
Or, if your system has the "script" command installed, you can save
a shell session, including telnet to a file. For example, to a file named
tracefile.out:
$ script tracefile.out
Script started on <date/time>
$ telnet router
..... do your trace, then exit from the router's telnet session.
$ exit
Script done on <date/time>
Name Resolution
Wireshark will attempt to use reverse name resolution capabilities when decoding IPv4 and IPv6 packets.
If you want to turn off name resolution while using Wireshark, start
Wireshark with the -n option to turn off all name resolution (including
resolution of MAC addresses and TCP/UDP/SMTP port numbers to names), or
with the -N mt option to turn off name resolution for all
network-layer addresses (IPv4, IPv6, IPX).
You can make that the default setting by opening the Preferences dialog box using the Preferences item in the Edit menu, selecting "Name resolution", turning off the appropriate name resolution options, clicking "Save", and clicking "OK".
SNMP
Wireshark can do some basic decoding of SNMP packets; it can also use
the libsmi library to do more sophisticated decoding, by reading MIB
files and using the information in those files to display OIDs and
variable binding values in a friendlier fashion. The configure script
will automatically determine whether you have the libsmi library on
your system. If you have the libsmi library but do not want to have
Wireshark use it, you can run configure with the --without-libsmi
option.
How to Report a Bug
Wireshark is under constant development, so it is possible that you will encounter a bug while using it. Please report bugs at https://bugs.wireshark.org. Be sure you enter into the bug:
-
The complete build information from the "About Wireshark" item in the Help menu or the output of
wireshark -vfor Wireshark bugs and the output oftshark -vfor TShark bugs; -
If the bug happened on Linux, the Linux distribution you were using, and the version of that distribution;
-
The command you used to invoke Wireshark, if you ran Wireshark from the command line, or TShark, if you ran TShark, and the sequence of operations you performed that caused the bug to appear.
If the bug is produced by a particular trace file, please be sure to attach to the bug a trace file along with your bug description. If the trace file contains sensitive information (e.g., passwords), then please do not send it.
If Wireshark died on you with a 'segmentation violation', 'bus error', 'abort', or other error that produces a UNIX core dump file, you can help the developers a lot if you have a debugger installed. A stack trace can be obtained by using your debugger ('gdb' in this example), the wireshark binary, and the resulting core file. Here's an example of how to use the gdb command 'backtrace' to do so.
$ gdb wireshark core
(gdb) backtrace
..... prints the stack trace
(gdb) quit
$
The core dump file may be named "wireshark.core" rather than "core" on some platforms (e.g., BSD systems). If you got a core dump with TShark rather than Wireshark, use "tshark" as the first argument to the debugger; the core dump may be named "tshark.core".
Disclaimer
There is no warranty, expressed or implied, associated with this product. Use at your own risk.
Gerald Combs gerald@wireshark.org
Gilbert Ramirez gram@alumni.rice.edu
Guy Harris guy@alum.mit.edu