UpgradingFromV2

The upgrade process is designed to be seamless and is functionally the same as upgrading V2 in the past. Depending on the platform and how you've installed V2, upgrading to V3 should be done in the same fashion (yum update, port upgrade, Windows Installer, make install, etc.) and the result should be a functional system, with the logs indicating that the software and library versions are updated and warnings about the detection of the older configuration namespace.

The essential information you need is found on the ReleaseNotes page, in which you will find a list of changes and altered behavior, and an explanation of how the configuration format has been "forked" to distinguish between older installations and a fresh install. An upgraded system is expected to initially run on the older configuration and the software will adjust its behavior accordingly, with some limited exceptions that are discussed in the notes.

One issue to highlight is that if you haven't ever modified the attribute-map.xml file, an RPM upgrade will replace it with the new default version, and an old mapping for an incorrect version of eduPersonTargetedID was removed in this release, so this could impact a system still making use of that broken attribute form. Just edit the file with a comment before upgrading to prevent this.

Once a system is upgraded and stable, carve out a small amount of time to review the warnings in the log for any deprecated settings or features, and establish a testing environment configured as a mirror of production. You can clean up your configuration in one of two ways:

• The simplest thing in most cases is just to update your shibboleth2.xml and security-policy.xml files in place by changing the namespace declaration at the top of the file from urn:mace:shibboleth:2.0:native:sp:config to urn:mace:shibboleth:3.0:native:sp:config (there are usually two mentions of the namespace in the root element). Note the difference there, the 2.0→ 3.0 in the string.

  Be sure to review all "MetadataProvider" elements in the shibboleth2.xml file for "file" and "uri" attributes.  These attribute names are no longer valid in the 3.0 namespace and must be replaced with the "path" and "url" attribute names.  Examples below.

  Old MetadataProvider

  <MetadataProvider type="XML" uri="http://federation.org/federation-metadata.xml" backingFilePath="federation-metadata.xml" reloadInterval="7200"> <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/> <MetadataFilter type="Signature" certificate="fedsigner.pem"/> </MetadataProvider> <MetadataProvider type="XML" file="idp-metadata.xml"/>

  New MetadataProvider

  <MetadataProvider type="XML" url="http://federation.org/federation-metadata.xml" backingFilePath="federation-metadata.xml" reloadInterval="7200"> <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/> <MetadataFilter type="Signature" certificate="fedsigner.pem"/> </MetadataProvider> <MetadataProvider type="XML" path="idp-metadata.xml"/>

• Alternatively you can start with the default shibboleth2.xml.dist file and transfer your settings to a new copy of shibboleth2.xml, but that has a tendency to break things because it's hard to reproduce complex settings accurately.

The V3 default filename remains "shibboleth2.xml" to facilitate the upgrade process. Any settings that are flagged with warnings may be removed from the updated XML schema and prevent the system from loading the file if the namespace is updated, so they should be corrected as part of the process and once the system is operating with the new file you're done.

If the warning doesn't explicitly mention how to replace a setting or what the alternative syntax should be, we will eventually capture that information on this page.

Note that as of V3.1, the XMLAttributeFilter configuration syntax has been updated to align with the IdP software, and the "basic" and "saml" XML namespaces are now deprecated. Use of those namespaces will emit warnings (usually quite a few of them).