Initial revision
[obnox/wireshark/wip.git] / ethereal.1
1 .rn '' }`
2 ''' $RCSfile: ethereal.1,v $$Revision: 1.1 $$Date: 1998/09/16 02:39:18 $
3 '''
4 ''' $Log: ethereal.1,v $
5 ''' Revision 1.1  1998/09/16 02:39:18  gerald
6 ''' Initial revision
7 '''
8 ''' Revision 1.1.1.1  1998/08/30 17:53:24  gerald
9 ''' Imported sources
10 '''
11 '''
12 .de Sh
13 .br
14 .if t .Sp
15 .ne 5
16 .PP
17 \fB\\$1\fR
18 .PP
19 ..
20 .de Sp
21 .if t .sp .5v
22 .if n .sp
23 ..
24 .de Ip
25 .br
26 .ie \\n(.$>=3 .ne \\$3
27 .el .ne 3
28 .IP "\\$1" \\$2
29 ..
30 .de Vb
31 .ft CW
32 .nf
33 .ne \\$1
34 ..
35 .de Ve
36 .ft R
37
38 .fi
39 ..
40 '''
41 '''
42 '''     Set up \*(-- to give an unbreakable dash;
43 '''     string Tr holds user defined translation string.
44 '''     Bell System Logo is used as a dummy character.
45 '''
46 .tr \(*W-|\(bv\*(Tr
47 .ie n \{\
48 .ds -- \(*W-
49 .ds PI pi
50 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
51 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
52 .ds L" ""
53 .ds R" ""
54 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
55 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
56 '''   such as .IP and .SH, which do another additional levels of
57 '''   double-quote interpretation
58 .ds M" """
59 .ds S" """
60 .ds N" """""
61 .ds T" """""
62 .ds L' '
63 .ds R' '
64 .ds M' '
65 .ds S' '
66 .ds N' '
67 .ds T' '
68 'br\}
69 .el\{\
70 .ds -- \(em\|
71 .tr \*(Tr
72 .ds L" ``
73 .ds R" ''
74 .ds M" ``
75 .ds S" ''
76 .ds N" ``
77 .ds T" ''
78 .ds L' `
79 .ds R' '
80 .ds M' `
81 .ds S' '
82 .ds N' `
83 .ds T' '
84 .ds PI \(*p
85 'br\}
86 .\"     If the F register is turned on, we'll generate
87 .\"     index entries out stderr for the following things:
88 .\"             TH      Title 
89 .\"             SH      Header
90 .\"             Sh      Subsection 
91 .\"             Ip      Item
92 .\"             X<>     Xref  (embedded
93 .\"     Of course, you have to process the output yourself
94 .\"     in some meaninful fashion.
95 .if \nF \{
96 .de IX
97 .tm Index:\\$1\t\\n%\t"\\$2"
98 ..
99 .nr % 0
100 .rr F
101 .\}
102 .TH ETHEREAL 1 "0.3.8" "24/Aug/98" "The Ethereal Network Analyzer"
103 .UC
104 .if n .hy 0
105 .if n .na
106 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
107 .de CQ          \" put $1 in typewriter font
108 .ft CW
109 'if n "\c
110 'if t \\&\\$1\c
111 'if n \\&\\$1\c
112 'if n \&"
113 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
114 '.ft R
115 ..
116 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
117 .       \" AM - accent mark definitions
118 .bd B 3
119 .       \" fudge factors for nroff and troff
120 .if n \{\
121 .       ds #H 0
122 .       ds #V .8m
123 .       ds #F .3m
124 .       ds #[ \f1
125 .       ds #] \fP
126 .\}
127 .if t \{\
128 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
129 .       ds #V .6m
130 .       ds #F 0
131 .       ds #[ \&
132 .       ds #] \&
133 .\}
134 .       \" simple accents for nroff and troff
135 .if n \{\
136 .       ds ' \&
137 .       ds ` \&
138 .       ds ^ \&
139 .       ds , \&
140 .       ds ~ ~
141 .       ds ? ?
142 .       ds ! !
143 .       ds /
144 .       ds q
145 .\}
146 .if t \{\
147 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
148 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
149 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
150 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
151 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
152 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
153 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
154 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
155 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
156 .\}
157 .       \" troff and (daisy-wheel) nroff accents
158 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
159 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
160 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
161 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
162 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
163 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
164 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
165 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
166 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
167 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
168 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
169 .ds ae a\h'-(\w'a'u*4/10)'e
170 .ds Ae A\h'-(\w'A'u*4/10)'E
171 .ds oe o\h'-(\w'o'u*4/10)'e
172 .ds Oe O\h'-(\w'O'u*4/10)'E
173 .       \" corrections for vroff
174 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
175 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
176 .       \" for low resolution devices (crt and lpr)
177 .if \n(.H>23 .if \n(.V>19 \
178 \{\
179 .       ds : e
180 .       ds 8 ss
181 .       ds v \h'-1'\o'\(aa\(ga'
182 .       ds _ \h'-1'^
183 .       ds . \h'-1'.
184 .       ds 3 3
185 .       ds o a
186 .       ds d- d\h'-1'\(ga
187 .       ds D- D\h'-1'\(hy
188 .       ds th \o'bp'
189 .       ds Th \o'LP'
190 .       ds ae ae
191 .       ds Ae AE
192 .       ds oe oe
193 .       ds Oe OE
194 .\}
195 .rm #[ #] #H #V #F C
196 .SH "NAME"
197 Ethereal \- Interactively browse network traffic
198 .SH "SYNOPSYS"
199 \fBethereal\fR
200 [\ \fB\-v\fR\ ]
201 [\ \fB\-B\fR\ byte\ view\ height\ ]
202 [\ \fB\-c\fR\ count\ ]
203 [\ \fB\-i\fR\ interface\ ] 
204 [\ \fB\-P\fR\ packet\ list\ height\ ]
205 [\ \fB\-r\fR\ infile\ ]
206 [\ \fB\-s\fR\ snaplen\ ]
207 [\ \fB\-T\fR\ tree\ view\ height\ ]
208 [\ \fB\-w\fR\ savefile]
209 .SH "DESCRIPTION"
210 \fBEthereal\fR is a network protocol analyzer based on the \fBGTK+\fR GUI toolkit.  It lets
211 you interactively browse packet data from a live network or from a \fBpcap\fR
212 / \fBtcpdump()\fR formatted capture file.
213 .SH "OPTIONS"
214 .Ip "-B" 4
215 Sets the initial height of the byte view (bottom) pane
216 .Ip "-c" 4
217 The default number of packets to read when capturing live data.
218 .Ip "-i" 4
219 The name of the interface to use for live packet capture.  It should match
220 one of the names listed in \*(L"\fBnetstat \-i\fR\*(R" or \*(L"\fBifconfig \-a\fR\*(R".
221 .Ip "-P" 4
222 Sets the initial height of the packet list (top) pane
223 .Ip "-r" 4
224 Read packet data from \fIfile\fR.  Currently, \fBEthereal\fR only understands
225 \fBpcap\fR / \fBtcpdump\fR formatted files.
226 .Ip "-s" 4
227 The default snapshot length to use when capturing live data.  No more than
228 \fIsnaplen\fR bytes of each network packet will be read into memory, or saved
229 to disk.
230 .Ip "-T" 4
231 Sets the initial height of the tree view (top) pane
232 .Ip "-v" 4
233 Prints the version and exits.
234 .Ip "-w" 4
235 Sets the default capture file name.
236 .SH "INTERFACE"
237 .Sh "\s-1MENU\s0 \s-1ITEMS\s0"
238 .Ip "File:Open, File:Close" 4
239 Open or close a capture file.
240 .Ip "File:Print Packet" 4
241 Print a description of each protocol header found in the packet, followed
242 by the packet data itself.  Printing options can be set with the
243 \fIEdit:Menu Options\fR menu item.
244 .Ip "File:Quit" 4
245 Exits the application.
246 .Ip "Edit:Printer Options" 4
247 Sets the packet printing options (see the section on \fIPrinter Options\fR below).
248 .Ip "Tools:Capture" 4
249 Initiates a live packet capture (see the section on \fICapture Preferences\fR below).
250 .Ip "Tools:Filter" 4
251 Sets the filter preferences (see the section on \fIFilters\fR below).
252 .Sh "\s-1WINDOWS\s0"
253 .Ip "Main Window" 4
254 The main window is split into three sections.  You can resize each section
255 using a \*(L"thumb\*(R" at the right end of each divider line.  An informational
256 message is also displayed at the bottom of the main window.
257 .Sp
258 The top section contains the list of network packets that you can scroll
259 through and select.  The packet number, source and destination addresses,
260 protocol, and description are printed for each packet.  An effort is made
261 to display information as high up the protocol stack as possible, e.g. \s-1IP\s0
262 addresses are displayed for \s-1IP\s0 packets, but the \s-1MAC\s0 layer address is
263 displayed for unknown packet types.
264 .Sp
265 The middle section contains a \fIprotocol tree\fR for the currently-selected
266 packet.  The tree displays each field and its value in each protocol header
267 in the stack.
268 .Sp
269 The bottom section contains a hex dump of the actual packet data. 
270 Selecting a field in the \fIprotocol tree\fR highlights the appropriate bytes
271 in this section.
272 .Ip "Printer Options" 4
273 The \fIPrinter Options\fR dialog lets you select the output format of packets
274 printed using the \fIFile:Print Packet\fR menu item.
275 .Sp
276 The radio buttons at the top of the dialog allow you choose between 
277 printing the packets as text or PostScript, and sending the output
278 directly to a command or saving it to a file.  The \fICommand:\fR text entry
279 box is the command to send files to (usually \fBlpr\fR), and the \fIFile:\fR
280 entry box lets you enter the name of the file you wish to save to. 
281 Additinally, you can select the \fIFile:\fR button to browse the file system
282 for a particular save file.
283 .Ip "Capture Preferences" 4
284 The \fICapture Preferences\fR dialog lets you specify various parameters for
285 capturing live packet data.
286 .Sp
287 The \fIInterface:\fR entry box lets you specify the interface from which to
288 capture packet data.  The \fICount:\fR entry specifies the number of packets
289 to capture.  Entering 0 will capture packets indefinitely.  The \fIFile:\fR
290 entry specifies the file to save to, as in the \fIPrinter Options\fR dialog
291 above.  You can choose to open the file after capture, and you can also
292 specify the maximum number of bytes to capture per packet with the
293 \fICapture length\fR entry.
294 .Ip "Filters" 4
295 The \fIFilters\fR dialog lets you create and modify filters, and set the
296 default filter to use when capturing data or opening a capture file.
297 .Sp
298 The \fIFilter name\fR entry specifies a descriptive name for a filter, e.g.
299 \fBWeb and \s-1DNS\s0 traffic\fR.  The \fIFilter string\fR entry is the text that
300 actually describes the filtering action to take.  It must have the same
301 format as \fBtcpdump\fR filter strings, since both programs use the same
302 underlying library.  A filter for \s-1HTTP\s0, \s-1HTTPS\s0, and \s-1DNS\s0 traffic might look
303 like this:
304 .Sp
305 .Vb 1
306 \&  tcp port 80 or tcp port 443 or port 53
307 .Ve
308 The dialog buttons perform the following actions:
309 .Ip "New" 12
310 If there is text in the two entry boxes, it creates a new associated list
311 item.
312 .Ip "Change" 12
313 Modifies the currently selected list item to match what's in the entry
314 boxes.
315 .Ip "Copy" 12
316 Makes a copy of the currently selected list item.
317 .Ip "Delete" 12
318 Deletes the currently selected list item.
319 .Ip "\s-1OK\s0" 12
320 Sets the currently selected list item as the active filter.  If  nothing
321 is selected, turns filtering off.
322 .Ip "Save" 12
323 Saves the current filter list in \fI$\s-1HOME\s0/.ethereal/filters\fR.
324 .Ip "Cancel" 12
325 Closes the dialog without making any changes.
326 .SH "SEE ALSO"
327 the \fItcpdump(1)\fR manpage, the \fIpcap(3)\fR manpage
328 .SH "NOTES"
329 The latest version of \fBethereal\fR can be found at
330 \fBhttp://ethereal.zing.org\fR.
331 .SH "AUTHORS"
332 .Sp
333 .Vb 3
334 \&  Original Author
335 \&  -------- ------
336 \&  Gerald Combs  <gerald@zing.org>
337 .Ve
338 .Vb 6
339 \&  Contributors
340 \&  ------------
341 \&  Gilbert Ramirez Jr.  <gram@verdict.uthscsa.edu>
342 \&  Hannes R. Boehm      <hannes@boehm.org>
343 \&  Mike Hall            <mlh@io.com>
344 \&  cpg                  <cpg@rocketmail.com>
345 .Ve
346 Theo de Raadt <deraadt@cvs.openbsd.org> was kind enough to give his
347 permission to use his version of snprintf.c.
348 .Sp
349 Dan Lasley <dlasley@promus.com> gave permission for his \fIdumpit()\fR hex-dump
350 routine to be used.
351
352 .rn }` ''
353 .IX Title "ETHEREAL 1"
354 .IX Name "Ethereal - Interactively browse network traffic"
355
356 .IX Header "NAME"
357
358 .IX Header "SYNOPSYS"
359
360 .IX Header "DESCRIPTION"
361
362 .IX Header "OPTIONS"
363
364 .IX Item "-B"
365
366 .IX Item "-c"
367
368 .IX Item "-i"
369
370 .IX Item "-P"
371
372 .IX Item "-r"
373
374 .IX Item "-s"
375
376 .IX Item "-T"
377
378 .IX Item "-v"
379
380 .IX Item "-w"
381
382 .IX Header "INTERFACE"
383
384 .IX Subsection "\s-1MENU\s0 \s-1ITEMS\s0"
385
386 .IX Item "File:Open, File:Close"
387
388 .IX Item "File:Print Packet"
389
390 .IX Item "File:Quit"
391
392 .IX Item "Edit:Printer Options"
393
394 .IX Item "Tools:Capture"
395
396 .IX Item "Tools:Filter"
397
398 .IX Subsection "\s-1WINDOWS\s0"
399
400 .IX Item "Main Window"
401
402 .IX Item "Printer Options"
403
404 .IX Item "Capture Preferences"
405
406 .IX Item "Filters"
407
408 .IX Item "New"
409
410 .IX Item "Change"
411
412 .IX Item "Copy"
413
414 .IX Item "Delete"
415
416 .IX Item "\s-1OK\s0"
417
418 .IX Item "Save"
419
420 .IX Item "Cancel"
421
422 .IX Header "SEE ALSO"
423
424 .IX Header "NOTES"
425
426 .IX Header "AUTHORS"
427