Tweaks for 1.2.1
authorcantor <cantor@ab3bd59b-922f-494d-bb5f-6f0a3c29deca>
Tue, 2 Nov 2004 19:28:44 +0000 (19:28 +0000)
committercantor <cantor@ab3bd59b-922f-494d-bb5f-6f0a3c29deca>
Tue, 2 Nov 2004 19:28:44 +0000 (19:28 +0000)
git-svn-id: https://subversion.switch.ch/svn/shibboleth/java-idp/trunk@1180 ab3bd59b-922f-494d-bb5f-6f0a3c29deca

doc/DEPLOY-GUIDE-TARGET.html

index 01efcb0..b2c29f3 100644 (file)
@@ -134,9 +134,9 @@ color: #00FF00
 <h2>Shibboleth Target Deployment Guide</h2>
 </center>
 <p>Shibboleth Target Deployment Guide<br>
-Shibboleth Version 1.2<br />
-May 10, 2004<br />
-<h3>This version of the deploy guide is for Shibboleth v1.2. For documentation 
+Shibboleth Version 1.2.1<br />
+November 15, 2004<br />
+<h3>This version of the deploy guide is for Shibboleth v1.2.1. For documentation 
 related to prior versions of Shibboleth, please consult the appropriate branch 
 in the Shibboleth CVS.</h3>
 <h3>The default configuration of Shibboleth is <b>not</b> secure and should not be
@@ -147,10 +147,10 @@ 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.</h3>
 
-<p>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. For a list of new features, please refer to the NEWS.txt
-file in the doc/ folder of the distribution.</p>
+<p>The Shibboleth target implementation was substantially redesigned in version 1.2.
+1.2.1 is a bug-fix release intended to address stability, major bugs, and small issues
+that have arisen in the last 6 months. For a list of new features and fixes, please
+refer to the NEWS.txt file in the doc/ folder of the distribution.</p>
 
 <p>Before starting, please sign up for all applicable
 <a href="http://shibboleth.internet2.edu/shib-misc.html#mailinglist">mailing 
@@ -436,9 +436,9 @@ SHAR and SHIRE are implemented entirely in C/C++. These are the recommendations
 and requirements for a successful implementation of a Shibboleth target.</p>
 <h4><a name="2.a."></a>2.a. Requirements</h4>
 <blockquote>
-    <p>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 Sun/ONC RPC mechanism to communicate 
+    <p>Shibboleth currently supports Windows NT/2000/XP/2003, Linux, Solaris, 
+    and Mac OS X. At present, Shibboleth consists of Apache/IIS plugins and a 
+    separate SHAR process. The plugins use the Sun-RPC mechanism to communicate 
     with the SHAR over Unix domain or TCP sockets. The target&#39;s web servers must 
     be running <a href="http://http://www.apache.org/dist/httpd/">Apache</a> 
     1.3+, 2.0+, or Microsoft IIS 4.0+ More precise technical 
@@ -447,10 +447,9 @@ and requirements for a successful implementation of a Shibboleth target.</p>
 <h4><a name="2.b."></a>2.b. Join a Federation</h4>
 <blockquote>
     <p>While it is not necessary for a target or origin to join a federation, 
-    doing so greatly facilitates the implementation of multilateral trust 
-    relationships. Each federation will have a different application process.</p>
-    <p>For more information on federations, refer to <a href="#1.d.">1.d</a> or 
-    the Shibboleth v1.0 architectural document.</p>
+    doing so can facilitate the implementation of multilateral trust 
+    relationships. Each federation will have a different application process.
+    For more information on federations, refer to <a href="#1.d.">1.d</a>.</p>
     <p>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
@@ -465,7 +464,7 @@ and requirements for a successful implementation of a Shibboleth target.</p>
     Shibboleth is as secure as possible, there are several recommended security 
     precautions which should be in place at local sites.</p>
     <ol type="i">
-        <li>SSL use is optional for target sites, but should be used if at all 
+        <li>While SSL use is optional for target sites,it should be used if at all 
         possible, at least in the processing of incoming sessions (called the 
         SHIRE URL or assertion consumer service). Federation guidelines should 
         be considered when determining whether to implement SSL, and, in 
@@ -587,10 +586,10 @@ and requirements for a successful implementation of a Shibboleth target.</p>
 <hr>
 <h3><a name="3."></a>3. Installation</h3>
 <h4><a name="3.a."></a>3.a. Software Requirements</h4>
-<p>The Shibboleth project makes binary packages available only for Windows,
-that are precompiled against recent releases of various required libraries such 
-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 
+<p>The Shibboleth project makes official binary packages available only for
+Windows, precompiled against recent releases of various required libraries such 
+as OpenSSL. Binaries or RPMs 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 
@@ -600,7 +599,7 @@ distributions.</p>
 <p>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 
+or search 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 &quot;letter&quot; updates should be usable.</p>
 <blockquote>
@@ -677,8 +676,8 @@ most minor &quot;letter&quot; updates should be usable.</p>
                 environment variables for you. A default SHAR service can also 
                 be installed, or you can install it manually using the 
                 instructions in this guide.</p>
-                <p>Note that debug/symbol versions of the libraries and software 
-                are included, and may be used by appending &quot;debug&quot; to the 
+                <p>Note that debug versions of the libraries and software are
+                included, and may be used by appending &quot;debug&quot; to the 
                 Shibboleth library path and using the corresponding modules and 
                 binaries. If you do so, be aware that Apache and other modules 
                 must also be compiled with Microsoft&#39;s debug runtime (via the /MDd 
@@ -703,14 +702,7 @@ most minor &quot;letter&quot; updates should be usable.</p>
             </li>
             </ul>
         </li>
-        <li>RedHat Linux 9 / Fedora
-            <ul type="disc">
-            <li>
-                <p>Apache 2.0 is included as the default Apache version in this release.</p>
-            </li>
-            </ul>
-        </li>
-        <li>RedHat Enterprise Linux
+        <li>RedHat Linux 9 / Fedora / RH Enterprise
             <ul type="disc">
             <li>
                 <p>Apache 2.0 is included as the default Apache version in this release.</p>
@@ -733,7 +725,14 @@ most minor &quot;letter&quot; updates should be usable.</p>
             </li>
             </ul>
         </li>
-        <li>Solaris 2.6+:
+        <li>Macintosh OS X 10.3
+            <ul type="disc">
+            <li>
+                <p>Apache 1.3 is included as the default Apache version in this release.</p>
+            </li>
+            </ul>
+        </li>
+        <li>Solaris 2.8+:
             <ul type="disc">
             <li>
                 <p>The shared library version of OpenSSL is required by 
@@ -830,7 +829,9 @@ most minor &quot;letter&quot; updates should be usable.</p>
         <li>If the OpenSSL libraries are not in the system&#39;s search path, they 
         should be added to the <span class="fixed">LD_LIBRARY_PATH</span> used by
         Apache. You will also usually need to add <span class="fixed">/opt/shibboleth/lib</span>
-        to <span class="fixed">LD_LIBRARY_PATH</span> as well.</li>
+        to <span class="fixed">LD_LIBRARY_PATH</span> as well. Note that on Mac OS X, the
+               environment variable used for this purpose is named
+               <span class="fixed">DYLD_LIBRARY_PATH</span></li>
         <li>The SHAR must be started along with Apache. Among other methods on 
         Unix, this can be done either by creating a separate SHAR startup script 
         or by modifying Apache&#39;s RC script to start/stop the <span class="fixed">
@@ -842,7 +843,10 @@ most minor &quot;letter&quot; updates should be usable.</p>
         the configuration file and schemas, but the SHIBCONFIG and SHIBSCHEMAS
         environment variables may be used as well. Command line options can also
         be used to specify them.</p>
-        <p>On Windows, the SHAR is a service and is managed separately.</li>
+        <p>On Windows, the SHAR is a service and is managed separately. Newer versions
+               of Windows support automatic restart of failed services. We suggest using this
+               feature to restart the SHAR when it fails. Although stability is good,
+               maximum reliability will be achieved by monitoring the process.</li>
         <li>By default, the Shibboleth modules are configured to log information
         on behalf of Apache to the file <span class="fixed">
         /opt/shibboleth/var/log/shibboleth/shire.log</span>, though this can be
@@ -852,7 +856,7 @@ most minor &quot;letter&quot; updates should be usable.</p>
         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.</li>
+        problems or change the location used.</li>
         <li>The options in <span class="fixed">shibboleth.xml</span> must be 
         configured as documented in <a href="#4.a.">4.a</a>. Apache content may 
         then need to be modified for Shibboleth authentication. This is 
@@ -879,7 +883,7 @@ most minor &quot;letter&quot; updates should be usable.</p>
             above. The priority should be High, and once the filter is loaded, 
             make sure it appears in the list <b>below</b> the &quot;sspifilt&quot; entry. 
             Restart IIS and make sure the filter shows up with a green arrow. 
-            Check the Windows event log if it fails to load.</li>
+            Check the Windows event log and/or shire.log if it fails to load.</li>
             <li type="a">Secondly, map a special, distinct file extension, such as
             <span class="fixed">.shire</span>, to the ISAPI library so that 
             virtual URLs can be specified to invoke the extension handler for each 
@@ -898,21 +902,22 @@ most minor &quot;letter&quot; updates should be usable.</p>
             Service Extension must be defined for Shibboleth; without this, the
             mapping from <span class="fixed">*.shire</span> to <span
             class="fixed">isapi_shib.dll</span> won't occur and a file error
-            will appear  Add this extension with an arbitrary name and associate
+            will appear. Add this extension with an arbitrary name and associate
             it with <span class="fixed">isapi_shib.dll</span>.</li>
         </ol>
         </li>
         <li>All other aspects of configuration are handled via the
         <span class="fixed">shibboleth.xml</span> file and associated XML
         files described in subsequent sections. Particular use is made of 
-        the <span class="fixed">/SHIRE/Implementation/ISAPI</span> element that allows
-        IIS sites to be mapped to scheme, hostname, and port for proper request
-        mapping and generation of redirects.</li>
+        the <span class="fixed">/SHIRE/Implementation/ISAPI</span> element
+               that allows IIS sites to be mapped to a hostname for proper request
+               mapping and generation of redirects.</li>
         <li>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.</li>
+        ASP or CGI script can be run within a site to dump the INSTANCE_ID header.
+               Newer versions actually list the site ID in the GUI console.</li>
         <li>See the following section for information on running the SHAR 
         service on Windows.</li>
         <li>The options in <span class="fixed">shibboleth.xml</span> must be 
@@ -964,7 +969,7 @@ most minor &quot;letter&quot; updates should be usable.</p>
 <h4><a name="4.a."></a>4.a. Configuring <span class="fixed">shibboleth.xml</span></h4>
 <blockquote>
        <p>The configuration for the target is mostly contained within <span class="fixed">shibboleth.xml</span>,
-       located by default at <span class="fixed">\opt\shibboleth\etc\shibboleth\shibboleth.xml</span>.
+       located by default at <span class="fixed">/opt/shibboleth/etc/shibboleth/shibboleth.xml</span>.
        The target comes pre-configured with certificates and settings that will work against a test origin
        running on the same server; however, there are several values that must later be changed to interoperate
        with other sites securely and effectively.</p>
@@ -1011,22 +1016,19 @@ most minor &quot;letter&quot; updates should be usable.</p>
 
         <a class="fixedlink" href="#confRequestMapProvider">&lt;RequestMapProvider type=&quot;edu.internet2.middleware.shibboleth.target.provider.XMLRequestMap&quot;&gt;</a>
             <a class="fixedlink" href="#confRequestMap">&lt;RequestMap applicationId=&quot;default&quot;&gt;</a>
-                <a class="fixedlink" href="#confHost">&lt;Host name=&quot;localhost&quot; scheme=&quot;https&quot;&gt;</a>
+                <a class="fixedlink" href="#confHost">&lt;Host name=&quot;localhost&quot;&gt;</a>
                     <a class="fixedlink" href="#confPath">&lt;Path name=&quot;secure&quot; requireSession=&quot;true&quot; exportAssertion=&quot;true&quot;&gt;
-                            &lt;!-- Example shows a subfolder on the SSL port assigned to a separate &lt;Application&gt; --&gt;
+                            &lt;!-- Example shows a subfolder on the default ports assigned to a separate &lt;Application&gt; --&gt;
                             &lt;Path name=&quot;admin&quot; applicationId=&quot;foo-admin&quot;/&gt;
                        &lt;/Path&gt;</a>
                 <a class="fixedlink" href="#confHost">&lt;/Host&gt;</a>
-                <a class="fixedlink" href="#confHost">&lt;Host name=&quot;localhost&quot; scheme=&quot;http&quot;&gt;</a>
-                    <a class="fixedlink" href="#confPath">&lt;Path name=&quot;secure&quot; requireSession=&quot;true&quot; exportAssertion=&quot;true&quot;/&gt;</a>
-                <a class="fixedlink" href="#confHost">&lt;/Host&gt;</a>
             <a class="fixedlink" href="#confRequestMap">&lt;/RequestMap&gt;</a>
         <a class="fixedlink" href="#confRequestMapProvider">&lt;/RequestMapProvider&gt;</a>
 
         &lt;!-- IIS only:
         <a class="fixedlink" href="#confImplementation">&lt;Implementation&gt;</a>
             <a class="fixedlink" href="#confISAPI">&lt;ISAPI normalizeRequest=&quot;true&quot;&gt;</a>
-                <a class="fixedlink" href="#confSite">&lt;Site id=&quot;1&quot; scheme=&quot;https&quot; name=&quot;localhost&quot; port=&quot;443&quot;/&gt;</a>
+                <a class="fixedlink" href="#confSite">&lt;Site id=&quot;1&quot; name=&quot;localhost&quot; /&gt;</a>
             <a class="fixedlink" href="#confISAPI">&lt;/ISAPI&gt;</a>
         <a class="fixedlink" href="#confImplementation">&lt;/Implementation&gt;</a>
         --&gt;
@@ -1106,7 +1108,10 @@ most minor &quot;letter&quot; updates should be usable.</p>
         <li> 
         <p>The main <a href="#confApplications"><span class="fixed">Applications</span></a> element's
         <span class="fixed">providerId</span> attribute must be changed to reflect the URI this target will
-        use to identify itself to origins by default. This will often be approved or supplied by a federation.</p>
+        use to identify itself to origins by default. This will often be submitted to a federation for
+               approval, but is generally a URI chosen by the deployer to uniquely identify his/her service.
+               For example, if Amazon.com were running Shibboleth (stop laughing), its identifier might be
+               <span class="fixed">https://amazon.com/shibboleth</span></p>
                </li>
                <li>
                <p>The <span class="fixed">supportContact</span> and error templates for the target found in the
@@ -1250,7 +1255,8 @@ most minor &quot;letter&quot; updates should be usable.</p>
         as an audience value.</p>
         <p>Within an <a href="#confApplication"><span class="fixed">Application</span></a> element, this setting is not
         inherited from the <a href="#confApplications"><span class="fixed">Applications</span></a> element. Any values
-        desired must be specified. In most cases, this element can be omitted.</p>
+        desired must be specified. In most cases, this element can be omitted unless required for supporting legacy
+               origins running older Shibboleth versions.</p>
         </dd>
 
         <dd class="attribute"><a name="confCAPath"><span class="fixed">&lt;CAPath&gt;<i>pathname</i>&lt;/CAPath&gt;</span></a></dd>
@@ -1369,7 +1375,8 @@ most minor &quot;letter&quot; updates should be usable.</p>
             <ul>
             <li><span class="fixed">scheme</span>: This specifies the protocol on which this host responds.
             Valid choices are <span class="fixed">http</span>, <span class="fixed">https</span>, <span class="fixed">ftp</span>,
-            <span class="fixed">ldap</span>, and <span class="fixed">ldaps</span>.</li>
+            <span class="fixed">ldap</span>, and <span class="fixed">ldaps</span>. If omitted, both <span class="fixed">http</span>
+                       and <span class="fixed">https</span> are in effect.</li>
             <li class="mandatory"><span class="fixed">name</span>: This is the fully-qualified domain name of the host.
             This appended to the <span class="fixed">scheme</span> must match what is contained in the URL for the element's
             settings to apply to the request.</li>
@@ -1400,7 +1407,7 @@ most minor &quot;letter&quot; updates should be usable.</p>
         <dd class="value">
         <p>The configuration information for Shibboleth targets deployed on Microsoft IIS is stored inside this container element.
         This element must contain one or more <a href="#confSite"><span class="fixed">Site</span></a> elements, each of which
-        maps an INSTANCE ID value to a hostname. If <span class="fixed">normalizeRequest</span> is
+        maps an INSTANCE ID value to a default hostname. If <span class="fixed">normalizeRequest</span> is
         <span class="fixed">true</span> (the default), all redirects and computed request URLs generated by Shibboleth will
         be created using the hostname assigned to the site instance handling the request. If <span class="fixed">false</span>,
         the browser's supplied URL is sometimes used to compute the information. Placed inside the
@@ -1667,7 +1674,10 @@ cookieProps=&quot;<i>URL</i>&quot;&gt;</span></a></dd>
         <dd class="attribute"><a name="confSite"><span class="fixed">&lt;Site <span class="mandatory">id=&quot;<i>INSTANCE_ID</i>&quot; name=&quot;<i>fqdn</i>&quot;</span> scheme=&quot;<i>http/https</i>&quot; port=&quot;<i>integer</i>&quot;&gt;</span></a></dd>
         <dd class="value">
         <p>This element is placed in the <a href="#confISAPI"><span class="fixed">ISAPI</span></a> element to specify a
-        mapping from individual instance ID's to the corresponding hostname, port, and scheme.</p>
+        mapping from individual instance ID's to a corresponding hostname. The port and scheme can also be specified, but
+               should normally be left out, enabling them to be determined from the browser request. Note that while IIS permits
+               multiple hostnames to be assigned to a web site, only one can be specified here. If you really need to allow for
+               multiple names (unusual), you should set the <span class="fixed">>normalizeRequest</span> attribute to false.</p>
         </dd>
 
         <dd class="attribute"><a name="confTCPListener"><span class="fixed">&lt;TCPListener <span class="mandatory">address=&quot;<i>pathname</i>&quot;  port=&quot;<i>integer</i>&quot;</span> acl=&quot;<i>ip</i>&quot;&gt;</span></a></dd>
@@ -2270,7 +2280,7 @@ cookieProps=&quot;<i>URL</i>&quot;&gt;</span></a></dd>
     <p>A complete command issued to <span class="fixed">siterefresh</span> might 
     take the form:</p>
     <blockquote>
-        <p><span class="fixed">/opt/shibboleth/bin/siterefresh --out IQ-sites.xml --cert internet2.pem \<br>
+        <p><span class="fixed">/opt/shibboleth/bin/siterefresh --out IQ-sites.xml --cert inqueue.pem \<br>
         --url http://wayf.internet2.edu/InQueue/IQ-sites.xml </span></p>
     </blockquote>
     <p>It is recommended that such commands be added to a <span class="fixed">
@@ -2378,5 +2388,4 @@ with a thorough description of errors and configurations used.</p>
 </blockquote>
 
 </body>
-
 </html>