Prepare Mini-NDN release 0.7.0
Change-Id: Ic7c9fe4a6838bda8e5897bf95ca22d5bea1f1589
diff --git a/AUTHORS.rst b/AUTHORS.rst
index 2bd28bb..58b7099 100644
--- a/AUTHORS.rst
+++ b/AUTHORS.rst
@@ -6,6 +6,7 @@
If you would like to become a contributor to the official repository, please follow the recommendations in https://github.com/named-data/.github/blob/master/CONTRIBUTING.md.
* Alexander Afanasyev <https://users.cs.fiu.edu/~afanasyev>
+* Italo Valcy S Brito <https://github.com/italovalcy>
* Muktadir R. Chowdhury <https://github.com/alvyC>
* Damian Coomes <https://github.com/dmcoomes>
* ***(Maintainer)*** Saurab Dulal <https://dulalsaurab.github.io>
@@ -15,12 +16,14 @@
* Giovanni Grieco <https://github.com/GiovanniGrieco>
* ***(Maintainer)*** Alexander Lane <https://github.com/awlane>
* Vince Lehman <http://vslehman.com>
+* Tianxing Ma <https://github.com/matianxing1992>
* Philipp Moll <https://github.com/phylib>
* Eric Newberry <https://ericnewberry.com>
+* Varun Patil <https://github.com/pulsejet>
+* Md Ashiqur Rahman (Mini-NDN Docker support) <marahman@email.arizona.edu>
* Junxiao Shi <https://cs.arizona.edu/~shijunxiao>
* Jeff Thompson <https://remap.ucla.edu/jeff-thompson>
* Yucheng Zhang <https://peterskycloud.wixsite.com/yzportfolio>
-* Italo Valcy S Brito <https://github.com/italovalcy>
Technical Advisors
diff --git a/README.md b/README.md
index 35e8fb8..187f02d 100644
--- a/README.md
+++ b/README.md
@@ -24,8 +24,8 @@
### Documentation
-Please refer to http://minindn.memphis.edu/ or [docs/index.rst](docs/index.rst) for installation, usage, and other documentation.
-The documentation can be built using:
+Please refer to http://minindn.memphis.edu/ for installation, usage, and other documentation.
+The documentation can also be built locally using:
./docs/build.sh
diff --git a/docker/README.md b/docker/README.md
deleted file mode 100644
index 0004ffb..0000000
--- a/docker/README.md
+++ /dev/null
@@ -1,35 +0,0 @@
-
-[comments]: The original author of Mini-NDN docker is Md Ashiqur Rahman (marahman@email.arizona.edu)
-
-## Running Mini-NDN inside Docker
-
-You can use the nightly build from GitHub package registry
-```bash
-docker run -m 4g --cpus=4 -it --privileged \
- -v /lib/modules:/lib/modules \
- ghcr.io/named-data/mini-ndn:master bash
-```
-
-## Building your own image
-
-The Dockerfile can be used directly to `build` an image from scratch.
-
-* Build with `Dockerfile`:
- * Clone the repository and type.
- ```bash
- docker build -t minindn .
- ```
- * You can then access the container through shell with,
- ```bash
- docker run -m 4g --cpus=4 -it --privileged \
- -v /lib/modules:/lib/modules \
- minindn bin/bash
- ```
-
-### Notes:
-
-* Memory (-m), CPU (--cpus) are recommended by Mini-NDN.
-* `--privileged` is mandatory for underlying [Mininet](http://mininet.org/) to utilize virtual switch
-* Root directory on `run` is `/mini-ndn` containing the installation and examples.
-* GUI may not work for now due to docker and xterm setup issues and is independent from Mini-NDN.
-If you intend to run the GUI, pass `-e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix` to the `docker run` command.
\ No newline at end of file
diff --git a/docs/howtos.rst b/docs/howtos.rst
index 102f6ef..4cc50a6 100644
--- a/docs/howtos.rst
+++ b/docs/howtos.rst
@@ -117,12 +117,9 @@
Generate NDN testbed topology
___________________________________________
-Run the following install.sh command
-
-::
-
- python3 util/testbed_topo_generator.py
-
-This will place a "testbed.conf" file in the topologies subdirectory,
-where it can be referenced as desired. To update the topology, simply
-rerun this command.
\ No newline at end of file
+Visit the `NDN Play testbed <https://play.ndn.today/?testbed=1>`_
+page and utilize the `MiniNDN Config` button after setting loss
+and latency parameters. This will export an up to date topology
+modeled on the testbed. We also provide a topology at
+`topologies/testbed.conf`, which is based on a sample from 2020
+which has latencies based on measurements from that configuration.
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index afc5d11..18ae23e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,6 +18,7 @@
faq
hackathon
videos
+ authors
Helpful Links
-------------
diff --git a/docs/install.rst b/docs/install.rst
index d9511de..1ff8399 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -4,15 +4,51 @@
Prerequisites
-------------
-Mini-NDN is tested on the following Linux distributions:
+Mini-NDN is officially supported on the following Linux distributions:
-- Ubuntu 20.04 (recommended)
-- Ubuntu 22.04
+- Ubuntu 20.04
+- Ubuntu 22.04 (recommended)
+- Ubuntu 24.04
- Debian 11 (WiFi scenario does not work)
- Fedora 33 (WiFi scenario does not work)
You must have sudo privileges to install and run Mini-NDN.
+Using Docker
+------------
+
+You can use the nightly build from GitHub package registry
+::
+ docker run -m 4g --cpus=4 -it --privileged \
+ -v /lib/modules:/lib/modules \
+ ghcr.io/named-data/mini-ndn:master bash
+
+NOTE: This nightly build is only currently supported for x86_64. ARM64 support
+(i.e. Apple silicon Macs) will be added in the future.
+
+Building your own Docker image
+------------------------------
+
+The provided Dockerfile can be used to build an image from scratch. To build with the Dockerfile:
+ - Clone the repository and type::
+
+ docker build -t minindn .
+
+ - You can then access the container through shell with::
+
+ docker run -m 4g --cpus=4 -it --privileged \
+ -v /lib/modules:/lib/modules \
+ minindn bin/bash
+
+Additional recommendations
+--------------------------
+- It is recommended to set reasonable constraints on memory (`-m`) and CPU cores (`--cpus`), especially on less
+ powerful or non-dedicated systems.
+- `--privileged` is mandatory for underlying `Mininet <http://mininet.org/>`_ to utilize the virtual switch
+- The root directory on `run` is `/mini-ndn`, which contains the installation and examples.
+- The GUI may not work for now due to docker and xterm setup issues and is independent from Mini-NDN.
+ If you intend to run the GUI, pass `-e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix` to the `docker run` command.
+
Using Vagrantfile
-----------------
@@ -26,8 +62,8 @@
Mini-NDN has the following dependencies:
-- `NDN Forwarding Daemon (NFD) <https://named-data.net/doc/NFD/>`_
-- `Named Data Link State Routing (NLSR) <https://named-data.net/doc/NLSR/>`_
+- `NDN Forwarding Daemon (NFD) <https://docs.named-data.net/NFD/current/>`_
+- `Named Data Link State Routing (NLSR) <https://docs.named-data.net/NLSR/current/>`_
- `NDN Essential Tools (ndn-tools) <https://github.com/named-data/ndn-tools>`_
- `NDN Traffic Generator <https://github.com/named-data/ndn-traffic-generator>`_
- `infoedit <https://github.com/NDN-Routing/infoedit>`_
@@ -48,13 +84,6 @@
This shortens installation time by downloading binary packages, but is only available on Ubuntu.
- ``--source`` prefers installing NDN software from source code.
- ``--use-existing`` will only install dependencies not already in the executable path.
-
-IMPORTANT: For now, Mininet-WiFi only works with ``--source`` installation because the current NFD release (0.7.1) doesn't
-incorporate `issue 5155 <https://redmine.named-data.net/issues/5155>`, a required patch for WiFi module to work properly.
-With the next NFD release, Mininet-WiFi will work with both ``source`` and ``ppa``. Alternatively, you can
-checkout (at your own risk) a third-party source "`Use NFD nightly with Mini-NDN <https://yoursunny.com/t/2021/NFD-nightly-minindn/>`", which provides
-NFD-nightly version and contains all the necessary patches.
-
- ``--dummy-keychain`` patches ndn-cxx to use an in-memory dummy KeyChain, which reduces CPU overhead
and allows you to scale up Mini-NDN experiments. Large Mini-NDN experiments would run significantly
faster after applying this patch. However, your experiments cannot use any NDN security related
@@ -80,7 +109,7 @@
Installing Dependencies
-----------------------
-This section outlines how to install dependnecies manually.
+This section outlines how to install dependencies manually.
If you used ``install.sh``, you do not need to perform these steps.
Mininet
@@ -122,11 +151,12 @@
Each node in Mini-NDN will run the official implementation of NDN
installed on your system. The following dependencies are needed:
-Mini-NDN uses NFD, NLSR, and ndn-tools.
+Mini-NDN uses ndn-cxx, NFD, NLSR, and ndn-tools.
-- To install NFD: https://named-data.net/doc/NFD/current/INSTALL.html
-- To install NLSR: https://named-data.net/doc/NLSR/current/INSTALL.html
-- To install ndn-tools: https://github.com/named-data/ndn-tools
+- To install ndn-cxx: https://docs.named-data.net/ndn-cxx/current/INSTALL.html
+- To install NFD: https://docs.named-data.net/NFD/current/INSTALL.html
+- To install NLSR: https://docs.named-data.net/NLSR/current/INSTALL.html
+- To install ndn-tools: https://github.com/named-data/ndn-tools/blob/master/INSTALL.md
.. warning::
Please do not try to install NDN software from both the source (GitHub) and PPA (apt).
@@ -134,8 +164,9 @@
to use apt, please run ``sudo ./waf uninstall`` in all the NDN projects before proceeding
with apt. Similarly, remove from apt if switching to source.
-Please see the :ref:`scaling-note <scaling-note>` to learn about disabling
-security for better scalability.
+In cases where using NDN security is not important to the results, it is recommended
+to use the dummy keychain patch for ndn-cxx to disable it for improved scalability.
+This patch is located at `util/patches/ndn-cxx-dummy-keychain.patch.`
Note that all three of these can be installed from the Named Data PPA.
Instructions for setting it up can be found in the NFD installation
diff --git a/docs/release-notes.rst b/docs/release-notes.rst
index 90b3733..b012c2b 100644
--- a/docs/release-notes.rst
+++ b/docs/release-notes.rst
@@ -1,6 +1,56 @@
Release Notes
=============
+Mini-NDN version 0.7.0 (Major changes since version 0.6.0)
+----------------------------------------------------------
+
+**Breaking Changes**:
+
+- Install behavior regarding existing installation of dependencies has been reversed; by default, these are now ignored. This is meant
+ to clear up confusion regarding installing on existing installs which have been used for NDN development previously. The previous
+ behavior can be enabled using `--use-existing`.
+
+**New features**:
+
+- Added `NFDCBatch` to NFDC helper, which allows the user to use the existing NFDC wrapper API to instead create and execute a batch file.
+ When running large numbers of commands, this significantly speeds up performance due to not needing to add delay between individual CLI
+ calls.
+- Added `MinindnAdhoc` class which can be used to construct adhoc Mini-NDN-Wifi networks from topology files.
+- Model mobility parameters can now also be passed to Mini-NDN-Wifi via topology files.
+- Working directory can be passed as constructor argument to `Minindn` objects
+- We have added a new `--release` flag to the installer which simplifies installing matching releases of dependencies. Reference
+ `the install documentation <./install.rst>`__ for more information.
+- Experimental wifi support for NLSR helper. See `experiment docs <experiment>` for details (`issue: 5232 <https://redmine.named-data.net/issues/5232>`__)
+- Added a Dockerfile for Mini-NDN. A prebuilt image for *linux/amd64* platforms is available on the
+ `GitHub container registry <https://github.com/named-data/mini-ndn/pkgs/container/mini-ndn>`__
+- The previous testbed topology generation script has been deprecated and removed. Please reference the `NDN Play website <https://play.ndn.today/?testbed=1>`__
+ for a replacement
+
+**Improvements**:
+
+- Ethernet unicast faces are now supported natively by NLSR wrapper, NFDC wrapper, and NDN routing helper. No additional formatting by the user is needed
+ for ethernet addresses extracted from the Mininet API when passed to these functions (`issue: 5321 <https://redmine.named-data.net/issues/5232>`__)
+- `NdnRoutingHelper` has been parallelized along with minor optimizations. You can now also use it to create
+ permanent faces (`issue: 5264 <https://redmine.named-data.net/issues/5264>`__)
+- `checkConvergence` method of `Experiment` helper can now output more detailed information when flag `returnConvergenceInfo` is set
+ (`issue: 5236 <https://redmine.named-data.net/issues/5236>`__)
+- `getPopen` can now accept commands formatted as lists as well as strings
+- We now natively edit nfd.conf files using infoconv to read and write it as json rather than calling infoedit at the shell
+ (`issue: 5318 <https://redmine.named-data.net/issues/5318>`__)
+- Added Sprint PoP topology
+- Link bandwidth value (`bw`) can now be specified as decimal megabits rather than only integers in topology files
+- NFDC was significantly refactored for the `NFDCBatch` change.
+
+**Bug fixes**:
+
+- NFDC helper properly supports existing faces and no longer outputs unnecessary error messages if face exists by default.
+- Fixed out of date ndnsec commands
+- Socket path now defaults to NFD default as of release 24.07. You can specify a different path with the `defaultSocketLocation`
+ argument in the `Nfd` object constructor (`issue: 5309 <https://redmine.named-data.net/issues/5309>`__)
+- Fixed jitter being parsed into incorrect type from topology files
+- Moved vestigial CLI arguments relating to `wifi_ping.py` example out of the Mini-NDN-Wifi class
+
+
Mini-NDN version 0.6.0 (Major changes since version 0.5.0)
----------------------------------------------------------
diff --git a/docs/videos.rst b/docs/videos.rst
index b6b3a51..db97952 100644
--- a/docs/videos.rst
+++ b/docs/videos.rst
@@ -1,7 +1,7 @@
Video Tutorials
===============
-Maybe outdated since version 0.5.0.
+May be outdated since version 0.5.0.
.. raw:: html
diff --git a/minindn/__init__.py b/minindn/__init__.py
index 2b8877c..a71c5c7 100644
--- a/minindn/__init__.py
+++ b/minindn/__init__.py
@@ -1 +1 @@
-__version__ = '0.5.0'
+__version__ = '0.7.0'
diff --git a/util/testbed_topo_generator.py b/util/testbed_topo_generator.py
deleted file mode 100755
index 4730587..0000000
--- a/util/testbed_topo_generator.py
+++ /dev/null
@@ -1,98 +0,0 @@
-#!/usr/bin/env python3
-# -*- Mode:bash; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
-#
-# Copyright (C) 2015-2020, The University of Memphis,
-# Arizona Board of Regents,
-# Regents of the University of California.
-#
-# This file is part of Mini-NDN.
-# See AUTHORS.md for a complete list of Mini-NDN authors and contributors.
-#
-# Mini-NDN is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Mini-NDN is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Mini-NDN, e.g., in COPYING.md file.
-# If not, see <http://www.gnu.org/licenses/>.
-
-# This script generates a testbed topology based on current data. Note
-# that this topology is memory intensive and can have issues on lower specced
-# systems due to its size.
-# To use, run with python3
-
-import argparse
-import datetime
-import json
-import logging
-from os import path
-from urllib.request import urlopen
-
-def testbedGen():
- """Returns a string with the Mini-NDN topology version of the testbed"""
- topology = None
- connections = None
- hosts = []
- links = []
- try:
- with urlopen("https://ndndemo.arl.wustl.edu/testbedNodes.json") as url:
- topology = json.loads(url.read().decode())
- with urlopen("https://ndndemo.arl.wustl.edu/links.json") as url:
- connections = json.loads(url.read().decode())
- except:
- logging.error("Failed to retrieve testbed info from WUSTL servers")
- if __name__ == '__main__':
- from sys import exit
- exit(1)
- raise
-
- logging.info("Generating testbed topology...")
- for node_name in topology:
- node = topology[node_name]
- if node['neighbors']:
- radius = node['hr_radius']
- angle = node['hr_angle']
- host_str = "{}: _ radius={} angle={}\n".format(node_name, radius, angle)
- hosts.append(host_str)
- logging.debug("Add node: {}".format(host_str)[:-1])
- else:
- # A node without neighbors shouldn't be considered part of the testbed
- # for testing purposes
- logging.debug("Node {} has no neighbors, passing...".format(node_name))
- for link in connections:
- node1 = link['start']
- node2 = link['end']
- # This value is equivalent to RTT in the testbed
- delay = link['nlsr_weight']
- link_str = "{}:{} delay={}ms\n".format(node1, node2, delay)
- logging.debug("Add link: {}".format(link_str)[:-1])
- links.append(link_str.strip())
-
- topo_str = "[nodes]\n"
- for host in hosts:
- topo_str = topo_str + host
- topo_str = topo_str + "[links]\n"
- for link in links:
- topo_str = topo_str + link
- return topo_str.strip()
-
-if __name__ == '__main__':
- default_path = path.dirname(__file__) + '/../topologies/testbed{}.conf'.format(str(datetime.date.today()))
- parser = argparse.ArgumentParser()
- parser.add_argument("-l", "--log_level", help="Log level to output", default="info", choices=["debug", "info", "warning", "error"])
- parser.add_argument("-o", "--output_dir", help="File output location", default=default_path)
- args = parser.parse_args()
- log_level = getattr(logging, args.log_level.upper())
- topologies_path = path.abspath(args.output_dir)
- logging.basicConfig(format="%(levelname)s: %(message)s", level=log_level)
- topo = testbedGen()
- logging.info("Testbed generated, writing to file...")
- with open(topologies_path, "w") as file:
- file.writelines(topo)
- logging.info("Finished")
\ No newline at end of file