X-Git-Url: https://git.octo.it/?p=liboping.git;a=blobdiff_plain;f=README;h=8611d7c65f748db7aa37be32b4126e8811cc8c02;hp=5e665fac57d962215646290b8326d53c95b355f6;hb=HEAD;hpb=4e4bc38b4c5913b3482e464ab23fbed08e45c8b6

diff --git a/README b/README
index 5e665fa..8611d7c 100644
--- a/README
+++ b/README
@@ -1,6 +1,6 @@
  liboping – Library to ping IPv4 and IPv6 hosts in parallel
 ════════════════════════════════════════════════════════════
-http://verplant.org/liboping/
+http://noping.cc/
 
 About
 ━━━━━
@@ -10,6 +10,11 @@ About
   IPv4 or IPv6 transparently. Other design principles were an object oriented
   interface, simplicity and extensibility.
 
+  On top of liboping two command line applications have been built. “oping” is
+  a drop-in replacement for ping(1) with very similar output. “noping” is an
+  ncurses-based application which displays statistics while pinging and
+  highlights aberrant round-trip times.
+
 
 Features
 ━━━━━━━━
@@ -30,8 +35,63 @@ Perl bindings
   “--without-perl-bindings”.
 
 
+Permissions
+━━━━━━━━━━━━━
+
+  On UNIX, special permissions are required to open raw sockets (raw(7)). If
+  you compile and install the “oping” and “noping” binaries as normal user
+  (which is strongly suggested), you won't be able to use the binaries as a
+  normal user, because you won't have the permission to open raw sockets.
+
+  The “install” target will automatically try fix this, if it is run with UID~0
+  (as user root).  When on Linux, the capabilities described below will be
+  added. On other UNIXes the traditional Set-UID method (also described below)
+  is used instead. The build system will not abort if this fails, because there
+  are file systems which do not support either method. Also, the Debian
+  packaging system and possibly other scenarios only act as if they were
+  running as root.
+
+  Linux
+  ━━━━━
+  On Linux, the preferred method is to assign the required “capability” to the
+  binaries. This will allow the binary to open raw sockets, but doesn't give
+  any other permissions such as reading other users' files or shutting down the
+  system. The downside is that this mechanism is comparatively new: Assigning
+  capabilities to files is available since Linux 2.6.24.
+
+  To set the required capabilities, run (as user root):
+
+    # setcap cap_net_raw=ep /opt/oping/bin/oping
+    # setcap cap_net_raw=ep /opt/oping/bin/noping
+
+  Other UNIX
+  ━━━━━━━━━━
+  Capabilities are a nice but Linux-specific solution. To make “oping” and
+  “noping” available to unprivileged users on other UNIX systems, use the
+  traditional set-UID root solution. If your system supports “saved set-UIDs”
+  (basically all systems do), the applications will drop the privileges during
+  initialization and only regain them when actually opening the socket(s).
+
+  To set the set-UID bit, run (as user root):
+
+    # chown root: /opt/oping/bin/{,n}oping
+    # chmod u+s   /opt/oping/bin/{,n}oping
+
+
+Licensing terms
+━━━━━━━━━━━━━━━
+
+  liboping is licensed under the “GNU Lesser General Public License” (LGPL),
+  version 2.1 or later. The exact licensing terms can be found in the file
+  “COPYING” included in the source distribution of liboping.
+
+  The “oping” and “noping” utilities included in this package are licensed
+  under the “GNU General Public License” (GPL), version 2. The full licensing
+  terms can be found online at <http://www.gnu.org/licenses/gpl-2.0.html>.
+
+
 Author
 ━━━━━━
 
-  Florian octo Forster <octo at verplant.org>
+  Florian “octo” Forster <ff at octo.it>