README

Content-Centric Networking CCNx Reference Implementation

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:

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

==================================================
1. Package contents
==================================================

This distribution includes the following things:

A) Preliminary specifications of CCNx protocol, application protocols
   and conventions.
B) C/POSIX reference implementation of CCNx forwarder, 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
   repository support (persistent storage of CCNx data), 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
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 
doc/ - documentation tree.  
doc/technical - specifications
doc/ccode - API documentation generated from C code
doc/javacode - API documentation generated from Java code
csrc/ - C code tree
csrc/include/ccn - C header files
csrc/lib - C application library implementation
csrc/ccnd - CCN daemon, the user-space forwarder implementation
csrc/libexec - connectivity utilities, especially ccndc, the ccnd
       configurator and connectivity agent
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/test - C test suite
csrc/util - launch script support
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/src - Java source tree
javasrc/lib - third-party libraries
javasrc/tools - convenience scripts
schema - XML schema and DTD files
apps - experimental/sample apps tree
apps/ccnChat - simple text chat sample in Java
apps/ccnFileProxy - simple proxy making local files available via CCNx
apps/vlc - vlc plugin for media transport experiments
apps/wireshark - wireshark plugin dissector for decoding CCNx packets
experiments/multicast - scripts for running multi-machine experiments in content
       distribution performance over local multicast group.
android/ - The Android implementaiton
android/external - External libraries needed for ARM
android/CCNx-Android-Lib - A common Android Library for working with CCNx
android/CCNx-Android-Services - Wrappers for ccnd and repository
android/apps - Android applications that use CCNx
android/apps/CCNx-Android-Chat - The CCNx Chat application for Android

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.  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.

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, CCNx 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.7.0 tested)
  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 CCNx-Java) and one each
in apps/ccnChat (Eclipse project name ccnChat) and apps/ccnFileProxy
(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.

Please let us know if JDK1.5 support is important to you, as we plan
to eliminate it in the near future.  The CCNx 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]

We require the Android SDK r7 or later, because of its support for
Android Libraries.  Earlier releases will not compile correctly.

We have tested with:
   Android SDK Tools, revision 7
   SDK Platform Android 2.1-update1, API 7, revision 2



==================================================
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/.
 
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 Content-Centric 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/.

CCND

All CCNx programs require that a ccnd be running:
  bin/ccndstart

To start ccnd sending output to a log file instead of the terminal,
set the 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:
  bin/ccnd -h 

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.

If a $HOME/.ccnx/ccnd.conf file is present then ccndstart will execute

ccndc -f $HOME/.ccnx/ccnd.conf

For a sample file, see csrc/libexec/ccnd.conf.sample

REPOSITORY

The repository provides persistent storage of CCNx content backed by a
filesystem, and responds to interests in the content it has available.

  bin/ccn_repo

will give a usage message showing options.

Start a repository with the name of a directory to use for its backing
store.  The directory does not need to exist already, e.g.:

  bin/ccn_repo ~/my_ccnx_repo

When launched in this way, the ccn_repo will turn into a daemon.  Note
the PID given in the output so you can terminate it later, e.g.:

  bin/ccn_repo stop 17328

Do not run two repositories on the same backing store directory at the same
time.  The experimental implementation has no protection to prevent
this.

It is sometimes very helpful to get a debug dump of the names of
content held by a repository.  You can do this with the command:

  bin/ccn_repo signal nametree
OR
  bin/ccn_repo signal nametreewide

This will produce output in a file in the repository backing
directory.  This file is overwritten every time you send such a
signal.

The repository takes an optional configuration file to control some
settings, but this is not well documented at this time.  See
javasrc/src/org/ccnx/ccn/test/repo/origPolicy.xml for a sample.  Most
important is probably the <namespace> parameter which controls the
CCNx name prefix which the repository will monitor.  By default this
is / which means that writes will be accepted for any name and reads
serviced for any name for which there is content.

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:

  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
  
==================================================
5. Runtime files
==================================================

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.

==================================================
6. Support and contact information
==================================================

Please see our website at http://www.ccnx.org