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

$Id: INSTALL,v 8.2 1994/12/15 06:27:04 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>
  Matt Ragan <matt@ibmoto.com>
  Greg A. Woods <woods@kuma.web.net>
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 shres/ISSUES.

If you have problems with the process (or its aftermath), see shres/PROBLEMS.

You should read through this whole file BEFORE BEGINNING.  I mean it.  I
really mean it.  The shared library is the second most important part of
SunOS (right behind /vmunix).  If you screw it up you will be very very
unhappy and so will your users.  You should also read shres/PROBLEMS before
starting, if only to know what sort of things to watch out for.

[Disclaimer: 
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.]

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
    ftp.vix.com, and it lives in /pub/bind.

    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 resolver code to install in the shared library, uncomment the
    SHRES line, as well as the appropriate SHCC and PIC lines.  If you
    have gcc, use it for SHCC, as it can share the read-only data (see
    $BINDSRC/shres/ISSUES for more details).

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.  This will also include
    the shared library build directory (/usr/lib/shlib.etc), which is
    useful if the "Shlib Custom" package was not already installed.

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

    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-18
will be done for you; read them anyway.

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.

You may wish to run makeshlib as "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.

    Note that Sun's documentation (/usr/lib/shlib.etc/README) omits the
    last "mv" command.  This will result in "undefined symbol" errors for
    the four symbols mbstowcs_xccs, mbtowc_xccs, wcstombs_xccs, and
    wctomb_xccs.  (See shres/PROBLEMS for more details.)

      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).  (If you want to
    keep using NIS or /etc/networks instead, you'll need to save Sun's
    getnetent.o, remove BIND's getnetby* files, and put Sun's getnetent.o
    back after this step.)  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. Sun's shipped awk script has a small bug; if you use their recommended
    procedure for saving old (FCS) versions of the shared libraries, it
    can get the wrong version number for the new libc.so.  You should fix
    this problem by applying (using the 'patch' program) the patch file
    $BINDSRC/shres/sun-awkfile.patches.

13. 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

     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:    herror.o
                     getnetnamadr.o
                     getnetbyaddr.o
                     getnetbyname.o
                     gethnamaddr.o
                     res_query.o
                     res_mkquery.o
                     sethostent.o
                     res_send.o
                     res_debug.o
                     res_comp.o
                     res_init.o
                     nsap_addr.o
                     strerror.o

     It isn't really kosher to hack the lorder-sparc file like this, but
     it isn't deadly either.  This ordering was created by using lorder
     and tsort on libresolv_pic.a; it should be the best ordering of the
     new files.  (Don't add the getnetby* files if you removed them in
     step 10.)

     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 supplied by Sun for building shared libraries,
     /usr/lib/shlib.etc/Makefile, 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

     In some versions of /usr/lib/shlib.etc/Makefile, you will also need
     to change the lines (there are two) which read

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

     to read

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

     The "jumbo libc patch" for 4.1.3 fixes this, but the "jumbo libc
     patch" for 4.1.3_U1 does not.  (Why?  I don't know...)

     If the shared library is built without -ldl, all subsequent
     compilations (except when using static linking) on the system will
     fail with "undefined symbol" errors for _dlopen, _dlclose, and
     _dlsym unless you add -ldl when linking.

     If you have *ever* modified your shared libc before (maybe for
     resolv+, maybe for other reasons) and you didn't add the -ldl to
     /usr/lib/shlib.etc/Makefile, you have probably been adding -ldl to
     every Makefile for every program you've compiled since then.  This is
     obviously suboptimal.  Fix your shared libc once and for all.

     The easiest way to fix these problems in /usr/lib/shlib.etc/Makefile is
     to apply (using the 'patch' program) the two patch files
     $BINDSRC/shres/sun-Makefile.patch1 & $BINDSRC/shres/sun-Makefile.patch2.
     If you have the patched 4.1.3 version of the Makefile, the second patch
     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'.

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) may not use the new library
     if you test it this way, because LD_LIBRARY_PATH is ignored for
     security reasons if the real and effective user or group ids do not
     match.  (If you test as root, ping will use the new library.)

     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

If you used makeshlib, you can delete the temporary directories created by
the script (/usr/lib/shlib.etc/tmp.s5 and /usr/lib/shlib.etc/tmp.ucb) now.

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.

     You can also use ldd to check which shared libraries will be used by
     a dynamically linked program:

       # ldd /usr/ucb/telnet
       -lc.1 => /usr/lib/libc.so.1.9.2
       -ldl.1 => /usr/lib/libdl.so.1.0

     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.

21.  "make install" in $BINDSRC to install the new resolver library,
     named, and header files.  This will allow statically linked programs
     and programs that link directly to the resolver library (like
     sendmail) to be compiled against the BIND resolver (highly
     recommended).

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