blob: 84b6784aafb51e62f1b944eba20143299bcac326 [file] [log] [blame]
Davide Pesavento17521592020-05-14 19:01:32 -04001Getting started with NFD
Steve DiBenedetto62a93942014-08-24 17:13:52 -06002========================
Alexander Afanasyev284257b2014-04-11 14:16:51 -07003
Davide Pesavento69857c32020-04-05 16:36:26 -04004Supported platforms
5-------------------
Steve DiBenedetto62a93942014-08-24 17:13:52 -06006
Davide Pesavento69857c32020-04-05 16:36:26 -04007NFD is built against a continuous integration system and has been tested on the
8following platforms:
9
Davide Pesaventoc5e3e7a2023-03-07 21:25:27 -050010- Ubuntu 22.04 (jammy)
Davide Pesavento4b7cffb2024-06-07 17:35:53 -040011- Ubuntu 24.04 (noble)
Davide Pesaventoc5e3e7a2023-03-07 21:25:27 -050012- Debian 11 (bullseye)
Davide Pesavento05bd6c22023-10-31 21:45:25 -040013- Debian 12 (bookworm)
Davide Pesaventoe541d1b2022-08-17 15:10:32 -040014- CentOS Stream 9
Davide Pesavento2073dce2024-12-10 21:24:41 -050015- macOS 13 / 14 / 15
Davide Pesavento69857c32020-04-05 16:36:26 -040016
Davide Pesaventoc5e3e7a2023-03-07 21:25:27 -050017NFD should also work on the following platforms, although they are not officially
Davide Pesavento69857c32020-04-05 16:36:26 -040018supported:
19
Davide Pesaventoc5e3e7a2023-03-07 21:25:27 -050020- Any other recent version of Ubuntu not listed above
Davide Pesavento2073dce2024-12-10 21:24:41 -050021- Fedora >= 34
22- Alpine >= 3.14
Davide Pesavento05bd6c22023-10-31 21:45:25 -040023- Any version of Raspberry Pi OS based on Debian 11 (bullseye) or later
Davide Pesavento2073dce2024-12-10 21:24:41 -050024- macOS >= 11
Davide Pesavento6d6f2072022-09-12 23:08:34 -040025- FreeBSD >= 12.2
Davide Pesavento69857c32020-04-05 16:36:26 -040026
27.. _Install NFD on Ubuntu Linux using the NDN PPA repository:
28
29Install NFD on Ubuntu Linux using the NDN PPA repository
Steve DiBenedetto62a93942014-08-24 17:13:52 -060030--------------------------------------------------------
31
Davide Pesavento69857c32020-04-05 16:36:26 -040032NFD binaries and related tools for supported versions of Ubuntu can be installed using
33PPA packages from the **named-data** repository. First, you will need to add the
34``named-data/ppa`` repository to the binary package sources and update the list of
35available packages.
Steve DiBenedetto62a93942014-08-24 17:13:52 -060036
Alexander Afanasyev84dd4ca2017-10-15 14:56:08 -040037Preliminary steps if you have not used PPA packages before
38~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Steve DiBenedetto62a93942014-08-24 17:13:52 -060039
Davide Pesavento69857c32020-04-05 16:36:26 -040040To simplify adding new PPA repositories, Ubuntu provides the ``add-apt-repository`` tool,
Davide Pesaventocc7bee72016-04-22 02:21:13 +020041which is not installed by default on some systems.
Steve DiBenedetto62a93942014-08-24 17:13:52 -060042
43::
44
Davide Pesavento69857c32020-04-05 16:36:26 -040045 sudo apt install software-properties-common
Steve DiBenedetto62a93942014-08-24 17:13:52 -060046
Davide Pesavento69857c32020-04-05 16:36:26 -040047Adding the NDN PPA
48~~~~~~~~~~~~~~~~~~
Steve DiBenedetto62a93942014-08-24 17:13:52 -060049
Davide Pesavento69857c32020-04-05 16:36:26 -040050After installing ``add-apt-repository``, run the following commands to add the `NDN PPA
51repository`_::
Steve DiBenedetto62a93942014-08-24 17:13:52 -060052
53 sudo add-apt-repository ppa:named-data/ppa
Davide Pesavento69857c32020-04-05 16:36:26 -040054 sudo apt update
Steve DiBenedetto62a93942014-08-24 17:13:52 -060055
56Installing NFD and other NDN packages
57~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58
Davide Pesavento69857c32020-04-05 16:36:26 -040059After you have added the `NDN PPA repository`_, NFD and other NDN packages can be easily
60installed either using ``apt``, as shown below, or any other compatible package manager.
Steve DiBenedetto62a93942014-08-24 17:13:52 -060061
62::
63
Davide Pesavento69857c32020-04-05 16:36:26 -040064 sudo apt install nfd
Steve DiBenedetto62a93942014-08-24 17:13:52 -060065
Davide Pesavento69857c32020-04-05 16:36:26 -040066For the list of available packages, refer to the `NDN PPA repository`_ page.
Steve DiBenedetto62a93942014-08-24 17:13:52 -060067
68.. _NDN PPA repository: https://launchpad.net/~named-data/+archive/ppa
69
Davide Pesavento69857c32020-04-05 16:36:26 -040070Building from source
Steve DiBenedetto62a93942014-08-24 17:13:52 -060071--------------------
72
Davide Pesavento69857c32020-04-05 16:36:26 -040073Downloading from git
Steve DiBenedetto62a93942014-08-24 17:13:52 -060074~~~~~~~~~~~~~~~~~~~~
75
Davide Pesavento69857c32020-04-05 16:36:26 -040076The first step is to obtain the source code for NFD and its main dependency, the
77*ndn-cxx* library. If you do not want a development version of NFD, make sure you
Davide Pesavento3bc8e192022-12-31 01:40:11 -050078checkout the correct release tag (e.g., ``*-0.8.1``) from both repositories.
Steve DiBenedetto62a93942014-08-24 17:13:52 -060079
Davide Pesavento9f6a7d92020-10-06 15:21:48 -040080.. code-block:: sh
Steve DiBenedetto62a93942014-08-24 17:13:52 -060081
82 # Download ndn-cxx
Davide Pesavento69857c32020-04-05 16:36:26 -040083 git clone https://github.com/named-data/ndn-cxx.git
Steve DiBenedetto62a93942014-08-24 17:13:52 -060084
85 # Download NFD
Davide Pesavento69857c32020-04-05 16:36:26 -040086 git clone --recursive https://github.com/named-data/NFD.git
Alexander Afanasyev284257b2014-04-11 14:16:51 -070087
Alexander Afanasyev84dd4ca2017-10-15 14:56:08 -040088.. note::
Davide Pesavento69857c32020-04-05 16:36:26 -040089 While we strive to ensure that the latest version (git master branch) of NFD and ndn-cxx
90 always compiles and works properly, we cannot guarantee that there will be no issues.
91 If this is discovered to be the case, please use matching released versions (git tag or
92 tarball) of NFD and ndn-cxx instead.
Alexander Afanasyev84dd4ca2017-10-15 14:56:08 -040093
Alexander Afanasyev284257b2014-04-11 14:16:51 -070094Prerequisites
Steve DiBenedetto62a93942014-08-24 17:13:52 -060095~~~~~~~~~~~~~
Alexander Afanasyev284257b2014-04-11 14:16:51 -070096
Davide Pesaventobf4c1312023-02-23 20:32:01 -050097Install the `ndn-cxx library <https://docs.named-data.net/ndn-cxx/current/INSTALL.html>`__
Davide Pesavento69857c32020-04-05 16:36:26 -040098and its prerequisites.
Alexander Afanasyev284257b2014-04-11 14:16:51 -070099
Davide Pesavento914eb282024-12-10 15:33:26 -0500100On Linux, NFD needs the following *optional* dependencies to enable additional features:
Junxiao Shie5e1e252014-12-13 22:07:35 -0700101
Davide Pesaventoe541d1b2022-08-17 15:10:32 -0400102- On **Debian** and **Ubuntu**:
Davide Pesavento9f6a7d92020-10-06 15:21:48 -0400103
104 .. code-block:: sh
Junxiao Shie5e1e252014-12-13 22:07:35 -0700105
Davide Pesavento17521592020-05-14 19:01:32 -0400106 sudo apt install libpcap-dev libsystemd-dev
107
Davide Pesavento9f6a7d92020-10-06 15:21:48 -0400108- On **CentOS** and **Fedora**:
109
110 .. code-block:: sh
Davide Pesavento17521592020-05-14 19:01:32 -0400111
Davide Pesavento17521592020-05-14 19:01:32 -0400112 sudo dnf install libpcap-devel systemd-devel
Alexander Afanasyev284257b2014-04-11 14:16:51 -0700113
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600114Build
115~~~~~
116
Davide Pesavento9f6a7d92020-10-06 15:21:48 -0400117The following commands can be used to build and install NFD from source:
118
119.. code-block:: sh
Alexander Afanasyev284257b2014-04-11 14:16:51 -0700120
Davide Pesavento2150da82022-07-08 18:18:51 -0400121 ./waf configure
Alexander Afanasyev284257b2014-04-11 14:16:51 -0700122 ./waf
123 sudo ./waf install
124
Davide Pesavento69857c32020-04-05 16:36:26 -0400125If you have installed ndn-cxx and/or any other dependencies into a non-standard path,
126you may need to modify the ``PKG_CONFIG_PATH`` environment variable before running
Davide Pesavento9f6a7d92020-10-06 15:21:48 -0400127``./waf configure``. For example:
128
129.. code-block:: sh
Alexander Afanasyev284257b2014-04-11 14:16:51 -0700130
Davide Pesavento69857c32020-04-05 16:36:26 -0400131 export PKG_CONFIG_PATH="/custom/lib/pkgconfig:$PKG_CONFIG_PATH"
Alexander Afanasyev284257b2014-04-11 14:16:51 -0700132 ./waf configure
133 ./waf
134 sudo ./waf install
135
Davide Pesavento69857c32020-04-05 16:36:26 -0400136Refer to ``./waf --help`` for more options that can be used during the ``configure`` stage.
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600137
Alexander Afanasyev508411e2014-12-16 13:27:59 -0800138.. note::
Davide Pesavento69857c32020-04-05 16:36:26 -0400139 If you are working on a source repository that has been compiled before, and you have
140 upgraded one of the dependencies, please execute ``./waf distclean`` to clear object files
141 and start over.
Alexander Afanasyev508411e2014-12-16 13:27:59 -0800142
Alexander Afanasyev26181532014-05-07 23:38:51 -0700143Debug symbols
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600144~~~~~~~~~~~~~
Alexander Afanasyev26181532014-05-07 23:38:51 -0700145
Davide Pesavento17521592020-05-14 19:01:32 -0400146The default compiler flags include debug symbols in binaries. This should provide
147more meaningful debugging information if NFD or other tools happen to crash.
Alexander Afanasyev26181532014-05-07 23:38:51 -0700148
Davide Pesavento17521592020-05-14 19:01:32 -0400149If this is not desired, the default flags can be overridden to disable debug symbols.
150The following example shows how to completely disable debug symbols and configure
151NFD to be installed into ``/usr`` with configuration in the ``/etc`` directory.
Alexander Afanasyev26181532014-05-07 23:38:51 -0700152
Davide Pesavento9f6a7d92020-10-06 15:21:48 -0400153.. code-block:: sh
Alexander Afanasyev26181532014-05-07 23:38:51 -0700154
155 CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
156 ./waf
157 sudo ./waf install
158
Davide Pesavento69857c32020-04-05 16:36:26 -0400159For Ubuntu PPA packages, debug symbols are available in ``*-dbg`` packages.
Alexander Afanasyev84dd4ca2017-10-15 14:56:08 -0400160
Davide Pesavento69857c32020-04-05 16:36:26 -0400161Customizing the compiler
162~~~~~~~~~~~~~~~~~~~~~~~~
Alexander Afanasyev7c10b3b2015-01-20 12:24:27 -0800163
Davide Pesavento69857c32020-04-05 16:36:26 -0400164To build NFD with a different compiler (rather than the platform default), set the
165``CXX`` environment variable to point to the compiler binary. For example, to build
Davide Pesavento9f6a7d92020-10-06 15:21:48 -0400166with clang on Linux, use the following:
167
168.. code-block:: sh
Alexander Afanasyev7c10b3b2015-01-20 12:24:27 -0800169
Eric Newberry81a9a862016-12-27 22:59:27 -0700170 CXX=clang++ ./waf configure
Alexander Afanasyev7c10b3b2015-01-20 12:24:27 -0800171
Davide Pesavento69857c32020-04-05 16:36:26 -0400172Building the documentation
173~~~~~~~~~~~~~~~~~~~~~~~~~~
Alexander Afanasyev284257b2014-04-11 14:16:51 -0700174
Davide Pesavento9f6a7d92020-10-06 15:21:48 -0400175Tutorials and API documentation can be built using the following commands:
176
177.. code-block:: sh
Alexander Afanasyev284257b2014-04-11 14:16:51 -0700178
179 # Full set of documentation (tutorials + API) in build/docs
180 ./waf docs
181
Davide Pesavento69857c32020-04-05 16:36:26 -0400182 # Only tutorials in build/docs
Alexander Afanasyev284257b2014-04-11 14:16:51 -0700183 ./waf sphinx
184
Davide Pesavento69857c32020-04-05 16:36:26 -0400185 # Only API docs in build/docs/doxygen
186 ./waf doxygen
Alexander Afanasyev284257b2014-04-11 14:16:51 -0700187
Davide Pesavento17521592020-05-14 19:01:32 -0400188If ``sphinx-build`` is detected during ``./waf configure``, manpages will automatically
189be built and installed during the normal build process (i.e., during ``./waf`` and
190``./waf install``). By default, manpages will be installed into ``${PREFIX}/share/man``
191(the default value for ``PREFIX`` is ``/usr/local``). This location can be changed
192during the ``./waf configure`` stage using the ``--prefix``, ``--datarootdir``, or
193``--mandir`` options.
Alexander Afanasyev284257b2014-04-11 14:16:51 -0700194
Davide Pesavento17521592020-05-14 19:01:32 -0400195For further details, please refer to ``./waf --help``.
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600196
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600197Initial configuration
198---------------------
199
200.. note::
201 If you have installed NFD from binary packages, the package manager has already
Davide Pesavento69857c32020-04-05 16:36:26 -0400202 installed a working configuration and you can safely skip this section.
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600203
204General
205~~~~~~~
206
Davide Pesavento69857c32020-04-05 16:36:26 -0400207After installing NFD from source, you need to create a proper configuration file.
208If the default installation directories were used with ``./waf configure``, this
209can be accomplished by simply copying the sample configuration file as follows::
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600210
211 sudo cp /usr/local/etc/ndn/nfd.conf.sample /usr/local/etc/ndn/nfd.conf
212
213NFD Security
214~~~~~~~~~~~~
215
216NFD provides mechanisms to enable strict authorization for all management commands. In
Davide Pesavento69857c32020-04-05 16:36:26 -0400217particular, one can authorize only specific public keys to create new faces or change the
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600218forwarding strategy for specific namespaces. For more information about how to generate
Davide Pesavento69857c32020-04-05 16:36:26 -0400219public/private key pairs, generate self-signed certificates, and use them to authorize
220NFD management commands, refer to the :ref:`How do I configure NFD security` FAQ question.
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600221
Davide Pesavento69857c32020-04-05 16:36:26 -0400222In the sample configuration file, all security mechanisms are disabled for local clients,
223effectively allowing anybody on the local machine to issue NFD management commands.
224
225.. note::
226 The sample configuration file is intended only for demo purposes and should NOT be
227 used in production environments.
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600228
229Running
230-------
231
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600232Starting
233~~~~~~~~
234
Davide Pesavento69857c32020-04-05 16:36:26 -0400235If you have installed NFD from source, it is recommended to start NFD with the
236``nfd-start`` script::
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600237
238 nfd-start
239
Davide Pesavento69857c32020-04-05 16:36:26 -0400240On macOS, this command may ask for your keychain password or ask "nfd wants to sign using
241key [xyz] in your keychain". Enter your keychain password and click "Always Allow".
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600242
243Later, you can stop NFD with ``nfd-stop`` or by simply killing the ``nfd`` process.
244
Davide Pesavento2849fd42019-01-03 18:30:05 -0500245If you have installed NFD using a package manager, you can start and stop NFD using the
Davide Pesavento69857c32020-04-05 16:36:26 -0400246operating system's service manager, such as ``systemctl`` or ``launchctl``.
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600247
Davide Pesavento69857c32020-04-05 16:36:26 -0400248Connecting to remote forwarders
249~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600250
Davide Pesavento69857c32020-04-05 16:36:26 -0400251To create a UDP tunnel to a remote instance of NFD, execute the following command
252in a terminal::
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600253
Davide Pesavento69857c32020-04-05 16:36:26 -0400254 nfdc face create udp://<other-host>
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600255
Davide Pesavento69857c32020-04-05 16:36:26 -0400256where ``<other-host>`` is the name or IP address of the other host (e.g.,
257``udp://ndn.example.net``). If successful, this will print something like::
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600258
Junxiao Shi849e12a2017-08-02 00:14:57 +0000259 face-created id=308 local=udp4://10.0.2.15:6363 remote=udp4://131.179.196.46:6363 persistency=persistent
260
Davide Pesavento69857c32020-04-05 16:36:26 -0400261To add a route ``/ndn`` toward this remote forwarder, execute the following command
262in a terminal::
Junxiao Shi849e12a2017-08-02 00:14:57 +0000263
Davide Pesavento69857c32020-04-05 16:36:26 -0400264 nfdc route add /ndn udp://<other-host>
Junxiao Shi849e12a2017-08-02 00:14:57 +0000265
Davide Pesavento69857c32020-04-05 16:36:26 -0400266This will print::
Junxiao Shi849e12a2017-08-02 00:14:57 +0000267
268 route-add-accepted prefix=/ndn nexthop=308 origin=static cost=0 flags=child-inherit expires=never
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600269
Davide Pesavento69857c32020-04-05 16:36:26 -0400270This indicates that NFD will forward all Interests that start with ``/ndn`` through the
271face to the other host. This forwards Interests to the other host, but does not provide
272a "back route" for the other host to forward Interests to you. For this, you can rely on
273the "automatic prefix propagation" feature of NFD or use the ``nfdc`` command on the other
274host to add the route.
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600275
276Playing with NFD
277----------------
278
Davide Pesavento69857c32020-04-05 16:36:26 -0400279After you have installed, configured, and started NFD, you can demonstrate the features
280of NDN using the following applications and libraries.
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600281
282Sample applications:
283
Davide Pesaventobf4c1312023-02-23 20:32:01 -0500284 + `Simple examples using the ndn-cxx library <https://docs.named-data.net/ndn-cxx/current/examples.html>`__
Davide Pesavento3bc8e192022-12-31 01:40:11 -0500285 + `Simple examples using the python-ndn library <https://python-ndn.readthedocs.io/en/latest/src/examples/basic_app.html>`__
Steve DiBenedetto62a93942014-08-24 17:13:52 -0600286
287Real applications and libraries:
288
Davide Pesavento17521592020-05-14 19:01:32 -0400289 + `ndn-tools - Essential NDN command-line tools <https://github.com/named-data/ndn-tools>`__
Davide Pesavento3bc8e192022-12-31 01:40:11 -0500290 + `ndn-traffic-generator - Simple traffic generator for NDN <https://github.com/named-data/ndn-traffic-generator>`__
291 + `ndn-svs - State Vector Sync library <https://github.com/named-data/ndn-svs>`__
292 + `PSync - Partial and full Sync library <https://github.com/named-data/PSync>`__