#
# $XORP: xorp/README,v 1.65 2009/01/09 19:20:58 jtc Exp $
#

		XORP: eXtensible Open Router Platform



1. Overview
===========

XORP is an open networking platform being developed by a core team of
developers from XORP, Inc., and members of the XORP.org community.
It started life as a project at the ICSI Center for Open Networking (ICON)
at the International Computer Science Institute in Berkeley, California,
USA, and is now owned and shepherded by the team at XORP, Inc.

XORP's primary goal is to be an open platform for networking protocol
implementations and an alternative to proprietary and closed networking
products in the marketplace today. XORP hopes to drive innovation in
the networking field by making available an enterprise-grade open
networking platform to the development community.

XORP design philosophy is:
  * modularity
  * extensibility
  * performance
  * robustness
This is achieved by carefully separating functionalities into
independent modules, and by providing an API for each module.

XORP divides into two subsystems. The higher-level ("user-level")
subsystem consists of the routing protocols. The lower-level ("kernel")
manages the forwarding path, and provides APIs for the higher-level to
access.

User-level XORP uses multi-process architecture with one process per
routing protocol, and a novel inter-process communication mechanism
called XRL (XORP Resource Locator). XRLs can be used across the network,
therefore XORP can in principle run in distributed fashion. For
example, we can have a distributed router with the forwarding engine
running on one machine, and each of the routing protocols that update
the forwarding engine is running on a separate machine.

The lower-level subsystem can use traditional UNIX kernel forwarding, or
Click modular router. The modularity and independency of the lower-level
from the user-level subsystem allows for its easily replacement with
other solutions including high-end hardware-based forwarding engines.

For more information about XORP high-level design see the following
paper available from http://www.xorp.org/ :
"XORP: An Open Platform for Network Research", HotNets-I 2002 Workshop.


2. Status
=========

This is XORP Release 1.7-WIP
It is reasonably stable and can be used for routing, but there are known
issues.

Supported platforms:

  * DragonFlyBSD
  * FreeBSD
  * NetBSD
  * OpenBSD
  * Linux
  * Mac OS X
  * Microsoft Windows

See ${XORP}/BUILD_NOTES for OS-specific details, compilation
information, etc.

Development platform:

  * FreeBSD-7.0-RELEASE
    - gcc/g++ version 4.2.1 (default)
    - gmake (GNU make) version 3.81
    - autoconf version 2.61
    - automake version 1.10
    - libtool version 1.5.24
    - flex version 2.5.4
    - yacc version default one that comes with the above OS

Other platforms can also be used for development, but the installed
version of autotools (autoconf/automake/libtool) should match the
information listed above.
For Microsoft Windows-based development see the corresponding
entry in ${XORP}/BUILD_NOTES.

See ${XORP}/ERRATA for the list of known problems.

Currently, XORP implements the following protocols:

  * RIP and RIPng:
    - RFC 2453 (RIP version 2)
    - RFC 2082 (RIP-2 MD5 Authentication)
    - RFC 2080 (RIPng for IPv6)

  * BGP4:
   - RFC 4271 (A Border Gateway Protocol 4 (BGP-4))
   - RFC 3392 (Capabilities Advertisement with BGP-4)
   - RFC 4760 (Multiprotocol Extensions for BGP-4)
   - RFC 2545 (Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain
              Routing)
   - RFC 1997 (BGP Communities Attribute)
   - RFC 2796 (BGP Route Reflection - An Alternative to Full Mesh IBGP)
   - RFC 3065 (Autonomous System Confederations for BGP)
   - RFC 2439 (BGP Route Flap Damping)
   - RFC 4893 (BGP Support for Four-octet AS Number Space)
   - RFC 1657 (Definitions of Managed Objects for the Fourth Version
	      of the Border Gateway Protocol (BGP-4) using SMIv2)

  * OSPFv2:
   - RFC 2328 (OSPF Version 2)
   - RFC 3101 (The OSPF Not-So-Stubby Area (NSSA) Option)

  * OSPFv3:
   - draft-ietf-ospf-ospfv3-update-14.txt (OSPF for IPv6)

  * PIM-SM:
    - draft-ietf-pim-sm-v2-new-11.{ps,txt}
    - draft-ietf-pim-sm-bsr-03.{ps,txt}

  * IGMP v1, v2, and v3:
    - RFC 2236 (Internet Group Management Protocol, Version 2)
    - RFC 3376 (Internet Group Management Protocol, Version 3)

  * MLD v1 and v2:
    - RFC 2710 (Multicast Listener Discovery (MLD) for IPv6)
    - RFC 3810 (Multicast Listener Discovery Version 2 (MLDv2) for IPv6)

  * VRRP v2:
    - RFC 3768 (Virtual Router Redundancy Protocol (VRRP))

For description of the changes in each release, see ${XORP}/RELEASE_NOTES.


3. Compilation, configuration and startup
=========================================

To compile XORP, you must have GNU make (gmake) installed. Then just
run the following commands in the top-level directory:

./configure
gmake

See ${XORP}/BUILD_NOTES for additional information of building XORP.

In general, configuration and startup of the various XORP processes are
normally meant to happen via the router manager (rtrmgr), so please
refer first to the XORP configuration guide:
http://www.xorp.org/getting_started.html

For additional information see the user documentation:
http://www.xorp.org/releases/current/docs/user_manual/user_manual.pdf
and ${XORP}/docs/user_manual.


4. Code structure and documentation
===================================

The code is split into several directories, each containing libraries,
components or implementation of the various XORP modules.  Typically,
documentation for each of them is available in one or more of the
following places:

  * the README file in each directory

  * a high level architecture overview, available in

	${XORP}/docs/<modulename>/

  * kdoc-generated documentation, created with the script

	${XORP}/docs/kdoc/gen-kdoc.sh

    whose output goes into

	${XORP}/docs/kdoc/html/<modulename>/

    with top-level index file in

	${XORP}/docs/kdoc/html/index.html

The content of each of the directories is the following:

  * bgp : BGP implementation.

  * cli : CLI (Command-Line Interface) library.
    It is used by the Router Manager (rtrmgr), and by some of the
    multicast code (the multicast-specific part of fea, mld6igmp, pim).

  * docs : XORP user documentation.

  * etc : Various XORP-related files (e.g., configuration, templates).

  * fea : Forwarding Engine Abstraction.
    The FEA implements the interface between XORP and the underlying
    forwarding engine (e.g., the UNIX kernel). It is used both for
    unicast and multicast. Note that the multicast-specific
    documentation is in ${XORP}/docs/mfea.

  * fib2mrib : Forwarding Information Base to the Multicast Routing
    Information Base route propagator.
    It uses the FEA to obtain the FIB information from the underlying
    system, and propagates it to the MRIB, so it can be used by
    multicast routing protocols such as PIM-SM. Typically, it is needed
    only if the unicast routing protocols run within XORP do not inject
    routes in the MRIB.

  * libcomm : Communication socket library.

  * libfeaclient : Library that is useful to clients of the FEA.

  * libproto : Abstract protocol library.
    Used by the following modules/directories: cli, fea, mld6igmp, ospf,
    pim.

  * libxipc : XRL (XORP Resource Locator) library and XRL-related
    programs.

  * libxorp : XORP library that contains various basic
    functionalities such as IP addresses, IP subnets, etc.

  * mld6igmp : Multicast Listen Discovery/Internet Group Management
    Protocol (MLD/IGMP) implementation.

  * mrt : Various multicast-related code.
    Used by the following modules/directories: fea, mld6igmp, pim.

  * ospf : Open Shortest Path First implementation.

  * policy : Policy-related library.

  * pim : Protocol Independent Multicast - Sparse Mode (PIM-SM)
    implementation.

  * rib : Routing Information Base.
    It is used to store the routing information from various protocols.

  * rip: Routing Information Protocol implementation.

  * rtrmgr : Router Manager.
    It is used to manage and configure all XORP components.

  * static_routes : Static routes management.
    It is used to configure static routes.

  * vrrp : Virtual Router Redundancy Protocol implementation.

  * xrl : XRL (XORP Resource Locator) interface.

The directories listed below contain third-party contributed code which
is distributed with each XORP source release:

  * contrib : various contributed code.

    * olsr : RFC 3626 Optimized Link State Routing implementation.
      Generously funded by CenGen, Inc.

    * mld6igmp_lite : Implementation of the Lightweight IGMPv3/MLDv2
      protocols:
      - draft-ietf-mboned-lightweight-igmpv3-mldv2-02.txt

The directories listed below contain various information that are of
limited interest, or are not relevant to the current release:

  * config : autoconf/automake related files.

  * devnotes : various notes for the XORP core members.

  * utils : Various XORP-related utilities.


5. Future plans
===============

In the short-term we plan to add:
  * IS-IS
  * Security
  * Bi-directional PIM-SM

In the long-term, we plan to add:
  * BGMP


6. Authors
==========

The core team currently consists of:

  * Fred Bauer
  * Andrea Bittau
  * Javier Cardona
  * Atanu Ghosh
  * Adam Greenhalgh
  * Mark Handley
  * Orion Hodson
  * Eddie Kohler
  * Pavlin Radoslavov
  * Luigi Rizzo
  * Bruce M. Simpson
  * Marko Zec

7. Acknowledgments
==================

  * Sponsors (in chronological order, oldest first):
    - AT&T funding (through ICIR)
    - Intel Corporation
    - NSF grant (ANI-0129541).
      The following acknowledgment and disclaimer applies for the NSF
      support:
	This material is based upon work supported by the National
	Science Foundation under Grant No. 0129541.
	Any opinions, findings, and conclusions or recommendations
	expressed in this material are those of the author(s) and do not
	necessarily reflect the views of the National Science Foundation.
    - Microsoft
    - Vyatta
    - CenGen

  * Martin C. Shepherd for the libtecla library (used by the CLI).

8. Additional information
=========================

  * WWW: http://www.xorp.org/

  * Source code and CVS access: see XORP Web site.

  * XORP Bugzilla database and bug reports: see XORP Web site.

  * XORP users mailing list: xorp-users@xorp.org
    This list is for general XORP discussion.

    To subscribe, send email to xorp-users-request@xorp.org with
    the word "subscribe" (no quotes!) in the subject or the body
    of the email. For more subscription options, send the command
    "help" instead, or use the following URL:
    http://mailman.ICSI.Berkeley.edu/mailman/listinfo/xorp-users

  * XORP hackers mailing list: xorp-hackers@xorp.org
    This list is for XORP development discussion.

    To subscribe, send email to xorp-hackers-request@xorp.org with
    the word "subscribe" (no quotes!) in the subject or the body
    of the email. For more subscription options, send the command
    "help" instead, or use the following URL:
    http://mailman.ICSI.Berkeley.edu/mailman/listinfo/xorp-hackers

  * XORP announcements mailing list:  xorp-announce@xorp.org
    This list is for XORP release and milestone announcements.

    To subscribe, send email to xorp-announce-request@xorp.org with
    the word "subscribe" (no quotes!) in the subject or the body
    of the email. For more subscription options, send the command
    "help" instead, or use the following URL:
    http://mailman.ICSI.Berkeley.edu/mailman/listinfo/xorp-announce

  * Feedback: feedback@xorp.org
