blob: 169769912f7a2b295df0a7b0a910815ab3cbf56a [file] [log] [blame]
Ashlesh Gawande6c86e302019-09-17 22:27:05 -05001Install
2=======
3
4Prerequisites
5-------------
6
Junxiao Shi48ada892021-11-04 09:02:21 -06007Mini-NDN is tested on the following Linux distributions:
8
9- Ubuntu 20.04 (recommended)
10- Debian 11 (WiFi scenario does not work)
11- Fedora 33 (WiFi scenario does not work)
12
13You must have sudo privileges to install and run Mini-NDN.
Ashlesh Gawande6c86e302019-09-17 22:27:05 -050014
15Using Vagrantfile
16-----------------
17
18With Vagrant installed, simply do ``vagrant up`` which will bring up an Ubuntu 18.04 virtual machine
19and install Mini-NDN and all its dependencies on it. Please make sure to tweak the CPU core count
20(default 4 cores) and RAM (default 4GB) according to your needs before doing vagrant up. Mini-NDN
21can be found in /home/vagrant/mini-ndn which is a symlink to /vagrant if Vagrantfile was used from within mini-ndn cloned on the host. Otherwise it is an actual clone of mini-ndn.
22
23Using install.sh
24----------------
25
Junxiao Shi48ada892021-11-04 09:02:21 -060026Mini-NDN has the following dependencies:
27
28- `NDN Forwarding Daemon (NFD) <https://named-data.net/doc/NFD/>`_
29- `Named Data Link State Routing (NLSR) <https://named-data.net/doc/NLSR/>`_
30- `NDN Essential Tools (ndn-tools) <https://github.com/named-data/ndn-tools>`_
31- `NDN Traffic Generator <https://github.com/named-data/ndn-traffic-generator>`_
32- `infoedit <https://github.com/NDN-Routing/infoedit>`_
33- `Mininet <http://mininet.org/>`_
34- `Mininet-WiFi <https://mininet-wifi.github.io/>`_ (optional)
35
36To install Mini-NDN and its dependencies, clone this repository and run:
Ashlesh Gawande6c86e302019-09-17 22:27:05 -050037
38::
39
Junxiao Shi48ada892021-11-04 09:02:21 -060040 ./install.sh
Ashlesh Gawande6c86e302019-09-17 22:27:05 -050041
Junxiao Shi48ada892021-11-04 09:02:21 -060042The script accepts various command line flags.
43Some notable flags are:
Ashlesh Gawande6c86e302019-09-17 22:27:05 -050044
Junxiao Shi48ada892021-11-04 09:02:21 -060045- ``-y`` skips interactive confirmation before installation.
46- ``--ppa`` prefers installing NDN software from `named-data PPA <https://launchpad.net/~named-data/+archive/ubuntu/ppa>`_.
47 This shortens installation time by downloading binary packages, but is only available on Ubuntu.
48- ``--source`` prefers installing NDN software from source code.
dulalsaurab8c8e6332021-05-21 20:37:03 +000049
50IMPORTANT: For now, Mininet-WiFi only works with ``--source`` installation because the current NFD release (0.7.1) doesn't
51incorporate `issue 5155 <https://redmine.named-data.net/issues/5155>`, a required patch for WiFi module to work properly.
52With the next NFD release, Mininet-WiFi will work with both ``source`` and ``ppa``. Alternatively, you can
53checkout (at your own risk) a third-party source "`Use NFD nightly with Mini-NDN <https://yoursunny.com/t/2021/NFD-nightly-minindn/>`", which provides
54NFD-nightly version and contains all the necessary patches.
55
Junxiao Shi48ada892021-11-04 09:02:21 -060056- ``--dummy-keychain`` patches ndn-cxx to use an in-memory dummy KeyChain, which reduces CPU overhead
57 and allows you to scale up Mini-NDN experiments. Large Mini-NDN experiments would run significantly
58 faster after applying this patch. However, your experiments cannot use any NDN security related
59 features (signatures, verifier, access control, etc).
60- ``--no-wifi`` skips Mininet-WiFi dependency.
61 Currently Mininet-WiFi only works on Ubuntu, so that you must specify this option when installing on other distros.
Ashlesh Gawande6c86e302019-09-17 22:27:05 -050062
Junxiao Shi48ada892021-11-04 09:02:21 -060063You can see all command line flags by running:
Ashlesh Gawande6c86e302019-09-17 22:27:05 -050064
65::
66
Junxiao Shi48ada892021-11-04 09:02:21 -060067 ./install.sh -h
Ashlesh Gawande6c86e302019-09-17 22:27:05 -050068
Junxiao Shi48ada892021-11-04 09:02:21 -060069The script uses ``setup.py develop`` to point the system install of Python packages to the codebase
70directory. Therefore, you can modify ``mininet``, ``mininet-wifi``, and ``mini-ndn``, and the
71changes will be reflected immediately.
Ashlesh Gawande6c86e302019-09-17 22:27:05 -050072
Junxiao Shi48ada892021-11-04 09:02:21 -060073If NDN software is installed from source code (not PPA), the code is downloaded to ``dl`` directory
74under your ``mini-ndn`` clone. If you modify the source code, you need to manually recompile and
75reinstall the software (``./waf && sudo ./waf install``).
Ashlesh Gawande6c86e302019-09-17 22:27:05 -050076
dulalsaurab8c8e6332021-05-21 20:37:03 +000077
Ashlesh Gawande6c86e302019-09-17 22:27:05 -050078Installing Dependencies
79-----------------------
80
Junxiao Shi48ada892021-11-04 09:02:21 -060081This section outlines how to install dependnecies manually.
82If you used ``install.sh``, you do not need to perform these steps.
83
Ashlesh Gawande6c86e302019-09-17 22:27:05 -050084Mininet
85_______
86
87Mini-NDN is based on Mininet. To install Mininet:
88
89::
90
91 git clone --depth 1 https://github.com/mininet/mininet.git
92
93After Mininet source is on your system, run the following command to
94install Mininet core dependencies and Open vSwitch:
95
96::
97
98 ./util/install.sh -nv
99
100To check if Mininet is working correctly, run this test:
101
102::
103
104 sudo mn --test pingall
105
106This will print out a series of statements that show the test setup and
107the results of the test. Look for ``Results:`` two-thirds of the way
108down where it will indicate the percentage of dropped packets. Your
109results should show "0% dropped (2/2 received)".
110
111NOTE: Mini-NDN, while providing a high level of emulation of hosts,
112requires programs to be installed onto your computer. It will not work
113if they are not installed. If you do not want NDN software installed
114onto your computer, you can use a virtual machine, which can be quite
115simply set up with the provided Vagrantfile.
116
117NDN dependencies
118________________
119
120Each node in Mini-NDN will run the official implementation of NDN
121installed on your system. The following dependencies are needed:
122
123Mini-NDN uses NFD, NLSR, and ndn-tools.
124
125- To install NFD: https://named-data.net/doc/NFD/current/INSTALL.html
126- To install NLSR: https://named-data.net/doc/NLSR/current/INSTALL.html
127- To install ndn-tools: https://github.com/named-data/ndn-tools
128
129.. warning::
130 Please do not try to install NDN software from both the source (GitHub) and PPA (apt).
131 It will not work in most cases! If you used ./install.sh -a in the past but now want
132 to use apt, please run ``sudo ./waf uninstall`` in all the NDN projects before proceeding
133 with apt. Similarly, remove from apt if switching to source.
134
135Please see the :ref:`scaling-note <scaling-note>` to learn about disabling
136security for better scalability.
137
138Note that all three of these can be installed from the Named Data PPA.
139Instructions for setting it up can be found in the NFD installation
140instructions. Note that PPA and installs from source **cannot** be
141mixed. You must completely remove PPA installs from the system if switching
142to source and vice-versa.
143
144For PPA installs, if you are using a custom nfd.conf file in an experiment, you should
145place it in /usr/local/etc/ndn/ rather than /etc/ndn/. This is to avoid
146a bug from the default configuration file for the PPA, which is
147incompatible with Mini-NDN.
148
149Infoedit
150________
151
152Infoedit is used to edit configuration files for NFD and NLSR.
153To install infoedit:
154
155::
156
157 git clone --depth 1 https://github.com/NDN-Routing/infoedit
158 cd infoedit
159 make
160 sudo make install
161
162Verification
163------------
164
165You can execute the following example to bring up the Mini-NDN command line
166with NFD and NLSR running on each node:
167
168::
169
170 sudo python examples/mnndn.py
171
172You can use these steps to run the sample pingall experiment:
173
1741. Issue the command: ``sudo python examples/nlsr/pingall.py``
1752. When the ``mini-ndn>`` CLI prompt appears, the experiment has
176 finished. On the Mini-NDN CLI, issue the command ``exit`` to exit the
177 experiment.
1783. Issue the command:
179 ``grep -c content /tmp/minindn/*/ping-data/*.txt``. Each file should
180 report a count of 50.
1814. Issue the command:
182 ``grep -c timeout /tmp/minindn/*/ping-data/*.txt``. Each file should
183 report a count of 0.