OpenLink Request Broker Administration

Introduction

Getting To Know Your OpenLink Request Broker Components

Registering the Request Broker

Obtaining Version Numbers & Additional Descriptive Information From Your

Server Components

Using The Command Line Approach
Using The Admin Assistant

Request Broker Startup & Shutdown Options

System Security Enhancement Program

Configuring Request Broker Session Setting

Using Admin Assistant Wizards
Using Admin Assistant Forms

Introduction

The OpenLink Request Broker is the server component responsible for brokering the services of OpenLink Data Access and Service Providing Agents. Its is also the component responsible for coordinating and controlling your entire OpenLink Data Access session, irrespective of Data Access mechanism being used. The Request Broker is the heart and soul of the OpenLink Database Independent Communications Layer, the technology that enables the OpenLink Data Access drivers communicate with your backend database engines without the need to acquire additional database specific networking software from your backend database vendor(s).

Getting To Know Your OpenLink Request Broker Components

The core components required by the Request Broker are situated within the "bin" and "bin/w3config" sub-directories under your OpenLink server components base installation directory. Each of these components is described below and grouped by directory location.

The "bin" sub-directory:

Below is a list of the important files in the bin directory:

The "bin/w3config" sub-directory:

Registering Your OpenLink Request Broker

The OpenLink Request Broker must be registered in order to use it beyond the default license provided by OpenLink Software (2 concurrent client machines and 10 database connections).

• Place the register.ini (or any other file issued to you by OpenLink software) file in the "bin" sub-directory of your OpenLink Server Components installation directory.
  
• If you have to use the "ftp"utility to transfer these files please remember to perform this transfer in ASCII mode.
  
• Move into the "bin" sub-directory using the command: cd bin
  and then type one of the following commands:

       ./register (if the file name is "register.ini")

or

./register <filename>
(if you have a file name something other than "register.ini")

• A message will be displayed indicating success or failure.

The Register program must be re run every time to you upgrade concurrent usage support or actual OpenLink Versions.

Obtaining Version Numbers & Additional Descriptive Information From Your Server Components

Using The Command Line Approach

This approach provides you with information about the actual executable file, it includes:

Version Number - this is a component identifier that indicates the version number specific of a specific OpenLink Component

Release Number - this is an identifier for a collection of OpenLink Components, numerous components with different version numbers make up an OpenLink Data Access Drivers commercial release.

Compilation Date - indicates the date component was compiled.

CVSID - this is a source code archive identifier that relates to the actual source code archive from which a particular component has been assembled.

Binary Platform - indicates what platform the component has been built to run on.

To obtain the information referred to above for any OpenLink Component simply type in the program name at your command prompt with the "-?" switch.

Examples of the output produced by the OpenLink Request Broker and the OpenLink Web Service Agent are depicted below:

OpenLink Request Broker:

[openlink@opllinux bin]$ oplrqb -?

OpenLink Request Broker
Version 2.7A (Release 3.2) as of Thu Jan 21 1999 (cvsid 00048).
Compiled for Linux 2.0.36 (i586-pc-linux-gnulibc1)
Copyright (C) OpenLink Software.

Usage:   oplrqb [-flLdcv] [+foreground] [+loglevel num] [+logfile arg]
[+debug] [+configfile arg] [+version]

Web Service Agent:

[openlink@opllinux w3config]$ www_sv -?
OpenLink Web Service Agent
Version 1.1A (Release 3.2) as of Thu Jan 21 1999 (cvsid 00048).
Compiled for Linux 2.0.36 (i586-pc-linux-gnulibc1)
Copyright (C) OpenLink Software.

Usage:  www_sv [-lLd] [+loglevel num] [+logfile arg] [+debug]

Obtaining Additional Information Using The Admin Assistant

You obtain additional information using the Admin Assistant, this includes:

Register File Information - enables you determine the license(s) that you have in place.
Session Rules Book - the current set of rules for your OpenLink Data Access sessions.
Request Broker Log File Information - displays the contents of your Request Broker log file.

The screen shot below shows you an example of how this is achieved from the Admin Assistant:

OpenLink Request Broker Startup & Shutdown Options

Startup Options

The Request Broker can be started in a number of ways using various command line options.

Usage: oplrqb [-flLdcv] [+foreground] [+loglevel num] [+logfile arg][+debug][+configfile arg] [+version]

+foreground run Broker in the foreground mode

+loglevel log level where Broker session log details decrease in verbosity from 7 down to 1

+logfile full path and file name into which Broker session log output is to be written

+debug starts Broker in debug mode

+configfile use alternate configuration file

+version show version number

CommandLine Examples:

[openlink@opllinux openlink]$ oplrqb
Starts the Broker in background mode.

[openlink@opllinux openlink]$ oplrqb -v
Starts the Broker in background mode and displays version information as part of startup process.

[openlink@opllinux openlink]$ oplrqb -dv
Starts the Broker in foreground debug mode using default log level 7 (most amount of session log information). This blocks your screen and echoes the output of all OpenLink Data Access Clients to the blocked screen.

[openlink@opllinux openlink]$ oplrqb -dvl 1
Starts the Broker in foreground debug mode using default log level 1 (lowest amount of session log information). This blocks your screen and echoes the output of all OpenLink Data Access Clients to the blocked screen.

[openlink@opllinux openlink]$ oplrqb -dvL /tmp/openlink.log
Starts the Broker in foreground debug mode using default log level 7 (most amount of session log information). This blocks your screen and echoes the output of all OpenLink Data Access Clients to the file "/tmp/openlink.log" .

Shutdown Options

The OpenLink Request Broker can be shutdown in a number of ways using various command line options.

Usage: oplshut [-hcskryfp] [+hostname arg] [+configfile arg] [+show] [+kill] [+reinit] [+yes] [+force] [+protocol arg] [pid ..]

+hostname contact oplrqb on given host

+configfile use alternate configuration file

+show show database agent connections

+kill kill a database agent

+reinit restart broker without shutting down clients (partial restart)

+yes don't ask for confirmation

+force force immediate shutdown (kill all)

+protocol specify default protocol to use when listening for client connections

CommandLine Examples:

[openlink@opllinux openlink]$ oplshut
Shuts down broker on local machine

[openlink@opllinux openlink]$ oplshut -f
Shuts down broker on local machine without waiting for clients to terminate

[openlink@opllinux openlink]$ oplshut -fy
Same functionality as prior command, but without asking for confirmation

[openlink@opllinux openlink]$ oplshut -s
Shows the current active OpenLink Data Access Client connections

oplshut -k 81 93
Try to terminate the database agent sessions with process IDs 81 and 93

System Security Enhancement Program

Due to the Unix security model certain kernel calls can only be used when the process is run by root or under the permission of root. One of these function calls is needed for the PingWatchDog protocol, thereby forcing you to run the request broker as root. This can be accomplished in two ways:

1. The user logs in as root and then fires up the request broker.
   
   
2. The request broker is flagged to run under root privileges and the user can start it up from other accounts.

The consequences of 1 are that the user(s) who need to startup the broker need to have knowledge of the root password, which is not advisable for system managers to give to ordinary users.

Therefore we have built a solution whereby the broker can be flagged as running under root privileges without the user(s) needing to know the root password. The system manager executing the following commands accomplishes this:

    cd openlink/bin

    ./security -s

This will place the broker into a special security state that has the following impact:

1. The permissions of the oplrqb program are changed so it takes on the identity of "root" when started up.
   
   
2. The broker now knows the position of the oplrqb.ini file and will not accept certain startup flags so it cannot be tricked to read in another oplrqb.ini file from the command line.
   
   
3. The oplrqb.ini file can now only be written to by the "root" account, other accounts will only be able to read this file.

If a user now starts the broker the StartupBy clause within the [Security] section of the broker is checked to see whether the user is allowed to startup the broker (same for shutdown).

This accomplishes the wish of many system administrators that the broker process can be started up as root, without widespread knowledge of the root password.

As stated in item 3 above the "oplrqb.ini" file can now only be written to by the account "root". This means that ordinary users cannot modify this file, which is often an unpleasant side effect. To overcome this some system administrators change the mode of the oplrqb.ini file, thereby opening up to security risks.

OpenLink also has a proper answer for this scenario with the use of the 'includerulebook' option inside the security section of the rule book. The system administrator can split up the rulebook into different files which than can be included from the master oplrqb.ini file. This makes specific sections available to normal users, but allowing the system administrator to decide which sections can be overruled by normal users. The included rulebooks cannot overrule any section within the oplrqb.ini file.

This is a very powerful way of dealing with high security installations within large companies.

Configuring Request Broker Session Parameters

The Request Broker is responsible for setting up the profile of one of more OpenLink Data Access sessions, this includes a Transport Protocol selection, Keep Alive Packets notifications, Network Message Buffer Sizes. Initialization retry intervals, Agent initialization timeouts, and much more. Rather than have you manually set this options via the OpenLink Rule Book, it is now possible for you to configure this options via your Web Browser of choice using the Admin Assitant.

The Admin assistant allows you to configure Request Broker session parameters in two ways, via a series of Wizard Interactions or via an HTML form, the sections that follow illustrate both approaches.

Using Admin Assistant Wizards

1. Click on the "Edit the OpenLink Request Broker's Parameters (Wizard)" hyperlink
   
   
   
   
   
2. Specify the location of your Request Broker and its dependent components and any Agent related restrictions you may want to apply to your OpenLink session, then click the "Next" button.
   
   
   
   
   
3. Enter session log values if you are running a troubleshooting as opposed to normal OpenLink session, then click on the "Next" button.
   
   
   
   
   
4. Enter buffer size values for the inbound and outbound network messages for each OpenLink Agent (it is advisable to take the default values presented). Then click the "Next" button.
   
   
   
   
   
5. Enter values for "Database Agent" session initialization, "Broker Contact", and initialization failure retry counts by entering values into the respective fields as depicted below (it is advisable take the defaults). Then click on the next button.
   
   
   
   
   
6. Check one of more of the check-boxes presented in order select the Network Transport Protocol to be used by your Request Broker and Database Agents when communicating with your OpenLink Data Access Clients. Then click on the next button
   
   
   
   
   
7. You can choose to enable OpenLink TCP session connection monitoring by checking the "Send Keep Alive Packets" check-box. this facility sends probes to all OpenLink Clients verifying if they are still "Alive". You set the intervals for these probes by entering a value in the "Every" field. The default values are adequate for most scenarios. Once completed click the "Next" button to continue.
   
   
   
   
   
8. If you have more than one Network Interface Card (NIC) installed on your OpenLink Server machine, then you can enter a value in the "Force IP Address" field that represents the IP address that you want the Request Broker to listen at.
   
   You can also designate port number ranges to be used by the Broker to advertise other OpenLink services (e.g JDBC Agent used by OpenLink Drivers for JDBC). Once completed click the "Next" button to continue.
   
   
   
   
   
9. Click on the "Save" button to save your changes permanently.
   
   
   
   
   
10. Click the "Exit" button to leave the Broker Settings Wizard.
    
    
    
    
    

Using Admin Assistant Forms

You can also choose to configure your Request Broker's session settings via a Forms as opposed to Wizard based interface. You select this option from the Admin Assistant and you will be presented with a screen similar to the snapshot below.

Each Broker session settings field contains a description of the values that need to be entered into each of the forms fields. In addition a brief description of the use of each of these values is provided below each field.