From 096f6ff918e996db400b3549375c4fbeb983206c Mon Sep 17 00:00:00 2001 From: cantor Date: Fri, 23 Apr 2004 06:07:47 +0000 Subject: [PATCH] Changes to technical requirement sections and basic setup. git-svn-id: https://subversion.switch.ch/svn/shibboleth/java-idp/trunk@1005 ab3bd59b-922f-494d-bb5f-6f0a3c29deca --- doc/DEPLOY-GUIDE-TARGET.html | 598 ++++++++++++++++++------------------------ 1 file changed, 250 insertions(+), 348 deletions(-) diff --git a/doc/DEPLOY-GUIDE-TARGET.html b/doc/DEPLOY-GUIDE-TARGET.html index 5746cea..e9930fb 100644 --- a/doc/DEPLOY-GUIDE-TARGET.html +++ b/doc/DEPLOY-GUIDE-TARGET.html @@ -128,22 +128,37 @@ April 4, 2004

This version of the deploy guide is for Shibboleth v1.2. For documentation related to prior versions of Shibboleth, please consult the appropriate branch in the Shibboleth CVS.

-

The default configuration of Shibboleth is not secure and should not be used for protection of production content. The example private key bundled with the distribution is publically available, widely circulated, and well-known; also, the default federation -and trust metadata is for testing purposes only. For information about securing a Shibboleth deployment, please refer to the production guide. Shibboleth should only be used to protect sensitive content when deployed carefully in conjunction with proper trust settings and policies.

+

The default configuration of Shibboleth is not secure and should not be +used for protection of production content. The example private key bundled with the +distribution is publically available, widely circulated, and well-known; also, the +default federation and trust metadata is for testing purposes only. For information +about securing a Shibboleth deployment, please refer to the production guide. +Shibboleth should only be used to protect sensitive content when deployed carefully +in conjunction with proper trust settings and policies.

-

Insert features here.

+

The Shibboleth target implementation has been substantially redesigned for this release. Most of the +configuration process has changed to accomodate more complex deployments but many of the defaults work +fine for testing and simpler applications. Among the new features:

+

Before starting, please sign up for all applicable mailing lists. Announcements pertinent to Shibboleth deployments and developments and resources for deployment assistance can be found here.

Please send any questions, concerns, or eventual confusion to -mace-shib-users@internet2.edu. +shibboleth-users@internet2.edu. This should include, but not be limited to, questions about the documentation, undocumented problems, installation or operational issues, and anything else -that arises. Please ensure that you have the -appropriate -tarball for your operating system.

+that arises.


@@ -336,10 +351,10 @@ and requirements for a successful implementation of a Shibboleth target.

Shibboleth currently supports Windows NT/2000/XP/2003, Linux, and Solaris. At present, Shibboleth consists of Apache (or IIS) plugins and a - separate SHAR process. The plugins use the ONC RPC mechanism to communicate + separate SHAR process. The plugins use the Sun/ONC RPC mechanism to communicate with the SHAR over Unix domain or TCP sockets. The target's web servers must be running Apache - 1.3.26+, or Microsoft IIS 4.0+, but not Apache 2. More precise technical + 1.3+, 2.0+, or Microsoft IIS 4.0+ More precise technical details are discussed in 3.a.

2.b. Join a Federation

@@ -349,13 +364,11 @@ and requirements for a successful implementation of a Shibboleth target.

relationships. Each federation will have a different application process.

For more information on federations, refer to 1.d or the Shibboleth v1.0 architectural document.

-

To use Shibboleth without a federation, manual configuration of target - and origin trust and site information will be needed to insure that sites - interoperate. Most identifiers, such as site names, should be URI-based, and - should be chosen in accordance with DNS domains under the control of the - parties involved, much as Java package naming is coordinated. In other - words, don't use a URI containing a DNS domain or hostname that you do not - control.

+

For testing in a private environment, Shibboleth comes with a default + configuration that demonstrates how to implement a local peered agreement + and supports testing both origin and target on the same box using localhost + URLs. The sample key and certificate is for ease of testing only, and should + always be replaced for real world use.

2.c. Security Considerations

@@ -380,7 +393,7 @@ and requirements for a successful implementation of a Shibboleth target.

against this is safeguarding the WAYF service and ensuring that rogue targets and origins are not used, generally by development of the trust model underneath Shibboleth. Shibboleth also leverages DNS for security, - which is not uncommon, but attacks concerning bad domain information + which is not uncommon, but attacks concerning domain name lookups should be considered.
  • Information regarding origin users is generally provided by the authoritative enterprise directory, and the acceptance of requests from @@ -408,9 +421,9 @@ and requirements for a successful implementation of a Shibboleth target.

    Policies (ARP's) that define which attributes are released to which targets. When a browser user tries to access a resource, the SHAR asks the origin site AA to release all the attributes it is allowed to know, possibly - restricted to specifically desired subset. The SHAR provides its own name - and an optional URL on behalf of which the attribute request is made which - can further refine the information the SHAR is allowed to know. The AA + restricted to a specifically desired subset. The SHAR provides a client + certificate with its request (assuming SSL is used) so the AA can further + refine the information the SHAR is allowed to know. The AA processes this request using all applicable ARP's, determines which attributes and values it will release, and then obtains the values actually associated with the browser user. The AA sends these attributes and values @@ -445,7 +458,7 @@ and requirements for a successful implementation of a Shibboleth target.

    2.h. Clocks

    NTP should be run on all - web servers. Shibboleth employs a short handle issuance time to protect + web servers. Shibboleth employs a short assertion acceptance window to protect against replay attacks. Because of this, any significant degree of clock skew can hinder the ability of users to access sites successfully.

    @@ -466,47 +479,95 @@ and requirements for a successful implementation of a Shibboleth target.

    3. Installation

    3.a. Software Requirements

    -

    The Shibboleth project makes binary packages available for Solaris and Linux +

    The Shibboleth project makes binary packages available only for Windows, that are precompiled against recent releases of various required libraries such -as OpenSSL. It is highly advisable to build from source when using Shibboleth in +as OpenSSL. Binaries for other platforms may be available on a limited or ad hoc +basis. It is highly advisable to build from source when using Shibboleth in a production environment in order to permit patching or updating of packages as security holes and bugs are fixed. Building from source is necessary to give you complete control over your deployment platform. The binary packages represent a snapshot in time only. To build from source, see the INSTALL.txt files in the doc folder of the OpenSAML and Shibboleth source distributions.

    -

    The software requirements listed correspond to the binary distributions. In +

    The software requirements listed correspond to the binary distribution. In general, source builds should work against all recent versions of the operating systems and software dependencies listed below. For specific questions, inquire to the support mailing list, or give it a try. Note that OpenSSL releases frequent security updates; the version listed may not be the most current, but most minor "letter" updates should be usable.

    -

    Operating System:

    +

    General Requirements and Notes:

    +
      +
    • Apache 1.3.x +
      +

      Apache 1.3.x must be compiled with mod_so for DSO module support, and + should include SSL support (preferably using mod_ssl), + and EAPI support (which mod_ssl requires and provides).

      +

      Portions of the libphp4 Apache + module are written in C++, as is Shibboleth. There is a known + conflict between the PHP extensions libpspell.so + and libsablot.so which will manifest + itself as segmentation faults when starting Apache. If a site wants + to use libphp4.so and Shibboleth at the same time, + then one of the following may be done: +

        +
      1. Remove the options --with-pspell + and --with-xslt-sablot from PHP's + configuration.
        2. +
      2. Rebuild these two modules using the same version of GCC that + was used to compile Shibboleth.
        3. +
      +

      +
      • +
    • Apache 2.0.x +
      +

      Apache 2.0.x must be compiled with mod_so for DSO module support, and + should include SSL support which is available but not included by default. + See also the note about PHP above.

      +

      At the time of writing, an incompatibility exists between Shibboleth + and mod_cgi that causes forked CGI child processes + to fail. The newer mod_cgid provided for use with + the multi-threaded worker MPM works fine and is suggested as a work-around + even if running in prefork mode.

      +
      +
      • +
    • IIS 4.0+ +
      +

      When installing under Windows 2003, if the server is not in a + domain before installing IIS 6, there may be issues surrounding + permissions on directories because of new restrictions on IIS + extensions accessing files.

      +
      +
      • +
    • OpenSSL +
      +

      Verions 0.9.6 and 0.9.7 are both supported, but 0.9.7 should be used + if possible, as support for 0.9.6 may be dropped in a future release. + Support for threads and shared libraries must be included during + configuration using the threads and shared options.

      +
      +
      • +

      Most other required libraries are either easy to update or not found + on typical systems. See the INSTALL.txt files + in the OpenSAML and Shibboleth source distributions for specific requirements + of a given release. The important requirements are for pthreads support and + shared libraries on Unix platforms. Without both, building will be hard and + stability unlikely.

      +
    +

    Operating System Specific Notes:

      -
    • Windows NT/2000/XP/2003
        -
      • Apache 1.3.27 or - IIS 4.0+
        -

        Apache must be compiled with mod_so for DSO module support, - and must include SSL support (preferably using - mod_ssl), and EAPI support (which - mod_ssl requires and provides). - Shibboleth can coexist with mod_auth, - which may be compiled or loaded into the server for use - elsewhere, but Shibboleth does not need or use it.

        +
      • Windows NT/2000/XP/2003 +
          +

        • Any Apache modules used, and Apache itself, must be compiled with the Microsoft DLL-based runtime, selected by compiling with the /MD switch.

          -
        • -
        • -
      • - - Shibboleth v1.1 Target for Windows
        -

        Available in both self-installer and ZIP format, the - installer will prompt for an install path, change default +

        • +
      • +

        The installer will prompt for an install path, change default configuration files as appropriate for Windows, and set various environment variables for you. A default SHAR service can also - be installed for you, or you can install it manually using the + be installed, or you can install it manually using the instructions in this guide.

        Note that debug/symbol versions of the libraries and software are included, and may be used by appending "debug" to the @@ -515,201 +576,95 @@ most minor "letter" updates should be usable.

        must also be compiled with Microsoft's debug runtime (via the /MDd compiler option). In most cases, you can safely ignore or even delete the debug versions.

        -

        When installing under Windows 2003, if the server is not in a - domain before installing IIS 6, there may be issues surrounding - permissions on directories.

        -
    +
    • + + +
  • RedHat Linux 7.2,7.3: +
      +
    • +

      The most recent Red Hat RPM (1.3.27-2 as of this writing) is sufficient for + use with Shibboleth. You can use the older version of OpenSSL included, for this + release, but be advised this may change in the future.

      • -
    +
  • +

    The version of GCC that comes with this system is too old to build Shibboleth. + Special update RPMs are available for GCC 3.04 that will work provided you + configure packages with CC and CXX set to gcc3 and g++3 respectively. Newer + GCC versions also work but may require a glibc upgrade and necessitate a lot + of unrelated package updates.

    +
    • + -

      -

  • RedHat 7.2-7.3:
      -
    • Apache 1.3.27
      -

      Apache must be compiled with mod_so for DSO module support, - and must include SSL support (preferably using - mod_ssl), and EAPI support (which - mod_ssl requires and provides). - Shibboleth can coexist with mod_auth, - which may be compiled or loaded into the server for use - elsewhere, but Shibboleth does not need or use it. The most - recent Red Hat RPM (1.3.27-2 as of this writing) is sufficient.

      -
      -
      -

      On Linux, Shibboleth requires that Apache and Apache-SSL be - built with libpthread, or loading the - mod_shibrm or - mod_shire modules will cause Apache to stop. While - RedHat's Apache is compatible, Debian's Apache must be rebuilt - with libpthread:

      +
    • RedHat Linux 9 / Fedora +
        +
      • +

        Apache 2.0 is included as the default version in this release. If using + the prefork MPM (/sbin/httpd), then the Apache configuration + file needs to be modified to use mod_cgid in place of + mod_cgi. If using the worker MPM + (/sbin/httpd.worker), then mod_cgid + is used already, which Apache strongly recommends.

        +
        • +
      +
      • +
    • RedHat Enterprise Linux +
        +
      • +

        Apache 2.0 is included as the default version in this release. Unlike + the RH 9 and Fedora distributions, mod_cgid is not + included, which not only causes problems for Shibboleth but is also suboptimal + if the worker MPM is used. No workaround is known yet, save building + mod_cgid from the Apache source.

        +
        • +
      +
      • +
    • Debian Linux +
        +
      • +

        Shibboleth requires that Apache and Apache-SSL be built with + libpthread, or loading the + mod_shib_13 or mod_shib_20 + modules will cause Apache to fail. While RedHat's Apache is compatible, + Debian's Apache must be rebuilt with libpthread:

        $ export LDFLAGS=-lpthread
        $ apt-build --rebuild --reinstall install \
            apache-common apache apache-ssl

        -
      • -
      • -
    • - - Shibboleth v1.1 Target for RedHat
      • -
    • openssl-0.9.6, revision - i or newer
      • -
    • libstdc++3-3.0.4-1.i386.rpm and libgcc-3.0.4-1.i386.rpm
      -

      Shibboleth binaries are currently built with - GCC 3.04, - and require these specific library versions. They are available - as RPMs and are available in the RedHat 7.2 updates directory on - any - - RedHat mirror. They can be installed alongside earlier and - later GCC libraries.

      -
      -
      • -
    • Portions of the libphp4 Apache - plugin are written in C++, as is Shibboleth. There is a known - conflict between the PHP extensions libpspell.so - and libsablot.so which will manifest - itself as segmentation faults when starting Apache. If a site wants - to use libphp4.so and Shibboleth at once, - then one of the following may be done:
        -
      1. Remove the options --with-pspell - and --with-xslt-sablot from PHP's - configuration.
        2. -
      2. Rebuild these two modules using the same version of GCC that - was used to compile Shibboleth.
        3. -
      • -
    +
    • -


    - -

  • Solaris 2.8:
      -
    • - openssl-0.9.7 -
      +
    • Solaris 2.6+: +
        +

      • The shared library version of OpenSSL is required by Shibboleth. The static libraries may be installed as well if necessary for other applications, but cannot be used within - mod_ssl or any other Apache modules. openssl-0.9.7b, the latest - security fix release, has been tested, but any 0.9.7 version - should work.

        -
      • -
      • -
    • Apache 1.3.27
      -

      Apache must be compiled with mod_so for DSO module support, - and must include SSL support (preferably using - mod_ssl) and EAPI support (which - mod_ssl requires and provides). - Shibboleth can coexist with mod_auth, - which may be compiled or loaded into the server for use - elsewhere, but Shibboleth does not need or use it.

      -

      mod_ssl's loadable module, - libssl.so, must be compiled against - OpenSSL 0.9.7b's shared libraries. - Other versions or a statically linked build of - libssl.so will cause failures such as - bus errors when used with Shibboleth.

      -

      To check how OpenSSL was built, run the + mod_ssl or any other Apache modules. If mod_ssl's libssl.so + module is linked against the static version, bus errors will + result.

      +

      To check how mod_ssl was built, run the ldd command against libssl.so - in the Apache /libexec/ folder and + in the Apache libexec/ folder and check the output for references to - libssl.so.0.9.7b. If you see an earlier version - mentioned, or no mention of it at all, then - OpenSSL 0.9.7b must be built with shared libraries from - source, and the Apache module rebuilt with it.

      -
      + libssl.so.0.9.7. If you see an earlier version + mentioned, or no mention of it at all, then OpenSSL 0.9.7 must be + built with shared libraries from source, and the Apache module rebuilt with it.

      +

      openssl-0.9.7d, the latest security fix release, has been tested, + but any 0.9.7 version should work.

    • - - libgcc v3.2.2+ and libstdc++ v3.2.2+
      -

      Shibboleth binaries are currently built with - GCC 3.2.2, - and require these specific library versions or newer. They are - available as Sun freeware packages and can be installed - alongside earlier and later GCC libraries.

      -
      +

      Solaris does not come with GCC 3, but various versions can be obtained + from http://www.sunfreeware.com. + If building your own, GCC must be configured to use Sun's linker. Note that + you should use a consistent version of GCC across any other C++ libraries + in use within Apache, but other C++ code can freely use a different version + as long as the necessary libstdc++.so for a given + version is available

    • - - Shibboleth v1.1 Target for Solaris
      • -
    • Portions of the libphp4 Apache - plugin are written in C++, as is Shibboleth. There is a known - conflict with the PHP extensions libpspell.so - and libsablot.so which will manifest - itself as segmentation faults when starting Apache. If a site wants - to use libphp4.so and Shibboleth at once, - then one of the following may be done:
        -
      1. Remove the options --with-pspell - and --with-xslt-sablot from PHP's - configuration.
        2. -
      2. Rebuild these two modules using the same version of GCC that - was used to compile Shibboleth.
        3. -
      -
      • -
    -
    • -


    - -

  • RedHat 8 and 9:
    -

    RedHat 8 and 9 ship with Apache 2, which is not yet supported by - Shibboleth. To run Shibboleth under this OS, - Apache 1.3.27 must - be installed.

    -
    -
    -

    Apache must be compiled with mod_so for DSO module support, and - must include SSL support (preferably using - mod_ssl), and EAPI support (which mod_ssl - requires and provides). Shibboleth can coexist with - mod_auth, which may be compiled or loaded - into the server for use elsewhere, but Shibboleth does not need or - use it. The most recent Red Hat RPM (1.3.23-14 as of this writing) - is sufficient.

    -
    -
    -

    On Linux, Shibboleth requires that Apache and Apache-SSL be built - with libpthread, or loading the - mod_shibrm or - mod_shire modules will cause Apache to stop. While RedHat's - Apache is compatible, Debian's Apache must be rebuilt with - libpthread:

    -
    -

    $ export LDFLAGS=-lpthread
    - $ apt-build --rebuild --reinstall install apache-common \
    -    apache apache-ssl

    -
    -
    -
      -
    • - - Shibboleth 1.1 Target for RedHat
      • -
    • openssl-0.9.6, revision - i or newer
      • -
    • libstdc++3-3.0.4-1.i386.rpm and libgcc-3.0.4-1.i386.rpm -
      -

      Shibboleth binaries are currently built with - GCC 3.04, - and require these specific library versions. They are available - as RPMs and are available in the RedHat 7.2 updates directory on - any - - RedHat mirror. They can be installed alongside earlier and - later GCC libraries.

      -
      -
      • -
    • Portions of the libphp4 Apache - plugin are written in C++, as is Shibboleth. There is a known - conflict with the PHP extensions libpspell.so - and libsablot.so which will manifest - itself as segmentation faults when starting Apache. If a site wants - to use libphp4.so and Shibboleth at once, - then one of the following may be done: -
        -
      1. Remove the options --with-pspell - and --with-xslt-sablot from PHP's - configuration.
        2. -
      2. Rebuild these two modules using the same version of GCC that - was used to compile Shibboleth.
        3. -
      +

      Use of GCC is recommended, but new releases of Sun's Forte compiler have + been used successfully with some tinkering with configuration scripts.

    • @@ -720,104 +675,58 @@ most minor "letter" updates should be usable.

    For the sake of clarity, this deployment guide assumes that standard directories are used for all installations. These directories may be changed for local implementations, but must be done so consistently.

    -
      -
    1. Ensure that you have obtained the proper - - tarball or installer for your operating system.
      2. -
    2. On Unix, the tarballs expand into - /opt/shibboleth, and should be expanded as - root from /. If you use a different - layout or location, you will need to adjust your configuration files. - You should see the following directory structure (date and size details - notwithstanding):
      -

      $ ls -l
      - drwxr-xr-x 2 root root 4096 Oct 24 03:54 bin
      - drwxr-xr-x 2 root root 4096 Oct 24 03:54 data
      - drwxr-xr-x 2 root root 4096 Oct 24 03:54 doc
      - drwxr-xr-x 4 root root 4096 Oct 24 03:54 etc
      - drwxr-xr-x 9 root root 4096 Oct 24 03:54 include
      - drwxr-xr-x 4 root root 4096 Oct 24 03:55 lib
      - drwxr-xr-x 2 root root 4096 Oct 24 03:55 libexec
      - drwxr-xr-x 4 root root 4096 Oct 24 02:02 share

      -
      -

      On Windows, if the installer is not used, the zip file should be - unpacked beneath the root of the system drive, where it will create an - \opt\shibboleth tree that resembles the Unix - layout above. This will allow the standard configuration options to - work. The C:\opt\shibboleth\lib directory - MUST be added to the system path to enable proper operation. If you - use a different location, changes to various configuration files must be - made by hand. The installer can do this for you, and is recommended in - such cases.

      3. -
    +

    On Unix, the build documentation suggests building into + /opt/shibboleth. If you use a different layout or + location, most of the essential configuration files will be tweaked for you, + but watch for any exceptions.

    +

    On Windows, use of the installer is recommended. Visual Studio 6.0 + project files are included with the OpenSAML and Shibboleth source + distributions for source builds if maximum flexibility to deal with + security issues is desired.

    -

    3.c. Configure Apache 1.3.x

    +

    3.c. Configure Apache

      -
    1. Shibboleth includes configuration directives in the file +
    2. Shibboleth includes configuration directives in the files /opt/shibboleth/etc/shibboleth/apache.config - which must be added to the httpd.conf file used locally. It is - recommended that these directives simply be added to the end of the + and /opt/shibboleth/etc/shibboleth/apache2.config + which must be added to the httpd.conf file used + locally. It is recommended that these directives simply be added to the end of the existing httpd.conf file rather than trying to merge it in-line; step 2 describes the necessary modifications to the Apache startup script. The default configuration will often work, but if customization is necessary, these options may be modified:
      -
      LoadModule <module> - <pathname>
      -
      Specifies the title and location of the - shibrm_module resource manager and - shire_module SHIRE modules. These are - installed by default at /opt/shibboleth/libexec/mod_shibrm.so - and /opt/shibboleth/libexec/mod_shire.so
      -
      SHIREConfig <pathname> -
      +
      LoadModule <module> <pathname>
      +
      Specifies the name and location of the module, + installed by default at /opt/shibboleth/libexec/mod_shib_13.so + or /opt/shibboleth/libexec/mod_shib_20.so
      + +
      ShibConfig <pathname>
      Specifies the pathname - of the SHIRE's configuration file. Defaults to + of the Shibboleth configuration file. Defaults to /opt/shibboleth/etc/shibboleth/shibboleth.xml.
      -
      SHIREURL <url>
      - <Location <url>>
      + +
      ShibSchemaDir <path>
      +
      Specifies the path + of the Shibboleth schema folder. Defaults to + /opt/shibboleth/etc/shibboleth.
      + +
      <Location url>
        SetHandler <method>
      </Location>
      -
      Specifies the URL and - the method the target uses to handle - requests for Shibboleth-protected resources. Currently, - shib-shire-post is the only available - handler method. - SHIREURL is used by Shibboleth when re-directing the user to - the WAYF and <Location> by Apache; for - this reason, both URL specifications must - match. Note that the configuration file itself contains <>'s, and - Location should not be replaced.

      The - referenced URL can be either a partial - path or an absolute URL. The partial path allows each virtual server - to use its own hostname and port in the SHIRE for session cookie - purposes, while the absolute URL forces HTTP virtual servers to use - HTTPS for the SHIRE. Use of a full https:// - URL is advised.

      -
      ShibMapAttribute - <attribute-uri> <HTTP-header> [alias]
      -
      This command has been deprecated in favor of - the configuration support available in the Attribute Acceptance - Policy file. See section 4.e. It may be removed - in a future release.
      +

      (Apache 1.3 only) Specifies the relative path + and the handler the target uses to process + incoming sessions and lazy session startup for Shibboleth-protected + resources. This works in concert with the shireURL + settings in the XML configuration file. Any virtual locations that are to be + used for this purpose should be defined to Apache here.

      3. -
    3. These modifications must be made to the Apache - startup script on Unix:

      Add the following environment variable:

      -
      -

      SHIBCONFIG=/opt/shibboleth/etc/shibboleth/shibboleth.xml
      - export SHIBCONFIG

      -
      -

      If the SHIBCONFIG environment variable is not specified, Shibboleth - will use /opt/shibboleth/etc/shibboleth/shibboleth.xml - by default.

      -

      On Windows, the installer will set the path and SHIBCONFIG variable - for you in the system path, enabling Apache or IIS to be used.

    4. If the OpenSSL libraries are not in the system's search path, they - should be added to LD_LIBRARY_PATH. Generally - libtool's linker options will insure that the modules can locate the - Shibboleth libraries, but if not, you may need to add + should be added to the LD_LIBRARY_PATH used by + Apache. Generally libtool's linker options will insure that the modules + can locate the Shibboleth libraries, but if not, you may need to add /opt/shibboleth/lib to LD_LIBRARY_PATH as well.
    5. The SHAR must be started along with Apache. Among other methods on @@ -827,20 +736,21 @@ most minor "letter" updates should be usable.

      suggested that Apache's script be modified by adding:

      /opt/shibboleth/bin/shar -f &

      -

      Sample init.d scripts may be included with - future releases. Ensure that the environment variable referenced in - 3.c.2 are in place.

      +

      In most cases, the build process insures that the SHAR can locate + the configuration file and schemas, but the SHIB_CONFIG and SHIB_SCHEMAS + environment variables may be used as well. Command line options can also + be used to specify them.

      On Windows, the SHAR is a service and is managed separately.

    6. By default, the Shibboleth modules are configured to log information on behalf of Apache to the file - /opt/shibboleth/etc/shibboleth/shire.log, though this can be + /opt/shibboleth/var/log/shibboleth/shire.log, though this can be changed. For this log to be created, Apache must have permission to write to this file, which may require that the file be manually created and permissions assigned to whatever user Apache is configured to run under. If the file does not appear when Apache runs with the modules - loaded, check for permission problems.
      7. + loaded, check for permission problems.
    7. The options in shibboleth.xml must be - configured as documented in 4.a. Apache content will + configured as documented in 4.a. Apache content may then need to be modified for Shibboleth authentication. This is discussed in 4.d. It is recommended that the target then be tested as detailed in section 5.a.
      8. @@ -849,13 +759,14 @@ most minor "letter" updates should be usable.

      3.d. Configure Microsoft IIS

        -
      1. The package includes an ISAPI filter and bundled extension for SHIRE - POST processing in a single library, libexec\isapi_shib.dll. +
      2. The package includes an ISAPI filter and bundled extension for + session processing in a single library, libexec\isapi_shib.dll. This filter is configured using commands in - C:\opt\shibboleth\etc\shibboleth\shibboleth.xml. Make sure you've - added the library directory to the path as directed in - section 3.b.

        Installing the extension into IIS is a two step - process:

          + C:\opt\shibboleth\etc\shibboleth\shibboleth.xml (or wherever you've + installed the software). Make sure you or the installer has added the lib + directory to the path as directed in section 3.b. +

          Installing the extension into IIS is a two step process: +

          1. First, add the filter using the Internet Services Manager MMC console. Right click on the machine icon on the left, and edit the WWW Service master properties. On the "ISAPI Filters" @@ -863,9 +774,7 @@ most minor "letter" updates should be usable.

            above. The priority should be High, and once the filter is loaded, make sure it appears in the list below the "sspifilt" entry. Restart IIS and make sure the filter shows up with a green arrow. - Check the Windows event log if it fails to load. The default - configuration options are sparse, but they should allow the filter - to at least initialize.
            2. + Check the Windows event log if it fails to load.
          2. Secondly, map a special file extension, such as .shire, to the ISAPI library so that virtual URLs can be specified to invoke the SHIRE handler for each @@ -875,54 +784,39 @@ most minor "letter" updates should be usable.

            box should point to isapi_shib.dll, and the "Extension" can be set to anything unlikely to conflict, but .shire is assumed (and the dot must be - included). You should select the option to limit verbs to POST, and - you must uncheck the "Check that file exists" box.
            3. + included). You should NOT select the option to limit verbs, and + you MUST uncheck the "Check that file exists" box.
          3. (IIS 6 Only) A new Web Service Extension must be defined for Shibboleth; without this, the mapping from *.shire to isapi_shib.dll won't occur and a file error - will show. Add this extension with an arbitrary name and associate + will appear Add this extension with an arbitrary name and associate it with isapi_shib.dll.
        1. All other aspects of configuration are handled via the - shibboleth.xml file and associated XML-based - policy files described in subsequent sections. Particular use is made of - the per-hostname section feature that allows global settings to be - overridden per-site, and this permits different IIS instances to be - separately configured.
          2. -
        2. A special section must be added/uncommented in the - shibboleth.xml file to support IIS usage. The - [isapi] section must be used to map IIS - Instance ID numbers to fully-qualified hostnames that correspond to - named sections later in the file. Instance IDs are used in the IIS - metabase to identify web sites. They are applied starting with the - number 1 and number the web sites in order in the Internet Services - Manager from top to bottom. In the [isapi] - section, add lines in the following form: -
          -

          1=hostname.domain.com
          - 2=hostname2.domain.com
          - (etc...)

          -
          -

          At least an empty configuration section named - hostname.domain.com should then be added to the end of the file. - Any options specific to that web site can be added as documented in - later sections.

          3. + shibboleth.xml file and associated XML + files described in subsequent sections. Particular use is made of + the /SHIRE/Implementation/ISAPI element that allows the + IIS sites to be mapped to fully-qualified hostnames for proper request mapping. +
        3. Instance IDs are used in the IIS metabase to identify web sites. In older versions, + they are applied starting with 1(one) and number the web sites in order in the + Internet Services Manager from top to bottom. Newer versions appear to assign + some IID values with strange ASCII formulas applied to the site name. A simple + ASP or CGI script can be run within a site to dump the INSTANCE_ID header.
        4. See the following section for information on running the SHAR service on Windows.
        5. The options in shibboleth.xml must be configured as documented in 4.a. It is recommended - that the target then be tested as detailed in section - 5.a.
          6. + that the target then be tested as detailed in section 5.a.

      3.e. Running the SHAR on Windows

      The SHAR is a console application that is primarily designed to be installed as a Windows service. To run the process in console mode for - testing, the -console parameter is used. - Otherwise, parameters are used to install (or remove) the SHAR from the + testing or to diagnose major problems, the -console + parameter is used. Otherwise, parameters are used to install (or remove) the SHAR from the service database and subsequent control is via the Service Control Manager applet. The following command line parameters can be used:

      @@ -930,11 +824,19 @@ most minor "letter" updates should be usable.

      Allows the process to be started from a command prompt. Since the console will exit if the desktop user logs out, this is not suitable for production use, but may be useful for testing.
      +
      -check
      +
      Validates the general correctness of the configuration. + Not all problems can be detected this way, but the chance of successful startup + is high if the checking process does not log any errors.
      -config <pathname>
      Specifies the pathname of the SHAR's configuration file. Defaults to \opt\shibboleth\etc\shibboleth\shibboleth.xml - or the value of the SHIBCONFIG environment + or the value of the SHIB_CONFIG environment variable, if it is set.
      +
      -schemadir <path>
      +
      Specifies the path to the XML schema files. Defaults to + \opt\shibboleth\etc\shibboleth or the value of the + SHIB_SCHEMAS environment variable, if it is set.
      -install <servicename>
      Installs the SHAR as a named service in the Windows service database. A name should be provided if multiple instances of the -- 1.7.10.4