docs: Adding manpages for the command-line tools

Change-Id: I3eba0d125f7da51696342edce1a2f1ee33a0471a
refs: #1446
diff --git a/docs/manpages/ndn-autoconfig-server.rst b/docs/manpages/ndn-autoconfig-server.rst
index 923347b..8ed7968 100644
--- a/docs/manpages/ndn-autoconfig-server.rst
+++ b/docs/manpages/ndn-autoconfig-server.rst
@@ -1,19 +1,41 @@
+.. _ndn-autoconfig-server:
+
 ndn-autoconfig-server
 =====================
 
-Synopsis
---------
+Usage
+-----
 
 ::
 
-    ndn-autoconfig-server [-h] Uri
+    ndn-autoconfig-server [-h] FaceUri
 
 
 Description
 -----------
 
+``ndn-autoconfig-server`` is a daemon that implements server part for the stage 1 of
+:ref:`NDN hub discovery procedure`.
+
+This daemon essentially waits for Interests for ``/localhop/ndn-autoconf/hub`` and
+satisfies them with a Data packet that contains TLV-encoded FaceUri block.  The value of
+this block is the ``Uri`` for the HUB, preferrably a UDP tunnel.
+
+``-h``
+  print usage and exit.
+
+``FaceUri``
+  FaceUri for this NDN hub.
+
+Examples
+--------
+
 ::
 
-    -h print usage and exit
+    ndn-autoconfig-server tcp://spurs.cs.ucla.edu
 
-    Uri - a FaceMgmt URI
+
+See also
+--------
+
+:ref:`ndn-autoconfig`
diff --git a/docs/manpages/ndn-autoconfig.rst b/docs/manpages/ndn-autoconfig.rst
index 07233a5..8e56435 100644
--- a/docs/manpages/ndn-autoconfig.rst
+++ b/docs/manpages/ndn-autoconfig.rst
@@ -1,18 +1,28 @@
+.. _ndn-autoconfig:
+
 ndn-autoconfig
 ==============
 
-Synopsis
---------
+Usage
+-----
 
 ::
 
     ndn-autoconfig
 
+Description
+-----------
+
+Client tool to run :ref:`NDN hub discovery procedure`.
+
+.. _NDN hub discovery procedure:
 
 NDN hub discovery procedure
 ---------------------------
 
-When an end host starts up, or detects a change in its network environment, it MAY use this procedure to discover a local or home NDN router, in order to gain connectivity to `the NDN research testbed <http://named-data.net/ndn-testbed/>`_.
+When an end host starts up, or detects a change in its network environment, it MAY use
+this procedure to discover a local or home NDN router, in order to gain connectivity to
+`the NDN research testbed <http://named-data.net/ndn-testbed/>`_.
 
 Overview
 ^^^^^^^^
@@ -23,7 +33,7 @@
     This is useful in a home or small office network.
 
 2.  Look for a local NDN router by DNS query with default suffix.
-    This allows network administrator to configure a NDN router for a large enterprise network.
+    This allows network administrator to configure a NDN router in a large enterprise network.
 
 3.  Connect to the home NDN router according to user certificate.
     This ensures connectivity from anywhere.
@@ -41,8 +51,9 @@
 Response
 ++++++++
 
-A producer app on the HUB answer this Interest with a Data packet that contains a TLV-encoded `Uri` block.
-The value of this block is the URI for the HUB, preferrably a UDP tunnel.
+A producer app on the HUB answer this Interest with a Data packet that contains a
+TLV-encoded `Uri` block.  The value of this block is the URI for the HUB, preferrably a
+UDP tunnel.
 
 Stage 2: DNS query with default suffix
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -57,26 +68,32 @@
 Response
 ++++++++
 
-The DNS server should answer with an SRV record that contains the hostname and UDP port number of the NDN router.
+The DNS server should answer with an SRV record that contains the hostname and UDP port
+number of the NDN router.
 
 Stage 3: find home router
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This stage assumes that user has configured default certificate using `<http://ndncert.named-data.net/>`_ as described in `Certification Architecture <http://redmine.named-data.net/attachments/download/23/CertificationArchitecture.pptx>`_.
+This stage assumes that user has configured default certificate using
+`<http://ndncert.named-data.net/>`_ as described in `Certification Architecture
+<http://redmine.named-data.net/attachments/download/23/CertificationArchitecture.pptx>`_.
 
 Request
 +++++++
 
-The end host loads the default user identity (eg. ``/ndn/edu/ucla/cs/afanasev``), and converts it to DNS format.
+The end host loads the default user identity (eg. ``/ndn/edu/ucla/cs/afanasev``), and
+converts it to DNS format.
 
-The end host sends a DNS query for an SRV record of name ``_ndn._udp.`` + user identity in DNS format + ``_homehub._autoconf.named-data.net``. For example::
+The end host sends a DNS query for an SRV record of name ``_ndn._udp.`` + user identity in
+DNS format + ``_homehub._autoconf.named-data.net``. For example::
 
     _ndn._udp.afanasev.cs.ucla.edu.ndn._homehub._autoconf.named-data.net
 
 Response
 ++++++++
 
-The DNS server should answer with an SRV record that contains the hostname and UDP port number of the home NDN router of this user's site.
+The DNS server should answer with an SRV record that contains the hostname and UDP port
+number of the home NDN router of this user's site.
 
 Client procedure
 ----------------
@@ -98,7 +115,15 @@
 Stage 3
 ^^^^^^^
 
-* Load default user identity, and convert it to DNS format; if either fails, the auto-discovery fails.
+* Load default user identity, and convert it to DNS format; if either fails, the
+  auto-discovery fails.
 
 * Send a DNS query to find home HUB.
-  If this query is answered, connect to the home HUB and terminate auto-discovery. Otherwise, the auto-discovery fails.
+  If this query is answered, connect to the home HUB and terminate auto-discovery.
+  Otherwise, the auto-discovery fails.
+
+
+See also
+--------
+
+:ref:`ndn-autoconfig-server`
diff --git a/docs/manpages/ndn-tlv-peek.rst b/docs/manpages/ndn-tlv-peek.rst
new file mode 100644
index 0000000..9b2a7e4
--- /dev/null
+++ b/docs/manpages/ndn-tlv-peek.rst
@@ -0,0 +1,56 @@
+ndn-tlv-peek
+============
+
+Usage
+-----
+
+::
+
+    ndn-tlv-peek [-h] [-f] [-r] [-m min] [-M max] [-l lifetime] [-p] [-w timeout] name
+
+Description
+-----------
+
+``ndn-tlv-peek`` is a simple consumer program that sends one Interest and expects one Data
+packet in response.  The full Data packet (in TLV format) is written to stdout.  The
+program terminates with return code 0 if Data arrives, and with return code 1 when timeout
+occurs.
+
+``name`` is interpreted as the Interest name.
+
+Options
+-------
+
+``-h``
+  Print help and exit
+
+``-f``
+  If specified, set ``MustBeFresh`` selector in the Interest packet.
+
+``-r``
+  Set ``ChildSelector=1`` (the rightmost child) selector.
+
+``-m``
+  Set ``min`` as the ``MinSuffixComponents`` selector.
+
+``-M``
+  Set ``max`` as the ``MaxSuffixComponents`` selector.
+
+``-l``
+  Set ``lifetime`` (in milliseconds) as the ``InterestLifetime``.
+
+``-p``
+  If specified, print the received payload only, not the full packet.
+
+``-w``
+  Timeout after ``timeout`` milliseconds.
+
+
+Examples
+--------
+
+Send Interest for ``ndn:/app1/video`` and print the received payload only
+
+::
+
+    ndn-tlv-peek -p ndn:/app1/video
diff --git a/docs/manpages/ndn-tlv-poke.rst b/docs/manpages/ndn-tlv-poke.rst
new file mode 100644
index 0000000..73acb82
--- /dev/null
+++ b/docs/manpages/ndn-tlv-poke.rst
@@ -0,0 +1,54 @@
+ndn-tlv-poke
+============
+
+Usage
+-----
+
+::
+
+    ndn-tlv-poke [-h] [-f] [-D] [-i identity] [-F] [-x freshness] [-w timeout] name
+
+Description
+-----------
+
+``ndn-tlv-poke`` is a simple producer program that reads payload from stdin and publishes it
+as a single NDN Data packet.  The Data packet is published either as a response to the
+incoming Interest for the given ``name``, or forcefully pushed to the local NDN
+forwarder's cache if ``-f`` flag is specified.
+
+The program terminates with return code 0 if Data is sent and with return code 1 when
+timeout occurs.
+
+Options
+-------
+
+``-h``
+  Print usage and exit.
+
+``-f``
+  If specified, send Data without waiting for Interest.
+
+``-D``
+  If specified, use ``DigestSha256`` signature instead of default ``SignatureSha256WithRsa``.
+
+``-i``
+  Use ``identity`` to sign the created Data packet.
+
+``-F``
+  Set ``FinalBlockId`` to the last component of specified name.
+
+``-x``
+  Set ``FreshnessPeriod`` in milliseconds.
+
+``-w``
+  Wait at most ``timeout`` milliseconds for the incoming Interest.  If no Interest arrives
+  within the ``timeout``, the Data packet will not be published.
+
+
+Examples
+--------
+
+Create Data packet with content ``hello`` with the name ``ndn:/app/video`` and wait at
+most 3 seconds for the incoming Interest for it::
+
+    echo "Hello" | build/bin/ndn-tlv-poke -w 3000 ndn:/app/video
diff --git a/docs/manpages/nfd-autoreg.rst b/docs/manpages/nfd-autoreg.rst
new file mode 100644
index 0000000..168528d
--- /dev/null
+++ b/docs/manpages/nfd-autoreg.rst
@@ -0,0 +1,57 @@
+ndn-autoreg
+===========
+
+Usage
+-----
+
+::
+
+    nfd-autoreg --prefix=</autoreg/prefix> [--prefix=</another/prefix>] ...
+
+Description
+-----------
+
+``autoreg-server`` is a deamon application that automatically registers the specified
+prefix(es) when new on-demand Face is created (i.e., when a new UDP face is created
+as a result of an incoming packet or TCP face is created as a result of an incoming
+connection).
+
+Options
+-------
+
+``-h`` or ``--help``
+  Produce help message.
+
+``-i`` or ``--prefix``
+  Prefix that should be automatically registered when a new remote face is created.
+  Can be repeated multiple to specify additional prefixes.
+
+``-c`` or ``--cost``
+  RIB cost to be assigned to auto-registered prefixes.   if not specified, default cost
+  is set to 255.
+
+``-w`` or ``--whitelist``
+  Whitelisted network, e.g., 192.168.2.0/24 or ::1/128.   Can be repeated multiple times
+  to specify multiple whitelisted networks.
+
+  Prefix(es) will be auto-registered only when remote IP address is within the specified
+  range(s), except blacklist ranges.
+
+  Default: 0.0.0.0/0 and ::/0
+
+``-b`` or ``--blacklist``
+  Blacklisted network, e.g., 192.168.2.32/30 or ::1/128.  Can be repeated multiple times
+  to specify multiple blacklisted networks.
+
+  Prefix(es) will be auto-registered only when remote IP address in **NOT** within the
+  specified range(s), but is within the range define by the whitelist(s).
+
+  Default: none
+
+Examples
+--------
+
+Auto-register two prefixes for any newly created on-demand Face, except those that has
+source IP address in ``10.0.0.0/8`` network::
+
+    nfd-autoreg --prefix=/app1/video --prefix=/app2/pictures -b 10.0.0.0/8
diff --git a/docs/manpages/nfd-status-http-server.rst b/docs/manpages/nfd-status-http-server.rst
new file mode 100644
index 0000000..a6aa0eb
--- /dev/null
+++ b/docs/manpages/nfd-status-http-server.rst
@@ -0,0 +1,43 @@
+nfd-status-http-server
+======================
+
+Usage
+-----
+
+::
+
+    nfd-status-http-server [-h] [-p port number] [-a IP address] [-r] [-v]
+
+Description
+-----------
+
+``nfd-status-http-server`` is a daemon that enables retrieval of NFD status via HTTP protocol.
+
+Options
+-------
+
+``-h``
+  Show this help message and exit.
+
+``-p``
+  HTTP server port number (default is 8080).
+
+``-a``
+  HTTP server IP address (default is 127.0.0.1).
+
+``-r``
+  Enable HTTP robots to crawl (disabled by default).
+
+``-v``
+  Verbose mode.
+
+Examples
+--------
+
+Enable NFD HTTP status server on all IPv4 interfaces::
+
+    nfd-status-http-server -p 80 -a 0.0.0.0
+
+Enable NFD HTTP status server on all IPv6 interfaces::
+
+    nfd-status-http-server -p 80 -a ::
diff --git a/docs/manpages/nfd-status.rst b/docs/manpages/nfd-status.rst
new file mode 100644
index 0000000..cf80991
--- /dev/null
+++ b/docs/manpages/nfd-status.rst
@@ -0,0 +1,64 @@
+nfd-status
+==========
+
+Usage
+-----
+
+::
+
+    nfd-status [options]
+
+Description
+-----------
+
+``nfd-status`` is a tool to retrieve and print out NFD version and status information.
+
+Options:
+--------
+
+``-h``
+  Print usage information.
+
+``-v``
+  Retrieve version information.
+
+``-f``
+  Retrieve face status information.
+
+``-b``
+  Retrieve FIB information.
+
+If no options are provided, all information is retrieved.
+
+Examples
+--------
+
+Get all status information from NFD::
+
+    $ nfd-status
+    General NFD status:
+                   version=1000
+                 startTime=20140427T230936.006000
+               currentTime=20140427T231055.924000
+                    uptime=79 seconds
+          nNameTreeEntries=12
+               nFibEntries=4
+               nPitEntries=2
+      nMeasurementsEntries=0
+                nCsEntries=24
+              nInInterests=20
+             nOutInterests=19
+                  nInDatas=24
+                 nOutDatas=19
+    Faces:
+      faceid=1 remote=internal:// local=internal:// counters={in={0i 24d} out={20i 0d}}
+      faceid=2 remote=udp4://224.0.23.170:56363 local=udp4://192.168.0.106:56363 counters={in={0i 0d} out={0i 0d}}
+      faceid=3 remote=udp4://224.0.23.170:56363 local=udp4://127.0.0.1:56363 counters={in={0i 0d} out={0i 0d}}
+      faceid=5 remote=fd://16 local=unix:///private/tmp/nfd.sock counters={in={12i 1d} out={1i 11d}}
+      faceid=8 remote=tcp4://131.179.196.46:6363 local=tcp4://192.168.0.106:56118 counters={in={0i 0d} out={0i 0d}}
+      faceid=9 remote=fd://17 local=unix:///private/tmp/nfd.sock counters={in={2i 0d} out={0i 1d}}
+    FIB:
+      /localhost/nfd nexthops={faceid=1 (cost=0)}
+      /localhop/nfd/rib nexthops={faceid=5 (cost=0)}
+      /ndn nexthops={faceid=8 (cost=0)}
+      /localhost/nfd/rib nexthops={faceid=5 (cost=0)}
diff --git a/docs/manpages/nfd.rst b/docs/manpages/nfd.rst
index 6ebef97..0fa0ef8 100644
--- a/docs/manpages/nfd.rst
+++ b/docs/manpages/nfd.rst
@@ -1,8 +1,8 @@
 nfd
 ===
 
-Synopsis
---------
+Usage
+-----
 
 ::
 
@@ -12,8 +12,27 @@
 Description
 -----------
 
+NFD forwarding daemon.
+
+
+Options:
+--------
+
+``--help``
+  Print this help message.
+
+``--modules``
+  List available logging modules
+
+``--config <path/to/nfd.conf>``
+  Specify the path to nfd configuration file (default: ``${SYSCONFDIR}/ndn/nfd.conf``).
+
+Examples
+--------
+
+Start NFD forwarding daemon as super user and use a configuration file from the current
+working directory.
+
 ::
 
-    [--help]   - print this help message
-    [--modules] - list available logging modules
-    [--config /path/to/nfd.conf] - path to configuration file (default: /usr/local/etc/ndn/nfd.conf)
+    sudo nfd --config nfd.conf
diff --git a/docs/manpages/nfdc.rst b/docs/manpages/nfdc.rst
new file mode 100644
index 0000000..c2006c1
--- /dev/null
+++ b/docs/manpages/nfdc.rst
@@ -0,0 +1,179 @@
+nfdc
+====
+
+Usage
+-----
+
+::
+
+    nfdc [-h] COMMAND [<command options>]
+
+
+Description
+-----------
+
+``nfdc`` is a tool to manipulate routing information base (RIB), forwarding information
+base (FIB), and StrategyChoices table (i.e., which strategy should be used by which
+namespaces).
+
+Options
+-------
+
+``-h``
+  Print usage information.
+
+``COMMAND``
+
+  ``register``
+    Register a new or update existing routing entry in Routing Information Base (RIB).
+
+    ``register [-I] [-C] [-c <cost>] <prefix> <faceId | faceUri>``
+
+      ``-I``
+        Unset CHILD_INHERIT flag from the routing entry.
+
+      ``-C``
+        Set CAPTURE flag in the routing entry.
+
+      ``-c <cost>``
+        Cost for the RIB entry (default is 0).
+
+      ``prefix``
+        A prefix of an existing or to be created RIB entry, for which routing entry is
+        requested to be added or updated.
+
+      ``faceId``
+        An existing NFD Face ID number, which can be obtained, for example, using
+        ``nfd-status`` command.
+
+      ``faceUri``
+        URI of the existing or to be created Face.
+
+  ``unregister``
+    Unregister an existing routing entry from Routing Information Base (RIB).
+
+    ``unregister <prefix> <faceId>``
+
+      ``prefix``
+        A prefix of an existing RIB entry, from which routing entry is requested to be
+        removed.
+
+      ``faceId``
+        An existing NFD Face ID number, which can be obtained, for example, using
+        ``nfd-status`` command.
+
+  ``create``
+    Create a UDP unicast or TCP Face
+
+    ``create <faceUri>``
+
+      ``faceUri``
+        UDP unicast or TCP Face URI::
+
+            UDP unicast:    udp[4|6]://<remote-IP-or-host>[:<remote-port>]
+            TCP:            tcp[4|6]://<remote-IP-or-host>[:<remote-port>]
+
+  ``destroy``
+    Create an existing UDP unicast or TCP Face.
+
+    ``destroy <faceId | faceUri>``
+
+      ``faceId``
+        An existing NFD Face ID number, which can be obtained, for example, using
+        ``nfd-status`` command.
+
+      ``faceUri``
+        UDP unicast or TCP Face URI::
+
+            UDP unicast:    udp[4|6]://<remote-IP-or-host>[:<remote-port>]
+            TCP:            tcp[4|6]://<remote-IP-or-host>[:<remote-port>]
+
+  ``set-strategy``
+    Select strategy to be used for the specified namespace
+
+    ``set-strategy <namespace> <strategy-name>``
+
+      ``namespace``
+        Namespace that will use the specified strategy.
+
+        Note that more specific namespace(s) can use different strategy or strategies.
+        For example, if namespace ``/A/B/C`` was using strategy
+        ``ndn:/localhost/nfd/strategy/best-route`` before running ``set-strategy`` on
+        ``/A`` namespace, it will continue using the same strategy no matter which
+        namespace was specified for ``/A``.
+
+      ``strategy-name``
+        Name of one of the available strategies.
+
+        Currently, NFD supports the following strategies::
+
+            ndn:/localhost/nfd/strategy/best-route
+            ndn:/localhost/nfd/strategy/broadcast
+            ndn:/localhost/nfd/strategy/client-control
+            ndn:/localhost/nfd/strategy/ncc
+
+  ``unset-strategy``
+    Unset the strategy for a given ``namespace``.
+
+    Effectively, this command select parent's namespace strategy to be used for the
+    specified ``namespace``.
+
+    ``unset-strategy <namespace>``
+
+      ``namespace``
+        Namespace from which namespace customization should be removed.
+
+  ``add-nexthop``
+    Directly add nexthop entry info NFD's Forwarding Information Base (FIB).  This command
+    is intended only for debugging purposes.  Normally, prefix-nexhop association should
+    be registered in Routing Information Base using ``register`` command.
+
+    ``add-nexthop [-c <cost>] <prefix> <faceId | faceUri>``
+
+      ``-c <cost>``
+        Cost for the nexthop entry to be inserted (default is 0).
+
+      ``prefix``
+        A prefix of an existing or to be created FIB entry, to which nexthop
+        entry is requested to be added.
+
+      ``faceId``
+        An existing NFD Face ID number, which can be obtained, for example, using
+        ``nfd-status`` command
+
+      ``faceUri``
+        URI of the existing or to be created Face.
+
+  ``remove-nexthop``
+    Directly remove nexthop entry from NFD'S FIB.  This command
+    is intended only for debugging purposes.  Normally, prefix-nexhop association should
+    be unregistered from Routing Information Base using ``unregister`` command.
+
+    ``remove-nexthop <prefix> <faceId>``
+
+      ``prefix``
+        A prefix of an existing FIB entry, from which nexthop entry is requested to be removed.
+
+      ``faceId``
+        An existing NFD Face ID number, which can be obtained, for example, using
+        ``nfd-status`` command.
+
+        Note that when ``faceId`` is the last Face associated with ``prefix`` FIB entry,
+        the whole FIB entry will be removed.
+
+
+
+Examples
+--------
+
+Add a namespace to a face uri:
+
+::
+
+    nfdc register ndn:/app1/video udp://192.168.1.2
+
+Set strategy to a name:
+
+::
+
+    nfdc set-strategy ndn:/app1/video ndn:/localhost/nfd/strategy/broadcast
diff --git a/docs/manpages/nrd.rst b/docs/manpages/nrd.rst
index 2f03b2a..31fb384 100644
--- a/docs/manpages/nrd.rst
+++ b/docs/manpages/nrd.rst
@@ -1,67 +1,34 @@
 NRD (NFD RIB Daemon)
-========================
+====================
 
-NRD is a complementary daemon designed to work in parallel with NFD
-and to provide services for Routing Information Base management and
-constructing NFD's FIB:
+Usage
+-----
+
+::
+
+    nrd [options]
+
+
+Description
+-----------
+
+NRD is a complementary daemon designed to work in parallel with NFD and to provide
+services for Routing Information Base management and constructing NFD's FIB:
 
 * prefix registration from applications;
 * manual prefix registration;
 * prefix registrations from multiple dynamic routing protocols.
 
-Running and Configuring NRD
----------------------------
+NRD's runtime settings may be modified via `rib_*` sections in NFD's configuration file.
 
-NRD's runtime settings may be modified via configuration file. After
-installation, a working sample configuration is provided at
-``SYSCONFDIR/ndn/nrd.conf.sample``. At startup, NRD will attempt to read
-the default configuration file from following location:
-``SYSCONFDIR/ndn/nrd.conf``.
+Options:
+--------
 
-You may also specify an alternative configuration file location by
-running NRD with:
+``--help``
+  Print this help message.
 
-::
+``--modules``
+  List available logging modules
 
-    nrd --config </path/to/nrd.conf>
-
-Currently, nrd.conf contains only a security section, which is well
-documented in the sample configuration file.
-
-Starting experiments
---------------------
-
-1. Build, install and setup NFD by following the directions provided in
-   README.md in NFD root folder.
-
-2. Create certificates by following the instructions in NFD's README.md
-
-3. Build and install NRD by following the directions in INSTALL.md
-
-4. Create nrd.conf file. You can simply copy the provided sample file in
-   ``SYSCONFDIR/ndn/nrd.conf``.
-
-5. Setup the trust-anchors in nrd.conf. Ideally, the prefix registration
-   Interest should be signed by application/user key, and this
-   application/user key should be used as trust-anchor. However,
-   currently the default certificate is used to sign the registration
-   Interests. Therefore, for initial testing the default certificate
-   should be set as the trust-anchor. For doing so, the default
-   certificate should be copied in the same folder where the nrd.conf
-   is. Secondly, the trust-anchor should point to the copied certificate
-   in nrd.conf. To know the id of default certificate you can use:
-
-   ~$ ndnsec-get-default
-
-6. Start NFD (assuming the NFD's conf file exist in
-   ``SYSCONFDIR/ndn/nfd.conf``):
-
-   ~$ nfd
-
-7. Start NRD (assuming the conf file exist in
-   ``SYSCONFDIR/ndn/nrd.conf``):
-
-   ~$ nrd
-
-8. Try to connect any application to NFD. For example, producer
-   application that is provided ndn-cxx examples.
+``--config <path/to/nfd.conf>``
+  Specify the path to nfd configuration file (default: ``${SYSCONFDIR}/ndn/nfd.conf``).