ANSR Installation Guide
This is the installation and configuration guide for ANSR version 3.5. It explains in
detail how to install the ANSR system.
2. Machine Setup
ANSR can be run as a stand alone server, but the paging server was designed to be run in
the MOC which is usually on a closed network. Therefore, ANSR comes with proxies
that can be run on an open network. Using these proxies, ANSR can email or page an
operator or perform some other operation that requires access to the outside internet.
A web-based or window-based console can be run to monitor the state of pages in the
ANSR system. The console can be run on the closed network or, with the help of a
GMSEC firewall bridge, on the open network.
If desired, two ANSR servers can be run to provide reliability. In fact, any number of
ANSR servers can be run and they will automatically coordinate a primary and multiple
hot backups. If proxies are being used, any number of proxies can be run on the open
side for redundancy. The target deployment of ANSR involves four machines, two
servers and two proxies, as shown in Figure 1.
Figure 1 Typical ANSR Deployment
In test systems, ANSR server was installed on two PCs with the following specifications
• Pentium 4, 2.99 GHz
• 2GB RAM
• 220GB HD
• Windows XP Professional 2002 service pack 1
The ANSR proxies were designed to run with very little resources so that they can be
piggy-backed on machines running other programs. In the test system they ran on
• Pentium 2
• 130MB RAM
• 9.5GB HD
• Windows 2000 version 5.00.2195 service pack 4
3. Required COTS
Java is needed to run the ANSR programs. Java is developed by Sun Microsystems and
more information can be found at http://www.javasoft.com/. ANSR 3.5 will work with
Java Runtime Environment 1.3 and above or Java Development Kit 1.3 and above. Java
must be installed and either the Java root directory must be specified in the environment
variable ANSR_JAVA or JAVA_HOME or the Java program “java.exe” must be in your
path. This must be done to run ANSR applications or to setup a Windows service. When
setting up a Unix service, the Java root directory must be specified in the first lines of the
The ANSR server communicates with other components using the GMSEC bus. ANSR
requires the GMSEC API 1.0 or above installed on the machine. On Windows, the
GMSEC binaries directory, GMSEC_RELEASE/bin/win/Release, must be in your path to
run ANSR applications or setup a Windows service. On Unix, the root GMSEC release
directory must be specified by the variable ANSR_GMSEC to run ANSR applications,
and must be specified in the first lines of the ansrinit.sh script to setup a Unix service.
The ANSR proxies do not need GMSEC. To run the ANSR web-based console on either
Unix or Windows, the GMSEC libraries must be copied to the web application server
(see Section d for more information).
GMSEC is simply an API and rely on an underlying middleware implementation -
usually SmartSockets but may be GMSEC’s Magic Bus, or other middlewares. To run
ANSR applications the middleware’s client software must be installed on the ANSR
server machines, the middleware libraries must be in the path, and any environment
variables required by the middleware must be defined. On Windows, the Java and
GMSEC variables and paths only needed to be defined when installing the ANSR
service. However middleware variables and paths must be in the path and defined
whenever the service is run and therefore should be configured as Windows environment
variables for the system or for the user that the service will run as. On Unix, the
ansrinit.sh script has a section at the beginning for adding any middleware required
ANSR comes with a web-based console to see the state of the system from remote
systems using a web browser. You will need a JSF-capable web application server such
as Tomcat, JBoss, WebLogic, or WebSphere. We recommend the open source web
application server Tomcat. ANSR was extensively tested on Tomcat version 5.5.
4. Installing and Configuring ANSR
ANSR can be installed by unpacking the ANSR.zip file found on the ANSR Distribution
CD. This will create the directory “ANSR”.
If there was an existing version of ANSR running on the machine, configuration must be
preserved. Every ANSR installation uses an application configuration file (by default
dev.xml) and a paging configuration file (by default targets.xml). The
configuration files will be found in ANSRcfg on ANSR releases before 3.2 and
ANSRWEB-INFclassescfg on 3.2 and later releases). Find these configuration files
in the old ANSR release and copy them to the new ANSR release (the ANSRWEB-
INFclassescfg directory), overwriting the present configuration files.
The operators must be able to edit the configuration file that specifies who is to be paged.
This may require file permissions be changed. On Windows,
Right click the file ANSRWEB-INFclassescfgtargets.xml
Click the “Security” tab
Select the “Users” entry
Click the check boxes for “Modify” and “Write”
If the “Properties” dialog does not have a “Security” tab, then the “Use Simple
File Sharing” option found in Windows Explorers advanced options must be
chmod a+w ANSR/WEB-INF/classes/cfg/targets.xml
Every ANSR server needs its own application configuration file. These can be found in
the ANSRWEB-INFclassescfg directory, have a filename ending with “.xml”, and
start with the text “<ANSR>”. These XML files specify a list of characteristics which are
described further in below sections. To start with a default configuration copy the file
dev.xml to a new name (e.g. trmm1.xml). The user’s manual devotes an entire section
to describing the syntax of the application configuration file.
a. Configuring GMSEC
In ANSR, GMSEC is used both for communicating with other MOC applications and for
sharing application state with other ANSR servers – so the GMSEC configuration is
specified twice in the configuration file.
The <GmsecTransport> section specifies the GMSEC bus configuration properties for
talking with other MOC applications. Every mission will need to change the connection
information within the <CONFIG> tag. The <CONFIG> tag contains a set of <PARAMETER>
tags, each of these is an argument used by the GMSEC API to define how to connect to
the GMSEC bus. For detailed instructions on GMSEC arguments, please see GMSEC
documentation. The majority of ANSR distributions use SmartSockets middleware and
can use the configuration provided by default and only need to change the IP addresses of
the SmartSockets servers.
To specify the IP addresses of the SmartSockets servers, find the line:
and change “XXX.XXX.XXX.XXX” to the IP address of the SmartSockets server. If
multiple, redundant SmartSockets servers are being used, add a second IP after the first
so it looks like:
The rest of the XML in the <GmsecTransport> describe what content different types of
messages will have and to what subjects they will be published. A mission should not
have to modify this from the provided data, but they will want to set the mission label and
default satellite label. GMSEC requires a satellite name on all its messages, and if the
message is not particular to one satellite (e.g. ANSR sends a message because it can no
longer talk to its proxy) it uses a default satellite label. These entries can be found inside
the <FIELD> tag where ‘NAME=”MISSION-ID”’ and ‘NAME=”SAT-ID-PHYSICAL”’.
The internal state sharing must be configured separately in the <ServerSync> tag. This
is required even if not running redundant servers, as the ANSR console also gets its state
information through this mechanism. ANSR can use IP multicast to share state, but this
is not supported for Solaris and only suggested for Microsoft Windows. The other option
is for ANSR to use the GMSEC bus. The <ServerSync><CONFIG> tag must specify the
same connection parameters as the <GmsecTransport><CONFIG> tag – though the other
tags inside <GmsecTransport> are not needed because we are not sending GMSEC
compliant messages – we are simply using the bus.
b. Configuring Emergency Pages
If the ANSR server hits a system problem like not being able to connect to the GMSEC
bus, it will send a page to a designated operator or system administrator. To designate
whom to page, find the line:
and change “XXX” to the name of the target to page. The target can be a person, a
group, or someone on-call in the group, as long as the value entered can be found in the
ANSRcfgtargets.xml configuration file. See the ANSR User’s guide for more
information on the targets.xml configuration file.
ANSR can impose a limit to the number of times to go through a call chain before giving
up. If it reaches that limit it will stop trying to deliver that page, but it will also send a
notification that no one responded to the page. To designate whom to notify, find the
and change “XXX” to the name of the target to page.
If ANSR loses connection with the internet because of firewall problems or because its
proxies fail, it will pop up a window at a designated computer or MOC that is staffed
around the clock.
From the ANSR server configuration file, you can not only configure where to pop up
this window, but you can change the text that will appear in the pop up. To change where
the window will appear, find the line:
and change “XXX” to the name of a target to page. That target should be a configured in
the ANSRcfgtargets.xml configuration file as either a “Popup” page or a group of
“Popup” pages. A “Popup” page is a page that takes the form of a pop up window and
starts with “<Popup name=…” See the ANSR User’s guide for more information on the
targets.xml configuration file.
The text that is displayed on the pop up should immediately follow the
“<PageIfNoInternet …” line, and is terminated by a line containing
“</PageIfNoInternet>”. The pop up window is used as a last resort and the message
should give the reader some context of where this sudden pop up is coming from as well
as indicating what critical people should be paged.
This feature is only available on Windows machines. If it is going to be used, a Windows
service called “Messenger” must be run on all ANSR server machines and on any
machines on which windows will be popped up. To run “Messenger”, run the Services
program found under Administrative Tools in the Windows Control Panel. A window
with a list of Windows services will appear. Scroll down to the “Messenger” service – by
default this service is disabled. Right click on the line and choose “Properties”. In the
properties window for the “Startup type” entry choose “Automatic” to have it
automatically run when the machine boots up. Then click “Start” to also have it run
immediately, and click “Ok”.
c. Configuring Redundant or Stand-Alone Servers
The configuration files as provided specify a redundant architecture. No changes need to
be made, though if there is one machine that is the preferred primary, this can be
designated. Find the section starting with “<ServerSync…” and set the attribute
“serverMode=”prime””. For the designated backup machine set the attribute to
“serverMode=”backup””. If no primary is specified, whichever server comes up first
will become primary.
If only one ANSR server will be running, set the attribute to “serverMode=”single””.
d. Configuring the ANSR Proxy
The ANSR proxy uses its own configuration file which is much simpler than the server
configuration file and needs to be changed very little from the configuration file provided
by default. To start with the default configuration, copy the file
ANSRcfgdevProxy.xml to a new name (e.g. trmmProxy.xml).
The proxy does not need to know the name or address of the server that will be
connecting to it, but it does need to know what port the server will be connecting to. The
proxy configuration file should start with the line.
Change the line to
where “XXX” is the port to which the server should connect to.
The ANSR server that will be using the proxy does need to know the IP address of the
proxy and the port it is listening on. Edit the ANSR server’s configuration file, and find
<OpenProxy host="XXX.XXX.XXX.XXX" port=="YYY"/>
and change “XXX.XXX.XXX.XXX” to the IP address of the proxy machine and “YYY” to the
port number the proxy will be listening on. If no port is specified the default port of 2678
is used. Each ANSR server should be configured to use all proxies by repeating the
e. Configuring the Firewall Bridge
GMSEC has a firewall bridge which works transparently inside the GMSEC API to allow
components to connect to a GMSEC bus that is behind a firewall. Currently this bridge is
in beta release and we do not recommend it for operations critical components. The
bridge is an application that must be run on the closed network. It will poll components
on the open network to see if they have messages to publish on the bus.
To configure a component to connect to a GMSEC bus behind a firewall simply specify
the following GMSEC configuration parameters.
Where 8160 is the port you want the bridge to poll – this can be any port number, you
will also specify it in the bridge configuration.
To run the bridge you must specify the connection parameters of the GMSEC bus and
must know the components it needs to poll. To configure this, edit the file stile.props in
ANSR/WEB-INF/classes/cfg. For each component, specify the IP address and a port to
poll (the same port specified in the client configuration).
gmsec.stile.client1.address = 184.108.40.206:8160
Also specify all parameters for connecting with the bus on the closed network.
gmsec.stile.client.bus.connectiontype = gmsec_ss
gmsec.stile.client.bus.server = tcp:192.168.1.5
gmsec.stile.client.bus.isThreaded = false
The bridge is in beta release. In the final release, it will be able to secure its
communication by restricting what open-side components can publish and subscribe to.
It will also be able to limit the frequency of connections going to the open-side.
Although ANSR will work with any version of GMSEC from 1.0 or later, the bridge
relies on GMSEC 2.0 functionality and cannot be used with earlier versions.
f. Configuring the Web-based Console
ANSR is already deployed as a working web application, and simply needs a web
application server to host it. Check with your web application server documentation on
how to declare the web application, though the procedure for doing so with Tomcat is:
1. Edit the file ANSR/WEB-INF/classes/cfg/ANSR_Context.xml
2. Specify in the “docBase” attribute the root directory of the ANSR release
3. Copy the ANSR_Context.xml to conf/Catalina/localhost/ under the
directory where Tomcat is installed.
If using an application configuration file other than the default dev.xml, edit ANSR/WEB-
INF/classes/cfg/webapp.props and specify the application configuration file.
Depending on the GMSEC connection you are using, the web application server may
need the GMSEC dynamic link libraries. This is not necessary if using one of the 100%
Java GMSEC API’s like java_gmsec_ss, java_gmsec_mb, or java_stile, but is necessary
for any GMSEC connections that use native code. On Windows, these are the .dll files in
<GMSEC>binwinRelease. On Unix these are the .so files in <GMSEC>/bin/<your
os>. Check with your web application server documentation on how to configure your
server to find these libraries. On Tomcat, simply copy these libraries to the bin/ directory
under where Tomcat is installed.
5. Running ANSR
ANSR was designed to run invisibly in the background and to start automatically at
machine startup. Setting this up is a very different process for Unix and Windows.
For unix systems, edit the script ANSRbinansrinit.sh and add ANSR and GMSEC
install locations as well as any middleware specific setup required. Then configure to run
automatically using the /etc/init.d framework. The ansrinit.sh script can be used to run
ANSR manually as well.
For Windows systems, ANSR must be installed as a Windows service. To configure
ANSR server to run automatically as a service, run the batch file
ANSRbinInstallServer.bat. The program will prompt you for the “deploy name”.
This is the name of the server’s configuration file without the directory name or “.xml”
extension (e.g. if your configuration file is “ANSR/cfg/trmm1.xml”, enter “trmm1” for
the deploy name). This will configure the ANSR server as a Windows service and set it
up to run automatically when the machine boots up. It will not immediately start the
ANSR service. You must use the Windows’ Services program found under
Administrative Tools in your Control Panel to immediately start or stop the ANSR server.
To uninstall the Windows service, simply run ANSRbinUninstallServer.bat and
enter the same deploy name. If the location of Java or the GMSEC API is changed, the
service must be uninstalled and reinstalled.
To run the server manually on Windows, use the script ANSRbinRunServer.bat.
Like the server, the proxy was designed to run in the background as a service.
For Windows, setting up the proxy is the same as setting up the server, but the batch files
InstallProxy.bat, UninstallProxy.bat, and RunProxy.bat are used instead.
For Unix, setting up the proxy is the same as setting up the server, just a proxy
deployment configuration file will be used.
c. Firewall Bridge
Like the server, the firewall bridge can be run in the background as a service.
For Windows, setting up the firewall bridge is the same as setting up the server, but the
batch files InstallStile.bat, UninstallStile.bat, and RunStile.bat are used
For Unix, setting up the firewall bridge is the same as setting up the server, but the shell
script stileinit.sh will be used.
The GUI-based console can be started on Windows by running
and on Unix with
ANSR/bin/runansr.sh console cfg/dev.xml
The web-based console can be started by pointing a browser at http://<your-web-
server-name-and-port>/ANSR/console.faces. See the web application server
documentation for starting and stopping your web application server.