Applications Systems

Configuring IBM DB2 and IBM DB2 HADR Health SAM Templates on Linux and AIX

How to configure IBM DB2 and IBM DB2 HADR Health SAM application monitor templates for agent-based polling on Linux and AIX DB2 servers using unixODBC and the IBM DB2 CLI/ODBC driver.

First published date

4/18/2026 11:15 AM

Last published date

4/18/2026 11:15 AM

Overview

How to configure IBM DB2 and IBM DB2 HADR Health SAM application monitor templates for agent-based polling on Linux and AIX DB2 servers using unixODBC and the IBM DB2 CLI/ODBC driver.

The procedure covers:

Preparing unixODBC and DB2 ODBC/CLI drivers
Configuring odbcinst.ini, odbc.ini, and db2cli.ini
Testing connectivity with isql
Wiring connection strings into the IBM DB2 and IBM DB2 HADR Health templates

Product section

Server Application Monitor

Resolution

1. Prerequisites

On each DB2 host you want to monitor:

IBM DB2 9.7 or later installed and running on the host.
A DB2 user with:
- Permission to connect to the monitored database.
- Permission to query HADR monitoring views and SYSIBMADM tables as required by the templates.
The SolarWinds Platform agent for Linux/AIX installed and assigned to the node.
Ability to install packages and edit config files as root (or via sudo).

2. Common Concepts and Files

Regardless of OS, three unixODBC/DB2 config files are involved:

Driver registry – odbcinst.ini
- Registers drivers (e.g. DB2) with unixODBC.
- Typical locations:
  - Linux: /etc/odbcinst.ini or /etc/unixODBC/odbcinst.ini
  - AIX: /opt/freeware/etc/odbcinst.ini (per docs).
Data sources – odbc.ini
- Defines DSNs (Data Source Names) that map to databases.
- Typical locations:
  - Linux: /etc/odbc.ini or /etc/unixODBC/odbc.ini
  - AIX: /opt/freeware/etc/odbc.ini.
DB2 CLI config – db2cli.ini / db2dsdriver.cfg
- Lives inside the DB2 CLI driver tree (e.g. .../clidriver/cfg/db2cli.ini).
- Required when using IBM’s CLI driver (libdb2o.so) and DSNs; defines database/host/port for each DSN.

The SolarWinds agent-side Python ODBC client (pypyodbc) uses unixODBC, which in turn calls the DB2 CLI library registered in odbcinst.ini and configured in db2cli.ini / odbc.ini.

3. Linux (RHEL/SLES/Other) – Step‑by‑Step

3.1 Install unixODBC

On the DB2 host:

# RHEL / CentOS / Oracle Linux
sudo yum -y install unixODBC

# SLES
sudo zypper install unixODBC

SolarWinds requires unixODBC to be present for ODBC-based monitoring.

3.2 Install or identify the IBM DB2 CLI/ODBC driver

You have two typical options:

DB2 instance-installed driver
DB2 often ships a shared library such as:

/db2/&lt;instance_home&gt;/DB2_11.5.../lib64/libdb2.so
/db2/&lt;instance_home&gt;/DB2_11.5.../lib64/libdb2o.so

Standalone IBM DB2 CLI/ODBC driver (preferred for clarity)
Download the appropriate DB2 CLI/ODBC package from IBM (e.g. v11.5_linuxx64_odbc_cli.tar.gz) and extract it to, for example:
```
sudo mkdir -p /opt/DB2CLI
sudo tar -xzf v11.5_linuxx64_odbc_cli.tar.gz -C /opt/DB2CLI
```
After extraction, you should see:
```
/opt/DB2CLI/odbc_cli/clidriver/lib/libdb2o.so
/opt/DB2CLI/odbc_cli/clidriver/cfg/db2cli.ini (or sample)
```

The CLI library (libdb2o.so) is the recommended target for Driver= in odbcinst.ini when using agent-based polling with the IBM CLI driver.

3.3 Configure `odbcinst.ini` (Linux)

Edit the unixODBC driver registry file (path may be /etc/odbcinst.ini or /etc/unixODBC/odbcinst.ini depending on your distro/build):

sudo vi /etc/unixODBC/odbcinst.ini

Add a dedicated driver entry for SolarWinds so you don’t disturb existing applications:

[DB2_SW]
Description = DB2 CLI Driver for SolarWinds
Driver      = /opt/DB2CLI/odbc_cli/clidriver/lib/libdb2o.so
FileUsage   = 1
DontDLClose = 1

You can also keep an existing [DB2] entry for legacy apps and only use [DB2_SW] for SAM.

3.4 Configure `db2cli.ini` for each monitored database

In the CLI driver config directory (matching the path used in Driver=):

cd /opt/DB2CLI/odbc_cli/clidriver/cfg
sudo vi db2cli.ini

Add a section for each database/DSN. Name must match the DSN name if you later use DSN-based connection strings:

[DB2APP1_DSN]
Database    = DB2APP1
Hostname    = db2app1.example.com
ServiceName = 5914
Protocol    = TCPIP

If you prefer not to use DSNs, you can still keep db2cli.ini minimal and rely on driver-based connection strings (Database/Hostname/Port in the string).

A common error SQL1531N indicates the DSN name used by the client is not defined in db2cli.ini / db2dsdriver.cfg.

3.5 Configure `odbc.ini` DSNs (Linux)

Edit the unixODBC DSN file (again, typically /etc/odbc.ini or /etc/unixODBC/odbc.ini):

sudo vi /etc/unixODBC/odbc.ini

Add a DSN per database:

[DB2APP1_DSN]
Description = IBM DB2 via CLI (SolarWinds)
Driver      = DB2_SW
Database    = DB2APP1
Hostname    = db2app1.example.com
Port        = 5914
Protocol    = TCPIP

The Driver value must match the section name in odbcinst.ini (e.g. [DB2_SW]).

3.6 Test connectivity with `isql` (Linux)

From the DB2 host:

isql -v DB2APP1_DSN db_user db_password

If it connects and shows a SQL> prompt, ODBC + CLI + unixODBC are correctly wired.
If you see:
- [IM002] [unixODBC][Driver Manager]Data source name not found, and no default driver specified
  → DSN not defined in odbc.ini or wrong Driver= mapping in odbcinst.ini.
- SQL10007N Message "0" could not be retrieved. Reason code: "3".
  → Incorrect or incomplete DB2 ODBC driver installation (wrong bitness or wrong library path). IBM and SolarWinds docs call this out as usually a driver version/architecture mismatch; point Driver= at the correct CLI library and ensure the correct DB2 CLI package and environment are used.
- SQL1531N ... DSN ... could not be found in ... db2cli.ini
  → DSN name not defined in db2cli.ini / db2dsdriver.cfg (section name mismatch).

Only proceed to SAM once isql works.

4. AIX – Step‑by‑Step

AIX requires special attention to paths and 32‑ vs 64‑bit drivers.

4.1 Install unixODBC and dependencies on AIX

SolarWinds docs recommend installing unixODBC and its dependencies from AIX Open Source Packages:

# Example sequence (run as root)
rpm -ivh unixODBC-2.3.4-1.aix5.1.ppc.rpm
rpm -ivh info-6.4-1.aix5.1.ppc.rpm
rpm -ivh libiconv-1.15-1.aix5.1.ppc.rpm
rpm -ivh libtool-ltdl-1.5.26-2.aix5.1.ppc.rpm
rpm -ivh readline-7.0-3.aix5.1.ppc.rpm
# plus any other prerequisites noted by unixODBC/DB2

Ensure rpm.rte is installed under /usr/bin/rpm as indicated in docs.

Important: Several support cases have shown that using the wrong DB2 ODBC driver bitness (e.g. 64‑bit driver with 32‑bit process) causes “can’t open lib ... file not found” and related issues. IBM and SolarWinds guidance is to use the driver build that matches the unixODBC / agent process bitness.

4.2 Install the IBM DB2 ODBC/CLI driver on AIX

For AIX, the docs reference bundles such as v11.1.1fp1_aix64_odbc_cli.tar.gz:

Example:

sudo mkdir -p /opt/odbc_cli
cd /opt/odbc_cli
sudo gunzip v11.1.1fp1_aix64_odbc_cli.tar.gz
sudo tar -x -f v11.1.1fp1_aix64_odbc_cli.tar -C /opt/odbc_cli

This will create a clidriver directory, typically under /opt/IBM/db2/V11.1/lib64 or a similar path, containing db2o.o / libdb2o.so and config files.

4.3 Configure `odbcinst.ini` (AIX)

On AIX, unixODBC commonly uses:

/opt/freeware/etc/odbcinst.ini

Create or edit this file:

sudo vi /opt/freeware/etc/odbcinst.ini

Add a DB2 driver entry for SolarWinds:

[DB2_SW]
Description = DB2 Driver for SolarWinds
Driver      = /opt/IBM/db2/V11.1/lib64/db2o.o
FileUsage   = 1
DontDLClose = 1

SolarWinds and internal runbooks use this pattern for AIX DB2 monitoring.

If the library is not found, adjust Driver= to the correct db2o.o / libdb2o.so path.

4.4 Configure `odbc.ini` and `db2cli.ini` (AIX)

/opt/freeware/etc/odbc.ini:

sudo vi /opt/freeware/etc/odbc.ini

Add:

[DB2APP1_DSN]
Description = IBM DB2 ODBC data source
Driver      = DB2_SW
DMEnvAttr   = SQL_ATTR_UNIXODBC_ENVATTR={DB2INSTANCE=db2app1}   ; optional per instance
Database    = DB2APP1
Hostname    = db2app1.example.com
Port        = 5914
Protocol    = TCPIP

Docs show using DMEnvAttr = SQL_ATTR_UNIXODBC_ENVATTR={DB2INSTANCE=<dbname>} to handle multiple instances on a single AIX host.

db2cli.ini (inside the CLI install, similar to Linux):

cd /opt/odbc_cli/clidriver/cfg
sudo vi db2cli.ini

Add:

[DB2APP1_DSN]
Database    = DB2APP1
Hostname    = db2app1.example.com
ServiceName = 5914
Protocol    = TCPIP

4.5 Test with `isql` on AIX

/opt/freeware/bin/isql -v DB2APP1_DSN db_user db_password

SolarWinds docs show a successful sample output with Connected! and a SQL> prompt when ODBC is correctly configured.

If you see:

“could not load module” / “No such file or directory” in pypyodbc or isql
→ Driver= path is wrong or libodbc is not in a known path. AIX guidance includes adding a symlink ln -s /opt/freeware/lib/libodbc.a /usr/lib/libodbc.a in some cases.
IM002 DSN not found
→ DSN missing/incorrect in /opt/freeware/etc/odbc.ini or driver section missing in odbcinst.ini.

Resolve all isql issues before proceeding to SAM.

5. Configuring SAM Templates

Once ODBC connectivity is verified on each host:

5.1 IBM DB2 template

In the SolarWinds web console, go to:
Settings → All Settings → SAM Settings → Manage Templates.
Locate the IBM DB2 template and create a copy to customize.

In your copy, update component connection strings to use either:

DSN-based:

DSN=DB2APP1_DSN;Uid=${USER};Pwd=${PASSWORD};

Driver-based:

Driver={DB2_SW};Database=DB2APP1;Hostname=${IP};Port=5914;Protocol=TCPIP;Uid=${USER};Pwd=${PASSWORD};

Assign appropriate credentials (DB user) to the components.
Assign the template to the DB2 node monitored by the agent and test components.

5.2 IBM DB2 HADR Health template

The IBM DB2 HADR Health template reads from HADR monitoring views (SNAPHADR / MON_GET_HADR) to expose role, connect status, heartbeats, and other metrics.

Follow similar steps:

Copy the built‑in IBM DB2 HADR Health template.

For each component, configure a connection string using the same DSN/driver pattern you validated with isql, for example:

DSN=DB2APP1_DSN;Uid=${USER};Pwd=${PASSWORD};

or:

Driver={DB2_SW};Database=DB2APP1;Hostname=${IP};Port=5914;Protocol=TCPIP;Uid=${USER};Pwd=${PASSWORD};

Assign the template to the HADR primary/standby node(s).
Test components; you should see values for:
- HADR Role
- HADR Connect Status
- Missed Heartbeats
- HADR State
- HADR Sync Mode, etc.

6. Common Error Codes and Fixes

Error / Symptom	Likely Cause	Fix
`[IM002] [unixODBC][Driver Manager] Data source name not found, and no default driver specified`	DSN not defined in `odbc.ini`, or `Driver=` in DSN refers to a non‑existent driver in `odbcinst.ini`	Define DSN in `odbc.ini`; ensure `Driver=` matches a section in `odbcinst.ini`.
`Can't open Lib 'IBM DB2 ODBC DRIVER' - file not found`	Driver name in connection string does not match any section in `odbcinst.ini`, or path is invalid	Use `Driver={DB2_SW}` (matching `[DB2_SW]`), and ensure `Driver=` path points to a real DB2 CLI library.
`[IBM][CLI Driver] SQL10007N Message "0" could not be retrieved. Reason code: "3".`	Wrong or incomplete DB2 ODBC driver (bitness/version mismatch, incorrect library path)	Install correct DB2 CLI driver and point `Driver=` at the correct `libdb2o.so`/`db2o.o` path.
`[IBM][CLI Driver] SQL1531N The connection failed because the name specified with the DSN ... not found in db2cli.ini`	DSN name not present (or mis‑spelled) in `db2cli.ini` / `db2dsdriver.cfg`	Add a matching section in `db2cli.ini` (e.g. `[DB2APP1_DSN]`) with Database/Hostname/ServiceName/Protocol.
Python/pypyodbc error: `Could not load module ... System error: No such file or directory`	`libodbc` or DB2 library not on library path (especially on AIX)	Ensure `Driver=` path exists; on AIX, add symlink for `libodbc.a` to `/usr/lib` if required.

7. Summary

For each IBM DB2 / IBM DB2 HADR host:

Install unixODBC and the IBM DB2 CLI/ODBC driver (correct bitness).
Register the driver in odbcinst.ini (e.g. [DB2_SW]).
Define DSNs in odbc.ini and the same names in db2cli.ini.
Verify connectivity with isql -v <DSN>.
Use the working DSN/driver in the IBM DB2 and IBM DB2 HADR Health SAM templates and test components.

Once this pattern is validated on one host, you can roll it out to additional DB2 servers by cloning the odbcinst.ini + odbc.ini + db2cli.ini structure and reusing the same SAM templates with per‑node connection strings.

Disclaimer: Please note, any content posted herein is provided as a suggestion or recommendation to you for your internal use. This is not part of the SolarWinds software or documentation that you purchased from SolarWinds, and the information set forth herein may come from third parties. Your organization should internally review and assess to what extent, if any, such custom scripts or recommendations will be incorporated into your environment. You elect to use third-party content at your own risk, and you will be solely responsible for the incorporation of the same if any.