Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ProjectCCNx/ccnx

THIS REPOSITORY IS NO LONGER MAINTAINED. IT HAS BEEN COMPLETELY REPLACED BY https://github.com/PARC/CCNx_Distillery
https://github.com/ProjectCCNx/ccnx

Last synced: 3 months ago
JSON representation

THIS REPOSITORY IS NO LONGER MAINTAINED. IT HAS BEEN COMPLETELY REPLACED BY https://github.com/PARC/CCNx_Distillery

Awesome Lists containing this project

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



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



## 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, 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

* `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.ccnx.ccn](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/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

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)



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.



__SPECIAL PLATFORM NOTES__



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

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.



    bin/ccnr



The directory named by `CCNR_DIRECTORY` must exist already.

To start ccnr as a daemon, redirect stderr to a file and execute



    bin/ccnr &



ccnr shuts down gracefully if it receives `SIGINT` or `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



    ccnnamelist $CCNR_DIRECTORY/repoFile1



A configuration file in `$CCNR_DIRECTORY/config` and/or environment

variables can be used to control some settings. Most important is probably

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



    bin/ccnr -h



gives configuration options.  For more information about repository

configuration, see the ccnr man page at `doc/manpages/ccnr.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`". 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.

The command `ccnrpolicyedit` may be used to edit the policy.

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:



* `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 ##



Support for CCNx is primarily found on the ccnx.org mailing lists.  There

are three lists: [email protected] (For Developers), [email protected]

(for Users) and [email protected] (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.



## 7. Contributions ##



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



## 8. Related Work ##



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.