Section II: Server Installation

Note: This is only for Windows 2016 Server, Windows 2012 Server, Windows 2008 Server, Windows 7 64-bit Professional Windows 8 & 8.1 64-bit Professional and Windows 10 64-bit Professional.

The installation of the Revelation Universal Driver NUL 5.2 is straightforward and consists of only a few steps. The setup program will search for a previous installation of the 5.x release and attempt to reinstall or upgrade it. If no existing installation is detected the setup program will work as a new installation. Steps to complete the setup are:

Performing the Server Side Installation

Creating the Server Side Installation

With the Windows Installation you have the choice of using either Named Pipes, TCP/IP, or a combination of the two. The default, and recommended, installation is TCP/IP. If you wish to use a different configuration, refer to “Changing How the Service Connects” later in this section.

The Revelation Universal Driver NUL 5.2 can coexist on the same server with the Universal Driver 4.7 or Universal Driver NUL 4.7 / 5.1.

1. Unzip the compressed file.

2. Run the appropriate "setup" program:

• Right click on UD52Setup.exe and choose Run as administrator.

3. Read the information presented on the Welcome screen, choose “Next”, and click “Yes” to accept the terms of the software license agreement.

If the installation program detects a previous version of the Linear Hash 5.x service you will be prompted to upgrade. Please refer to the “Upgrade Installation – Server Side” section.

4. Enter the authorization code provided by Revelation Software or your vendor. The authorization code must be valid, or you will not be able to progress past this point. When you have finished, click “Next”.

5. You are informed that the Revelation Universal Driver NUL 5.2 will be installed into the \REVSOFT\UNIVERSAL DRIVER 5.2 directory. If you would prefer a different destination directory, you can make the change at this screen. Confirm your choice by clicking “Next”.

6. The next screen asks you for the location of your existing OpenInsight application. This is because the setup will install a REVPARAM file in the specified location with the necessary settings to run OpenInsight (any existing REVPARAM file will be backed up). Once you enter the path to your application, click “Next”.

7. The Universal Driver will interact with the Management Console. The Management Console relies upon the Engine Server to operate. You must specify the Engine Server URL and Engine Server web server port number.

8. You are asked if you wish the Service to run using TcpIp. If you click “Tcp/IP”, you will be asked for a port to use on the next screen. If you choose Named Pipe, you will be asked for the named pipe name on the next page. Choose the connection type, and click “Next.”

9. This screen asks you for the connection details required by the Universal Driver.

If you previously selected TCP/IP for the connection information, you must now specify the TCP/IP Port to use for the Universal Driver. If you wish to use another port aside from the default, enter it on the screen. NOTE: If any connections from OpenInsight workstations come from outside any firewalls you have established, you will need to allow this TCP/IP port to pass through those firewalls.

If you previously chose not to run Tcp/Ip, you are asked for a Named Pipe to use. You can choose the default, or enter your own name for the Named Pipe.

If “No security/encryption required” is selected, then communications between the Universal Driver and workstations will be sent without any additional encryption. This is the “legacy” behavior, identical to the way the prior Universal Drivers operated.

If “Encrypt client/server communications” is selected, then each communication session between the Universal Driver and all workstations will be uniquely encrypted.

If “Encrypt and validate client/server communications” is selected, then the communications are encrypted and the clients have to be “registered” with the Universal Driver for communications to proceed.

If “Allow clients to reconnect” is checked, the workstations will attempt to reconnect with the Universal Driver if their session is interrupted do to network issues. NOTE: reconnection will only succeed if the cause of the interruption is network related; if either the Universal Driver or the workstation has shut down, then the existing session cannot be restored. Also note that, if reconnect is allowed, it is strongly suggested that either the “Encrypt” or “Encrypt and validate” secure option is selected to prevent “spoofing” during a reconnect attempt.

You must also enter the Host name or IP Address of the Server you are installing the Universal Driver on, and then click “Next”.

10. At this point please select the Program Group you want the Linear Hash 5.2 Manager listed under.

11. Click the Install button to start the installation process.

12. The last screen allows you to automatically view the README document and to start the Linear Hash 5.2 service, via checkboxes. It is strongly recommended that you leave both boxes checked. Click “Next” to complete the installation.

1. Unzip the compressed file.

2. Run the appropriate "setup" program:

• Right click on UD52Setup.exe and choose Run as administrator.

3. Read the information presented on the Welcome screen, choose “Next”, and click “Yes” to accept the terms of the software license agreement.

If the installation program detects a previous version of the Linear Hash 5.2 service you will be prompted to upgrade. If you are performing an upgrade the installer will locate the previous installation in the registry and prompt you to upgrade. During installation any previous versions will be deactivated and replaced with the new Universal Driver.

4. The Installer will automatically detect your previous installed version of the Universal Driver 5.2. Click the “Yes” button if you want to reinstall or upgrade your version of the Universal Driver.

5. Enter the authorization code provided by Revelation Software or your vendor. The authorization code must be valid, or you will not be able to progress past this point. When you have finished, click “Next”.

6. You are informed that the Revelation Universal Driver will be installed into the \REVSOFT\UNIVERSAL DRIVER 5.2 directory. If you would prefer a different destination directory, you can make the change at this screen. Confirm your choice by clicking “Next”.

If the installation process cannot find the valid Universal Driver directory from a prior install an error will be reported. Cancel the installation process and remove your prior Universal Driver registry settings. The registry settings will be in a folder located under one of the following locations depending on the server edition:

64bit server: HKEY_LOCAL_MACHINE\SOFTWARE\RevSoft

Remove any folders named “Revelation Universal Driver” sub folder “5.2”. Restart the installation to continue.

7. The next screen asks you for the location of your existing OpenInsight application. This is because the setup will install a Revparam file in the specified location with the necessary settings to run OpenInsight. Once you enter the path to your application, click “Next”.

8. The Universal Driver will interact with the Management Console. The Management Console relies upon the Engine Server to operate. You must specify the Engine Server URL and Engine Server web server port number.

9. You are asked if you wish the Service to run using TcpIp. If you click “Tcp/IP”, you will be asked for a port to use on the next screen. If you choose Named Pipe, you will be asked for the named pipe name on the next page. Choose the connection type, and click “Next.”

10. This screen asks you for the connection details required by the Universal Driver.

If you previously selected TCP/IP for the connection information, you must now specify the TCP/IP Port to use for the Universal Driver. If you wish to use another port aside from the default, enter it on the screen. NOTE: If any connections from OpenInsight workstations come from outside any firewalls you have established, you will need to allow this TCP/IP port to pass through those firewalls.

If you previously chose not to run Tcp/Ip, you are asked for a Named Pipe to use. You can choose the default, or enter your own name for the Named Pipe.

If “No security/encryption required” is selected, then communications between the Universal Driver and workstations will be sent without any additional encryption. This is the “legacy” behavior, identical to the way the prior Universal Drivers operated.

If “Encrypt client/server communications” is selected, then each communication session between the Universal Driver and all workstations will be uniquely encrypted.

If “Encrypt and validate client/server communications” is selected, then the communications are encrypted and the clients have to be “registered” with the Universal Driver for communications to proceed.

If “Allow clients to reconnect” is checked, the workstations will attempt to reconnect with the Universal Driver if their session is interrupted do to network issues. NOTE: reconnection will only succeed if the cause of the interruption is network related; if either the Universal Driver or the workstation has shut down, then the existing session cannot be restored. Also note that, if reconnect is allowed, it is strongly suggested that either the “Encrypt” or “Encrypt and validate” secure option is selected to prevent “spoofing” during a reconnect attempt.

You must also enter the Host name or IP Address of the Server you are installing the Universal Driver on, and then click “Next”.

11. At this point please select the Program Group you want the Linear Hash 5.2 Manager listed under.

12. Click the Install button to start the installation process.

13. The last screen allows you to automatically view the README document and to start the Linear Hash 5.2 service, via checkboxes. It is strongly recommended that you leave both boxes checked. Click “Next” to complete the installation.

In addition to the steps above, you need to ensure that the Universal Driver’s LinearHash service will have appropriate access to your files. By default, the LinearHash service logs into your server as the “System” user/group. This is a predefined user/group on the server. It is important that the System user/group be granted “Full” access to the shared data in the “Permissions” window (located in the “Security” tab of a shared drive’s properties). Furthermore, you should configure the security settings of the shared volume to both “Replace Permissions on Subdirectories” and “Replace Permissions on Existing Files”. For instructions on how to do this, consult your Microsoft Windows 2016/2012/2008 documentation.

After completing the installation procedure, you should verify that the software has been installed properly and is functioning. There are two ways to accomplish this, either through the services dialog or the command line.

There are a number of ways to check the services running on your server, depending on the operating system. Please consult your Windows documentation for details. You can access the services list by right clicking “Computer” and choosing “Manage”. Navigate to “Configuration → Services” and locate “Linear Hash v5.2” in the list of services names. This service is what the Revelation Universal Driver registers itself to the operating system as. The status should read “Started”. You can try stopping, starting, and restarting the service with the start and stop buttons on the top button bar.

Your dialog should look similar to this:

The Universal Driver’s LinearHash service status can also be checked using the command line. The command line is less intuitive, but quicker for those who are more comfortable with text interfaces. If you are not one of these people, use the Services dialog to verify the installation—it’s equally valid. The command line steps follow below:

1. Change to the \REVSOFT\UNIVERSAL DRIVER 5.2 directory

(assuming you accepted the defaults; use the directory name you installed to)

2. Type RevLHSrvc status

The service should respond with the message “Running”. If you have stopped the service yourself, it should read “Created”. For a description of the other command line parameters for the RevLHSrvc executable, see “Using the Universal Driver” later in this section.

The REVPARAM file (with no extension) is a file that is automatically created in the directory where your Revelation application executable resides. It will allow certain behaviors of the client driver to be customized. This file is a text file that can be created in any text editor, such as the Notepad program in Windows (NotePad.EXE).

The REVPARAM file consists of a series of parameters followed by an equal sign and a value. Below are the contents of a sample REVPARAM file for a Windows network:

ServerOnly=1

ServerName=win10test4.winwinsol.int

TcpIpPort=1777

Secure=0

Although there are several configuration settings available to be used in the REVPARAM file, not all of them need to be explicitly present in the file itself. For any variable that you do not put in the REVPARAM file, it uses system defaults. This means that you only need to enter the configuration settings that you wish to change.

If you have multiple Revelation Software applications installed on your server, you will need to create a REVPARAM file for each application.

This REVPARAM file flag controls access to your data. If the ServerOnly flag is set to 0, then any user with OpenInsight can read information from your data directories, whether or not they have been configured to use the Revelation Universal Driver. Although having this flag set to the value of 0 will allow every user to use your data, it is a recommended security precaution that you change this flag to 1. This ensures that all user requests are making use of the LinearHash service – which is the purpose of the Universal Driver.

If the ServerOnly flag is set to 1, then all copies of OpenInsight will refuse to read the files in your data directories, unless they can communicate with the LinearHash service on the server. This means that the individual client machines will not attempt to manipulate the data themselves, and will instead perform all their data I/O via requests to the server.

This REVPARAM file flag controls the type of communication between the server and the client. If Secure=0 then the client/server communications channel will operate as it always has in a non-encrypted format.

If Secure=1 then all communications between the client (OpenInsight) and the server (the Universal Driver, named “RevLHSrvc”) will be encrypted and will thus be protected from “eavesdropping” on the communication line.

For additional protection, setting Secure=2 into the REVPARAM and setting “Secure” to “2” in the Universal Driver registry will cause RevRCL to operate in “authorized” security mode. In addition to encrypting all communication between the client and the server, each client must be “authorized” to communicate with the server before any access is granted.

Please note that, in all cases, the “Secure” value in the REVPARAM must match the value that is specified in the registry, otherwise the attempted communication will fail.

Authorized security is ensured by the use of public key encryption. The server maintains a list of the “public keys” for the clients that are authorized; the client workstations maintain their own “private keys”. The OpenInsight client maintains (on Windows platforms) the private key information, in encrypted format, in the registry on the client’s workstation; the public keys are stored in the Universal Driver directory, also in encrypted format. Note that it is the IT administrator’s responsibility to set permissions properly on the Universal Driver directory so that unauthorized users cannot put their own keys into the public key directory.

RevRCL includes a command line tool, RevGenerateKey, to allow for the key creation. For each client workstation that will run OpenInsight in “authorized” mode, the IT administrator or other authorized user must configure the workstation by opening up a DOS cmd prompt and typing in the following command:

RevGenerateKey –write <outputlocation>

Where <outputlocation> is the full path and file name of the “public key certificate” that should be created (note that the file name MUST end with “.cert”).

For example:

RevGenerateKey –write z:\shareddir\wkstation1.cert

This will create the private key (in the workstations’ registry), and the public key in z:\shareddir\wkstation1.cert. It will also create a companion file, z:\shareddir\wkstation1.name, containing the current workstation name and unique ID. In this example, the “z:\” directory is mapped to some folder that is accessible to both the workstation, and the Universal Driver server.

By default, the “workstation name” will be generated via the Windows API, and will be in the format “machinename\username”. However, if desired, the workstation name can be manually specified with the “-u” option of RevGenerateKey:

RevGenerateKey –write z:\shareddir\wkstation1.cert –u Workstation_1_By_Coffee_Machine

The user name can be used by the IT administrator to identify the public key, but is otherwise unused.

Since “authorized” mode uses per-user encryption on Windows to protect the private key, services (such as the OEngineServer service) that you wish to configure for this enhanced security must be run with the credentials of a Windows user (rather than as the “system service” user). A new Windows user can be created, or an existing Windows user can be used. In either case, log in as the desired Windows user and run “RevGenerateKey –write” to generate the appropriate private keys, and then be sure to set the “service logon user” information (in the Window’s Services control panel) to this user.

Once the public key has been generated, the IT administrator or other authorized user must “import” the public key into the Universal Driver. This is done from a DOS cmd prompt, running as an administrator, in the Universal Driver directory itself (note that this MUST be run from inside the Universal Driver directory, otherwise these additional options are not available). To import a generated certificate, run RevKeyMgr with the “-import” or “-add” switch:

RevKeyMgr –import z:\shareddir\wkstation1.cert

If the RevKeyMgr detects that the unique ID is already in the “clients” table, a message will be displayed asking if you wish to overwrite the current information. If the RevKeyMgr detects that this user already has an entry in the “clients” table, with a different unique ID, a message will be displayed asking if you wish to add this additional information.

Once the certificate information has been imported, the client can now communicate with the server. If the same client would like to communicate with additional authorized servers, the same generated certificate should be imported into the additional server’s “clients” table with RevKeyMgr –import, run in that server’s Universal Driver directory. Note that you cannot just take the entry from on “clients” subdirectory and put it on another server; the files in the “clients” subdirectory are encrypted on a per-machine basis.

After all servers have been configured, if desired, the client’s generated output files (both .cert and .name) can be deleted, or preserved elsewhere. This set of operations – “RevGenerateKey –write” and “RevKeyMgr –import” – needs to be performed for each authorized user.

RevKeyMgr provides some additional utility functions. A list of all the authorized clients can be displayed via the “-list” option:

RevKeyMgr –list

A user can be removed from the list of authorized clients by using the “-del” option:

RevKeyMgr –del <clientNameOrID>

Either a client name, or the unique ID (displayed via –list) can be used to specify the client entry to delete. Note again that both –list and –del are only available when RevKeyMgr is run in the Universal Driver directory.

The Universal Driver allows you to specify the set of files that your OpenInsight installation works with. This is done by creating a “share name” that points to the physical directory the Universal Driver should manage. You may think of this as a “virtual directory” or “shortcut” name to the physical directory. A common use of this is to hide data files in directories where users cannot access or modify them from outside OpenInsight. This allows sites with sensitive data to add an extra layer of security. In addition, the Universal Driver’s VSS (the Volume Shadow Service, used to create “Shadow Volumes” for backup routines) will only process the directories specified as shares.

Note: Different software packages utilize the functionality of VSS-aware applications (such as the Universal Driver 5.2) in different ways; therefore, you may or may not be able to take explicit advantage of the Universal Driver VSS capabilities. Please consult your backup (or other VSS Requester) software for more details.

At its simplest, you can create an entry in the Shares section of the Universal Driver registry containing a “share name” that can apply to your overall data directory – for example, you might create a share named “OI”, and set its value to “C:\Revsoft\OInsight10”.

Your REVPARAM in the C:\Revsoft\OInsight10 directory will have the following contents:

ServerOnly=1

ServerName=win10test4.winwinsol.int

TcpIpPort=1777

Secure=0

ShareName=OI

In this fashion, the client workstations would not need to know where the data resides, while the Volume Shadow Copy (VSS) would know what directory to back up.

Note: You must stop and start the Linear Hash v5.2 service for VSS to take effect.

It is possible to create multiple shares for multiple directory structures. For example, if you have subdirectories named North_Region and South_Region that need to be isolated from users, you can relocate those directories to a location that is inaccessible to end users and use a share name that makes it accessible to the OpenInsight application. In this example the folder name will be called Data. The Universal Driver will have full rights to access this folder whereas end users will have no rights .LK and .OV files in this folder.

In the Universal Driver registry we will create a String value under Shares called “Data”, with the value: “J:\Data”.

This new share instructs the Universal Driver to access the private location (J:\Data), when the client utilizes the public Share name (Data). A REVPARAM must be placed in a folder accessible to the client. In this example the REVPARAM is placed in the “J:\Data” folder. We provide users with Read access to that REVPARAM file only not the folders called North_Region and South_Region.

Our REVPARAM will contain the following:

ServerOnly=1

ServerName=win10test4.winwinsol.int

TcpIpPort=1777

Secure=0

ShareName=Data

In our OpenInsight application we will attach “J:\Data\North_Region” and “J:\Data\South_Region”. OpenInsight will locate the REVPARAM in the “J:\Data” folder and pass the Share name to the Universal Driver. The Universal Driver will know to look for the North_Region and South_Region folders under the “J:\Data” folder.

Note: The REVPARAM need not be located in the “J:\Data” folder for the application to use the “J:\Data” folder. For example, the REVPARAM can be located in “K:\Data”. The OpenInsight application will attach “K:\Data\North_Region” and “K:\Data\South_Region”. OpenInsight will locate the REVPARAM in the “K:\Data” folder and pass the Share name to the Universal Driver. The Universal Driver will know to look for the North_Region and South_Region folders under the “J:\Data” folder.

Please take a moment to make sure that you have installed the Universal Driver correctly. Here is a brief summary of the installation steps used to install the Revelation Universal Driver on the server.

OpenInsight

• Install the Server Side of the Service
• Create the SYSTEM user/group
• Verify Proper Service Installation

The Revelation Universal Driver is a Windows 2016, Windows 2012 and Windows 2008 operating system service that was designed to reduce network traffic and increase application speed by processing Linear Hash file activity on the server. This eliminates the bottleneck caused by multiple computers simultaneously requesting data from individual Linear Hash files. The result of transferring this task from the client to the server is an increase in application speed and data integrity, as well as a reduction in network traffic.

The Revelation Universal Driver by default, communicates via TCP/IP but can be configured to use Named Pipes, a high level application programming interface (API) used for passing data between two processes, regardless of whether the processes are local or remote. The underlying network transport used in establishing a connection between client and server can be any protocol that is common between the two. The client uses the highest priority transport that both the client and server support.

The default communication is via TCP/IP. When establishing the TCP/IP connection, you can choose the specific port number you wish to use, or allow the Service to allocate a port itself. How to configure these settings will be covered further in “Changing How the Service Connects” later in this chapter. Before you change from the default settings, please be sure to consult the compatibility table that is located in this Linear Hash Manager.

Ideally, the Revelation Universal Driver should be installed on every file server containing OpenInsight linear hash files in order to provide maximum performance benefits. In situations where application files are stored on a different server from the data, and only one Universal Driver is available, it is necessary that the Universal Driver be installed on the file server on which the data resides.

Revelation Software recommends the use of TCP/IP (socket) connections rather than named pipe connections in most circumstances. Only Universal Drivers with entirely local clients (all on the same machine as the Universal Driver) should use named pipe connections.

By default, the Universal Driver installs in TcpIp mode, but you can change to Named Pipes, or a combination of Named Pipes and TcpIp if you are so inclined. TcpIp is the recommended connection method.

The next sections discuss making changes to the registry. These instructions are written for 64bit versions of Windows.

On a 64-bit server the root registry path is: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Revsoft\Revelation Universal Driver\5.2

To run Named Pipes Only:

In this configuration, you only need to specify the Named Pipe you will use. We will use REVLHSRVC as an example.

Start → Run → REGEDIT

A screen shot of the Registry Settings for the Universal Driver using TcpIp

HKEY_LOCAL_MACHINE → SOFTWARE → REVSOFT → REVELATION UNIVERSAL DRIVER → 5.2

You will need to add the following line to your REVPARAM:

NamedPipeName=REVLHSRVC

If there is a line mentioning a TcpIpPort, you will need to change the value to None.

By default, the Universal Driver uses the following flags when calling the Windows API to access OpenInsight’s LK/OV files:

FILE_ATTRIBUTE_NORMAL FILE_FLAG_RANDOM_ACCESS FILE_FLAG_OVERLAPPED

which evaluates to 0x50000080. This is the optimal setting for most scenarios. However, certain sites may wish to modify the flags to better suit their individual situations. This can be controlled via the registry.

The next sections discuss making changes to the registry. These instructions are written for 64bit versions of Windows.

On a 64-bit server the root registry path is: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Revsoft\Revelation Universal Driver\5.2

Open up the registry editor:

Start → Run → REGEDIT

Navigate to the UD 5 registry:

HKEY_LOCAL_MACHINE → SOFTWARE → REVSOFT → REVELATION UNIVERSAL DRIVER → 5.2

Create a new DWORD registry value, with the key name CreateFileFlags, if it does not already exist. Set its value to the desired create/open flags, as described by Microsoft here:

https://msdn.microsoft.com/en-us/library/windows/desktop/aa363858%28v=vs.85%29.aspx

From the Universal Driver 5.2 Program Group choose "Uninstall"

The following files are installed when you install the Revelation Universal Driver 5.2. The default install directory for all the files listed below is the \REVSOFT\UNIVERSAL DRIVER 5.2 directory.

RevLHSrvc.EXE, the file used to control the Revelation Universal Driver, can accept parameters when used from the command line. The format for using these parameters is as follows:

RevLHSrvc.EXE <parameter>

These parameters are described in the following table.

For debugging purposes, you can create the RevLHSrvc.log file in the subdirectory where the RevLHSrvc.exe is located. This will log all the calls to the Universal Driver with no noticeable speed penalty. After you create the RevLHSrvc.LOG file, you will need to stop and restart the RevLHSrvc.EXE.

The REVPARAM file controls whether or not OpenInsight uses the Service to coordinate locking. The contents of this file should be created with an ASCII editor. Each line of the file contains the following format:

<parameter> = <value>

Depending on the parameter the value will be on of the following:

Boolean: 1 or 0; True or False; Yes or No

Unsigned decimal integer: Any number between 1 and approximately 4 million

Hexadecimal value: 0x followed by a hexadecimal number

The following table describes available parameters and their default values. Keep in mind that these drivers are client-side settings, and the Universal Driver overrides many of them when the Linear Hash service is running. Normally there is no reason to change the values that are installed with the Linear Hash Service.

The following files are used by OpenInsight 10 and are included with your system.

OpenInsightRevLH.DLL RevLHClient.DLL RevRCL.DLL REVERROR.DAT