aboutsummaryrefslogtreecommitdiffstats
path: root/docbook
diff options
context:
space:
mode:
authorGerald Combs <gerald@zing.org>2014-11-08 22:05:52 -0800
committerGerald Combs <gerald@wireshark.org>2014-11-09 17:44:35 +0000
commitd8a075767429a37d555993812ee0f66984ad2287 (patch)
tree9ecf534921692976454d0652b017ad5d45343ec2 /docbook
parent2dda0888fce95e930b03fd18cc67e8c9e9e1f1fa (diff)
WSUG: Convert ``Files'' to AsciiDoc.
Leave most of the content intact for now. Change-Id: I78f47b8310cb41ac5a07d352e56ec907b36665f8 Reviewed-on: https://code.wireshark.org/review/5209 Reviewed-by: Gerald Combs <gerald@wireshark.org>
Diffstat (limited to 'docbook')
-rw-r--r--docbook/CMakeLists.txt5
-rw-r--r--docbook/Makefile.am2
-rw-r--r--docbook/Makefile.common3
-rw-r--r--docbook/Makefile.nmake2
-rw-r--r--docbook/wsug_src/WSUG_app_files.asciidoc544
-rw-r--r--docbook/wsug_src/WSUG_app_files.xml833
6 files changed, 551 insertions, 838 deletions
diff --git a/docbook/CMakeLists.txt b/docbook/CMakeLists.txt
index 9c4ee7ac11..26da16dcff 100644
--- a/docbook/CMakeLists.txt
+++ b/docbook/CMakeLists.txt
@@ -32,7 +32,7 @@ set(COMMON_GRAPHICS
)
set(WSUG_FILES
- wsug_src/WSUG_app_files.xml
+ WSUG_app_files.xml
wsug_src/WSUG_app_howitworks.xml
wsug_src/WSUG_app_messages.xml
wsug_src/WSUG_app_protocols.xml
@@ -54,6 +54,7 @@ set(WSUG_FILES
)
set(WSDG_ASCIIDOC_FILES
+ wsug_src/WSUG_app_files.asciidoc
wsug_src/WSUG_chapter_advanced.asciidoc
wsug_src/WSUG_chapter_build_install.asciidoc
wsug_src/WSUG_chapter_capture.asciidoc
@@ -312,7 +313,7 @@ MACRO( ASCIIDOC2CHAPTER _asciidocsource _conf_files )
${_output_xml}
${_output_dbk}
COMMAND ${XMLLINT_EXECUTABLE}
- --xpath '//chapter | //preface'
+ --xpath '//chapter | //preface | //appendix'
${_output_dbk}
> ${_output_xml}
DEPENDS
diff --git a/docbook/Makefile.am b/docbook/Makefile.am
index cab1f9504f..b79b083128 100644
--- a/docbook/Makefile.am
+++ b/docbook/Makefile.am
@@ -64,7 +64,7 @@ wsug_src/%.xml : wsug_src/%.asciidoc
--format=docbook --doctype=book \
$<
mv wsug_src/$*.xml wsug_src/$*.dbk
- xmllint --xpath '//chapter | //preface' wsug_src/$*.dbk > $@
+ xmllint --xpath '//chapter | //preface | //appendix' wsug_src/$*.dbk > $@
if HAVE_XSLTPROC
ALL_TARGETS=git_version_check wsug wsdg release_notes
diff --git a/docbook/Makefile.common b/docbook/Makefile.common
index d92d512e9d..40ca1342e1 100644
--- a/docbook/Makefile.common
+++ b/docbook/Makefile.common
@@ -1,7 +1,7 @@
#
WSUG_FILES = \
- wsug_src/WSUG_app_files.xml \
+ wsug_src/WSUG_app_files.asciidoc \
wsug_src/WSUG_app_howitworks.xml \
wsug_src/WSUG_app_messages.xml \
wsug_src/WSUG_app_protocols.xml \
@@ -22,6 +22,7 @@ WSUG_FILES = \
ws.css
WSUG_GENERATED_SOURCE = \
+ wsug_src/WSUG_app_files.xml \
wsug_src/WSUG_chapter_advanced.xml \
wsug_src/WSUG_chapter_build_install.xml \
wsug_src/WSUG_chapter_capture.xml \
diff --git a/docbook/Makefile.nmake b/docbook/Makefile.nmake
index 3cbda11a6a..64fdf8cd23 100644
--- a/docbook/Makefile.nmake
+++ b/docbook/Makefile.nmake
@@ -46,7 +46,7 @@ A2X_TEXT_OPTS=$(A2X_TEXT_OPTS) --lynx
$<
<<
mv $*.xml $*.dbk
- xmllint --xpath "//chapter | //preface" $*.dbk > $@
+ xmllint --xpath "//chapter | //preface | //appendix" $*.dbk > $@
.SUFFIXES: .asciidoc .xml
diff --git a/docbook/wsug_src/WSUG_app_files.asciidoc b/docbook/wsug_src/WSUG_app_files.asciidoc
new file mode 100644
index 0000000000..3d85e418e1
--- /dev/null
+++ b/docbook/wsug_src/WSUG_app_files.asciidoc
@@ -0,0 +1,544 @@
+++++++++++++++++++++++++++++++++++++++
+<!-- WSUG Appendix Files -->
+++++++++++++++++++++++++++++++++++++++
+
+[[AppFiles]]
+
+[appendix]
+== Files and Folders
+
+[[ChAppFilesCaptureFilesSection]]
+
+=== Capture Files
+
+To understand which information will remain available after the captured packets
+are saved to a capture file, it's helpful to know a bit about the capture file
+contents.
+
+Wireshark uses the
+link:http://www.winpcap.org/ntar/draft/PCAP-DumpFileFormat.html[pcapng] file
+format as the default format to save captured packets. It is very flexible
+but other tools may not support it.
+
+Wireshark also supports the
+link:http://wiki.wireshark.org/Development/LibpcapFileFormat[libpcap] file
+format. This is a much simpler format and is well established. However, it has
+some drawbacks: it's not extensible and lacks some information that would be
+really helpful (e.g. being able to add a comment to a packet such as ``the
+problems start here'' would be really nice).
+
+In addition to the libpcap format, Wireshark supports several different capture
+file formats. However, the problems described above also applies for these
+formats.
+
+[[ChIOFileContentSection]]
+
+==== Libpcap File Contents
+
+At the start of each libpcap capture file some basic information is stored like
+a magic number to identify the libpcap file format. The most interesting
+information of this file start is the link layer type (Ethernet, 802.11,
+MPLS, etc).
+
+The following data is saved for each packet:
+
+* The timestamp with millisecond resolution
+
+* The packet length as it was ``on the wire''
+
+* The packet length as it's saved in the file
+
+* The packet's raw bytes
+
+A detailed description of the libpcap file format can be found at:
+link:$$http://wiki.wireshark.org/Development/LibpcapFileFormat$$[]
+
+[[ChIOFileNotContentSection]]
+
+==== Not Saved in the Capture File
+
+You should also know the things that are _not saved_ in capture files:
+
+* Current selections (selected packet, ...)
+
+* Name resolution information. See <<ChAdvNameResolutionSection>> for details
++
+--
+Pcapng files can optionally save name resolution information. Libpcap files
+can't. Other file formats have varying levels of support.
+--
+
+* The number of packets dropped while capturing
+
+* Packet marks set with ``Edit/Mark Packet''
+
+* Time references set with ``Edit/Time Reference''
+
+* The current display filter
+
+[[ChAppFilesConfigurationSection]]
+
+=== Configuration Files and Folders
+
+Wireshark uses a number of files and folders while it is running. Some of these
+reside in the personal configuration folder and are used to maintain information
+between runs of Wireshark, while some of them are maintained in system areas.
+
+[TIP]
+====
+A list of the folders Wireshark actually uses can be found under the _Folders_
+tab in the dialog box shown when you select _About Wireshark_ from the _Help_
+menu.
+====
+
+The content format of the configuration files is the same on all platforms.
+However, to match the different policies for Unix and Windows platforms,
+different folders are used for these files.
+
+[[AppFilesTabFolders]]
+.Configuration files and folders overview
+[options="header"]
+|===============
+|File/Folder|Description|Unix/Linux folders|Windows folders
+|_preferences_|Settings from the Preferences dialog box.|/etc/wireshark.conf, $HOME/.wireshark/preferences|%WIRESHARK%\wireshark.conf, %APPDATA%\Wireshark\preferences
+|_recent_|Recent GUI settings (e.g. recent files lists).|$HOME/.wireshark/recent|%APPDATA%\Wireshark\recent
+|_cfilters_|Capture filters.|$HOME/.wireshark/cfilters|%WIRESHARK%\cfilters, %APPDATA%\Wireshark\cfilters
+|_dfilters_|Display filters.|$HOME/.wireshark/dfilters|%WIRESHARK%\dfilters, %APPDATA%\Wireshark\dfilters
+|_colorfilters_|Coloring rules.|$HOME/.wireshark/colorfilters|%WIRESHARK%\colorfilters, %APPDATA%\Wireshark\colorfilters
+|_$$disabled_protos$$_|Disabled protocols.|$HOME/.wireshark/disabled_protos|%WIRESHARK%\disabled_protos, %APPDATA%\Wireshark\disabled_protos
+|_ethers_|Ethernet name resolution.|/etc/ethers, $HOME/.wireshark/ethers|%WIRESHARK%\ethers, %APPDATA%\Wireshark\ethers
+|_manuf_|Ethernet name resolution.|/etc/manuf, $HOME/.wireshark/manuf|%WIRESHARK%\manuf, %APPDATA%\Wireshark\manuf
+|_hosts_|IPv4 and IPv6 name resolution.|/etc/hosts, $HOME/.wireshark/hosts|%WIRESHARK%\hosts, %APPDATA%\Wireshark\hosts
+|_services_|Network services.|/etc/services, $HOME/.wireshark/services|%WIRESHARK%\services, %APPDATA%\Wireshark\services
+|_subnets_|IPv4 subnet name resolution.|/etc/subnets, $HOME/.wireshark/subnets|%WIRESHARK%\subnets, %APPDATA%\Wireshark\subnets
+|_ipxnets_|IPX name resolution.|/etc/ipxnets, $HOME/.wireshark/ipxnets|%WIRESHARK%\ipxnets, %APPDATA%\Wireshark\ipxnets
+|_plugins_|Plugin directories.|/usr/share/wireshark/plugins, /usr/local/share/wireshark/plugins, $HOME/.wireshark/plugins|%WIRESHARK%\plugins\<version>,%APPDATA%\Wireshark\plugins
+|_temp_|Temporary files.|Environment: TMPDIR|Environment: TMPDIR or TEMP
+|===============
+
+[float]
+===== Windows folders
+%APPDATA% points to the personal configuration folder, e.g.: _C:\Documents and
+Settings\<username>\Application Data_ (details can be found at:
+<<ChWindowsProfiles>>),
+
+%WIRESHARK% points to the Wireshark program folder, e.g.: _C:\Program
+Files\Wireshark_
+
+[float]
+===== Unix/Linux folders
+The _/etc_ folder is the global Wireshark configuration folder. The folder
+actually used on your system may vary, maybe something like: _/usr/local/etc_.
+
+$HOME is usually something like: _/home/<username>_
+
+[float]
+===== File contents
+
+_preferences/wireshark.conf_::
+This file contains your Wireshark preferences, including defaults for capturing
+and displaying packets. It is a simple text file containing statements of the
+form:
++
+--
+----
+variable: value
+----
+
+The settings from this file are read in at program start and written to disk
+when you press the Save button in the ``Preferences'' dialog box.
+--
+
+_recent_::
+This file contains various GUI related settings like the main window position
+and size, the recent files list and such. It is a simple text file containing
+statements of the form:
++
+--
+----
+variable: value
+----
+
+It is read at program start and written at program exit.
+--
+
+_cfilters_::
+This file contains all the capture filters that you have defined and saved. It
+consists of one or more lines, where each line has the following format:
++
+--
+----
+"<filter name>" <filter string>
+----
+
+The settings from this file are read in at program start and written to disk
+when you press the Save button in the ``Capture Filters'' dialog box.
+--
+
+_dfilters_::
+This file contains all the display filters that you have defined and saved. It
+consists of one or more lines, where each line has the following format:
++
+--
+----
+"<filter name>" <filter string>
+----
+
+The settings from this file are read in at program start and written to disk
+when you press the Save button in the ``Display Filters'' dialog box.
+--
+
+_colorfilters_::
+This file contains all the color filters that you have defined and saved. It
+consists of one or more lines, where each line has the following format:
++
+--
+----
+@<filter name>@<filter string>@[<bg RGB(16-bit)>][<fg RGB(16-bit)>]
+----
+
+The settings from this file are read in at program start and written to disk
+when you press the Save button in the ``Coloring Rules'' dialog box.
+--
+
+_$$disabled_protos$$_::
+Each line in this file specifies a disabled protocol name. The following are
+some examples:
++
+--
+----
+tcp
+udp
+----
+
+The settings from this file are read in at program start and written to disk
+when you press the Save button in the ``Enabled Protocols'' dialog box.
+--
+
+_ethers_::
+When Wireshark is trying to translate Ethernet hardware addresses to names, it
+consults the files listed in <<AppFilesTabFolders>>. If an address is not found
+in /etc/ethers, Wireshark looks in $HOME/.wireshark/ethers
++
+--
+Each line in these files consists of one hardware address and name separated by
+whitespace. The digits of hardware addresses are separated by colons (:), dashes
+(-) or periods(.). The following are some examples:
+
+----
+ff-ff-ff-ff-ff-ff Broadcast
+c0-00-ff-ff-ff-ff TR_broadcast
+00.2b.08.93.4b.a1 Freds_machine
+----
+
+The settings from this file are read in at program start and never written by
+Wireshark.
+--
+
+_manuf_::
+Wireshark uses the files listed in <<AppFilesTabFolders>> to translate the first
+three bytes of an Ethernet address into a manufacturers name. This file has the
+same format as the ethers file, except addresses are three bytes long.
++
+--
+An example is:
+
+----
+00:00:01 Xerox # XEROX CORPORATION
+----
+
+The settings from this file are read in at program start and never written by
+Wireshark.
+--
+
+_hosts_::
+Wireshark uses the files listed in <<AppFilesTabFolders>> to translate IPv4 and
+IPv6 addresses into names.
++
+--
+This file has the same format as the usual /etc/hosts file on Unix systems.
+
+An example is:
+
+----
+# Comments must be prepended by the # sign!
+192.168.0.1 homeserver
+----
+
+The settings from this file are read in at program start and never written by
+Wireshark.
+--
+
+_services_::
+Wireshark uses the files listed in <<AppFilesTabFolders>> to translate port
+numbers into names.
++
+--
+An example is:
+
+----
+mydns 5045/udp # My own Domain Name Server
+mydns 5045/tcp # My own Domain Name Server
+----
+
+The settings from this file are read in at program start and never written by
+Wireshark.
+--
+
+_subnets_::
+Wireshark uses the files listed in <<AppFilesTabFolders>> to translate an IPv4
+address into a subnet name. If no exact match from the hosts file or from DNS is
+found, Wireshark will attempt a partial match for the subnet of the address.
++
+--
+Each line of this file consists of an IPv4 address, a subnet mask length
+separated only by a '/' and a name separated by whitespace. While the address
+must be a full IPv4 address, any values beyond the mask length are subsequently
+ignored.
+
+An example is:
+----
+# Comments must be prepended by the # sign!
+192.168.0.0/24 ws_test_network
+----
+
+A partially matched name will be printed as ``subnet-name.remaining-address''.
+For example, ``192.168.0.1'' under the subnet above would be printed as
+``ws_test_network.1"; if the mask length above had been 16 rather than 24, the
+printed address would be ``ws_test_network.0.1''.
+
+The settings from this file are read in at program start and never written by
+Wireshark.
+--
+
+_ipxnets_::
+Wireshark uses the files listed in <<AppFilesTabFolders>> to translate IPX network numbers into names.
++
+--
+
+An example is:
+----
+C0.A8.2C.00 HR
+c0-a8-1c-00 CEO
+00:00:BE:EF IT_Server1
+110f FileServer3
+----
+
+The settings from this file are read in at program start and never written by
+Wireshark.
+--
+
+_plugins_ folder::
+Wireshark searches for plugins in the directories listed in
+<<AppFilesTabFolders>>. They are searched in the order listed.
+
+_temp_ folder::
+If you start a new capture and don't specify a filename for it, Wireshark uses
+this directory to store that file; see <<ChCapCaptureFiles>>.
+
+[[ChProtocolHelp]]
+
+==== Protocol help configuration
+
+Wireshark can use configuration files to create context-sensitive menu items for
+protocol detail items which will load help URLs in your web browser.
+
+To create a protocol help file, create a folder named ``protocol_help'' in
+either the personal or global configuration folders. Then create a text file
+with the extension ``.ini'' in the ``protocol_help'' folder. The file must
+contain key-value pairs with the following sections:
+
+[database]::
+Mandatory. This contains initialization information for the
+help file. The following keys must be defined:
++
+--
+source::
+Source name, e.g. ``HyperGlobalMegaMart''
+
+version::
+Must be ``1''.
+
+location::
+General URL for help items. Variables can be substituted using
+the [location data] section below.
+--
+
+[location data]::
+Optional. Contains keys that will be used for variable
+substitution in the ``location'' value. For example, if
+the database section contains
++
+--
+----
+location = http://www.example.com/proto?cookie=${cookie}&amp;path=${PATH}
+----
+then setting
+----
+cookie = anonymous-user-1138
+----
+will result in the URL
+``http://www.example.com/proto?cookie=anonymous-user-1138&amp;path=${PATH}''.
+PATH is used for help path substitution, and shouldn't be defined in this section.
+--
+
+[map]::
+Maps Wireshark protocol names to section names below. Each key
+MUST match a valid protocol name such as ``ip''. Each value MUST
+have a matching section defined in the configuration file.
+
+Each protocol section must contain an ``_OVERVIEW'' key which will be used as
+the first menu item for the help source. Subsequent keys must match descriptions
+in the protocol detail. Values will be used as the ${PATH} variable in the
+location template. If ${PATH} isn't present in the location template the value
+will be appended to the location.
+
+Suppose the file
+_$$C:\Users\sam.clemens\AppData\Roaming\Wireshark\protocol_help\wikipedia.ini$$_
+contains the following:
+----
+
+# Wikipedia (en) protocol help file.
+
+# Help file initialization
+# source: The source of the help information, e.g. ``Inacon'' or ``Wikipedia"
+# version: Currently unused. Must be ``1''.
+# url_template: Template for generated URLs. See ``URL Data'' below.
+[database]
+source=Wikipedia
+version=1
+url_template=http://${language}.wikipedia.org/wiki/${PATH}
+
+# Substitution data for the location template.
+# Each occurrence of the keys below in the location template will be
+# substituted with their corresponding values. For example, ``${license}"
+# in the URL template above will be replaced with the value of ``license"
+# below.
+#
+# PATH is reserved for the help paths below; do not specify it here.
+[location data]
+language = en
+
+# Maps Wireshark protocol names to section names below. Each key MUST match
+# a valid protocol name. Each value MUST have a matching section below.
+[map]
+tcp=TCP
+
+# Mapped protocol sections.
+# Keys must match protocol detail items descriptions.
+[TCP]
+_OVERVIEW=Transmission_Control_Protocol
+Destination port=Transmission_Control_Protocol#TCP_ports
+Source port=Transmission_Control_Protocol#TCP_ports
+
+----
+
+Right-clicking on a TCP protocol detail item will display a help menu item that
+displays the Wikipedia page for TCP. Right-clicking on the TCP destination or
+source ports will display additional help menu items that take you to the ``TCP
+ports'' section of the page.
+
+The [location data] and ${PATH} can be omitted if they are not needed. For
+example, the following configuration is functionally equivalent to the previous
+configuration:
+----
+
+[database]
+source=Wikipedia
+version=1
+location=http://en.wikipedia.org/wiki/
+
+[map]
+tcp=TCP
+
+[TCP]
+_OVERVIEW=Transmission_Control_Protocol
+Destination port=Transmission_Control_Protocol#TCP_ports
+Source port=Transmission_Control_Protocol#TCP_ports
+
+----
+
+[[ChWindowsFolder]]
+
+=== Windows folders
+
+Here you will find some details about the folders used in Wireshark on different
+Windows versions.
+
+As already mentioned, you can find the currently used folders in the _About
+Wireshark_ dialog.
+
+[[ChWindowsProfiles]]
+
+==== Windows profiles
+
+Windows uses some special directories to store user configuration files which
+define the ``user profile''. This can be confusing, as the default directory
+location changed from Windows version to version and might also be different for
+English and internationalized versions of Windows.
+
+[NOTE]
+====
+If you've upgraded to a new Windows version, your profile might be kept in the
+former location. The defaults mentioned here might not apply.
+====
+
+The following guides you to the right place where to look for Wireshark's
+profile data.
+
+Windows 8, Windows 7, Windows Vista, and associated server editions::
+_C:\Users\<username>\AppData\Roaming\Wireshark_
+
+Windows XP and Windows Server 2003 footnoteref:[historical,No longer supported by Wireshark. For historical reference only.]::
+_C:\Documents and Settings\<username>\Application Data_. ``Documents and
+Settings'' and ``Application Data'' might be internationalized.
+
+Windows 2000 footnoteref:[historical]::
+_C:\Documents and Settings\<username>\Application Data_. ``Documents and
+Settings'' and ``Application Data'' might be internationalized.
+
+Windows NT 4 footnoteref:[historical]::
+_C:\WINNT\Profiles\<username>\Application Data\Wireshark_
+
+Windows ME, Windows 98 with user profiles footnoteref:[historical]::
+In Windows ME and 98 you could enable separate user profiles. In that case,
+something like _C:\windows\Profiles\<username>\Application Data\Wireshark_
+is used.
+
+Windows ME, Windows 98 without user profiles footnoteref:[historical]::
+Without user profiles enabled the default location for all users was
+_C:\windows\Application Data\Wireshark_
+
+[[ChWindowsRoamingProfiles]]
+
+==== Windows roaming profiles
+
+Some larger Windows environments use roaming profiles. If this is the case the
+configurations of all programs you use won't be saved on your local hard drive.
+They will be stored on the domain server instead.
+
+Your settings will travel with you from computer to computer with one exception.
+The ``Local Settings'' folder in your profile data (typically something like:
+__C:\Documents and Settings\<username>\Local Settings__) will not be
+transferred to the domain server. This is the default for temporary capture
+files.
+
+[[ChWindowsTempFolder]]
+
+==== Windows temporary folder
+
+Wireshark uses the folder which is set by the TMPDIR or TEMP environment
+variable. This variable will be set by the Windows installer.
+
+Windows 8, Windows 7, Windows Vista, and associated server editions::
+_C:\Users\<username>\AppData\Local\Temp_
+
+Windows XP, Windows 2000 footnoteref:[historical]::
+_C:\Documents and Settings\<username>\Local Settings\Temp_
+
+Windows NT footnoteref:[historical]::
+_C:\TEMP_
+
+++++++++++++++++++++++++++++++++++++++
+<!-- End of WSUG Appendix Files -->
+++++++++++++++++++++++++++++++++++++++ \ No newline at end of file
diff --git a/docbook/wsug_src/WSUG_app_files.xml b/docbook/wsug_src/WSUG_app_files.xml
deleted file mode 100644
index 1460ee2d71..0000000000
--- a/docbook/wsug_src/WSUG_app_files.xml
+++ /dev/null
@@ -1,833 +0,0 @@
-<!-- WSUG Appendix Files -->
-
-<appendix id="AppFiles">
- <title>Files and Folders</title>
-
- <section id="ChAppFilesCaptureFilesSection"><title>Capture Files</title>
- <para>
- To understand which information will remain available after
- the captured packets are saved to a capture file,
- it's helpful to know a bit about the capture file contents.
- </para>
- <para>
- Wireshark uses the libpcap file format as the default format to save
- captured packets; this format has existed for a long time and it's pretty simple.
- However, it has some drawbacks: it's not extensible and lacks some
- information that would be really helpful (e.g. being able to add a comment
- to a packet such as "the problems start here" would be really nice).
- </para>
- <para>
- In addition to the libpcap format, Wireshark supports several different
- capture file formats. However, the problems described above also applies
- for these formats.
- </para>
- <para>
- A new capture file format "PCAP Next Generation Dump File Format"
- is currently under development, which will fix these drawbacks.
- However, it still might take a while until the new file format is ready
- and Wireshark can use it.
- </para>
- <section id="ChIOFileContentSection"><title>Libpcap File Contents</title>
- <para>
- At the start of each libpcap capture file some basic information is stored
- like a magic number to identify the libpcap file format.
- The most interesting information of this file start is the link layer type
- (Ethernet, Token Ring, ...).
- </para>
- <para>
- The following data is saved for each packet:
- <itemizedlist>
- <listitem>
- <para>
- the timestamp with millisecond resolution
- </para>
- </listitem>
- <listitem>
- <para>
- the packet length as it was "on the wire"
- </para>
- </listitem>
- <listitem>
- <para>
- the packet length as it's saved in the file
- </para>
- </listitem>
- <listitem>
- <para>
- the packet's raw bytes
- </para>
- </listitem>
- </itemizedlist>
- A detailed description of the libpcap file format can be found at:
- <ulink url="http://wiki.wireshark.org/Development/LibpcapFileFormat"/>
- </para>
- </section>
- <section id="ChIOFileNotContentSection"><title>Not Saved in the Capture File</title>
- <para>
- Probably even more interesting for everyday Wireshark usage is to know
- the things that are <command>not saved</command> in the capture file:
- <itemizedlist>
- <listitem>
- <para>
- current selections (selected packet, ...)
- </para>
- </listitem>
- <listitem>
- <para>
- name resolution information, see <xref
- linkend="ChAdvNameResolutionSection"/> for details
- <warning><title>Warning!</title>
- <para>
- The name resolution information is rebuilt each time Wireshark is
- restarted so this information might even change when the capture file
- is reopened on the same machine later!
- </para>
- </warning>
- </para>
- </listitem>
- <listitem>
- <para>
- the number of packets dropped while capturing
- </para>
- </listitem>
- <listitem>
- <para>
- packet marks set with "Edit/Mark Packet"
- </para>
- </listitem>
- <listitem>
- <para>
- time references set with "Edit/Time Reference"
- </para>
- </listitem>
- <listitem>
- <para>
- the current display filter
- </para>
- </listitem>
- <listitem>
- <para>
- ...
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- </section>
-
- <section id="ChAppFilesConfigurationSection"><title>Configuration Files and Folders</title>
- <para>
- Wireshark uses a number of files and folders while it is running. Some
- of these reside in the personal configuration folder and are used to
- maintain information between runs of Wireshark, while some of them are
- maintained in system areas.
- </para>
- <tip><title>Tip</title>
- <para>A list of the folders Wireshark actually uses can be found under the
- <command>Folders</command> tab in the dialog box shown when you select
- <command>About Wireshark</command> from the <command>Help</command> menu.
- </para>
- </tip>
- <para>
- The content format of the configuration files is the same on all platforms.
- However, to match the different policies for Unix and Windows platforms,
- different folders are used for these files.
- </para>
- <table id="AppFilesTabFolders" frame="none">
- <title>Configuration files and folders overview</title>
- <tgroup cols="4">
- <colspec colnum="1" colwidth="72pt"/>
- <colspec colnum="2" colwidth="80pt"/>
- <colspec colnum="3" colwidth="80pt"/>
- <thead>
- <row>
- <entry>File/Folder</entry>
- <entry>Description</entry>
- <entry>Unix/Linux folders</entry>
- <entry>Windows folders</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><command>preferences</command></entry>
- <entry>Settings from the Preferences dialog box.</entry>
- <entry>/etc/wireshark.conf, $HOME/.wireshark/preferences</entry>
- <entry>%WIRESHARK%\wireshark.conf, %APPDATA%\Wireshark\preferences</entry>
- </row>
- <row>
- <entry><command>recent</command></entry>
- <entry>Recent GUI settings (e.g. recent files lists).</entry>
- <entry>$HOME/.wireshark/recent</entry>
- <entry>%APPDATA%\Wireshark\recent</entry>
- </row>
- <row>
- <entry><command>cfilters</command></entry>
- <entry>Capture filters.</entry>
- <entry>$HOME/.wireshark/cfilters</entry>
- <entry>%WIRESHARK%\cfilters, %APPDATA%\Wireshark\cfilters</entry>
- </row>
- <row>
- <entry><command>dfilters</command></entry>
- <entry>Display filters.</entry>
- <entry>$HOME/.wireshark/dfilters</entry>
- <entry>%WIRESHARK%\dfilters, %APPDATA%\Wireshark\dfilters</entry>
- </row>
- <row>
- <entry><command>colorfilters</command></entry>
- <entry>Coloring rules.</entry>
- <entry>$HOME/.wireshark/colorfilters</entry>
- <entry>%WIRESHARK%\colorfilters, %APPDATA%\Wireshark\colorfilters</entry>
- </row>
- <row>
- <entry><command>disabled_protos</command></entry>
- <entry>Disabled protocols.</entry>
- <entry>$HOME/.wireshark/disabled_protos</entry>
- <entry>%WIRESHARK%\disabled_protos, %APPDATA%\Wireshark\disabled_protos</entry>
- </row>
- <row>
- <entry><command>ethers</command></entry>
- <entry>Ethernet name resolution.</entry>
- <entry>/etc/ethers, $HOME/.wireshark/ethers</entry>
- <entry>%WIRESHARK%\ethers, %APPDATA%\Wireshark\ethers</entry>
- </row>
- <row>
- <entry><command>manuf</command></entry>
- <entry>Ethernet name resolution.</entry>
- <entry>/etc/manuf, $HOME/.wireshark/manuf</entry>
- <entry>%WIRESHARK%\manuf, %APPDATA%\Wireshark\manuf</entry>
- </row>
- <row>
- <entry><command>hosts</command></entry>
- <entry>IPv4 and IPv6 name resolution.</entry>
- <entry>/etc/hosts, $HOME/.wireshark/hosts</entry>
- <entry>%WIRESHARK%\hosts, %APPDATA%\Wireshark\hosts</entry>
- </row>
- <row>
- <entry><command>services</command></entry>
- <entry>Network services.</entry>
- <entry>/etc/services, $HOME/.wireshark/services</entry>
- <entry>%WIRESHARK%\services, %APPDATA%\Wireshark\services</entry>
- </row>
- <row>
- <entry><command>subnets</command></entry>
- <entry>IPv4 subnet name resolution.</entry>
- <entry>/etc/subnets, $HOME/.wireshark/subnets</entry>
- <entry>%WIRESHARK%\subnets, %APPDATA%\Wireshark\subnets</entry>
- </row>
- <row>
- <entry><command>ipxnets</command></entry>
- <entry>IPX name resolution.</entry>
- <entry>/etc/ipxnets, $HOME/.wireshark/ipxnets</entry>
- <entry>%WIRESHARK%\ipxnets, %APPDATA%\Wireshark\ipxnets</entry>
- </row>
- <row>
- <entry><command>plugins</command></entry>
- <entry>Plugin directories.</entry>
- <entry>/usr/share/wireshark/plugins,
- /usr/local/share/wireshark/plugins,
- $HOME/.wireshark/plugins
- </entry>
- <entry>%WIRESHARK%\plugins\&lt;version&gt;,
- %APPDATA%\Wireshark\plugins</entry>
- </row>
- <row>
- <entry><command>temp</command></entry>
- <entry>Temporary files.</entry>
- <entry>Environment: TMPDIR</entry>
- <entry>Environment: TMPDIR or TEMP</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <note><title>Windows folders</title>
- <para>
- %APPDATA% points to the personal configuration folder, e.g.:
- <filename>C:\Documents and Settings\&lt;username&gt;\Application Data</filename>
- (details can be found at: <xref linkend="ChWindowsProfiles"/>),
- </para>
- <para>
- %WIRESHARK% points to the Wireshark program folder, e.g.:
- <filename>C:\Program Files\Wireshark</filename>
- </para>
- </note>
- <note><title>Unix/Linux folders</title>
- <para>
- The <filename>/etc</filename> folder is the global Wireshark configuration
- folder. The folder actually used on your system
- may vary, maybe something like: <filename>/usr/local/etc</filename>.
- </para>
- <para>
- $HOME is usually something like: <filename>/home/&lt;username&gt;</filename>
- </para>
- </note>
- <para>
- <variablelist>
- <varlistentry>
- <term><command>preferences/wireshark.conf</command></term>
- <listitem>
- <para>
- This file contains your Wireshark preferences,
- including defaults for capturing and displaying packets.
- It is a simple text file containing statements of the form:
- <programlisting>
-variable: value
- </programlisting>
- The settings from this file are
- read in at program start and written to disk when you press the
- Save button in the "Preferences" dialog box.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>recent</command></term>
- <listitem>
- <para>
- This file contains various GUI related settings like the main window
- position and size, the recent files list and such.
- It is a simple text file containing statements of the form:
- <programlisting>
-variable: value
- </programlisting>
- It is read at program start and written at program exit.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>cfilters</command></term>
- <listitem>
- <para>
- This file contains all the capture filters that you have defined
- and saved. It consists of one or more lines, where each
- line has the following format:
- <programlisting>
-"&lt;filter name>" &lt;filter string>
- </programlisting>
- The settings from this file are read in at program start and written
- to disk when you press the Save button in the "Capture Filters" dialog
- box.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>dfilters</command></term>
- <listitem>
- <para>
- This file contains all the display filters that you have defined
- and saved. It consists of one or more lines, where each
- line has the following format:
- <programlisting>
-"&lt;filter name>" &lt;filter string>
- </programlisting>
- The settings from this file are read in at program start and written
- to disk when you press the Save button in the "Display Filters" dialog
- box.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>colorfilters</command></term>
- <listitem>
- <para>
- This file contains all the color filters that you have
- defined and saved. It consists of one or more lines,
- where each line has the following format:
- <programlisting>
-@&lt;filter name>@&lt;filter string>@[&lt;bg RGB(16-bit)>][&lt;fg RGB(16-bit)>]
- </programlisting>
- </para>
- <para>
- The settings from this file are read in at program start and written
- to disk when you press the Save button in the "Coloring Rules" dialog
- box.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>disabled_protos</command></term>
- <listitem>
- <para>
- Each line in this file specifies a disabled protocol name. The
- following are some examples:
- <programlisting>
-tcp
-udp
- </programlisting>
- </para>
- <para>
- The settings from this file are read in at program start and written
- to disk when you press the Save button in the "Enabled Protocols"
- dialog box.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <command>ethers</command>
- </term>
- <listitem>
- <para>
- When Wireshark is trying to translate Ethernet hardware
- addresses to names, it consults the files listed in
- <xref linkend="AppFilesTabFolders"/>.
- If an address is not found in /etc/ethers,
- Wireshark looks in $HOME/.wireshark/ethers
- </para>
- <para>
- Each line in these files consists of one hardware address and
- name separated by whitespace. The digits of hardware
- addresses are separated by colons (:), dashes (-) or
- periods(.). The following are some examples:
- <programlisting>
-ff-ff-ff-ff-ff-ff Broadcast
-c0-00-ff-ff-ff-ff TR_broadcast
-00.2b.08.93.4b.a1 Freds_machine
- </programlisting>
- The settings from this file are read in at program start and never
- written by Wireshark.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>manuf</command></term>
- <listitem>
- <para>
- Wireshark uses the files listed in <xref linkend="AppFilesTabFolders"/>
- to translate the first three bytes of an Ethernet address into a
- manufacturers name. This file has the same format as the ethers
- file, except addresses are three bytes long.
- </para>
- <para>
- An example is:
- <programlisting>
-00:00:01 Xerox # XEROX CORPORATION
- </programlisting>
- </para>
- <para>
- The settings from this file are read in at program start and never
- written by Wireshark.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>hosts</command></term>
- <listitem>
- <para>
- Wireshark uses the files listed in <xref linkend="AppFilesTabFolders"/>
- to translate IPv4 and IPv6 addresses into names.
- </para>
- <para>
- This file has the same format as the usual /etc/hosts file on Unix systems.
- </para>
- <para>
- An example is:
- <programlisting>
-# Comments must be prepended by the # sign!
-192.168.0.1 homeserver
- </programlisting>
- </para>
- <para>
- The settings from this file are read in at program start and never
- written by Wireshark.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>services</command></term>
- <listitem>
- <para>
- Wireshark uses the files listed in <xref linkend="AppFilesTabFolders"/>
- to translate port numbers into names.
- </para>
- <para>
- An example is:
- <programlisting>
-mydns 5045/udp # My own Domain Name Server
-mydns 5045/tcp # My own Domain Name Server
- </programlisting>
- </para>
- <para>
- The settings from this file are read in at program start and never
- written by Wireshark.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>subnets</command></term>
- <listitem>
- <para>
- Wireshark uses the files listed in <xref linkend="AppFilesTabFolders"/>
- to translate an IPv4 address into a subnet name. If no exact match from the
- hosts file or from DNS is found, Wireshark will attempt a partial match for the subnet
- of the address.
- </para>
- <para>
- Each line of this file consists of an IPv4 address, a subnet mask length separated
- only by a '/' and a name separated by whitespace. While the address must be a full IPv4
- address, any values beyond the mask length are subsequently ignored.
- </para>
-
- <para>
- An example is:
- <programlisting>
-# Comments must be prepended by the # sign!
-192.168.0.0/24 ws_test_network
- </programlisting>
- </para>
- <para>
- A partially matched name will be printed as "subnet-name.remaining-address". For example,
- "192.168.0.1" under the subnet above would be printed as "ws_test_network.1"; if the mask length
- above had been 16 rather than 24, the printed address would be "ws_test_network.0.1".
- </para>
- <para>
- The settings from this file are read in at program start and never
- written by Wireshark.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>ipxnets</command></term>
- <listitem>
- <para>
- Wireshark uses the files listed in <xref linkend="AppFilesTabFolders"/>
- to translate IPX network numbers into names.
- </para>
- <para>
- An example is:
- <programlisting>
-C0.A8.2C.00 HR
-c0-a8-1c-00 CEO
-00:00:BE:EF IT_Server1
-110f FileServer3
- </programlisting>
- </para>
- <para>
- The settings from this file are read in at program start and never
- written by Wireshark.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>plugins</command> folder</term>
- <listitem>
- <para>
- Wireshark searches for plugins in the directories listed in
- <xref linkend="AppFilesTabFolders"/>.
- They are searched in the order listed.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>temp</command> folder</term>
- <listitem>
- <para>
- If you start a new capture and don't specify a filename for it,
- Wireshark uses this directory to store that file; see
- <xref linkend="ChCapCaptureFiles"/>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <section id="ChProtocolHelp"><title>Protocol help configuration</title>
- <para>
- Wireshark can use configuration files to create context-sensitive menu
- items for protocol detail items which will load help URLs in your web
- browser.
- </para>
- <para>
- To create a protocol help file, create a folder named "protocol_help"
- in either the personal or global configuration folders. Then create a
- text file with the extension ".ini" in the "protocol_help" folder. The
- file must contain key-value pairs with the following sections:
- <variablelist>
- <varlistentry>
- <term>[database]</term>
- <listitem>
- <para>
- Mandatory. This contains initialization information for the
- help file. The following keys must be defined:
- <variablelist>
- <varlistentry>
- <term>source</term>
- <listitem><para>Source name, e.g. "HyperGlobalMegaMart".</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>version</term>
- <listitem><para>Must be "1".</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>location</term>
- <listitem>
- <para>
- General URL for help items. Variables can be substituted using
- the [location data] section below.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>[location data]</term>
- <listitem>
- <para>
- Optional. Contains keys that will be used for variable
- substitution in the "location" value. For example, if
- the database section contains
- <programlisting>
-location = http://www.example.com/proto?cookie=${cookie}&amp;path=${PATH}
- </programlisting>
- then setting
- <programlisting>
-cookie = anonymous-user-1138
- </programlisting>
- will result in the URL
- "http://www.example.com/proto?cookie=anonymous-user-1138&amp;path=${PATH}".
- PATH is used for help path substitution, and shouldn't be defined in this section.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>[map]</term>
- <listitem>
- <para>
- Maps Wireshark protocol names to section names below. Each key
- MUST match a valid protocol name such as "ip". Each value MUST
- have a matching section defined in the configuration file.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- Each protocol section must contain an "_OVERVIEW" key which will be used
- as the first menu item for the help source. Subsequent keys must match
- descriptions in the protocol detail. Values will be used as the ${PATH}
- variable in the location template. If ${PATH} isn't present in the location
- template the value will be appended to the location.
- </para>
-
- <para>
- Suppose the file
- <filename>C:\Users\sam.clemens\AppData\Roaming\Wireshark\protocol_help\wikipedia.ini</filename>
- contains the following:
-
- <programlisting>
-# Wikipedia (en) protocol help file.
-
-# Help file initialization
-# source: The source of the help information, e.g. "Inacon" or "Wikipedia"
-# version: Currently unused. Must be "1".
-# url_template: Template for generated URLs. See "URL Data" below.
-[database]
-source=Wikipedia
-version=1
-url_template=http://${language}.wikipedia.org/wiki/${PATH}
-
-# Substitution data for the location template.
-# Each occurrence of the keys below in the location template will be
-# substituted with their corresponding values. For example, "${license}"
-# in the URL template above will be replaced with the value of "license"
-# below.
-#
-# PATH is reserved for the help paths below; do not specify it here.
-[location data]
-language = en
-
-# Maps Wireshark protocol names to section names below. Each key MUST match
-# a valid protocol name. Each value MUST have a matching section below.
-[map]
-tcp=TCP
-
-# Mapped protocol sections.
-# Keys must match protocol detail items descriptions.
-[TCP]
-_OVERVIEW=Transmission_Control_Protocol
-Destination port=Transmission_Control_Protocol#TCP_ports
-Source port=Transmission_Control_Protocol#TCP_ports
- </programlisting>
- Right-clicking on a TCP protocol detail item will display a help menu
- item that displays the Wikipedia page for TCP. Right-clicking on the
- TCP destination or source ports will display additional help menu items that
- take you to the "TCP ports" section of the page.
- </para>
-
- <para>
- The [location data] and ${PATH} can be omitted if they are not needed.
- For example, the following configuration is functionally equivalent to
- the previous configuration:
- <programlisting>
-[database]
-source=Wikipedia
-version=1
-location=http://en.wikipedia.org/wiki/
-
-[map]
-tcp=TCP
-
-[TCP]
-_OVERVIEW=Transmission_Control_Protocol
-Destination port=Transmission_Control_Protocol#TCP_ports
-Source port=Transmission_Control_Protocol#TCP_ports
- </programlisting>
- </para>
- </section>
-
- </section>
-
- <section id="ChWindowsFolder"><title>Windows folders</title>
- <para>
- Here you will find some details about the folders used in Wireshark
- on different Windows versions.
- </para>
- <para>
- As already mentioned, you can find the currently used folders in the
- <command>About Wireshark</command> dialog.
- </para>
-
- <section id="ChWindowsProfiles"><title>Windows profiles</title>
- <para>
- Windows uses some special directories to store user configuration files
- which define the "user profile". This can be confusing, as the default directory location
- changed from Windows version to version and might also be different for English
- and internationalized versions of Windows.
- </para>
- <note><title>Note!</title>
- <para>
- If you've upgraded to a new Windows version, your profile might
- be kept in the former location, so the defaults mentioned here might not
- apply.
- </para>
- </note>
- <para>
- The following guides
- you to the right place where to look for Wireshark's profile data.
- </para>
- <para>
- <variablelist>
- <varlistentry>
- <term><application>Windows 7</application>, <application>Windows Vista</application></term>
- <listitem>
- <para>
- <filename>C:\Users\&lt;username&gt;\AppData\Roaming\Wireshark</filename>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><application>Windows XP</application></term>
- <listitem>
- <para>
- <filename>C:\Documents and Settings\&lt;username&gt;\Application Data</filename>,
- "Documents and Settings" and "Application Data" might be internationalized.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><application>Windows 2000</application> (no longer supported by Wireshark, for historical reference only)</term>
- <listitem>
- <para>
- <filename>C:\Documents and Settings\&lt;username&gt;\Application Data</filename>,
- "Documents and Settings" and "Application Data" might be internationalized.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><application>Windows NT 4</application> (no longer supported, for historical reference only)</term>
- <listitem>
- <para>
- <filename>C:\WINNT\Profiles\&lt;username&gt;\Application Data\Wireshark</filename>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><application>Windows ME</application>, <application>Windows 98</application> with user profiles (no longer supported, for historical reference only)</term>
- <listitem>
- <para>
- In Windows ME and 98 you can enable separate user profiles. In that case,
- something like
- <filename>C:\windows\Profiles\&lt;username&gt;\Application Data\Wireshark</filename>
- is used.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><application>Windows ME</application>, <application>Windows 98</application> without user profiles (no longer supported, for historical reference only)</term>
- <listitem>
- <para>
- Without user profiles enabled the default location for all users is
- <filename>C:\windows\Application Data\Wireshark</filename>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </section>
-
- <section id="ChWindowsRoamingProfiles">
- <title>Windows 7, Vista, XP, 2000, and NT roaming profiles</title>
- <para>
- The following will only be applicable if you are using roaming profiles.
- This might be the case, if you work in a Windows domain environment
- (used in company networks). The configurations of all
- programs you use won't be saved on the local hard drive of the computer
- you are currently working on, but on the domain server.
- </para>
- <para>
- As Wireshark is using the correct places to store its profile data,
- your settings will travel with you, if you logon to a different computer
- the next time.
- </para>
- <para>
- There is an exception to this: The "Local Settings" folder in your profile
- data (typically something like:
- <filename>C:\Documents and Settings\&lt;username&gt;\Local Settings</filename>)
- will not be transferred to the domain server. This is the default for
- temporary capture files.
- </para>
- </section>
-
- <section id="ChWindowsTempFolder">
- <title>Windows temporary folder</title>
- <para>
- Wireshark uses the folder which is set by the TMPDIR or TEMP environment
- variable. This variable will be set by the Windows installer.
- </para>
- <para>
- <variablelist>
- <varlistentry>
- <term><application>Windows 7</application>, <application>Windows Vista</application></term>
- <listitem>
- <para>
- <filename>C:\Users\&lt;username&gt;\AppData\Local\Temp</filename>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><application>Windows XP</application>, <application>Windows 2000</application></term>
- <listitem>
- <para>
- <filename>C:\Documents and Settings\&lt;username&gt;\Local Settings\Temp</filename>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><application>Windows NT</application></term>
- <listitem>
- <para>
- <filename>C:\TEMP</filename>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </section>
-
- </section>
-
-</appendix>
-<!-- End of WSUG Appendix Files -->