docs/experiment.rst

Experiment
==========

Configuration
-------------

Mini-NDN uses a configuration file describing the topology and its parameters to setup a network.

The [nodes] section:

At the bare minimum, the node section describes the nodes present in the
topology.

::

    [nodes]
    a: key1=value1 key2=value2
    b: key1=value1

Any key and value passed here is accessible in Mini-NDN as:

::

    ndn = Minindn(...)
    value = ndn.net.hosts[0].params['params'].get('key1', "defaultValue")

One can specify log levels for each node's NFD and NLSR using this key-value system:

::

    [nodes]
    a: nfd-log-level=DEBUG nlsr-log-level=DEBUG
    b: nfd-log-level=INFO

To specify a log level for certain modules of NFD, the following line can be added to `nfd.py`:

::

   node.cmd('infoedit -f {} -s log.Forwarder -v {}'.format(self.confFile, 'INFO'))

This will turn on FORWARDER logging to INFO for all nodes.

.. Todo: Add switch section

The [links] section:

The links section describes the links in the topology.

::

    e.g.)

    [links]
    a:b delay=10ms

This would create a link between a and b. 'b:a' would also result in the
same. The following parameters can be configured for a node:

-  delay : Delay parameter is a required parameter which defines the
   delay of the link (1-1000ms)

-  bw : Bandwidth of a link (<1-1000> Mbps)

-  loss : Percentage of packet loss (<1-100>)

Example configuration file

::

    [nodes]
    a:
    b:
    [links]
    a:b delay=10ms bw=100

See ``ndn_utils/topologies`` for more sample files

Sample
------

Sample experiment may written as follows:

.. code:: python

    from mininet.log import setLogLevel, info

    from minindn.minindn import Minindn
    from minindn.util import MiniNDNCLI
    from minindn.apps.appmanager import AppManager
    from minindn.apps.nfd import Nfd
    from minindn.apps.nlsr import Nlsr
    from minindn.helpers.routing_helper import IPRoutingHelper

    if __name__ == '__main__':
        setLogLevel('info')

        Minindn.cleanUp()
        Minindn.verifyDependencies()

        # Can pass a custom parser, custom topology, or any Mininet params here
        ndn = Minindn()

        ndn.start()

        # IP reachability if needed
        # IPRoutingHelper.calcAllRoutes(ndn.net)
        # info("IP routes configured, start ping\n")
        # ndn.net.pingAll()

        # Start apps with AppManager which registers a clean up function with ndn
        info('Starting NFD on nodes\n')
        nfds = AppManager(ndn, ndn.net.hosts, Nfd)
        info('Starting NLSR on nodes\n')
        nlsrs = AppManager(ndn, ndn.net.hosts, Nlsr)

        # or can not start NLSRs with some delay in between:
        # nlsrs = AppManager(ndn, ndn.net.hosts, Nlsr)
        # for host in ndn.net.hosts:
        #     nlsrs.startOnNode(host)
        #     time.sleep(30)

        MiniNDNCLI(ndn.net)

        # Calls the clean up functions registered via AppManager
        ndn.stop()

Users may look at how the NFD and NLSR applications are written as a sub class of Application
in the ``minindn/apps`` folder. Or users may choose to directly run their application on nodes
such as ndnpingserver is run in ``minindn/helpers/experiment.py``.

Execution
---------

To run Mini-NDN with the default topology,
``ndn_utils/topologies/default-topology.conf``, type:

::

    sudo python examples/minindn.py

To run Mini-NDN with a topology file, provide the filename as the first
argument:

::

    sudo python examples/minindn.py my-topology.conf

After Mini-NDN is installed, users can run examples from anywhere with python directly as follows:

::

    sudo python /path/to/myexample.py

The user no longer needs to create an experiment in the old Mini-NDN way, then install it to the system before executing it via the minindn binary. The new examples can be separate from the Mini-NDN folder if the core is not being modified.

CLI Interface
_____________

During set up, the list of nodes in the network will be listed as they
are initialized:

::

    *** Adding hosts:
    a b c d

After set up, the command-line interface (CLI) will display a prompt.

::

    mini-ndn>

To interact with a node, first type the node's name and then the command
to be executed:

::

    mini-ndn> a echo "Hello, world!"
    Hello, world!

To see the status of the forwarder on the node:

::

    mini-ndn> a nfdc status report

To see the status of routing on the node:

::

    mini-ndn> a nlsrc status

To exit Mini-NDN, type ``quit`` in the CLI or use ``ctrl + D``:

::

    mini-ndn> quit

``Ctrl + C`` is used to quit an application run in the foreground of the command line.

For a more in depth explanation of the CLI, please see the `Mininet
Walkthrough <http://mininet.org/walkthrough/>`__.

To run NDN commands from the outside the command line user can also open a new terminal
and export the HOME folder of a node ``export HOME=/tmp/minindn/a && cd ~``

Working Directory Structure
---------------------------

Currently Mini-NDN uses /tmp/minindn as the working directory if not
specified otherwise by using the option --work-dir.

Each node is given a HOME directory under /tmp/minindn/<node-name> where
<node-name> is the name of the node specified in the [nodes] section of
the conf file.

NFD
___

- NFD conf file is stored at ``/tmp/minindn/<node-name>/nfd.conf``

- NFD log file is stored at ``/tmp/minindn/<node-name>/log/nfd.log``

- ``.ndn`` folder is stored at ``/tmp/minindn/<node-name>/.ndn``

NLSR
____

- NLSR conf file is stored at ``/tmp/minindn/<node-name>/nlsr.conf``
- NLSR log file is stored at ``/tmp/minindn/<node-name>/log/nlsr.log``

When security is enabled, NLSR security certificates are stored in:
``/tmp/minindn/<node-name>/security`` Note that no NLSR publishes the root
certificate, Mini-NDN installs root.cert in security folder for each
NLSR.