Apache-dictated format

[shibboleth/sp.git] / doc / INSTALL.txt

diff --git a/doc/INSTALL.txt b/doc/INSTALL.txt
index e149ca9..098da6d 100644 (file)
--- a/doc/INSTALL.txt
+++ b/doc/INSTALL.txt
@@ -1,5 +1,5 @@
-7/31/03
-Version 1.1
+11/15/04
+Version 1.2.1
 
 Binary distributions of the Shibboleth code are available.
 Information on obtaining and installing binaries can be found at
@@ -24,17 +24,15 @@ however need to provide the necessary build flags during configure, or
 ideally, let our configure script use your Apache's apxs script to extract
 the necessary information.
 
-Once Apache is in place, you'll also need to build the libapreq library.
-Adjust the include path as needed.
+Also, at a minimum, Apache needs to be built with mod_so enabled for
+dynamically loading modules. If you encounter problems with crashing
+or apparent module conflicts, make sure you've built Apache and any
+modules with threading support and ideally as much dynamically as
+possible.
 
-http://www.apache.org/dist/httpd/libapreq/libapreq-1.1.tar.gz
-
-$ tar xvzf libapreq-1.1.tar.gz
-$ cd libapreq-1.1
-$ ./configure --prefix=/opt/shibboleth --enable-static=no \
-    --with-apache-includes=/usr/local/apache/include
-$ make
-$ make install
+Apache 1.x does not directly support threads, but you can set the
+CFLAGS variable before running configure to include the proper gcc
+thread flag (usually -pthread or -pthreads, depends on your platform).
 
 --- MySQL (optional)
 
@@ -46,7 +44,7 @@ to configure. You can force exclude the plugin with the --disable-mysql option.
 Many default installs of MySQL will not include the embedded library, so don't
 be surprised if it's not there. Also, just as with PHP and certain other packages
 that include C++, you'll need to build it with the same compiler used to build
-Shibboleth unless g++ 3.2 or higher was used.
+Shibboleth.
 
 The MySQL 4.0.x build is currently not clean on either platform. There are errors
 in several Makefile.in files that have to corrected to get the build to work.
@@ -76,27 +74,43 @@ are needed to get a correct build of the library to link against.
 Building the Shibboleth target libraries, shar, test programs, and Apache
 modules is more or less like building OpenSAML. You can get the code from
 CVS and run the bootstrap script if you want, or just use a source tarball.
+
+On Solaris/OS X, if you're rebuilding into a prefixed location that already
+contains a copy of the software and headers, you'll want to remove
+some of the headers to prevent extra build work when you run the make
+install command. Just do:
+
+$ rm -rf /opt/shibboleth/include/rpc
+
 With the source distribution or the results of your bootstrap:
 
-$ ./configure --prefix=/opt/shibboleth --with-xmlsec=/opt/shibboleth --with-apxs -C
+$ ./configure --prefix=/opt/shibboleth --with-log4cpp=/opt/shibboleth \
+    --enable-apache-13 --with-apxs --enable-apache-20 --with-apxs2 -C
 $ make
 $ make install
 
-This will build the Apache modules by extracting build settings from apxs.
-The configure script will look in normal spots for the script
-(/usr/bin/apxs, /usr/local/apache/bin/apxs) but you can point it if you need to.
+This will build the Apache 1.x and 2.x modules by extracting build settings
+from apxs. The configure script will look in normal spots for the script
+(/usr/bin/apxs, /usr/local/apache/bin/apxs) but you can point to it so that
+both modules can be built at once.
 
 If you want to build the modules but not use apxs, you can use the
 --without-apxs option, and provide flags using the APXS_PREFIX, APXS_CFLAGS,
 APXS_INCLUDE, APXS_LIBEXEC, and APXS_SYSCONFDIR variables (see the apxs docs
 for some guidance on what these should be).
 
-To test your installation, you can try this:
+To test your installation, you can try the shibtest utility, which actually
+loads your configuration and attempts to obtain attributes from a Shibboleth
+Attribute Authority of your choosing. You indicate to it the "handle" of the
+principal to query, and the identifier (providerId) of the origin site,
+and it will use your configuration files to locate the proper AA.
 
 $ set LD_LIBRARY_PATH=/opt/shibboleth/lib; export LD_LIBRARY_PATH
-$ cd /opt/shibboleth
-$ bin/shibtest -d etc/shibboleth/ -h foo -q urn:mace:inqueue:example.edu \
-    -r http://www.foo.edu/ -a http://wayf.internet2.edu/InQueue/AA
+$ /opt/shibboleth/bin/shibtest -h test-handle \
+       -f urn:mace:shibboleth:test:nameIdentifier \
+       -q urn:mace:inqueue:example.edu
 
+The example shown uses a built-in test principal, and uses the InQueue
+example origin, which is known to the target after initial installation.
 You should get some reasonably structured output back that lists some simple
 attributes. An error here is a pretty good sign there's trouble.