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 prefer.

Do not start 'Tomcat' service yet. Replace 'c:\hosting' with the new directory path in the following parameters:

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 installation 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-9.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/

Replace 'www.yourkeysurvey.com' with the address of your Key Survey site. '8443' is the default Tomcat HTTPS port.

To improve security, 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. Using Microsoft Management Console stop Tomcat service, if it is running.

2. In 'c:\hosting\keysurvey-standalone\keysurvey\config.properties' file 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 443 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 access Key Survey site in the browser via site address without port numbers.

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 application.

• 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 should set up a reverse proxy Web server that will forward traffic to the application. You can setup Web server either on the same APP host, where Key Survey is installed, or on the dedicated Web hos

• 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 suggested 3-tier Key Survey deployment schema is the following:

HTTP traffic forwarding

There are a couple of technologies to perform 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.

More about ARR

You can find more documentation on ARR in these instructions:

• URL Rewrite Module 2.0 Configuration Reference | Microsoft Learn

• Reverse Proxy with URL Rewrite v2 and Application Request Routing | Microsoft Learn

Set up HTTP Web site in IIS 10 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.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 IIS 10 extension at https://www.iis.net/download/applicationrequestrouting

Once installed, you will see an 'Application Request Routing Cache' feature in 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, choose '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://:8080/{R:1}

• Replace with an address of the server where Key Survey application is running.

e. Click Apply

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 via Web server address

Set up HTTPS Web site in IIS 10 using ARR.

It is assumed that HTTP Web site is successfully setup at this point. In this section we will add HTTPS binding to Key Survey Web site and adjust URL Rewriting to work with HTTPS clients. URL Rewriting setup is similar to 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 Key Survey Web site.

3. 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 '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. Click OK.

d. Click 'Back to Rules' e. Click 'Add Rules'

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: (.*)

• Conditions 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://:8080/{R:1}

Replace with an address of server where Key Survey application is running.

• Check the checkbox 'Stop processing of subsequent rules'

h. Click Apply.

i. Click 'Back to Rules

' j. Select 'Key Survey HTTPS' rule in the list 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.

4. 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

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, 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

Tomcat Access log adjustment

Once users start using Key Survey application 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 ' <Value className="org.apache.catalina.valves.AccessLogValve"' so 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 user’s 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'.

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 User 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 User Data directory from default 'c:\hosting\keysurveystandalone\keysurvey\user-data\' to another place where the SAN/NAS folder is mounted, you should change the following:

• keysurvey\config.properties

CUSTOM_IMAGES_DIRECTORY – the value must be replaced with the path of new ‘user-data’ folder. For example:

CUSTOM_IMAGES_DIRECTORY=d:/data/shared/keysurvey/userdata

The last part of the path should remain as ‘user-data’

• conf\server.xml

find the following line line

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

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

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

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

• Once config changes are applied, restart Tomcat service.