From 7f25a1197631f88d855dfbdf09b48a998b02c42c Mon Sep 17 00:00:00 2001 From: Eric Newberry Date: Sun, 31 May 2015 11:23:25 -0700 Subject: [PATCH] README and manpages for ndnping and ndnpingserver refs #2818 Change-Id: I5ada2f4adbc234f0fdf11452560199df73a5314e --- manpages/conf.py | 2 ++ manpages/ndnping.rst | 63 ++++++++++++++++++++++++++++++++++++++ manpages/ndnpingserver.rst | 53 ++++++++++++++++++++++++++++++++ tools/ping/README.md | 38 +++++++++++++++++++++++ 4 files changed, 156 insertions(+) create mode 100644 manpages/ndnping.rst create mode 100644 manpages/ndnpingserver.rst create mode 100644 tools/ping/README.md diff --git a/manpages/conf.py b/manpages/conf.py index 20709a9..ea32680 100644 --- a/manpages/conf.py +++ b/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), ] diff --git a/manpages/ndnping.rst b/manpages/ndnping.rst new file mode 100644 index 0000000..41fc7a3 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/manpages/ndnpingserver.rst b/manpages/ndnpingserver.rst new file mode 100644 index 0000000..da948d1 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/tools/ping/README.md b/tools/ping/README.md new file mode 100644 index 0000000..d5b536d --- /dev/null +++ b/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`. \ No newline at end of file