Universal Driver and REVPARAM: Best Practices (Deployment,General,Network Compatibility) [Revelation On-Line Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Universal Driver and REVPARAM: Best Practices (Deployment,General,Network Compatibility) ======

==== Created at 26 OCT 2020 10:51AM ====


=== Overview ===

This article describes the communication between the Universal driver (UD) client and server, and the function and best practice usage of revparam file. The article assumes the reader is using Revelation Technologies Universal Driver version 4.7.2 or 5.x and is familiar with these products and their terminology.

 

=== The Universal Driver ===

The Universal Driver employs client and server components to implement the Linear Hash filing system in a manner which scales to multiple users and supports consistent data access, updates, and backups.  

{{kb1089_1.jpg}} 

Figure 1. Communication Flow

When a running instance of OpenInsight accesses linear hash data it calls the program RTP57. RTP57 calls the Universal Driver client, LH.DLL (in OpenInsight prior to OpenInsight 10) or REVLH.DLL (in OpenInsight 10.x).  The Universal Driver client (often referred to as the "LH client") will always try to contact the UD server.  The LH client reads the revparam file to learn the preferred method. If the revparam does not provide instructions the LH client will attempt to connect by named pipe. If the client can contact the server which owns the linear hash files (revXXX.LK and .OV) then it forwards the request to the server.  If the LH client cannot find the owning server, it will access the files directly unless forbidden by a revparam ServerOnly=1 setting.  In the diagram above the yellow lines indicate operating system (OS) file operations by the client, the green lines depict direct communication between the components.

Note that it is the client which reads the revparam, not the server. Also note that if the client succeeds in connecting to the server then the client never directly accesses the linear hash ( .LK and .OV ) files.   Conversely, the service never accesses the revparam.  Thus, the revparam must be located where the client can see it, but need not be accessible to the service, and the .LK and .OV files must lie where the service can see them, but can be invisible to the client.  (This behavior is the basis for the ShareName functionality, discussed below).

OS file operations occur in the security context of the user.  The operating system will confirm the user has access rights to each file. In a complex network the security checks for a pc to read from a server are expensive.  The UD service performs OS file operations, so it too is subject to the cost of access control (ACL) validation. Set the "SYSTEM" user as the file owner for all .LK and .OV files on the server to minimize this overhead.

As stated, the LH client will always try to contact the server - therefore, the LH client will always search for a revparam.  When you attach a folder, OpenInsight sends the path to the LH client.  The client will look for a revparam in that folder. If not found it will look in the path's parent folder, then the parent of that folder, up to the root of the share or drive.  That single revparam is an umbrella for all the subfolders. In the UD 4.7, this search happens for many operations. Thus, in the 4.7, while the OI will function with a revparam in the root, the same revparam may be put in every folder for performance reasons. The UD 5 series resolves the revparam for a path once, then caches the result. So, for the UD5 there is not a big performance consideration when using a single revparam for all subfolders. For either service, you should always have at least one revparam so the client can stop searching.

 

== Revparam "ServerOnly" Setting ==

The primary directive in the revparam file is ServerOnly.  The ServerOnly directive specifies whether the server mode is required or optional. The LH client will always try to connect to the UD server; if it cannot connect, then if ServerOnly = 0 the LH client will "downgrade" to local mode.  If ServerOnly=1 then the LH client will abort the operation.   The UDs prior to UD 5 default to ServerOnly =0, while the UD 5 defaults to ServerOnly=1, if no ServerOnly setting is found. This means that an Openinsight using the UD 5 will not be able to access files in a directory tree which lacks a revparam. This enforces the "best practice" of requiring a UD server for shared files.

 

=== Revparam: Search Examples ===

== Single Server, Single Tree ==

{{kb1089_2.jpg}}

This is the most common OpenInsight installation.  The application and data are all on one server running the Universal Driver, with the data stored in subdirectories under the OpenI__n__sight folder. In the above figure, this would correspond to a site with only the OIProd and SameTreeData folders. In this case, a single revparam in the OIProd folder is sufficient.  Note that the UD 4.x mayget some performance gain with a copy of that same revparam in each subfolder.

== Single Server, Multi Tree ==

{{kb1089_3.jpg}}

If your application has data in folders which are not subfolders of the __O__penInsight folder, as shown for example by the ExternalData folder above, then that folder needs a revparam. A single revparam in the ExternalData folder is sufficient to cover any subfolders under ExternalData.   UD4.x will get some performance gain if you copy that same revparam into each subfolder.  ExternalData can be a different folder on the same drive, or on other drives owned by the same server.  In fact, in the example above the revparam could be placed in the Parent folder to make it the default for both ExternalData and Revsoft folders.

 

=== Local files ===

Revelation recommends using a revparam with ServerOnly=0 in folders on local machines where the universal driver is not installed.  The UD 4.7 will search for a revparam, then default to ServerOnly=0.  The UD 5.x will search for a revparam, then default to ServerOnly=1, then fail to attach the volume.

== Revparam: Implication for Locking ==

The linear hash filing system implements logical record locking by placing operating system share locks on a table named revlocks in the folder containing the LH files.  If the UD server is controlling a folder then it will place the share locks in the context of the UD service user.  If the LH client is accessing files in local mode then it will place share locks in the context of the user who placed the lock. Failing to prevent local mode access can lead to a situation where one user in local mode takes control of the REVLOCKS file, preventing the UD and thus all other users from accessing any files in the same folder.  UDs prior to UD 5, by defaulting to Local mode, made it easy to stumble into this situation if a revparam was renamed, deleted, or rendered inaccessible by access rights.  The UD 5, by requiring a revparam in all cases, forces you to explicitly choose local mode if that is truly what is intended. 

== UD Manager ==



The UD manager is a copy of OpenInsight which ships with the Universal Driver.  It sits in a folder under the Universal Driver folder. The UD Manager shows which users are holding file locks. It too needs a revparam with the correct settings to contact the UD server.  Usually the installer for the Universal Driver places a revparam in the Universal Driver folder.  Since the UD Manager folder is under the installed UD folder, the revparam in the UD folder is sufficient.  If you move the UD_Manager folder to a location which is not below the UD service the revparam file must be copied to that new location.



 

== Revparam: ShareNames ==

The ShareName directive supplies an alias for a physical path.  Without a ShareName directive the LH client sends the path being attached. With a ShareName directive, the LH client sends the sharname plus the path to the Universal driver.  The Universal Driver looks in the registry "Shares" subkey for a matching string and replaces the path received from the client with the path from the registry. The ShareName directive means that the revparam does not need to be in the same folder tree as the physical location. The LH client only reads the revparam and not the .LK/.OV files. The UD service reads the registry and the .LK/.OV files but not the revparam.  Thus you can put all  .LK and .OV files in locations where only UD service has access rights, and the revparam files in locations accessible by the user but not the UD service.  For example, you can create a data server which hosts the UD and all .LK / .OV files, and an application server which hosts the Oinsight.exe, dlls, images and other non .LK/,ov information. The revparam(s) on the application server use a ServerName, IPPort and ShareName to tell the LH client how to reach the data.

This appserver / dataserver configuration has some benefits:

·        Users do not need file access to the linear hash folders   

·        Users cannot accidentally connect in local mode by deleting the revparam

·        Communication with the data server is by TCPIP, the OS does not spend time checking access rights to the data server.

 

Make a terminal server or appserver farm by copying an OpenInsight folder containing all exes, dlls, images and other static files, a revparam with a ShareName, deleting all .LK and .OV files. Copy this folder to each terminal server in the farm.  Since the dlls and exes are local to each terminal server, only data crosses the network. This configuration gives good performance. The Universal driver will enforce the license count.

 

=== ShareName example ===

 

Below are screenshots of a revparam and the matching registry entries. The revparam is  the only file in a folder named data under the OI10_SOURCE folder.

{{kb1089_4.jpg}} 

The revparam contains a ShareName directive

{{kb1089_5.jpg}} 

The server's registry shows that data points to d:\data\

{{kb1089_6.jpg}}


Call attach_table("DATA", "", "") and the Universal Driver will serve files from the server folder "d:\data"

 

Note that the paths in the ShareName folders end with "\"
 

=== Multiple Server ===

If you need to share data across multiple servers, each having their own Universal Driver, we recommend using the Universal Driver 5.x.  The Universal Driver 4 client does not understand multiple UD services.  Using the UD4 client to simultaneously attach data on different UD4 managed servers may give unexpected results, particularly when folders with the same name exist on each server.  Locks may get placed on the first server reached rather than the correct host, or the LH client may attach the files in local mode.  In theory detaching all files from one host, then attaching to the other may clear that up, but in practice the revboot folder cannot be detached. Using the UD4.7 with multiple servers is impractical.

The Universal Driver 5.x can attach concurrently attach files from different servers (of course, the TCPIP address and port must be specified to point to the correct server). Combining this multiple server ability with the Share Name facility decouples the logical data structure from the physical structure.  For example what looks like a single tree can actually be a hierarchy of revparams pointing to a data striped across multiple servers.

 

== Managing the LH Client ==

LH.dll (in OI 9.x and prior) and REVLH.dll (in OI 10+) is the DLL which implements the Linear Hash filing system.  If the LH client locates a UD server then it proxies data activity between OpenInsight and the Universal Driver, in "server mode".   If the LH client cannot locate a server then it performs data activity itself, in "local mode".  Local mode can work with data located on the same or different servers, but it is not reliable when multiple users access the same files. Best practice is to avoid local mode for anything except temporary files in a user's personal context.

Revelation Software has released several versions of the Universal Driver over the years.  Each version of the UD has a matching version of LH.DLL.  When installing the Universal Driver service on a server it will prompt to install the Universal Driver client in a copy of OpenInsight on the same server.  The installer will copy LH.dll and some related dlls (for example RCL4.dll) into the OpenInsight folder.  OpenInsight versions prior to OpenInsight 10 are hard coded to use LH.DLL. The installer overwrites the existing LH.DLL with the version specific client dll. The LH.DLL in the __O__pen__I__nsight folder **must** match the version of the service you are running.  Use the NetDrv.exe tool located in the __O__pen__I__nsightfolder to confirm that your OpenInsight is using the correct network driver.

 

{{kb1089_7.jpg}}




The LH client will always try to contact a universal driver using the revparam instructions. If the client cannot find revparam instructions, it will try to connect to a Universal Driver server using named pipes on the machine hosting the specified folder. If the client cannot connect to a server then the UD4.x will default to operating in local mode and the UD5.x will default to aborting with an error message. Best practice is to ensure that the LH client will find a revparam for all data access.

 

RCL4.DLL

RCL4.DLL (in OpenInsight prior to 10) or REVRCL.DLL (in Openinsight 10) handles the actual communication between the LH client and the Universal Driver.  The date of RCL4.DLL in the __O__pen__I__nsight folder should match the date of the rcl.dll file in the Universal Driver folder.  Mismatched rcl versions have been known to cause instability.

 

 

=== Conclusion ===

The revparam file is an important (and necessary for the UD5) component for ensuring optimum performance of an OpenInsight application. The ShareName facility offers flexibility and possible performance improvements at the cost of configuration complexity.  Best practice implementation is to at least ensure that all files are controlled by a revparam, use TCPIP communication, have the SYSTEM own .LK and .OV files, and to examine the ShareName facility to see if its use is warranted.