#
# Copyright (c) 1996 The Regents of the University of Michigan
# All Rights Reserved
#

Installing GateD R3_6

NOTE: THE POSTSCRIPT FILE doc/tex/gated.ps CONTAINS A MORE UP-TO-DATE
AND DETAILLED DOCUMENTATION ABOUT THE INSTALLATION AND OPERATION OF
GATED. YOU ARE STRONGLY SUGGESTED TO READ IT FIRST.

The GateD makefile system is setup to allow object directories for
multiple architectures to use one source tree.  The object directories
consist of a few configured files and symlinks for the majority of the
GateD files.  They are named obj.<arch> where <arch> is related
to architecture of your system. As for the 3.6 gated version, a new
autoconfiguration process is provided. This feature is available
on a restricted set of architecture, and you may need to use the
old (before verison 3.6) gated installation procedures.

------------------------------------------------------------------------
Auto-configuration
------------------------------------------------------------------------

	This process is supported on the following system: SunOS4.1.x,
SunOS5.x, BSD/OS, Ultrix4.x. For other system you may want to use
the old manual procedures.

	- Change the current directory to the source (src)
	directory:

	cd src

	- Start the auto configuration program:

	make autoconf

	- Answer all the questions. When done, compile gated:

	make

	- Then install gated:

	make install

	- And clean up the mess:

	make clean

	For those interested in the details of the process, the
postscript document doc/tex/gated.ps explains the diferent stages of
the configuration process. To sum up, 'make autoconf' will create the
object directory. The name is obj.<arch> where <arch> is the output of
the command 'util/configure -a'. In this object directory a Config file
is created with all the options/parameters needed.

	One can modify this Config to change some options. After doing
that a 'make config' is needed to uptdate certain files in the object
directory.

	'make autoconf' will also look at a file named Config in the
source (src) directory. This file must be used to store user
preferences that are not asked by the make autoconf process. For
instance, make autoconf will chose  the GNU gcc compiler over cc. If
one want to force the use of cc the src/Config file should contain this
single line:

cc      gcc

	The final src/obj.<arch>/Config file is a combination of the
src/Config file and some system-generic ones in src/configs. Those
files should not be edited by the user.

------------------------------------------------------------------------
Manual configuration
------------------------------------------------------------------------

	This is the usual process for any Gated distribution prior
to version 3.7. If you want to use this process on the 3.7 or later
distributions you first need to replace the generic Makefile in the
source directory:

cd src
cp Makefile.org Makefile

	and then follow the instructions:

- Create an object directory,
     src/obj.`src/util/archtype`.  Run
     src/util/archtype directly to display the
     architecture.  If you will never compile GateD on a second
     architecture you can use obj.  For example, on a Sun
     SPARCstation running SunOS 4.1.1:

sun% src/util/archtype
SunOS-4.1.1-sun4
sun% mkdir src/obj.`src/util/archtype`
sun% ls -d src/obj.*
src/obj.SunOS-4.1.1-sun4/

     On BSD 4.3 Reno and later obj directories are supported
     in the format the system sources use.  This support is not
     direct, but a hack.  On these systems you will need to specify
     the full path to some directories, for an example see
     src/configs/vangogh.

- Build a config file.  This file is used as input to a
     configuration script which builds a Makefile and system specific
     header files.

     A description of config file options is available in
     src/configs/README.

     Examples of quite a few config files are in
     src/configs, pick the one that is closest to what
     you want and tailor it to your specific configuration.  Install
     this config file in the previously created object directory with
     the name Config.

- Configure GateD for this architecture by typing 'make
     config'.  This will run an awk script on your
     obj.`src/util/archtype`/Config file which builds a
     sed script.  This sed script is used to edit a Makefile template.
     The Makefile is then run to configure architecture specific
     files, create symbolic links, and dependencies. make config
     must be run in the src directory.

- Build GateD by typing 'make' in the src directory or
     the object directory.

- Become root and install GateD: 'make install' in the
     src or object directory.  Then optionally type make
     install-man in the same directory to install the man
     pages.
	   
- Make up a configuration file.  Sample config files are in the
     conf directory and the man page explains all config options.
     Install the config file in /etc/gated.conf.

- Take cover and .... FIRE IT UP!

------------------------------------------------------------------------
Notes
------------------------------------------------------------------------

UDP Checksums

     RIP will refuse to run if it determines that UDP checksums are
     disabled in the kernel.  Running without UDP checksums can lead
     to incorrect routing information being propagated, especially on
     serial links.  This check does not help you determine if RIP
     packets you receive are missing a checksum, but at least it
     prevents you from generating these packets and calls attention to
     the problem.

     There are two ways to enable UDP checksums.  Your operating system
     may provide enough source to enable checksums by default.  SunOS
     provides this in /sys/netinet/in_proto.c. Update the source and
     recompile the kernel.

     If your operating system does not provide the relevent source,
     you can patch the running kernel and disk image with a sequence
     similar to this (as root): 

sun# adb -k -w /vmunix /dev/mem
_udp_cksum/W 1
_udp_cksum:     0x0             =       0x1
_udp_cksum?W 1
_udp_cksum:     0x0             =       0x1
^D
sun#

     You can probably find the proper name for the UDP checksum value with:

sun# nm -o /vmunix | grep udp_c
/vmunix:f80fa35c D _udp_cksum
/vmunix:f801bd10 T _udp_ctlinput
sun#
	
IP Multicast support

     The OSPF and RIP implementations (and in the future hopefully
     Router Discovery) make use of IP multicasting facilities.  If
     these facilities are not present, functionality is reduced.

     Some systems ship with IP multicasting support, namely BSDI's
     BSD/386 1.0, Sun's Solaris 2.0 and Silicon Graphics' IRIX.
     For other systems, IP multicasting support may be available (for
     example SunOS 4.1.* and some versions of Ultrix), check the FTP
     directories on ftp://gregorio.stanford.edu/vmtp-ip,
     gregorio.stanford.edu, ftp://parcftp.xerox.com and
     ftp://ftp.isi.edu/mbone".

     RIP-II and OSPF specify the use of IP multicast on P2P
     interfaces.  Due to bugs in most implementations of the IP
     multicast code GateD will not be able to specify it's use on
     these interfaces.  GateD will automatically fall back to using
     the destination address of the P2P link.  In the OSPF case, no
     functionality will be lost, but in the RIP-II case you will loose
     the ability to pass arbitrary subnet masks via these interfaces.
     
     Another bug in IP multicast support causes multicast packets to
     local-wire groups to fail if there is not a default route for IP,
     multicast, or the specific group.  As a workaround, GateD
     installs a route for any local-wire multicast group it
     uses via the loopback interface.  This default is not actually
     used, but it avoids a kernel bug sending to these groups.

IP Multicast Routing support

     Gated now includes support for multicast routing protocols. It
     implements the router portion of the IGMP protocol to determine
     local group membership information. It currently supports
     PIM (Dense Mode) and Distance Vector Multicast Routing Protocol
     (DVMRP). It tries to be compatible with the 3.3 and 3.5
     releases of the IP Multicast distribution from Xerox Parc.

     Gated can be configured to use one of three different multicast
     kernel models. These are distinguished by how multicast
     forwarding table entries are placed in the kernel.

     - KRT_IPMULTI_NOCACHE
       This model does not provide a protocol independent multicast forwarding
       cache in the kernel. Therefore, it is not possible to use this type
       of kernel for IP Multicast Routing with Gated. This includes all
       releases of the IP Multicast software from Xerox PARC and Stanford
       University with versions 1.x and 2.x. If your kernel falls in
       this category, then unfortunately, you cannot use Gated for
       IP Multicast routing.
  
     - KRT_IPMULTI_RTSOCK
       Because of the DVMRP dependencies in the 1.x and 2.x releases, a
       new kernel was designed by some of the Gated developers that would
       be completely protocol independent. The design assumed that certain
       features typical of BSD 4.3 reno and later systems (including the
       routing socket) would be present. When a multicast datagram arrives
       for a Group,Source pair and no forwarding cache entry exists in
       the kernel, a request is put on the routing socket to resolve
       the Group,Source. The routing daemon (who listens on the routing
       socket) will see the request and generate a forwarding cache entry
       to be installed in the kernel.
      
       Another goal of the new kernel was to eliminate the use of
       Virtual Interfaces (or Vifs). Instead, pseudo tunnel interfaces
       with their own ifnet structures were implemented. This made the
       software much simpler since a tunnel interface appeared to be
       just like and other point to point interface in the router.

       The implementation also takes advantage of the radix tree that
       exists in BSD 4.3 Reno systems and later. The Group,Source pairs
       are installed as a single key in the radix tree as opposed to
       the more traditional hashing table found in BSD 4.3 systems.  A
       copy of the source patches to this kernel that is applicable to
       most BSD 4.4 Lite systems is available from
       ftp://ftp.gated.cornell.edu/pub/multicast

       Note: Not yet implemented.

     - KRT_IPMULTI_TTL0
       With this model, the kernel also acts as a protocol independent
       multicast forwarding cache. Forwarding cache entries are
       generate on demand as data traffic is forwarded. It uses
       messages on the IGMP socket to communicate with the
       routing daemon and request that a forwarding cache entry
       be calculated. Examples of the use of this model include
       the Xerox PARC IP Multicast 3.3 and 3.5 kernel releases.

Running GateD on SunOS 4.0 systems

     If GateD gets sendto() network unreachable problems when running
     on SunOS 4.0 systems, add `hostname` to the ifconfig commands for
     ie0/le0/ec0 in /etc/rc.local.  Otherwise SunOS has a misconception
     of the route to the attached network.

     In an attempt to make binaries that read kernel memory compatible
     between different kernel architectures, Sun has created libkvm.a.
     Unfortunately, the dynamically loaded versions of these libraries
     are broken on SunOS 4.* systems, so GateD must be statically
     linked.  This prevents the use of a GateD binary compiled on one
     kernel architecuture (say sun4m) from working on another (sun4c).

Running GateD on AIX 3.2 systems

     AIX 3.2 has networking code based on BSD 4.3 Reno, including
     variable length subnet masks and the routing socket.  Some of the
     extensions are available when the system is not running in BSD 4.3
     compatibility mode (see the compat_43 variable and no).  Amoung
     these are the ability to determine the destination address of a
     RIP packet (used when GateD is responding to the ripquery
     program).  GateD can run in either mode with a slight loss of
     functionality in BSD 4.3 compatability mode.  Make sure you
     compile with -D_BSD=44!

     In order to generate a core dump useful for debugging on AIX 3,
     the default limit on the core size must be increased.  This can be
     accomplished via the shell, or automatically when GateD is started
     via gdc.  Some compilation-time configuring is necessary for this
     to work.  Either define GDC_CORESIZE=RLIM_INFINITY in the
     obj/Config file, or define GDC_RESOURCE and use the -c option to
     gdc at run time.

Compiling GateD on systems with shared libraries

     If an assertion failure occurs in task_stdio_read(), it is because
     a file descriptor was improperly closed.  This can occur when the
     named resolver libraries are improperly installed in the system
     shared libraries.  If the socket used by the shared libraries is
     not statically initialized to -1, file descriptor zero will be
     closed when GateD calls endhostent().  The solution is to fix the
     shared libraries.  A workaround would be to not use any symbolic
     names in the config file and specify options noresolv ;.

Using GateD on AIX 3.1 and 3.2

     Problems have been reported with yacc on at least
     some versions of AIX 3.1 and 3.2.  On of the problems is that yacc
     does not report parse errors to the caller, resulting in GateD
     trying to run with an incorrect configuration.  It is strongly
     recommended that you obtain GNU bison instead.  It is available
     from ftp://prep.ai.mit.edu/pub/gnu.

Running HELLO and/or EGP on 4.2 based systems

     If you would like to run HELLO or EGP on a 4.2 based system such
     as Ultrix 1.2, 2.0, 2.1 and SunOS 3.x you will need to add the
     following code to the following modules and rebuild your kernel.

/sys/netinet/in.h:

#define IPPROTO_EGP		8		/* exterior gateway protocol */

#define IPPROTO_HELLO		63		/* Fuzzball HELLO protocol */

/sys/netinet/in_proto.c for SunOS 3.x:

{ SOCK_RAW,	PF_INET,	IPPROTO_HELLO,	PR_ATOMIC|PR_ADDR,
  rip_input,	rip_output,	0,	0,
  raw_usrreq,
  0,		0,		0,		0,
,
{ SOCK_RAW,	PF_INET,	IPPROTO_EGP,	PR_ATOMIC|PR_ADDR,
  rip_input,	rip_output,	0,	0,
  raw_usrreq,
  0,		0,		0,		0,
,

/sys/netinet/in_proto.c for Ultrix 1.2, 2.0 and 2.2:

{ SOCK_RAW,     &inetdomain,    IPPROTO_HELLO,    PR_ATOMIC|PR_ADDR,
  rip_input,    rip_output,     0,              0,
  raw_usrreq,
  0,            0,              0,              0,
  0,            0,              0,
,
{ SOCK_RAW,     &inetdomain,    IPPROTO_EGP,    PR_ATOMIC|PR_ADDR,
  rip_input,    rip_output,     0,              0,
  raw_usrreq,
  0,            0,              0,              0,
  0,            0,              0,
,


Interfacing to the ISODE SMUX interface

     This version of GateD can do SNMP via the ISODE 7.0 SMUX
     interface. If you don't already have ISODE 7.0 you may obtain a
     version with many SMUX/SNMP patches applied via\linebreak
     ftp://gated.cornell.edu/pub/gated/isode-snmp-7.0.tar.Z from
     gated.cornell.edu as\linebreak pub/gated/isode-snmp-7.0.tar.Z.

     Even though the ISODE source requires alot of disk space, it isn't
     necessary to build and install all of ISODE, just the core
     distribution and the snmp code.  A partial install (inst-partial
     and inst-snmp) are the minimum required.

     GateD also supports the ISODE 6.8 based SMUX interface
     on AIX 3 systems.  If you experience errors of the form:

Building:       gated-mib.c
mosy -s -c gated-mib.c ../mib/smi.my ../mib/mib.my ../mib/rt.my ../mib/bgp.my ..
/mib/ospf.my ../mib/rip.my
mosy 6.8 of Sat Nov 23 12:30:27 CST 1991
line 56: Warning: EXPORTS but no ModuleIdentifier
last token read was ";"
object enterprises: Warning: IMPORTS but no ModuleIdentifier
object snmpEnableAuthenTraps: Warning: IMPORTS but no ModuleIdentifier
object snmpEnableAuthenTraps: syntax error
make: *** [gated-mib.c] Error 1

     change the default for ipForwardInfo to remove the second zero so
     it becomes:

    DEFVAL  { { 0  } } -- 0.0

     The mosy supplied with ISODE 6.8 could not parse this
     syntax, even though it is correct.


