This repository has been archived by the owner. It is now read-only.
Permalink
Fetching contributors…
Cannot retrieve contributors at this time
429 lines (308 sloc) 16 KB
Named Data Networking Reference Implementation (NDNx)
=====================================================
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.
For more information on the relationship between NDNx and CCNx, see
http://named-data.net/relationship-ndnx-ccnx/.
-----------------------------------------------------
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:
1. Package contents
2. Supported platforms and development tools
3. Build and install instructions
4. Running the programs
5. Runtime files
6. Support and contact information
README files in other directories provide platform and application-specific
notes and instructions. Top-level examples include the following:
android/README.build
csrc/README.cygwin
csrc/README.darwin
csrc/README.freebsd
csrc/README.linux
csrc/README.netbsd
csrc/README.solaris
csrc/ndnd/README
doc/manpages/README
## 1. Package contents ##
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. Java reference implementation of library including primitive
utilities, skeleton API docs, and unit test suite. The Java
library has more functionality implemented or started than the C
library and may be an easier place to start experimenting.
D. Minimal sample app (ndnChat) to demonstrate basic communication on
local LAN.
E. Minimal sample file proxy (ndnFileProxy) to demonstrate basic
communication on local LAN.
F. Experimental plugins for vlc (media transport) and wireshark
(packet dissector)
G. An Android implementation for smartphones. The Android implementation
has a service wrapper for ndnd and the repository. It also has
an NDN Chat implementation.
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 file
* `LICENSE` - license terms that apply to the distribution
* `MANIFEST` - listing of every file in the distribution
* `MD5` - MD5 sum for every file in the distribution
* `NEWS` - release notes
* `NOTICES` - NDNx notices
* `SHA1` - SHA1 sum for every file in the distribution
* `configure` - master configure script. Note that configure scripts are
hand-written at this time, not generated by autoconf
* `android/` - The Android implementation
* `android/apps` - Android applications that use NDNx
* `android/apps/NDNx-Android-Chat` - The NDNx Chat application for Android
* `android/NDNx-Android-Lib` - A common Android Library for working with NDNx
* `android/NDNx-Android-Services` - Wrappers for ndnd and repository
* `android/external` - External libraries needed for ARM
* `apps` - experimental/sample apps tree
* `apps/ndnChat` - simple text chat sample in Java
* `apps/ndnFileProxy` - simple proxy making local files available via NDNx
* `apps/examples` - small example programs and code snippets
* `apps/HttpProxy` - sample HTTP proxy that converts HTTP Gets to NDN interests
* `apps/vlc` - vlc plugin for media transport experiments
* `apps/wireshark` - wireshark plugin dissector for decoding NDNx packets
* `csrc/` - C code tree
* `csrc/ndnd` - NDN daemon, the user-space forwarder implementation
* `csrc/cmd` - simple command-line utilities
* `csrc/conf` - OS-specific configuration scripts etc.
* `csrc/contrib` - third-party library needed for certain platforms that
are POSIX-deficient
* `csrc/include/ndn` - C header files
* `csrc/lib` - C application library implementation
* `csrc/libexec` - connectivity utilities, especially ndndc, the ndnd
configurator and connectivity agent
* `csrc/tests` - C test suite
* `csrc/util` - launch script support
* `doc/` - documentation tree
* `doc/android` - API documentation generated from Java code for Android
* `doc/ccode` - API documentation generated from C code
* `doc/javacode` - API documentation generated from Java code
* `doc/manpages` - NDNx man pages
* `doc/technical` - specifications
* `experiments/multicast` - scripts for running multi-machine experiments in content
distribution performance over local multicast group.
* `javasrc/` - Java code tree. The usual Java conventions are used for mapping
package names to the file tree, with root package [org.ndnx.ndn](org.ndnx.ndn).
* `javasrc/lib` - third-party libraries
* `javasrc/src` - Java source tree
* `javasrc/tools` - convenience scripts
* `schema` - XML schema and DTD files
After building, the following notable directories will appear:
* `bin/` - command-line tools you can run, providing convenience access to
mixture of C and Java utilities and samples
* `lib/` - all libraries needed for applications (both C and Java)
* `include/` - headers needed for applications in C
* `javasrc/build` - Java build outputs from ant (`javasrc/bin` is equivalent
for Eclipse)
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.
## 2. Supported platforms ##
__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 vlc and wireshark to build and use the NDNx
plugins for those packages. Please see the individual README files
for more information.
See `csrc/README*` files for further notes about what needs to be installed or
configured on each OS.
__JAVA LANGUAGE REQUIREMENTS AND TOOLS__
For parts of the system written in Java, NDNx code is tested with Sun
Java JDK 1.5 and 1.6 only, with ant used as the canonical build tool.
You will need:
* ant (>= 1.8.2 tested, download latest version from: http://ant.apache.org/bindownload.cgi)
extra libraries for JDK1.5 only (see below)
Eclipse `.project` and `.classpath` files are included in the distribution
so you can create Eclipse projects easily that will resolve
dependencies correctly. There are three Eclipse Java projects
defined: one in `javasrc` (Eclipse project name `NDNx-Java`) and one each
in `apps/ndnChat` (Eclipse project name `ndnChat`) and `apps/ndnFileProxy`
(Eclipse project name `ndnFileProxy`). To import one of these projects
into your Eclipse workspace, choose File/Import... from the menu, open
the General category in the Import dialog and select "Existing
Projects into Workspace". Type in (or browse to) the appropriate
directory and you should see the named Project listed and selected so
you can click Finish to complete the import.
Please let us know if JDK1.5 support is important to you, as we plan
to eliminate it in the near future. The NDNx distribution includes
JAR files for required libraries for JDK1.6.
ONLY IF you are going to run on JDK1.5 you must obtain the following additional
library file independently:
* Bouncy Castle Provider for JDK1.5: `bcprov-jdk15-143.jar`
(http://www.bouncycastle.org/download/bcprov-jdk15-143.jar)
Copy the extra JAR file into `javasrc/lib`, again ONLY IF you
are running on JDK1.5.
__SPECIAL PLATFORM NOTES__
_Fedora_
JDK1.5 on Fedora has been seen to be extremely slow at seeding the
random number generator, which causes major delays for certain
operations such as generating the initial keystore file. We recommend
using JDK1.6 on Fedora.
_Solaris_
You will need to use gmake rather than make.
_Android_
Please see `android/README` for special notes about Android.
_Ubuntu_
As a result of Sun Java JDK packages being removed for Ubuntu (see
https://lists.ubuntu.com/archives/ubuntu-security-announce/2011-December/001528.html), we are now using OpenJDK for Ubuntu. Please see csrc/README.linux
for more information.
## 3. Build and install instructions ##
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:
./configure
make
The top-level build will compile both C and Java code, but
not Android code. The above is sufficient to run programs
locally out of `bin/` and build apps referencing `lib/` and `include/`.
For users of Maven, it is now possible to build the javasrc. From the
top-level:
mvn clean package
will produce a library, javadocs, and sources in separate jar files
under javasrc/target. This is provided as a convenience for users of
the Maven ecosystem of tools. The Maven build does not support the
full suite of tests yet.
__TESTING__
To run the complete test suite (both C and Java):
make test
__MACHINE INSTALL (OPTIONAL)__
To install to a standard location on your machine you may also use
make install
__FURTHER DOCUMENTATION__
See the notes in the Named Data Networking in C in the top-level
documentation.
## 4. Running the programs ##
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:
bin/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:
bin/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 `csrc/libexec/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.
bin/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
bin/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.
bin/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 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:
* `ndnexplore` - primitive GUI browser in Java, usable to browse only
repo content since it requires name enumeration support
available only there. Also allows writing files to repo.
* `ndnls` - primitive content listing by retrieval
* `ndnlsrepo` - command-line content listing from repo (via name
enumeration)
* `ndnputfile` - command-line tool to send file as NDNx data (asks repo
to receive unless -raw arg given)
* `ndngetfile` - command-line tool to retrieve NDNx content and store it
in file
* `ndnchat` - the ndnChat sample application
* `ndnfileproxy` - the ndnFileProxy sample application
## 5. Runtime files ##
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
* `~/.rmi-server-*` - per-user files Java daemon RMI interface objects.
These are supposed to be cleared away automatically but that
does not occur if processes are terminated manually and in
other cases.
Repository directories are also created if you run a repository, but
in that case you must tell the program what directory to use.
## 6. Support and contact information ##
For support information, please contact the NDN project PIs at http://named-data.net.
## 7. Contributions ##
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.