help/faq.py

   1 #!/usr/bin/env python
   2 #
   3 # faq.py
   4 #
   5 # Routines to assemble a FAQ list for the Wireshark web site.
   6 # Questions and answer content can be found below. Section and
   7 # question numbers will be automatically generated.
   8 #
   9 # $Id$
  10
  11 import sys
  12 import string
  13
  14 class faq_section:
  15         def __init__(self, name, secnum):
  16                 self.name = name
  17                 self.secnum = secnum
  18                 self.qa = []
  19                 self.subsecs = []
  20
  21         def add_qa(self, question, answer, tag):
  22                 q_num = len(self.qa) + 1
  23                 q_id = "%s.%d" % (self.get_num_string(), q_num)
  24                 self.qa.append( (q_id, question, answer, tag) )
  25
  26         def get_all_qa(self):
  27                 return self.qa
  28
  29         def add_subsec(self, subsec):
  30                 self.subsecs.append(subsec)
  31
  32         def get_all_subsecs(self):
  33                 return self.subsecs
  34
  35         def get_num_string(self):
  36                 return "%d" % (self.secnum)
  37
  38         def get_name(self):
  39                 return self.name
  40
  41         def get_num_name(self):
  42                 return "%s. %s" % (self.get_num_string(), self.name)
  43
  44         def get_header_level(self):
  45                 return 3
  46
  47         def print_index(self):
  48                 print(("<a href=#sec%s><h%d>%s:</h%d></a>\n" % (self.get_num_string(), self.get_header_level(), self.get_num_name(), self.get_header_level())))
  49                 for qa in self.qa:
  50                         id = qa[0]
  51                         question = qa[1]
  52                         print('<p class="faq_q">')
  53                         print(('<a class="faq_qnum" href=#q%s>%s %s</a>\n' % (id, id, question)))
  54                         print('</p>')
  55                 for subsec in self.subsecs:
  56                         subsec.print_index()
  57
  58         def print_contents(self):
  59                 # Table header
  60                 print(("""
  61   <a name="sec%s">
  62     <h%d>%s</h%d>
  63   </a>
  64 """ % (self.get_num_string(), self.get_header_level(), self.get_num_name(), self.get_header_level())))
  65
  66                 # Questions and Answers
  67                 for qa in self.qa:
  68                         id = qa[0]
  69                         question = qa[1]
  70                         answer = qa[2]
  71                         tag = qa[3]
  72
  73                         print('<p class="faq_q">')
  74                         print(('<a class="faq_qnum" name=q%s>Q %s:</a>' % (id, id)))
  75                         if tag is not None:
  76                                 print(('<a name=%s>' % tag))
  77                         print(('<span>%s</span>' % (question)))
  78                         if tag is not None:
  79                                 print('</a>')
  80                         print('</p>')
  81
  82                         print('<p class="faq_a">')
  83                         print('<span class="faq_anum">A:</span>\n')
  84                         print(answer)
  85                         print('</p>')
  86
  87                 # Subsections
  88                 for subsec in self.subsecs:
  89                         subsec.print_contents()
  90
  91                 # Table footer
  92                 print("")
  93
  94 class faq_subsection(faq_section):
  95         def __init__(self, name, secnum, subsecnum):
  96                 self.name = name
  97                 self.secnum = secnum
  98                 self.subsecnum = subsecnum
  99                 self.qa = []
 100                 self.subsecs = []
 101
 102         def get_num_string(self):
 103                 return "%d.%d" % (self.secnum, self.subsecnum)
 104
 105         def get_header_level(self):
 106                 return 2
 107
 108 class faq_subsubsection(faq_section):
 109         def __init__(self, name, secnum, subsecnum, subsubsecnum):
 110                 self.name = name
 111                 self.secnum = secnum
 112                 self.subsecnum = subsecnum
 113                 self.subsubsecnum = subsubsecnum
 114                 self.qa = []
 115                 self.subsecs = []
 116
 117         def get_num_string(self):
 118                 return "%d.%d.%d" % (self.secnum, self.subsecnum, self.subsubsecnum)
 119
 120         def get_header_level(self):
 121                 return 2
 122
 123 sec_num = 0
 124 subsec_num = 0
 125 subsubsec_num = 0
 126 sections = []
 127 current_section = None
 128 parent_section = None
 129 grandparent_section = None
 130 current_question = None
 131 current_tag = None
 132
 133 # Make a URL of itself
 134 def selflink(text):
 135         return "<a href=\"%s\">%s</a>" % (text, text)
 136
 137 # Add a section
 138 def section(name):
 139         global sec_num
 140         global subsec_num
 141         global subsubsec_num
 142         global current_section
 143         global grandparent_section
 144         assert not current_question
 145         sec_num = sec_num + 1
 146         subsec_num = 0
 147         subsubsec_num = 0
 148         sec = faq_section(name, sec_num)
 149         sections.append(sec)
 150         current_section = sec
 151         grandparent_section = sec
 152
 153 # Add a subsection
 154 def subsection(name):
 155         global subsec_num
 156         global subsubsec_num
 157         global current_section
 158         global parent_section
 159         global grandparent_section
 160         assert not current_question
 161         subsec_num = subsec_num + 1
 162         subsubsec_num = 0
 163         sec = faq_subsection(name, sec_num, subsec_num)
 164         grandparent_section.add_subsec(sec)
 165         current_section = sec
 166         parent_section = sec
 167
 168 # Add a subsubsection
 169 def subsubsection(name):
 170         global subsubsec_num
 171         global current_section
 172         global parent_section
 173         assert not current_question
 174         subsubsec_num = subsubsec_num + 1
 175         sec = faq_subsubsection(name, sec_num, subsec_num, subsubsec_num)
 176         parent_section.add_subsec(sec)
 177         current_section = sec
 178
 179 # Add a question
 180 def question(text, tag=None):
 181         global current_question
 182         global current_tag
 183         assert current_section
 184         assert not current_question
 185         assert not current_tag
 186         current_question = text
 187         current_tag = tag
 188
 189 # Add an answer
 190 def answer(text):
 191         global current_question
 192         global current_tag
 193         assert current_section
 194         assert current_question
 195         current_section.add_qa(current_question, text, current_tag)
 196         current_question = None
 197         current_tag = None
 198
 199
 200 # Create the index
 201 def create_index():
 202         print("""
 203   <a name="index">
 204     <h1>Index</h1>
 205   </a>
 206 """)
 207         for sec in sections:
 208                 sec.print_index()
 209
 210         print("""
 211 """)
 212
 213
 214 # Print result
 215 def create_output(header='', footer=''):
 216
 217         print(header)
 218         create_index()
 219
 220         for sec in sections:
 221                 sec.print_contents()
 222
 223         print(footer)
 224
 225 def main():
 226         header = '''\
 227 <?xml version="1.0" encoding="UTF-8"?>
 228 <!DOCTYPE html
 229   PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
 230   "DTD/xhtml1-strict.dtd">
 231 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 232 <head>
 233   <title>Wireshark FAQ</title>
 234 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
 235 </head>
 236 <body>
 237 '''
 238         footer = '''\
 239 </body>
 240 </html>
 241 '''
 242
 243         if len(sys.argv) > 1 and sys.argv[1] == '-b': # Only print the document body
 244                 header = ''
 245                 footer = ''
 246
 247         create_output(header, footer)
 248
 249 #################################################################
 250 section("General Questions")
 251 #################################################################
 252
 253 question("What is Wireshark?")
 254 answer("""
 255 Wireshark&#174; is a network protocol analyzer. It lets you capture and
 256 interactively browse the traffic running on a computer network.  It has
 257 a rich and powerful feature set and is world's most popular tool of its
 258 kind. It runs on most computing platforms including Windows, OS X,
 259 Linux, and UNIX. Network professionals, security experts, developers,
 260 and educators around the world use it regularly. It is freely available
 261 as open source, and is released under the GNU General Public License
 262 version 2.
 263
 264 <br />
 265
 266 It is developed and maintained by a global team of protocol experts, and
 267 it is an example of a
 268 <a href="http://en.wikipedia.org/wiki/Disruptive_technology">disruptive
 269 technology</a>.
 270
 271 <br />
 272
 273 Wireshark used to be known as Ethereal&#174;.  See the next question
 274 for details about the name change.  If you're still using Ethereal, it
 275 is <a href="http://www.ethereal.com/appnotes/enpa-sa-00024.html">strongly
 276 recommended that you upgrade to Wireshark</a>.
 277
 278 <br />
 279
 280 For more information, please see the
 281 <a href="/about.html">About Wireshark</a>
 282 page.
 283 """)
 284
 285
 286 question("What's up with the name change?  Is Wireshark a fork?")
 287 answer("""
 288 In May of 2006, Gerald Combs (the original author of Ethereal)
 289 went to work for CACE Technologies (best known for WinPcap).
 290 Unfortunately, he had to leave the Ethereal trademarks behind.
 291
 292 <br />
 293
 294 This left the project in an awkward position.  The only reasonable way
 295 to ensure the continued success of the project was to change the name.
 296 This is how Wireshark was born.
 297
 298 <br />
 299
 300 Wireshark is almost (but not quite) a fork. Normally a "fork" of an open source
 301 project results in two names, web sites, development teams, support
 302 infrastructures, etc. This is the case with Wireshark except for one notable
 303 exception -- every member of the core development team is now working on
 304 Wireshark. There has been no active development on Ethereal since the name
 305 change. Several parts of the Ethereal web site (such as the mailing lists,
 306 source code repository, and build farm) have gone offline.
 307
 308 <br />
 309
 310 More information on the name change can be found here:
 311
 312 <ul class="item_list">
 313
 314   <li><href url="http://www.prweb.com/releases/2006/6/prweb396098.htm" name="Original press release">
 315   <li><href url="http://trends.newsforge.com/article.pl?sid=06/06/09/1349255&from=rss" name="NewsForge article">
 316   <li>Many other articles in <href url="bibliography.html" name="our bibliography">
 317 </ul>
 318 """)
 319
 320
 321 question("Where can I get help?")
 322 answer("""
 323 Community support is available on the
 324 <a href="http://ask.wireshark.org/">Q&amp;A site</a> and on the
 325 wireshark-users mailing list.  Subscription information and archives for
 326 all of Wireshark's mailing lists can be found at %s.  An IRC channel
 327 dedicated to Wireshark can be found at %s.
 328
 329 <br />
 330
 331 Self-paced and instructor-led training is available at <a
 332 href="http://www.wiresharktraining.com">Wireshark University</a>.
 333 Wireshark University also offers certification via the Wireshark
 334 Certified Network Analyst program.
 335
 336 """ % (selflink("https://www.wireshark.org/mailman/listinfo"),
 337        selflink("irc://irc.freenode.net/wireshark")
 338        ))
 339
 340
 341 question("What kind of shark is Wireshark?")
 342 answer("""
 343 <i>carcharodon photoshopia</i>.
 344 """)
 345
 346
 347 question("How is Wireshark pronounced, spelled and capitalized?")
 348 answer("""
 349 Wireshark is pronounced as the word <i>wire</i> followed immediately by
 350 the word <i>shark</i>.  Exact pronunciation and emphasis may vary
 351 depending on your locale (e.g. Arkansas).
 352
 353 <br />
 354
 355 It's spelled with a capital <i>W</i>, followed by a lower-case
 356 <i>ireshark</i>.  It is not a CamelCase word, i.e., <i>WireShark</i>
 357 is incorrect.
 358 """)
 359
 360
 361 question("How much does Wireshark cost?", "but_thats_not_all")
 362 answer("""
 363 Wireshark is "free software"; you can download it without paying any
 364 license fee.  The version of Wireshark you download isn't a "demo"
 365 version, with limitations not present in a "full" version; it
 366 <em>is</em> the full version.
 367
 368 <br />
 369
 370 The license under which Wireshark is issued is <a
 371 href="http://www.gnu.org/licenses/gpl.html">the GNU General Public
 372 License version 2</a>.  See <a href="http://www.gnu.org/licenses/gpl-faq.html">the
 373 GNU GPL FAQ</a> for some more information.
 374 """)
 375
 376 question("But I just paid someone on eBay for a copy of Wireshark! Did I get ripped off?")
 377 answer("""
 378 That depends. Did they provide any sort of value-added product or service, such
 379 as installation support, installation media, training, trace file analysis, or
 380 funky-colored shark-themed socks? Probably not.
 381
 382 <br />
 383
 384 Wireshark is <a href="/download.html">available for anyone to download,
 385 absolutely free, at any time</a>. Paying for a copy implies that you should
 386 get something for your money.
 387 """)
 388
 389 question("Can I use Wireshark commercially?")
 390 answer("""
 391 Yes, if, for example, you mean "I work for a commercial organization;
 392 can I use Wireshark to capture and analyze network traffic in our
 393 company's networks or in our customer's networks?"
 394
 395 <br />
 396
 397 If you mean "Can I use Wireshark as part of my commercial product?", see
 398 <a href="#derived_work_gpl">the next entry in the FAQ</a>.
 399 """)
 400
 401
 402 question("Can I use Wireshark as part of my commercial product?",
 403 "derived_work_gpl")
 404
 405 answer("""
 406 As noted, Wireshark is licensed under <a
 407 href="http://www.gnu.org/licenses/gpl.html">the GNU General Public
 408 License</a>.  The GPL imposes conditions on your use of GPL'ed code in
 409 your own products; you cannot, for example, make a "derived work" from
 410 Wireshark, by making modifications to it, and then sell the resulting
 411 derived work and not allow recipients to give away the resulting work.
 412 You must also make the changes you've made to the Wireshark source
 413 available to all recipients of your modified version; those changes
 414 must also be licensed under the terms of the GPL.  See the <a
 415 href="http://www.gnu.org/licenses/gpl-faq.html">GPL FAQ</a> for more
 416 details; in particular, note the answer to <a
 417 href="http://www.gnu.org/licenses/gpl-faq.html#GPLCommercially">the
 418 question about modifying a GPLed program and selling it
 419 commercially</a>, and <a
 420 href="http://www.gnu.org/licenses/gpl-faq.html#LinkingWithGPL">the
 421 question about linking GPLed code with other code to make a proprietary
 422 program</a>.
 423
 424 <br />
 425
 426 You can combine a GPLed program such as Wireshark and a commercial
 427 program as long as they communicate "at arm's length", as per <a
 428 href="http://www.gnu.org/licenses/gpl-faq.html#GPLInProprietarySystem">this
 429 item in the GPL FAQ</a>.
 430
 431 <br />
 432
 433 We recommend keeping Wireshark and your product completely separate,
 434 communicating over sockets or pipes. If you're loading any part of
 435 Wireshark as a DLL, you're probably doing it wrong.
 436 """)
 437
 438 question("What protocols are currently supported?")
 439 answer("""
 440 There are currently hundreds of supported
 441 protocols and media.  Details can be found in the
 442 <a href="/docs/man-pages/wireshark.html">wireshark(1)</a> man page.
 443 """)
 444
 445
 446 question("Are there any plans to support {your favorite protocol}?")
 447 answer("""
 448 Support for particular protocols is added to Wireshark as a result of
 449 people contributing that support; no formal plans for adding support for
 450 particular protocols in particular future releases exist.
 451 """)
 452
 453
 454 question("""Can Wireshark read capture files from {your favorite network
 455 analyzer}?""")
 456
 457 answer("""
 458 Support for particular protocols is added to Wireshark as a result of
 459 people contributing that support; no formal plans for adding support for
 460 particular protocols in particular future releases exist.
 461
 462 <br />
 463
 464 If a network analyzer writes out files in a format already supported by
 465 Wireshark (e.g., in libpcap format), Wireshark may already be able to read
 466 them, unless the analyzer has added its own proprietary extensions to
 467 that format.
 468
 469 <br />
 470
 471 If a network analyzer writes out files in its own format, or has added
 472 proprietary extensions to another format, in order to make Wireshark read
 473 captures from that network analyzer, we would either have to have a
 474 specification for the file format, or the extensions, sufficient to give
 475 us enough information to read the parts of the file relevant to
 476 Wireshark, or would need at least one capture file in that format
 477 <strong>AND</strong> a detailed textual analysis of the packets in that
 478 capture file (showing packet time stamps, packet lengths, and the
 479 top-level packet header) in order to reverse-engineer the file
 480 format.
 481
 482 <br />
 483
 484 Note that there is no guarantee that we will be able to reverse-engineer
 485 a capture file format.
 486 """)
 487
 488
 489 question("What devices can Wireshark use to capture packets?")
 490 answer("""
 491 Wireshark can read live data from Ethernet, Token-Ring, FDDI, serial (PPP
 492 and SLIP) (if the OS on which it's running allows Wireshark to do so),
 493 802.11 wireless LAN (if the OS on which it's running allows Wireshark to
 494 do so), ATM connections (if the OS on which it's running allows Wireshark
 495 to do so), and the "any" device supported on Linux by recent versions of
 496 libpcap.
 497
 498 <br />
 499
 500 See <a href="http://wiki.wireshark.org/CaptureSetup/NetworkMedia">the list of
 501 supported capture media on various OSes</a> for details (several items
 502 in there say "Unknown", which doesn't mean "Wireshark can't capture on
 503 them", it means "we don't know whether it can capture on them"; we
 504 expect that it will be able to capture on many of them, but we haven't
 505 tried it ourselves - if you try one of those types and it works, please
 506 update the wiki page accordingly.
 507
 508 <br />
 509
 510 It can also read a variety of capture file formats, including:
 511
 512 <ul>
 513
 514 <li> AG Group/WildPackets EtherPeek/TokenPeek/AiroPeek/EtherHelp/Packet Grabber captures
 515 <li> AIX's iptrace captures
 516 <li> Accellent's 5Views LAN agent output
 517 <li> Cinco Networks NetXRay captures
 518 <li> Cisco Secure Intrusion Detection System IPLog output
 519 <li> CoSine L2 debug output
 520 <li> DBS Etherwatch VMS text output
 521 <li> Endace Measurement Systems' ERF format captures
 522 <li> EyeSDN USB S0 traces
 523 <li> HP-UX nettl captures
 524 <li> ISDN4BSD project i4btrace captures
 525 <li> Linux Bluez Bluetooth stack hcidump -w traces
 526 <li> Lucent/Ascend router debug output
 527 <li> Microsoft Network Monitor captures
 528 <li> Network Associates Windows-based Sniffer captures
 529 <li> Network General/Network Associates DOS-based Sniffer (compressed or uncompressed) captures
 530 <li> Network Instruments Observer version 9 captures
 531 <li> Novell LANalyzer captures
 532 <li> RADCOM's WAN/LAN analyzer captures
 533 <li> Shomiti/Finisar Surveyor captures
 534 <li> Toshiba's ISDN routers dump output
 535 <li> VMS TCPIPtrace/TCPtrace/UCX$TRACE output
 536 <li> Visual Networks' Visual UpTime traffic capture
 537 <li> libpcap, tcpdump and various other tools using tcpdump's capture format
 538 <li> snoop and atmsnoop output
 539
 540 </ul>
 541
 542 so that it can read traces from various network types, as captured by
 543 other applications or equipment, even if it cannot itself capture on
 544 those network types.
 545 """)
 546
 547 question("""
 548 Does Wireshark work on Windows Vista or Windows Server 2008?
 549 """)
 550
 551 answer("""
 552 Yes, but if you want to capture packets as a normal user, you must make sure
 553 npf.sys is loaded. Wireshark's installer enables this by default. This is not a
 554 concern if you run Wireshark as Administrator, but this is discouraged. See the
 555 <a
 556 href="http://wiki.wireshark.org/CaptureSetup/CapturePrivileges#windows">CapturePrivileges</a>
 557 page on the wiki for more details.
 558 """)
 559
 560 #################################################################
 561 section("Downloading Wireshark")
 562 #################################################################
 563
 564
 565 question("""Why do I get an error when I try to run the Win32 installer?""")
 566
 567 answer("""
 568 The program you used to download it may have downloaded it incorrectly.
 569 Web browsers and download accelerators sometimes may do this.
 570
 571 <br />
 572
 573 Try downloading it with, for example:
 574 <ul>
 575 <li>Wget, for which Windows binaries are available from <a
 576 href="http://www.christopherlewis.com/WGet/WGetFiles.htm">Christopher Lewis</a>
 577 or
 578 <a href="http://www.jensroesner.de/wgetgui/">wGetGUI</a>, which offers a GUI
 579 interface that uses wget;
 580
 581 <li>WS_FTP from <a href="http://www.ipswitch.com/">Ipswitch</a>,
 582
 583 <li>the <tt>ftp</tt> command that comes with Windows.
 584
 585 </ul>
 586
 587 If you use the <tt>ftp</tt> command, make sure you do the transfer in
 588 binary mode rather than ASCII mode, by using the <tt>binary</tt> command
 589 before transferring the file.
 590 """)
 591
 592
 593
 594 #################################################################
 595 section("Installing Wireshark")
 596 #################################################################
 597
 598
 599 question("""I installed the Wireshark RPM (or other package); why did
 600 it install TShark but not Wireshark?""")
 601
 602 answer("""
 603 Many distributions have separate Wireshark packages, one for non-GUI
 604 components such as TShark, editcap, dumpcap, etc. and one for the GUI.
 605 If this is the case on your system, there's probably a separate package
 606 named <tt>wireshark-gnome</tt> or <tt>wireshark-gtk+</tt>.  Find it and
 607 install it.
 608 """)
 609
 610
 611 #################################################################
 612 section("Building Wireshark")
 613 #################################################################
 614
 615
 616 question("""I have libpcap installed; why did the configure script not
 617 find pcap.h or bpf.h?""")
 618
 619 answer("""
 620 Are you sure pcap.h and bpf.h are installed?  The official distribution
 621 of libpcap only installs the libpcap.a library file when "make install"
 622 is run.  To install pcap.h and bpf.h, you must run "make install-incl".
 623 If you're running Debian or Redhat, make sure you have the "libpcap-dev"
 624 or "libpcap-devel" packages installed.
 625
 626 <br />
 627
 628 It's also possible that pcap.h and bpf.h have been installed in a strange
 629 location.  If this is the case, you may have to tweak aclocal.m4.
 630 """)
 631
 632
 633 question("""
 634 Why do I get the error
 635
 636 <blockquote><samp>dftest_DEPENDENCIES was already defined in condition TRUE,
 637 which implies condition HAVE_PLUGINS_TRUE</samp></blockquote>
 638
 639 when I try to build Wireshark from SVN or a SVN snapshot?
 640 """)
 641
 642 answer("""
 643 You probably have automake 1.5 installed on your machine (the command
 644 <kbd>automake --version</kbd> will report the version of automake on
 645 your machine).  There is a bug in that version of automake that causes
 646 this problem; upgrade to a later version of automake (1.6 or later).
 647 """)
 648
 649 question("""
 650 Why does the linker fail with a number of "Output line too long." messages
 651 followed by linker errors when I try to build Wireshark?
 652 """)
 653
 654 answer("""
 655 The version of the <tt>sed</tt> command on your system is incapable of
 656 handling very long lines.  On Solaris, for example,
 657 <tt>/usr/bin/sed</tt> has a line length limit too low to allow
 658 <tt>libtool</tt> to work; <tt>/usr/xpg4/bin/sed</tt> can handle it, as
 659 can GNU <tt>sed</tt> if you have it installed.
 660
 661 <br />
 662
 663 On Solaris, changing your command search path to search
 664 <tt>/usr/xpg4/bin</tt> before <tt>/usr/bin</tt> should make the problem
 665 go away; on any platform on which you have this problem, installing GNU
 666 <tt>sed</tt> and changing your command path to search the directory in
 667 which it is installed before searching the directory with the version of
 668 <tt>sed</tt> that came with the OS should make the problem go away.
 669 """)
 670
 671 question("""
 672 When I try to build Wireshark on Solaris, why does the link fail
 673 complaining that <tt>plugin_list</tt> is undefined?
 674 """)
 675
 676 answer("""
 677 This appears to be due to a problem with some versions of the GTK+ and
 678 GLib packages from www.sunfreeware.org; un-install those packages, and
 679 try getting the 1.2.10 versions from that site, or the versions from <a
 680 href="http://www.thewrittenword.com">The Written Word</a>, or the
 681 versions from Sun's GNOME distribution, or the versions from the
 682 supplemental software CD that comes with the Solaris media kit, or build
 683 them from source from <a href="http://www.gtk.org/">the GTK Web
 684 site</a>.  Then re-run the configuration script, and try rebuilding
 685 Wireshark.  (If you get the 1.2.10 versions from www.sunfreeware.org, and
 686 the problem persists, un-install them and try installing one of the
 687 other versions mentioned.)
 688 """)
 689
 690 question("""
 691 When I try to build Wireshark on Windows, why does the build fail because
 692 of conflicts between <tt>winsock.h</tt> and <tt>winsock2.h</tt>?
 693 """)
 694
 695 answer("""
 696 As of Wireshark 0.9.5, you must install WinPcap 2.3 or later, and the
 697 corresponding version of the developer's pack, in order to be able to
 698 compile Wireshark; it will not compile with older versions of the
 699 developer's pack.  The symptoms of this failure are conflicts between
 700 definitions in <tt>winsock.h</tt> and in <tt>winsock2.h</tt>; Wireshark
 701 uses <tt>winsock2.h</tt>, but pre-2.3 versions of the WinPcap
 702 developer's packet use <tt>winsock.h</tt>.  (2.3 uses
 703 <tt>winsock2.h</tt>, so if Wireshark were to use <tt>winsock.h</tt>, it
 704 would not be able to build with current versions of the WinPcap
 705 developer's pack.)
 706
 707 <br />
 708
 709 Note that the installed version of the developer's pack should be the
 710 same version as the version of WinPcap you have installed.
 711 """)
 712
 713 #################################################################
 714 section("Starting Wireshark")
 715 #################################################################
 716
 717
 718 question("""Why does Wireshark crash with a Bus Error when I try to run
 719 it on Solaris 8?""")
 720
 721 answer("""
 722 Some versions of the GTK+ library from www.sunfreeware.org appear to be
 723 buggy, causing Wireshark to drop core with a Bus Error.  Un-install those
 724 packages, and try getting the 1.2.10 version from that site, or the
 725 version from <a href="http://www.thewrittenword.com">The Written
 726 Word</a>, or the version from Sun's GNOME distribution, or the version
 727 from the supplemental software CD that comes with the Solaris media kit,
 728 or build it from source from <a href="http://www.gtk.org/">the GTK Web
 729 site</a>.  Update the GLib library to the 1.2.10 version, from the same
 730 source, as well.  (If you get the 1.2.10 versions from
 731 www.sunfreeware.org, and the problem persists, un-install them and try
 732 installing one of the other versions mentioned.)
 733
 734 <br />
 735
 736 Similar problems may exist with older versions of GTK+ for earlier
 737 versions of Solaris.
 738 """)
 739
 740 question("""When I run Wireshark on Windows NT, why does it die with a Dr.
 741 Watson error, reporting an "Integer division by zero" exception, when I
 742 start it?""")
 743
 744 answer("""
 745 In at least some case, this appears to be due to using the
 746 default VGA driver; if that's not the correct driver for your video
 747 card, try running the correct driver for your video card.
 748 """)
 749
 750 question("""When I try to run Wireshark, why does it complain about
 751 <tt>sprint_realloc_objid</tt> being undefined?""")
 752
 753 answer("""
 754 Wireshark can only be linked with version 4.2.2 or later of UCD SNMP.
 755 Your version of Wireshark was dynamically linked with such a version of
 756 UCD SNMP; however, you have an older version of UCD SNMP installed,
 757 which means that when Wireshark is run, it tries to link to the older
 758 version, and fails.  You will have to replace that version of UCD SNMP
 759 with version 4.2.2 or a later version.
 760 """)
 761
 762 question("""
 763 I've installed Wireshark from Fink on Mac OS X; why is it very slow to
 764 start up?
 765 """)
 766
 767 answer("""
 768 When an application is installed on OS X, prior to 10.4, it is usually
 769 "prebound" to speed up launching the application.  (That's what the
 770 "Optimizing" phase of installation is.)
 771
 772 <br />
 773
 774 Fink normally performs prebinding automatically when you install a
 775 package. However, in some rare cases, for whatever reason the prebinding
 776 caches get corrupt, and then not only does prebinding fail, but startup
 777 actually becomes much slower, because the system tries in vain to
 778 perform prebinding "on the fly" as you launch the application. This
 779 fails, causing sometimes huge delays.
 780
 781 <br />
 782
 783 To fix the prebinding caches, run the command
 784
 785 <pre>
 786         sudo /sw/var/lib/fink/prebound/update-package-prebinding.pl -f
 787 </pre>
 788 """)
 789
 790 #################################################################
 791 section("Crashes and other fatal errors")
 792 #################################################################
 793
 794
 795 question("""
 796 I have an XXX network card on my machine; if I try to capture on it, why
 797 does my machine crash or reset itself?
 798 """)
 799
 800 answer("""
 801 This is almost certainly a problem with one or more of:
 802
 803 <ul>
 804 <li>the operating system you're using;
 805 <li>the device driver for the interface you're using;
 806 <li>the libpcap/WinPcap library and, if this is Windows, the WinPcap
 807 device driver;
 808 </ul>
 809
 810 so:
 811
 812 <ul>
 813 <li>if you are using Windows, see <a
 814 href="http://www.winpcap.org/contact.htm">the WinPcap support
 815 page</a> - check the "Submitting bugs" section;
 816 <li>if you are using some Linux distribution, some version of BSD, or
 817 some other UNIX-flavored OS, you should report the problem to the
 818 company or organization that produces the OS (in the case of a Linux
 819 distribution, report the problem to whoever produces the distribution).
 820 </ul>
 821 """)
 822
 823 question("""
 824 Why does my machine crash or reset itself when I select "Start" from the
 825 "Capture" menu or select "Preferences" from the "Edit" menu?
 826 """)
 827
 828 answer("""
 829 Both of those operations cause Wireshark to try to build a list of the
 830 interfaces that it can open; it does so by getting a list of interfaces
 831 and trying to open them.  There is probably an OS, driver, or, for
 832 Windows, WinPcap bug that causes the system to crash when this happens;
 833 see the previous question.
 834 """)
 835
 836 #################################################################
 837 section("Capturing packets")
 838 #################################################################
 839
 840
 841 question("""When I use Wireshark to capture packets, why do I see only
 842 packets to and from my machine, or not see all the traffic I'm expecting
 843 to see from or to the machine I'm trying to monitor?""", "promiscsniff")
 844
 845 answer("""
 846 This might be because the interface on which you're capturing is plugged
 847 into an Ethernet or Token Ring switch; on a switched network, unicast
 848 traffic between two ports will not necessarily appear on other ports -
 849 only broadcast and multicast traffic will be sent to all ports.
 850
 851 <br />
 852
 853 Note that even if your machine is plugged into a hub, the "hub" may be
 854 a switched hub, in which case you're still on a switched network.
 855
 856 <br />
 857
 858 Note also that on the Linksys Web site, they say that their
 859 auto-sensing hubs "broadcast the 10Mb packets to the port that operate
 860 at 10Mb only and broadcast the 100Mb packets to the ports that operate
 861 at 100Mb only", which would indicate that if you sniff on a 10Mb port,
 862 you will not see traffic coming sent to a 100Mb port, and <i>vice
 863 versa</i>.  This problem has also been reported for Netgear dual-speed
 864 hubs, and may exist for other "auto-sensing" or "dual-speed" hubs.
 865
 866 <br />
 867
 868 Some switches have the ability to replicate all traffic on all ports to
 869 a single port so that you can plug your analyzer into that single port to
 870 sniff all traffic.  You would have to check the documentation for the
 871 switch to see if this is possible and, if so, to see how to do this.
 872 See <a href="http://wiki.wireshark.org/SwitchReference">the switch
 873 reference page</a> on <a href="http://wiki.wireshark.org/">the Wireshark
 874 Wiki</a> for information on some switches.  (Note that it's a Wiki, so
 875 you can update or fix that information, or add additional information on
 876 those switches or information on new switches, yourself.)
 877
 878 <br />
 879
 880 Note also that many firewall/NAT boxes have a switch built into them;
 881 this includes many of the "cable/DSL router" boxes.  If you have a box
 882 of that sort, that has a switch with some number of Ethernet ports into
 883 which you plug machines on your network, and another Ethernet port used
 884 to connect to a cable or DSL modem, you can, at least, sniff traffic
 885 between the machines on your network and the Internet by plugging
 886 the Ethernet port on the router going to the modem, the Ethernet port on
 887 the modem, and the machine on which you're running Wireshark into a hub
 888 (make sure it's not a switching hub, and that, if it's a dual-speed hub,
 889 all three of those ports are running at the same speed.
 890
 891 <br />
 892
 893 If your machine is <em>not</em> plugged into a switched network or a
 894 dual-speed hub, or it is plugged into a switched network but the port is
 895 set up to have all traffic replicated to it, the problem might be that
 896 the network interface on which you're capturing doesn't support
 897 "promiscuous" mode, or because your OS can't put the interface into
 898 promiscuous mode.  Normally, network interfaces supply to the host only:
 899
 900 <ul>
 901 <li>packets sent to one of that host's link-layer addresses;
 902 <li>broadcast packets;
 903 <li>multicast packets sent to a multicast address that the host has
 904                          configured the interface to accept.
 905 </ul>
 906
 907 Most network interfaces can also be put in "promiscuous" mode, in which
 908 they supply to the host all network packets they see.  Wireshark will try
 909 to put the interface on which it's capturing into promiscuous mode
 910 unless the "Capture packets in promiscuous mode" option is turned off in
 911 the "Capture Options" dialog box, and TShark will try to put the
 912 interface on which it's capturing into promiscuous mode unless the
 913 <tt>-p</tt> option was specified.  However, some network interfaces
 914 don't support promiscuous mode, and some OSes might not allow interfaces
 915 to be put into promiscuous mode.
 916
 917 <br />
 918
 919 If the interface is not running in promiscuous mode, it won't see any
 920 traffic that isn't intended to be seen by your machine.  It
 921 <strong>will</strong> see broadcast packets, and multicast packets sent
 922 to a multicast MAC address the interface is set up to receive.
 923
 924 <br />
 925
 926 You should ask the vendor of your network interface whether it supports
 927 promiscuous mode.  If it does, you should ask whoever supplied the
 928 driver for the interface (the vendor, or the supplier of the OS you're
 929 running on your machine) whether it supports promiscuous mode with that
 930 network interface.
 931
 932 <br />
 933
 934 In the case of token ring interfaces, the drivers for some of them, on
 935 Windows, may require you to enable promiscuous mode in order to capture
 936 in promiscuous mode.  See <a
 937 href="http://wiki.wireshark.org/CaptureSetup/TokenRing">the Wireshark
 938 Wiki item on Token Ring capturing</a> for details.
 939
 940 <br />
 941
 942 In the case of wireless LAN interfaces, it appears that, when those
 943 interfaces are promiscuously sniffing, they're running in a
 944 significantly different mode from the mode that they run in when they're
 945 just acting as network interfaces (to the extent that it would be a
 946 significant effort for those drivers to support for promiscuously
 947 sniffing <em>and</em> acting as regular network interfaces at the same
 948 time), so it may be that Windows drivers for those interfaces don't
 949 support promiscuous mode.
 950 """)
 951
 952 question("""When I capture with Wireshark, why can't I see any TCP
 953 packets other than packets to and from my machine, even though another
 954 analyzer on the network sees those packets?""")
 955
 956 answer("""
 957 You're probably not seeing <em>any</em> packets other than unicast
 958 packets to or from your machine, and broadcast and multicast packets; a
 959 switch will normally send to a port only unicast traffic sent to the MAC
 960 address for the interface on that port, and broadcast and multicast
 961 traffic - it won't send to that port unicast traffic sent to a MAC
 962 address for some other interface - and a network interface not in
 963 promiscuous mode will receive only unicast traffic sent to the MAC
 964 address for that interface, broadcast traffic, and multicast traffic
 965 sent to a multicast MAC address the interface is set up to receive.
 966
 967 <br />
 968
 969 TCP doesn't use broadcast or multicast, so you will only see your own
 970 TCP traffic, but UDP services may use broadcast or multicast so you'll
 971 see some UDP traffic - however, this is not a problem with TCP traffic,
 972 it's a problem with unicast traffic, as you also won't see all UDP
 973 traffic between other machines.
 974
 975 <br />
 976
 977 I.e., this is probably <a href="#promiscsniff">the same question
 978 as this earlier one</a>; see the response to that question.
 979 """)
 980
 981 question("""Why am I only seeing ARP packets when I try to capture
 982 traffic?""")
 983
 984 answer("""
 985 You're probably on a switched network, and running Wireshark on a machine
 986 that's not sending traffic to the switch and not being sent any traffic
 987 from other machines on the switch.  ARP packets are often broadcast
 988 packets, which are sent to all switch ports.
 989
 990 <br />
 991
 992 I.e., this is probably <a href="#promiscsniff">the same question
 993 as this earlier one</a>; see the response to that question.
 994 """)
 995
 996 question("""
 997 Why am I not seeing any traffic when I try to capture traffic?""")
 998
 999 answer("""
1000 Is the machine running Wireshark sending out any traffic on the network
1001 interface on which you're capturing, or receiving any traffic on that
1002 network, or is there any broadcast traffic on the network or multicast
1003 traffic to a multicast group to which the machine running Wireshark
1004 belongs?
1005
1006 <br />
1007
1008 If not, this may just be a problem with promiscuous sniffing, either due
1009 to running on a switched network or a dual-speed hub, or due to problems
1010 with the interface not supporting promiscuous mode; see the response to
1011 <a href="#promiscsniff">this earlier question</a>.
1012
1013 <br />
1014
1015 Otherwise, on Windows, see the response to <a href="#capprobwin">this
1016 question</a> and, on a UNIX-flavored OS, see the response to <a
1017 href="#capprobunix">this question</a>.
1018 """)
1019
1020 question("""
1021 Can Wireshark capture on (my T1/E1 line, SS7 links, etc.)?
1022 """)
1023
1024 answer("""
1025 Wireshark can only capture on devices supported by libpcap/WinPcap.  On
1026 most OSes, only devices that can act as network interfaces of the type
1027 that support IP are supported as capture devices for libpcap/WinPcap,
1028 although the device doesn't necessarily have to be running as an IP
1029 interface in order to support traffic capture.
1030
1031 <br />
1032
1033 On Linux and FreeBSD, libpcap 0.8 and later support the API for <a
1034 href="http://www.endace.com/products.htm">Endace Measurement Systems'
1035 DAG cards</a>, so that a system with one of those cards, and its driver
1036 and libraries, installed can capture traffic with those cards with
1037 libpcap-based applications.  You would either have to have a version of
1038 Wireshark built with that version of libpcap, or a dynamically-linked
1039 version of Wireshark and a shared libpcap library with DAG support, in
1040 order to do so with Wireshark.  You should ask Endace whether that could
1041 be used to capture traffic on, for example, your T1/E1 link.
1042
1043 <br />
1044
1045 See <a href="http://wiki.wireshark.org/CaptureSetup/SS7">the SS7 capture
1046 setup page</a> on <a href="http://wiki.wireshark.org/">the Wireshark
1047 Wiki</a> for current information on capturing SS7 traffic on TDM
1048 links.
1049 """)
1050
1051 question("""How do I put an interface into promiscuous mode?""")
1052
1053 answer("""
1054 By not disabling promiscuous mode when running Wireshark or TShark.
1055
1056 <br />
1057
1058 Note, however, that:
1059 <ul>
1060 <li>the form of promiscuous mode that libpcap (the library that
1061 programs such as tcpdump, Wireshark, etc.  use to do packet capture)
1062 turns on will <strong>not</strong> necessarily be shown if you run
1063 <tt>ifconfig</tt> on the interface on a UNIX system;
1064 <li>some network interfaces might not support promiscuous mode, and some
1065 drivers might not allow promiscuous mode to be turned on - see <a
1066 href="#promiscsniff">this earlier question</a> for more information on
1067 that;
1068 <li>the fact that you're not seeing any traffic, or are only seeing
1069 broadcast traffic, or aren't seeing any non-broadcast traffic other than
1070 traffic to or from the machine running Wireshark, does not mean that
1071 promiscuous mode isn't on - see <a href="#promiscsniff">this earlier
1072 question</a> for more information on that.
1073 </ul>
1074
1075 I.e., this is probably <a href="#promiscsniff">the same question
1076 as this earlier one</a>; see the response to that question.
1077 """)
1078
1079 question("""
1080 I can set a display filter just fine; why don't capture filters work?
1081 """)
1082
1083 answer("""
1084 Capture filters currently use a different syntax than display filters.  Here's
1085 the corresponding section from the
1086 <a href="/docs/man-pages/wireshark.html">wireshark(1)</a>
1087  man page:
1088
1089 <br />
1090
1091 "Display filters in Wireshark are very powerful; more fields are filterable
1092 in Wireshark than in other protocol analyzers, and the syntax you can
1093 use to create your filters is richer. As Wireshark progresses, expect
1094 more and more protocol fields to be allowed in display filters.
1095
1096 <br />
1097
1098 Packet capturing is performed with the pcap library. The capture filter
1099 syntax follows the rules of the pcap library. This syntax is different
1100 from the display filter syntax."
1101
1102 <br />
1103
1104 The capture filter syntax used by libpcap can be found in the
1105 <a href="http://www.tcpdump.org/tcpdump_man.html">tcpdump(8)</a>
1106 man page.
1107 """)
1108
1109
1110 question("""I'm entering valid capture filters; why do I still get
1111 "parse error" errors?""")
1112
1113 answer("""
1114 There is a bug in some versions of libpcap/WinPcap that cause it to
1115 report parse errors even for valid expressions if a previous filter
1116 expression was invalid and got a parse error.
1117
1118 <br />
1119
1120 Try exiting and restarting Wireshark; if you are using a version of
1121 libpcap/WinPcap with this bug, this will "erase" its memory of the
1122 previous parse error.  If the capture filter that got the "parse error"
1123 now works, the earlier error with that filter was probably due to this
1124 bug.
1125
1126 <br />
1127
1128 The bug was fixed in libpcap 0.6; 0.4[.x] and 0.5[.x] versions of
1129 libpcap have this bug, but 0.6[.x] and later versions don't.
1130
1131 <br />
1132
1133 Versions of WinPcap prior to 2.3 are based on pre-0.6 versions of
1134 libpcap, and have this bug; WinPcap 2.3 is based on libpcap 0.6.2, and
1135 doesn't have this bug.
1136
1137 <br />
1138
1139 If you are running Wireshark on a UNIX-flavored platform, run "wireshark
1140 -v", or select "About Wireshark..." from the "Help" menu in Wireshark, to
1141 see what version of libpcap it's using.  If it's not 0.6 or later, you
1142 will need either to upgrade your OS to get a later version of libpcap,
1143 or will need to build and install a later version of libpcap from <a
1144 href="http://www.tcpdump.org/">the tcpdump.org Web site</a> and then
1145 recompile Wireshark from source with that later version of libpcap.
1146
1147 <br />
1148
1149 If you are running Wireshark on Windows with a pre-2.3 version of
1150 WinPcap, you will need to un-install WinPcap and then download and
1151 install WinPcap 2.3.
1152 """)
1153
1154 question("""
1155 How can I capture packets with CRC errors?
1156 """)
1157
1158 answer("""
1159 Wireshark can capture only the packets that the packet capture library -
1160 libpcap on UNIX-flavored OSes, and the WinPcap port to Windows of libpcap
1161 on Windows - can capture, and libpcap/WinPcap can capture only the
1162 packets that the OS's raw packet capture mechanism (or the WinPcap
1163 driver, and the underlying OS networking code and network interface
1164 drivers, on Windows) will allow it to capture.
1165
1166 <br />
1167
1168 Unless the OS always supplies packets with errors such as invalid CRCs
1169 to the raw packet capture mechanism, or can be configured to do so,
1170 invalid CRCs to the raw packet capture mechanism, Wireshark - and other
1171 programs that capture raw packets, such as tcpdump - cannot capture
1172 those packets.  You will have to determine whether your OS needs to be
1173 so configured and, if so, can be so configured, configure it if
1174 necessary and possible, and make whatever changes to libpcap and the
1175 packet capture program you're using are necessary, if any, to support
1176 capturing those packets.
1177
1178 <br />
1179
1180 Most OSes probably do <strong>not</strong> support capturing packets
1181 with invalid CRCs on Ethernet, and probably do not support it on most
1182 other link-layer types.  Some drivers on some OSes do support it, such
1183 as some Ethernet drivers on FreeBSD; in those OSes, you might always get
1184 those packets, or you might only get them if you capture in promiscuous
1185 mode (you'd have to determine which is the case).
1186
1187 <br />
1188
1189 Note that libpcap does not currently supply to programs that use it an
1190 indication of whether the packet's CRC was invalid (because the drivers
1191 themselves do not supply that information to the raw packet capture
1192 mechanism); therefore, Wireshark will not indicate which packets had CRC
1193 errors unless the FCS was captured (see the next question) and you're
1194 using Wireshark 0.9.15 and later, in which case Wireshark will check the
1195 CRC and indicate whether it's correct or not.
1196 """)
1197
1198 question("""
1199 How can I capture entire frames, including the FCS?
1200 """)
1201
1202 answer("""
1203 Wireshark can only capture data that the packet capture library -
1204 libpcap on UNIX-flavored OSes, and the WinPcap port to Windows of
1205 libpcap on Windows - can capture, and libpcap/WinPcap can capture only
1206 the data that the OS's raw packet capture mechanism (or the WinPcap
1207 driver, and the underlying OS networking code and network interface
1208 drivers, on Windows) will allow it to capture.
1209
1210 <br />
1211
1212 For any particular link-layer network type, unless the OS supplies the
1213 FCS of a frame as part of the frame, or can be configured to do so,
1214 Wireshark - and other programs that capture raw packets, such as tcpdump
1215 - cannot capture the FCS of a frame.  You will have to determine whether
1216 your OS needs to be so configured and, if so, can be so configured,
1217 configure it if necessary and possible, and make whatever changes to
1218 libpcap and the packet capture program you're using are necessary, if
1219 any, to support capturing the FCS of a frame.
1220
1221 <br />
1222
1223 Most OSes do <strong>not</strong> support capturing the FCS of a frame
1224 on Ethernet, and probably do not support it on most other link-layer
1225 types.  Some drivres on some OSes do support it, such as some (all?)
1226 Ethernet drivers on NetBSD and possibly the driver for Apple's gigabit
1227 Ethernet interface in Mac OS X; in those OSes, you might always get the
1228 FCS, or you might only get the FCS if you capture in promiscuous mode
1229 (you'd have to determine which is the case).
1230
1231 <br />
1232
1233 Versions of Wireshark prior to 0.9.15 will not treat an Ethernet FCS in a
1234 captured packet as an FCS.  0.9.15 and later will attempt to determine
1235 whether there's an FCS at the end of the frame and, if it thinks there
1236 is, will display it as such, and will check whether it's the correct
1237 CRC-32 value or not.
1238 """)
1239
1240 question("""
1241 I'm capturing packets on a machine on a VLAN; why don't the packets I'm
1242 capturing have VLAN tags?
1243 """)
1244
1245 answer("""
1246 You might be capturing on what might be called a "VLAN interface" - the
1247 way a particular OS makes VLANs plug into the networking stack might,
1248 for example, be to have a network device object for the physical
1249 interface, which takes VLAN packets, strips off the VLAN header and
1250 constructs an Ethernet header, and passes that packet to an internal
1251 network device object for the VLAN, which then passes the packets onto
1252 various higher-level protocol implementations.
1253
1254 <br />
1255
1256 In order to see the raw Ethernet packets, rather than "de-VLANized"
1257 packets, you would have to capture not on the virtual interface for the
1258 VLAN, but on the interface corresponding to the physical network device,
1259 if possible.  See <a
1260 href="http://wiki.wireshark.org/CaptureSetup/VLAN">the Wireshark Wiki
1261 item on VLAN capturing</a> for details.
1262 """)
1263
1264 question("""
1265 Why does Wireshark hang after I stop a capture?
1266 """)
1267
1268 answer("""
1269 The most likely reason for this is that Wireshark is trying to look up an
1270 IP address in the capture to convert it to a name (so that, for example,
1271 it can display the name in the source address or destination address
1272 columns), and that lookup process is taking a very long time.
1273
1274 <br />
1275
1276 Wireshark calls a routine in the OS of the machine on which it's running
1277 to convert of IP addresses to the corresponding names.  That routine
1278 probably does one or more of:
1279 <ul><li>a search of a system file listing IP addresses and names;
1280 <li>a lookup using DNS;
1281 <li>on UNIX systems, a lookup using NIS;
1282 <li>on Windows systems, a NetBIOS-over-TCP query.
1283 </ul>
1284
1285 If a DNS server that's used in an address lookup is not responding, the
1286 lookup will fail, but will only fail after a timeout while the system
1287 routine waits for a reply.
1288
1289 <br />
1290
1291 In addition, on Windows systems, if the DNS lookup of the address fails,
1292 either because the server isn't responding or because there are no
1293 records in the DNS that could be used to map the address to a name, a
1294 NetBIOS-over-TCP query will be made.  That query involves sending a
1295 message to the NetBIOS-over-TCP name service on that machine, asking for
1296 the name and other information about the machine.  If the machine isn't
1297 running software that responds to those queries - for example, many
1298 non-Windows machines wouldn't be running that software - the lookup will
1299 only fail after a timeout.  Those timeouts can cause the lookup to take
1300 a long time.
1301
1302 <br />
1303
1304 If you disable network address-to-name translation - for example, by
1305 turning off the "Enable network name resolution" option in the "Capture
1306 Options" dialog box for starting a network capture - the lookups of the
1307 address won't be done, which may speed up the process of reading the
1308 capture file after the capture is stopped.  You can make that setting
1309 the default by selecting "Preferences" from the "Edit" menu, turning off
1310 the "Enable network name resolution" option in the "Name resolution"
1311 options in the preferences disalog box, and using the "Save" button in
1312 that dialog box; note that this will save <em>all</em> your current
1313 preference settings.
1314
1315 <br />
1316
1317 If Wireshark hangs when reading a capture even with network name
1318 resolution turned off, there might, for example, be a bug in one of
1319 Wireshark's dissectors for a protocol causing it to loop infinitely.  If
1320 you're not running the most recent release of Wireshark, you should first
1321 upgrade to that release, as, if there's a bug of that sort, it might've
1322 been fixed in a release after the one you're running.  If the hang
1323 occurs in the most recent release of Wireshark, the bug should be
1324 reported to <a href="mailto:wireshark-dev@wireshark.org">the Wireshark
1325 developers' mailing list</a> at <tt>wireshark-dev@wireshark.org</tt>.
1326
1327 <br />
1328
1329 On UNIX-flavored OSes, please try to force Wireshark to dump core, by
1330 sending it a <tt>SIGABRT</tt> signal (usually signal 6) with the
1331 <tt>kill</tt> command, and then get a stack trace if you have a debugger
1332 installed.  A stack trace can be obtained by using your debugger
1333 (<tt>gdb</tt> in this example), the Wireshark binary, and the resulting
1334 core file.  Here's an example of how to use the gdb command
1335 <tt>backtrace</tt> to do so.
1336
1337 <pre>
1338         $ gdb wireshark core
1339         (gdb) backtrace
1340         ..... prints the stack trace
1341         (gdb) quit
1342         $
1343 </pre>
1344
1345 The core dump file may be named "wireshark.core" rather than "core" on
1346 some platforms (e.g., BSD systems).
1347
1348 <br />
1349
1350 Also, if at all possible, please send a copy of the capture file that
1351 caused the problem; when capturing packets, Wireshark normally writes
1352 captured packets to a temporary file, which will probably be in
1353 <tt>/tmp</tt> or <tt>/var/tmp</tt> on UNIX-flavored OSes, <tt>\TEMP</tt>
1354 on the main system disk (normally <tt>C:</tt>) on Windows 9x/Me/NT 4.0,
1355 <tt>\Documents and Settings\</tt><var>your login name</var>
1356 <tt>\Local Settings\Temp</tt> on the main system disk on
1357 Windows 2000/Windows XP/Windows Server 2003, and
1358 <tt>\Users\<var>your login name</var>\AppData\Local\Temp</tt> on the main system disk on
1359 Windows 7, so the capture file will probably be there.  It will have a name
1360 of the form, <tt>wireshark_iface_YYYYmmddHHMMSS_XXXXXX</tt>.  Please don't
1361 send a trace file greater than 1 MB when compressed; instead, make it
1362 available via FTP or HTTP, or say it's available but leave it up to a
1363 developer to ask for it.  If the trace file contains sensitive
1364 information (e.g., passwords), then please do not send it.
1365 """)
1366
1367
1368 #################################################################
1369 section("Capturing packets on Windows")
1370 #################################################################
1371
1372 question("""
1373 I'm running Wireshark on Windows; why does some network interface on my
1374 machine not show up in the list of interfaces in the "Interface:" field
1375 in the dialog box popped up by "Capture->Start", and/or why does
1376 Wireshark give me an error if I try to capture on that interface?
1377 """, "capprobwin")
1378
1379 answer("""
1380 If you are running Wireshark on Windows NT 4.0, Windows 2000, Windows XP,
1381 or Windows Server 2003, and this is the first time you have run a
1382 WinPcap-based program (such as Wireshark, or TShark, or WinDump, or
1383 Analyzer, or...) since the machine was rebooted, you need to run that
1384 program from an account with administrator privileges; once you have run
1385 such a program, you will not need administrator privileges to run any
1386 such programs until you reboot.
1387
1388 <br />
1389
1390 If you are running on Windows Windows 2000/Windows XP/Windows Server
1391 2003 and have administrator privileges or a WinPcap-based program has
1392 been run with those privileges since the machine rebooted, this problem
1393 <em>might</em> clear up if you completely un-install WinPcap and then
1394 re-install it.
1395
1396 <br />
1397
1398 If that doesn't work, then note that Wireshark relies on the WinPcap
1399 library, on the WinPcap device driver, and on the facilities that come
1400 with the OS on which it's running in order to do captures.
1401
1402 <br />
1403
1404 Therefore, if the OS, the WinPcap library, or the WinPcap driver don't
1405 support capturing on a particular network interface device, Wireshark
1406 won't be able to capture on that device.
1407
1408 <br />
1409
1410 Note that:
1411
1412 <ol>
1413 <li>2.02 and earlier versions of the WinPcap driver and library that
1414 Wireshark uses for packet capture didn't support Token Ring interfaces;
1415 versions 2.1 and later support Token Ring, and the current version of
1416 Wireshark works with (and, in fact, requires) WinPcap 2.1 or later.
1417
1418 <br />
1419
1420 If you are having problems capturing on Token Ring interfaces, and you
1421 have WinPcap 2.02 or an earlier version of WinPcap installed, you should
1422 uninstall WinPcap, download and install the current version of WinPcap,
1423 and then install the latest version of Wireshark.
1424
1425 <br >
1426
1427 <li>WinPcap 2.3 has problems supporting PPP WAN interfaces on Windows NT
1428 4.0, Windows 2000, Windows XP, and Windows Server 2003, and, to avoid
1429 those problems, support for PPP WAN interfaces on those versions of
1430 Windows has been disabled in WinPcap 3.0.  Regular dial-up lines, ISDN
1431 lines, ADSL connections using PPPoE or PPPoA, and various other lines
1432 such as T1/E1 lines are all PPP interfaces, so those interfaces might
1433 not show up on the list of interfaces in the "Capture Options"
1434 dialog on those OSes.
1435
1436 <br />
1437
1438 On Windows 2000, Windows XP, and Windows Server 2003, but
1439 <strong>not</strong> Windows NT 4.0 or Windows Vista Beta 1, you should
1440 be able to capture on the "GenericDialupAdapter" with WinPcap 3.1.  (3.1
1441 beta releases called it the "NdisWanAdapter"; if you're using a 3.1 beta
1442 release, you should un-install it and install the final 3.1 release.)
1443 See <a href="http://wiki.wireshark.org/CaptureSetup/PPP">the Wireshark
1444 Wiki item on PPP capturing</a> for details.
1445
1446 <br />
1447
1448 <li>WinPcap prior to 3.0 does not support multiprocessor machines (note
1449 that machines with a single multi-threaded processor, such as Intel's
1450 new multi-threaded x86 processors, are multiprocessor machines as far as
1451 the OS and WinPcap are concerned), and recent 2.x versions of WinPcap
1452 refuse to operate if they detect that they're running on a
1453 multiprocessor machine, which means that they may not show any network
1454 interfaces.  You will need to use WinPcap 3.0 to capture on a
1455 multiprocessor machine.
1456
1457 </ol>
1458
1459 <br />
1460
1461 If an interface doesn't show up in the list of interfaces in the
1462 "Interface:" field, and you know the name of the interface, try entering
1463 that name in the "Interface:" field and capturing on that device.
1464
1465 <br />
1466
1467 If the attempt to capture on it succeeds, the interface is somehow not
1468 being reported by the mechanism Wireshark uses to get a list of
1469 interfaces.  Try listing the interfaces with WinDump; see <a
1470 href="http://www.windump.org/">the WinDump Web site</a>
1471 for information on using WinDump.
1472
1473 <br />
1474
1475 You would run WinDump with the <tt>-D</tt> flag; if it lists the
1476 interface, please report this to <a
1477 href="mailto:wireshark-dev@wireshark.org">wireshark-dev@wireshark.org</a>
1478 giving full details of the problem, including
1479
1480 <ul>
1481 <li>the operating system you're using, and the version of that operating
1482 system;
1483 <li>the type of network device you're using;
1484 <li>the output of WinDump.
1485 </ul>
1486
1487 If WinDump does <em>not</em> list the interface,
1488 this is almost certainly a problem with one or more of:
1489
1490 <ul>
1491 <li>the operating system you're using;
1492 <li>the device driver for the interface you're using;
1493 <li>the WinPcap library and/or the WinPcap device driver;
1494 </ul>
1495
1496 so first check <a href="http://www.winpcap.org/misc/faq.htm">the
1497 WinPcap FAQ</a> or <a
1498 href="http://www.mirrors.wiretapped.net/security/packet-capture/winpcap/misc/faq.htm">
1499 the Wiretapped.net mirror of that FAQ</a>, to see if your problem is
1500 mentioned there.  If not, then see <a
1501 href="http://www.winpcap.org/contact.htm">the WinPcap support page</a>
1502 - check the "Submitting bugs" section.
1503
1504 <br />
1505
1506 If you are having trouble capturing on a particular network interface,
1507 first try capturing on that device with WinDump; see <a
1508 href="http://www.windump.org/">the WinDump Web site</a>
1509 for information on using WinDump.
1510
1511 <br />
1512
1513 If you can capture on the interface with WinDump, send mail to <a
1514 href="mailto:wireshark-users@wireshark.org">wireshark-users@wireshark.org</a>
1515 giving full details of the problem, including
1516
1517 <ul>
1518 <li>the operating system you're using, and the version of that operating
1519 system;
1520 <li>the type of network device you're using;
1521 <li>the error message you get from Wireshark.
1522 </ul>
1523
1524 If you <em>cannot</em> capture on the interface with WinDump,
1525 this is almost certainly a problem with one or more of:
1526
1527 <ul>
1528 <li>the operating system you're using;
1529 <li>the device driver for the interface you're using;
1530 <li>the WinPcap library and/or the WinPcap device driver;
1531 </ul>
1532
1533 so first check <a href="http://www.winpcap.org/misc/faq.htm">the
1534 WinPcap FAQ</a> or <a
1535 href="http://www.mirrors.wiretapped.net/security/packet-capture/winpcap/misc/faq.htm">
1536 the Wiretapped.net mirror of that FAQ</a>, to see if your problem is
1537 mentioned there.  If not, then see <a
1538 href="http://www.winpcap.org/contact.htm">the WinPcap support page</a>
1539 - check the "Submitting bugs" section.
1540
1541 <br />
1542
1543 You may also want to ask the <a
1544 href="mailto:wireshark-users@wireshark.org">wireshark-users@wireshark.org</a>
1545 and the <a
1546 href="mailto:winpcap-users@winpcap.org">winpcap-users@winpcap.org</a>
1547 mailing lists to see if anybody happens to know about the problem and
1548 know a workaround or fix for the problem.  (Note that you will have to
1549 subscribe to that list in order to be allowed to mail to it; see <a
1550 href="http://www.winpcap.org/contact.htm">the WinPcap support
1551 page</a> for information on the mailing list.) In your mail,
1552 please give full details of the problem, as described above, and also
1553 indicate that the problem occurs with WinDump, not just with Wireshark.
1554 """)
1555
1556 question("""
1557 I'm running Wireshark on Windows; why do no network interfaces show up in
1558 the list of interfaces in the "Interface:" field in the dialog box
1559 popped up by "Capture->Start"?
1560 """)
1561
1562 answer("""
1563 This is really <a href="#capprobwin">the same question as a previous
1564 one</a>; see the response to that question.
1565 """)
1566
1567 question("""
1568 I'm running Wireshark on Windows; why doesn't my serial port/ADSL
1569 modem/ISDN modem show up in the list of interfaces in the "Interface:"
1570 field in the dialog box popped up by "Capture->Start"?
1571 """)
1572
1573 answer("""
1574 Internet access on those devices is often done with the Point-to-Point
1575 (PPP) protocol; WinPcap 2.3 has problems supporting PPP WAN interfaces
1576 on Windows NT 4.0, Windows 2000, Windows XP, and Windows Server 2003,
1577 and, to avoid those problems, support for PPP WAN interfaces on those
1578 versions of Windows has been disabled in WinPcap 3.0.
1579
1580 <br />
1581
1582 On Windows 2000, Windows XP, and Windows Server 2003, but
1583 <strong>not</strong> Windows NT 4.0 or Windows Vista Beta 1, you should
1584 be able to capture on the "GenericDialupAdapter" with WinPcap 3.1.  (3.1
1585 beta releases called it the "NdisWanAdapter"; if you're using a 3.1 beta
1586 release, you should un-install it and install the final 3.1 release.)
1587 See <a href="http://wiki.wireshark.org/CaptureSetup/PPP">the Wireshark
1588 Wiki item on PPP capturing</a> for details.
1589 """)
1590
1591 question("""
1592 I'm running Wireshark on Windows NT 4.0/Windows 2000/Windows XP/Windows
1593 Server 2003; my machine has a PPP (dial-up POTS, ISDN, etc.) interface,
1594 and it shows up in the "Interface" item in the "Capture Options" dialog
1595 box.  Why can no packets be sent on or received from that network while
1596 I'm trying to capture traffic on that interface?""", "nt_ppp_sniff")
1597
1598 answer("""
1599 Some versions of WinPcap have problems with PPP WAN interfaces on
1600 Windows NT 4.0, Windows 2000, Windows XP, and Windows Server 2003; one
1601 symptom that may be seen is that attempts to capture in promiscuous mode
1602 on the interface cause the interface to be incapable of sending or
1603 receiving packets.  You can disable promiscuous mode using the
1604 <tt>-p</tt> command-line flag or the item in the "Capture Preferences"
1605 dialog box, but this may mean that outgoing packets, or incoming
1606 packets, won't be seen in the capture.
1607
1608 <br />
1609
1610 On Windows 2000, Windows XP, and Windows Server 2003, but
1611 <strong>not</strong> Windows NT 4.0 or Windows Vista Beta 1, you should
1612 be able to capture on the "GenericDialupAdapter" with WinPcap 3.1.  (3.1
1613 beta releases called it the "NdisWanAdapter"; if you're using a 3.1 beta
1614 release, you should un-install it and install the final 3.1 release.)
1615 See <a href="http://wiki.wireshark.org/CaptureSetup/PPP">the Wireshark
1616 Wiki item on PPP capturing</a> for details.
1617 """)
1618
1619 question("""
1620 I'm running Wireshark on Windows; why am I not seeing any traffic being
1621 sent by the machine running Wireshark?""")
1622
1623 answer("""
1624 If you are running some form of VPN client software, it might be causing
1625 this problem; people have seen this problem when they have Check Point's
1626 VPN software installed on their machine.  If that's the cause of the
1627 problem, you will have to remove the VPN software in order to have
1628 Wireshark (or any other application using WinPcap) see outgoing packets;
1629 unfortunately, neither we nor the WinPcap developers know any way to
1630 make WinPcap and the VPN software work well together.
1631
1632 <br />
1633
1634 Also, some drivers for Windows (especially some wireless network
1635 interface drivers) apparently do not, when running in promiscuous mode,
1636 arrange that outgoing packets are delivered to the software that
1637 requested that the interface run promiscuously; try turning promiscuous
1638 mode off.
1639 """)
1640
1641 question("""
1642 When I capture on Windows in promiscuous mode, I can see packets other
1643 than those sent to or from my machine; however, those packets show up
1644 with a "Short Frame" indication, unlike packets to or from my machine.
1645 What should I do to arrange that I see those packets in their entirety?
1646 """)
1647
1648 answer("""
1649 In at least some cases, this appears to be the result of PGPnet running
1650 on the network interface on which you're capturing; turn it off on that
1651 interface.
1652 """)
1653
1654 question("""
1655 I'm trying to capture 802.11 traffic on Windows; why am I not seeing any
1656 packets?
1657 """, "win802_11promisc")
1658
1659 answer("""
1660 At least some 802.11 card drivers on Windows appear not to see any
1661 packets if they're running in promiscuous mode.  Try turning promiscuous
1662 mode off; you'll only be able to see packets sent by and received by
1663 your machine, not third-party traffic, and it'll look like Ethernet
1664 traffic and won't include any management or control frames, but that's a
1665 limitation of the card drivers.
1666
1667 <br />
1668
1669 See <a
1670 href="http://www.micro-logix.com/WinPcap/Supported.asp">MicroLogix's
1671 list of cards supported with WinPcap</a> for information on
1672 support of various adapters and drivers with WinPcap.
1673 """)
1674
1675 question("""
1676 I'm trying to capture 802.11 traffic on Windows; why am I seeing packets
1677 received by the machine on which I'm capturing traffic, but not packets
1678 sent by that machine?
1679 """)
1680
1681 answer("""
1682 This appears to be another problem with promiscuous mode; try turning it
1683 off.
1684 """)
1685
1686 question("""
1687 I'm trying to capture Ethernet VLAN traffic on Windows, and I'm
1688 capturing on a "raw" Ethernet device rather than a "VLAN interface", so
1689 that I can see the VLAN headers; why am I seeing packets received by the
1690 machine on which I'm capturing traffic, but not packets sent by that
1691 machine?
1692 """)
1693
1694 answer("""
1695 The way the Windows networking code works probably means that packets
1696 are sent on a "VLAN interface" rather than the "raw" device, so packets
1697 sent by the machine will only be seen when you capture on the "VLAN
1698 interface".  If so, you will be unable to see outgoing packets when
1699 capturing on the "raw" device, so you are stuck with a choice between
1700 seeing VLAN headers and seeing outgoing packets.
1701 """)
1702
1703 #################################################################
1704 section("Capturing packets on UN*Xes")
1705 #################################################################
1706
1707 question("""
1708 I'm running Wireshark on a UNIX-flavored OS; why does some network
1709 interface on my machine not show up in the list of interfaces in the
1710 "Interface:" field in the dialog box popped up by "Capture->Start",
1711 and/or why does Wireshark give me an error if I try to capture on that
1712 interface? """, "capprobunix")
1713
1714 answer("""
1715 You may need to run Wireshark from an account with sufficient privileges
1716 to capture packets, such as the super-user account, or may need to give
1717 your account sufficient privileges to capture packets.  Only those
1718 interfaces that Wireshark can open for capturing show up in that list; if
1719 you don't have sufficient privileges to capture on any interfaces, no
1720 interfaces will show up in the list.  See
1721 <a href="http://wiki.wireshark.org/CaptureSetup/CapturePrivileges">the
1722 Wireshark Wiki item on capture privileges</a> for details on how to give
1723 a particular account or account group capture privileges on platforms
1724 where that can be done.
1725
1726 <br />
1727
1728 If you are running Wireshark from an account with sufficient privileges,
1729 then note that Wireshark relies on the libpcap library, and on the
1730 facilities that come with the OS on which it's running in order to do
1731 captures.  On some OSes, those facilities aren't present by default; see
1732 <a href="http://wiki.wireshark.org/CaptureSetup/CaptureSupport">the
1733 Wireshark Wiki item on adding capture support</a> for details.
1734
1735 <br />
1736
1737 And, even if you're running with an account that has sufficient
1738 privileges to capture, and capture support is present in your OS, if the
1739 OS or the libpcap library don't support capturing on a particular
1740 network interface device or particular types of devices, Wireshark won't
1741 be able to capture on that device.
1742
1743 <br />
1744
1745 On Solaris, note that libpcap 0.6.2 and earlier didn't support Token
1746 Ring interfaces; the current version, 0.7.2, does support Token Ring,
1747 and the current version of Wireshark works with libpcap 0.7.2 and later.
1748
1749 <br />
1750
1751 If an interface doesn't show up in the list of interfaces in the
1752 "Interface:" field, and you know the name of the interface, try entering
1753 that name in the "Interface:" field and capturing on that device.
1754
1755 <br />
1756
1757 If the attempt to capture on it succeeds, the interface is somehow not
1758 being reported by the mechanism Wireshark uses to get a list of
1759 interfaces; please report this to <a
1760 href="mailto:wireshark-dev@wireshark.org">wireshark-dev@wireshark.org</a>
1761 giving full details of the problem, including
1762
1763 <ul>
1764 <li>the operating system you're using, and the version of that operating
1765 system (for Linux, give both the version number of the kernel and the
1766 name and version number of the distribution you're using);
1767 <li>the type of network device you're using.
1768 </ul>
1769
1770 If you are having trouble capturing on a particular network interface,
1771 and you've made sure that (on platforms that require it) you've arranged
1772 that packet capture support is present, as per the above, first try
1773 capturing on that device with <tt>tcpdump</tt>.
1774
1775 <br />
1776
1777 If you can capture on the interface with <tt>tcpdump</tt>, send mail to
1778 <a
1779 href="mailto:wireshark-users@wireshark.org">wireshark-users@wireshark.org</a>
1780 giving full details of the problem, including
1781
1782 <ul>
1783 <li>the operating system you're using, and the version of that operating
1784 system (for Linux, give both the version number of the kernel and the
1785 name and version number of the distribution you're using);
1786 <li>the type of network device you're using;
1787 <li>the error message you get from Wireshark.
1788 </ul>
1789
1790 If you <em>cannot</em> capture on the interface with <tt>tcpdump</tt>,
1791 this is almost certainly a problem with one or more of:
1792
1793 <ul>
1794 <li>the operating system you're using;
1795 <li>the device driver for the interface you're using;
1796 <li>the libpcap library;
1797 </ul>
1798
1799 so you should report the problem to the company or organization that
1800 produces the OS (in the case of a Linux distribution, report the problem
1801 to whoever produces the distribution).
1802
1803 <br />
1804
1805 You may also want to ask the <a
1806 href="mailto:wireshark-users@wireshark.org">wireshark-users@wireshark.org</a>
1807 and the <a
1808 href="mailto:tcpdump-workers@lists.tcpdump.org">tcpdump-workers@lists.tcpdump.org</a>
1809 mailing lists to see if anybody happens to know about the problem and
1810 know a workaround or fix for the problem.  In your mail, please give
1811 full details of the problem, as described above, and also indicate that
1812 the problem occurs with <tt>tcpdump</tt> not just with Wireshark.
1813 """)
1814
1815 question("""
1816 I'm running Wireshark on a UNIX-flavored OS; why do no network interfaces
1817 show up in the list of interfaces in the "Interface:" field in the
1818 dialog box popped up by "Capture->Start"?
1819 """)
1820
1821 answer("""
1822 This is really <a href="#capprobunix">the same question as the previous
1823 one</a>; see the response to that question.
1824 """)
1825
1826 question("""I'm capturing packets on Linux; why do the time stamps have
1827 only 100ms resolution, rather than 1us resolution?""")
1828
1829 answer("""
1830 Wireshark gets time stamps from libpcap/WinPcap, and
1831 libpcap/WinPcap get them from the OS kernel, so Wireshark - and any other
1832 program using libpcap, such as tcpdump - is at the mercy of the time
1833 stamping code in the OS for time stamps.
1834
1835 <br />
1836
1837 At least on x86-based machines, Linux can get high-resolution time
1838 stamps on newer processors with the Time Stamp Counter (TSC) register;
1839 for example, Intel x86 processors, starting with the Pentium Pro, and
1840 including all x86 processors since then, have had a TSC, and other
1841 vendors probably added the TSC at some point to their families of x86
1842 processors.
1843
1844 The Linux kernel must be configured with the CONFIG_X86_TSC option
1845 enabled in order to use the TSC.  Make sure this option is enabled in
1846 your kernel.
1847
1848 <br />
1849
1850 In addition, some Linux distributions may have bugs in their versions of
1851 the kernel that cause packets not to be given high-resolution time
1852 stamps even if the TSC is enabled.  See, for example, bug 61111 for Red
1853 Hat Linux 7.2.  If your distribution has a bug such as this, you may
1854 have to run a standard kernel from kernel.org in order to get
1855 high-resolution time stamps.
1856 """)
1857
1858 #################################################################
1859 section("Capturing packets on wireless LANs")
1860 #################################################################
1861
1862
1863 question("""
1864 How can I capture raw 802.11 frames, including non-data (management,
1865 beacon) frames?
1866 """, "raw_80211_sniff")
1867
1868 answer("""
1869 That depends on the operating system on which you're running, and on the
1870 802.11 interface on which you're capturing.
1871
1872 <br />
1873
1874 This would probably require that you capture in promiscuous mode or in
1875 the mode called "monitor mode" or "RFMON mode".  On some platforms, or
1876 with some cards, this might require that you capture in monitor mode -
1877 promiscuous mode might not be sufficient.  If you want to capture
1878 traffic on networks other than the one with which you're associated, you
1879 will have to capture in monitor mode.
1880
1881 <br />
1882
1883 Not all operating systems support capturing non-data packets and, even
1884 on operating systems that do support it, not all drivers, and thus not
1885 all interfaces, support it.  Even on those that do, monitor mode might
1886 not be supported by the operating system or by the drivers for all
1887 interfaces.
1888
1889 <br />
1890
1891 <strong>NOTE:</strong> an interface running in monitor mode will, on
1892 most if not all platforms, not be able to act as a regular network
1893 interface; putting it into monitor mode will, in effect, take your
1894 machine off of whatever network it's on as long as the interface is in
1895 monitor mode, allowing it only to passively capture packets.
1896
1897 <br />
1898
1899 This means that you should disable name resolution when capturing in
1900 monitor mode; otherwise, when Wireshark (or TShark, or tcpdump) tries
1901 to display IP addresses as host names, it will probably block for a long
1902 time trying to resolve the name because it will not be able to
1903 communicate with any DNS or NIS servers.
1904
1905 <br />
1906
1907 See <a
1908 href="http://wiki.wireshark.org/CaptureSetup/WLAN">the Wireshark
1909 Wiki item on 802.11 capturing</a> for details.
1910 """)
1911
1912 question("""
1913 How do I capture on an 802.11 device in monitor mode?""",
1914 "monitor")
1915
1916 answer("""
1917 Whether you will be able to capture in monitor mode depends on the
1918 operating system, adapter, and driver you're using.
1919 See <a href="#raw_80211_sniff">the previous question</a> for information
1920 on monitor mode, including a link to the Wireshark Wiki page that gives
1921 details on 802.11 capturing.
1922 """)
1923
1924 #################################################################
1925 section("Viewing traffic")
1926 #################################################################
1927
1928
1929 question("Why am I seeing lots of packets with incorrect TCP checksums?")
1930
1931 answer("""
1932 If the packets that have incorrect TCP checksums are all being sent by
1933 the machine on which Wireshark is running, this is probably because the
1934 network interface on which you're capturing does TCP checksum
1935 offloading.  That means that the TCP checksum is added to the packet by
1936 the network interface, not by the OS's TCP/IP stack; when capturing on
1937 an interface, packets being sent by the host on which you're capturing
1938 are directly handed to the capture interface by the OS, which means that
1939 they are handed to the capture interface without a TCP checksum being
1940 added to them.
1941
1942 <br />
1943
1944 The only way to prevent this from happening would be to disable TCP
1945 checksum offloading, but
1946
1947 <ol>
1948 <li>that might not even be possible on some OSes;
1949 <li>that could reduce networking performance significantly.
1950 </ol>
1951
1952 However, you can disable the check that Wireshark does of the TCP
1953 checksum, so that it won't report any packets as having TCP checksum
1954 errors, and so that it won't refuse to do TCP reassembly due to a packet
1955 having an incorrect TCP checksum.  That can be set as an Wireshark
1956 preference by selecting "Preferences" from the "Edit" menu, opening up
1957 the "Protocols" list in the left-hand pane of the "Preferences" dialog
1958 box, selecting "TCP", from that list, turning off the "Check the
1959 validity of the TCP checksum when possible" option, clicking "Save" if
1960 you want to save that setting in your preference file, and clicking
1961 "OK".
1962
1963 <br />
1964
1965 It can also be set on the Wireshark or TShark command line with a
1966 <tt>-o tcp.check_checksum:false</tt> command-line flag, or manually set
1967 in your preferences file by adding a <tt>tcp.check_checksum:false</tt>
1968 line.
1969 """)
1970
1971 question("""
1972 I've just installed Wireshark, and the traffic on my local LAN
1973 is boring.  Where can I find more interesting captures?
1974 """)
1975
1976 answer("""
1977 We have a collection of strange and exotic sample capture
1978 files at %s""" % (selflink("http://wiki.wireshark.org/SampleCaptures")))
1979
1980
1981 question("""
1982 Why doesn't Wireshark correctly identify RTP packets? It shows them
1983 only as UDP.""")
1984
1985 answer("""
1986 Wireshark can identify a UDP datagram as containing a packet of a
1987 particular protocol running atop UDP only if
1988
1989 <ol>
1990 <li> The protocol in question has a particular standard port
1991 number, and the UDP source or destination port number is that port
1992
1993 <li> Packets of that protocol can be identified by looking for a
1994 "signature" of some type in the packet - i.e., some data
1995 that, if Wireshark finds it in some particular part of a
1996 packet, means that the packet is almost certainly a packet of
1997 that type.
1998
1999 <li> Some <em>other</em> traffic earlier in the capture indicated that,
2000 for example, UDP traffic between two particular addresses and
2001 ports will be RTP traffic.
2002 </ol>
2003
2004 RTP doesn't have a standard port number, so 1) doesn't work; it doesn't,
2005 as far as I know, have any "signature", so 2) doesn't work.
2006
2007 <br />
2008
2009 That leaves 3).  If there's RTSP traffic that sets up an RTP session,
2010 then, at least in some cases, the RTSP dissector will set things up so
2011 that subsequent RTP traffic will be identified.  Currently, that's the
2012 only place we do that; there may be other places.
2013
2014 <br />
2015
2016 However, there will always be places where Wireshark is simply
2017 <b>incapable</b> of deducing that a given UDP flow is RTP; a mechanism
2018 would be needed to allow the user to specify that a given conversation
2019 should be treated as RTP.  As of Wireshark 0.8.16, such a mechanism
2020 exists; if you select a UDP or TCP packet, the right mouse button menu
2021 will have a "Decode As..." menu item, which will pop up a dialog box
2022 letting you specify that the source port, the destination port, or both
2023 the source and destination ports of the packet should be dissected as
2024 some particular protocol.
2025 """)
2026
2027 question("""
2028 Why doesn't Wireshark show Yahoo Messenger packets in captures that
2029 contain Yahoo Messenger traffic?""")
2030
2031 answer("""
2032 Wireshark only recognizes as Yahoo Messenger traffic packets to or from TCP
2033 port 3050 that begin with "YPNS", "YHOO", or "YMSG".  TCP segments that
2034 start with the middle of a Yahoo Messenger packet that takes more than one
2035 TCP segment will not be recognized as Yahoo Messenger packets (even if the
2036 TCP segment also contains the beginning of another Yahoo Messenger
2037 packet).
2038 """)
2039
2040 #################################################################
2041 section("Filtering traffic")
2042 #################################################################
2043
2044
2045 question("""I saved a filter and tried to use its name to filter the
2046 display; why do I get an "Unexpected end of filter string" error?""")
2047
2048 answer("""
2049 You cannot use the name of a saved display filter as a filter.  To
2050 filter the display, you can enter a display filter expression -
2051 <strong>not</strong> the name of a saved display filter - in the
2052 "Filter:" box at the bottom of the display, and type the <Enter> key or
2053 press the "Apply" button (that does not require you to have a saved
2054 filter), or, if you want to use a saved filter, you can press the
2055 "Filter:" button, select the filter in the dialog box that pops up, and
2056 press the "OK" button.""")
2057
2058 question("""
2059 How can I search for, or filter, packets that have a particular string
2060 anywhere in them?
2061 """)
2062
2063 answer("""
2064 If you want to do this when capturing, you can't.  That's a feature that
2065 would be hard to implement in capture filters without changes to the
2066 capture filter code, which, on many platforms, is in the OS kernel and,
2067 on other platforms, is in the libpcap library.
2068
2069 <br />
2070
2071 After capture, you can search for text by selecting <i>Edit&#8594;Find
2072 Packet...</i> and making sure <i>String</i> is selected. Alternately, you can
2073 use the "contains" display filter operator or "matches" operator if it's
2074 supported on your system.
2075 """)
2076
2077 question("""
2078 How do I filter a capture to see traffic for virus XXX?
2079 """)
2080
2081 answer("""
2082 For some viruses/worms there might be a capture filter to recognize the
2083 virus traffic.  Check the <a
2084 href="http://wiki.wireshark.org/CaptureFilters">CaptureFilters</a> page
2085 on the <a href="http://wiki.wireshark.org/">Wireshark Wiki</a> to see if
2086 anybody's added such a filter.
2087
2088 <br />
2089
2090 Note that Wireshark was not designed to be an intrusion detection system;
2091 you might be able to use it as an IDS, but in most cases software
2092 designed to be an IDS, such as <a href="http://www.snort.org/">Snort</a>
2093 or <a href="http://www.prelude-ids.org/">Prelude</a>, will probably work
2094 better.
2095
2096 <br />
2097
2098 The <a href="http://www.bleedingsnort.com/">Bleeding Edge of Snort</a>
2099 has a collection of signatures for Snort to detect various viruses,
2100 worms, and the like.
2101 """)
2102
2103 #################################################################
2104 if __name__ == '__main__':
2105         sys.exit(main())
2106 #################################################################