From 73add71f860979426aef63136bf78ed525862e5c Mon Sep 17 00:00:00 2001 From: awlane Date: Mon, 12 Aug 2024 21:49:00 -0500 Subject: [PATCH] Prepare Mini-NDN release 0.7.0 Change-Id: Ic7c9fe4a6838bda8e5897bf95ca22d5bea1f1589 --- AUTHORS.rst | 5 +- README.md | 4 +- docker/README.md | 35 ------------ docs/howtos.rst | 15 +++--- docs/index.rst | 1 + docs/install.rst | 69 +++++++++++++++++------- docs/release-notes.rst | 50 +++++++++++++++++ docs/videos.rst | 2 +- minindn/__init__.py | 2 +- util/testbed_topo_generator.py | 98 ---------------------------------- 10 files changed, 115 insertions(+), 166 deletions(-) delete mode 100644 docker/README.md delete mode 100755 util/testbed_topo_generator.py diff --git a/AUTHORS.rst b/AUTHORS.rst index 2bd28bb..58b7099 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -6,6 +6,7 @@ The specific contributions of individual authors can be obtained from the git hi 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 +* Italo Valcy S Brito * Muktadir R. Chowdhury * Damian Coomes * ***(Maintainer)*** Saurab Dulal @@ -15,12 +16,14 @@ If you would like to become a contributor to the official repository, please fol * Giovanni Grieco * ***(Maintainer)*** Alexander Lane * Vince Lehman +* Tianxing Ma * Philipp Moll * Eric Newberry +* Varun Patil +* Md Ashiqur Rahman (Mini-NDN Docker support) * Junxiao Shi * Jeff Thompson * Yucheng Zhang -* Italo Valcy S Brito Technical Advisors diff --git a/README.md b/README.md index 35e8fb8..187f02d 100644 --- a/README.md +++ b/README.md @@ -24,8 +24,8 @@ Bug reports and feedback are highly appreciated and can be made through our ### 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 @@ reached via external machines. 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 `_ +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 @@ Mini-NDN: A Mininet-based NDN emulator 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 @@ Install 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 `_ 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 @@ Using install.sh Mini-NDN has the following dependencies: -- `NDN Forwarding Daemon (NFD) `_ -- `Named Data Link State Routing (NLSR) `_ +- `NDN Forwarding Daemon (NFD) `_ +- `Named Data Link State Routing (NLSR) `_ - `NDN Essential Tools (ndn-tools) `_ - `NDN Traffic Generator `_ - `infoedit `_ @@ -48,13 +84,6 @@ Some notable flags are: 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 `, 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 `", 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 @@ reinstall the software (``./waf && sudo ./waf install``). 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 @@ Mini-NDN uses NFD, NLSR, and ndn-tools. 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 ` 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 ` for details (`issue: 5232 `__) +- Added a Dockerfile for Mini-NDN. A prebuilt image for *linux/amd64* platforms is available on the + `GitHub container registry `__ +- The previous testbed topology generation script has been deprecated and removed. Please reference the `NDN Play website `__ + 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 `__) +- `NdnRoutingHelper` has been parallelized along with minor optimizations. You can now also use it to create + permanent faces (`issue: 5264 `__) +- `checkConvergence` method of `Experiment` helper can now output more detailed information when flag `returnConvergenceInfo` is set + (`issue: 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 `__) +- 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 `__) +- 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 . - -# 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