# $Id: README,v 1.15 2004/01/15 17:00:22 evertonm Exp $

LICENSE

  bera - Buriti Experimental Routing Architecture

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.
  
  This program is distributed in the 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
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with this program -- see the file COPYING; if not, write to
  the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  Boston, MA 02111-1307 USA 


INTRODUCTION

  bera defines an architecture for implementation of experimental
  routing control planes.

  We borrow ideas from other similar software projects like Quagga
  [1] and Xorp [2]. However, bera's major goal is to provide a
  framework for experimental development of routing protocols, thus
  facilitating the work of researchers in the routing community.

  The bera system comprises several daemons working cooperatively to
  offer services commonly found in a routing control plane. In such a
  scenario, XMLRPC [3] is used as primary IPC mechanism. While bera
  initially uses Java [4] as rapid prototyping language, its overall
  design will remain independent of programming language.

  As initial milestone, bera plans to offer a minimal implementation
  of traditional routing protocols, namely RIP, OSPF, BGP and LDP.


GOALS

  The fundamental bera goals can be stated as:

  1) To provide a framework for research focused on development of
  routing control plane.
 
  2) To provide a functional control plane implementation for common
  routing protocols.

  3) To remain as simple as possible, refusing to re-invent mechanisms
  not strictly related to control plane functions. Thus, bera is
  expected to rely heavily on third-party libraries for non-routing
  functions.


SITE

  bera is hosted at Savannah:

  http://savannah.nongnu.org/projects/bera/


THIS DIRECTORY

  In the bera distribution directory, one is supposed to find the
  following entries:

  AUTHORS   - listing of bera authors
  README    - this file
  COPYING   - GNU GPL, the bera licensing terms
  Makefile  - the makefile for bera
  build.xml - Ant build file
  lib       - stores third-party packages used by bera
  doc       - documentation repository
  src       - source code for bera
  old       - old stuff that may be useful
  tools     - miscellaneous tools used in bera development
  bin       - auxiliary scripts used by Makefile in the build process


REQUIREMENTS

  All bera requirements are Free Software packages available under
  GPL-compatible licenses.

  bera is developed and tested under Debian GNU/Linux [12], the only
  platform currently supported.

  The first release of bera is going to use Java as rapid prototyping
  language. Thus, following packages are recommended for running bera:

  Package name          Reference Version
  ------------------------------------------
  gcj                         [5] 3.3.2
  kaffe                       [6] 1.1.3
  freenet                     [7] 0.5.2.1    (*) (optional)
  jakarta-log4j               [8] 1.2.8      (*)
  jakarta-tomcat              [9] 5.0.12     (*)
  classpathx-servletapi      [10] 2.3-alpha1 (*)
  apache-xmlrpc              [11] 1.2-b1     (*)
  jakarta-regexp             [12] 1.3        (*)

  (*) By default, source code for these packages is automatically
      downloaded (if needed) and built by the build process.

  The Freenet package is optional and used strictly as provider of
  framework for unitary testing. Jakarta Regexp is needed because
  currently gcj does not support the package 'java.util.regex'.

  gcj is used to compile bera source code. gcj can compile bera
  directly to executable object code, which may be very convenient for
  some uses.

  Kaffe is needed to run the bytecode produced by gcj.

  There are other packages needed to build and run the bera, like
  'make', but those are commonly available by default on supported
  platforms.


BUILDING

  PRE-REQUISITES

  Make sure that:
  1) gcj is properly installed and available in the shell search path.
  2) The following source packages lie in the 'lib' directory,
     OR
     you have Internet access and the 'wget' utility is available;
     then the Makefile will be able to automatically fetch them.
     You may need to edit the 'Makefile' to adjust the download URLs.

     lib/jakarta-log4j-1.2.8.tar.gz
     lib/jakarta-tomcat-5.0.12-src.tar.gz
     lib/servletapi-2.3-alpha1.tar.gz
     lib/xmlrpc-1.2-b1-src.tar.gz
     lib/jakarta-regexp-1.3.tar.gz

  BUILDING BYTECODE

    To compile the available modules to bytecode, just type:

    make bera-jar

    The resulting jar files are deposited under the 'dist' directory.
  
  BUILDING OBJECT CODE

    To compile the desired modules directly to object code, by invoking
    gcj, type:

    make fea
    make rib
    make rip
    make rip-query
    make manager

RUNNING

  RUNNING BYTECODE

    Make sure 'java' points to Kaffe virtual machine.

    To execute bytecode for available modules, type:

    make run-fea-jar
    make run-rib-jar
    make run-rip-jar
    make run-rip-query-jar
    make run-manager-jar

  RUNNING OBJECT CODE

    Ensure 'dist/lib' directory is in the dynamic loader path. 
    Example:

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:dist/lib

    Invoke the desired modules. Examples:

    su -c ./dist/bin/fea ;# FEA handles kernel routing table
    ./dist/bin/rib
    su -c "./dist/bin/rip <instanceName>" ;# RIP listens on privileged port
    ./dist/bin/rip-query <hostname>
    ./dist/bin/manager <configDirectory>

    EXAMPLE: RUNNING RIP

    In order to properly run RIP, one must start these daemons:
    - fea:     for communication with underlying operating system
    - rib:     for handling of routing information
    - manager: for configuration of RIP process through CLI
    - rip:     the RIP process itself

    For instance, a typical startup sequence for trying RIP follows:

      su -c ./dist/bin/fea ;# FEA handles kernel routing table

      ./dist/bin/rib

      mkdir /tmp/manager
      ./dist/bin/manager /tmp/manager

      su -c './dist/bin/rip 1' ;# RIP listens on privileged port

    As soon as 'manager' is running, one can telnet to port 3000 to
    access the CLI. Just press ENTER at the username/password prompts.

    Actually the exact invokation sequence does not matter. Just make
    sure you start all those processes. But see also the CAVEATS file.

    Please notice that currently the processes don't put themselves
    automatically into background; you'll probably want to start each
    process in a separate terminal window.


INSTALL

  At this stage, there is no specific instruction for installation of
  bera on a live system.

  However, the following command can be used to dump binaries and
  libraries under '/usr/local/bera':

    make INSTALL_DIR=/usr/local/bera install


REFERENCES

[1] Quagga 
    http://www.quagga.net/

[2] Xorp
    http://www.xorp.org/

[3] XMLRPC
    http://www.xmlrpc.com/

[4] Java
    http://java.sun.com/

[5] gcj
    http://gcc.gnu.org/java/

[6] Kaffe
    http://www.kaffe.org/

[7] Freenet
    http://freenet.sourceforge.net/

[8] Jakarta Log4j
    http://jakarta.apache.org/log4j/

[9] Jakarta Tomcat
    http://jakarta.apache.org/tomcat/

[10] GNU Classpathx
     http://www.gnu.org/software/classpathx/

[11] Apache XMLRPC
     http://ws.apache.org/xmlrpc/

[12] Jakarta Regexp
     http://jakarta.apache.org/regexp/

[13] Debian GNU/Linux
     http://www.debian.org/

