Openlink Request Broker Configurator

OpenLink Request Broker Configurator Skill

Purpose

Configure and manage the OpenLink Request Broker (oplrqb) rule book (oplrqb.ini). The rule book controls:

• Mapping Rules — which DB agent handles each incoming connection request
• [generic_<name>] sections — per-agent program, environment, and connection defaults
• [Environment <type>]sections — OS environment variables injected into each agent process
• Broker global settings — port, timeouts, security, protocol parameters

Primary use cases: configure ODBC Agent rules from host-installed DSNs and JDBC Agent rules from discovered JDBC driver JARs.

→ Full parameter reference: Read references/rulebook-structure.md → www_sv endpoint reference: Read references/broker-www_sv-endpoints.md → JDBC driver registry: Read references/jdbc-driver-registry.md → ODBC DSN examples and token naming: Read references/odbc-dsn-examples.md

Execution Routing

Default execution order:

1. Mode C (www_sv) — HTTP Admin Assistant at http://localhost:8000 (preferred when available)
2. Mode A (direct file edit + CLI) — edit oplrqb.ini directly and use oplrqb CLI commands
3. Terminal-owned OAuth flow — when a REST endpoint requires OAuth 2.0 authentication, execute the OAuth flow from the terminal (authorization code, client credentials, or device flow), capture the Bearer token, and inject it into subsequent REST/OpenAPI calls via Authorization: Bearer {token} headers
4. MCP — if a remote MCP-enabled Virtuoso instance exposes broker management tools

If the user names a specific mode or protocol, follow that preference instead.

Step 0 — Mode Detection

Always run first.

# 1. Is www_sv responding? (Mode C)
curl -s http://localhost:8000/ | grep -i "openlink\|admin" | head -3

# 2. Is www_sv binary present but not running?
ls "/Library/Application Support/openlink/bin/www_sv" 2>/dev/null   # macOS
ls /opt/openlink/bin/www_sv 2>/dev/null                              # Linux

# 3. Is the rulebook directly accessible? (Mode A)
ls "/Library/Application Support/openlink/bin/oplrqb.ini" 2>/dev/null  # macOS
ls /opt/openlink/bin/oplrqb.ini 2>/dev/null                             # Linux

Decision:

• www_sv responds at port 8000 → Mode C
• www_sv binary found but not running → ask user "www_sv is installed but not running — start it?" → if yes, start it (see below) → Mode C
• Rulebook file accessible but www_sv unavailable → Mode A
• Neither → ask user which path to take

Starting www_sv (macOS):

nohup "/Library/Application Support/openlink/bin/www_sv" > /tmp/www_sv.log 2>&1 &
sleep 2 && curl -s http://localhost:8000/ | grep -i openlink

Credentials: www_sv uses HTTP Basic Authentication. Prompt for uid and pwd once at session start. Never write credentials to disk.

Platform Paths

Mode C — www_sv HTTP Admin Assistant (Preferred)

Base URL: http://localhost:8000 Auth: -u <uid>:<pwd> on every curl call.

C1. Discover Host DSNs (for ODBC Agent wizard)

curl -s -u <uid>:<pwd> http://localhost:8000/scripts/odbcdsn

Parse the HTML response to extract DSN names, or use Mode A's configparser approach for a clean list.

C2. View Full Rulebook (plain text)

curl -s -u <uid>:<pwd> "http://localhost:8000/scripts/brkbook?mode=plain"

Parse with Python configparser.RawConfigParser(strict=False, delimiters=('=',)).

Download as file:

curl -s -u <uid>:<pwd> "http://localhost:8000/scripts/brkbook?mode=save" -o /tmp/oplrqb_backup.ini

C3. View / Edit Broker Global Settings

# View
curl -s -u <uid>:<pwd> http://localhost:8000/scripts/brksetup

# Edit — POST changed keys
curl -s -u <uid>:<pwd> -X POST http://localhost:8000/scripts/brksetup \
  -d "BinaryDirectory=%2FLibrary%2FApplication+Support%2Fopenlink%2Fbin&Listen=5001&MaxAgents=0&HostNameResolver=Yes"

POST fields: BinaryDirectory, Listen, MaxAgents, MaxConnections, HostNameResolver, LingerTimeout, PingWatchdog, PingInterval, SendSize, ReceiveSize, BrokerTimeout, StartupBy, ShutdownBy, ShutdownFrom

C4. View / Edit DB Agent Sections

# List all agent sections
curl -s -u <uid>:<pwd> http://localhost:8000/scripts/brkagents

# View one agent
curl -s -u <uid>:<pwd> "http://localhost:8000/scripts/brkagents?agent=generic_odbc"

# Edit an agent — POST
curl -s -u <uid>:<pwd> -X POST http://localhost:8000/scripts/brkagents \
  -d "agent=generic_odbc_MyDSN&Program=odbc_mv&Environment=ODBC&ReUse=always&Database=MyDSN&Description=ODBC+agent+for+MyDSN"

POST fields: agent, Program, Description, CommandLine, Directory, Database, UserID, Password, ConnectOptions, ReadOnly, ServerOptions, OpsysLogin, ReUse, Environment, SSLKeyFile, SSLRequired

C5. View / Edit Mapping Rules

# View
curl -s -u <uid>:<pwd> http://localhost:8000/scripts/brkmaped

# Add a rule
curl -s -u <uid>:<pwd> -X POST http://localhost:8000/scripts/brkmaped \
  -d "action=add&domain=odbc&db=MyDSN&uid=*&opsys=*&machine=*&appl=*&mode=*&target=generic_odbc_MyDSN"

# Delete a rule (by 1-based index)
curl -s -u <uid>:<pwd> -X POST http://localhost:8000/scripts/brkmaped \
  -d "action=delete&rule=<index>"

Rule fields: domain, db, uid, opsys, machine, appl, mode; target = generic_<name> for accept or a message for reject.

C6. View / Edit Alias Sections

# View Domain Aliases
curl -s -u <uid>:<pwd> "http://localhost:8000/scripts/brkalias?atype=Domain+Aliases"

# Add a Domain Alias
curl -s -u <uid>:<pwd> -X POST http://localhost:8000/scripts/brkalias \
  -d "atype=Domain+Aliases&action=add&key=MyDB+JDBC&value=myjdbc"

Valid atype values: Domain Aliases, Database Aliases, Opsys Aliases, Machine Aliases, Application Aliases, User Aliases

C7. Utility Endpoints

# Reinitialize broker (reload rulebook — preferred after edits)
curl -s -u <uid>:<pwd> http://localhost:8000/scripts/brkinit

# View broker log
curl -s -u <uid>:<pwd> http://localhost:8000/scripts/brklog

# Broker version
curl -s -u <uid>:<pwd> http://localhost:8000/scripts/brkver

# Active connections
curl -s -u <uid>:<pwd> http://localhost:8000/scripts/brkconn

# License info
curl -s -u <uid>:<pwd> http://localhost:8000/scripts/brklic

Success detection: POST responses contain "Configuration Updated" on success, "Sorry, this operation failed" on error.

Mode A — Direct File Operations (Fallback)

A1. Read Rulebook

import configparser, os

RULEBOOK_PATHS = [
    '/Library/Application Support/openlink/bin/oplrqb.ini',  # macOS
    '/opt/openlink/bin/oplrqb.ini',                          # Linux
    '/etc/openlink/oplrqb.ini',                              # Linux alt
]

def read_rulebook():
    cfg = configparser.RawConfigParser(strict=False, delimiters=('=',))
    for path in RULEBOOK_PATHS:
        if os.path.exists(path):
            cfg.read(path)
            return cfg, path
    return None, None

cfg, path = read_rulebook()
for section in cfg.sections():
    print(f'\n[{section}]')
    for k, v in cfg.items(section):
        print(f'  {k} = {v}')

Important: Use RawConfigParser(strict=False, delimiters=('=',)). The [Mapping Rules] section contains keys like odbc:*:*:*:*:*:* — colons in keys will confuse the default parser if colon is treated as a delimiter.

A2. Discover Host DSNs (for ODBC Agent wizard)

import configparser, os

def list_dsns():
    dsns = []
    paths = [
        '/Library/ODBC/odbc.ini',            # macOS system
        os.path.expanduser('~/Library/ODBC/odbc.ini'),  # macOS user
        '/etc/odbc.ini',                      # Linux system
        os.path.expanduser('~/.odbc.ini'),    # Linux user
    ]
    for p in paths:
        if os.path.exists(p):
            cfg = configparser.RawConfigParser(strict=False)
            cfg.read(p)
            for sec in cfg.sections():
                if sec.lower() not in ('odbc data sources',):
                    dsns.append(sec)
    return sorted(set(dsns))

print('\n'.join(list_dsns()))

A3. Validate After Edits

Always run inicheck before attempting a broker reinit:

# macOS
"/Library/Application Support/openlink/bin/inicheck" \
  "/Library/Application Support/openlink/bin/oplrqb.ini"

# Linux
/opt/openlink/bin/inicheck /opt/openlink/bin/oplrqb.ini

Exit code 0 = valid. Any error output must be fixed before proceeding.

A4. Editing Sections

Use the Read tool to read the rulebook, then the Edit tool to make targeted replacements. Prefer line-precise edits to preserve existing comments.

Appending a new agent section — add after the last [generic_odbc*] block:

[generic_odbc_MyDSN]
Description     = ODBC agent for MyDSN
Program         = odbc_mv
Environment     = ODBC
ReUse           = always
Database        = MyDSN
;Userid         =
;Password       =
;ReadOnly       = Yes

Appending a new Environment section — add after [Environment ODBC]:

[Environment JDBC_MyDriver]
CLASSPATH       = /path/to/mydriver.jar

Adding a Mapping Rule — insert before the odbc:*:*:*:*:*:* catch-all in [Mapping Rules]:

odbc:MyDSN:*:*:*:*:*         = accept generic_odbc_MyDSN

ODBC Agent Configuration Wizard

When the user asks to configure ODBC agents:

Step ODBC-1: Discover DSNs

Mode C:

curl -s -u <uid>:<pwd> http://localhost:8000/scripts/odbcdsn

Parse HTML for DSN names, or parse odbc.ini directly (Mode A method above).

Mode A: Use list_dsns() Python snippet above.

Step ODBC-2: Present List

Display discovered DSNs and ask: "Which DSNs should have dedicated ODBC Agent rules? Enter DSN names (comma-separated) or 'all' for a single catch-all rule."

Step ODBC-3: Generate for Each Selected DSN

For each DSN <dsnname> (URL-encode spaces as + for POST, or use underscore-normalized names for section keys):

Domain Alias — add to [Domain Aliases] if not already present:

<dsnname>   = odbc_<normalized_name>

Where <normalized_name> is the DSN name lowercased with spaces replaced by underscores.

Agent section [generic_odbc_<normalized_name>]:

[generic_odbc_<normalized_name>]
Description     = ODBC agent for <dsnname>
Program         = odbc_mv
Environment     = ODBC
ReUse           = always
Database        = <dsnname>

Mapping Rule in [Mapping Rules] — insert before the existing odbc:*:*:*:*:*:* catch-all:

odbc:<dsnname>:*:*:*:*:*     = accept generic_odbc_<normalized_name>

Step ODBC-4: Catch-all Fallback (if user selects "all")

Ensure this rule exists (it is in the default rulebook already):

odbc:*:*:*:*:*:*             = accept generic_odbc

And the stock [generic_odbc] section is present:

[generic_odbc]
Description     = Default settings for ODBC agent
Program         = odbc_mv
Environment     = ODBC
ReUse           = always

Step ODBC-5: Reinitialize

After all changes: reinitialize the broker (see Step 6 below).

JDBC Agent Configuration Wizard

When the user asks to configure JDBC agents:

Step JDBC-1: Discover JDBC Driver JARs

# 1. Scan $CLASSPATH entries for JAR files
echo $CLASSPATH | tr ':' '\n' | grep '\.jar$'

# 2. Check common JAR directories if $CLASSPATH is unset or empty
for d in /usr/local/lib ~/lib /opt/jdbc /Library/Java/Extensions /usr/share/java; do
  ls "$d"/*.jar 2>/dev/null
done

# 3. Peek inside each JAR for JDBC SPI registration
# (run for each discovered JAR)
unzip -p <jar-path> META-INF/services/java.sql.Driver 2>/dev/null

Step JDBC-2: Match JARs to Driver Registry

→ Full registry with URL templates: Read references/jdbc-driver-registry.md

Quick reference:

Step JDBC-3: Present Discovered Drivers

List matched drivers and ask: "Which JDBC drivers should have agent rules? Enter numbers (comma-separated) or 'all'."

Step JDBC-4: Prompt for URL Parameters

For each selected driver, display the URL template from the registry and prompt:

• Host (default: localhost)
• Port (default: driver-specific)
• Database/SID/Schema name

Step JDBC-5: Generate for Each Selected Driver

Select the appropriate JDBC version slot. The rulebook has pre-defined slots jdbc11 through jdbc18. Use the first unused slot, or create a new labeled slot.

[Environment JDBC<n>] — update or create:

[Environment JDBC<n>]
CLASSPATH       = <jar-path>

[generic_jdbc<n>] — agent section:

[generic_jdbc<n>]
Description     = <Driver display name> JDBC agent
Program         = jdbc<n>_sv
Environment     = JDBC<n>
ReUse           = never
;Database       = <jdbc-url-with-filled-params>

Domain Alias in [Domain Aliases]:

<DbType> JDBC   = jdbc<n>

Mapping Rule in [Mapping Rules]:

jdbc<n>:*:*:*:*:*:*           = accept generic_jdbc<n>

Step JDBC-6: Reinitialize

After all changes: reinitialize the broker (see Step 6 below).

Step 6 — Broker Restart / Reinitialize

Always confirm with the user before executing privileged commands.

Reinitialize (preferred after rulebook edits — reloads config, keeps connections alive):

# Via www_sv (Mode C)
curl -s -u <uid>:<pwd> http://localhost:8000/scripts/brkinit

# Via CLI (Mode A) — macOS
"/Library/Application Support/openlink/bin/oplshut" +reinit

# Via CLI (Mode A) — Linux (systemd)
sudo systemctl reload oplrqb

# Via CLI (Mode A) — Linux (direct)
/opt/openlink/bin/oplshut +reinit

Full restart:

# macOS
"/Library/Application Support/openlink/bin/oplshut" +yes
nohup "/Library/Application Support/openlink/bin/oplrqb" > /tmp/oplrqb_start.log 2>&1 &
sleep 3 && curl -s http://localhost:8000/scripts/brkver

# Linux (systemd)
sudo systemctl restart oplrqb
sudo systemctl status oplrqb

# Linux (direct)
/opt/openlink/bin/oplshut +yes
nohup /opt/openlink/bin/oplrqb > /tmp/oplrqb_start.log 2>&1 &

Sudo note: If oplshut requires sudo and Claude Code has no TTY, configure passwordless sudo (same pattern as openlink-license-manager skill):

echo 'USERNAME ALL=(ALL) NOPASSWD: /path/to/oplshut' | sudo tee /etc/sudoers.d/oplshut && sudo chmod 440 /etc/sudoers.d/oplshut

Quick Reference Table

Troubleshooting

Initialization Sequence

When invoked:

⛔ PRE-BUILD CHECK: Before producing output, re-read the relevant workflow section above and re-read any checklists or verification gates defined in this skill. Confirm each checklist item before writing output. Build to pass — do not retro-fit. Apply the CLAUDE.md Anti-Drift Protocol: re-read spec section before build, gate-first validation, section-by-section delivery.

1. Run Step 0 — detect OS, check www_sv, resolve rulebook path
2. If www_sv binary found but not running: offer to start it
3. Report: mode, OS, rulebook path, broker version, listen port
4. Prompt www_sv credentials if Mode C (session only)
5. Ask what to do:
   • Configure ODBC Agents → run ODBC wizard (Steps ODBC-1 through ODBC-5)
   • Configure JDBC Agents → run JDBC wizard (Steps JDBC-1 through JDBC-6)
   • View rulebook → full plain-text dump
   • Edit mapping rules → show current rules; offer add/delete
   • Edit agent settings → list agents; offer edit
   • Edit broker global settings → show current; offer edit
   • View broker log → tail last 50 lines
   • Reinitialize / restart broker → confirm then execute
   • Validate → run inicheck and report result

Version

1.0.0 — Initial release. ODBC and JDBC agent configuration wizards with host DSN discovery and JDBC driver auto-detection. Full rule book management via www_sv HTTP (Mode C) and direct file access (Mode A). macOS and Linux support.