Getting started with NFD

Supported platforms

NFD is built against a continuous integration system and has been tested on the following platforms:

  • Ubuntu 18.04 (amd64, armhf, i386)
  • Ubuntu 20.04 (amd64)
  • macOS 10.13
  • macOS 10.14
  • macOS 10.15
  • CentOS 8

NFD is known to work on the following platforms, although they are not officially supported:

  • Debian 10 (Buster)
  • Fedora >= 29
  • Gentoo Linux
  • Raspbian >= 2019-06-20 (Buster)

Install NFD on Ubuntu Linux using the NDN PPA repository

NFD binaries and related tools for supported versions of Ubuntu can be installed using PPA packages from the named-data repository. First, you will need to add the named-data/ppa repository to the binary package sources and update the list of available packages.

Preliminary steps if you have not used PPA packages before

To simplify adding new PPA repositories, Ubuntu provides the add-apt-repository tool, which is not installed by default on some systems.

sudo apt install software-properties-common

Adding the NDN PPA

After installing add-apt-repository, run the following commands to add the NDN PPA repository:

sudo add-apt-repository ppa:named-data/ppa
sudo apt update

Installing NFD and other NDN packages

After you have added the NDN PPA repository, NFD and other NDN packages can be easily installed either using apt, as shown below, or any other compatible package manager.

sudo apt install nfd

For the list of available packages, refer to the NDN PPA repository page.

Building from source

Downloading from git

The first step is to obtain the source code for NFD and its main dependency, the ndn-cxx library. If you do not want a development version of NFD, make sure you checkout the correct release tag (e.g., *-0.7.1) from both repositories.

# Download ndn-cxx
git clone https://github.com/named-data/ndn-cxx.git

# Download NFD
git clone --recursive https://github.com/named-data/NFD.git

Note

While we strive to ensure that the latest version (git master branch) of NFD and ndn-cxx always compiles and works properly, we cannot guarantee that there will be no issues. If this is discovered to be the case, please use matching released versions (git tag or tarball) of NFD and ndn-cxx instead.

Prerequisites

Install the ndn-cxx library and its prerequisites.

On Linux, NFD needs the following dependencies to enable optional features:

  • On Ubuntu:

    sudo apt install libpcap-dev libsystemd-dev

  • On CentOS and Fedora:

    sudo dnf config-manager --enable PowerTools  # on CentOS only
sudo dnf install libpcap-devel systemd-devel

Build

The following commands can be used to build and install NFD from source:

./waf configure  # on CentOS, add --without-pch
./waf
sudo ./waf install

If you have installed ndn-cxx and/or any other dependencies into a non-standard path, you may need to modify the PKG_CONFIG_PATH environment variable before running ./waf configure. For example:

export PKG_CONFIG_PATH="/custom/lib/pkgconfig:$PKG_CONFIG_PATH"
./waf configure
./waf
sudo ./waf install

Refer to ./waf --help for more options that can be used during the configure stage.

Note

If you are working on a source repository that has been compiled before, and you have upgraded one of the dependencies, please execute ./waf distclean to clear object files and start over.

Debug symbols

The default compiler flags include debug symbols in binaries. This should provide more meaningful debugging information if NFD or other tools happen to crash.

If this is not desired, the default flags can be overridden to disable debug symbols. The following example shows how to completely disable debug symbols and configure NFD to be installed into /usr with configuration in the /etc directory.

CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
./waf
sudo ./waf install

For Ubuntu PPA packages, debug symbols are available in *-dbg packages.

Customizing the compiler

To build NFD with a different compiler (rather than the platform default), set the CXX environment variable to point to the compiler binary. For example, to build with clang on Linux, use the following:

CXX=clang++ ./waf configure

Building the documentation

Tutorials and API documentation can be built using the following commands:

# Full set of documentation (tutorials + API) in build/docs
./waf docs

# Only tutorials in build/docs
./waf sphinx

# Only API docs in build/docs/doxygen
./waf doxygen

If sphinx-build is detected during ./waf configure, manpages will automatically be built and installed during the normal build process (i.e., during ./waf and ./waf install). By default, manpages will be installed into ${PREFIX}/share/man (the default value for PREFIX is /usr/local). This location can be changed during the ./waf configure stage using the --prefix, --datarootdir, or --mandir options.

For further details, please refer to ./waf --help.

Initial configuration

Note

If you have installed NFD from binary packages, the package manager has already installed a working configuration and you can safely skip this section.

General

After installing NFD from source, you need to create a proper configuration file. If the default installation directories were used with ./waf configure, this can be accomplished by simply copying the sample configuration file as follows:

sudo cp /usr/local/etc/ndn/nfd.conf.sample /usr/local/etc/ndn/nfd.conf

NFD Security

NFD provides mechanisms to enable strict authorization for all management commands. In particular, one can authorize only specific public keys to create new faces or change the forwarding strategy for specific namespaces. For more information about how to generate public/private key pairs, generate self-signed certificates, and use them to authorize NFD management commands, refer to the How do I configure NFD security? FAQ question.

In the sample configuration file, all security mechanisms are disabled for local clients, effectively allowing anybody on the local machine to issue NFD management commands.

Note

The sample configuration file is intended only for demo purposes and should NOT be used in production environments.

Running

Starting

If you have installed NFD from source, it is recommended to start NFD with the nfd-start script:

nfd-start

On macOS, this command may ask for your keychain password or ask “nfd wants to sign using key [xyz] in your keychain”. Enter your keychain password and click “Always Allow”.

Later, you can stop NFD with nfd-stop or by simply killing the nfd process.

If you have installed NFD using a package manager, you can start and stop NFD using the operating system’s service manager, such as systemctl or launchctl.

Connecting to remote forwarders

To create a UDP tunnel to a remote instance of NFD, execute the following command in a terminal:

nfdc face create udp://<other-host>

where <other-host> is the name or IP address of the other host (e.g., udp://ndn.example.net). If successful, this will print something like:

face-created id=308 local=udp4://10.0.2.15:6363 remote=udp4://131.179.196.46:6363 persistency=persistent

To add a route /ndn toward this remote forwarder, execute the following command in a terminal:

nfdc route add /ndn udp://<other-host>

This will print:

route-add-accepted prefix=/ndn nexthop=308 origin=static cost=0 flags=child-inherit expires=never

This indicates that NFD will forward all Interests that start with /ndn through the face to the other host. This forwards Interests to the other host, but does not provide a “back route” for the other host to forward Interests to you. For this, you can rely on the “automatic prefix propagation” feature of NFD or use the nfdc command on the other host to add the route.

Playing with NFD

After you have installed, configured, and started NFD, you can demonstrate the features of NDN using the following applications and libraries.

Sample applications:

Real applications and libraries: