Wireshark · Ethereal-dev: Re: [Ethereal-dev] No further comments on the 'User's guide' preview?!?

["Guy Harris" <gharris@xxxxxxxxx>]

Ulf Lamping said:
> BTW: is BeOS unix based or a completely different thing?

Different.  It is (was?) somewhat *influenced* by Unix, but it's not a
Unix-compatible OS.

>  >     The FAQ gives the official pronounciation as "e-the-real".
> I've added this, please review.

My in-house editor (who's done technical publications editing for Novell
and is now an editor at Network Appliance) would probably say it should be

    You are welcome to call it what you like, as long as you find it
useful.  The FAQ gives the official pronounciation as "e-the-real".

as that was her response to another case of a comma separating independent
clauses in a sentence - split the sentence into two sentences.

>  >     Or, at this point, we might want to leave out everybody but
>  > Gerald, as even if we only mention the *major* contributors, that
>  > history would get a bit long.
> I think it's ok to describe the beginning of the project the way it is.
> I find it interesting to read :-)

...although it fails to give credit to a number of developers who've
contributed a lot to the project, including you. :-)

>  >     "dependant libraries" should be "dependent libraries".
> changed

There's one other occurrence of "dependant", in the paragraph at the end
of page 69.

>  > P. 13:

In the second paragraph, "ethereal" should be "Ethereal" in the first
sentence.

>  > P. 15:

libpcap-0.5 should probably be changed to libpcap-0.8.3, as that's the
current version.

>  >     "deb's" should be "debs".
> Hmm, that looks strange, I keep it as it is.

A Google for

    debs apt-get

found 15,100 pages, a Google for

    deb's apt-get

found 2,220.

I'm not sure wheether there's an official standard - the first Google also
found "DEBs", although "DEB" isn't an acronym (it's short for "Deborah",
as in "Deborah and Ian") so it probably shouldn't be all-caps.  The main
Debian page just has a link to "Debian Packages".

>  > P. 30:
>  >
>  >     Is the blank line at the top of the "Description" field for each
> menu item supposed to be there?
> I'm unsure why it's there. That seems to be a bug in the pdf conversion,
> the HTML version doesn't show that behaviour :-(

How is the PDF generated?  Is there a DocBook-to-PDF translator used, or
is there some intermediate step?

>  > P. 43:
>  >
>  >     "obsoleted be" should be "obsoleted by".
> changed

There's another one in the description of "Endpoint List".

>  > P. 49:
>  >
>  >     "it's data" should be "its data".
> changed

Some others:

P. 2 - "Unlike it's name suggests, Ethereal can capture traffic from some
other network media than Ethernet too." should probably be "Although its
name might suggest that it captures only on Ethernet, Ethereal can capture
traffic from some other network media as well."

P. 49: "the IP dissector will overwrite this by it's own" should be
"...its own".

P. 138: "Each protocol has it's own dissector" should be "Each protocol
has its own dissector".

>  > P. 56:
>  >
>  >     The link-layer header type description should probably be
>  > something such as

...

> I think this is too long and won't be a good description what it's for
> (I still just don't understand it completely).

Part of the problem is that the mechanism in libpcap that this uses was
originally added for one purpose, but is useful for other purposes as
well, and was used for that.

The original purpose was to handle support 802.11 headers; I think it was
added so that applications that don't understand 802.11 headers wouldn't
have to be changed if support for them was added to BPF (the underlying
feature that libpcap uses for that is a BSD BPF feature, currently
supported in FreeBSD 5.2 and later and NetBSD 2.0-beta).  Ethereal should
probably check whether a device offers both Ethernet and 802.11 headers
and, if so, default to 802.11 headers (although capture filters
*currently* can't handle packets with 4 MAC addresses in 802.11 headers; I
hope to find time to fix that before the next libpcap release).

However, it also turned out to be useful for people trying to capture
DOCSIS traffic from the Cisco cable modem hardware in question, which uses
an Ethernet as a bit pipe, encapsulating DOCSIS frames inside low-level
Ethernet framing, so that the packets don't have an Ethernet header.  This
lets you capture that traffic but have it marked as a DOCSIS capture, so
that you don't have to set the Ethereal "treat all traffic as DOCSIS"
dissector preference in order to read the capture file correctly.  That's
in the current main-branch libpcap, but not yet in any release.

It then also turned out to be useful for passive capturing on synchronous
serial lines.  If you're capturing serial line traffic to or from your
machine, the OS knows the encapsulation being used, so that libpcap can
find out from the OS whether it's PPP, Cisco HDLC, etc..  However, if
you're doing a passive capture, you'd have to tell it - there are settings
in Sniffer, for example, for that - so that was also done using that
libpcap feature.

> If we want to have it that detailed (which might be really a good idea),
we might want to put
> this into a new section and put a link to it?

We could do that.

>  >     The section on the snapshot length should perhaps discuss why you
> would want a smaller snapshot length (less CPU time spent copying
> packets, less buffer space required, so perhaps fewer packets dropped if
> traffic is heavy) and why you would not want a smaller snapshot length
> (you don't get all the packet data, and the stuff you want might be in
> the part that's dropped, or reassembly might not be done).
> I've added similar, please review

I'd either remove the "The value should be at least the MTU for the
interface you're capturing on", as the whole point of a short snapshot
length is *not* to capture all of the packet data, or say "If you want to
capture all of the data in each packet, the value should be...", but if
you want to capture all of the data in each packet, you should just
disable that field.

I'd make the second and third rules be

    If you don't need all of the data in a packet - for example, if you
only need the link-layer, IP, and TCP headers - you might want to
choose a smal snapshot length, as less CPU time is required for
copying packets, less buffer space is required for packets, and thus
perhaps fewer packets will be dropped if traffic is very heavy.

    If you don't capture all of the data in a packet, you might find that
the packet data you want is in the part that's dropped, or that
reassembly isn't possible as the data required for reassembly is
missing.

>  > P. 57:
>  >     "after the given number of ... were captured" should probably be
> "... have been captured", and "expired" should probably be "have
> expired" or "have elapsed".
> changed

The ones in section 4.2.2 "Capture File(s) frame" should also be changed.

>  > P. 61:
>  >
>  >     Would the reference in the first sentence to Kipling's poem be
> considered offensive by Indian readers (or mysterious to those not
> familiar with his poem)?
>
> Well, "or mysterious to those not familiar with his poem" might be true
> for a lot of people (like me).

    http://www.lockstockandbarrel.org/Poems/Kipling/gunga_din.html

> I've replaced it by a more general sentence, please review.

It looks good, although "to some extend" should be "to some extent".

>  > P. 67:
> I've put the sentence about dnd into a note and also added that it's not
> available on all desktop environments. please review.

>  >     The note on the open dialog should probably be

   ...

> As on win32 the GTK libs are installed by Ethereal, I've changed to a
> slightly different text, please review

It looks good, although "might be looking different" should be "might look
different".

>  > P. 70:
>  >
>  >     The note on the save dialog should probably be changed along the
> lines of the changes to the open dialog.
> changed

Again, "be looking different" should be "look different".

>  > P. 82:
>  >
>  >     "output of the packet bytes" should probably be "output of the
> packet bytes, just as in the "Packet Bytes" pane".
> changed

"just like in the "Packet List" pane" should probably also be "just as
in...".

>  > P. 91:
>  >
>  >     "All filter expressions are entered in lowercase" should be "all
> protocol and field names are entered in lowercase" (assuming nobody's
> added any mixed-case field names).
> That only complicates the text without adding additional information IMHO.

My concern was that somebody looking for, for example, an HTTP GET request
might think that even strings in the expression would have to be entered
in lower-case.

P. 97:

"*not*" should probably be italicized, rather than put in asterisks.

>  >     "hexdump" should be "hex dump" - and "Uncompressed entity body"
> probably isn't the name it'll have unless the entity was sent over the
> wire compressed, and even then the reassembled data will be in a tab
> labeled "Desegmented TCP".
> changed hex dump
> It was from a real life example I've seen, and they are only examples

But the "Uncompressed entity body" tab doesn't come from reassembly - if
reassembly is done in that case, the tab with the reassembled data would
be "Desegmented TCP".  The "Uncompressed entity body" tab would come from
uncompression, which could happen even if no reassembly was done.

P. 114:

In the warning, "ethereal" should be "Ethereal".

>  >     In section 7.4.2, another problem might be addresses for which
> there's no DNS entry on machines that don't support NetBIOS-over-TCP, if
> you're running Ethereal on Windows - NBNS address resolution is done by
> sending an NBNS packet to the IP address in question, and if that
> machine doesn't support NetBIOS-over-TCP, it won't respond.  Using ADNS
> would help there - because it means no NBNS name resolution will be
> done, so some IP addresses might not get resolved.
> I don't know how to write this down, and if it's that important.

The NBNS problem is probably very often the cause of Ethereal "hangs" on
Windows.

Also, that warning says "your DNS server" - the problem is that it's not
just your DNS server, it's whatever DNS servers are needed to resolve a
name, so you might have a problem even if your DNS server is working
perfectly.

>  > P. 115:
>  >
>  >     "informations" should be "information".
> changed

Some other places where that needs to be fixed:

P. 11: "the informations mentioned".

P. 49: "Ethereal will place informations".

P. 59: "these informations only for the loaded files".

>  >     "seperately" should be "separately".
> changed

One more place where that should be fixed - P. 114, "en-/disabled
seperately".