220 Forbes Road

Braintree MA 02184
Phone: (781) 849 8118
Fax: (781) 849 8133
WWW.KEYSURVEY.COM

Install Instructions for Key Survey v8.2

on MS Windows based systems
1. Introduction.
Key Survey application consists of two components: database and application. In the following instructions DB stands for
Database Server and APP stands for Application server. Each application component can be physically located on a
separate host or components can be installed on one server. In the latter case, consider DB and APP servers in the
following instructions as one and the same server.
The default Key Survey installation schema:

Web server in front of Key Survey application

In the default installation option, Key Survey runs on a standalone Apache Tomcat application server. This
is the simplest way to get Key Survey up and running.
However, you can consider using dedicated Web server as a front end to Key Survey application. In this
case Web server can work as a reverse proxy. Web server running in front provides some benefits:
usually, Web server handles heavy traffic better than application server itself. It can help protecting
APP server from overload
for security reasons, Web server can be placed into DMZ to handle raw traffic from Web clients
if you are going to run Key Survey site on HTTPS, Web server can offload SSL processing from APP
server
See Appendix A for additional installation options.

1.1. Before you begin.

Before you begin, you must verify the following:
Your environment should meet system hardware and software requirements. You can find those requirements in the
Key Survey v8.2 hardware and software requirements.pdf file in the Distributive Package provided by
WorldAPP.
You should prepare the following information to successfully install and configure Key Survey application:
Key Survey Web site name (or IP if you are going to run it on IP)
APP server IP or host name
DB server IP or host name
credentials to access DB on a DB server
DNS server IP or host name (for sending email)
SMTP server IP or host name and credentials if needed (for sending email)
Sender email address that Key Survey application can use in the "From" field in emails (update profile,
registration, password reminder emails, etc).

1.2. Key Survey distributive contents.

Key Survey distributive provided by WorldAPP inc. includes the following items:
Key Survey Application with preconfigured Apache Tomcat config files
initial Key Survey database dump
install instructions
version.txt file that contains version information of provided Key Survey application
Key Survey distributive package is a ZIP archive named 'keysurvey-standalone-VERSION-ENVIRONMENT.zip'. Here
VERSION stands for Key Survey version and build number. ENVIRONMENT includes several acronyms separated by dash,
those identify the environment the distributive is intended for.
For example, keysurvey-standalone-v82b53-w2k8-tomcat70-mysql.zip means that the package contains:
Key Survey version 8.2, build 53
initial database dump for MySQL DBMS
config files for Tomcat 7.0.x
config files and scripts for Windows 2008 Server OS
Other examples of environment acronyms that can be specified in the package name:
lin stands for Linux OS
ms2k8 stands for Microsoft SQL Server 2008
ora11g stands for Oracle DB 11g

1.3. Extracting the distributive package.

If you have not extracted the Key Survey distributive package yet, make sure destination disk partition has 1 GB of free
space. Unzip distributive package and go to the folder, the package was extracted to.
In the distributive folder you can find a ZIP archive with Key Survey files 'keysurvey_app/keysurvey-standalone.zip'
and initial Key Survey database dump 'keysurvey_database/<your_db_type>/<db_dump>'. Here <your_db_type> varies
according to your choice of the database type and can be one of the following: mysql, ms_sql or oracle. <db_dump> also
varies according to the database type and version of your DBMS.
If needed, copy 'keysurvey_app/keysurvey-standalone.zip' and DB dump file to the appropriate folders on APP host and
DB management host respectively.

1.4. Firewall settings

Firewall should be properly configured between Key Survey components to allow Web clients (survey designer,
respondents) to work with Key Survey and to allow Key Survey components communicate with each other.
To master a Firewall for Default Key Survey installation, see the following traffic flow schema.
The idea is to allow traffic flow from 'Source' to 'Destination' on 'Destination Protocol/Port'.
#

Source

Destination

Dst
Proto/Port

Notes

Internet/Intranet
Web client

Key Survey APP

server

tcp/8080
(tcp/8443)

HTTP(S) traffic from Internet/Intranet Web clients to

Key Survey APP

Key Survey APP

Key Survey APP

server

tcp/8080
(tcp/8443)

HTTP(S) traffic from Key Survey to itself for drawing

Survey snapshots, etc

Key Survey APP

Key Survey MySQL

DB server

tcp/3306

JDBC traffic from Key Survey APP to MySQL DB

Key Survey APP

Key Survey Oracle

DB server

tcp/1521,
tcp/1526

JDBC traffic from Key Survey APP to Oracle DB

Key Survey APP

Key Survey MS SQL

DB server

tcp/1433

JDBC traffic from Key Survey APP to MS SQL DB

Key Survey APP

DNS server

udp/53

DNS traffic. This is needed for email sending

Key Survey APP

SMTP server

tcp/25

SMTP traffic. This is needed for email sending

Use the APP-to-DB lines according to the type of your DB.

2. Database setup and configuration.

MS SQL Server
This section assumes that Microsoft SQL Server 2008 is already installed on DB host. If not, you should
install it properly. Before installing you should check all hardware and software system requirements. For
MS SQL Server 2008, follow this link:
http://msdn.microsoft.com/en-us/library/ms143506%28v=SQL.100%29.aspx

1. Restoring the DB Dump on the DB server.

The DB Dump for MS SQL Server is located in the 'keysurvey_database\ms_sql\ms2k8_db.dump' file in the
Distributive Package provided by WorldAPP.
You can restore the Key Survey Database using either of the two options: via SQL commands or via
GUI of MS SQL Management Studio. Both options are described below.
Restoring the Dump with the help of SQL commands.
restore database <DB_name>
from disk='<Path_To_Distributive_Folder>\keysurvey_database\ms_sql\ms2k8_db.dump'
with
move 'keysurvey' to '<DB_path>\<DB_name>.dat',
move 'keysurvey_log' to '<DB_path>\<DB_name>.log'

Change parameters in angle brackets < > according to your system:

<DB_name> DB name which is specified according to the DB naming rules in MS SQL Server
<DB_path> path to the MS SQL Server database files
<Path_To_Distributive_Folder> path to Key Survey Distribution Package
For example:

restore database keysurvey

from
disk='d:\keysurvey-standalone-v82b53-w2k8-tomcat70-ms2k8\keysurvey_database\ms_sql\ms2k8_db.dump'withm
'keysurvey' to 'c:\db\keysurvey.dat',
move 'keysurvey_log' to 'c:\db\keysurvey.log'

Restoring the DB dump using GUI of MS SQL Management Studio.

For this, right-click on 'Databases' and choose 'Restore Database'. Then type the name of the database,
choose 'From Device:' source and browse for DB Dump. 'Files of type' should be selected as 'All types'.

Once all these steps are done, click 'Ok'. Refresh MS SQL Object Explorer. 'Keysurvey' database should now
appear in database list.
2. Create a DB user and grant him all privileges on <DB_name> database.
Select users from Security/Logins

Right click Logins

Enter Login Name: member (for example)
Choose SQL Server authentication
Enter password: 123456 (for example Note: this should be a password that can not be easily
guessed and should be the same user and password that was configured before)
Uncheck Enforce password policy
Default database: Change to KeySurvey
Default language: <default>

Go to Server Roles
Check dbcreator role if unchecked

Go to User Mapping
Click on the KeySurvey database in the list of databases
Check db_owner role (Note: Public is also checked) for this database

Check Logins to see that these settings have been updated (for example, check that the member has
the dbo role)
Logout and login back as the member to verify that username and password is set correctly and that it has
correct privileges

MySQL
MySQL 5.0 or 5.1 is required for the Key Survey application. It is recommended to use the latest stable version of MySQL.
If MySQL package of the needed version is already installed and configured, you can skip steps 1-2 of this section and go
to instructions described in step 3.
1. Installation package is available for download at MySQL site on the following page
http://dev.mysql.com/downloads/mysql/5.1.html. Download MySQL distributive for your OS version and DB server
architecture.
2. Install downloaded package, setup and start MySQL server.
We recommend using 'my-innodb-heavy-4GB.ini' as a template config file for MySQL.
In the folder where MySQL is installed, just copy that file into 'my.ini' and edit the settings in
'my.ini' for your individual needs.
comment out 'log-bin' option if you do not plan using data replication
comment out 'slow_query_log' option
the default value of '2G' in 'innodb_buffer_pool_size' is sufficient amount of memory
dedicated to the DB. However, if you do not have enough free memory on the DB server,
you can at first set this option to '1G' or '512M'. Note, that total amount of memory on the
DB server should be at least 30% higher than you are allocating to MySQL.
3. Log in to MySQL server with any MySQL client using user account with privilege for creating database. Create
database for Key Survey application. See example of the SQL command to create 'keysurveydb' database below:
create database keysurveydb default charset utf8;

4. Grant privileges in created database to user 'keysurvey', that will be used in Key Survey application to connect to
the database. See example of the SQL command to grant privileges below:
grant all privileges on keysurveydb.* to keysurvey@192.168.0.3 identified by changeit;

In this command you can change database name keysurveydb, user name keysurvey and password changeit
and use these in the application configuration in section 3. You should also replace the address 192.168.0.3 with
an IP address of the APP server.

5. Restore Key Survey initial database from SQL dump that you can find in 'keysurvey_database\mysql\my_db.sql' file
in the Key Survey distributive folder. This step can be performed with the help of the following SQL commands:
use keysurveydb;
source PATH_TO_DISTRIBUTIVE_FOLDER\keysurvey_database\mysql\my_db.sql;

Path to my_db.sql must be replaced with a path to the database dump in the Key Survey distributive folder or
folder on your server, where you have copied the DB dump file to.

Oracle 11G
1. To insert application data into the DB, a separate tablespace should be created. This can be done by Oracle DB
administrator with DBA privileges. Once logged into the DB with DBA privileges, use any program that allows
execution of SQL commands to the DB, such as 'sqlplus' or 'sqlplusw' and run the following SQL command:
CREATE TABLESPACE "KEYSURVEYDB"
LOGGING
DATAFILE 'KEYSURVEYDB.DBF' SIZE 500M
AUTOEXTEND
ON NEXT 200M MAXSIZE UNLIMITED EXTENT MANAGEMENT LOCAL
SEGMENT SPACE MANAGEMENT AUTO;

This command creates a tablespace named 'KEYSURVEYDB' in the 'KEYSURVEYDB.DBF' file, its size is 500 MBytes
and it automatically extends every time it is completely filled with data during work. DATAFILE parameter in this
command is a full path to the file where data is stored. The path should contain logical disk label and name with
.ORA or .DBF extension. In case of intensive application usage the size of the file and its autoextension can be
increased. The name of the tablespace though should not be altered, as the DB dump supplied in the distributive
package requires the data to be in the tablespace named 'KEYSURVEYDB' only. For example, SQL command to
create a tablespace with size of 1000 MBytes and auto extension for 500 MBytes should look like the following:
CREATE TABLESPACE "KEYSURVEYDB"
LOGGING
DATAFILE 'C:\ORACLE\DATA\KEYSURVEYDB.ORA' SIZE 1000M
AUTOEXTEND
ON NEXT 500M MAXSIZE UNLIMITED EXTENT MANAGEMENT LOCAL
SEGMENT SPACE MANAGEMENT AUTO;

Note, it is necessary to make sure that 1) the specified path to the file exists (and create such if it does not), 2)
Oracle has all the rights needed for file creation in this directory and 3) there is enough disc space for the file of the
given size. If the tablespace with the given name already exists, then it is necessary to make sure it has enough
free space for the database of the application. Otherwise, the size of the file (or files, if the tablespace is located in
several files), needs to be extended. The recommended free space in the tablespace for the application startup and
to start working is 500 MBytes. Further it can be extended, or automatic extension can be set for the file. To avoid
errors during queries to the DB, every SQL command must end with a semicolon ";". This setup can be performed
with the help of the graphical utility 'Oracle Enterprise Manager Console' supplied with the Oracle distributive or the
utility bundle for DB Oracle maintenance.
2. To import data to the DB and to connect the application to the DB, create a user (DB scheme) with restricted
privileges. This user must have privileges for data import in 'KEYSURVEYDB' tablespace and rights for remote
connection to the database. Once connected to the database with DBA privileges, create a user with name
'KEYSURVEY' and password 'changeit' using the following SQL command:
CREATE USER "KEYSURVEY"
PROFILE "DEFAULT"
IDENTIFIED BY "changeit"
DEFAULT TABLESPACE "KEYSURVEYDB"
TEMPORARY TABLESPACE "TEMP"
QUOTA UNLIMITED ON "KEYSURVEYDB"
ACCOUNT UNLOCK;

Assign necessary privileges to this user using following SQL-commands:

GRANT CREATE TRIGGER TO "KEYSURVEY";
GRANT CONNECT TO "KEYSURVEY";

You can change user name 'KEYSURVEY' used in above-mentioned SQL commands. The specified password
'changeit' used to create a user can be also changed at your discretion. To ensure application can connect to the
DB, the database password and user name should be specified in application configurations in 'config.properties' file

in section 3 of these instructions. User with appropriate privileges and options can be created with the help of
graphical Oracle database management utility 'Oracle Enterprise Manager Console'.
3. Copy the DB dump file 'ora11g_db.dump', which is located in 'keysurvey_database\oracle' the Key Survey
distributive folder, to Oracle system folder DP_DUMP. Import data with the help of 'IMPDP' utility, which is provided
with Oracle Database Server distribution. For this, connect to the database with DBA privileges. To import data run
the following command in the command line:
shell> impdp SYSDBA@SID SCHEMAS=KEYSURVEY DUMPFILE=ora11g_db.dump
REMAP_SCHEMA=KEYSURVEY:LOCAL_KEYSURVEY REMAP_TABLESPACE=KEYSURVEYDB:KEYSURVEYDB

Replace 'SYSDBA' with user name, which has DBA privileges (SYSTEM as example). 'SID' should be replaced with
Oracle database instance, where this user is created. If in the "CREATE USER ..." command mentioned in step 2,
other than "KEYSURVEY" user name is used, then it should be specified in the "REMAP_SCHEMA" instead of
"LOCAL_KEYSURVEY" parameter. "REMAP_TABLESPACE" option should remain unchanged since it is indicating
previous DB user in the provided DB dump. Below is the sample of data import command:
shell> impdp SYSTEM@oraDB SCHEMAS=KEYSURVEY DUMPFILE=ora11g_db.dump
REMAP_SCHEMA=KEYSURVEY:KEYSURVEY REMAP_TABLESPACE=KEYSURVEYDB:KEYSURVEYDB

If password is requested during data import, enter the password for SYSDBA user (SYSTEM in example above). If
import is successful you will receive the following message 'Import terminated successfully...'. If for some reason
data import resulted in error, created user should be deleted with the help of SQL command mentioned below and
then recreated using instructions from the previous step.To recreate DB user you should connect to the DB with
DBA privileges. See the SQL command used to delete a user below:
DROP USER "KEYSURVEY" CASCADE;

Replace "KEYSURVEY" with the name of the user, created in the previous step of this document. Further it is
necessary to repeat data importing process and specify additional parameter in the import command. Parameter
'log=logfile.txt' with the name of the file turns on logging of import command, and output will be logged into this
file. See the sample of import command, where output logging is included:
shell>impdp SYSTEM@oraDB SCHEMAS=KEYSURVEY DUMPFILE=ora11g_db.dump
REMAP_SCHEMA=KEYSURVEY:KEYSURVEY REMAP_TABLESPACE=KEYSURVEYDB:KEYSURVEYDB LOG=import_log.txt

Analysis of created 'import_log.txt' file will help determine the reasons for occurring errors during data import
process.

3. Key Survey application setup and configuration.

1. Application Setup.

Please note that we do not support 32-bit Windows!

This section instructions assume that all preparations, installation and configuration steps are
performed on the APP host under the Administrator account.

Before you proceed with application files setup, make sure that Oracle JRE or JDK 6 is already installed on the APP
host, where you are going to install Key Survey Application. Oracle JRE or JDK can be installed from the installer
which can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/index.html. It is
recommended to download and install the latest available JRE build of Java SE 6. Chose Installer version for
Windows based platform.

Java VM implementations other than from Oracle/Sun are not supported.

If you prefer to install Key Survey application into directory other than 'c:\hosting' as described in
this section, see Appendix A for additional installation options.
a. Create 'c:\hosting' directory, where the application will be located (if it does not exist)
b. Extract 'keysurvey-app\keysurvey-standalone.zip' file from the Key Survey distributive folder into the
'c:\hosting\' directory.
Folder 'keysurvey-standalone' should appear in the 'c:\hosting\' directory.
2. Application Configuration.
a. Edit the 'c:\hosting\keysurvey-standalone\keysurvey\config.properties' file using tips in the comments.
Comments and examples are prefixed by '#' character at the beginning of the line. All the parameter values
enclosed into angle brackets '<>' should be replaced with the values appropriate to your site. Angle
brackets should be removed.
'DB_CONNECTION', 'DB_LOGIN' and 'DB_PASSWORD' values should be set using DB host, DB name, DB
credentials values that have been configured during the database setup in Section 2.
b. Run 'c:\hosting\keysurvey-standalone\bin\service-install.bat' to register Tomcat 7 service.
To check that service was installed successfully, run Start->Administrative Tools->Services.
You should see 'Apache Tomcat 7' service in the list.
c. Run 'c:\hosting\keysurvey-standalone\bin\tomcat7w.exe' to set up Tomcat parameters.
d. Click on the 'Java' tab and add the parameters listed below on a separate line into 'Java Options' field
-Djava.awt.headless=true
-XX:PermSize=392M
-XX:+UseConcMarkSweepGC
-XX:+UseParNewGC

In the 'Initial memory pool' and 'Maximum memory pool' fields type '4096' , and click 'Apply'.

e. Key Survey application has a number of password protected service pages. Default credentials for these
pages are 'admin' and 'password'. It is highly recommended to change the default password in the file
'c:\hosting\keysurvey-standalone\conf\tomcat-users.xml'. You can change the password by editing the
following line
<user username="admin" password="password" roles="keysurveyadmin"/>

3. Start Tomcat service. Application will start in about 1-2 minutes.

You can watch logs in 'c:\hosting\keysurvey-standalone\logs' directory. Log files may contain useful information for
resolving any errors occurring during start up process or application work.
4. Once Key Survey application is started you should use link specified in the 'URL_PATH.SURVEY' parameter in the
'config.properties' file to access Key Survey application in your browser.

At this point you have your Key Survey site up and running. It is available via the internal server name or
IP of your APP host or via other domain name you have configured for the site.
By default, with basic installation option, Key Survey site is available on TCP port 8080 the default
Tomcat HTTP port. According to this don't forget to enable Windows Firewall rule to access the Key Survey
application via port 8080.
Do not forget to add the colon and port number to the site address in the browser so that it looks like this:
http://www.yourkeysurvey.com:8080/
If you would like to run Key Survey site on the standard HTTP port tcp/80, to eliminate the 8080 from the
site address, see Appendix A for additional installation options.

4. Key Survey lifecycle maintenance (optional)

Once Key Survey application is installed, you can setup Monitoring and Backups. This step is optional, however it is
strongly recommended not to skip Monitoring and Backup setup to make sure your Key Survey Web site is always online
and Survey data is safely stored in backups.
Monitoring of Key Survey application
Key Survey site availability
The Web sites availability should be checked by loading the page
http(s)://<KeySurveySite>/StatusInformator/QuickTest.jsp

This page is secured by HTTP credentials stored in '/hosting/keysurvey-standalone/conf/tomcat-users.xml'

file.
QuickTest.jsp prints the status of connection to DB and the APP uptime.
Example of output:
connection=OK uptime=1 month 27 days 21 hours 18 min

The Key Survey application is working fine if:

HTTP 200 OK status received
"connection=OK" text is displayed on the page
Disk space on:
c:\hosting\keysurvey-standalone\logs log files of Tomcat and Key Survey
c:\hosting\keysurvey-standalone\temp temporary files of Tomcat and Key Survey
c:\hosting\keysurvey-standalone\keysurvey\survey-data survey images, styles and other
data files
Backup of Key Survey data
The frequency of performing backup tasks should be chosen depending on the intensity of data collected: new
surveys, new respondents.
Key Survey Database
Backup tasks for Key Survey Database should be performed using any of available internal or 3rd party tools
for your DBMS.
Backup of Metadata like constraints and stored procedures should be processed along with DB Tables.
Key Survey Data Files at c:\hosting\keysurvey-standalone\keysurvey\survey-data\
Backup tasks for Survey images, styles and other data files should be performed using any of available
system tools.
Backup of Survey files should be performed approximately at the same time as DB backup.

Appendix A. Additional Key Survey installation options

A.1. How to install Key Survey into directory other than default
'c:\hosting'.
Key Survey application can be installed into the directory other than default 'c:\hosting'. Just follow instructions in Section
3 and instead of 'c:\hosting' directory use any other directory you want. Do not start 'Tomcat' service yet.
Replace 'c:\hosting' with the new directory path in the following parameters:
Filename

Parameters to edit

NEW_KEYSURVEY_PATH/keysurvey-standalone/keysurvey/config.properties

LOGS_DIRECTORY
CUSTOM_IMAGES_DIRECTORY
CUSTOM_TEMP_DIRECTORY
CUSTOM_DATA_DIRECTORY
DB_CONNECTION.VIRTUAL
ACTIVE_MQ_DIR
CERT_PATH

Now you can start 'Tomcat' service using Microsoft Management Console.

A.2. How to run Key Survey site in secure mode in default standalone
installation.
Tomcat of Key Survey distributive has to be configured to handle HTTPS traffic. This can be done following the instructions
from Apache Tomcat official site: http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html
All needed settings in 'server.xml' file mentioned in Tomcat documentation have to be applied to the
'c:\hosting\keysurvey-standalone\conf\server.xml' file of Key Survey installation.
Key Survey should be configured to work with HTTPS links. This can be accomplished by adjusting parameters in
'c:\hosting\keysurvey-standalone\keysurvey\config.properties' file.
SECURE_URL_PATH.SURVEY=https://www.yourkeysurvey.com:8443/
ALLOW_SECURE_LOGIN=true

Replace 'www.yourkeysurvey.com' with the address of your Key Survey site. '8443' is the default Tomcat HTTPS port.
To improve security on your Key Survey site, turn on redirection to Secure connection on admin pages. Change the value
of 'ALLOW_SECURE_LOGIN.SURVEY' to 'true' in 'keysurvey/config.properties':

ALLOW_SECURE_LOGIN.SURVEY=true

A.3. How to run Key Survey site on standard HTTP ports in basic
standalone installation.
To run Key Survey site on standard HTTP and HTTPS ports follow the steps below
1. Stop 'Tomcat' service, if it is running, using Microsoft Management Console
2. In 'c:\hosting\keysurvey-standalone\keysurvey\config.properties', remove port numbers from URL related settings:
URL_PATH.SURVEY=http://www.yourkeysurvey.com/
SECURE_URL_PATH.SURVEY=https://www.yourkeysurvey.com/

Replace 'www.yourkeysurvey.com' with the address of your Key Survey site.

3. In 'c:\hosting\keysurvey-standalone\conf\server.xml', edit HTTP connector settings to listen on port 80 instead of
default 8080. Edited block will look like this:

<Connector port="80" protocol="HTTP/1.1"

redirectPort="8443"
maxThreads="1000"
URIEncoding= "UTF-8" />

4. If you have configured Tomcat to work over HTTPS on port 8443 then in
'c:\hosting\keysurvey-standalone\conf\server.xml', edit SSL HTTP connector settings to listen on port 443 instead
of default 8443. Edited block will look like this:
<Connector port="443" protocol="HTTP/1.1"
SSLEnabled="true"
maxThreads="1000"
scheme= "https" secure="true"
clientAuth= "false" sslProtocol="TLS" />

5. Start 'Tomcat' service

Now you can type the address of Key Survey site without port number in the browser address bar.

A.4. How to run dedicated Web server in front of basic Key Survey
installation.
You can consider running dedicated Web server in front of Key Survey instance for several reasons:
if you want Key Survey site to handle traffic from public network (Internet) while running Key Survey instance in
the restricted area. In this case you have to set up a reverse proxy Web server in DMZ that will forward traffic to
Key Survey.
if you want Key Survey site to be accessible over standard HTTP ports while running Key Survey instance under
non-privileged ports. In this case you have to set up a reverse proxy Web server that will forward traffic to the Key
Survey. You can setup Web server either on the same APP host, where Key Survey is installed, or on the dedicated
Web host.
if you want to terminate HTTPS traffic on the dedicated Web server to eliminate decryption overhead from APP
server and forward plain traffic to the Key Survey instance.
If any item from this list meets your needs, find an appropriate solution below.
The supposed Key Survey deployment schema is of 3-tier way like the following:

It is assumed that web-server IIS7 is already installed on the server. This section describes examples of
IIS7 configuration as a dedicated Web front end for Key Survey Application.

HTTP traffic forwarding

There are a couple of technologies to perform a traffic forwarding from Web server to Tomcat. In these
instructions we will use Application Request Routing (ARR) for IIS since it is less complicated than
others and is relatively simple to set up.
There is also Tomcat Connector from Apache foundation for the same purpose. In previous versions of Key
Survey distributive, it was the preferred option for traffic forwarding. However, as of v8.0 Key Survey it is
able to work in conjunction with ARR and we moved to ARR completely.

More about ARR

You can find more documentation on ARR in these instructions:
http://learn.iis.net/page.aspx/665/url-rewrite-module-20-configuration-reference/
http://learn.iis.net/page.aspx/659/reverse-proxy-with-url-rewrite-v2-and-application-request-routing/

Set up HTTP Web site in IIS7 using ARR.

1. Launch Internet Information Services Manager
2. Create a Web site
On the left-side panel click on the plus to the left of your server name.
In the tree that opens right-click on 'Sites' and choose 'Add Web Site' from the dropdown list.
Fill in the 'Site name' field (enter KeySurvey) in the 'Add Web Site' window.
In the 'Path' field of the 'Web Site Home Directory' window specify the path to the application
(c:\hosting\keysurvey-standalone\keysurvey\app).
In the 'Binding' window leave 'All Unassigned' IP Address.
If your security policy contradicts this statement you should select required IP address.
Leave port 80 as is.
If necessary, enter a site name into the 'Host name' field, e.g. www.keysurvey.site.domain.
If you do not specify the site's name, the site will fail to load due to a conflict with the Default Web Site. To
resolve that, you can turn off the Default Web Site or remove it completely from IIS configuration.
Click Ok.

3. Install ARR
Download the appropriate install for the ARR IIS7 extension at

http://www.iis.net/download/applicationrequestrouting
Once installed, you can see an 'Application Request Routing Cache' feature at the list of Web server features

4. Enable proxy option

Launch 'Application Request Routing Cache' and click 'Server Proxy Settings' in the right Actions pane.
Check the 'Enable proxy' checkbox

5. Create a Rewrite rule for traffic forwarding

a. On the left-side pane tree select KeySurvey Web site and launch a 'URL Rewrite' tool

b. Click 'Add Rules' in the Actions pane

c. In the window that opens, chose 'Blank Rule' in the 'Inbound Rules' section
d. In the pane 'Edit Inbound Rule' enter the values as following:
Name: Key Survey HTTP
Match URL section:
Requested URL: Matches the Pattern
Using: Regular Expressions
Pattern: (.*)
Action section
Action type: Rewrite
Rewrite URL: http://<IP address of APP server>:8080/{R:1}

Replace <IP address of APP server> with an address of server where Key Survey application is
running.
e. Click Apply on Actions pane when done

6. Turn on preserving Host Name in HTTP headers

Run CMD shell on Web server and run the following commands:
cd c:\Windows\System32\inetsrv
appcmd.exe set config -section:system.webServer/proxy /preserveHostHeader:"True"
/commit:apphost

HTTP forwarding setup is complete

At this moment you should be able to access Key Survey site in your browser by entering a Web server
address into address bar.

Set up HTTPS Web site in IIS7 using ARR.

It is assumed that HTTP Web site is successfully setup at this point. In this paragraph we will add HTTPS binding to
KeySurvey Web site and adjust URL Rewriting to work well with HTTPS clients. URL Rewriting setup is similar to the one of
HTTP site. The difference is adding HTTP Header X-Forwarded-Proto to client's requests to let Key Survey application
know that client is using HTTPS.
1. Launch Internet Information Services Manager.
2. Set up HTTPS binding on KeySurvey Web site
Refer to the page http://learn.iis.net/page.aspx/144/how-to-set-up-ssl-on-iis/ (section 'IIS Manager' for GUI) to
create an appropriate server certificate and add HTTPS binding to KeySurvey Web site.
3. Create a Rewrite rule for traffic forwarding
a. On the left-side pane tree select KeySurvey Web site and launch an 'URL Rewrite' tool

b. Click 'View Server Variables' in the Actions pane. 'Allowed Server Variables' will appear in the middle.
c. Click 'Add' in the Actions pane and enter 'HTTP_X_FORWARDED_PROTO' in the Server Variable Name field.
Then click OK.
d. Click 'Back to Rules' in the Actions pane
e. Click 'Add Rules' in the Actions pane
f. In the window that opens, chose 'Blank Rule' in the 'Inbound Rules' section
g. In the pane 'Edit Inbound Rule' enter the values as following:
Name: Key Survey HTTPS
Match URL section:
Requested URL: Matches the Pattern
Using: Regular Expressions
Pattern: (.*)
Condition section. Click Add and enter the following:
Condition input: {HTTPS}
Check if input string: Matches the Pattern
Pattern: on
Click OK
Server Variables section. Click Add and enter the following:
Server variable name: HTTP_X_FORWARDED_PROTO
Value: HTTPS
Click OK
Action section
Action type: Rewrite
Rewrite URL: http://<IP address of APP server>:8080/{R:1}
Replace <IP address of APP server> with an address of server where Key Survey application is
running.
Check the checkbox 'Stop processing of subsequent rules'
h. Click Apply on Actions pane when done

i. Click 'Back to Rules' in the Actions pane

j. Select 'Key Survey HTTPS' rule in the list of the top middle pane and click 'Move Up' in the Actions pane.
Click Yes on the Warning message that opens.
'Key Survey HTTPS' rule should move above the 'Key Survey HTTP' rule.
The rule list should look like the following:

4. Turn on preserving Host Name in HTTP headers

Run CMD shell on Web server and run the following commands:

4.

cd c:\Windows\System32\inetsrv\
appcmd.exe set config -section:system.webServer/proxy /preserveHostHeader:"True"
/commit:apphost

Make sure that the value of 'SECURE_URL_PATH.SURVEY' in 'keysurvey\config.properties' corresponds to the HTTPS Web
site address you configured in IIS:

SECURE_URL_PATH.SURVEY=https://www.yourkeysurvey.com/

To improve security on your Key Survey site, turn on redirection to Secure connection on admin pages. Change the value
of 'ALLOW_SECURE_LOGIN.SURVEY' to 'true' in 'keysurvey\config.properties':

ALLOW_SECURE_LOGIN.SURVEY=true

HTTPS forwarding setup is complete

At this moment you should be able to access Key Survey site over HTTPS protocol in your browser by
entering a Web server address into address bar.

Tomcat Access log adjustment

Once users start using Key Survey over Front end Web server, you will see a Web server's IP in Tomcat Access log file
instead of user IP address in the first field
c:\hosting\keysurvey-standalone\logs\keysurvey_access_log.DATE
If you want to see a real user IP in the Access log file, follow the steps below:
1. Open c:\hosting\keysurvey-standalone\conf\server.xml file for editing.
2. Find a Key Survey host description there:

<Host name="keysurvey" appBase="">

3. Edit the statement that begins with '<Valve className="org.apache.catalina.valves.AccessLogValve"' so that it

looks as following:

<Valve className="org.apache.catalina.valves.AccessLogValve"
directory="logs" prefix="keysurvey_access_log." suffix=".txt"
pattern='%{X-Forwarded-For}i %v %u %t %m %U%q %H %s %b %{Referer}i "%{User-Agent}i" %D
%S' resolveHosts="false"/>

Here a default pattern's first field '%h' is replaced with '%{X-Forwarded-For}i'.

4. Restart Tomcat service.
Now users IP address will be displayed in the Tomcat Access log.

Firewall settings
To configure the Firewall, rule #1 and rule #2 from section '1.4. Firewall settings' should be replaced with the following.
The idea is to allow traffic flow from 'Source' to 'Destination' on 'Destination Protocol/Port'.
#

Source

Destination

Dst
Proto/Port

Notes

1.1

Internet/Intranet Web
client

Key Survey Web

server

tcp/80
(tcp/443)

HTTP(S) traffic from Internet/Intranet Web clients

1.2

Key Survey Web

server

Key Survey APP

server

tcp/8080

HTTP traffic from Web server to Key Survey APP

Key Survey APP

Key Survey Web

server

tcp/80
(tcp/443)

HTTP(S) traffic from Key Survey to itself to take Survey

snapshots, etc

A.5. How to setup 2 separate front end Web servers: for external and
internal users.
If you would like to handle traffic to Key Survey site by different Web servers, set up both as described in the section
above. The important thing here is that Key Survey virtual host on both Web servers must work with one and the same site
address. For example, if external users work on Key Survey site using address 'www.yourkeysurvey.com' then internal
users must use the same 'www.yourkeysurvey.com'. In this case your DNS system must be set up properly to resolve
'www.yourkeysurvey.com' to different IP for external and internal users.

A.6. How to set up High Available Key Survey site.

At the moment the only available option for building High Available (HA) Key Survey installation is Warm standby.
This scenario assumes that two instances of Key Survey application are set up on separate servers: Active and Standby. In
the normal condition, Active instance handles incoming Key Survey traffic. Standby instance is turned off at this time. In
case of a failure on the Active instance, Tomcat on Standby instance has to be started and Key Survey site's traffic should
be directed to the Standby instance that becomes now Active.

Warning
Important! Only one instance should be running at the same time.

Instances should be set up as the following.

Both instances should be set up in the similar environment. This involves Java version, Tomcat version, memory
settings.
Since the contents of DB and Survey Data directory in Key Survey application is the subject to change often, the
Standby instance must be in sync with those components from Active instance. The sync should be performed using
DMBS or OS or other 3rd party tools.
If you have a reliable solution for the DB and SAN/NAS for Survey Data directory, replication can be avoided.
In this case, Active and Standby instances should have an identical value in DB_CONNECTION parameter in
'config.properties'.
If you need to move the Survey Data directory from default 'c:\hosting\keysurvey-standalone\keysurvey\survey-data\' to
another place where the SAN/NAS folder is mounted, you should tune the following:
keysurvey\config.properties
CUSTOM_IMAGES_DIRECTORY the value must be changed to the path of new 'survey-data' folder. For example:

CUSTOM_IMAGES_DIRECTORY=d:/data/shared/keysurvey/survey-data

The last part of the path should remain as 'survey-data'

conf\server.xml
locate the line

<Context path="/survey-data" docBase="${catalina.base}/keysurvey/survey-data" />

Replace the value of docBase with the path to new 'survey-data' folder. For example:

<Context path="/survey-data" docBase="d:/data/shared/keysurvey/survey-data" />

Key Survey application must be able to read/write to new 'survey-data' folder;

once config changes are applied, restart Tomcat service.

Appendix B. Additional Key Survey features

B.1. LDAP and NTLM
If you want to integrate LDAP directory service or NTLM (Single Sign-On) in Key Survey application to control users' access
to the application you should follow step-by-step guide which is described in LDAP and NTLM Integration Guide.pdf file
in the Distributive Package provided by WorldAPP.

B.2. Bounce email processing

To enable bounced email processing create an imap mailbox where bounced emails will be delivered, for example
bounce@yourdomain.com. Then add the following code to the
'c:\hosting\keysurvey-standalone\keysurvey\config.properties' file and change parameters in the angular brackets
according to your configuration.

##################################BOUNCED EMAILS SPECIFIC

PROPERTIES###############################
# Enables the Bounced Processor
BOUNCED_PROCESSOR_START=true
# Delay in minutes between mailbox checks
MAIL_BOUNCED_SERV_MINUTES_DELAY=60
# Whether to delete the processed messages
MAIL_BOUNCED_DELETE=true
# Pattern to create ReturnPath email header. Do not remove '+{0}'
BOUNCED_ADDRESS_TEMPLATE=bounce+{0}@yourdomain.com
# Email retrieving protocol
MAIL_BOUNCED_PROTOCOL=imap
# Email account settings
MAIL_BOUNCED_USER=<MAIL_BOUNCED_USER>
MAIL_BOUNCED_PASSWORD=<MAIL_BOUNCED_PASSWORD>
mail.imap.host=<MAIL_IMAP_HOST>
##################################END BOUNCED EMAILS SPECIFIC
PROPERTIES###########################

For example this section can be look like this one:

##################################BOUNCED EMAILS SPESIFIC

PROPERTIES###############################
# Enables the Bounced Processor
BOUNCED_PROCESSOR_START=true
# Delay in minutes between mailbox checks
MAIL_BOUNCED_SERV_MINUTES_DELAY=60
# Whether to delete the processed messages
MAIL_BOUNCED_DELETE=true
# Pattern to create ReturnPath email header. Do not remove '+{0}'
BOUNCED_ADDRESS_TEMPLATE=bounce+{0}@yourdomain.com
# Email retrieving protocol
MAIL_BOUNCED_PROTOCOL=imap
# Email account settings
MAIL_BOUNCED_USER=bounce
MAIL_BOUNCED_PASSWORD=password
mail.imap.host=192.168.0.2
##################################END BOUNCED EMAILS SPECIFIC
PROPERTIES###########################