V5 IdP Installer

The idea behind this page to capture some thoughts about the IdP installer over and above the point changes discussed in https://shibboleth.atlassian.net/browse/IDP-2105

With a following wind this should turn into the detailed documentation for V5

Architectural overview

I had some original thoughts to split the installer into smaller sub parts, but it turns out that on further code reading the current implementation is no too far from OK. The way it is exposed (via an ant task) sucks and as per https://shibboleth.atlassian.net/browse/IDP-1815 we can get much of where we want to just by replacing that.

The core of how the Installer (and here I also include build.sh) works is a class which contains (and captures where needed) the implementation. Thing like source directory, target directory detailed configuration (for new installs). Currently this class is populated

  • From System Properties

  • From an supplied property file

  • And from the command line (if neither of the above two provide the required value)

The first two bullets have proven popular with people bundling the IdP.

The proposal is to keep this but to add to it with proper command line qualifiers

  • Probably one for each property we have

  • And we will add properties for things we some add (like HttpClient bean names or aes key sizes), but not for other CLI things (like spring bean files)

  • We will do away with the special logback file for the installer and replace it with the standard command line thing

  • I think we can get rid of the input property - you can only install from the distribution and it suffices to make that the input

Note that when I say “property driven” below this means via this class which encapsulates the above 4 bullets (so if configured, take from the command line/property file/system properties otherwise ask)

Current implementation

As the time of writing (the first pass of changes for https://shibboleth.atlassian.net/browse/IDP-2002 completed the code does this.

Initial Populate

  • Update only: Tidy

    • delete bin/lib

    • delete dist (save for the plugin stuff)

    • unprotected system

  • Copy webapp to dist\webapp (not overwriting)

  • Copy bin/lib to bin/lib (overwriting)

  • copy system to system (not overwriting)

Configure

  • Version handling

    • Write the version to a the version file in dist

    • check idp.properties for forbidden properties

    • Check plugin conformance

  • New Install Only:

    • Enable idp.Core

    • Create key material (property driven)

    • Run property changing over idp.properties, ldap.properties (property driven)

    • create secret.properties (prooperty driven)

  • Update only

    • check edit-webapp\WEB-INF\web.xml for badness

  • enable modules

  • Clean up detritus

  • New Install Only: Create metadata (driven from idp.properties)

Build war

(this is part of the install but also needs to be its own command line)

  • delete webapp (why?)

  • create webapp.tmp

    • populate from dist\webapp

    • overlap from dist\plugin-webapp

    • overlap from edit-webapp

  • create war\idp.war from webapp.tmp

  • delete webapp.tmp

Windows

This is actually not much different

  • Initial Populate is handled by the Windows MSI installer

  • Configure and Build war are run as java programs inside the installer

  • … Plus a whole lot of stuff to do with Jetty which will be exbedded ( or something else)

Properties & Qualifiers used to drive the Install

Under construction

This section os changing frequently as I update my ideas. Check in here frequently or watch the page.

Property

V5 Proposed qualifier

Default

Prompt

Description

Property

V5 Proposed qualifier

Default

Prompt

Description

idp.property.file

--propertyFile

 

N/A

The first thing looked it. If present it is used to get other properties

Not as a property

--sourceDir
-s

 

None

No longer prompted for. This is injected by the install scripts

idp.target.dir

--targetDir
-t

 

Installation Directory:

 

idp.noprompt

--noPrompt

 

 

If the qualifier is present (or the property set to any value) then if a required value is not available via properties then the install fails (rather than prompting for a value)

idp.entityID

 

https://$idp.host.name/idp/shibboleth

SAML EntityID:

Written into idp.properties on initial install

idp.host.name

 

Some nasty hackery with the network

Host Name:

Drives the default entityId
Drives the default scope
Drives the subjectAltName
Drives the metadata
Drives key generation

idp.scope

 

The host name with the first bit removed

Attribute Scope:

 

idp.merge.properties

 

idp.entityID=$idp.entityId
idp.scope=$idp.scope

 

A property file whose contents are merged into the default idp.properties on an initial install only.
This is either the absolute path or a path relative to the source dir

ldap.merge.properties

 

no merge

 

If present this file is merged into ldap.properties

This is either the absolute path or a path relative to the source dir

idp.LDAP.credential

 

myServicePassword

 

Used to set idp.authn.LDAP.bindDNCredential in secrets.properties

idp.keystore.password

 

 

Backchannel PKCS12 Password:

Password for credentials/idp-backchannel.p12
Are we going to keep om generating this?

idp.sealer.password

 

 

Cookie Encryption Key Password:

Password for credentials/sealer.p12

idp.sealer.alias

 

secret

 

Alias in credentials/sealer.p12

idp.sealer.keysize

 

128

 

New In V5
AES key size for credentials/sealer.p12

idp.keysize

 

3072

 

key size for credentials\idp-signing.*, credentials\idp-encryption.* and credentials/idp-backchannel.p12

idp.conf.setmode

 

true

 

whether to lock down the installation
bin/*.sh 755
system/* 444
dist/* 444
dist/plugin* 640

New install only:
credentials/* $idp.conf.credentials.filemode
credentials/* group $idp.conf.credentials.group (if present)

idp.conf.credentials.filemode

 

600

 

Mode to set credentials/* on a new install if $idp.conf.setmode

idp.conf.credentials.group

 

 

 

If non-null and $idp.conf.setmode, the group to set on credentials/*

idp.no.tidy

 

false

 

Debug only if set to anything then any intermdeiate files (like the merge files) are not deleted.

idp.initial.modules

 

idp.EditWebApp (V5) idp.CommandLine (V5) idp.authn.Password idp.admin.Hello

 

Comma-separated list of modules to enable on install. If this starts with '+' then the valuse are appended to the list.

ant.home (v4)

 

From where the installer is being run

N/A

Not available in V5

idp.conf.preoverlay (V4 only)

 

 

 

No longer Used, proposed alternative is to write a plugin and get that installed

idp.initial.edit-webapp (V4 only)

 

 

 

No longer Used, proposed alternative is to write a plugin and get that installed