Migrating an existing CAS server installation

Suppose you have an existing CAS server installation. You'd now like to migrate it to a new server. Maybe you're taking the opportunity to switch hardware, to upgrade OSs, or you're moving to a new datacenter. These instructions are intended to help you accomplish this migration.

There's actually not much uniquely interesting to say about moving an existing CAS installation – it's a lot like installing a new CAS instance. Rather than installing things anew, you'll be looking at what you currently have to migrate it. So these instructions are going to sound a lot like instructions for installing CAS in the first place.

It's also hard to write generic CAS server migration documentation because so much depends on your local practices and proclivities. You may have local practices around where you get your servlet container distributions and how you keep them up-to-date, for instance.

What value does this documentation have, then? At the least, it surveys the breadth of items and configuration that make up your existing CAS server to help identify what all to look out for in replicating on a new CAS server instance.

Anatomy of your CAS installation

Your CAS installation consists of:

• A server environment, complete with some operating system
• A JDK (superset of the JVM, since your servlet container needs to compile JSPs e.g.). This may come with your operating system.
• A servlet container, probably Apache Tomcat. This might come with your operating system, and you might or might not want to use the one that came with your operating system.
• Possibly, an Apache httpd (Apache web server) instance fronting that servlet container. This might come with your operating system, and you might or might not want to use the one that came with your operating system.
• An answer to how your CAS service is available via https:// (SSL) . This probably means an SSL certificate and using Apache, but Tomcat could be your SSL endpoint, or you might have fronted your CAS server with a load balancer that's the SSL endpoint. Anyway, something has to be providing SSL for your CAS server.
• Possibly (likely), a database into which your services registry is stored. Possibly you're using this to store your ticket registry if you have a multi-node, high availability CAS configuration.
• Possibly, an external cache solution like memcached, if you're achieving high availability clustering of ticket registry state in this way.
• Possibly, utilities to check out and build you CAS server .war if you're doing this on your CAS server boxes (some adopters do this, some adopters build elsewhere and upload to their CAS servers ready-to-go war files)
• A deployed instance of the CAS war file, the customized Java servlet application that is your customized CAS server software.

How to migrate your CAS installation

Have a target server

First, you'll need the new server onto which you want to install CAS. It should have a reasonable server environment ready to go.

In particular, it'll need a user as whom you'd like your CAS service to run. It's a poor practice to run CAS as root, as a plenipotent administrator, or as a human user account.

JDK

Your servlet container will require a JDK, which is a superset of the Java Virtual Machine.

This may be installed in your new OS, or you may need to install one.

You're likely going to choose the Oracle JDK, though there are competing JDK implementations available.

You need to make your JDK location available via the environment variable JAVA_HOME, via something like

export JAVA_HOME=/home/jasig/cas/java
export PATH=$PATH:$JAVA_HOME/bin

(or via the System UI for this in Windows Server, if you're using that OS.

Install an equivalent servlet container

Your new CAS server will need a servlet container.

You're probably using Tomcat. There are several options for where to get a Tomcat to install and how to install it. In general you can get the latest Tomcat release here:

http://tomcat.apache.org/

If you're conservative, you probably want the latest Tomcat 6.0.x release.

You'll have existing servlet container configuration, e.g. the conf directory within Tomcat, which you'll need to migrate over from your old servlet container to your new one.

Install/configure Apache httpd if you're using it

If you're fronting your servlet container with Apache httpd, then you'll need to install it too. Apache httpd also has configuration, which you'll need to migrate over from your existing Apache httpd instance.

SSL certificates

That make your CAS server available over SSL

Your CAS server needs to be available over SSL.

Your servlet container might be the SSL endpoint, in which case there will be a JKS file containing your server's SSL certificate that needs migrated over. That is, a keystore file that makes this certificate available to the JVM running your servlet container.

A fronting Apache httpd instance might be your SSL endpoint, in which case there will be a conf/ssl directory within your Apache directory, that needs copied over from your old server to the new server.

That allow CAS to make proxy granting ticket callback URLs to PGT-using services

This point's subtle.

If you're using proxy tickets (e.g., with uPortal or with ClearPass), then CAS needs to make https:// callbacks to the services that need to acquire proxy granting tickets, e.g. uPortal or the CAS client software in front of Outlook Web Access. In order for those callbacks to succeed, CAS needs to trust the SSL certificates of those services. If those services have self-signed or otherwise insufficiently expensive SSL certificates such that the JVM doesn't trust them by default, then you had to install the public keys of those SSL certificates into the JVM keystore. You'll need to migrate this populated keystore, or install those public keys into the new JVM's keystore, in order for your new CAS server to successfully complete proxy granting ticket vending callbacks to these services.

If you're not using proxy tickets, don't worry about it.

Database(s)

If you're using the JPA services registry, that services registry has an associated database. Is it moving in your CAS server migration? If so, you'll need to install your preferred database software at its destination and migrate your data.

If you're using the JPA ticket registry (in a multi-node, high availability CAS deployment), likewise. You don't need to migrate this transient data (on loss of the ticket registry data, the worst things that happen are users lose their single sign-on sessions and applications their proxy granting ticket sessions and users need to log-in again on their next usage of CAS.) But you do need to ensure that your new CAS server wakes up able to store and retrieve tickets.

External cache solution

If you have a high availability CAS solution, and you're not using a database for your ticket registry, then you're using something else, maybe a cache solution like memcached. In this case, you're doing something advanced and complicated and it's goiong to have other processes, configuration that needs migrated. Sorry. This document just isn't going to help you much.

Utilities and environment

If you're checking out source code onto your new CAS server (a questionable practice), you'll need to have or install tools for doing this, i.e. svn or git or something.

If you're building the CAS .war on your new CAS server (a questionable practice), you'll nede to have or install Maven2.

And then you'll need to put these tools on the PATH via something like

export MAVEN_HOME=/home/jasig/cas/maven
export PATH=$PATH:$MAVEN_HOME/bin

The CAS war file

Laying hands on the CAS web application software

If you're using source control

Ideally, you're using local source control for your local customized version of the cas-server web application. Ideally what you have in source control is a Maven Overlay build.

If you're using source control, then perhaps you'll need to update some of the configuration for your new server, or perhaps you won't if nothing has changed.

In general, if you're using source control, the strategy is to make updates in source control and then build a new CAS server .war from source for deployment to your new CAS server instance.

If you're not using source control

If you're not using source control, then you probably should start.

In the meantime, you can copy CAS as it's actually deployed on your current CAS server from your servlet container's webapps directory. You should grab the actual exploded deployed /tomcat/webapps/cas directory, since this will include any changes that might have been made after any cas.war that's there was deployed.

Paste this directry into your new CAS server's /tomcat/webapps/ directory. But really, you should use local source control.

What changes you may need to make

cas.properties

cas.properties declares the hostname of the CAS server. If your CAS server isn't changing hostname in this migration, this won't need to change. If it is, that's going to be disruptive to the services using CAS that are using the current CAS server hostname, but in any case you'll need to update this hostname here.

log4j.xml

log4j.xml declares where you want your CAS server to put its log file. You probably customized this to point to a directory on your current CAS server where you want your logs. If that path doesn't exist on the new server, or there's some new better path for this, you'll need to update log4j.xml to declare the new desired log file path.

Spring configuration

What else are you changing in your migration?

In particular, if in your migration you've moved your databases (for the services registry, for the ticket registry if you're using the JPA ticket registry implementation in a load balanced environment), then your Spring configuration will declare DataSources that need to be updated to connect to the new RDBMS.

How to apply these changes

If you're using source control

If you're using source control, check out the source from your source control, make the needed changes (likely committing these to source control so you'll have them tracked), and then build your customized CAS server .war from source using Maven.

In the same directory with your project's pom.xml, run

mvn package

this will generate a target/cas.war , (or possibly a .war file with some other name you've defined in your pom.xml; in any case you can rename the .war file to whatever name you'd like your CAS server web application to have).

Deploy the resulting .war file to Tomcat by dropping it into your new Tomcat's "webapps" directory. If Tomcat is running, it will unpack and start the CAS server application immediately – if it's not running, it will do this when next started.

If you're editing a deployed web application

Again, you probably shouldn't be doing this.

That said, if your practice is to edit a deployed CAS web application, then after you copied the deployed CAS web application over into your new servlet container, you'd edit the deployed files in place. The changes will take effect upon next Tomcat restart.

This approach avoids all the advantages of using source control to track and back up your configuration. Consider using source control instead.