#
# $XORP: xorp/ERRATA,v 1.43 2008/07/17 22:53:33 pavlin Exp $
#

		XORP ERRATA

  ALL:
    - Parallel building (e.g., "gmake -j 4") may fail on multi-CPU
      machines. The simplest work-around is to rerun gmake or not to use
      the -j flag.

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

    - If you run BGP, RIB, FIB2MRIB, and PIM-SM at the same time,
      the propagation latency for the BGP routes to reach the kernel
      is increased. We are investigating the problem.

  LIBXORP:
    - No known issues.

  LIBXIPC:
    - No known issues.

  LIBFEACLIENT:
    - No known issues.

  XRL:
    - No known issues.

  RTRMGR:
    - There are several known issues, but none of them is considered
      critical. The list of known issues is available from:

        http://www.xorp.org/bugzilla/query.cgi

    - Using the rtrmgr "-r" command-line option to restart processes
      that have failed does not work if a process fails while being
      reconfigured via xorpsh. If that happens, the rtrmgr itself may
      coredump. Therefore, using the "-r" command-line option is not
      recommended! Also, note that a process that has been killed by
      SIGTERM or SIGKILL will not be restarted (this is a feature rather
      than a bug). Ideally, we want to monitor the processes status
      using the finder rather than the forked children process status,
      therefore in the future when we have a more robust implementation
      the "-r" switch will be removed and will be enabled by default.

  XORPSH:
    - There are several known issues, but none of them is considered
      critical. The list of known issues is available from:

        http://www.xorp.org/bugzilla/query.cgi

  FEA/MFEA:
    - On Linux with kernel 2.6 (e.g., RedHat FC2 with kernel
      2.6.5-1.358), some of the tests may fail (with or without an error
      message), but no coredump image. Some of those failures can be
      contributed to a kernel problem. E.g., running "dmesg" can show
      kernel "Oops" messages like:

        Unable to handle kernel NULL pointer dereference at virtual
        address 00000000 printing eip:
        ...

      This appears to be a kernel bug triggered by ioctl(SIOCGIFNAME)
      which itself is called by if_indextoname(3). Currently, there 
      is no known solution, but it appears the problem may have been
      fixed for more recent Linux kernel versions:

        https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=121697

    - On Linux with kernel older than linux-2.6.15-rc7 there is a
      kernel bug that prevents the FEA to receive netlink(7) notifications
      about added/deleted IPv6 network addresses and routes:

        http://www.uwsg.indiana.edu/hypermail/linux/kernel/0512.2/2121.html

      Typically, this could be an issue only if someone is running
      IPv6 PIM-SM on Linux, and only if the unicast routes may be modified
      while XORP is running. In that case the fix would be to replace
      "RTMGRP_IPV6_IFADDR" with "(RTMGRP_IPV6_IFADDR >> 1)" inside
      fea/data_plane/ifconfig/ifconfig_observer_netlink_socket.cc, and to
      replace "RTMGRP_IPV6_ROUTE" with "(RTMGRP_IPV6_ROUTE >> 1)" inside
      fea/data_plane/fibconfig/fibconfig_entry_observer_netlink_socket.cc
      and fea/data_plane/fibconfig/fibconfig_table_observer_netlink_socket.cc

    - On Linux, adding and deleting multiple IPv4 addresses per interface
      may trigger an error: typically, if the primary IPv4 address
      is deleted, the kernel automatically deletes all secondary IPv4
      addresses on that interface. In Linux kernel 2.6.12 and later,
      enabling the new sysctl net.ipv4.conf.all.promote_secondaries
      (or one of the interface specific variants) can be used to
      automatically promote one of the secondary addresses to become
      the new primary address.

    - On Linux with kernel older than linux-2.6.17.11 there is a kernel
      bug related to modifying MAC addresses using the RTM_SETLINK
      netlink mechanism:
        http://www.spinics.net/lists/kernel/msg498873.html

      If it is not possible to update the kernel, the simplest
      work-around would be to replace "#ifdef RTM_SETLINK"
      with "#if 0" inside file
      fea/data_plane/ifconfig/ifconfig_set_netlink_socket.cc, method
      IfConfigSetNetlinkSocket::set_interface_mac_address().

    - The mechanism for tracking the network interface link status
      may not work for the following OS-es because the kernel for those
      systems does not provide a mechanism for asynchronous notification
      of userland programs when the link status changes: FreeBSD-5.2 and
      earlier and MacOS X (note: if the Windows kernel supports this
      feature, it is not used yet in XORP). Though, for those systems
      the link status should be read properly on startup.

    - On Linux with kernel version linux-2.6.17 and older there is a kernel
      bug which prevents adding an IPv6 address to an interface if the
      interface is DOWN:
        # ip link set eth1 down
        # ip addr add 3ffe:c00:0:0:1111:1111:1111:1111/64 dev eth1
        RTNETLINK answers: Network is down
        Exit 2

      As a result of that, XORP cannot be started with explicitly
      configured IPv6 addresses on an interface if that interface is DOWN.
      The problem has been fixed between linux-2.6.17 and linux-2.6.20.
      If updating to a newer Linux kernel is not feasible, a possible
      work-around is to explicitly set the interface status to UP before
      adding/configuring IPv6 addresses to it. 

    - On Linux systems up to year 2008 or so the following header files
      are not C++ friendly:
        <linux/netfilter_ipv4/ip_tables.h>
        <linux/netfilter_ipv6/ip6_tables.h>
      This prevents the compilation of the Linux Netfilter-based
      firewall support. See the following Bugzilla entry for details:
        https://bugzilla.netfilter.org/cgi-bin/bugzilla/show_bug.cgi?id=536

      To enable the Linux firewall compilation
      the following patches need should be applied to the above
      two files. Note that the patches are for Ubuntu Server-7.10,
      so they might need slight adjustment for other Linux distributions.
      After applying the patch rerun "./configure; gmake".

--- /usr/include/linux/netfilter_ipv4/ip_tables.h.org	2008-02-12 02:49:51.000000000 -0800
+++ /usr/include/linux/netfilter_ipv4/ip_tables.h	2008-04-19 22:09:22.000000000 -0700
@@ -217,7 +217,7 @@
 static __inline__ struct ipt_entry_target *
 ipt_get_target(struct ipt_entry *e)
 {
-	return (void *)e + e->target_offset;
+	return (struct ipt_entry_target *)((char *)e + e->target_offset);
 }
 
 /* fn returns 0 to continue iteration */
--- /usr/include/linux/netfilter_ipv6/ip6_tables.h.org	2008-02-12 02:49:51.000000000 -0800
+++ /usr/include/linux/netfilter_ipv6/ip6_tables.h	2008-04-25 16:43:05.000000000 -0700
@@ -271,7 +271,7 @@
 static __inline__ struct ip6t_entry_target *
 ip6t_get_target(struct ip6t_entry *e)
 {
-	return (void *)e + e->target_offset;
+	return (struct ip6t_entry_target *)((char *)e + e->target_offset);
 }
 
 /* fn returns 0 to continue iteration */

    - On Linux systems up to year 2008 or so a VLAN can be configured
      on a network interface only if the interface us UP.
      Eventually this limitation would be fixed in Linux kernel 2.6.28.

  RIB:
    - In some rare cases, the RIB may fail to delete an existing route:

        http://www.xorp.org/bugzilla/show_bug.cgi?id=62

      We are aware of the issue and will attempt to fix it in the
      future.

  RIP:
    - No known issues.

  OSPF:
    - Just before the XORP-1.4 release it was noticed that in OSPFv3
      LSAs with link-local scope could be flooded to links where they
      shouldn't be sent. We believe this shouldn't affect the routing
      computation, but it does introduce more LSAs than necessary.

    - There are several other known issues, but none of them is considered
      critical. The list of known issues is available from:

        http://www.xorp.org/bugzilla/query.cgi

  BGP:
    - The BGP configuration mandates that an IPv4 nexthop must be
      supplied. Unfortunately it is necessary to provide an IPv4 nexthop
      even for an IPv6 only peering. Even more unfortunately it is not
      possible to force the IPv6 nexthop.

    - It is *essential* for an IPv6 peering that an IPv6 nexthop is
      provided. Unfortunately the configuration does not enforce this
      requrement. This will be fixed in the future.

  STATIC_ROUTES:
    - No known issues.
      
  MLD/IGMP:
    - If MLD/IGMP is started on Linux with a relatively large number of
      interfaces (e.g., on the order of 10), then it may fail with the
      following error:

        [ 2004/06/14 12:58:56  ERROR test_pim:16548 MFEA +666
        mfea_proto_comm.cc join_multicast_group ] Cannot join group
        224.0.0.2 on vif eth8: No buffer space available

      The solution is to increase the multicast group membership limit.
      E.g., to increase the value from 20 (the default) to 200, run as a
      root:

        sysctl -w net.ipv4.igmp_max_memberships=200
      or
        echo 200 > /proc/sys/net/ipv4/igmp_max_memberships

      In addition, if the number of interfaces is notably larger (e.g.,
      on the order of 150), the maximum amount of socket option memory
      buffer should be increased as well. E.g., to increase the value from
      10240 (the default) to 200000, run as a root:

        sysctl -w net.core.optmem_max=200000
      or
        echo 200000 > /proc/sys/net/core/optmem_max

      Also, see the PIM-SM instructions for increasing other system
      limits when the number of interfaces is relatively large.

  PIM-SM:
    - If the kernel does not support PIM-SM, or if PIM-SM is not enabled
      in the kernel, then running PIM-SM will fail with the following
      error message:

        [ 2004/06/12 10:26:41  ERROR xorp_fea:444 MFEA +529 mfea_mrouter.cc
        start_mrt ] setsockopt(MRT_INIT, 1) failed: Operation not supported

    - On Linux, if the unicast Reverse Path Forwarding information is
      different from the multicast Reverse Path Forwarding information,
      the Reverse Path Filtering should be disabled. E.g., as root:

        echo 0 > /proc/sys/net/ipv4/conf/all/rp_filter

      OR

        echo 0 > /proc/sys/net/ipv4/conf/eth0/rp_filter
        echo 0 > /proc/sys/net/ipv4/conf/eth1/rp_filter
        ...

      Otherwise, the router will ignore packets if they don't arrive on
      the reverse-path interface. For more information about Reverse
      Path Filtering see:

        http://www.tldp.org/HOWTO/Adv-Routing-HOWTO/lartc.kernel.rpf.html

    - Currently, the PIM-SM implementation does not support unnumbered
      point-to-point links. Furthermore, even on numbered point-to-point
      links the next-hop information in the routing entries should use
      an IP address instead of an interface name. For example,
      if there is a GRE tunnel on Linux, then use the following command
      to add a route that uses that tunnel:

        route add -net <target> gw <IP address of other side of GRE tunnel>

      instead of:

        route add -net <target> <GRE interface name>

    - If PIM-SM is configured to run over a large number of interfaces
      (e.g., more than 31 VLANs), it might fail with the following error:

      [ 2006/07/04 11:56:23  ERROR xorp_fea:28353 MFEA +967 mfea_mrouter.cc
      add_multicast_vif ]
      setsockopt(MRT_ADD_VIF, vif eth0.4) failed: Too many open files in system

      The reason for that error is that by default majority of the UNIX
      kernels cannot support more than 32 interfaces enabled for multicast
      forwarding (one interface is always used as the internal PIM Register
      virtual interface).

      The solution is to increase the MAXVIFS limit in the kernel
      (typically defined in the "netinet/ip_mroute.h" (BSD) or the
      "include/linux/mroute.h" (Linux) kernel file), and recompile the
      kernel. It should be increased also in the corresponding system
      header file as well: <netinet/ip_mroute.h> or <linux/mroute.h>.
      After that XORP should be recompiled to take into account the
      MAXVIFS increase. If modifying the system header files is not
      acceptable, then the following should be added toward the end of
      file "xorp/mrt/max_vifs.h" before recompiling XORP:

      #undef MAX_VIFS
      #define MAX_VIFS 50

      Also, see the MLD/IGMP instructions for increasing other system
      limits when the number of interfaces is relatively large.

  FIB2MRIB:
    - No known issues.

  CLI:
    - No known issues.

  SNMP:
    - On some versions of Linux, there are some bugs in net-snmp
      versions 5.0.8 and 5.0.9, which prevent dynamic loading from
      working. See the following URL for links to the net-snmp
      patches that solve the problems:

        http://www.xorp.org/snmp.html

    - Version 5.1 of net-snmp requires a simple modification, otherwise
      XORP will fail to compile.
      See the following URL for a link to the net-snmp patch that solves
      the problems:

         http://www.xorp.org/snmp.html 

    - There might be a compilation error in the mibs directory on some
      systems running on 64-bit machines (e.g., FreeBSD-6.x or FreeBSD-7.x on
      amd64):

g++ -shared   xorpevents.lo -Wl,--whole-archive ../libxipc/.libs/libxipc.a ../libxorp/.libs/libxorp.a ../libcomm/.libs/libcomm.a -Wl,--no-whole-archive  ../libxipc/.libs/libxipc.a ../libxorp/.libs/libxorp.a ../libcomm/.libs/libcomm.a -lcrypto  -Wl,-soname -Wl,libnetsnmpxorp.so -o .libs/libnetsnmpxorp.so
/usr/bin/ld: ../libxipc/.libs/libxipc.a(hmac_md5.o): relocation R_X86_64_32S can not be used when making a shared object; recompile with -fPIC
../libxipc/.libs/libxipc.a(hmac_md5.o): could not read symbols: Bad value
gmake[1]: *** [libnetsnmpxorp.la] Error 1

     In that case use the "--enable-shared" flag to "./configure", and
     remove the previous compilation:

       ./configure --with-snmp --enable-shared
       gmake clean
       gmake
