Getting Started with NFD

Installing NFD from Binaries

We provide NFD binaries for the supported platforms, which are the preferred installation method. In addition to simplifying installation, the binary release also includes automatic initial configuration and platform-specific tools to automatically start NFD and related daemons. In particular, on OS X and macOS NFD is controlled using launchd and on Ubuntu using upstart mechanisms. In both cases, nfd-start and nfd-stop scripts are convenience wrappers for launchd and upstart.

On OS X and macOS, NFD can be installed with MacPorts. Refer to Install NFD Using the NDN MacPorts Repository on OS X and macOS for more details.

On Ubuntu 14.04 and 16.04, NFD can be installed from NDN PPA repository. Refer to Install NFD Using the NDN PPA Repository on Ubuntu Linux.

Future releases could include support for other platforms. Please send us feedback on the platforms you’re using, so we can prioritize our goals. We would also appreciate help packaging the current NFD release for other platforms.

Install NFD Using the NDN MacPorts Repository on OS X and macOS

OS X and macOS users have the opportunity to seamlessly install and run NFD as well as other related applications via MacPorts. If you are not using MacPorts yet, go to the MacPorts website and install the MacPorts package.

NFD and related ports are not part of the official MacPorts repository. In order to use these ports, you will need to add the NDN MacPorts repository to your local configuration. In particular, you will need to modify the list of source URLs for MacPorts. For example, if your MacPorts are installed in /opt/local, add the following line to /opt/local/etc/macports/sources.conf before or after the default port repository:

rsync://macports.named-data.net/macports/

After this step, you can use sudo port selfupdate to fetch updated port definitions.

The following command will install NFD using MacPorts:

sudo port install nfd

Note

You have to have XCode installed on your machine. This can be installed from the AppStore (free) on OS X 10.7 or later. Older editions of OS X can download an appropriate version of XCode from http://developer.apple.com.

One advantage of using MacPorts is that you can easily upgrade NFD and other packages to the latest version. The following commands will do this job:

sudo port selfupdate
sudo port upgrade nfd

Install NFD Using the NDN PPA Repository on Ubuntu Linux

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

Preliminary steps if you haven’t used PPA packages before

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

sudo apt-get install software-properties-common

Adding NDN PPA

After installing add-apt-repository, run the following command to add NDN PPA repository.

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

Installing NFD and other NDN packages

After you have added NDN PPA repository, NFD and other NDN packages can be easily installed in a standard way, i.e., either using apt-get as shown below or using any other package manager, such as Synaptic Package Manager:

sudo apt-get install nfd

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

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 are not planning to work with the bleeding edge code, make sure you checkout the correct release tag (e.g., *-0.2.0) for both repositories:

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

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

Prerequisites

  • Install the ndn-cxx library and its requirements

  • pkg-config

    On OS X / macOS with MacPorts:

    sudo port install pkgconfig
    

    On Ubuntu:

    sudo apt-get install pkg-config
    
  • libpcap

    Comes with the base system on OS X / macOS.

    On Ubuntu:

    sudo apt-get install libpcap-dev
    

To build manpages and API documentation:

  • doxygen

  • graphviz

  • python-sphinx

    On OS X / macOS with MacPorts:

    sudo port install doxygen graphviz py27-sphinx sphinx_select
    sudo port select sphinx py27-sphinx
    

    On Ubuntu:

    sudo apt-get install doxygen graphviz python-sphinx
    

Besides officially supported platforms, NFD is known to work on: Fedora 20, CentOS 6/7, Gentoo Linux, Raspberry Pi, OpenWRT, FreeBSD 10.0, and several other platforms. We are soliciting help with documenting common problems / pitfalls in installing/using NFD on different platforms on NFD Wiki.

Build

The following basic commands should be used to build NFD on Ubuntu:

./waf configure
./waf
sudo ./waf install

If you have installed ndn-cxx library and/or other dependencies into a non-standard paths, you may need to modify 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 configure stage and how to properly configure and run NFD.

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 enable debug symbols to be included in binaries. This potentially allows more meaningful debugging if NFD or other tools happen to crash.

If it is undesirable, default flags can be easily overridden. The following example shows how to completely disable debug symbols and configure NFD to be installed into /usr with configuration in /etc folder.

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

Customize Compiler

To choose a custom C++ compiler for building NFD, set the CXX environment variable to point to the compiler binary. For example, when using the clang compiler on a Linux system, use the following:

CXX=clang++ ./waf configure

Building documentation

NFD 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 doxgyen

Manpages are automatically created and installed during the normal build process (e.g., during ./waf and ./waf install), if python-sphinx module is detected during ./waf configure stage. By default, manpages are installed into ${PREFIX}/share/man (where default value for PREFIX is /usr/local). This location can be changed during ./waf configure stage using --prefix, --datarootdir, or --mandir options.

For more details, refer to ./waf --help.

Initial configuration

Note

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

General

After installing NFD from source, you need to create a proper config file. If default location for ./waf configure was used, this can be accomplished by simply copying the sample configuration file:

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 private/public key pair, generate self-signed certificate, and use this self-signed certificate to authorize NFD management commands refer to How to configure NFD security? FAQ question.

In the sample configuration file, all authorizations are disabled, effectively allowing anybody on the local machine to issue NFD management commands. The sample file is intended only for demo purposes and MUST NOT be used in a production environment.

Running

Starting

If you have installed NFD from source code, the recommended way of starting NFD is to use the nfd-start script:

nfd-start

On macOS it may ask for your keychain password or ask nfd wants to sign using key 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 service using the operating system’s service manager (such as Upstart, systemd, or launchd).

Connecting to remote NFDs

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

nfdc face create udp://<other host>

where <other host> is the name or IP address of the other host (e.g., udp://spurs.cs.ucla.edu). This outputs:

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 the remote NFD, execute the following command in terminal:

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

This outputs:

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

The /ndn means that NFD will forward all Interests that start with /ndn through the face to the other host. If you only want to forward Interests with a certain prefix, use it instead of /ndn. This only forwards Interests to the other host, but there is no “back route” for the other host to forward Interests to you. For that, you must go to the other host and use nfdc to add the route.

The “back route” can also be automatically configured with nfd-autoreg. For more information refer to ndn-autoreg.

Playing with NFD

After you haved installed, configured, and started NFD, you can try to install and play with the following:

Sample applications:

Real applications and libraries: