Installing BIND 4.9.3 resolver code in SunOS 4.1.x shared libraries
===================================================================

$Id: INSTALL,v 1.4 1994/07/19 22:51:24 vixie Exp $

by Chris Davis <ckd@kei.com>

based on code and documentation by:
  Paul Balyoz <pab@naucse.cse.nau.edu>
  Piete Brooks <pb@cl.cam.ac.uk>
  Dave Morrison <drmorris@mit.edu>
  Hal Pomeranz <pomeranz@nas.nasa.gov>
and probably others (apologies if I've forgotten you).

Note that if you wish to modify this process, you should read and
understand the file ISSUES in this directory.

1.  Get and unpack a copy of BIND 4.9.3.  (This document is from that
    distribution, as shres/INSTALL.)  BIND's home site is
    gatekeeper.dec.com, and it lives in /pub/misc/vixie.

    In the remainder of this document, $BINDSRC represents the directory
    you unpacked the BIND distribution into.

2.  Configure it to your tastes by editing $BINDSRC/conf/options.h, using
    $BINDSRC/OPTIONS as a guide to the available choices.  SUNSECURITY
    must be on (and will be turned on automatically on Suns).  Not all of
    the options affect the resolver library, but you probably want the new
    named as well (the one Sun supplies is really, really old).

3.  (Optional) Use "make DST=sun4.b links" to create a shadow source tree
    for the Sun4 architecture (see $BINDSRC/README for details).  This is
    particularly useful if you are building for more than one architecture
    or operating system (like, say, SunOS 4.1.x and Solaris 2.x).  If you
    do this, cd into the new build directory ("cd sun4.b", for example).

4.  Uncomment the appropriate lines in $BINDSRC/sun4.b/Makefile (or
    $BINDSRC/Makefile if you didn't do step 3, shame shame) for SunOS 4.
    To build a shared library, uncomment the lines just after the one
    labeled "uncomment next line to build a shared library version of
    libresolv", in the SunOS 4.x section.  If you have gcc, use it, as it
    can share the read-only data (see $BINDSRC/shres/ISSUES for more
    details).

    Note that there are some "common" lines in the Makefile that you will
    need to uncomment for SunOS 4 in addition to the ones specifically for
    SunOS 4; don't forget to uncomment those as well.

5.  (Optional) Add $BINDSRC/bin to your path, and "make depend".

6.  Type "make" to build named, the tools, the "normal" libresolv, and the
    position-independent code ("pic") libresolv.

7.  Install the appropriate "jumbo libc patch" for your SunOS version, if
    you haven't already.  Among other things, this includes fixes for some
    bugs in the shared library building process.

    At the time of this writing, the patch numbers and latest revisions of
    the "international" versions of these patches were:

      4.1.3:    100891-10
      4.1.3_U1: 101558-02

    Note that "international" means "has not installed the extra-cost 'US
    Encryption Kit'", so most sites, even in the US, will need these
    versions.  If you have installed the "US Encryption Kit" you will need
    to get the domestic versions.

    As "recommended" patches, these patches are available for anonymous
    ftp to all Sun customers, even those without support contracts, from
    sunsolve1.sun.com in the /pub/patches directory.

Perform the following steps to integrate the shareable resolver library
code (libresolv_pic.a) into the shared libc (for both BSD and SysV
universes).  If you use the $BINDSRC/shres/makeshlib script, steps 8-16
will be done for you; in that case, you may want to skip ahead to step 17.

The makeshlib script does minimal error checking and is mostly a quick &
dirty convenience for people tired of typing commands.

Note that some or all of these steps may need to be done as root.  You
should read the makeshlib script carefully before running it as root.

The makeshlib script is not executable by default.  You may wish to use
"sh -x shres/makeshlib" to view the commands as they are executed as a
progress indicator.

8.  Move into the shared-lib area and make a temporary directory:

      cd /usr/lib/shlib.etc
      mkdir tmp

9.  Move into this new directory, extract the pic (position independent
    code) object files from libc_pic.a and remove the SYMDEF file.  The
    renaming (mv commands) is done because the "ar" command truncates
    names to 16 characters.

      cd tmp
      ar x ../libc_pic.a
      rm __.SYMDEF
      mv rpc_dtablesize. rpc_dtablesize.o
      mv rpc_commondata. rpc_commondata.o
      mv xccs.multibyte. xccs.multibyte.o

10. Extract the shareable libresolv_pic.a into this target directory.  This
    will replace Sun's inet_addr.o, which is ok, this one is better.  It
    will also replace Sun's getnetent.o, which is ok, as long as you have
    DNS entries for your networks (as in RFC 1101).  Make sure that Sun's
    mktemp.o and strpbrk.o don't get stomped; you need to use Sun's.

      ar x $BINDSRC/shres/libresolv_pic.a
      rm __.SYMDEF

11. Make sure the old host resolver is not still lying around:

       rm gethostent.o

    (ignore error "rm: gethostent.o nonexistent" if you see it.)

12. Go back up to the shared library building directory and duplicate the
    list of object files to use:

      cd ..
      cp lorder-sparc lorder-sparc.orig

13.  Edit this object file list and make the following modifications if
     they haven't already been done before to this file:

             remove: gethostent.o
             add:    gethnamaddr.o
                     herror.o
                     sethostent.o
                     res_query.o
                     res_mkquery.o
                     res_send.o
                     res_debug.o
                     res_comp.o
                     res_init.o
                     getnetnamadr.o
                     getnetbyname.o
                     getnetbyaddr.o
                     strerror.o

     If you don't want the getnet* routines (some sites want to use yp for
     getting networks), don't add the getnet* lines.  It isn't really
     kosher to hack the lorder-sparc file like this, but it isn't
     deadly either.  Other orderings may have different performance
     effects (could be better, could be worse...).

     The easiest way to do this is to apply (using the 'patch' program)
     the patch file $BINDSRC/shres/sun-lorder-sparc.patches.

14.  The Makefile in shlib.etc for building shared libraries has one
     problem when you run it as the super user if you don't have '.' in
     your path (and you shouldn't...).  So edit it and modify the
     definition of "OBJSORT" to read:

       OBJSORT=./objsort

     If you are using the SunOS 4.1.x unpatched shlib.etc, change the
     lines (there are two) in the Makefile which read

       ld -assert pure-text `${OBJSORT} lorder-sparc tmp`

     to read

       ld -assert pure-text `${OBJSORT} lorder-sparc tmp` -ldl

     The patched shlib.etc for 4.1.3 already has this fixed, but the
     patched shlib.etc for 4.1.3_U1 does not.  (Why?  I don't know...)

     The easiest way to do this is to apply (using the 'patch' program)
     the patch file $BINDSRC/shres/sun-Makefile.patches.  If you have the
     4.1.3 version of the Makefile, the second chunk will fail; this can
     safely be ignored.

15.  Now we can finally build the shared library.  Type:
       make libc.so

     What kind of errors might you get?  Here's a couple:

       a. It blows up on one of the .o files in tmp, saying that the
	  object file is in an inconsistent state.

          SOLUTION: start over; you did something wrong when you compiled
	  libresolv_pic.a in step 4, above.  Make SURE you're using the
	  libresolv_pic.a that was built in $BINDSRC/shres, and not the
	  "normal" libresolv.a built in $BINDSRC/res.

       b. It lists hundreds of error lines about offsets or addresses
	  being wrong in all your resolver .o files.

          SOLUTION: start over; you needed to specify "-pic" or "-fpic" to
	  the C compiler when building shres/libresolv_pic.a.  Make sure
	  you're using libresolv_pic.a, and make sure that SHCC and PIC
	  were properly defined in $BINDSRC/Makefile.

16.  To build the System V shared libc, repeat steps 8-11, using
     'libcs5_pic.a' instead of 'libc_pic.a', then 'make libcs5.so'.

If you used makeshlib, you should now 'cd /usr/lib/shlib.etc' for the
following tests. You will also have a symlink "tmp" and two directories
"tmp.s5" and "tmp.ucb" in this directory, all three of which can be
deleted.

17.  If all goes well, you now have a "libc.so.x.y.z" in this directory
     (two, if you rebuilt the SysV shared library as well; the BSD one is
     libc.so.1.y.z, while the SysV one is libc.so.2.y.z).  Test it (or
     them) out before installing it (or them) systemwide!  You can do this
     by pointing the LD_LIBRARY_PATH environment variable to the current
     directory, then trying various networking commands.

     In csh or tcsh:
       setenv LD_LIBRARY_PATH `pwd`
       ftp another.host.com
       telnet someone.else.ca
       unsetenv LD_LIBRARY_PATH

     ping (or any other setuid/setgid program) will not work if you test
     it this way, because LD_LIBRARY_PATH is ignored for security reasons.

     Make sure you have a valid /etc/resolv.conf, or it will not appear to
     work.  If you have been using DNS via NIS in the past, you might not
     have a resolv.conf file on the clients.

     If anything in the library fails, you need to start section B over
     again.  Maybe you forgot to use Sun's versions of mktemp.o and
     strpbrk.o; things just won't work with BIND's new versions of these
     files.

18.  When you are sure it's working OK, you can install it into the system
     library directory (you will need to be superuser to do this):

       su
       cd /usr/lib/shlib.etc
       cp libc.so.x.y.z /usr/lib
       chmod 755 /usr/lib/libc.so.x.y.z
       # for sysv shared library
       cp libc.so.x.y.z /usr/5lib
       chmod 755 /usr/5lib/libc.so.x.y.z
       # for both
       ldconfig

     Next you need to install the shared archive, which contains
     initialized global data.  If you skip this step, executables compiled
     on your machine since the new library was installed will not contain
     that data.  They still will be able to run (which is probably why
     this step has been missing from both the Internet and *Sun*
     instructions for years), as the data is replicated in the shared
     object.  A few preliminary tests indicate missing this step can
     marginally slow down processes, although it necessarily a depends on
     the program and the machine in question.  For more details on this,
     see $BINDSRC/shres/ISSUES.

     The numbers x, y, and z must match the numbers in the shared object
     above.

       cd /usr/lib
       cp libc.sa.x.y libc.sa.x.y.z
       ranlib libc.sa.x.y.z
       cd /usr/5lib
       cp libc.sa.x.y libc.sa.x.y.z
       ranlib libc.sa.x.y.z

19.  You can prove that you're using the new library now, by watching the
     output of something like:

       trace date

     Look for the open() of libc.so.* and note the version number.

     The latest BIND resolver is now installed in your system's shared C
     library.

20.  Once you are fully confident of your new library, reboot your
     machine.  Until you do, running processes will continue to use the
     old shared library.

You may also want to modify the unshared system C library /usr/lib/libc.a;
see the item "Modifying the static libc" in shres/ISSUES for discussion of
how (and why) to do this.

