vReporter Data Server Installation Instructions

Version: 1.2
Date: October 24, 2014
Contents
vReporter Data Server Installation Instructions ........................................................................................... 1
Pre-requisites ............................................................................................................................................ 3
Acquiring the Installer ............................................................................................................................... 3
vReporter Data Server Upgrade Preparation............................................................................................ 3
Backup configuration file to be reused after installation ..................................................................... 3
Uninstall the existing VRDS version ...................................................................................................... 3
vReporter Data Server Installation Steps .................................................................................................. 3
Kdb+ Script Deployment ........................................................................................................................... 5
Populating the Kdb+ instance with existing XDB data .............................................................................. 5
To Test Database....................................................................................................................................... 8
Advanced vReporter Data Server Configuration ...................................................................................... 8
vrDataServer Routine Scanning and Synchronization .............................................................................. 9
vrDataServer Monitoring .......................................................................................................................... 9
vrDataServer Backup................................................................................................................................. 9
vrDataServer Disaster Recovery ............................................................................................................. 10
Installing Kdb+ as a Monitored Service ................................................................................................... 10
Securing Kdb+ with user credentials....................................................................................................... 13
Pre-requisites
Requires a Kdb+ instance (If an existing Kdb+ instance does not exist for this installation, then
follow the steps outlined later in this document to install one).
Windows 2003 Server or later.
Microsoft .NET Framework 4.0.
Preferred deployment model has the vReporter Data Server being installed on the same server
as the vReporter application server it is intended to support.
Memory and CPU requirements for the vReporter Data Server are negligible. Consideration
needs to be placed on setup of the Kdb+ instance used by the vReporter data server. The Kdb+
database can be set up remote from the vReporter Data Server.

Acquiring the Installer

Installer versions can be found at the following location.

\\172.16.102.127\byldan\VOS\Platform\vrDataServer\vrDataServerSetup

vReporter Data Server Upgrade Preparation

If you are performing an upgrade, then perform these steps before continuing. Otherwise, proceed
directly to the vReporter Data Server Installation Steps below.

Backup configuration file to be reused after installation

Backup the following file found within the existing vrDataServer installation directory.

D:\Program Files\VistaOne Solutions\vrDataServer\vrDataServer.exe.config

Copy as vrDataServer_YYYYDDYY.exe.config

Uninstall the existing VRDS version

On App Server

Stop Service vReporter DataServer.

Add/Remove programs - vrDataServer

vReporter Data Server Installation Steps

1. Copy MSI installer locally to the server where it is to be installed.
2. Double-click the MSI installer icon to start the installation.
3. Click Next to advance past the Welcome screen.
4. Check off the box to Configure KDB and supply the proper values for each of the following
parameters. (For upgrades, you can leave blank and just copy back the vrDataServer.exe.config
from above step)

Example - Citi QA
IP Address = 172.16.26.86 (KDB Server)
Port = 2029
D:\intrabode\citihl\qa124\SECURE\CITI\DB\ROOT (File vrDataServer.exe.config Dataroot Path)

a. IP Address The address where the Kdb+ instance is installed

b. Port The network port that the Kdb+ instance is running on
c. Root Path The full path to the root of the vReporter XDB database
-full path: D:\intraBode\<app space>\<account> \SECURE\<client store>\DB\ROOT
- Client store is either the Client name or XCLIENT, this directory is different for
every client
5. Click Next
6. Provide the path where the vReporter Data Server should be installed. It is suggested to keep
the default. D:\Program Files\VistaOne Solutions
7. Click Next
8. Click the Install button to start the installation.
9. After the new service has been installed, Delete existing D:\Program Files\VistaOne
Solutions\vrDataServer\ vrDataServer.exe.config, and rename the one that was backed up
above before install from vrDataServer_YYYYDDYY.exe.config to vrDataServer.exe.config .
10. After the new service has been installed, start the service & verify it is running, from
the Services dialog (Start Button->Run and type services.msc). The service name is
vrDataServer. Again verify services is running in Task Manager (can verify vrdataServer\
Logs)
Kdb+ Script Deployment
In order for the vReporter Data Server to function, the related Kdb+ scripts must be set up.

To accomplish this:

1. In (App Server) D:\Program Files\VistaOne Solutions\vrDataServer\ Simply extract the contents

of EntitlementScripts.rar archive into the Kdb+ Q installation directory (e.g. D:\Program
Files\Vista One\QHostingSetup\q). Note: if Q is installed on a remote server then the RAR
archive may need to be copied onto that server first. The result of this extraction would replace
the existing q.bat script with the new one from the archive

This extract creates a Common folder & Script folder under D:\Program Files\VistaOne
Solutions\vrDataServer\. These 2 folders must be copied from the App Server to the KDB
Server D:\Program Files (x86)\Vista One\QHostingSetup\q\

2. Double-check that the filename of the .q file under the Common folder matches the
transaction logging set up in the q.bat script.
Sample q.bat
set arg1=%1
cd /d %arg1%
w32\q.exe Common/entitlementDB -l -p 2029

The highlighted section describes a relative path from the batch script where the transaction
logs and database checkpoint live, in this case D:\Program Files\Vista
One\QHostingSetup\q\Common. All files within that directory should have the prefix
described, in this case entitlementDB. If this is not the case then rename the .q file to have
the same prefix.

3. On the KDB Server - Kill the Q process from the task manager. This will cause the Q process to
be restarted and the newly installed scripts to be loaded in.

Populating the Kdb+ instance with existing XDB data

In order to upgrade existing vReporter environments to use the new vReporter Data Server service, the
Kdb+ instance must be populated with existing object, entitlement and constraint data.

To accomplish this:

1. On the App Server - Run the scanners.bat script in the Scanners directory found within the
vReporter Data Server installation directory. The script will require a single argument pointing it
to the path of the client store that represents the vReporter database.
Example: Run this from the CMD line This will run for a while depending on size of database.

Change to D-Drive, then cd to Progam Files\vistaOne Solutions\vrDataServer\Scanners

scanners.bat D:\intraBode\<App space>\<account>\SECURE\<client store>

scanners.bat D:\intraBode\citihl\qa124\SECURE\citi (Citi QA)

NOTE: -Client store is either the Client name or XCLIENT, this directory is different
for every client
2. On KDB Server - Modify the D:\Program Files (86)\Vista
One\QhostingSetup\q\Scripts\KdbScript.q script file that was recently extracted into the Q
installation directory as follows:
The line that reads:
;filePath:"E://kdb//Entitlement//received//7-16-2014//Data//"

Should be adjusted to match the location where the scanners were run or copied to, for
example:
;filePath:"D://Program Files//VistaOne Solutions//vrDataServer//Scanners//"
--You may need to create this directory on the server--

Actual steps needed to complete step 2 is below Copying results to the KDB Server)
Copy the 7 scanners.bat output files
ConstraintOutputfileStatus0detail
ConstraintOutputfileStatus0Main
ConstraintOutputfileStatus1detail
ConstraintOutputfileStatus1Main
Entitle.csv
Objects.csv
RoleuserGroup.csv

From: App Server D:\ D:\Program Files\VistaOne Solutions\vrDataServer\Scanners\

To: KDB server - D:\Program Files (x86)\vrDataServer output\
 1. On KDB Server - Modify the D:\Program Files (86)\Vista
One\QhostingSetup\q\Scripts\KdbScript.q script file that was recently extracted into the Q
installation directory as follows:

The line that reads:

;filePath:"E://kdb//Entitlement//received//7-16-2014//Data//"

or

;filePath:"E://kdb//Entitlement//received//08-21-2014//Data//"

Change to:

;filePath:D://Program Files (x86)//vrDataServer output//

Or

;filePath:D://Program Files (x86)//VistaOne Solutions//vrDataServer//Scanners//

NOTE: On New install - when moving the scanners.bat output files to the stand alone KDB server create
a directory in program files (x86).

2. On KDB Server - Load the data into Kdb+ using the qcon Q client.

NOTE: The 1 is actually a lower case L l Run From Administrator: Command Prompt.
Change to D-Drive, then cd to Progam Files (x86)\Vista One\QHostingSetup\q\w32

(Note There is a \ at start of command, then lower case L)

D:\Program Files\Vista One\QHostingSetup\q\w32>qcon localhost:2029

localhost:2029>\l Scripts\LoadData.q
localhost:2029>\l
To Test Database
On App Server Put http:\\KDB Server Name.coreone.com:2029

Can view database here.

Advanced vReporter Data Server Configuration

If the vReporter instance using the vReporter Data Server is remote, then add an entry to the
allowedIPAddresses in the vrDataServer.exe.config file found in the root directory of the vReporter Data
Server installation directory.

The configured set of connections must be limited to the minimum list of application components that
are required to connect (aka the whitelist). In a typical Enterprise vReporter deployment this would
consist of only the APPLICATIONSERVER and the REFRESHSERVER

-App server connects as locahhost - <ipAddress key="localhost" address="127.0.0.0/8"/>

-Refresh server IP will need to be added <ipAddress key="refresh" address="172.16.xx.xx/32"/>

Example:

<vrDataServerSection xmlns="urn:VRDataServer.Configuration">

<maxMessageSize value="16384"/>

<kdbServer ipAddress="127.0.0.1" port="2029" bufferSize="1000000" />

<allowedIPAddresses>
<ipAddress key="localhost" address="127.0.0.0/8"/>
<ipAddress key="refresh" address="172.16.xx.xx/32"/>
</allowedIPAddresses>

<dataRoot path="D:\intraBode\<App space>\<account>\SECURE\<client

store>\DB\ROOT"/>
</vrDataServerSection>
Edit ibmonitor.ini on App & Refresh server to complete vReporter Data Server
setup
NOTE: App & Refresh communicate with vrDataServer on port 9196, not to be confused with
port used for KDB communication with vReportedDataServer

App Setting:
[VRDS]
IP=127.0.0.1
PORT=9169
USER=
PASSWORD=
Ref Setting:
[VRDS]
IP=172.16.xx.xx
PORT=9169
USER=
PASSWORD=

vrDataServer Routine Scanning and Synchronization

For UAT and production environments, a scheduled task should be set up to run each of the
vrDataServer routine scanners twice a day (e.g. 12AM and 12PM). This should be set up only once on
the server hosting the vrDataServer (normally this is the application server).

This can be set up using Windows task scheduling. The scanners should be executed from the
vrDataServer scanner directory as the working directory.

Command-lines for executing the entitlement and object scanners respectively:

> Entitlement.RoutineScanner.exe /ScannerType:2 /StorePath:<Path to the vReporter client store>

> Entitlement.RoutineScanner.exe /ScannerType:3 /StorePath:<Path to the vReporter client store>

If any differences are detected by the routine scanners, a .vql script will be generated in the scanner
folder. If this is the case, then the deployed tcpClient.exe client utility (installed to the vrDataServer root
folder) may be used to execute the .vql script, thus synchronizing the Kdb database appropriately.

Example:
> tcpClient.exe /ipAddress:127.0.0.1 /port:9169 /result+ /file: Entitle_Delete-10-22--2014-13-
38.vql

vrDataServer Monitoring
For UAT and production environments, there should be an Uptime service monitor set up to verify that
the vrDataServer service and the QHosting service are both running.

An additional monitor should be set up to watch for any .vql scripts generated in the vrDataServer
scanner folder.

vrDataServer Backup
For UAT and production environments, a scheduled task should be set up to back-up the transaction
logging directory to reliable storage once a day at midnight. The backups should be retained for a
minimum of 10 days.
Transaction logging directory can be identified by inspecting the q.bat script in the QHostingSetup
installation performed as part of the setup of vrDataServer. By default, found in D:\Program Files\Vista
One\QHostingSetup\q.

Sample q.bat
set arg1=%1
cd /d %arg1%
w32\q.exe Common/entitlementDB -l -p 2029

The highlighted section describes a relative path from the batch script where the transaction logs and
database checkpoint live, in this case D:\Program Files\Vista One\QHostingSetup\q\Common. That is
the directory that should be backed up and would, in this case, include files with the entitlementDB
prefix.

vrDataServer Disaster Recovery

To recreate the Kdb database in the case of disaster, perform the following steps:

Shut down the Q (Kdb) service and process.

Locate the most recent and healthy backup transaction log files and copy them into the
transaction logging directory. Identify this location as described in the previous section.
To replay data modifications that had occurred since the time of the backup, copy all VQL
statements from the vrDataServer audit logs into a .vql file. This can be achieved by opening the
audit files in Excel and copying the cells from the VQL column.
Run the .vql script using the tcpClient.

> tcpClient.exe /ipAddress:127.0.0.1 /port:9169 /result+ /file:<vql file>

Installing Kdb+ as a Monitored Service

1. Acquire the QHostingSetup installer from the build repository. Be careful to retrieve the
required version.< v3.0 is the free fully functional version 2GB mem limit>

\\172.16.102.127\byldan\VOS\Platform\Experimental\QHostingSetup
2. Copy the QHostingSetup MSI installer locally to the appropriate transfer folder on the chosen
server for installation.
3. Log onto the chosen installation server as an Administrator in order to execute the installer.
4. Right click the MSI and select to Run without restrictions.
5. When prompted by the installer, change the target installation folder to the D: drive (within
Program Files) and select to install for all users as depicted below.
6. Verify that the installation was performed correctly by navigating with Windows Explorer to the
q folder within the new installation folder.

7. Open the Service Manager and search for QHostingService. It will be in started mode.

8. Also q.exe in Task Manager should be running.

 9. Manual Steps for adding license file to the Q (if applicable)
a. Stop QHostingService from Service Manager (Start->Programs->Administrative Tools-
>Services).
b. End q.exe from Task Manager.
c. Copy K4.lic where q is installed. i.e. D:\Program Files\Vista One\QHostingSetup\q in
above case. (not necessary w/ v3.0)
d. Restart QHostingService from Service Manager (Start->Programs->Administrative Tools-
>Services).
e. After the service is restarted, verify that it is running by launching the task manager and
locating the q process.

10. Q installation is complete.

Securing Kdb+ with user credentials

To secure Kdb+ with a username and password:

1. Use the PasswordEncrypt tool deployed with vrDataServer (located within the installation root
directory) to generate a hashed and encrypted version of the desired password.

Sample Usage:
> PasswordEncrypt.exe

Enter password to be encrypted: ******

The hashed password is (Kdb userfile) : A029D0DF84EB5549C641E04A9EF389E5

The encrypted password is (vrDataServer config) : TktqPxqGINA=

 2. Take the hashed password and add that to a text file (recommended name is userFile.txt) as
follows:
myusername:A029D0DF84EB5549C641E04A9EF389E5

3. To start Kdb+ with the new user credential in affect, update the q.bat script in the Q folder
(D:\Program Files\Vista One\QHostingSetup\q) to include the U option. The text file created
previously should be placed in this same location.

Example:

Sample q.bat
set arg1=%1
cd /d %arg1%
w32\q.exe Common/entitlementDB -l -p 2029 U userFile.txt

4. Take the encrypted password and add it to the vrDataServer configuration file as follows:

<vrDataServerSection xmlns="urn:VRDataServer.Configuration">

<maxMessageSize value="16384"/>

<kdbServer ipAddress="127.0.0.1" port="2029" userName="myusername"

password="TktqPxqGINA=" bufferSize="1000000"/>
..