The NDNx reference implementation provides the libraries and components required to build and run applications that use and demonstrate the basic NDNx protocols for experimental and research purposes.
NDNx is authored by participants in the Named Data Networking research project (NDN) described at http://named-data.net/. It is based on a fork of the open source CCNx codebase created by PARC and published at https://github.com/ProjectCCNx.
The protocol specifications and the reference implementation are at an early research stage of development, and are released to enable collaboration with researchers. What is provided at this time is pure infrastructure, with no applications of interest. Documentation is also minimal, and so using the release software will require technical sophistication and a willingness to read the code.
This work is free software; you can redistribute it and/or modify it under the terms of the appropriate licenses as covered in the file LICENSE and noted in each source file.
This software is distributed in hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file LICENSE for more information.
- Please see the file LICENSE for important licensing details and limitations.
- Please see the file NOTICES for important notices.
For more information about Project NDNx, see our website at http://www.ndnx.org.
This file provides introductory information in the following sections:
- Package contents
- Supported platforms and development tools
- Build and install instructions
- Running the programs
- Runtime files
- Support and contact information
README files in other directories provide platform and application-specific notes and instructions. Top-level examples include the following:
csrc/README.cygwin
csrc/README.darwin
csrc/README.freebsd
csrc/README.linux
csrc/README.netbsd
csrc/README.solaris
csrc/ndnd/README
doc/manpages/README
This distribution includes the following things:
A. Preliminary specifications of NDNx protocol, application protocols and conventions.
B. C/POSIX reference implementation of NDNx forwarder, repository (persistent stroage of NDNx data, with synchronization), library, primitive utilities, skeleton API docs, and unit test suite. The C implementation is required for all NDNx communication.
C. Minimal sample app (ndnc) to demonstrate basic communication on local LAN.
Documentation is built from source files of various kinds (using a
combination of doxygen and asciidoc) BUT the distribution includes pre-built
documentation so it is not necessary to have a build environment and
toolchain configured to start reading. Point your browser at
doc/index.html
to get started.
The file tree is organized as follows:
README
- this fileLICENSE
- license terms that apply to the distributionwaf
- master configure and build programwscript
- configure and build scriptapps/*
- general-use command-line toolsndn-c/
- NDN C APIndnd
- NDN daemon, the user-space forwarder implementationcontrib
- various useful tools and pluginstests
- C test suitedoc/*
- documentation tree
After building, the following notable directories will appear:
build/bin/
- command-line tools you can run, providing convenience access to mixture of utilities and samplesbuild/lib/
- all libraries needed for applications (both C and Java)build/ndn/
- headers needed for applications in C
Note that these directories are entirely generated and will be removed by some clean targets, so don't use them for anything you want to keep.
OS PLATFORMS
Only Unix-like platforms are currently supported. NDNx code is tested on Ubuntu Linux, MacOS, Solaris, and FreeBSD. Some packaging for Cygwin is currently provided but is not fully supported and there is no other support for Windows platforms yet.
Android is supported in the android/
tree. It only introduces minimal
new code specific to the Android platform and otherwise re-uses the
existing NDNx C and Java code.
C LANGUAGE REQUIREMENTS AND TOOLS
For parts of the system written in C, you will require a standard toolchain including gcc, make. etc. and the following libraries which are not included in the distribution.
- libcrypto >= 0.9.8 from openssl available from http://openssl.org/source/
- expat available from http://sourceforge.net/projects/expat/
- libpcap available from http://www.tcpdump.org (optional, needed for certain utilities only)
- libxml2 available from xmlsoft.org
In addition, you will need wireshark to build and use the NDNx plugins for those packages. Please see the individual README files for more information.
See doc/README*
files for further notes about what needs to be installed or
configured on each OS.
Note that the overall build handles both the C and Java code,
so you will need to have requirements for both met in order
to avoid errors. See the section above. See android/README.build
for information on building for Android.
BUILDING
In the root directory:
./waf configure
./waf
sudo ./waf install
These notes assume that you have performed the build steps listed
above, but not performed a machine install. Everything may be run
directly out of the build tree using programs in bin/
.
NDND
All NDNx programs require that a ndnd be running:
ndndstart
To start ndnd sending output to a log file instead of the terminal,
set the NDND_LOG
environment variable with the path of the file you
want to write. Any existing file with that name will be overwritten.
For a listing of other environment variables that are available (including debug message controls) run:
ndnd -h
Note that you should not ordinarily run ndnd directly, but use the ndndstart script.
For experiments on one machine it is sufficient to have a ndnd running without using a ndnd configuration file, however for multiple machine experimentation you will need to use ndndc to configure the inter-machine forwarding of interest/content.
If a $HOME/.ndnx/ndnd.conf
file is present then ndndstart will execute
ndndc -f $HOME/.ndnx/ndnd.conf
For a sample file, see apps/ndndc/ndnd.conf.sample
REPOSITORY
The repository provides persistent storage of NDNx content backed by a file system, and responds to interests in the content it has available.
Start a repository with the NDNR_DIRECTORY
environment variable set to
the fully qualified pathname of the repository file directory.
ndnr
The directory named by NDNR_DIRECTORY
does not need to exist already.
To start ndnr as a daemon, redirect stderr to a file and execute
ndnr &
ndnr shuts down gracefully if it receives SIGINT
or SIGTERM
, or if the
ndnd to which it is connected is shut down.
Do not run two repositories on the same backing store directory at the same time.
It is sometimes helpful to get a list of the names of stored content held by a repository. To do this, use
ndnnamelist $NDNR_DIRECTORY/repoFile1
A configuration file in $NDNR_DIRECTORY/config
and/or environment
variables can be used to control some settings. Most important is probably
the NDNR_GLOBAL_PREFIX
parameter, which is a namespace for
configuration information about this repository that is expected by
convention to be globally unique and meaningful, rather than only locally
unique and contextually meaningful.
ndnr -h
gives configuration options. For more information about repository
configuration, see the ndnr man page at doc/manpages/ndnr.html
.
A policy file specifies the namespaces for which the repository accepts
and holds content. The name of the policy file is the concatenation of
the global prefix and "data/policy.xml
". Unless an alternative policy has
been explicitly written/published under the policy information name, the
the policy defaults to /
, which means that writes will be accepted for
any name and reads serviced for any name for which there is content.
For more information about policies, see doc/technical/RepoPolicies.html
.
UTILITIES
There are a variety of simple utilities and tools in bin/
. Some of them
have usage messages, but the handling of arguments and usage messages is
inconsistent as of this release. Here are a few notable utilities:
ndnpeek
ndnpoke
ndnd-autoconfig
ndnd-publish-local-info
ndnc
- the ndnChat sample applicationndn-extract-public-key
ndn-install-pubcert
ndn-pubkey-name
and many others.
Beware that running the experimental software will create a variety of files, and that this list may not be complete:
~/.ndnx
- per-user directory, used primarily for personal keystore and key cache
Repository directories are also created if you run a repository, but in that case you must tell the program what directory to use.
For support information, please contact the NDN project PIs at http://named-data.net.
Contributions with compatible license agreements are welcome. For more information, please contact the NDN project PIs at http://named-data.net or issue a pull request on http://github.com/named-data/NDNx.