Give more detailed information about capture permissions on Debian.

Indicate what you're supposed to do when running dpkg-reconfigure
wireshark-common, and indicate that you have to run it as root using
sudo.

Emphasize in README.Debian, and indicate in the permission failure
secondary message, that you have to add users to the "wireshark" group
after doing that, and that a user may have to log out and log in again
to make this change take effect.

Bug: 14847
Change-Id: Ia83ff8e92bd2f00b6c3779272322a40201416da0
Reviewed-on: https://code.wireshark.org/review/28206
Reviewed-by: Guy Harris <guy@alum.mit.edu>

1 files changed, 29 insertions, 12 deletions

diff --git a/debian/README.Debian b/debian/README.Debian
index 048717f57d..eb553d7da9 100644
--- a/debian/README.Debian
+++ b/debian/README.Debian
@@ -1,7 +1,9 @@
 
 I. Capturing packets with Wireshark/Tshark
 
-   There are two ways of installing Wireshark/Tshark on Debian:
+   There are two ways of installing Wireshark/Tshark on Debian; the
+   installation process may offer a choice between these two ways,
+   asking "Should non-superuser be able to capture packets?"
 
    I./a. Installing dumpcap without allowing non-root users to capture packets
 
@@ -9,7 +11,8 @@ I. Capturing packets with Wireshark/Tshark
       packets with the bundled dumpcap program as root and then run
       Wireshark/Tshark as an ordinary user to analyze the captured logs. [2]
 
-      This is the default on Debian systems.
+      This is the default on Debian systems; it is selected by answering
+      "<No>" to the question mentioned above.
 
    I./b. Installing dumpcap and allowing non-root users to capture packets
 
@@ -19,15 +22,26 @@ I. Capturing packets with Wireshark/Tshark
       that way only the dumpcap process has to be run with elevated privileges
       thanks to the privilege separation[1].
 
-      Note that no user will be added to group wireshark automatically, the
-      system administrator has to add them manually. After a user is added
-      to the wireshark group she/he may need to log in again to make her/his new
-      group membership take effect and be able to capture packets.
+      This is selected by answering "<Yes>" to the question mentioned
+      above.
+
+      Note that no user will be added to group wireshark automatically;
+      a system administrator has to add them manually, using the usermod
+      command:
+
+         sudo usermod -a -G wireshark {username}
+
+      or, if you're using a desktop environment that includes a tool for
+      managing users, such as the "Users and Groups" tool in GNOME (found
+      in the gnome-system-tools package), using that tool.  After a user
+      is added to the wireshark group, she/he may need to log in again to
+      make her/his new group membership take effect and be able to capture
+      packets.
 
       The additional privileges are provided using the Linux Capabilities
-      system where it is available and resort to setting the set-user-id bit
-      of the dumpcap binary as a fall-back, where the Linux Capabilities system
-      is not present (Debian GNU/kFreeBSD, Debian GNU/Hurd).
+      system where it is available and resorting to setting the set-user-id
+      bit of the dumpcap binary as a fall-back, where the Linux Capabilities
+      system is not present (Debian GNU/kFreeBSD, Debian GNU/Hurd).
 
       Linux kernels provided by Debian support Linux Capabilities, but custom
       built kernels may lack this support. If the support for Linux
@@ -42,10 +56,13 @@ I. Capturing packets with Wireshark/Tshark
       Note that capturing USB packets is not enabled for non-root users by using
       Linux Capabilities. You have to capture the packets using the method
       described in I./a., setting the set-user-id permanently using
-      dpkg-statoverride or running Wireshark as root.
+      dpkg-statoverride or running dumpcap as root.
+
+      The installation method can be changed any time by running:
+
+         sudo dpkg-reconfigure wireshark-common
 
-   The installation method can be changed any time by running:
-   dpkg-reconfigure wireshark-common
+      The question mentioned above will be asked; answer "<Yes>" to it.
 
 
 II. Installing SNMP MIBs