doc/INSTALL.txt

   1 Binary distributions of the Shibboleth code are available.
   2 Information on obtaining and installing binaries can be found at
   3 http://shibboleth.internet2.edu/
   4
   5 This document provides details for those wishing to build from source.
   6 The Wiki contains additional information and more up to date build
   7 notes.
   8
   9 C++ Service Provider
  10
  11 Your first step is going to be the OpenSAML INSTALL.txt file. Please read it
  12 thoroughly to understand the issues. All the requirements in that file
  13 apply, mainly because you need to build OpenSAML, and almost all the
  14 dependencies are the same. Once you reach the end of that build process and
  15 have some confidence it worked, you can come back and continue here.
  16
  17 --- Apache
  18
  19 You'll next need to get an Apache in place. If you're building from source,
  20 you don't have to use the "real" Apache code, or use mod_ssl. You will
  21 however need to provide the necessary build flags during configure, or
  22 ideally, let our configure script use your Apache's apxs script to extract
  23 the necessary information.
  24
  25 Also, at a minimum, Apache needs to be built with mod_so enabled for
  26 dynamically loading modules. If you encounter problems with crashing
  27 or apparent module conflicts, make sure you've built Apache and any
  28 modules with threading support and ideally as much dynamically as
  29 possible.
  30
  31 Apache 1.3 does not directly support threads, but you can set the
  32 CFLAGS variable before running configure to include the proper gcc
  33 thread flag (usually -pthread or -pthreads, depends on your platform).
  34
  35 --- MySQL (optional)
  36
  37 The distribution now includes a cache plugin using embedded MySQL.
  38 This plugin will be included in the build by default if the embedded MySQL
  39 library (libmysqld.a) can be found, or if the --with-mysql option is passed
  40 to configure. You can force exclude the plugin with the --disable-mysql option.
  41
  42 Many default installs of MySQL will not include the embedded library, so don't
  43 be surprised if it's not there. Also, just as with PHP and certain other packages
  44 that include C++, you'll need to build it with the same compiler used to build
  45 Shibboleth.
  46
  47 The MySQL 4.x build is currently not clean. There are errors in several
  48 Makefile.in files that have to corrected to get the build to work.
  49 The patch for the pre-configure Makefile.in files in version 4.0.12 is included
  50 in this directory as the file "mysql-4.0.12.diff", which can be applied from the
  51 mysql-4.0.12 directory. Similar changes may be needed in other versions.
  52
  53 After patching, to get it to build, the --with-embedded-server option is used
  54 with MySQL. An example build with gcc/g++ is below:
  55
  56 $ cd mysql-4.1.12
  57 $ env CFLAGS="-fPIC -DPIC" CXXFLAGS="-fPIC -DPIC"
  58 $ ./configure --prefix=/opt/mysql \
  59     --libexecdir='${exec_prefix}/sbin' --disable-static \
  60     --enable-thread-safe-client --enable-assembler --enable-local-infile \
  61     --with-extra-charsets=complex --with-embedded-server \
  62     --with-berkeley-db --with-innodb --with-raid
  63 $ make all
  64 $ make install
  65
  66 MySQL has a lot of options, so some local customization may be needed. The
  67 command to set the compiler flags is critical on Solaris, because the flags
  68 are needed to get a correct build of the library to link against.
  69
  70 --- Shibboleth
  71
  72 Building the Shibboleth libraries, shibd, test programs, and Apache
  73 modules is more or less like building OpenSAML. You can get the code from
  74 SVN and run the bootstrap script if you want, or just use a source tarball.
  75
  76 With the source distribution or the results of your bootstrap:
  77
  78 $ ./configure --prefix=/opt/shibboleth-sp --with-log4cpp=/opt/shibboleth-sp \
  79     --enable-apache-20 -C
  80 $ make
  81 $ make install
  82
  83 This will build the Apache 2.0 modules by extracting build settings
  84 from apxs. You can use different options to build for other Apache
  85 versions or specify the location of the apxs script.
  86
  87 To test your installation, you can run the shibtest utility, which actually
  88 loads your configuration and attempts to obtain attributes from a Shibboleth
  89 Attribute Authority. It's not a great tool for testing because normally you
  90 can't query on a known principal name.
  91
  92 $ set LD_LIBRARY_PATH=/opt/shibboleth-sp/lib; export LD_LIBRARY_PATH
  93 $ /opt/shibboleth-sp/bin/shibtest -h test-handle \
  94         -f urn:mace:shibboleth:test:nameIdentifier \
  95         -q  https://idp.example.org/shibboleth
  96
  97 The example shown uses a test principal that is specific to the InQueue
  98 sample IdP, which is known to the SP after initial installation.
  99 You should get some reasonably structured output back that lists some
 100 attributes. Some warnings or errors are normal.