From 700a474d3b3c61fac0a910c8efd35b66e40cbedc Mon Sep 17 00:00:00 2001 From: Gerald Combs Date: Wed, 16 Jul 2014 18:38:42 -0700 Subject: Start converting the User's Guide to AsciiDoc. Convert the preface and introduction. Update various makefiles. Change-Id: Id998cabadb6de458f04b7a43bdba4f98e4edb052 Reviewed-on: https://code.wireshark.org/review/3139 Reviewed-by: Gerald Combs Tested-by: Gerald Combs --- .../wsug_src/WSUG_chapter_introduction.asciidoc | 484 ++++++++++++++ docbook/wsug_src/WSUG_chapter_introduction.xml | 710 --------------------- docbook/wsug_src/WSUG_preface.asciidoc | 116 ++++ docbook/wsug_src/WSUG_preface.xml | 169 ----- 4 files changed, 600 insertions(+), 879 deletions(-) create mode 100644 docbook/wsug_src/WSUG_chapter_introduction.asciidoc delete mode 100644 docbook/wsug_src/WSUG_chapter_introduction.xml create mode 100644 docbook/wsug_src/WSUG_preface.asciidoc delete mode 100644 docbook/wsug_src/WSUG_preface.xml (limited to 'docbook/wsug_src') diff --git a/docbook/wsug_src/WSUG_chapter_introduction.asciidoc b/docbook/wsug_src/WSUG_chapter_introduction.asciidoc new file mode 100644 index 0000000000..b915dafd3c --- /dev/null +++ b/docbook/wsug_src/WSUG_chapter_introduction.asciidoc @@ -0,0 +1,484 @@ +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ + +[[ChapterIntroduction]] + +== Introduction + +[[ChIntroWhatIs]] + +=== What is Wireshark? + +Wireshark is a network packet analyzer. A network packet analyzer will try to +capture network packets and tries to display that packet data as detailed as +possible. + +You could think of a network packet analyzer as a measuring device used to +examine what's going on inside a network cable, just like a voltmeter is used by +an electrician to examine what's going on inside an electric cable (but at a +higher level, of course). + +In the past, such tools were either very expensive, proprietary, or both. +However, with the advent of Wireshark, all that has changed. + +Wireshark is perhaps one of the best open source packet analyzers available +today. + +[[ChIntroPurposes]] + +==== Some intended purposes + +Here are some examples people use Wireshark for: + +* Network administrators use it to _troubleshoot network problems_ + +* Network security engineers use it to _examine security problems_ + +* Developers use it to _debug protocol implementations_ + +* People use it to _learn network protocol_ internals + +Beside these examples Wireshark can be helpful in many other situations too. + +[[ChIntroFeatures]] + +==== Features + +The following are some of the many features Wireshark provides: + +* Available for _UNIX_ and _Windows_. + +* _Capture_ live packet data from a network interface. + +* _Open_ files containing packet data captured with tcpdump/WinDump, Wireshark, and a number of other packet capture programs. + +* _Import_ packets from text files containing hex dumps of packet data. + +* Display packets with _very detailed protocol information_. + +* _Save_ packet data captured. + +* _Export_ some or all packets in a number of capture file formats. + +* _Filter packets_ on many criteria. + +* _Search_ for packets on many criteria. + +* _Colorize_ packet display based on filters. + +* Create various _statistics_. + +* ...and _a lot more!_ + +However, to really appreciate its power you have to start using it. + +<> shows Wireshark having captured some packets and waiting for you +to examine them. + +[[ChIntroFig1]] +.Wireshark captures packets and lets you examine their contents. +image::wsug_graphics/ws-main.png[] + +==== Live capture from many different network media + +Wireshark can capture traffic from many different network media types - and +despite its name - including wireless LAN as well. Which media types are +supported, depends on many things like the operating system you are using. An +overview of the supported media types can be found at +wireshark-wiki-site:[]CaptureSetup/NetworkMedia[]. + +==== Import files from many other capture programs + +Wireshark can open packets captured from a large number of other capture +programs. For a list of input formats see <>. + +==== Export files for many other capture programs + +Wireshark can save packets captured in a large number of formats of other +capture programs. For a list of output formats see <>. + +==== Many protocol decoders + +There are protocol decoders (or dissectors, as they are known in Wireshark) for +a great many protocols: see <>. + +==== Open Source Software + +Wireshark is an open source software project, and is released under the +gpl-url:[][GNU General Public License] (GPL). You can freely use +Wireshark on any number of computers you like, without worrying about license +keys or fees or such. In addition, all source code is freely available under the +GPL. Because of that, it is very easy for people to add new protocols to +Wireshark, either as plugins, or built into the source, and they often do! + +[[ChIntroNoFeatures]] + +==== What Wireshark is not + +Here are some things Wireshark does not provide: + +* Wireshark isn't an intrusion detection system. It will not warn you when + someone does strange things on your network that he/she isn't allowed to do. + However, if strange things happen, Wireshark might help you figure out what is + really going on. + +* Wireshark will not manipulate things on the network, it will only "measure" + things from it. Wireshark doesn't send packets on the network or do other + active things (except for name resolutions, but even that can be disabled). + +[[ChIntroPlatforms]] + +=== System Requirements + +The amount of resources Wireshark needs depends on your environment and on the +size of the capture file you are analyzing. The values below should be fine for +small to medium-sized capture files no mor than a few hundred MB. Larger capture +files will require more memory and disk space. + +[NOTE] +.Busy networks mean large captures +==== +Working with a busy network can easily produce huge capture files. Capturing on +a gigabit or even 100 megabit network can produce hundreds of megabytes of +capture data in a short time. A fast processor, lots of memory and disk +space is always a good idea. +==== + +If Wireshark runs out of memory it will crash. See +wireshark-wiki-site:[]KnownBugs/OutOfMemory[] for details and workarounds. + +Although Wireshark captures packets using a separate process the main interface +is single-threaded and won't benefit much from multi-core systems. + +==== Microsoft Windows + +* The current version of Wireshark should support any version of Windows that is + still within its http://windows.microsoft.com/en-us/windows/lifecycle[extended + support lifetime]. At the time of writing this includes Windows 8, 7, Vista, + Server 2012, Server 2008 R2, Server 2008, and Server 2003. + +* Any modern 32-bit x86 or 64-bit AMD64/x86-64 processor. + +* 200 MB available RAM. Larger capture files require more RAM. + +* 75 MB available disk space. Capture files require additional disk space. + +* 1024×768 (1280×1024 or higher recommended) resolution with at + least 16 bit color. 8 bit color should work but user experience will be + degraded. + +* A supported network card for capturing + + - Ethernet. Any card supported by Windows should work. See the wiki pages on + wireshark-wiki-site:[]CaptureSetup/Ethernet[Ethernet capture] and + wireshark-wiki-site:[]CaptureSetup/Offloading[offloading] for issues that + may affect your environment. + + - 802.11. See the wireshark-wiki-site:[]CaptureSetup/WLAN#Windows[Wireshark + wiki page]. Capturing raw 802.11 information may be difficult without + special equipment. + + - Other media. See wireshark-wiki-site:[]CaptureSetup/NetworkMedia[] + +Older versions of Windows which are outside Microsoft's extended lifecycle +support window are no longer supported. It is often difficult or impossible to +support these systems due to circumstances beyond our control, such as third +party libraries on which we depend or due to necessary features that are only +present in newer versions of Windows (such as hardened security or memory +management). + +Wireshark 1.10 was the last release branch to officially support Windows XP. +Wireshark 1.2 was the last branch to support Windows 2000. See the +wireshark-wiki-site:[]Development/LifeCycle[Wireshark release lifecycle] page +for more details. + +==== UNIX / Linux + +Wireshark currently runs on most UNIX platforms. The system requirements should +be comparable to the Windows values listed above. + +Binary packages are available for most Unices and Linux distributions including +the following platforms: + +* Apple Mac OS X + +* Debian GNU/Linux + +* FreeBSD + +* Gentoo Linux + +* HP-UX + +* Mandriva Linux + +* NetBSD + +* OpenPKG + +* Red Hat Enterprise/Fedora Linux + +* Sun Solaris/i386 + +* Sun Solaris/SPARC + +* Canonical Ubuntu + +If a binary package is not available for your platform you can download the +source and try to build it. Please report your experiences to +mailto:wireshark-dev-list-email:[][wireshark-dev-list-email:[]]. + +[[ChIntroDownload]] + +=== Where to get Wireshark + +You can get the latest copy of the program from the Wireshark website at +wireshark-download-page:[][wireshark-download-page:[]]. The download page should +automatically highlight the appropriate download for your platform and direct you +to the nearest mirror. + +A new Wireshark version typically becomes available each month or two. + +If you want to be notified about new Wireshark releases you should subscribe to +the wireshark-announce mailing list. You will find more details in +<>. + +[[ChIntroHistory]] + + +=== A brief history of Wireshark + +In late 1997 Gerald Combs needed a tool for tracking down network problems +and wanted to learn more about networking so he started writing Ethereal (the +original name of the Wireshark project) as a way to solve both problems. + +Ethereal was initially released after several pauses in development in July +1998 as version 0.2.0. Within days patches, bug reports, and words of +encouragement started arriving and Ethereal was on its way to success. + +Not long after that Gilbert Ramirez saw its potential and contributed a +low-level dissector to it. + +In October, 1998 Guy Harris was looking for something better than tcpview so he +started applying patches and contributing dissectors to Ethereal. + +In late 1998 Richard Sharpe, who was giving TCP/IP courses, saw its potential +on such courses and started looking at it to see if it supported the protocols +he needed. While it didn't at that point new protocols could be easily added. +So he started contributing dissectors and contributing patches. + +The list of people who have contributed to the project has become very long +since then, and almost all of them started with a protocol that they needed that +Wireshark or did not already handle. So they copied an existing dissector and +contributed the code back to the team. + +In 2006 the project moved house and re-emerged under a new name: Wireshark. + +In 2008, after ten years of development, Wireshark finally arrived at version +1.0. This release was the first deemed complete, with the minimum features +implemented. Its release coincided with the first Wireshark Developer and User +Conference, called Sharkfest. + +[[ChIntroMaintenance]] + + +=== Development and maintenance of Wireshark + +Wireshark was initially developed by Gerald Combs. Ongoing development and +maintenance of Wireshark is handled by the Wireshark team, a loose group of +individuals who fix bugs and provide new functionality. + +There have also been a large number of people who have contributed protocol +dissectors to Wireshark, and it is expected that this will continue. You can +find a list of the people who have contributed code to Wireshark by checking the +about dialog box of Wireshark, or at the wireshark-authors-url:[][authors] page +on the Wireshark web site. + +Wireshark is an open source software project, and is released under the +gpl-url:[][GNU General Public License] (GPL) version 2. All source code is +freely available under the GPL. You are welcome to modify Wireshark to suit your +own needs, and it would be appreciated if you contribute your improvements back +to the Wireshark team. + +You gain three benefits by contributing your improvements back to the community: + +. Other people who find your contributions useful will appreciate them, and you + will know that you have helped people in the same way that the developers of + Wireshark have helped people. + +. The developers of Wireshark might improve your changes even more, as there's + always room for improvement. Or they may implement some advanced things on top + of your code, which can be useful for yourself too. + +. The maintainers and developers of Wireshark will maintain your code as well, + fixing it when API changes or other changes are made, and generally keeping it + in tune with what is happening with Wireshark. So if Wireshark is updated + (which is done often), you can get a new Wireshark version from the website + and your changes will already be included without any effort for you. + +The Wireshark source code and binary kits for some platforms are all available +on the download page of the Wireshark website: +wireshark-download-page:[][wireshark-download-page:[]]. + +[[ChIntroHelp]] + +=== Reporting problems and getting help + +If you have problems or need help with Wireshark there are several places that +may be of interest to you (well, besides this guide of course). + +[[ChIntroHomepage]] + +==== Website + +You will find lots of useful information on the Wireshark homepage at +wireshark-web-site:[][wireshark-web-site:[]]. + +[[ChIntroWiki]] + +==== Wiki + +The Wireshark Wiki at wireshark-wiki-site:[][wireshark-wiki-site:[]] provides a +wide range of information related to Wireshark and packet capture in general. +You will find a lot of information not part of this user's guide. For example, +there is an explanation how to capture on a switched network, an ongoing effort +to build a protocol reference and a lot more. + +And best of all, if you would like to contribute your knowledge on a specific +topic (maybe a network protocol you know well) you can edit the wiki pages by +simply using your web browser. + +[[ChIntroQA]] + +==== Q&A Site + +The Wireshark Q&A site at wireshark-qa-url:[][wireshark-qa-url:[]] offers a +resource where questions and answers come together. You have the option to +search what questions were asked before and what answers were given by people +who knew about the issue. Answers are graded, so you can pick out the best ones +easily. If your question hasn't been discussed before you can post one yourself. + +[[ChIntroFAQ]] + +==== FAQ + +The Frequently Asked Questions lists often asked questions and their corresponding answers. + +[NOTE] +.Read the FAQ +==== +Before sending any mail to the mailing lists below, be sure to read the FAQ. It +will often answer any questions you might have. This will save yourself and +others a lot of time. Keep in mind that a lot of people are subscribed to the +mailing lists. +==== + +You will find the FAQ inside Wireshark by clicking the menu item Help/Contents +and selecting the FAQ page in the dialog shown. + +An online version is available at the Wireshark website: +link:$$wireshark-faq-url:[]$$[wireshark-faq-url:[]]. You might prefer this +online version, as it's typically more up to date and the HTML format is easier +to use. + +[[ChIntroMailingLists]] + +==== Mailing Lists + +There are several mailing lists of specific Wireshark topics available: + +_wireshark-announce_:: + This mailing list will inform you about new program releases, which usually appear about every 4-8 weeks. + + +_wireshark-users_:: + This list is for users of Wireshark. People post questions about building and using Wireshark, others (hopefully) provide answers. + + +_wireshark-dev_:: + This list is for Wireshark developers. If you want to start developing a protocol dissector, join this list. + +You can subscribe to each of these lists from the Wireshark web site: +wireshark-mailing-lists-url:[][wireshark-mailing-lists-url:[]]. From +there, you can choose which mailing list you want to subscribe to by clicking on +the Subscribe/Unsubscribe/Options button under the title of the relevant list. +The links to the archives are included on that page as well. + +[TIP] +.The lists are archived +==== +You can search in the list archives to see if someone asked the same question +some time before and maybe already got an answer. That way you don't have to +wait until someone answers your question. +==== + +==== Reporting Problems + +[NOTE] +==== +Before reporting any problems, please make sure you have installed the latest +version of Wireshark. +==== + + +When reporting problems with Wireshark please supply the following information: + +. The version number of Wireshark and the dependent libraries linked with it, + such as Qt or GLib. You can obtain this from Wireshark's about box or the + command `wireshark -v`. + +. Information about the platform you run Wireshark on. + +. A detailed description of your problem. + +. If you get an error/warning message, copy the text of that message (and also a + few lines before and after it, if there are some) so others may find the + place where things go wrong. Please don't give something like: "I get a + warning while doing x" as this won't give a good idea where to look. + +[NOTE] +.Don't send large files +==== +Do not send large files (>500KB) to the mailing lists. Just place a note that +further data is available on request. Large files will only annoy a lot of +people on the list who are not interested in your specific problem. If required +you will be asked for further data by the persons who really can help you. +==== + +[WARNING] +.Don't send confidential information! +==== +If you send capture files to the mailing lists be sure they don't contain any +sensitive or confidential information like passwords or personally identifiable +information (PII). +==== + +==== Reporting Crashes on UNIX/Linux platforms + +When reporting crashes with Wireshark it is helpful if you supply the traceback +information along with the information mentioned in "Reporting Problems". + +You can obtain this traceback information with the following commands on UNIX or Linux (note the backticks): + +---- +$ gdb `whereis wireshark | cut -f2 -d: | cut -d' ' -f2` core >& backtrace.txt +backtrace +^D +---- + +If you do not have `gdb` available, you will have to check out your operating system's debugger. + +Mail `backtrace.txt` to +mailto:wireshark-dev-list-email:[][wireshark-dev-list-email:[]]. + +==== Reporting Crashes on Windows platforms + +The Windows distributions don't contain the symbol files (.pdb) because they are +very large. You can download them separately at +wireshark-download-page:[]download/win32/all-versions and +wireshark-download-page:[]download/win64/all-versions + +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ \ No newline at end of file diff --git a/docbook/wsug_src/WSUG_chapter_introduction.xml b/docbook/wsug_src/WSUG_chapter_introduction.xml deleted file mode 100644 index 80a9bb1024..0000000000 --- a/docbook/wsug_src/WSUG_chapter_introduction.xml +++ /dev/null @@ -1,710 +0,0 @@ - - - - Introduction - -
- What is <application>Wireshark?</application> - - Wireshark is a network packet analyzer. A network packet - analyzer will try to capture network packets and tries to display - that packet data as detailed as possible. - - - You could think of a network packet analyzer as a measuring device used to - examine what's going on inside a network cable, just like a voltmeter is - used by an electrician to examine what's going on inside an electric cable - (but at a higher level, of course). - - - In the past, such tools were either very expensive, proprietary, or both. - However, with the advent of Wireshark, all that has changed. - - - Wireshark is perhaps one of the best open - source packet analyzers available today. - - -
Some intended purposes - - Here are some examples people use Wireshark for: - - - network administrators use it to troubleshoot network - problems - - - network security engineers use it to examine security - problems - - - developers use it to debug protocol implementations - - - people use it to learn network protocol - internals - - - Beside these examples, Wireshark can be helpful in many other situations - too. - -
- -
Features - - The following are some of the many features Wireshark provides: - - - Available for UNIX and Windows. - - - - Capture live packet data from a network interface. - - - - - Open files containing packet data captured with - tcpdump/WinDump, Wireshark, and a number of other packet capture - programs. - - - - - Import packets from text files containing hex - dumps of packet data. - - - - - Display packets with very detailed protocol information. - - - - - Save packet data captured. - - - - - Export some or all packets in a number of - capture file formats. - - - - Filter packets on many criteria. - - - Search for packets on many criteria. - - - Colorize packet display based on filters. - - - Create various statistics. - - - ... and a lot more! - - - However, to really appreciate its power, you have to start using it. - - - shows Wireshark - having captured some packets and waiting for you to examine - them. -
- - <application>Wireshark</application> captures packets and allows - you to examine their content. - - -
- -
- -
- Live capture from many different network media - - Wireshark can capture traffic from many different network media types - - and despite its name - including wireless LAN as well. - Which media types are supported, depends on many things like the - operating system you are using. - An overview of the supported media types can be found at: - . - -
- -
Import files from many other capture programs - - Wireshark can open packets captured from a large number of - other capture programs. For a list of input formats see - . - -
-
Export files for many other capture programs - - Wireshark can save packets captured in a large number of formats of - other capture programs. For a list of output formats see - . - -
- -
- Many protocol decoders - - There are protocol decoders (or dissectors, as they are - known in Wireshark) for a great many protocols: - see . - -
- -
Open Source Software - - Wireshark is an open source software project, and is released under - the GNU General Public License (GPL). - You can freely use Wireshark on any number of computers you like, without - worrying about license keys or fees or such. In addition, all source - code is freely available under the GPL. Because of that, it is very easy - for people to add new protocols to Wireshark, either as plugins, or built - into the source, and they often do! - -
- -
What Wireshark is not - - Here are some things Wireshark does not provide: - - - Wireshark isn't an intrusion detection system. It will not warn you when - someone does strange things on your network that he/she isn't allowed to - do. However, if strange things happen, Wireshark might help you figure - out what is really going on. - - - Wireshark will not manipulate things on the network, it will only - "measure" things from it. Wireshark doesn't send packets on the network - or do other active things (except for name resolutions, but even - that can be disabled). - - - -
-
- -
- System Requirements - What you'll need to get Wireshark up and running ... - -
General Remarks - - - The values below are the minimum requirements and only - "rules of thumb" for use on a moderately used network - Working with a busy network can easily produce huge - memory and disk space usage! For example: Capturing on a fully saturated - 100MBit/s Ethernet will produce ~ 750MBytes/min! Having a fast processor, - lots of memory and disk space is a good idea in that case. - If Wireshark is running out of memory it crashes, - see: - for details and workarounds - Wireshark won't benefit much from Multiprocessor/Hyperthread - systems as time consuming tasks like filtering packets are single threaded. - No rule is without exception: during an "Update list of packets in real - time" capture, capturing traffic runs in one process and dissecting and - displaying packets runs in another process - which should benefit from two - processors. - - -
- -
Microsoft Windows - - - Windows XP Home, XP Pro, XP Tablet PC, XP Media - Center, Server 2003, Vista, Home Server, Server 2008, Server 2008 R2, - Home Server 2011, 7, or Server 2012. - - Any modern 32-bit x86 or 64-bit AMD64/x86-64 processor. - - 128MB available RAM. Larger capture files require more RAM. - - 75MB available disk space. Capture files require additional disk space. - - 800*600 (1280*1024 or higher recommended) resolution with - at least 65536 (16bit) colors (256 colors should work if Wireshark is - installed with the "legacy GTK1" selection of the Wireshark 1.0.x releases) - - A supported network card for capturing: - - - - Ethernet: Any card supported by Windows should work. See the wiki - pages on Ethernet - capture and offloading - for issues that may affect your environment. - - - 802.11: See the Wireshark - wiki page. Capturing raw 802.11 information may be difficult without special equipment. - - - Other media: See - - - - - - Remarks: - - - - Many older Windows versions are no longer supported for three reasons: - None of the developers use those systems which makes support - difficult. The libraries Wireshark depends on (GTK, WinPcap, …) have - dropped support for older releases. Microsoft has also dropped - support for these systems. - - - Windows 95, 98 and ME are no longer supported. The "old technology" - releases of Windows lack memory protection (specifically VirtualProtect) - which we use to improve program safety and security. The last known - version to work was Ethereal 0.10.14 (which includes WinPcap 3.1). You - can get it from . - According to this - bug report, you may need to install Ethereal 0.10.0 on some - systems. - - - Microsoft retired support for Windows 98 and ME in 2006. - - - Windows NT 4.0 no longer works with Wireshark. The last known version - to work was Wireshark 0.99.4 (which includes WinPcap 3.1). You still - can get it from . - - - Microsoft retired support for Windows NT 4.0 in 2004. - - - Windows 2000 no longer works with Wireshark. The last known version - to work was Wireshark 1.2.x (which includes WinPcap 4.1.2). You still - can get it from . - - - Microsoft retired support for Windows 2000 in 2010. - - - Windows CE and the embedded versions of Windows are not currently supported. - - - Multiple monitor setups are supported but may behave a bit - strangely. - - - -
- -
Unix / Linux - - Wireshark currently runs on most UNIX platforms. - The system requirements should be comparable to the Windows values - listed above. - - - Binary packages are available for at least the following platforms: - - - - Apple Mac OS X - Debian GNU/Linux - FreeBSD - Gentoo Linux - HP-UX - Mandriva Linux - NetBSD - OpenPKG - Red Hat Enterprise/Fedora Linux - rPath Linux - Sun Solaris/i386 - Sun Solaris/Sparc - Canonical Ubuntu - - - - If a binary package is not available for your platform, you should - download the source and try to build it. - Please report your experiences - to &WiresharkDevMailList; - . - -
- -
- -
- Where to get Wireshark? - - You can get the latest copy of the program from the Wireshark website: - &WiresharkDownloadPage;. The - website allows you to choose from among several mirrors for - downloading. - - - A new Wireshark version will typically become available every 4-8 months. - - - If you want to be notified about new Wireshark releases, you should - subscribe to the wireshark-announce mailing list. You will find more - details in . - -
- -
- A brief history of Wireshark - - In late 1997, Gerald Combs needed a tool for tracking down - networking problems and wanted to learn more about networking, so - he started writing Ethereal (the former name of the Wireshark project) - as a way to solve both problems. - - - Ethereal was initially released, after several pauses in development, - in July 1998 as version 0.2.0. Within days, patches, bug reports, - and words of encouragement started arriving, so Ethereal was on its - way to success. - - - Not long after that, Gilbert Ramirez saw its potential and contributed - a low-level dissector to it. - - - In October, 1998, Guy Harris of Network Appliance was looking for - something better than tcpview, so he started applying patches and - contributing dissectors to Ethereal. - - - In late 1998, Richard Sharpe, who was giving TCP/IP courses, saw its - potential on such courses, and started looking at it to see if it - supported the protocols he needed. While it didn't at that point, - new protocols could be easily added. So he started contributing - dissectors and contributing patches. - - - The list of people who have contributed to the project has become very - long since then, and almost all of them started with a protocol that they - needed that Wireshark or Ethereal did not already handle. So they copied - an existing dissector and contributed the code back to the team. - - - In 2006 the project moved house and re-emerged under a new name: Wireshark. - - - In 2008, after ten years of development, Wireshark finally arrived at - version 1.0. This release was the first deemed complete, with the minimum - features implemented. Its release coincided with the first Wireshark - Developer and User Conference, called SharkFest. - -
- -
- - Development and maintenance of <application>Wireshark</application> - - - Wireshark was initially developed by Gerald Combs. Ongoing development - and maintenance of Wireshark is handled by the Wireshark team, a loose - group of individuals who fix bugs and provide new functionality. - - - There have also been a large number of people who have contributed - protocol dissectors to Wireshark, and it is expected that this will - continue. You can find a list of the people who have contributed - code to Wireshark by checking the about dialog box of Wireshark, or at - the authors page on the - Wireshark web site. - - - Wireshark is an open source software project, and is released under - the GNU General Public License (GPL). - All source code is freely available under the GPL. You are welcome to - modify Wireshark to suit your own needs, and it would be appreciated - if you contribute your improvements back to the Wireshark team. - - - You gain three benefits by contributing your improvements back to the - community: - - - - Other people who find your contributions useful will appreciate - them, and you will know that you have helped people in the - same way that the developers of Wireshark have helped people. - - - - - The developers of Wireshark might improve your changes even more, - as there's always room for improvement. Or they may implement some - advanced things on top of your code, which can be useful for yourself - too. - - - - - The maintainers and developers of Wireshark will maintain your - code as well, fixing it when API changes or other changes are - made, and generally keeping it in tune with what is happening - with Wireshark. So if Wireshark is updated (which is done often), - you can get a new Wireshark version from the website and your changes - will already be included without any effort for you. - - - - - - The Wireshark source code and binary kits for some platforms are all - available on the download page of the Wireshark website: - &WiresharkDownloadPage;. - -
- -
- Reporting problems and getting help - - If you have problems, or need help with Wireshark, there are several - places that may be of interest to you (well, besides this guide of - course). - - -
Website - - You will find lots of useful information on the Wireshark homepage at - &WiresharkWebSite;. - -
- -
Wiki - - The Wireshark Wiki at &WiresharkWikiPage; provides a wide range - of information related to Wireshark and packet capturing in general. - You will find a lot of information not part of this user's guide. For - example, there is an explanation how to capture on a switched network, - an ongoing effort to build a protocol reference and a lot more. - - - And best of all, if you would like to contribute your knowledge on a - specific topic (maybe a network protocol you know well), you can edit the - wiki pages by simply using your web browser. - -
- -
Q&A Forum - - The Wireshark Q and A forum at - &WiresharkQASite; offers a resource - where questions and answers come together. You have the option to search - what questions were asked before and what answers were given by people who - knew about the issue. Answers are graded, so you can pick out the best ones - easily. If your issue isn't discussed before you can post one yourself. - -
- -
FAQ - - The "Frequently Asked Questions" will list often asked questions and - the corresponding answers. - Read the FAQ! - - Before sending any mail to the mailing lists below, be sure to read the - FAQ, as it will often answer the question(s) you might have. This will save - yourself and others a lot of time (keep in mind that a lot of people are - subscribed to the mailing lists). - - - You will find the FAQ inside Wireshark by clicking the menu item - Help/Contents and selecting the FAQ page in the dialog shown. - - - An online version is available at the Wireshark website: - &WiresharkFAQPage;. You might - prefer this online version, as it's typically more up to date and the HTML - format is easier to use. - -
- -
Mailing Lists - - There are several mailing lists of specific Wireshark topics available: - - wireshark-announce - - - This mailing list will inform you about new program - releases, which usually appear about every 4-8 weeks. - - - - wireshark-users - - - This list is for users of Wireshark. People post - questions about building and using Wireshark, others (hopefully) - provide answers. - - - - wireshark-dev - - - This list is for Wireshark developers. If you want to start - developing a protocol dissector, join this list. - - - - - - You can subscribe to each of these lists from the Wireshark web site: - &WiresharkListsPage;. - From there, you can choose which mailing list you want to subscribe to - by clicking on the Subscribe/Unsubscribe/Options button under the title - of the relevant list. The links to the archives are included on that - page as well. - - Tip! - - You can search in the list archives to see if someone asked the same - question some time before and maybe already got an answer. That way you - don't have to wait until someone answers your question. - - - -
- -
Reporting Problems - Note! - - Before reporting any problems, please make sure you have installed the - latest version of Wireshark. - - - - When reporting problems with Wireshark, it is helpful if you supply the - following information: - - - - The version number of Wireshark and the dependent libraries linked with - it, e.g. GTK+, etc. You can obtain this from the about dialog box - of Wireshark, or with the command wireshark -v. - - - - - Information about the platform you run Wireshark on. - - - - - A detailed description of your problem. - - - - - If you get an error/warning message, copy the text of that message - (and also a few lines before and after it, if there are some), so - others may find the place where things go wrong. Please don't - give something like: "I get a warning while doing x" as this won't - give a good idea where to look at. - - - - - Don't send large files! - - Do not send large files (>100KB) to the mailing lists, just place a note - that further data is available on request. Large files will only annoy a - lot of people on the list who are not interested in your specific problem. - If required, you will be asked for further data by the persons who really - can help you. - - - Don't send confidential information! - - If you send captured data to the mailing lists, be sure they don't contain - any sensitive or confidential information like passwords or such. - - -
- -
Reporting Crashes on UNIX/Linux platforms - - When reporting crashes with Wireshark, it is helpful if you supply the - traceback information (besides the information mentioned in "Reporting - Problems"). - - - You can obtain this traceback information with the following commands: - -& bt.txt -backtrace -^D -$ -]]> - - - - Type the characters in the first line verbatim! Those are - back-tics there! - - - - - backtrace is a gdb command. You should - enter it verbatim after the first line shown above, but it will not be - echoed. The ^D - (Control-D, that is, press the Control key and the D key - together) will cause gdb to exit. This will - leave you with a file called - bt.txt in the current directory. - Include the file with your bug report. - - - - - If you do not have gdb available, you - will have to check out your operating system's debugger. - - - - - You should mail the traceback to the - &WiresharkDevMailList; - mailing list. - -
- -
Reporting Crashes on Windows platforms - - The Windows distributions don't contain the symbol files (.pdb), because - they are very large. For this reason it's not possible to create - a meaningful backtrace file from it. You should report your crash just - like other problems, using the mechanism described above. - -
-
- - - diff --git a/docbook/wsug_src/WSUG_preface.asciidoc b/docbook/wsug_src/WSUG_preface.asciidoc new file mode 100644 index 0000000000..9f150de563 --- /dev/null +++ b/docbook/wsug_src/WSUG_preface.asciidoc @@ -0,0 +1,116 @@ +[[Preface]] + +[preface] + +== Preface + +[[PreForeword]] + +=== Foreword + +Wireshark is one of those programs that many network managers would love to be +able to use, but they are often prevented from getting what they would like from +Wireshark because of the lack of documentation. + +This document is part of an effort by the Wireshark team to improve the +usability of Wireshark. + +We hope that you find it useful and look forward to your comments. + +[[PreAudience]] + +=== Who should read this document? + +The intended audience of this book is anyone using Wireshark. + +This book will explain all the basics and also some of the advanced features +that Wireshark provides. As Wireshark has become a very complex program since +the early days, not every feature of Wireshark may be explained in this book. + +This book is not intended to explain network sniffing in general and it will not +provide details about specific network protocols. A lot of useful information +regarding these topics can be found at the Wireshark Wiki at +wireshark-wiki-site:[][wireshark-wiki-site:[]] + +By reading this book, you will learn how to install Wireshark, how to use the +basic elements of the graphical user interface (such as the menu) and what's +behind some of the advanced features that are not always obvious at first sight. +It will hopefully guide you around some common problems that frequently appear +for new (and sometimes even advanced) users of Wireshark. + +[[PreAck]] + +=== Acknowledgements + +The authors would like to thank the whole Wireshark team for their assistance. +In particular, the authors would like to thank: + +* Gerald Combs, for initiating the Wireshark project and funding to do this + documentation. + +* Guy Harris, for many helpful hints and a great deal of patience in reviewing + this document. + +* Gilbert Ramirez, for general encouragement and helpful hints along the way. + +The authors would also like to thank the following people for their helpful +feedback on this document: + +* Pat Eyler, for his suggestions on improving the example on generating a backtrace. + +* Martin Regner, for his various suggestions and corrections. + +* Graeme Hewson, for a lot of grammatical corrections. + +The authors would like to acknowledge those man page and README authors for the +Wireshark project from who sections of this document borrow heavily: + +* Scott Renfro from whose `mergecap` man page <> is derived. + +* Ashok Narayanan from whose `text2pcap` man page <> is derived. + +* Frank Singleton from whose `README.idl2wrs` <> is derived. + +[[PreAbout]] + +=== About this document + +This book was originally developed by mailto:wsug-author-email2:[][Richard +Sharpe] with funds provided from the Wireshark Fund. It was updated by +mailto:wsug-author-email3:[][Ed Warnicke] and more recently redesigned and +updated by mailto:wsug-author-email:[][Ulf Lamping]. + +It was originally written in DocBook/XML and converted to AsciiDoc by Gerald Combs. + +You will find some specially marked parts in this book: + +[WARNING] +.This is a warning +==== +You should pay attention to a warning, otherwise data loss might occur. +==== + +[NOTE] +.This is a note +==== +A note will point you to common mistakes and things that might not be obvious. +==== + +[TIP] +.This is a tip +==== +Tips are helpful for your everyday work using Wireshark. +==== + +[[PreDownload]] + +=== Where to get the latest copy of this document? + +The latest copy of this documentation can always be found at wireshark-users-guide-url:[][]. + +[[PreFeedback]] + +=== Providing feedback about this document + +Should you have any feedback about this document, please send it to the authors +through mailto:wireshark-dev-list-email:[][wireshark-dev-list-email:[]]. \ No newline at end of file diff --git a/docbook/wsug_src/WSUG_preface.xml b/docbook/wsug_src/WSUG_preface.xml deleted file mode 100644 index 88b7a5433c..0000000000 --- a/docbook/wsug_src/WSUG_preface.xml +++ /dev/null @@ -1,169 +0,0 @@ - - - Preface -
- Foreword - - Wireshark is one of those programs that many network managers would love - to be able to use, but they are often prevented from getting what they - would like from Wireshark because of the lack of documentation. - - - This document is part of an effort by the Wireshark team to improve the - usability of Wireshark. - - - We hope that you find it useful, and look forward to your comments. - -
- -
- Who should read this document? - - The intended audience of this book is anyone using Wireshark. - - - This book will explain all the basics and also some of the advanced features - that Wireshark provides. As Wireshark has become a very complex program since - the early days, not every feature of Wireshark may be explained in this - book. - - - This book is not intended to explain network sniffing in general and it will - not provide details about specific network protocols. A lot of useful - information regarding these topics can be found at the Wireshark Wiki at - &WiresharkWikiPage; - - - By reading this book, you will learn how to install Wireshark, how to use the - basic elements of the graphical user interface (such as the menu) and what's - behind some of the advanced features that are not always obvious at first - sight. It will hopefully guide you around some common problems that - frequently appear for new (and sometimes even advanced) users of Wireshark. - -
- -
- Acknowledgements - - The authors would like to thank the whole Wireshark team for their - assistance. In particular, the authors would like to thank: - - - - Gerald Combs, for initiating the Wireshark project and funding to - do this documentation. - - - - - Guy Harris, for many helpful hints and a great deal of patience - in reviewing this document. - - - - - Gilbert Ramirez, for general encouragement and helpful hints along - the way. - - - - - - The authors would also like to thank the following people for their - helpful feedback on this document: - - - - Pat Eyler, for his suggestions on improving the example on - generating a backtrace. - - - - - Martin Regner, for his various suggestions and corrections. - - - - - Graeme Hewson, for a lot of grammatical corrections. - - - - - - The authors would like to acknowledge those man page and README authors - for the Wireshark project from who sections of this document borrow heavily: - - - - Scott Renfro from whose mergecap man page - is derived. - - - - - Ashok Narayanan from whose text2pcap man page - is derived. - - - - - Frank Singleton from whose README.idl2wrs - is derived. - - - - -
- -
- About this document - - This book was originally developed by - Richard Sharpe with - funds provided from the Wireshark Fund. It was updated by - Ed Warnicke and more recently - redesigned and updated by Ulf - Lamping. - - - It is written in DocBook/XML. - - - You will find some specially marked parts in this book: - - This is a warning! - - You should pay attention to a warning, as otherwise data loss might occur. - - - This is a note! - - A note will point you to common mistakes and things that might not be - obvious. - - - This is a tip! - - Tips will be helpful for your everyday work using Wireshark. - - -
- -
- Where to get the latest copy of this document? - - The latest copy of this documentation can always be found at: - . - -
- -
- Providing feedback about this document - - Should you have any feedback about this document, please send it - to the authors through &WiresharkDevMailList;. - -
- -- cgit v1.2.3