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``).