Locations and Assumptions about the Windows Installer- DRAFT

TheWix Installer is broken up into 6 parts

1. The Merge modules
2. Registry setting and interrogation
3. Executables
4. Architecture insensitive files
5. Editing configuration
6. The GUI

Each of these has its own specifc locations and assumptions. This entry documents current assumptions (although as always the code is the definitive statement)

1. The Merge Modules

Most merge modules are installed under:

• %SystemDrive%\Program Files\Shibboleth\SP (For native architecture binaries and documentation)
• %SystemDrive%\Program Files (x86)\Shibboleth\SP (For native architecture binaries and documentation)

Three directories are populated below this:

• lib and lib\debug contain DLLs and executables
• doc contains license materials and so forth.

Additionally three merge modules populate

• %SystemDrive%\Program Files\Shibboleth\SP\xml (Vista and later)
• %SystemDrive%\Documents and Settings\All Users\Application Data\Shibboleth\SP\xml (Win2003 and earlier)

By the joys of symbolic links, backwards compatibility can be maintained across all platforms by opening %ALLUSERSAPPPROFILE%\Application Data\Shibboleth\SP\xml. This has the advantage of not requiring special knowledge about which is the boot device.

The merge modules do NOT make changes to the path. It is as assumption that the parent installer will make this change.

The merge modules do NOT include the CRTL(s)

The components with associated merge modules are listed below. All component have at least two (architecture specific) merge modules associated. Some components have a third architecture free merge module (this is needed because of linkage restrictions around merge modules, components, and architectures)

Curl

• The associated DLL has a version free name (so this API is guaranteed to be forward compatible)
• Installs libcurl.dll and curl.exe (and debug)

FastCGI

• The associated DLL has a version free name (so this API is guaranteed to be forward compatible)
• Installs libfcgi.dll (and debug) and FASTCGI.LICENSE

Log4Shib

• Installs log4shib.dll and NTEventLogAppender.dll (and debug) and LOG4CPP.LICENSE
• NTEventLogAppender.dll has a version free name; log4shib.dll does not.

OpenSAML

• Installs saml.dll, samlsign.exe, xmltooling.dll and xmltoolinglite.dll (and debug).
• Also installs CREDITS.txt, LICENSE.txt, NOTICE.txt, README.txt and RELEASE.txt
• A third (architecture independent) merge module installed the schema files and catalog to PATH\xml\opensaml and {{PATH\xml\xmltooling }}

OpenSSL

• Installs libeay32.dll, ssleay32.dll, openssel.exe (and debug) and OPENSSL.LICENSE

Shibboleth

• Installs shibsp.dll and shibsplite.dll (and debug). NOTE that the version is NOT the same as the current shibboleth major version.
• A third (architecture independent) merge module installed the schema files and catalog to PATH\xml\shibboleth

Xerces

• Installs xerces.dll (and debug).

XmlSec

• Installs xsec.dll, c14n.exe, checksig.exe, cipher.exe, siginf.exe, templatesign.exe, txfmout.exe (and debug).

XmlTooling

Zlib

• Installs zlib.dll (and debug).

2. Registry setting and interrogation

This is done by two (related, but architecture sensitive) Fragments. It:

• Looks up previous installs (so as to deny incompatible upgrades) using the same mechanism as the old installers
• Looks up (in the 32 bit registry) and, if we are installing the IIS filter, stores (in both registries) the SSO extension
• Sets up the icon for the Add/Remove Programs window
• Looks up any parameters passed to initial install (if there was one). A very few of these are used to allow for seamless upgrade. The rest are there for historic interest.
• Looks to see whether the Shibd_default service is installed. This is used during an upgrade to control whether to restart the service.
• In addition, the IISMAJORVERSION p[roperty (available via the WiX plugin library) is interrogated.

3. Executables

These are all installed in a series of directories under a user chosen directory (default \opt\shibboleth-sp

• lib/lib64\shibboleth (and debug subdirectories): contains the WSebserver plugins (*.so, Isapi_shib.dll and Nsapi_shib.dll, also shibauthorizer.exe and shibresponder.exe
• bin/bin64 (and debug): mdquery.exe and resolvertest.exe
• sbin/sbin64 : shibd.exe

4. Architecture Insensitive files

These are all installed below the same folder as the executables, to:

• doc\shibboleth: main.css and the same license related files as the Shibboleth merge module
• etc\shibboleth: upgrade.xsl, example-metadata.xml, examples-shibboleth2.xml, keygen.bat and xsltproc.js. These are un-installable but will be updated (if the file versioning rules allow)
• etc\shibboleth\dist: A whole bunch of files These are all un-installable and will be updated. See below for how these files are then handled.
• var\log, var\run are both created.

5. Installing and editing configuration. Logging

• Editing the config files.
  • The same process as currently (note that some of the editing will be moved to the merge modules in order to get the catalogs located correctly)
  • This process will be run on installs and on upgrades, but the edit code is sensitive to not overwriting these files. Thus files can be via this mechanism on upgrades.
  • The files created are never un-installed.
• Editing IIS. This will be roughly the same as currently but
  • The dialog is not offered if IIS is not installed, nor is any other work scheduled.
  • Architecture sensitive DLLs for the x64 version
  • The install the dlls dance will only be called if we know this is a from fresh install
  • The uninstall will only be called if we know this is a not an upgrade
• Edit the Service (x64 only)
  • The service is declared (because it has to be done there) with the 32 bit install of shibd.
  • IFF we are doing the first install and the user has specified x64, then the path to shibd is changed to point at the x64 prior to the service being started.
  • The Service is only declared if specified by INSTALL_SHIBD_FILTER and this is detected as a first time install (not an upgrade)
  • The Service is only removed if this is detected as a last uninstall (not an upgrade)
• Environment Variables
  • Add the lib direcrtory(s) that the merge modules installed into into the path
  • Add (currently via javascript) SHIBSP_PREFIX to point to the shib install dir
• Logging
  • The VBScript do some minimal logging to path\var\log\Installer.log

6. The GUI (and not) & command files

The GUI is integrated into the WiX standard GUI so only two dialogs (instal and update) are used. The plumbing was derived from analaysis of the standard GUI based WiX installs.

The new install dialog's job is to set the following properties which are then passed to the installer.

• INSTALLDIR (default {c:\opt\shibboleth-sp}} - where to install Shibboleth
• SHIB_FILE_EXTENSION (default ".sso") - the extension to register (for IIS)
• INSTALL_ISAPI_FILTER (default "TRUE") - whether to register with IIS
• INSTALL_SHIBD_SERVICE (default "TRUE") - whether to register the service
• INSTALL_32BIT (tbd) - whether to register 32 or 64 bit service (and IIS plugins)

If an upgrade is sensed then these values are filled in from a mixture of values stored in the registry (like OLD_INSTALLDIR), whenther the service is installed and so on.

Note that these properties can be passed to the installer in no gui mode:

msiexec /qn /i ShibboltherSP-x64.msi INSTALLDIR=d:\Path\MorePath SHIBD_PORT 

Command files shipped with the installer include:

keygen

As currently, this generates the LLSS certificate key pair.

SetService64 (x64 install only)

This stops the shibd, sets the path such that from now on the 64 bit version of shibd is run and then restarts shibs

SetService32 (x64 install only)

This stops the shibd, sets the path such that from now on the 32 bit service of shibd is run and then restarts shibs

7. Versioning

All version information (and some other global configuration) is contained in the header file Versions.wxi
It is an assumption that all DLLs have versioning information encoded in the name such that a change of API will cause the DLL name to change. If the DLL name changes then it is vital that the associated component GUID change as well.

8. Architecture

The X86 installer installs:

• All the Shibboleth Provided X86 Merge modules
• The Microsoft 32 bit VC merge modules
• The 32 bit registry settings
• The 32 bit executables
• The architecture insensitive files
• The architecture independent configuration

The x64 installer installs all the above, plus:

• All the Shibboleth Provided x64 Merge modules
• The Microsoft 64 bit VC merge modules
• The 64 bit registry settings
• The 64 bit executables
• Any 64 bit only configuration

In addition the 32 bit installer detects if it being installed on a 64 bit machine and refuses, instead recommending the 64 bit installer in 32 bit mode.

9 Building

See BuildingTheInstallers