diff options
| -rw-r--r-- | INSTALL | 180 | ||||
| -rw-r--r-- | doc/README.packaging | 28 | ||||
| -rw-r--r-- | docbook/wsdg_src/WSDG_chapter_tools.asciidoc | 82 |
3 files changed, 123 insertions, 167 deletions
@@ -17,31 +17,31 @@ README.windows for those instructions. 0. This is software. Beware. -1. If you wish to build Wireshark, make sure you have GTK+ and GLib - installed. Try running 'pkg-config glib-2.0 --modversion' to see if - you have GLib 2.x installed. Then try running - 'pkg-config gtk+-3.0 --modversion' to see if you - have GTK+ 3.x installed and, if that fails, try running - 'pkg-config gtk+-2.0 --modversion' to see if you have GTK+ 2.x installed. - Wireshark needs version 3.0.0 or above of gtk+-3.0 or 2.12.0 or above of - gtk+-2.0 and version 2.16.0 or above of glib-2.0. If you need to install - or re-install GTK+ or GLIB, you can find the packages at: - - http://www.gtk.org - - If you installed GTK+ from a binary package, you may have to - install a "development" package; there may be separate "user's" - and "developer's" packages, with the former not including - header files and the like. For example, Red Hat users will - need to install a "gtk-devel" .rpm. - - Note also that Wireshark configuration defaults to using GTK+ 3.x; - you need to configure with --disable-gtk3 to use GTK+ 2.x. +1. If you wish to build Wireshark, make sure you have the Qt and GLib + development packages installed. Try running + 'pkg-config glib-2.0 --modversion' to see if you have GLib 2.x + installed. Then try running 'pkg-config Qt5Widgets --modversion' + to see if you have Qt installed. Wireshark needs version 4.8 or above + of Qt, although 5.2 and above are strongly recommended. It needs + version 2.22.0 or above of glib-2.0. If you need to install or + re-install GLIB, you can find the packages at: + + https://www.gtk.org + + You can find Qt at: + + https://www.qt.io/download + + If you installed Qt or GLib from binary packages, you may have to + install corresponding "development" packages; there may be separate + "user's" and "developer's" packages, with the former not including + header files and the like. For example, Red Hat users will need to + install a "glib2-devel" .rpm. + 2. If you wish to build TShark, the line-mode version of Wireshark, - make sure you have GLIB installed. See note #1 above for instructions - on checking if you have GLIB installed. You can download GLIB from - the same site as GTK. + make sure you have GLib installed. See note #1 above for instructions + on checking if you have GLib installed. 3. If you want to capture packets, make sure you have libpcap installed. The latest "official" version can be found at @@ -62,122 +62,98 @@ README.windows for those instructions. 5. Building Wireshark requires Python. -6. Run './configure' in the Wireshark distribution directory. - Running './configure --help' displays a complete list of options. - The file 'INSTALL.configure' contains general instructions for - using 'configure' and 'make'. Some of the Wireshark non-generic - configure options are as follows: - - --disable-usr-local - By default 'configure' will look in /usr/local/{include,lib} for - additional header files and libraries. Using this switch keeps - 'configure' from looking there - - --disable-wireshark - By default 'configure' tries to find the GTK+ libraries so Wireshark, - the GUI packet analyzer, can be built. You can disable the build of - the GUI version of Wireshark with this switch. +6. Create a build directory separate from the source directory. It can + be anywhere, but you might run into issues if the path contains + spaces. - --without-gtk3 - Don't try to build a Gtk+ 3.x-based Wireshark. If given in - conjunction with --disable-gtk2 then the Gtk+ GUI is disabled (and - only the Qt GUI is built). +7. Run 'cmake <options> <path/to/the/wireshark/sources>' in your build + directory. Running 'cmake -L' displays a complete list of options. + The "Tool Reference" section of Developer's Guide contains general + instructions for using CMake. Some of the Wireshark-specific options + are as follows: - --without-gtk2 - Don't try to build a Gtk+ 2.x-based Wireshark. If given in - conjunction with --disable-gtk3 then the Gtk+ GUI is disabled (and - only the Qt GUI is built). + -G Ninja + CMake supports many different build systems, including UNIX + Make, MSBuild, and Ninja. UNIX Make is the default, but Ninja + tends to be faster. - --without-qt - Don't try to build a Qt-based Wireshark. + -DBUILD_wireshark=OFF + By default CMake tries to find the Qt libraries so Wireshark, + the GUI packet analyzer, can be built. You can disable the + build of the GUI version of Wireshark with this switch. - --disable-tshark + -DBUILD_tshark=OFF By default the line-mode packet analyzer, TShark, is built. Use this switch to avoid building it. - --disable-editcap + -DBUILD_editcap=OFF By default the capture-file editing program is built. Use this switch to avoid building it. - --disable-capinfos + -DBUILD_capinfos=OFF By default the capture-file statistics reporting pogram is built. Use this switch to avoid building it. - --disable-captype + -DBUILD_captype=OFF By default the capture-type reporting pogram is built. Use this switch to avoid building it. - --disable-mergecap + -DBUILD_mergecap=OFF By default the capture-file merging program is built. Use this switch to avoid building it. - --disable-reordercap + -DBUILD_reordercap=OFF By default the capture-file reordering program is built. Use this switch to avoid building it. - --disable-text2pcap + -DBUILD_text2pcap=OFF By default the hex-dump-to-capture file conversion program is built. Use this switch to avoid building it. - --disable-dftest + -DBUILD_dftest=OFF By default the display-filter-compiler test program is built. Use this switch to avoid building it. - --disable-randpkt + -DBUILD_randpkt=OFF By default the program which creates random packet-capture files is built. Use this switch to avoid building it. - --disable-dumpcap + -DBUILD_dumpcap=OFF By default the network traffic capture program is built. Use this switch to avoid building it. - --disable-rawshark + -DBUILD_rawshark=OFF By default the program used to dump and analyze raw libpcap data is built. Use this switch to avoid building it. - --disable-ipv6 - If 'configure' finds support for IPv6 name resolution on - your system, the packet analyzers will make use of it. - To avoid using IPv6 name resolution if you have the support for it, - use this switch. - - --enable-setuid-install - Wireshark and TShark rely on dumpcap for packet capture. Setting this - flag installs dumpcap with setuid root permissions, which lets any user - on the system capture live traffic. If this is not desired, you can - restrict dumpcap's permissions so that only a single user or group can - run it. This can be used in conjunction with --with-libcap described - below. + -DDUMPCAP_INSTALL_OPTION=suid + -DDUMPCAP_INSTALL_OPTION=capabilities + Wireshark and TShark rely on dumpcap for packet capture. Setting + this flag to "suid" installs dumpcap with setuid root + permissions, which lets any user on the system capture live + traffic. If this is not desired, you can restrict dumpcap's + permissions so that only a single user or group can run it and + set the "capabilities" flag. Running Wireshark or TShark as root is not recommended. - --without-libcap - By default, if 'configure' finds libcap (the POSIX capabilities + -DENABLE_CAP=OFF + By default, if 'cmake' finds libcap (the POSIX capabilities library) dumpcap will be built so that if it is installed setuid root, it will attempt to retain CAP_NET_RAW and CAP_NET_ADMIN before dropping root privileges. Use this option to disable this behavior. - --with-libcap=DIR - Use this option to tell 'configure' where libcap is installed, - if it is installed in a non-standard location. Note that libcap - (the POSIX capabilities library, sans "p") and libpcap (the - packet capture library, avec "p") are two very different things. - - --without-pcap + -DENABLE_PCAP=OFF If you choose to build a packet analyzer that can analyze capture files but cannot capture packets on its own, but you *do* have libpcap installed, or if you are trying to build Wireshark on a system that doesn't have libpcap installed (in which case you have no choice but to build a version that can analyze capture files but cannot capture packets on its own), - use --without-pcap to avoid using libpcap. + use -DENABLE_PCAP=OFF to avoid using libpcap. - --with-pcap=DIR - Use this to tell Wireshark where you have libpcap installed, if - it is installed in a non-standard location. - - --without-zlib + -DENABLE_ZLIB=OFF By default, if 'configure' finds zlib (a.k.a, libz), the wiretap library will be built so that it can read compressed capture files. If you have zlib but do not wish to build @@ -185,43 +161,29 @@ README.windows for those instructions. the capture-file utilities that come in this package, use this switch. - --with-zlib=DIR - Use this to tell Wireshark where you have zlib installed, if it - is installed in a non-standard location. - - --without-plugins + -DENABLE_PLUGINS=OFF By default, if your system can support run-time loadable modules, the packet analyzers are build with support for plugins. Use this switch to build packet analyzers without plugin support. - --with-plugins=DIR - By default, plugins are installed in - ${LIBDIR}/wireshark/plugins/${VERSION} - - ${LIBDIR} can be set with --libdir, or defaults to ${EPREFIX/lib} - ${EPREFIX} can be set with --exec-prefix, or defaults to ${PREFIX} - ${VERSION} is the Wireshark version. - - Use this switch to change the location where plugins - are installed. - -7. After running './configure', you will see a summary of some +8. After running 'cmake', you will see a summary of some of the options you chose. Ensure that the summary reflects - what you want. If it doesn't, re-run './configure' with new options. + what you want. If it doesn't, re-run 'cmake' with new options. -8. Run 'make'. Hopefully, you won't run into any problems. +9. Run 'make', or 'ninja' if you chose to create Ninja build files. + Hopefully, you won't run into any problems. -9. Run './wireshark' or './tshark' or ./dumpcap, and make sure things are +10. Run './wireshark' or './tshark' or ./dumpcap, and make sure things are working. You must have root privileges in order to capture live data. -10./a. Run 'make install'. If you're running a system that supports +11./a. Run 'make install'. If you're running a system that supports the RPM packaging systems you can run make rpm-package to make an installable package for your system. -10/b. If you 're running a system that supports APT (Debian/Ubuntu/etc.) +11/b. If you 're running a system that supports APT (Debian/Ubuntu/etc.) run dpkg-buildpackage -us -uc -rfakeroot diff --git a/doc/README.packaging b/doc/README.packaging index 3665a2073a..86d443af64 100644 --- a/doc/README.packaging +++ b/doc/README.packaging @@ -13,7 +13,7 @@ The canonical location for every Wireshark source release is https://www.wireshark.org/download/src/all-versions/, e.g. - https://www.wireshark.org/download/src/all-versions/wireshark-2.4.5.tar.xz + https://www.wireshark.org/download/src/all-versions/wireshark-2.6.5.tar.xz If your packaging system downloads a copy of the Wireshark sources, use this location. Don't use https://www.wireshark.org/download/src. @@ -32,10 +32,7 @@ newer. Make sure your package complies with this license. 3. Privileges. -In versions up to and including 0.99.6, it was necessary to run -Wireshark with elevated privileges in order to be able to capture -traffic. With version 0.99.7, all function calls that require elevated -privileges have been moved out of the GUI to dumpcap. +All function calls that require elevated privileges are in dumpcap. WIRESHARK CONTAINS OVER TWO MILLION LINES OF SOURCE CODE. DO NOT RUN THEM AS ROOT. @@ -46,25 +43,20 @@ There are several configure-time options on non-Windows systems that affect the privileges a normal user needs to capture traffic and list interfaces: - --enable-setcap-install Install dumpcap with cap_net_admin and - cap_net_raw capabilities. Linux only. + -DDUMPCAP_INSTALL_OPTION=capabilities + Install dumpcap with cap_net_admin and cap_net_raw capabilities. + Linux only. - --enable-setuid-install Install dumpcap setuid root. - - --with-libcap If running as root, try to grab - CAP_NET_ADMIN and CAP_NET_RAW, then drop - privileges. Linux only. - - --with-dumpcap-group=... Restricts dumpcap execution to the - specified group. + -DDUMPCAP_INSTALL_OPTION=suid + Install dumpcap setuid root. These are necessary for non-root users to be able to capture on most systems, e.g. on Linux or FreeBSD if the user doesn't have permissions to access /dev/bpf*. Setcap installation is preferred over setuid on -Linux. If "--enable-setcap-install" is used it will override any setuid -settings. +Linux. If "-DDUMPCAP_INSTALL_OPTION=capabilities" is used it will +override any setuid settings. -The "--with-libcap" option is only useful when dumpcap is installed +The "-DENABLE_CAP" option is only useful when dumpcap is installed setuid. If it is enabled dumpcap will try to drop any setuid privileges it may have while retaining the CAP_NET_ADMIN and CAP_NET_RAW capabilities. It is enabled by default, if the Linux capabilities diff --git a/docbook/wsdg_src/WSDG_chapter_tools.asciidoc b/docbook/wsdg_src/WSDG_chapter_tools.asciidoc index ed7705ad03..f8e1891d4b 100644 --- a/docbook/wsdg_src/WSDG_chapter_tools.asciidoc +++ b/docbook/wsdg_src/WSDG_chapter_tools.asciidoc @@ -161,48 +161,17 @@ One or more Cygwin packages can be installed using `cyg-get`: PS$>cyg-get sed asciidoc ---- -[[ChToolsGNUChain]] - -=== GNU compiler toolchain (UNIX only) - -[[ChToolsGCC]] - -==== gcc (GNU compiler collection) - -The GCC C compiler is available for most of the -UNIX-like platforms. - -If GCC isn't already installed or available -as a package for your platform, you can get it at: -http://gcc.gnu.org/[]. - -After correct installation, typing at the -bash command line prompt: - ----- -$ gcc --version ----- - -should result in something like - ----- -gcc (Ubuntu 4.9.1-16ubuntu6) 4.9.1 -Copyright (C) 2014 Free Software Foundation, Inc. -This is free software; see the source for copying conditions. There is NO -warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. ----- - -Your version string may vary, of course. - [[ChToolsCMake]] -Wireshark’s build environment can be configured using CMake on Windows -and either CMake or Autotools on Linux, macOS, and UNIX. CMake is designed -to support out of tree builds. So much so, that in tree builds do not work -properly in all cases. Along with being cross-platform, CMake supports -many build tools and environments including traditional make, Ninja, and -MSBuild. Our Buildbot runs CMake steps on Ubuntu, Win32, Win64, and macOS. -In particular, the macOS and Windows packages are built using CMake. +=== CMake + +Wireshark’s build environment can be configured using CMake on Windows, +Linux, macOS, and UNIX. CMake is designed to support out of tree builds. +So much so, that in tree builds do not work properly in all cases. Along +with being cross-platform, CMake supports many build tools and +environments including traditional make, Ninja, and MSBuild. Our +Buildbot runs CMake steps on Ubuntu, Win32, Win64, and macOS. In +particular, the macOS and Windows packages are built using CMake. Building with CMake typically includes creating a build directory and specifying a *generator*, aka a build tool. For example, to build @@ -267,6 +236,39 @@ Frequently Asked Questions: http://www.cmake.org/Wiki/CMake_FAQ // 2017-08-04 dead //Additional cmake modules: http://code.google.com/p/cmake-modules/ +[[ChToolsGNUChain]] + +=== GNU compiler toolchain (UNIX only) + +[[ChToolsGCC]] + +==== gcc (GNU compiler collection) + +The GCC C compiler is available for most of the +UNIX-like platforms. + +If GCC isn't already installed or available +as a package for your platform, you can get it at: +http://gcc.gnu.org/[]. + +After correct installation, typing at the +bash command line prompt: + +---- +$ gcc --version +---- + +should result in something like + +---- +gcc (Ubuntu 4.9.1-16ubuntu6) 4.9.1 +Copyright (C) 2014 Free Software Foundation, Inc. +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +---- + +Your version string may vary, of course. + [[ChToolsGDB]] ==== gdb (GNU project debugger) |