Connect Layer Setup, Access and Configuration Guide

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

campusM enables institutions to integrate with both hosted and locally-installed, on-premise solutions. Best practice for campusM is to provide access to your 3rd party systems via APIs and to avoid the need for your institution to procure, provision and maintain additional servers and services and allow campusM to deliver its service as a pure SaaS service and the below can be ignored. For more information on setting up campusM product integrations using APIs and without Connect layer, please see here.

However, if your institution is unable to provide APIs, then to facilitate the integrations with such solutions, campusM utilizes a Connect Layer which resides on the institution's servers and can connect to on-premise back-office systems. Since the Connect Layer would need to be utilized in order to access on-premise systems of your institution, typically the Connect Layer itself will be an on-premise environment maintained by your institution as well. However, hosted solutions may be used for the Connect Layer as long as those systems have the appropriate network access to your back-end systems, are accessible via VPN and SSH to Ex Libris and all other technical pre-requirements noted below are met.

The Connect Layer environment requires Apache Tomcat servers that are accessible publicly via HTTPS from outside the institution. Those Tomcat servers should be accessible via SSH (within the customer's VPN) for Ex Libris staff to manage and support Web services code deployed on the servers. Additionally, the Tomcat servers should have access to relevant campus back-end systems. The back-office systems should also be accessible from within your institution's VPN (outside of the Connect Layer servers themselves) in order to enable access and troubleshooting. This guide details the activities required to be completed by the institution's technical team to enable product integrations.

The following is a set of requirements for the installation of the Apache Tomcat servers at the implementing institution, including:

Setting up the application servers with Java and Apache Tomcat
Installing certificates and setting up remote access to the various campus systems

As you review the document and implement the various steps, please use the checklist below to ensure that all processes and procedures are completed successfully. The checklist should also be used at the end of the installation process to confirm that all servers are available as needed.

For an overview of the environments and architecture, please see here.

campusM Connect Layer Installation Checklist

Requirement		Production	Sandbox
Server is provisioned per the specification definitions?
Server is publicly available over HTTPS?
SSL installed?
Apache Tomcat installed?
Java installed?
Tested server access to relevant campus systems?
Provided user credentials for SSH/SFTP?
Provided VPN access?
Log rotate enabled?
Other: (please specify)

Local Connect Layer Server Setup

This section will involve installing Java and Apache Tomcat on local servers within the institution network. Two environments are to be provisioned; a Production and a Sandbox environment.

Configuration Specifications

Below are details of server requirements, including specifications and versions of the specific software to be installed.

Configuration Option	Specifications
Machine Name/IP Address	campusm.[uni].edu / campusm.[uni].ac.uk / etc. (please send this to your campusM Project manager
Recommended Machine Sizing and Specification	Production: Disk Space 30GB, 10G of memory (We recommend 2x load balanced servers for Production sized) Sandbox: Disk Space 20GB, 4GB of memory
CPU	Production: at least 4 CPU cores Sandbox: at least 2 CPU cores
Operating System	Linux platform - Redhat, CentOS is recommended but not required. (Other Operating Systems are supported for campusM Tomcat Connect Layers as long as Tomcat and Java are installed)
Apache Tomcat (Max) Version	Apache Tomcat Version 8.5 and 9
Java (Max) Version	openJDK 11 - https://openjdk.java.net/projects/jdk/11/

Machine Memory Sizing

Memory settings noted in the table above represent Ex Libris' recommendations for ensuring enough memory for high or low usage even during high peak times of production app usage.

For a more specific breakdown, and for existing customers who are adding additional services to their Production campusM app, the recommendation can be further refined between High and Standard Usage of the app (number of requests / second) which may be impacted by the following key factors:

Number of Active Users
Number of Connect Layer Integrations
Number of Live Tiles
Web portal Usage

Usage Level	Requests/Second	Required	Recommended
Standard	Up to 30 requests/second	2G of free memory (Total: 4G)	At least 2G added (for existing customers) (Total: 6-10G)
High	Over 30 requests/second	2G of free memory (Total: 4G)	At least 4G added (for existing customers) (Total: 8-10G)

Usage Level

Requests/Second

Required

Recommended

Standard

Up to 30 requests/second

2G of free memory (Total: 4G)

At least 2G added (for existing customers)

(Total: 6-10G)

High

Over 30 requests/second

2G of free memory (Total: 4G)

At least 4G added (for existing customers)

(Total: 8-10G)

Java (openJDK) Installation

Please visit: https://jdk.java.net/11/ and choose the Builds > Linux/x64 version for download. openJDK is provided open source under the GNU general public license.

Disable any access control services

Certain Linux distributions contain built-in Security services which may have a default setting to block any outgoing traffic from the server.
SELinux (Security-Enhanced Linux), a Linux kernel security feature for access control, is the most common such distribution.
Please make sure to disable this service upon starting up after system reboot by editing /etc/selinux/config and setting SELINUX=disabled.
We recommend consulting the SELinux (or similar) formal documentation before making any changes.

Apache Tomcat Installation, Compression and Memory

Please visit: http://tomcat.apache.org for general instructions. For the version refer to box above.

No special Tomcat packages beyond the standard base package are required to be installed.

Compression and Max Threads

Ex Libris strongly recommends enabling the compression feature and setting the maxthreads parameters to 1200 on the Tomcat application server.xml level in order to reduce and optimize the data transfer between the connect layer and the browser and optimize the concurrent load of transactions passing through the connect layer. Note: Setting the maxthreads to 1200 necessitates that the ulimit file descriptors also be set in tandem to the higher than default value recommended below (65536).

These are the suggested steps for activating (turning on) the compression setting:

Shutdown the Tomcat server
Backup the current server.xml file found under Tomcat's conf directory
Edit the server.xml file to include the compression part (** please see Ex Libris suggestion below)
Re-start the Tomcat server and review the startup log to ensure the service is running correctly

Please note to repeat the steps per each of the Tomcat servers deployed in your environment.

** The below settings are the ones recommended, tested and supported by campusM.
If a different set of configuration is to be implemented, please raise a Salesforce ticket and share in advance with the Ex Libris team to prevent any impact on the platform/service.

Ex Libris recommends to perform the server.xml file modification with care and after understanding the impact of this change.

For official configuration instructions on compression, please refer to the following link https://tomcat.apache.org/tomcat-8.0-doc/config/http.html, HTTP Connector attributes.

Java / Tomcat Memory

On the Connect Layer Production servers, the Apache Tomcat should be configured to use additional (JVM heap) memory (6G) - dependent on what was provided as part of the operating system, we recommend the following Java options when Tomcat starts: -Xms512m -Xmx6144m.

For sites with lower than recommended RAM memory settings, the JVM heap memory should be set lower, accordingly.

Please note that the campusM software cannot run with Java security manager enabled.

For the Sandbox environment, the following lower settings are recommended: -Xms512m -Xmx2048m.

Maximum number of files

At the Operating system kernel level, the ulimit file descriptors / open files should be set to 65536. This is in order to further optimize the concurrent load of transactions passing through the Production Connect Layer.

Configure Basic Auth Users on Tomcat

Modify $TOMCAT_HOME/conf/tomcat-users.xml, add following code:

<role rolename="campusm"/>
<user username="application_sec_user" password="***Please complete***" roles="campusm"/>

The application_sec_user user will be used by the mobile device to access the campusM web services, and must have the campusm role.

Please note that the password has a maximum length of 100 characters, and should not contain special characters. (only alphabetic and numeric characters should be used)

Load-Balancing / Sizing

Web services developed by Ex Libris that reside on the Connect Layer Tomcat servers are completely stateless and atomic in nature i.e. there is no requirement for memory to be shared across Tomcat nodes. Thus there is no requirement to enable sticky sessions for your load balancer configuration.

We recommend load balancing with two Connect Layer server nodes setup and sized per the above recommendations for your Production Connect Layer servers regardless of your institution's size. Load balancing for the Sandbox (Test) environment is not required.

Setup Log File

The campusM Connect Layer code will generate log files inside Tomcat's log directory. These must be managed to ensure they do not fill the disk space. Create a logrotate cron job or similar to compress old log files, e.g. over 2 weeks old. It is suggested to delete or archive compressed log files over 1 month old.

Make sure to review that this is working adequately once web services are in use on the server, and ensure that all log files are included by the time the campusM service is live.

NOTE - Please verify the following configuration to prevent log of sensitive information

<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"

prefix="localhost_access_log." suffix=".txt"

pattern="%h %l %u %t "%m %U %H" %s %b" />

Configuration of External SSL Access

Tomcat must be publicly accessible over HTTPS in all environments (Production and Sandbox). All public facing servers must present an SSL certificate from a valid trusted authority (Verisign / JANET / GoDaddy / etc.). This cannot be a self-signed certificate.

If you are obtaining an SSL certificate signed by QuoVadis (JISC obtain their certificate from QuoVadis), you will be required to ensure that you request the certificate to be signed by “QuoVadis Root CA2” , if the certificate is signed by the G3 root it will not be trusted by Android 4.x (i.e. it is not supported).

By default, tomcat will run under port 8080 and port 8009. In order to provide SSL connection to the tomcat servers, there are effectively two options:

Install the SSL certificate on an upstream server (apache; loadbalancer; F5; etc.). This enables the institution to manage the SSL certificate alongside other SSL certificates. If termination is configured on the upstream server, then the connections through to tomcat need to be either http connections to port 8080 or via an ajp proxy to port 8009.
Install an SSL certificate on the Tomcat servers. This involves converting the SSL certificate obtained from the provider into a Java keystore (Use Portecle for easier keystore management) and configure an additional connector in $TOMCAT_HOME/conf/server.xml either on port 443 or port 8443 (some versions of Linux will not allow Tomcat to run on a port below 1024). Documentation on how to do this is on the tomcat documentation site.

Caution: Editing documents in use by the Connect Layer

In certain circumstances, the Connect Layer is able to be altered in real-time in order to allow changes to various configurations without requiring intervention by Development. For example, some customers may choose to alter their web.xml or context.xml files in such a way as to update passwords to various Databases, APIs, or other back end systems so that integration continue to work after changes elsewhere in the institution.

However, this entails a certain level of risk. If the XML contained within the two aforementioned files is invalid, it can prevent the WAR file from re-expanding and thus prevent services from working, including ones used for such things as login and integration. As such, one must always ensure due diligence in altering these files to ensure that the XML in the file remains valid.

One common mistake that is very easy to overlook is the inclusion of ampersands ("&") within these files. It is common for password generators to include Alphanumeric and Punctuation characters, including the ampersand. However, an ampersand within XML acts as an escape character. Including an ampersand without correctly escaping it will make the whole XML file invalid and thus cause disruption to the Connect Layer. If the password or any other entry must contain an ampersand it must be escaped like so:

This can be observed in the following examples, wherein the desired password is "Secret&Safe".

Incorrect and invalid:

Correct and valid:

Required Network Access - SSL/VPN and Tomcat

This section covers opening of ports for mobile applications to access the institution's services. It also covers allowing the Ex Libris team access to the Tomcat servers and the back-office systems.

Allowing Connections from Tomcat

The Tomcat servers need to have sufficient firewall rules in place so they are able to connect to the data sources with which campusM will integrate.

Tomcat Server Port Access

The following ports need to be opened publicly to allow access from the Internet at large (e.g. mobile phone devices using 3G/4G) to all servers running Tomcat, through a load balancer, when one is used. The details are listed in the table below. Further information is in the section regarding SSL configuration.

Port	Type	Description
443 or 8443	Production/Sandbox HTTP with SSL (HTTPS) Access	Access for mobile phone devices to access institution hosted services

VPN Account / Remote Access

The Ex Libris campusM team will require remote access to all Tomcat servers which must be able to connect to all back-office systems we will integrate with (including secure LDAP and any database schema). The Tomcat server access should either be open directly and publicly via appropriate credentials or be provided through a Virtual Private Network (VPN).

The back-office systems should also be accessible directly or via VPN directly (not via the Tomcat servers) in order to allow appropriate, but secure, troubleshooting of the on-premise integration system end-points.

The terms and agreement of usage and access are detailed in your Ex Libris contractual agreement.

To allow proper and smooth service delivery and support, the customer should provide and maintain a robust remote access to the production and sandbox connect layer servers in which the campusM Tomcat servers are located.

Ex Libris recommends at least 2 concurrent sessions to be available for remote access, this is required to allow Ex Libris staff from different locations to be logged in simultaneously (Project team, Support, R&D).

Access to Tomcat Server

The campusM team will require SSH and SFTP access (via VPN), allowing secure remote connection to the server. This can either be via a username / password or a username / pem-encoded certificate.

This user will require permissions to:

Be able to stop and start Tomcat (As a service - e.g. service tomcat start / service tomcat stop / service tomcat restart)
Read/Write on all files within the $TOMCAT_HOME directories and sub-directories (move, copy, edit and delete)
Ability to transfer files via SFTP (from within VPN) directly to any of the $TOMCAT_HOME directories and sub-directories
Read any generated logs

Please provide your campusM project team with:

The installation directory of Tomcat (including the locations of the webapps, logs and conf directories)
The commands used to stop and start Tomcat (including whether sudo is required)

These will vary depending on your installation (eg. from a package manager or some other method).

Prepare Test Data

Having test data prepared would be very beneficial during the development process and can further be used by testers at the institution.

For each system we are planning to integrate with, we require a test university account with valid sample data.

WAR file Deployment

In the event where Ex-Libris do not have permissions or access to deploy the connect layer web services (war file) onto your production environment, customers will need to copy the war file into the "webapps" directory of Tomcat ensuring the war file is given the correct permissions.

Before copying the WAR file into the webapps directory please ensure the WAR file has been set to read access for the user running the Tomcat process.

You can run the following UNIX command as the Tomcat user to set the permissions to read only "chmod 644 <filename>.war"

Maintenance

Maintaining the Connect layer servers is in the customer's control. This refers to all aspects of the Connect layer including but not limited to backups, monitoring, up time, disk space, security patches, performance and server and Java/Tomcat related updates (within the supported major versions).