Latest changes from Steven.
[java-idp.git] / doc / UPGRADE-GUIDE.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3 <html>
4   <head>
5
6     <title>Shibboleth Upgrade Guide</title>
7     <meta http-equiv="Content-Type" content=
8     "text/html; charset=utf-8">
9     <style type="text/css">
10
11 html
12 {       
13 background-color: #FFFFFF;
14 color: #000000;
15 margin: .5em;
16 }
17 a:visited
18 {
19 color: #999999;
20 }
21 a:link
22 {
23 color: #990000;
24 }
25 a:active
26 {
27 color: #440000;
28 }
29 dl
30 {
31 background-color: #DDDDDD;
32 background-image: none;
33 margin: 5px;
34 padding: 0px;
35 border-style: solid;
36 border-bottom-width: 2px;
37 border-top-width: 2px;
38 border-left-width: 2px;
39 border-right-width: 2px;
40 }
41 dt
42 {
43 background-color: #DDDDDD;
44 background-image: none;
45 margin: 1px;
46 padding: 1px;
47 }
48 dd
49 {
50 background-color: #DDDDDD;
51 background-image: none;
52 margin: 0px;
53 padding: 1px;
54 }
55 .attribute
56 {
57 font-size: 115%;
58 font-color: #000000;
59 text-align: left;
60 background-color: #DDDDDD;
61 border: 1px black inset;
62 background-image: none;
63 margin: 0px;
64 padding: 2px;
65 }
66 .value
67 {
68 font-color: #000000;
69 text-align: left;
70 background-color: #EEEEEE;
71 background-image: none;
72 padding-top: 0em;
73 padding-bottom: 0.5em;
74 padding-right: 1em;
75 padding-left: 5em;
76 border-style: solid;
77 border-bottom-width: none;
78 border-top-width: none;
79 border-left-width: 1px;
80 border-right-width: 1px;
81 }
82 .attributeopt
83 {
84 font-size: 115%;
85 font-color: #000000;
86 text-align: left;
87 background-color: #BCBCEE;
88 border: 1px black inset;
89 background-image: none;
90 margin: 0px;
91 padding: 2px;
92 }
93 .valueopt
94 {
95 font-color: #000000;
96 text-align: left;
97 background-color: #DDDDFF;
98 background-image: none;
99 padding-top: 0em;
100 padding-bottom: 0.5em;
101 padding-right: 1em;
102 padding-left: 5em;
103 border-style: solid;
104 border-bottom-width: none;
105 border-top-width: none;
106 border-left-width: 1px;
107 border-right-width: 1px;
108 }
109 .attributelong
110 {
111 font-size: 85%;
112 font-color: #000000;
113 text-align: left;
114 background-color: #DDDDDD;
115 border: 1px black inset;
116 background-image: none;
117 margin: 0px;
118 padding: 2px;
119 }
120 .attributeoptlong
121 {
122 font-size: 85%;
123 font-color: #000000;
124 text-align: left;
125 background-color: #BCBCEE;
126 border: 1px black inset;
127 background-image: none;
128 margin: 0px;
129 padding: 2px;
130 }
131 .demo
132 {
133 background-color: #EEEEEE;
134 padding: 3px;
135 }
136 .fixedwidth
137 {
138 font-family: monospace;
139 font-size: 90%;
140 font-color: #121212;
141 }
142
143   </style>
144   </head>
145
146   <body link="red" vlink="red" alink="black" bgcolor="white">
147     <center>
148       <h2>Shibboleth Upgrade Guide</h2>
149     </center>
150         Shibboleth Upgrade Guide<br>
151 Shibboleth Version 1.1<br>
152 July 29, 2003<br>
153
154 <br>
155 <hr>
156 <br>
157
158 <center><table width="500" border="0"><tr><td align="center" width="250">
159 <a href="#origin">Latest Origin Upgrade</a>
160 </td><td align="center" width="250">
161 <a href="#target">Latest Target Upgrade</a>
162 </td></tr></table></center>
163
164 <p>This guide contains suggested steps to upgrade from a Shibboleth 1.0 installation to a Shibboleth 1.1 installation.  There are many ways to do this and some steps may need to be modified to reflect differences in the local installation.</p>
165
166 <p>Shibboleth 1.1 is fully backward compatible with Shibboleth 1.0; however, some features have been deprecated, so all deployments are highly encouraged to move to current configurations.  For a full list of new and changed functionality, consult the header of the <a href="http://shibboleth.internet2.edu/">Shibboleth Deployment Guides</a>.</p>
167
168 <a name="origin"></a><h3>Origin</h3>
169
170 <a name="origin1.0to1.1"></a><h4>v1.0 to v1.1</h4>
171
172 <p>All Shibboleth 1.0 configuration specifications are still current as of Shibboleth 1.1.</p>
173
174 <ol type="1">
175   <li>Shutdown Tomcat.
176   <li>Copy the following files to a scratch directory:
177     <ol type="a">
178       <li><span class="fixedwidth">origin.properties</span> (defaults to <span class="fixedwidth">$CATALINA_HOME/webapps/shibboleth/WEB-INF/classes/conf/origin.properties</span>)</li>
179       <li><span class="fixedwidth">resolver.xml</span> (defaults to <span class="fixedwidth">$CATALINA_HOME/webapps/shibboleth/WEB-INF/classes/conf/resolver.xml</span>)</li>
180       <li>The logging configuration file (defaults to <span class="fixedwidth">$CATALINA_HOME/webapps/shibboleth/WEB-INF/classes/conf/log4j.properties</span>)</li>
181       <li>The HS' Keystore (defaults to <span class="fixedwidth">$CATALINA_HOME/webapps/shibboleth/WEB-INF/classes/conf/keystore.jks</span>)</li>
182       <li>The web application deployment descriptor (defaults to <span class="fixedwidth">$CATALINA_HOME/webapps/shibboleth/WEB-INF/web.xml</span>)</li>
183       <li>Any created ARP's (defaults to <span class="fixedwidth">$CATALINA_HOME/webapps/shibboleth/WEB-INF/classes/conf/arps/*)</span></li>
184       <li>The crypto handle repository keystore <font color="#5555EE">(if used)</font> (defaults to <span class="fixedwidth">$CATALINA_HOME/webapps/shibboleth/WEB-INF/classes/conf/handle.jks</span>)</li>
185       <li>The targetedId attribute keystore <font color="#5555EE">(if used)</font> (defaults to <span class="fixedwidth">$CATALINA_HOME/webapps/shibboleth/WEB-INF/classes/conf/persistent.jks</span>)</li>
186     </ol>
187   </li>
188   <li>Delete the old origin.</li>
189   <li>Deploy the new origin.</li>
190   <li>Copy over the files from the scratch directory.</li>
191   <li>Start up Tomcat.</li>
192 </ol>
193
194 <a name="target"></a><h3>Target</h3>
195
196 <a name="target1.0to1.1"></a><h4>v1.0 to v1.1</h4>
197
198 <p>Shibboleth 1.1 handles attributes differently than 1.0.  Attributes are now added to the target in one place rather than three.  The <span class="fixedwidth">[attributes]</span> section may be deleted
199 from <span class="fixedwidth">shibboleth.ini</span>, and all <span class="fixedwidth">ShibMapAttribute</span> commands maybe be removed from the Apache configuration.
200 Any customization of the <span class="fixedwidth">ShibMapAttribute</span> parameters needs to be reflected in <span class="fixedwidth">AAP.xml</span>, as documented in the <a href="http://marsalis.internet2.edu/cgi-bin/viewcvs.cgi/*checkout*/shibboleth/c/doc/DEPLOY-GUIDE-TARGET.html?rev=HEAD&amp;only_with_tag=HEAD&amp;content-type=text/html#4.e.">Shibboleth Target Deploy Guide</a>.</p>
201
202 <ol>
203   <li>Stop the SHAR and Apache.</li>
204   <li>Move the old Shibboleth to a new folder:
205     <blockquote><span class="fixedwidth">
206       $ mv /opt/shibboleth /opt/shibboleth-old
207     </span></blockquote>
208   </li>
209   <li>Unpack/install the new .tarball into <span class="fixedwidth">/opt/shibboleth</span>.</li>
210   <li>Copy the old configuration files back into the new Shibboleth's folder:
211     <blockquote><span class="fixedwidth">
212       $ cp /opt/shibboleth-old/etc/shibboleth/shibboleth.ini \<br>
213       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/opt/shibboleth-old/etc/shibboleth/*.xml \<br>
214           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/opt/shibboleth-old/etc/shibboleth/*.log* \<br>
215           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/opt/shibboleth-old/etc/shibboleth/*.html \<br>
216           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/opt/shibboleth/etc/shibboleth
217         </span></blockquote>
218   </li>
219   <li>If changes have been made to <span class="fixedwidth">apache.config</span> and
220 it is being used to configure Apache, it should be copied over as well in a similar fashion.</li>
221   <li>Copy over the SHAR's key and certificate if they are stored in the old <span class="fixedwidth">/opt</span> tree.
222   <li>Restart the target.</li>
223 </ol>
224
225 </body>
226 </html>
227