techservicesillinois/elmrsample repository overview

⁠elmrsample

Sample application to use in an integration environment with elmr⁠.

elmrsample is packaged as a minimal Tomcat 9⁠ server. It can be started and stopped using the regular Tomcat scripts. See the section Running⁠ for more details. There is no packaged support for clustering in this installation.

⁠Requirements

elmrsample is built and run on Java-10. Please make sure it is installed and can be used.

elmrsample requires Maven version 3.5.3⁠ (or newer) to be built.

elmr requires an Apache httpd web server running with mod_jk installed and enabled. See below⁠ for configuration of both.

⁠Building

This project uses Maven⁠ as its build system. From the project's root directory, run the command below and it will be built.

mvn clean package

⁠Testing

This project uses JUnit 5⁠ as its test system. Tests will be run when the project is built, however to run tests while developing, the command below will work.

mvn [sysprops] clean test

⁠Installing

Unpack the file elmr-distribution.tar.gz on your filesystem. The directory structure will be a traditional Tomcat server tree:

elmrsample
├── bin                (control scripts)
├── conf               (server wide and application configuration)
├── lib                (Tomcat server libraries)
├── logs
├── temp
├── webapps
│   └── elmrsample
│       └── WEB-INF
│           └── jsp    (java server pages)
│           └── lib    (elmrsample web application libraries)
└── work

⁠Configuring

There are 6 configuration components:

1. bin/setenv.sh for system properties.
2. conf/server.xml for Tomcat server-wide configuration.
3. conf/context.xml for elmr web application configuration (do not use web.xml).
4. conf/logging.properties for java.util.logging/org.apache.tomcat.juli configuration.
5. conf/mod_jk.conf for configuring the connection between Apache + Shibboleth and Tomcat.
6. conf/workers.properties for configuring the connection between Apache and Tomcat.

It is recommended that web application configuration be set in the file conf/context.xml. However for ad-hoc runs it is fine to use the system properties set in bin/setenv.sh to override the values in the configuration file. Logging is configured in conf/logging.properties.

⁠Configuring Tomcat in conf/server.xml

See Apache Tomcat 9 Configuration Reference, The Server Component⁠ for details on editing this file. It should be very minimal. By default, an HTTP connector on port 8081.

Additionally, an AccessLogValve⁠ is configured to write to stdout (not a file) in combined format. This file is actually just the console, and is defined as being non-rotatable. Edit this to meet your needs.

⁠Setting JAVA_HOME in bin/setenv.sh

If you are using a custom installation of Java-10 in a non-default location, set the JAVA_HOME environment variable in bin/setenv.sh to point to the base directory of your JDK or JRE install. See RUNNING.TXT⁠ for other environment variables you can set.

⁠Setting System Properties in bin/setenv.sh

System properties may be set at startup and will override any other configuration that is set as described in the subsequent subsections⁠. They must be set in bin/setenv.sh by the CATALINA_OPTS environment variable. The table below lists what properties the application can accept outside the regular JVM system properties. See RUNNING.TXT⁠ for other environment variables you can set.

⁠Setting Context Parameters in conf/context.xml

Context parameters are read when the Tomcat server is started from the conf/context.xml (there is no webapps/elmrsample/WEB-INF/web.xml file in this application). See Tomcat Context Parameters⁠ for how these work and how they replace elements in a traditional web.xml file. Edit the value attributes of the <Parameter> elements as follows:

These parameters would affect ALL contexts (web applications) deployed to the webapps directory. Since elmr is the only context, configuring at this level is OK. If you want to override this configuration or deploy more web applications, see the link above about configuring contexts in Tomcat.

⁠Configuring Logging in conf/logging.properties

Logging uses the Tomcat default logging system (which is based on the JDK logging system). See Tomcat Logging⁠ and for details.

Loggers have been pre-configured to log at the highest level for each application package. Logs are configured by default to be written to console. This will cause logs to be written to elmrsample/logs/catalina.out in most environments.

⁠Configuring Apache HTTPD

There are 2 sample files you can use to configure mod_jk. You will be configuring attributes retrieved via mod_shib as environment variables. See the Tomcat mod_jk documentation⁠ for an overview of AJP and mod_jk.

⁠conf/mod_jk.conf

Use the contents of this file to configure which paths will be routed through mod_jk as JkMounts.

⁠conf/worker.properties

Copy this file to a location configured in your httpd's configuration. Edit as appropriate. See the workers.properties reference⁠ for contents. For elmrsample, this ought to be a minimal configuration.

⁠Running

For general information about running a Tomcat server, see RUNNING.TXT⁠. These instructions are provided here to get you started with the basic elmr configuration.

⁠Starting

Run the file elmrsample/bin/startup.sh to start the server. Tomcat will log messages to elmr/logs/catalina.out about application startup and operation.

⁠Stopping

Run the file elmrsample/bin/shutdown.sh to stop the server. Tomcat will log messages to elmrsample/logs/catalina.out for shutdown.

⁠Troubleshooting

⁠Application Does Not Run

If the web application is not running, check elmrsample/logs/catalina.out for any log messages logged at SEVERE and look for anything related to elmr not starting. When errors occur, they will usually be when application listeners are started and data is being cached.

⁠Attributes Are Not Visible in the Application

If there are Shibboleth attributes that you expect to be visible in your application but are not showing up, you will have to review the JkEnvVars set in your Apache configuration and the attributes you set in your Shibboleth attribute map. These can be seen by visiting the /elmr/config page which will show what has been configured.

⁠Apache (not Tomcat) Responds to Requests with 413 Status

The 413 status⁠ signals that Apache is trying to process a request containing an entity (header, attribute, etc) that exceeds its configured capacity. The likely cause in the case of Shibboleth is that one of the attributes contains a lot of data. Fix this by doing the following:

1. Edit workers.properties adding the line worker.[worker-name].max_packet_size=65536. Restart Apache.
2. Edit elmrsample/conf/server.xml adding the attribute packetSize="65536" to the AJP <Connector>. Restart Tomcat.

It is important that the values for max_packet_size and packetSize are the same. It's OK to set them this high. This isn't configured by default for any of the examples in the source. When this is done, the request will go through.

See the workers.properties reference⁠ and the AJP Connector reference⁠ documentation for details.