README.md

NFD - Named Data Networking Forwarding Daemon
==============================================================

## Default Paths

This README uses `SYSCONFDIR` when referring to the default locations of
various NFD configuration files.  By default, `SYSCONFDIR` is set to
`/usr/local/etc`.  If you override `PREFIX`, then `SYSCONFDIR` will
default to `PREFIX/etc`.

You may override `SYSCONFDIR` and `PREFIX` by specifying their
corresponding options during installation:

    ./waf configure --prefix <path/for/prefix> --sysconfdir <some/other/path>

Refer to `INSTALL.md` for more detailed instructions on how to compile
and install NFD.

## Running and Configuring NFD

NFD's runtime settings may be modified via configuration file.  After
installation, a working sample configuration is provided at
`SYSCONFDIR/ndn/nfd.conf.sample`.  At startup, NFD will attempt to
read the default configuration file location:
`SYSCONFDIR/ndn/nfd.conf`.

You may also specify an alternative configuration file location
by running NFD with:

    nfd --config </path/to/nfd.conf>

Once again, note that you may simply copy or rename the provided
sample configuration and have an **almost** fully configured NFD.
However, this NFD will be unable to add FIB entries or perform
other typical operation tasks until you authorize an NDN certificate
with the appropriate privileges.

## Installing an NDN Certificate for Command Authentication

Many NFD management protocols require signed commands to be processed
(e.g. FIB modification, Face creation/destructions, etc.). You will
need an NDN certificate to use any application that issues signed
commands.

If you do not already have NDN certificate, you can generate one with
the following commands:

**Generate and install a self-signed identity certificate**:

    ndnsec-keygen /`whoami` | ndnsec-install-cert -

Note that the argument to ndnsec-key will be the identity name of the
new key (in this case, `/your-username`). Identity names are
hierarchical NDN names and may have multiple components
(e.g. `/ndn/ucla/edu/alice`).  You may create additional keys and
identities as you see fit.

**Dump the NDN certificate to a file**:

The following commands assume that you have not modified
`PREFIX` or `SYSCONFDIR` If you have, please substitute
`/usr/local/etc` for the appropriate value (the overriden
`SYSCONFDIR` or `PREFIX/etc` if you changed `PREFIX`).

    sudo mkdir -p /usr/local/etc/ndn/keys
    ndnsec-cert-dump -i /`whoami` > default.ndncert
    sudo mv default.ndncert /usr/local/etc/ndn/keys/default.ndncert

## Running NFD with Ethernet Face Support

The ether configuration file section contains settings for Ethernet
faces and channels.  These settings will **NOT** work without root or
setting the appropriate permissions:

    sudo setcap cap_net_raw,cap_net_admin=eip /full/path/nfd

You may need to install a package to use setcap:

**Ubuntu:**

    sudo apt-get install libcap2-bin

**Mac OS X:**

    curl https://bugs.wireshark.org/bugzilla/attachment.cgi?id=3373 -o ChmodBPF.tar.gz
    tar zxvf ChmodBPF.tar.gz
    open ChmodBPF/Install\ ChmodBPF.app

or manually:

    sudo chgrp admin /dev/bpf*
    sudo chmod g+rw /dev/bpf*

## UDP multicast support in multi-homed Linux machines

The UDP configuration file section contains settings for unicast and multicast UDP
faces. If the Linux box is equipped with multiple network interfaces with multicast
capabilities, the settings for multicast faces will **NOT** work without root
or setting the appropriate permissions:

    sudo setcap cap_net_raw=eip /full/path/nfd