SSO Simulator Getting Started 6.5

SSO Simulator Getting Started


Java Development Kit: Version 1.5 or later

Steps to get SSO Simulator working in your development environment

1. Change your hosts file

If you are online when testing, then is already defined in DNS and you don't need to make any changes. Skip to the next section. If you are testing offline you need to keep reading here. In order for the cookies to be set properly by the SSO Simulator you will need to modify your hosts file to point a domain name to your computer. In the example configuration files below we use as our local domain name. You can choose any name you wish; just make sure that you choose something that will not block another site you need to visit. If you want to work off-line, add the following line to your hosts file following the directions for your operating system below:

Windows: edit the hosts file with Notepad (Windows 7 users will need to start Notepad as an administrator) found in:


Linux or OS X: from the command line run the following command to edit the hosts file:

sudo vi /etc/hosts

2. Download the Executable Jar File

Download the latest version of the executable Jar file from the SSO Simulator Downloads page.

3. Create a configuration that meets your needs

Here are a few sso simulator configuration file examples that will help you get started
Also read through the examples:
dual debug page example
conditions example
For more information about how to do advanced things with your SSO Simulator see: Configuration File Documentation

4. Starting the Simulator from the Command Line

java -Xmx128m -jar SSOSim-6.5.jar <path to config file>

This starts the simulator limiting its memory to 128MB. Previously on this page the command above included another flag, -server, which will run the java vm in a special "optimized" mode that takes longer to start but may run faster[1]. For local development this is probably unnecessary.

Note that if you are using a computer with OS X or Linux, you will need to admin/root privileges to start your SSO Simulator because it is starting on a port lower than 1024. If you get a permission denied error when starting your SSO Simulator try the following command line instead:

sudo java -Xmx128m -jar SSOSim-6.5.jar <path to config file>

You will then be prompted to enter the admin/root password. Once you successfully enter the admin/root password the SSO Simulator will start.

Note that if you are using classpath-ref condition aliases in your policies or entitlements then you cannot start the simulator via the -jar mechanism since that precludes use of the -cp and -classpath parameters which are needed to add the directories containing your condition files to the classpath. In that case you need to start the simulator by calling out the main java class directly. In the example below assume that some condition files are located in the /condition directory relative to the current directory. Adjust the ";" path delimiter appropriately for your operating system.

java -Xmx128m -cp ./condition;SSOSim-6.5.jar <path to config file>

Since 5.26

In version 5.26 support was added for specifying a start-up command. For backwards compatibility the default command that is invoked when launching the simulator is start which is a start-and-block command. It keeps the server running inside of the java process that launched it. There is no difference between running without specifying a command or running with the start command specified. For example both of the following result in identical behavior.

 java -jar SSOSim-5.26.jar <path to config file>
 java -jar SSOSim-5.26.jar start <path to config file>

To start the simulator in a separate process, call it with the run parameter:

 java -jar SSOSim-5.26.jar run <path to config file>

Note! If you need to specify other command line arguments besides 'run' and the '<path to config file>' those must be set in an environment variable named 'WAM_OPTS'. This is because in order to spawn another process we need to execute the original command with arguments. Some arguments are not given to the program such as system property (-D...) arguments. Setting your arguments in the environment variable allows the "run" command to spawn the long running process using the correct command line arguments.

 set WAM_OPTS=-DhttpPort=8080
 java -jar SSOSim-5.26.jar run <path to config file>

To stop the simulator, call it with the stop parameter. Alternatively, you can tell it to shutdown via that browser by hitting the console port with a path of "/admin/shutdown" which is what the stop command does:

 java -jar SSOSim-5.26.jar stop <path to config file>

In both cases, a timeout can also be specified:

 java -jar SSOSim-5.26.jar <command> 5000 <path to config file>

Since 5.39

In version 5.39 support was added for hot updates of the config file. Before this version, if the developer made changes to the config file, the Wamulator would need to be shut down and restarted in order for the changes to become active. Now, however, the Wamulator is watching the config file for any update. If an update is detected, the Wamulator automatically shuts down and restarts and all updates are active.

5. Starting the Simulator from a Java Stack project

If you are running an LDS Java Stack project, the Wamulator is fully integrated. By using the Stack Starter, a basic wam-config.xml file is created for you and you can run from the command-line or within the LDS Tech IDE. To run from the command-line, use the following command:

 mvn stack-wam:run

This will start the Wamulator in the same way as #4 above. To run within the LDS Tech IDE, download the latest version and, after importing your project, find the "wam" subproject, right-click, then "Run As" -> "Run WAM Emulator". This will start the Wamulator within the IDE and can be viewed and stopped in the console tab.

In both cases, it is unnecessary to download the Wamulator jar separately as it is pulled in by Maven for you.

6. Tweaking Logging Settings

Since 5.35

In 5.35, the Wamulator was migrated from Log4J in favor of JDK logging. This provides the benefit of allowing you in your individual project to easily override logging settings. There are three basic ways:

  1. Create a file in your deploy project - If you are creating a Java Stack project, then the easiest way is to create your own file and place it on the classpath. If you place it in the deploy project, then you will also receive the benefits of being able to have different logging configurations for different lanes by following the standard naming convention (lane name)
  2. Create a file and place it in your JDK installation - If you are starting the Wamulator outside of a Java project, then you can place a file in the $JRE_HOME/lib directory, which is probably something like $JAVA_HOME/jre/lib.
  3. Create a file and point to it with a system property - If you are starting the Wamulator outside of a Java project and don't want to affect the JDK installation, then you can also place a file elsewhere and refer to it by system property:
  java -Djava.util.logging.config.file=path/to/ -jar SSOSim-5.35.jar ...

For more details, see the Stack Logging reference documentation (contains details about JDK logging specifically).

Since 5.39

In 5.39, the Wamulator's logging of the decisions it makes as it compares incoming request paths against the ctx paths specified in the config was enhanced. This should make it easier to get started with the Wamulator since the log text should make it clear why the specified ctx paths are or are not matching incoming requests. In order to make it easier to turn on this enhanced logging, a logging properties file named: "" is included in the Wamulator jar file. To use this file, just extract it from the jar file and specify this file as your logging properties file (as described above) when starting the Wamulator.

This page was last modified on 2 December 2016, at 13:06.

Note: Content found in this wiki may not always reflect official Church information.