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:
Filename | Parameters to edit |
---|---|
NEW_KEYSURVEY_PATH/keysurveystandalone/keysurvey/config.propertie | 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 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:
Using Microsoft Management Console stop Tomcat service, if it is running.
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:
It is assumed that web-server IIS 10 is already installed on the server. This section describes examples of IIS 10 configuration as a dedicated Web front end for Key Survey Application
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:
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'.
# | 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 |
2 | 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 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.