README and manpages for ndnping and ndnpingserver

refs #2818

Change-Id: I5ada2f4adbc234f0fdf11452560199df73a5314e

manpages/conf.py

@@ -8,4 +8,6 @@ project = u'NDN Essential Tools'
 man_pages = [
     ('ndnpeek', 'ndnpeek', 'simple consumer to send one Interest and expect one Data', None, 1),
     ('ndnpoke', 'ndnpoke', 'simple producer to publish one Data', None, 1),
+    ('ndnping', 'ndnping', 'reachability testing client', None, 1),
+    ('ndnpingserver', 'ndnpingserver', 'reachability testing server', None, 1),
 ]

manpages/ndnping.rst

@@ -0,0 +1,63 @@
+ndnping
+=======
+
+Usage
+-----
+
+::
+
+    ndnping [-h] [-V] [-i interval] [-o timeout] [-c count] [-n start] [-p identifier] [-a] [-t] prefix
+
+Description
+-----------
+
+``ndnping`` is a reachability testing tool that sends Interest packets and expects Data packets in
+response. If Data packets are not received within the timeout period for their Interest,
+``ndnping`` marks them as timed out. If ``ndnping`` does receive a Data packet within the timeout,
+the time from sending the Interest to receiving the Data is recorded and displayed. Once
+``ndnping`` either reaches the specified total number of Interests to be sent or receives an
+interrupt signal, it prints statistics on the Interests, including the number of Interests sent,
+the number of Data packets received, and the average response time of the Data.
+
+``prefix`` is interpreted as the Interest prefix. The name of the sent Interest consists of the
+prefix followed by "ping", the optional identifier specified by the '-p' option, and finally a
+sequence number as a decimal number string.
+
+Options
+-------
+
+``-h``
+  Print help and exit.
+
+``-V``
+  Print version and exit.
+
+``-i``
+  Set ping interval in milliseconds (default 1000ms - minimum 1ms).
+
+``-o``
+  Set ping timeout in milliseconds (default 4000ms).
+
+``-c``
+  Set total number of Interests to be sent.
+
+``-n``
+  Set the starting sequence number, which is incremented by 1 after each Interest sent.
+
+``-p``
+  Adds specified identifier to the Interest names before the numbers to avoid conflict.
+
+``-a``
+  Allows routers to return stale Data from cache.
+
+``-t``
+  Prints a timestamp with received Data and timeouts.
+
+Examples
+--------
+
+Test reachability for ``ndn:/edu/arizona`` using 4 Interest packets and print timestamp
+
+::
+
+    ndnping -c 4 -t ndn:/edu/arizona

manpages/ndnpingserver.rst

@@ -0,0 +1,53 @@
+ndnping
+=======
+
+Usage
+-----
+
+::
+
+    ndnpingserver [-h] [-V] [-x freshness] [-p satisfy] [-t] [-s size] prefix
+
+Description
+-----------
+
+``ndnpingserver`` listens for the specified Interest prefix and sends Data packets when an Interest
+under that prefix is received. Once ``ndnpingserver`` either reaches the specified total number of
+Interests to be satisfied or receives an interrupt signal, it prints the number of Data packets
+sent.
+
+``prefix`` is interpreted as the Interest prefix to listen for. The FreshnessPeriod of Data packets
+is set with the -x option (default 1000ms). The content is by default empty, but if a size is
+specified with the '-s' option, it contains the specified number of the letter "a". Finally, the
+Data is signed with an SHA256 digest.
+
+Options
+-------
+
+``-h``
+  Print help and exit.
+
+``-V``
+  Print version and exit.
+
+``-x``
+  Set freshness period in milliseconds (minimum 1000ms).
+
+``-p``
+  Set maximum number of pings to satisfy.
+
+``-t``
+  Prints a timestamp with received Data and timeouts.
+
+``-s``
+  Specify the size of the response payload.
+
+Examples
+--------
+
+Listen on ``ndn:/edu/arizona`` and response to at most 4 pings, printing timestamp on each received
+ping
+
+::
+
+    ndnpingserver -p 4 -t ndn:/edu/arizona

tools/ping/README.md

@@ -0,0 +1,38 @@
+# ndnping and ndnpingserver
+
+## Introduction
+
+**ndnping** and **ndnpingserver** are reachability testing tools for
+[Named Data Networking](http://named-data.net). They test the reachability between two nodes. The
+client sends an Interest intended for a node running **ndnpingserver**. The ping server then sends
+Data in response. The client then calculates the roundtrip time for the Interest-Data exchange, or
+marks it as a timeout if the Data is not received within the timeout period.
+
+## Using the Client
+
+The client can be invoked by calling **ndnping** with a name to ping. For example, to ping
+`ndn:/edu/arizona`, one would execute::
+
+    ndnping ndn:/edu/arizona
+
+There are also a variety of options to control the behavior of the ping client. For example, to
+send only four pings to `ndn:/edu/arizona`, displaying a timestamp with each received Data or
+timeout, type::
+
+    ndnping -c 4 -t ndn:/edu/arizona
+
+A list of the available options can be found with `man ndnping`.
+
+## Using the Server
+
+The server can be invoked by calling **ndnpingserver** with a name to listen for pings to. For
+example, to listen for pings to `ndn:/edu/arizona`, one would execute::
+
+    ndnpingserver ndn:/edu/arizona
+
+There are also a variety of options to control the behavior of the ping server. For example, to
+satisfy only 4 ping requests before exiting, execute the following::
+
+    ndnpingserver -p 4 ndn:/edu/arizona
+
+A list of the available options can be found with `man ndnpingserver`.