...
Attribute Registry (optionally)
With V4.1 a A Hello World module is available that will allow you test the system at this stage without diving into actual SSO protocol considerations.
...
The following summary will guide you in understanding the installed software layout and how to locate important files.
The most important thing to note is the separation of configuration files into user- and system-level files. The contents of the system directory and its subdirectories are meant to be left unmodified, and they are created as read-only files to emphasize this. This is to ensure that backward-compatible upgrades can be accomplished safely without reapplying local changes, and so that internal configuration changes required by newer versions can be applied automaticallyOlder versions of the software included a mix of user-editable and system configuration files. With V4+, there are files installed that aren’t meant to be editable, and any content in the system directory, if it exists, are for compatibilty and should never be modified.
There are a number of interdependencies between the Spring configuration files in various locations and in system inside the software that are like a contract between the user-modifiable configuration and the system configuration. In most cases, these dependencies can be identified via the use of Spring bean names that contain the prefix "shibboleth." When in doubt, don't remove a bean name that contains such a prefix, or comment it out (unless it starts out commented).
Directory | Explanation |
|---|---|
bin | Contains command line tools, and any Java libraries needed during installation. During upgrades files from the distribution will be overwritten, but additional files that you add will be preserved, so you can store your own command line scripts here. |
conf | The main configuration tree. During any installation (first time or upgrades), files are never replaced in this directory. New files required by the IdP version being installed will be populated if and only if they do not exist. |
credentials | Contains your keys, certificates, and keystores, as well as credentials on which you rely such as for metadata signature validation. Files in this directory should generally be readable only by the user account the IdP will run under (certificates aren't secret, but it's easiest to just lock down everything). During any installation (first time or upgrades), files are never replaced in this directory. In unusual cases, new files may be created if they do not exist. |
dist | Contains the original/default versions of the contents of the conf, flows, messages, and view directories. This folder is always deleted and re-created from the distribution on every install. This directory can be used as a reference against any locally modified copies of these files. |
doc | Contains documentation, licenses, and the like. This folder is always deleted and re-created from the distribution on every install. |
edit-webapp | This directory is created on initial install and thereafter files may (rarely) be added during upgrades but not overwritten. You may place any local configuration you wish to include in your packed warfile. During warfile creation, the contents of this tree are copied over top of the webapp directory, from which the war file is then built. Thus, it is an overlay tool for your local modifications and extensions. |
flows | Contains any user-editable Spring Web Flow definitions. During any installation (first time or upgrades), files are never replaced in this directory. New files required by the IdP version being installed will be populated if and only if they do not exist. |
logs | Contains the IdP diagnostic and audit logs by default. |
messages | Contains internationalized message properties used in various UI templates. This contains only new or overriden message properties or post-install translations; all of the default messages and translations are in the system tree. During any installation (first time or upgrades), files are never replaced in this directory. New files required by the IdP version being installed will be populated if and only if they do not exist. |
metadata | A storage location for SAML metadata used by the IdP (see MetadataConfiguration). During initial installation, some representative SAML metadata for the IdP is generated based on the installation inputs and placed in this directory in a file named idp-metadata.xml. Note that the IdP does not need to load its own metadata. Also note that the metadata is generated as a one-time operation during installation. It does not result from an in-depth analysis of the IdP configuration and does not change when the configuration changes. It's a starter example, not a real metadata source. |
system | Contains read-only internal system configuration that should not be modified and are generally only present on older installations for compatibility. The contents of this directory tree will be deleted and re-created by an install or upgrade. |
views | Contains Velocity page templates displayed to users of the IdP. While JSP views (and the older taglibs) are generally supported, most of the default webflow views provided are now Velocity templates that can be maintained outside the warfile and changed at runtime. During any installation (first time or upgrades), files are never replaced in this directory. New files required by the IdP version being installed will be populated if and only if they do not exist. |
war | Contains the packed IdP warfile for container deployment. The warfile can be rebuilt at any time by running the build.sh or build.bat script in the bin directory. It wll prompt you to verify the installation directory (which in theory allows for multiple installations). |
Backup
...
Files
When upgrading, the installer uses the Module system to re-enable all active modules, resulting in new files being added to the system and old files usually left alone, with the distributed versions of those files added with an “.idpnew-<version>” extension for easy comparison. On rare occasions, files may require overwrite, in which case the original file will be preserved with an “.idpsave” extension.
Windows-Only
On Windows, if Jetty has been installed there will be extra directories created.
...
Please refer to the ReleaseNotes for the 4.0.0 (and if applicable 4.1.0) 5.x releases for the relevant changes to be aware of when upgrading, which are minimal in nature for most deployers. For V4.1, there is some additional discussion on the Upgrading page as well.