docs/manpages/ndn-autoconfig.rst

.. _ndn-autoconfig:

ndn-autoconfig
==============

Usage
-----

::

    ndn-autoconfig [options]

Description
-----------

Client tool to run :ref:`NDN hub discovery procedure`.

Options
-------

``-d`` or ``--daemon``
  Run ndn-autoconfig in daemon mode. In this mode, the auto-discovery procedure is re-run
  hourly or when a network change event is detected.

  NOTE: if connection to NFD fails, the daemon will be terminated.

``-c [FILE]`` or ``--config=[FILE]``
  Use the specified configuration file. If `enabled = true` is not specified in the
  configuration file, no actions will be performed.

``--ndn-fch-url=[URL]``
  Use the specified URL to find the closest hub (NDN-FCH protocol).  If not specified,
  ``http://ndn-fch.named-data.net/`` will be used.  Only ``http://`` URLs are supported.

``-h`` or ``--help``
  Print help message and exit.

``-V`` or ``--version``
  Show version information and exit.

.. _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 NDN router, in order to gain connectivity to
`the NDN research testbed <https://named-data.net/ndn-testbed/>`__.
This procedure can discover either an NDN router in the local network, or a NDN testbed
gateway router (commonly known as a "hub").

Overview
^^^^^^^^

This procedure contains four methods to discover a NDN router:

1.  Look for a local NDN router by multicast.
    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 in a large enterprise network.

3.  Find closest hub by sending an HTTP request to NDN-FCH server.

4.  Connect to the home hub according to user certificate.
    This ensures connectivity from anywhere.

After connecting, two prefixes will be registered toward the router:

- ``/`` --- this allows application communication
- ``/localhop/nfd`` --- this informs NFD-RIB that there is connectivity to a router

Stage 1: multicast discovery
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Request
+++++++

The end host sends Interest ``/localhop/ndn-autoconf/hub`` over a multicast face.

Response
++++++++

A producer app on the router answers this Interest with a Data packet that contains a
``Uri`` TLV element.  The value of this element is the FaceUri for the router, such as
a UDP tunnel.

Stage 2: DNS query with default suffix
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Request
+++++++

The end host sends a DNS query that is equivalent to this command::

    dig +search +short +cmd +tries=2 +ndots=10 _ndn._udp srv

Response
++++++++

The DNS server should answer with an SRV record that contains the hostname and UDP port
number of a nearby NDN router.

Stage 3: HTTP Request to NDN-FCH server
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This stage uses a simple HTTP-based API.  For more information about NDN-FCH server, refer
to the `NDN-FCH README file <https://github.com/named-data/ndn-fch>`__.

Request
+++++++

HTTP/1.0 request for the NDN-FCH server URI (`<http://ndn-fch.named-data.net/>`__ by default)

Response
++++++++

The HTTP response is expected to be a hostname or an IP address of the closest hub,
inferred using IP-geo approximation service.

Stage 4: find home router
^^^^^^^^^^^^^^^^^^^^^^^^^

This stage assumes that user has configured default certificate using
`<https://ndncert.named-data.net/>`__ as described in `Certification Architecture
<https://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 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 hub of this user's site.

Client procedure
----------------

Stage 1
^^^^^^^

Send a multicast discovery Interest.
If this Interest is answered, connect to the router and terminate auto-discovery.

Stage 2
^^^^^^^

Send a DNS query with default suffix.
If this query is answered, connect to the router and terminate auto-discovery.

Stage 3
^^^^^^^

Send HTTP request to NDN-FCH server.
If request succeeds, attempt to connect to the discovered hub and terminate
auto-discovery.

Stage 4
^^^^^^^

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.

Exit status
-----------

0: No error.

1: An unspecified error occurred.

2: Malformed command line, e.g., invalid, missing, or unknown argument.

4: Insufficient privileges.

See also
--------

:ref:`ndn-autoconfig-server`, :doc:`ndn-autoconfig.conf`