
	Build Notes for XORP (eXtensible Open Router Platform)


0. Preface
==========

XORP builds on Linux and BSD variants that support the 'scons' build
system and GNU g++ compiler toolset.  Please ask on the xorp-hackers
mailing list if your preferred system is not currently supported.

1. Compilation
==============

1.1 Compiling the binaries
==========================

To compile XORP, you must have SCons installed. Then just
run the following commands in the top-level directory:

scons
scons install

To change the default C and C++ compilers, then assign the binary
names to the CC and CXX user environmental variables respectively.
E.g., if you want to use the gcc34/g++34 compilers, then use (in case
of csh/tcsh) the following commands before running "scons":

setenv CC gcc34
setenv CXX g++34

To compile XORP with additional user-specified compiler flags, assign
those flags to the CFLAGS and CXXFLAGS environmental variables (for the
C and C++ compiler respectively) before running "scons".

For various compile options use:  scons --help


1.2 Generating documentation
============================

The documentation for each XORP release is available from the XORP Web
site. The following procedure can be used to generate the
documentation directly from the source files.

The documentation is now in a separate area of the XORP SVN repository,
and is no longer part of the source tree itself.

1.2.1. Install TeX and LaTeX

  * FreeBSD
    cd /usr/ports/print/teTeX
    make
    make install
    # Optionally install the Prosper LaTeX class:
    cd /usr/ports/textproc/prosper
    make
    make install

  * Ubuntu Linux
    apt-get install texlive
    apt-get install texlive-latex-extra
    apt-get install texlive-math-extra

1.2.2. Compile the documentation.

# Note that this must be done directly in the XORP docs directory with the
# original source files.
cd /path/to/xorp/docs
scons

2. Internal tests
=================

As of September 2009, not all of the regression tests are active in
the public SVN tree.

To run the internal tests, you must have "bash" and "python" installed.
Note that if the python's executable filename is not "python", then
you would have to create a symbolic link with such name. E.g., execute
as a root:

cd /path/to/python/binary
ln -s python2.4 python

After the code is compiled, you need to run the following command
in the top-level XORP directory:

scons check


3. OS-specific notes
====================

3.1. DragonFlyBSD
=================

  * DragonFlyBSD-1.4
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 3.4.5 20050809 (prerelease) [DragonFly] (propolice, visibility)

  * DragonFlyBSD-1.6
    - The following system header file has a bug (it uses the C++ keyword
      "new" for the name of a variable):
        /usr/include/machine/atomic.h

      The following patch must be applied to that file before compiling XORP:
      http://www.dragonflybsd.org/cvsweb/src/sys/i386/include/atomic.h.diff?r1=1.20.2.1&r2=1.20.2.2

    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 3.4.5 20050809 (prerelease) [DragonFly] (propolice, visibility)

  * DragonFlyBSD-1.8
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 3.4.6 [DragonFly] (propolice, visibility)

  * DragonFlyBSD-1.10.1
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 3.4.6 [DragonFly] (propolice, visibility)

  * DragonFlyBSD-1.12.2
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 4.1.2 (DragonFly)

3.2. FreeBSD
============

  * FreeBSD-4.5, FreeBSD-4.6.2, FreeBSD-4.6-RELEASE, FreeBSD-4.8-RELEASE:
    - Earlier XORP releases have been developed and tested on those
      platforms.

  * FreeBSD-4.9-RELEASE and FreeBSD-4.10-RELEASE:
    - No known issues.
    - The code should compile with the following versions of the
      gcc/g++ compiler: 2.95.4 (default), 3.3.4,
      3.4.2 20040827 (prerelease), and 3.4.6.

  * FreeBSD-5.1:
    - The default gcc/g++ compiler (version 3.2.2) has a bug, hence
      you must install a new compiler (e.g., gcc-3.3 from
      /usr/ports/lang/gcc33 in the ports collection). Then, you must
      set environmental variables CC and CXX to point to the new compiler
      before running "./configure"
      (e.g., "setenv CC gcc33; setenv CXX g++33").
    - The code compiles with the new compiler, and the internal tests
      appear to succeed.

  * FreeBSD-5.2, FreeBSD-5.3, FreeBSD-5.4
    - The code compiles with the default compiler, and the internal tests
      appear to succeed.

  * FreeBSD-6.0 on i386
    - No known issues.

  * FreeBSD-6.0 on amd64
    - Multicast routing doesn't work because of a broken "struct igmpmsg"
      definition inside <netinet/ip_mroute.h>.
      The fix (already in FreeBSD-6.1) is to replace
      u_long with uint32_t inside the body of "struct igmpmsg", and
      then recompile both the FreeBSD kernel and XORP.
    - The SNMP support inside the "mibs" directory fails to compile.
    - The rest of code compiles with the default compiler, and the internal
      tests appear to succeed:
      gcc (GCC) 3.4.4 [FreeBSD] 20050518

  * The following compiler is known to be buggy, and should not be used
    to compile XORP:
    - gcc34 (GCC) 3.4.0 20040310 (prerelease) [FreeBSD]
    A newer compiler such as the following should be used instead:
    - gcc34 (GCC) 3.4.2 20040827 (prerelease) [FreeBSD]

  * FreeBSD-6.1 on i386
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 3.4.4 [FreeBSD] 20050518

  * FreeBSD-6.1 on amd64
    - The SNMP support inside the "mibs" directory can be compiled only
      if the "--enable-shared" flag is used when running "./configure":
      ./configure --with-snmp --enable-shared
    - The rest of code compiles with the following compilers, and the internal
      tests appear to succeed:
      gcc (GCC) 3.4.4 [FreeBSD] 20050518 (default)
      gcc42 (GCC) 4.2.0 20060218 (experimental)
      gcc43 (GCC) 4.3.0 20070223 (experimental)

  * FreeBSD-6.2 on i386
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 3.4.6 [FreeBSD] 20060305

  * FreeBSD-7.0 on i386 and amd64
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 4.2.1 20070719  [FreeBSD]

3.3. NetBSD
===========

  * NetBSD-2.0, NetBSD-3.0, NetBSD-3.0.1, and NetBSD-3.1
    - The SNMP support inside the "mibs" directory may fail to compile.
    - The rest of code compiles, and the internal tests appear to succeed:
      gcc (GCC) 3.3.3 (NetBSD nb3 20040520)
    - If the compilation fails with the following error:
      "/usr/pkg/bin/bash: Undefined PLT symbol "read" (reloc type = 7, symnum = 92)"
      then just run "gmake" again, and the compilation should continue from
      the point it has failed.
    - The default datasize limit per user may not be sufficient to compile
      some parts of the code, hence you may need to increase the datasize
      limit.  If you see a compilation error like:
	  ld: final link failed: Memory exhausted
      then you should increase the data size limit by
      "limit datasize 200000" in csh/tcsh or "ulimit -d 200000" in sh.
      If necessary, increase further the datasize limit.
    - The default limit of maximum opened file descriptors per process
      is 64 which may not be sufficient. If you run a XORP program and
      there are errors like:

	  [ 2004/06/20 22:26:09  ERROR test_pim:31634 LIBCOMM +582 comm_sock.c comm_sock_accept ] Error accepting socket 4: Too many open files

      then you should increase the file descriptors limit by
      "limit descriptors 400" in csh/tcsh or "ulimit -n 400" in sh.

  * NetBSD-4.0
    - The code compiles with the default compiler, and the internal tests
      appear to succeed:
      gcc (GCC) 4.1.2 20061021 prerelease (NetBSD nb3 20061125)

3.4. OpenBSD
============

  * If the system would be used as a multicast router, then add the
    following lines to /etc/rc.conf.local and reboot:

    # Enable multicast routing (see netstart(8) for details).
    multicast_host=NO
    multicast_router=YES

    Note that OpenBSD-3.7 is the first release that has PIM multicast routing
    support in the kernel.

  * OpenBSD-3.5:
    - The default gcc/g++ compiler (version 2.95.x) has a bug, hence
      you must install a new compiler (e.g., gcc-3.3.2 and g++-3.3.2 from
      packages). Then, you must set environmental variables CC and CXX
      to point to the new compiler before running "./configure"
      (e.g., "setenv CC egcc; setenv CXX eg++").
    - The code compiles with the new compiler, but some of the internal
      tests fail.
    - The default datasize limit per user may not be sufficient to compile
      some parts of the code, hence you may need to increase the datasize
      limit.  If you see a compilation error like:
	  /usr/bin/ld: final link failed: Memory exhausted
	  collect2: ld returned 1 exit status
      then you should increase the data size limit by
      "limit datasize 200000" in csh/tcsh or "ulimit -d 200000" in sh.
      If necessary, increase further the datasize limit.
    - The default limit of maximum opened file descriptors per process
      is 64 which may not be sufficient. If you run a XORP program and
      there are errors like:

	  [ 2004/06/20 22:26:09  ERROR test_pim:31634 LIBCOMM +582 comm_sock.c comm_sock_accept ] Error accepting socket 4: Too many open files

      then you should increase the file descriptors limit by
      "limit descriptors 400" in csh/tcsh or "ulimit -n 400" in sh.

  * OpenBSD-3.6-current (as of February 2005) on i386 and amd64,
    OpenBSD-3.8, OpenBSD-3.9, OpenBSD-4.0, OpenBSD-4.1, OpenBSD-4.2,
    OpenBSD-4.3, OpenBSD-4.4
    - The default gcc/g++ compiler (version 3.3.5 (propolice)) has a bug
      in the propolice implementation:
          http://www.monkey.org/openbsd/archive2/tech/200503/msg00011.html
      Hence, you must disable the propolice feature. You need to add the
      "-fno-stack-protector" flag to your CFLAGS and CXXFLAGS
      environmental variables. E.g. (in csh/tcsh): 
	  setenv CFLAGS -fno-stack-protector
	  setenv CXXFLAGS -fno-stack-protector
	  ./configure
    - The code compiles, and the internal tests appear to succeed.
      Multicast routing seems to work.
    - The default datasize limit per user may not be sufficient to compile
      some parts of the code, hence you may need to increase the datasize
      limit.  If you see a compilation error like:
	  collect2: ld terminated with signal 11 [Segmentation fault], core dumped
      then you should increase the data size limit by
      "limit datasize 200000" in csh/tcsh or "ulimit -d 200000" in sh.
      If necessary, increase further the datasize limit.
    - The default limit of maximum opened file descriptors per process
    - The default limit of maximum opened file descriptors per process
      is 64 (increased to 128 in OpenBSD-4.2) which may not be
      sufficient. If you run a XORP program and there are errors like:

	  [ 2004/06/20 22:26:09  ERROR test_pim:31634 LIBCOMM +582 comm_sock.c comm_sock_accept ] Error accepting socket 4: Too many open files

      then you should increase the file descriptors limit by
      "limit descriptors 400" in csh/tcsh or "ulimit -n 400" in sh.

3.5. Linux
==========

  * It is difficult to get distributions older than Fedora Core 5
    to compile XORP 1.7, primarily due to scons and python dependencies.

  * Linux Red Hat Enterprise Linux Server release 5 (Tikanga)
    (kernel 2.6.18-8.el5)
    - Optionally install the following packages:
      - libpcap-devel (e.g., libpcap-devel.x86_64)
        This package is needed for sending/receiving link layer data frames.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.1 20070105 (Red Hat 4.1.1-52)
    - Tested on the following architectures: x86_64 (amd64)

  * Linux Fedora Core5 (2.6.16-1.2080_FC5smp):
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.0 20060304 (Red Hat 4.1.0-3)

  * Linux Fedora Core6 (2.6.18-1.2798.fc6PAE):
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.1 20061011 (Red Hat 4.1.1-30)

  * Linux Fedora 7 (2.6.21-1.3194.fc7):
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.2 20070502 (Red Hat 4.1.2-12)

  * Linux Fedora 8 (2.6.21-2950.fc8xen):
    - Optionally install the following packages:
      - libpcap-dev
        This package is needed for sending/receiving link layer data frames.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.2 20070925 (Red Hat 4.1.2-33)

  * Linux Fedora 9 (2.6.25-14.fc9.i686):
    - Optionally install the following packages:
      - libpcap-devel
        This package is needed for sending/receiving link layer data frames.
    - gcc (GCC) 4.3.0 20080428 (Red Hat 4.3.0-8)

  * Linux Fedora 10 (2.6.27.5-117.fc10.i686):
    - Optionally install the following packages:
      - libpcap-devel
        This package is needed for sending/receiving link layer data frames.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.3.2 20081105 (Red Hat 4.3.2-7)

  * Linux CentOS 5.2 (2.6.18-92.el5):
    - You must install the following packages:
      - gcc
      - gcc-c++
      - openssl-devel
    - Optionally install the following packages:
      - libpcap-devel
        This package is needed for sending/receiving link layer data frames.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.2 20071124 (Red Hat 4.1.2-42)

  * Linux Debian-3.1 (sarge) (2.4.27-3-386):
    - You must install the following packages:
      - libssl (e.g., libssl0.9.7)
      - libssl-dev
      - gcc (e.g., gcc-3.3)
      - g++ (e.g., g++-3.3)
    - The binaries for the GCC C and C++ compilers might not be called
      gcc/g++, but gcc-3.3 and g++-3.3.
      Either create a link from gcc to gcc-3.3 and from g++ to g++-3.3,
      or set the CC and CXX environments to point to the binary names.
      E.g., in csh/tcsh: setenv CC gcc-3.3; setenv CXX g++-3.3
    - The code compiles, and the internal tests appear to succeed.
    - gcc-3.3 (GCC) 3.3.5 (Debian 1:3.3.5-13)

  * Linux Debian-4.0 (etch) (2.6.18-5-486):
    - Optionally install the following packages:
      - libpcap0.8-dev
        This package is needed for sending/receiving link layer data frames.
    - The binaries for the GCC C and C++ compilers might not be called
      gcc/g++, but gcc-4.1 and g++-4.1.
      Either create a link from gcc to gcc-4.1 and from g++ to g++-4.1,
      or set the CC and CXX environments to point to the binary names.
      E.g., in csh/tcsh: setenv CC gcc-4.1; setenv CXX g++-4.1
    - The code compiles, and the internal tests appear to succeed.
    - gcc-4.1 (GCC) 4.1.1-15 (Debian 4:4.1.1-15)
    - gcc-4.1 (GCC) 4.1.3 20070812 (prerelease) (Debian 4.1.2-15)

  * Linux Debian-5.0 (lenny, unreleased) (2.6.25-2-686 and 2.6.26-1-686):
    - You must install the following packages:
      - gcc (e.g., gcc-4.3)
      - g++ (e.g., g++-4.3)
      - libssl-dev
    - Optionally install the following packages:
      - libpcap-dev
        This package is needed for sending/receiving link layer data frames.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (Debian 4.3.1-2) 4.3.1
    - Tested on the following architectures: i386

  * Linux Gentoo 2006.1:
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.1 (Gentoo 4.1.1-r3)

  * Linux Gentoo 2007.0 with hardened profile:
    - The following hardened compiler has some issues (correct C++ programs
      might coredump), and should not be used:
        g++ (GCC) 3.4.6 (Gentoo Hardened 3.4.6-r2, ssp-3.4.6-1.0, pie-8.7.10)
      The solution is to use gcc-config and switch to a gcc profile that
      disables ssp, e.g., the "hardenednossp" profile.

  * Linux Gentoo 2008.0 (kernel 2.6.24-gentoo-r7):
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.2 (Gentoo 4.1.2 p1.1)

  * Linux Ubuntu-7.04 (Server Edition, kernel 2.6.20-15-server):
    - You must install the following packages:
      - libssl-dev (e.g., version 0.9.8c-4build1)
      - gcc (e.g., gcc-4.1)
      - g++ (e.g., g++-4.1)
    - Optionally install the following packages:
      - libpcap0.8-dev
        This package is needed for sending/receiving link layer data frames.
      - snmpd and libsnmp-dev
        Those packages are needed for SNMP support.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.1.2 (Ubuntu 4.1.2-0ubuntu4)
    - Tested on the following architectures: i386, sparc64

  * Linux Ubuntu-7.10 (Server Edition, kernel 2.6.22-14-server):
    - You must install the following packages:
      - libssl-dev (e.g., version 0.9.8e-5ubuntu3.1)
      - gcc (e.g., gcc-4.1)
      - g++ (e.g., g++-4.1)
    - Optionally install the following packages:
      - libpcap0.8-dev
        This package is needed for sending/receiving link layer data frames.
      - iptables-dev
        This package is needed for configuring firewall rules using XORP.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.2.3 (Ubuntu 4.2.3-2ubuntu7)
    - Tested on the following architectures: i386, amd64

  * Linux Ubuntu-8.04.1 (Server Edition, kernel 2.6.24-19-server):
    - You must install the following packages:
      - libssl-dev (e.g., version 0.9.8g-4ubuntu3.3)
      - gcc (e.g., gcc-4.2)
      - g++ (e.g., g++-4.2)
    - Optionally install the following packages:
      - libpcap0.8-dev
        This package is needed for sending/receiving link layer data frames.
      - iptables-dev
        This package is needed for configuring firewall rules using XORP.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.2.3 (Ubuntu 4.2.3-2ubuntu7)
    - Tested on the following architectures: i386

  * Linux Ubuntu-8.10 (Server Edition, kernel 2.6.27-7-server):
    - You must install the following packages:
      - libssl-dev (e.g., 0.9.8g-10.1ubuntu2)
      - gcc (e.g., gcc-4.3)
      - g++ (e.g., g++-4.3)
    - Optionally install the following packages:
      - libpcap0.8-dev
        This package is needed for sending/receiving link layer data frames.
      - iptables-dev
        This package is needed for configuring firewall rules using XORP.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (GCC) 4.3.2 (Ubuntu 4.3.2-1ubuntu11)
    - Tested on the following architectures: i386

  * Linux openSUSE 11.0 (2.6.25.11-0.1-default):
    - You must install the following packages:
      - gcc
      - g++
      - libopenssl-devel
    - Optionally install the following packages:
      - libpcap-devel
        This package is needed for sending/receiving link layer data frames.
    - The code compiles, and the internal tests appear to succeed.
    - gcc (SUSE Linux) 4.3.1 20080507 (prerelease) [gcc-4_3-branch revision 135036]

  * There is a known problem with building XORP on Linux with gcc-4.0.x
    and optimization enabled. It is a bug in gcc, see XORP Bugzilla #435
    for details:
        http://www.xorp.org/bugzilla/show_bug.cgi?id=435
    A simple work-around is not to enable compiler's optimization, or
    just to upgrade to a newer compiler (4.1.x or later).

  * There is a known problem with building XORP on Linux with gcc-3.3
    or gcc-3.4 and post-2.15 binutils.
    It is a bug in gcc, see XORP Bugzilla #497 for details:
        http://www.xorp.org/bugzilla/show_bug.cgi?id=497
    Newer versions of the gcc compiler (e.g., gcc-4.0.2 or gcc-4.1) should
    be used instead.

  * Intel C/C++ compiler 9.x can be used to compile XORP on Linux
    platform.

3.6. Mac OS X
=============
  * NOTE:  I have no idea if XORP 1.7 on Mac OS X compiles at all. --Ben

  * All:
    - Unicast routing appears to work.
    - Multicast routing doesn't work, because the kernel doesn't have
      the appropriate support.

  * OS X 10.3.8 (Darwin 7.8.0):
    - gcc version 3.3 20030304 (Apple Computer, Inc. build 1495)
    - The code compiles, and the internal tests appear to succeed.

  * OS X 10.4.2 - 10.4.9 (Darwin 8.2.0 - 8.9.0) on PowerPC:
    - gcc version 4.0.0 20041026 (Apple Computer, Inc. build 4061)
    - The code compiles, and the internal tests appear to succeed.

  * OS X 10.4.5 (Darwin 8.5.3) on i386:
    - gcc version 4.0.1 (Apple Computer, Inc. build 5250)
    - The code compiles, and the internal tests appear to succeed.

  * OS X 10.5.2 (Darwin 9.2.2), OS X 10.5.3 (Darwin 9.3.0),
    OS X 10.5.4 (Darwin 9.4.0) on i386:
    - gcc version 4.0.1 (Apple Computer, Inc. build 5465)
    - The code compiles, and the internal tests appear to succeed.

3.7 Microsoft Windows
=====================
  * Not supported any longer.

3.8. Cross-compilation
======================
  * Not supported at this time, but may not be difficult to enable.

4. Performance optimization
===========================

By default, XORP is compiled with compiler debug information enabled
and moderate optimization.

See 'scons --help' for more options.


5. Setting-up Ubuntu for XORP Installation
==========================================

[ This section is at least partially out-dated. ]

1)Install Ubuntu from Live CD - all default values hold good.
2)Add your login name to the sudoers file
3)Edit interfaces file
a.sudo vim /etc/network/interfaces
b.Edit the config for eth0 and other required interfaces, remove dhcp
configuration.

Example eth0 configuration:

Remove the following eth0 config, if present:
auto eth0
iface eth0 inet dhcp
Key-in the following config.
auto eth0
iface eth0 inet static
	address 10.10.10.50 ---  specify interface ip address
	netmask 255.255.255.0 --- specify subnet mask
	network 10.10.10.0  --- specify network
	broadcast 10.10.10.255 --- specify broadcast address
	gateway 10.10.10.1 ---  specify default gateway
		Repeat for the other interfaces if necessary.

4)sudo /etc/init.d/networking restart
5)Create a group called "xorp" - Mandatory to run xorp.
addgroup xorp
6)Add yourself to the group "xorp". This is mandatory to run xorpsh.
adduser  <username> xorp
7)Relogin/Reboot the system to take these permission changes into effect.
8)sudo apt-get update
9)sudo apt-get remove dhcp-client
10)sudo apt-get install openssh-server openssh-client
11)sudo apt-get install make
12)sudo apt-get install gcc
13)sudo apt-get install g++
14)sudo apt-get install openssl
15)sudo apt-get install cvs - To access xorpcvs
16)sudo apt-get install traceroute - To get rid of the warning when xorpsh
is installed.
17)sudo apt-get install libssl-dev
18)sudo apt-get install libpcap0.8-dev [optional]
19)sudo apt-get install snmpd [optional, but necessary if snmp compilation
is enabled via configure script]
20)sudo apt-get install libsnmp-dev [optional, but necessary if snmp
compilation is enabled via configure script]
21)sudo apt-get install iptables-dev
22)sudo apt-get install tcpdump [optional - to help in debugging]
23)sudo apt-get install wireshart [optional - to help in debugging]
24)sudo apt-get install tclsh [optional - to enable TCL scripting]
25)sudo apt-get install expect [optional]


6. Known problems
=================

See file ${XORP}/ERRATA.
