From Michael Mann via https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=6377, with...
[obnox/wireshark/wip.git] / doc / README.packaging
1 The following guidelines should be followed by anyone distributing a software
2 package containing Wireshark:
3
4 1. URLs.
5
6 1.1. Wireshark web site.
7
8 The Wireshark web site URL is http://www.wireshark.org/ .
9
10 1.2. Wireshark releases.
11
12 The canonical location for every Wireshark source release is
13
14     http://www.wireshark.org/download/src/all-versions/, e.g.
15
16     http://www.wireshark.org/download/src/all-versions/wireshark-0.99.55.tar.bz2
17
18 If your packaging system downloads a copy of the Wireshark sources, use
19 this location. Don't use http://www.wireshark.org/download/src.
20
21 1.3. Artwork.
22
23 Logo and icon artwork can be found in the "image" directory in the
24 distribution. This is available online at
25
26     http://anonsvn.wireshark.org/wireshark/trunk/image/
27
28 2. Licensing.
29
30 Wireshark is released under the GNU General Public License version 2.
31 Make sure your package complies with this license.
32
33 3. Privileges.
34
35 In versions up to and including 0.99.6, it was necessary to run
36 Wireshark with elevated privileges in order to be able to capture
37 traffic. With version 0.99.7, all function calls that require elevated
38 privileges have been moved out of the GUI to dumpcap.
39
40 WIRESHARK CONTAINS OVER TWO MILLION LINES OF SOURCE CODE. DO NOT RUN
41 THEM AS ROOT.
42
43 Warnings are displayed when Wireshark and TShark are run as root.
44
45 There are several configure-time options on non-Windows systems that
46 affect the privileges a normal user needs to capture traffic and list
47 interfaces:
48   
49     --enable-setcap-install   Install dumpcap with cap_net_admin and
50                               cap_net_raw capabilities. Linux only.
51
52     --enable-setuid-install   Install dumpcap setuid root.
53
54     --with-libcap             If running as root, try to grab
55                               CAP_NET_ADMIN and CAP_NET_RAW, then drop
56                               privileges. Linux only.
57
58     --with-dumpcap-group=...  Restricts dumpcap execution to the
59                               specified group.
60
61 These are necessary for non-root users to be able to capture on most
62 systems, e.g. on Linux or FreeBSD if the user doesn't have permissions
63 to access /dev/bpf*. Setcap installation is preferred over setuid on
64 Linux. If "--enable-setcap-install" is used it will override any setuid
65 settings.
66
67 The "--with-libcap" option is only useful when dumpcap is installed
68 setuid. If it is enabled dumpcap will try to drop any setuid privileges
69 it may have while retaining the CAP_NET_ADMIN and CAP_NET_RAW
70 capabilities. It is enabled by default, if the Linux capabilities
71 library (on which it depends) is found.
72
73 Note that enabling setcap or setuid installation allows packet capture
74 for ALL users on your system. If this is not desired, you can restrict
75 dumpcap execution to a specific group or user. The following two examples
76 show how to restrict access using setcap and setuid respectively:
77
78 # groupadd -g packetcapture
79 # chmod 750 /usr/bin/dumpcap
80 # chgrp packetcapture /usr/bin/dumpcap
81 # setcap cap_net_raw,cap_net_admin+eip /usr/bin/dumpcap
82
83 # groupadd -g packetcapture
84 # chgrp packetcapture /usr/bin/dumpcap
85 # chmod 4750 /usr/bin/dumpcap
86
87 4. Customization.
88
89 Custom version information can be added by creating a file called
90 "version.conf" and running "make-version.pl -p". See make-version.pl for
91 details. If your package contains significant changes we recommend that
92 you use this to differentiate it from official Wireshark releases.
93
94 4.1. Source-level version detection.
95
96 The SVN version corresponding to each release is in svnversion.h. It's
97 defined as a string. If you need a numeric definition, let us know.
98
99 5. Trademarks.
100
101 Wireshark and the "fin" logo are registered trademarks of the Wireshark
102 Foundation.
103
104 6. Spelling.
105
106 Wireshark is spelled with a capital "W", and with everything else lower
107 case. E.g., "WireShark" is incorrect.
108
109
110 If you have a question not addressed here, send it to
111 wireshark-dev@wireshark.org.
112
113 $Id$