The CCNx reference implementation provides the libraries and components required to build and run applications that use and demonstrate the basic CCNx protocols for experimental and research purposes.
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 CCNx, see our website at http://www.ccnx.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:
android/README.build csrc/README.cygwin csrc/README.darwin csrc/README.freebsd csrc/README.linux csrc/README.netbsd csrc/README.solaris csrc/ccnd/README doc/manpages/README
This distribution includes the following things:
A. Preliminary specifications of CCNx protocol, application protocols and conventions.
B. C/POSIX reference implementation of CCNx forwarder, repository (persistent stroage of CCNx data, with synchronization), library, primitive utilities, skeleton API docs, and unit test suite. The C implementation is required for all CCNx 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 (ccnChat) to demonstrate basic communication on local LAN.
E. Minimal sample file proxy (ccnFileProxy) 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 ccnd and the repository. It also has a CCN 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- CCNx 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 CCNx
android/apps/CCNx-Android-Chat- The CCNx Chat application for Android
android/CCNx-Android-Lib- A common Android Library for working with CCNx
android/CCNx-Android-Services- Wrappers for ccnd and repository
android/external- External libraries needed for ARM
apps- experimental/sample apps tree
apps/ccnChat- simple text chat sample in Java
apps/ccnFileProxy- simple proxy making local files available via CCNx
apps/examples- small example programs and code snippets
apps/HttpProxy- sample HTTP proxy that converts HTTP Gets to CCN interests
apps/vlc- vlc plugin for media transport experiments
apps/wireshark- wireshark plugin dissector for decoding CCNx packets
csrc/- C code tree
csrc/ccnd- CCN daemon, the user-space forwarder implementation
csrc/ccnr- repository daemon, for persistent storage of content
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/ccn- C header files
csrc/lib- C application library implementation
csrc/libexec- connectivity utilities, especially ccndc, the ccnd configurator and connectivity agent
csrc/rc- sample rc scripts for automatic daemon startup
csrc/sync- sync protocol implementation
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- CCNx man pages
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.ccnx.ccn.
javasrc/lib- third-party libraries
javasrc/src- Java source tree
javasrc/tools- convenience scripts
schema- XML schema and DTD files
vendor- unmodified copies of included third-party code
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/binis 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.
Only Unix-like platforms are currently supported. CCNx 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 CCNx 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 CCNx plugins for those packages. Please see the individual README files for more information.
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, CCNx code is tested with Java JDK 1.6 and 1.7 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)
.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
CCNx-Java) and one each
apps/ccnChat (Eclipse project name
(Eclipse project name
ccnFileProxy). 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.
SPECIAL PLATFORM NOTES
You will need to use gmake rather than make.
android/README for special notes about Android.
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.
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
for information on building for Android.
In the root directory:
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
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.
To run the complete test suite (both C and Java):
MACHINE INSTALL (OPTIONAL)
To install to a standard location on your machine you may also use
See the notes in the Content-Centric Networking in C in the top-level documentation.
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
All CCNx programs require that a ccnd be running:
To start ccnd sending output to a log file instead of the terminal,
CCND_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:
Note that you should not ordinarily run ccnd directly, but use the ccndstart script.
For experiments on one machine it is sufficient to have a ccnd running without using a ccnd configuration file, however for multiple machine experimentation you will need to use ccndc to configure the inter-machine forwarding of interest/content.
$HOME/.ccnx/ccnd.conf file is present then ccndstart will execute
ccndc -f $HOME/.ccnx/ccnd.conf
For a sample file, see
The repository provides persistent storage of CCNx content backed by a file system, and responds to interests in the content it has available.
Start a repository with the
CCNR_DIRECTORY environment variable set to
the fully qualified pathname of the repository file directory.
The directory named by
CCNR_DIRECTORY must exist already.
To start ccnr as a daemon, redirect stderr to a file and execute
ccnr shuts down gracefully if it receives
SIGTERM, or if the
ccnd 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
A configuration file in
$CCNR_DIRECTORY/config and/or environment
variables can be used to control some settings. Most important is probably
CCNR_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.
gives configuration options. For more information about repository
configuration, see the ccnr man page at
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". The actual encoding of the
files is in ccnb form, and it must be stored in the repository to take
effect. 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.
ccnrpolicyedit may be used to edit the policy.
For more information about policies, see
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:
ccnexplore- 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.
ccnls- primitive content listing by retrieval
ccnlsrepo- command-line content listing from repo (via name enumeration)
ccnputfile- command-line tool to send file as CCNx data (asks repo to receive unless -raw arg given)
ccngetfile- command-line tool to retrieve CCNx content and store it in file
ccnchat- the ccnChat sample application
ccnfileproxy- the ccnFileProxy sample application
Beware that running the experimental software will create a variety of files, and that this list may not be complete:
~/.ccnx- 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.
Support for CCNx is primarily found on the ccnx.org mailing lists. There are three lists: firstname.lastname@example.org (For Developers), email@example.com (for Users) and firstname.lastname@example.org (for NEW and Updates). Find out more at: http://www.ccnx.org/subscribe-to-the-mailing-lists/
Live support can be found in realtime on IRC: #ccnx
Please see our website at http://www.ccnx.org.
For developers looking to provide bug fixes, documentation, code samples, or new features, we recommend first reviewing our process for contributing code online: http://www.ccnx.org/support/contributing-code/
All code contributions and patches will require individuals to sign a Contributor Agreement. Individuals representing an organization should first consult with their own legal departments before singing anything. Once we have a ratified document, we are free to take in source contributions. We strongly recommend using the Fork feature of Github described here: http://help.github.com/fork-a-repo/
When code is ready for review, send a Pull Request, described here: http://help.github.com/send-pull-requests/
This process creates a nice dialogue and fosters transparency in the process.
For organizations interested in contributing large bodies of work, we recommend contacting the project leads to discuss a Software Grant Agreement.
If signing a Contributor Agreement is not possible due to organizational or legal restrictions, there are other ways to get involved, including contributing interesting code on our WIKI at: https://www.ccnx.org/wiki
We are actively interested in promoting and fostering development and collaboration within the CCNx Community. If you have something great to share related to CCNx, built on, forked from, or otherwise of interest to this Community, please contact us. We will be looking for ways to publish community project via http://www.ccnx.org on our WIKI.