Initial revision
[obnox/wireshark/wip.git] / README
1 General Information
2 ------- -----------
3
4 Ethereal is a network traffic analyzer for Unix-ish operating systems.
5 It is based on GTK+, a graphical user interface library, and libpcap,
6 a packet capture and filtering library.
7
8 The official home of Ethereal is
9
10     http://ethereal.zing.org
11
12 The latest distribution can be found in the subdirectory
13
14     http://ethereal.zing.org/distribution
15
16
17 Installation
18 ------------
19
20 Ethereal is known to compile and run under Linux (2.0.35) and Solaris
21 (2.6).  It should run on other systems without too much trouble.
22
23
24 Installation Checklist (Short):
25
26   [ ] 1. Unpack the archive.
27
28   [ ] 2. Run './configure; make; make install; make install-man'.
29          If there are any problems, read on:
30
31
32 Installation Checklist (Long):
33
34   [ ] 0. This is alpha software.  Beware.
35   
36   [ ] 1. Make sure you have GTK+ installed.  Try running 'gtk-config
37          --version'.  If you need to install/reinstall GTK, you can find
38          it at
39
40          http://www.gtk.org .
41
42          Ethereal should work with the latest stable (1.0.x) version, but
43          I've had reports that it doesn't compile with the development
44          (1.1.x) tree.
45
46   [ ] 2. Make sure you have libpcap installed.  The latest version can be
47          found at
48           
49          ftp://ftp.ee.lbl.gov .
50
51          Make sure you install the headers ('make install-incl') when you
52          install the library.
53
54   [ ] 3. Run './configure' in the Ethereal distribution directory.
55          Running './configure --help' displays a list of options.
56          The file 'INSTALL' contains general instructions for running
57          'configure'.
58
59   [ ] 4. Run 'make'.  Hopefully, you won't run into any problems.
60
61   [ ] 5. Run './ethereal', and make sure things are working.  You must
62          have root privileges in order to capture live data.
63
64   [ ] 6. Run 'make install'.  If you wish to install the man page, run
65          'make install-man'.  You're done.
66
67          
68 Usage
69 -----          
70
71 In order to capture packets from the network, you need to be running
72 as root.  Although it might be tempting to make the Ethereal executable
73 setuid root, please don't - alpha code is by nature not very robust, and
74 liable to contain security holes.
75
76 The filtering mechanism is far from complete.  Until the interface
77 solidifies, here's a description of what each component of the filter
78 dialog:
79
80   - 'Filter name' entry: Gives a name to the filter you are about to create
81     or modify, e.g. 'Web and DNS traffic'
82     
83   - 'Filter string' entry: The text describing the filtering action to
84     take.  It must have the same format as tcpdump filter strings (both
85     programs use the same underlying library), e.g. 
86     
87     'tcp port 80 or tcp port 443 or port 53'
88
89   - 'New' button: If there is text in the two entry boxes, adds it to the
90     list.
91     
92   - 'Change' button: Modifies the currently selected list item to match
93     what's in the two entry boxes.
94     
95   - 'Copy' button: Makes a copy of the currently-selected list item.
96   
97   - 'Delete' button: Deletes the currently-selected list item.
98   
99   - 'OK' button: Sets the selected list item as the active filter.  If
100     nothing is selected, turns filtering off.
101     
102   - 'Save' button: Saves the current filter list in
103     $HOME/.ethereal/filters.
104     
105   - 'Cancel' button: Closes the window without making changes.
106
107
108 Disclaimer
109 ----------
110
111 There is no warranty, expressed or implied, associated with this product.
112 Use at your own risk.