doc/INSTALL.txt

   1 7/25/03
   2 Version 1.0.1
   3
   4 Binary distributions of the Shibboleth code are available.
   5 Information on obtaining and installing binaries can be found at
   6 http://shibboleth.internet2.edu/ and in the deploy guide in this
   7 directory.
   8
   9 This document provides details for those wishing to build from source.
  10
  11 C++ / TARGET
  12
  13 Your first step is going to be the OpenSAML INSTALL.txt file. Please read it
  14 thoroughly to understand the issues. All the requirements in that file
  15 apply, mainly because you need to build OpenSAML, and almost all the
  16 dependencies are the same. Once you reach the end of that build process and
  17 have some confidence it worked, you can come back and continue here.
  18
  19 --- Apache
  20
  21 You'll next need to get an Apache in place. If you're building from source,
  22 you don't have to use the "real" Apache code, or use mod_ssl. You will
  23 however need to provide the necessary build flags during configure, or
  24 ideally, let our configure script use your Apache's apxs script to extract
  25 the necessary information.
  26
  27 Once Apache is in place, you'll also need to build the libapreq library.
  28 Adjust the include path as needed.
  29
  30 http://www.apache.org/dist/httpd/libapreq/libapreq-1.1.tar.gz
  31
  32 $ tar xvzf libapreq-1.1.tar.gz
  33 $ cd libapreq-1.1
  34 $ ./configure --prefix=/opt/shibboleth --enable-static=no \
  35     --with-apache-includes=/usr/local/apache/include
  36 $ make
  37 $ make install
  38
  39 --- MySQL (optional)
  40
  41 The distribution now includes a session cache plugin using embedded MySQL.
  42 This plugin will be included in the build by default if the embedded MySQL
  43 library (libmysqld.a) can be found, or if the --with-mysql option is passed
  44 to configure. You can force exclude the plugin with the --disable-mysql option.
  45
  46 Many default installs of MySQL will not include the embedded library, so don't
  47 be surprised if it's not there. Also, just as with PHP and certain other packages
  48 that include C++, you'll need to build it with the same compiler used to build
  49 Shibboleth unless g++ 3.2 or higher was used.
  50
  51 The MySQL 4.0.x build is currently not clean on either platform. There are errors
  52 in several Makefile.in files that have to corrected to get the build to work.
  53 The patch for the pre-configure Makefile.in files in version 4.0.12 is included
  54 in this directory as the file "mysql-4.0.12.diff", which can be applied from the
  55 mysql-4.0.12 directory.
  56
  57 After patching, to get it to build, the --with-embedded-server option is used
  58 with MySQL. An example build is below:
  59
  60 $ cd mysql-4.0.12
  61 $ env CFLAGS="-fPIC -DPIC" CXXFLAGS="-fPIC -DPIC"
  62 $ ./configure --prefix=/opt/mysql \
  63     --libexecdir='${exec_prefix}/sbin' \
  64     --enable-thread-safe-client --enable-assembler --enable-local-infile \
  65     --with-extra-charsets=complex --with-embedded-server \
  66     --with-berkeley-db --with-innodb --with-raid
  67 $ make all
  68 $ make install
  69
  70 MySQL has a lot of options, so some local customization may be needed. The
  71 command to set the compiler flags is critical on Solaris, because the flags
  72 are needed to get a correct build of the library to link against.
  73
  74 --- Shibboleth
  75
  76 Building the Shibboleth target libraries, shar, test programs, and Apache
  77 modules is more or less like building OpenSAML. You can get the code from
  78 CVS and run the bootstrap script if you want, or just use a source tarball.
  79 With the source distribution or the results of your bootstrap:
  80
  81 $ ./configure --prefix=/opt/shibboleth --with-xmlsec=/opt/shibboleth --with-apxs -C
  82 $ make
  83 $ make install
  84
  85 This will build the Apache modules by extracting build settings from apxs.
  86 The configure script will look in normal spots for the script
  87 (/usr/bin/apxs, /usr/local/apache/bin/apxs) but you can point it if you need to.
  88
  89 If you want to build the modules but not use apxs, you can use the
  90 --without-apxs option, and provide flags using the APXS_PREFIX, APXS_CFLAGS,
  91 APXS_INCLUDE, APXS_LIBEXEC, and APXS_SYSCONFDIR variables (see the apxs docs
  92 for some guidance on what these should be).
  93
  94 To test your installation, you can try this:
  95
  96 $ set LD_LIBRARY_PATH=/opt/shibboleth/lib; export LD_LIBRARY_PATH
  97 $ cd /opt/shibboleth
  98 $ bin/shibtest -d etc/shibboleth/ -h foo -q urn:mace:inqueue:example.edu \
  99     -r http://www.foo.edu/ -a http://wayf.internet2.edu/InQueue/AA
 100
 101 You should get some reasonably structured output back that lists some simple
 102 attributes. An error here is a pretty good sign there's trouble.