SQL Toolkit
Overview Copied
The SQL Toolkit plugin executes database queries that can display the output of the query in the dataview and run custom queries to monitor database data. For more information about the SQL Toolkit plugin and configuration, see SQL Toolkit configuration.
This plugin can connect to and extract data from the following supported databases:
- MySQL or MariaDB.
- Microsoft SQL Server
- Oracle
- SAP ASE, formerly known as Sybase ASE.
- PostgreSQL.
- IBM DB2.
For the complete list of supported database server versions, go to Geneos Compatibility Matrix.
A typical view constructed using the SQL Toolkit plugin consists of a dataview whose columns and rows are entirely determined by the query.
This works well for use cases that require periodical queries on databases, such as:
- Security administrators who check and review audit logs recorded in the database server.
- Service Level Managers who get alerted on application incidents.
- Administrators who view the quality metrics inserted in the database servers.
In addition, below is an example of SQL Toolkit dataview where you can see the headline variables:
To connect to the database, the Netprobe requires third-party database client libraries to run the SQL Toolkit plugin. These libraries are usually included in the database installation.
Headline | Description |
---|---|
queryStatus |
displays the status of the query. The following are the possible values:
|
queryDuration | Displays the time in seconds that the current query took on its last run. The time is set to 0 when the status is Idle . |
rowsReturned | Shows the number of rows returned in the dataview. |
Intended audience Copied
This guide is intended for experienced Geneos users who want to configure the SQL Toolkit plugin to execute database queries.
As a user, you should be familiar with SQL or other database, and with the administration of Netprobe and DB libraries that are required to run the SQL Toolkit sampler.
Prerequisites Copied
The following requirements must be met prior to the configuration and setup of the SQL Toolkit plugin:
- You must use the supported versions of Active Console, Gateway, and Netprobe. For guidance, see Supported Geneos versions in 6.x Compatibility Matrix.
- You must have the servers of the Active Console, Gateway, and Netprobe running on the supported operating systems. For guidance, see Operating system support in 6.x Compatibility Matrix.
- You must connect your Active Console to the Gateway where this plugin is configured.
- The Netprobe user must have a read-access permission to the monitored file.
Configure the Netprobe and database client libraries Copied
Depending on what database your Netprobe needs to connect to, you may have to amend your environment to expose the appropriate libraries to the Netprobe. The Netprobe indirectly loads these libraries depending on what database the plugin has been configured to connect to. For more information on supported libraries for each platform, see Required client libraries in Databases.
You must first configure your selected database and define its required variables in the Netprobe start script before you can set up your SQL Toolkit sampler in Gateway Setup Editor. The configuration steps for each database changes depending on the operating system you are using.
Note
The Netprobe start script is found innetprobe/templates
directory of your Netprobe package.
Linux Copied
- Ensure the database libraries and paths are defined in the Netprobe start script. A Netprobe start script is where you define the required variables to run a Netprobe.
- Log in to the Linux server where the Netprobe is running.
- Use any Secure Shell or SSH client to access the server and to modify the Netprobe start script.
Windows Copied
- Ensure the required Windows environment variables and libraries are defined in the system properties.
- Log in the Windows server where the Netprobe is running.
- Access the actual Windows server.
AIX Copied
Caution
Some IBM AIX hosts still use theLIBPATH
variable when loading shared libraries. For backward compatibility, the path to the required libraries must be added to theLIBPATH
variable.
MySQL database Copied
For more information on supported MySQL libraries for each platform, see Required client libraries in Databases.
Note
The following authentication plugins are supported:
mysql_native_password
caching_sha2_password
The
caching_sha2_password
authentication plugin can only be used with secure connections. To do this, the MySQL server should be configured to use secure connections, and the SSL mode in the SQL Toolkit configuration should be set toPreferred
,Required
,Verify_ca
, orVerify_identity
.
Linux Copied
When MySQL is installed via packaged installation, it automatically adds /usr/lib64/mysql
to the list of directories (/etc/ld.so.conf.d
) where the dynamic linker searches for libraries. This way, even if you do not set LD_LIBRARY_PATH
, the Netprobe can find the library in /usr/lib64/mysql
.
If you need to set LD_LIBRARY_PATH
, follow these steps:
-
Locate the MySQL client library file.
-
Add these variables to the Netprobe start script using a text editor.
Variable Value MYSQL_LIB export MYSQL_LIB=/usr/lib64/mysql LD_LIBRARY_PATH export LD_LIBRARY_PATH=${NP_LIB}:${MYSQL_LIB} -
Add the MYSQL_LIB variable.
-
Enter the path of the library file in the MYSQL_LIB variable:
MYSQL_LIB=/usr/lib64/mysql
- Enter the MYSQL_LIB in the LD_LIBRARY_PATH variable:
export LD_LIBRARY_PATH=${NP_LIB}:${MYSQL_LIB}
- Save the changes to the Netprobe start script.
- Exit the editor.
- Restart the Netprobe.
Windows Copied
-
Modify the Path variable of the Windows host.
-
Locate the MySQL client library file –
libmysql.dll
. Below is an example that shows you where to locate the MySQL file:Variable Value Path <existing path>;C:\database_libs\mysql\mysql-connector-c-6.1.11-winx64\lib
C:\database_libs\mysql\mysql-connector-c-6.1.11-winx64\lib>dirVolume in drive C has no label.Volume
Serial Number is 1846-3FFADirectory of C:\database_libs\mysql\mysql-connector-c-6.1.11-winx64\lib10/25/2017
04:59 PM <DIR> ..07/18/2017 12:07 AM 4,879,360 libmysql.dll07/18/2017 12:07 AM
26,956 libmysql.libC:\database_libs\mysql\mysql-connector-c-6.1.11-winx64\lib>
Caution
If you are also using a Maria in your machine and added its path in the Path variable, then you must move the MySQL to a higher directory to avoid conflict.
- Click Start on your computer.
- Right-click Computer, and click Properties.
- Click Advanced system settings.
- Click Environment Variables.
- Click the Path system variable.
- Click Edit… to append the path of the
libmysql.dll
file - Click OK to save the changes in the Edit System Variable screen.
- Click OK to save the changes in the Environment Variables screen.
- Restart the Netprobe.
Go to the Gateway Setup Editor to Connect to a MySQL database in SQL Toolkit configuration.Success
You have successfully defined the path variables of the Windows host.
IBM AIX Copied
Run the following export command in your machine before running the Netprobe:
export LIBPATH=/opt/freeware/lib/gcc/powerpc-ibm-aix7.2.0.0/8/pthread:/opt/freeware/lib64
If you are using Netprobe version 6.2.x. or older, then you must run the following additional export command:
export GENEOS_MYSQL_CLIENT_LIBRARY=libmysqlclient.a\(libmysqlclient.so.21\)
Caution
Some IBM AIX hosts still use theLIBPATH
variable when loading shared libraries. For backward compatibility, the path to the required libraries must be added to theLIBPATH
variable.
Success
You have successfully defined the database library paths in the Netprobe start script. Go to the Gateway Setup Editor to Connect to a MySQL database in SQL Toolkit configuration.
Microsoft SQL Server database Copied
Note
MS SQL is not supported in an ARM64 environment. Instead, MS SQL is designed to run on AMD64 or x64 processors.
Linux Copied
- Install the MS SQL Server ODBC 18 driver by following the instructions in the Microsoft website. Select the instruction that matches your Linux version.
- Execute this command to verify whether the installation is successful:
odbcinst -q -d -n "ODBC Driver 18 for SQL Server"
The command displays the message below once the installation is successful:
[ODBC Driver 18 for SQL Server]
Description=Microsoft ODBC Driver 18 for SQL Server
Driver==/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.2.so.1.1
UsageCount=1
- Copy or symlink the
/etc/odbcinst.ini
to/opt/microsoft/msodbcsql18/lib64
folder:
sudo ln -s /etc/odbcinst.ini /opt/microsoft/msodbcsql18/lib64/odbcinst.ini
Note
Symlink or symbolic link is a reference to another file or directory.
-
Add these variables to the Netprobe start script using a text editor. Follow the variables and their values in the table:
Variable Value SQLSERVER_LIB /opt/microsoft/msodbcsql18/lib64 ODBCHOME ${SQLSERVER_LIB} ODBCSYSINI ${SQLSERVER_LIB} ODBCINSTINI odbcinst.ini GENEOS_MSSQL_DRIVER 'ODBC Driver 18 for SQL Server' LD_LIBRARY_PATH <Existing path>:${SQLSERVER_LIB} -
Add the variables and their corresponding values:
export SQLSERVER_LIB=/opt/microsoft/msodbcsql18/lib64
export ODBCHOME=${SQLSERVER_LIB}
export ODBCSYSINI=${SQLSERVER_LIB}
export ODBCINSTINI=odbcinst.ini
export GENEOS_MSSQL_DRIVER='ODBC Driver 18 for SQL Server'
The SQLSERVERLIB contains the path of the MS SQL Server client library file – libmsodbcsql-18.2.so.1.1
.
- Add the SQLSERVER_LIB in the LD_LIBRARY_PATH variable:
export LD_LIBRARY_PATH=${NP_LIB}:${SQLSERVER_LIB}
- Save the changes to the start script.
- Exit the editor.
- Restart the Netprobe.
Success
You have successfully defined the database variables and their values in the Netprobe start script. Go to the Gateway Setup Editor to Connect to an SQL Server database in SQL Toolkit configuration.
Windows Copied
Windows Server 2019 Copied
- Verify if the Microsoft OLE DB Driver is installed in your system. To check, the
msoledbsql.dll
ormsoledbsql19.dll
, andmsoledbsqlr.rll
should be in%SYSTEMROOT%\system32\
. - If the OLD DB Driver does not exist, then download and install the OLE DB Driver from Microsoft’s website.
- After installing the driver, restart the Netprobe.
Success
You have successfully defined the database variables and their values in the Netprobe start script. Go to the Gateway Setup Editor to Connect to an SQL Server database in SQL Toolkit configuration.
Windows Server 2018 and older Copied
Note
You may use either the OLE DB Driver or the Microsoft SQL Server Native Client for Windows Server 2018 and older.
- Verify if the Microsoft SQL Server Native Client is installed in your system. To check, the
sqlncli*.dll
should be in%SYSTEMROOT%\System32
or%SYSTEMROOT%\SysWOW64
. - If the Microsoft SQL Server Native Client does not exist, then download and install the Microsoft SQL Server Native Client from Microsoft’s website.
- After installing the client, restart the Netprobe.
Success
You have successfully defined the database variables and their values in the Netprobe start script. Go to the Gateway Setup Editor to Connect to an SQL Server database in SQL Toolkit configuration.
AIX Copied
Microsoft does not currently provide AIX drivers which allow connecting to MS SQL Server running on Windows.
Solaris Copied
Microsoft does not currently provide Solaris drivers which allow connecting to MS SQL Server running on Windows.
Oracle database Copied
Linux Copied
- Locate the Oracle library file -
libclntsh.so
. Below is an example that shows you where to locate the Oracle library file:
[root@pabo lib]# pwd
/usr/lib/oracle/21/client64/lib
[root@pabo lib]# ls -l libclntsh*
lrwxrwxrwx. 1 oracle oinstall 12 Aug 9 22:27 libclntsh.so.10.1 -> libclntsh.so
lrwxrwxrwx. 1 oracle oinstall 12 Aug 9 22:27 libclntsh.so.11.1 -> libclntsh.so
-rwxr-xr-x. 1 oracle oinstall 58804016 Aug 9 22:28 libclntsh.so.12.1
[root@pabo lib]#
- Locate the
tnsnames.ora
file. Below is an example of script that shows you thetnsnames.ora
file:
[root@pabo admin]# pwd
/usr/lib/oracle/21/client64/network/admin
[root@pabo admin]# ls -l
total 20
-rw-r--r--. 1 oracle oinstall 350 Aug 9 22:29 listener.ora
drwxr-xr-x. 2 oracle oinstall 4096 Aug 9 22:24 samples
-rw-r--r--. 1 oracle oinstall 373 Oct 31 2013 shrept.lst
-rw-r--r--. 1 oracle oinstall 195 Aug 9 22:29 sqlnet.ora
-rw-r--r--. 1 oracle oinstall 359 Aug 9 22:34 tnsnames.ora
-
Add these variables to the Netprobe start script using a text editor. Refer to the table below:
Variable Value ORACLE_HOME /usr/lib/oracle/21/client64 TNS_ADMIN /usr/lib/oracle/21/client64/network/admin ORACLE_LIB /usr/lib/oracle/21/client64/lib LD_LIBRARY_PATH <Existing path>:${ORACLE_LIB} -
Add the ORACLE_HOME variable.
-
Enter the path of the lib folder that contains the
libclntsh.so
file in the ORACLE_HOME variable. -
Export the ORACLE_HOME variable:
export ORACLE_HOME=/usr/lib/oracle/21/client64
- Add the TNS_ADMIN variable.
- Export the TNS_ADMIN variable. For example:
export TNS_ADMIN=/usr/lib/oracle/21/client64/network/admin
- Add the ORACLE_LIB variable.
- Enter the path of the folder which contains the
libclntsh.so
file in the ORACLE_LIB variable. - Export the ORACLE_LIB variable:
export ORACLE_LIB=/usr/lib/oracle/21/client64/lib
- Add the variables ORACLE_LIB in the LD_LIBRARY_PATH variable:
export LD_LIBRARY_PATH=${NP_LIB}:${ORACLE_LIB}
- Exit the editor.
- Restart the Netprobe.
Success
You have successfully defined the database variables and their values in the Netprobe start script. Go to the Gateway Setup Editor to Connect to an Oracle database in SQL Toolkit configuration.
Windows Copied
-
Locate the Oracle client library file -
oci.dll
. -
Locate the
tnsnames.ora
file. -
Add the Path system variable of the Windows host:
Variable Value Path <Existing path>;C:\database_libs\oracle\lib ORACLE_HOME C:\database_libs\oracle
Note: The ORACLE_HOME variable should be set one directory higher where the
oci.dll
library file is located.TNS_ADMIN C:\database_libs\oracle -
Click Start on your computer.
-
Right-click Computer, and click Properties.
-
Click Advanced system settings.
-
Click Environment Variables.
-
Click the Path system variable.
-
Click Edit… to append the path to oci.dll file.
-
Click OK to save the changes in the Edit System Variable screen.
-
Add the ORACLE_HOME system variable in the Windows host.
- Click New… in the System variables group.
- Enter the ORACLE_HOME in the Variable name field.
- Enter the path of the
oci.dll
file in the Variable value field. - Click OK to save the changes in the New System Variable screen.
- Click OK to save the changes in the Environment Variables screen.
-
Add the TNS_ADMIN system variable in the Windows host.
- Click New… in the System variables group.
- Enter the TNS_ADMIN in the Variable name field.
- Enter the path of the oci.dll file in the Variable value field.
- Click OK to save the changes in the New System Variable screen.
- Click OK to save the changes in the Environment Variables screen.
Note
You have successfully defined the path variables of the Windows host. Go to the Gateway Setup Editor to Connect to an Oracle database in SQL Toolkit configuration.
AIX Copied
Export the following variables:
export ORACLE_HOME=/usr/local/oracle/instantclient_19_3_ppc64
export TNS_ADMIN=/usr/local/oracle/instantclient_19_3_ppc64
export LIBPATH=$ORACLE_HOME:$LIBPATH
Setting up Oracle connection with Kerberos authentication Copied
This section provides a configuration guide for setting up the Oracle connection with Kerberos authentication, enabling connectivity between SQL Toolkit and Gateway Database Logging.
Preparing the Active Directory Server Copied
To prepare the Active Directory server, do the following:
- Create a service account in the Active Directory for the database server to validate the Kerberos tickets. This user does not need any specific rights but enable password never expires.
- Ensure that you deselect the account option Use Kerberos DES Encryption types for this account and select the option Do not require Kerberos preauthentication for this user.
- Make sure that the SPN is set to the correct realm. For example:
setspn -A <oracle_service_name>/<key_distribution_center>@<domain> <user>
- Extract the keytab file for this designated user, so that we can create tickets without inputting a password. To do this, use the following command:
ktpass -princ <oracle_service_name>/<key_distribution_center>@<domain> -crypto all -pass <password> -mapuser <user>@<domain> -out v5srvtab
- Copy the file in the database server and store it in the
/etc/v5srvtab
directory.
Setting up the Oracle Server Copied
- Generate a Kerberos ticket, which will be used to connect to the Kerberos server for ticket validation. To do this:
$ORACLE_HOME/bin/okinit -k -t /etc/v5srvtab <oracle_service_name>/<key_distribution_center>
- Update the following files:
sqlnet.ora
# sqlnet.ora Network Configuration File: /opt/oracle/homes/OraDBHome21cEE/network/admin/sqlnet.ora
# Generated by Oracle configuration tools.
# Debug/Tace logs can be removed
SQLNET.AUTHENTICATION_SERVICES= (BEQ, KERBEROS5)
TRACE_LEVEL_SERVER = ADMIN
SQLNET.KERBEROS5_CLOCKSKEW = 6000
SQLNET.KERBEROS5_CONF = /etc/krb5.conf
SQLNET.KERBEROS5_CONF_MIT = true
LOG_DIRECTORY_SERVER = /opt/oracle/logging
DIAG_ADR_ENABLED = OFF
SQLNET.KERBEROS5_KEYTAB=/etc/v5srvtab
SQLNET.AUTHENTICATION_KERBEROS5_SERVICE = oracle
tnsnames.ora
# tnsnames.ora Network Configuration File: /opt/oracle/homes/OraDBHome21cEE/network/admin/tnsnames.ora
# Generated by Oracle configuration tools.
ORCLPDB1=
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = kskdc.qamnl.com)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = ORCLPDB1)
)
)
LISTENER_ORCLPDB1 =
(ADDRESS = (PROTOCOL = TCP)(HOST = kskdc.qamnl.com)(PORT = 1521))
/etc/krb5.conf
# Configuration snippets may be placed in this directory as well
includedir /etc/krb5.conf.d/
includedir /var/lib/sss/pubconf/krb5.include.d/
[logging]
default = FILE:/var/log/krb5libs.log
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmind.log
[libdefaults]
default_realm = QAMNL.COM
[realms]
QAMNL.COM = {
kdc = ksad2.qamnl.com
admin_server = ksad2.qamnl.com
default_domain = QAMNL.COM
}
[domain_realm]
qamnl.com = QAMNL.COM
.qamnl.com = QAMNL.COM
- Additional configurations can be included within the libdefaults section, such as:
- ticket_lifetime = 24h
- renew_lifetime = 7d
Setting up the Oracle Client Copied
- Update the following files:
sqlnet.ora
SQLNET.KERBEROS5_CONF = /etc/krb5.conf
SQLNET.KERBEROS5_CONF_MIT = true
ADR_BASE = /opt/oracle
SQLNET.AUTHENTICATION_SERVICES= (BEQ, TCPS, KERBEROS5)
TRACE_LEVEL_CLIENT = ADMIN
SQLNET.KERBEROS5_CLOCKSKEW = 6000
LOG_DIRECTORY_SERVER = /opt/oracle/logging
DIAG_ADR_ENABLED = OFF
SQLNET.AUTHENTICATION_KERBEROS5_SERVICE = oracle
tnsnames.ora
ORCLPDB1=
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = kskdc.qamnl.com)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = ORCLPDB1)
)
)
LISTENER_ORCLPDB1 =
(ADDRESS = (PROTOCOL = TCP)(HOST = kskdc.qamnl.com)(PORT = 1521))
/etc/krb5.conf
includedir /etc/krb5.conf.d/
includedir /var/lib/sss/pubconf/krb5.include.d/
[logging]
default = FILE:/var/log/krb5libs.log
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmind.log
[libdefaults]
default_realm = QAMNL.COM
[realms]
QAMNL.COM = {
kdc = ksad2.qamnl.com
admin_server = ksad2.qamnl.com
default_domain = QAMNL.COM
}
[domain_realm]
qamnl.com = QAMNL.COM
.qamnl.com = QAMNL.COM
- Additional configurations can be included within the libdefaults section, such as:
- ticket_lifetime = 24h
- renew_lifetime = 7d
Troubleshooting Oracle with Kerberos authentication errors Copied
ERROR: SQL-TOOLKIT[sql] Fail - ORA-12638
: Credential retrieval failed
- Regenerate Kerberos Ticket on Oracle Server using the command:
$ORACLE_HOME/bin/okinit -k -t /etc/v5srvtab <oracle_service_name>/<key_distribution_center>
- Obtain a Kerberos ticket-granting ticket (TGT) using
kinit
on Oracle Clients
ERROR: SQL-TOOLKIT[sql] Fail - ORA-12641
: Authentication service failed to initialize
- Obtain a Kerberos ticket-granting ticket (TGT) using
kinit
on Oracle Clients - Verify KRB5CCNAME environment variable does not point to a null credential cache, better to unset.
- Once TGT has been issued, copy the credential cache to the current gateway working directory as geneos_krb5
ERROR: SQL-TOOLKIT[sql] Fail - OCIEnvNlsCreate != OCI_SUCCESS(6)
- Verify
ORACLE_HOME
environment variable has been exported with the correct path
PostgreSQL database Copied
Netprobe requires the PostgreSQL client libraries to communicate with the PostgreSQL database server. The path to these client libraries should be included in the machine’s path environment variable.
Note
- PostgreSQL is not supported in IBM AIX platforms.
- PostgreSQL connections configured with SSL or TLS are not supported in SUSE 12 platforms.
Linux Copied
- Locate the PostgreSQL client library file -
libpq.so
. Below is an example that shows you where to locate the PostgreSQL client library file:
[root@pabo admin]# pwd
/usr/lib/postgresql/14/lib
[root@pabo admin]# ls -l
total 10928
-rw-r--r-- 1 500 sandbox 17120 Mar 23 2015 libcom_err.so.3
-r-xr-xr-x 1 500 sandbox 2135635 Mar 23 2015 libcrypto.so.1.0.0
-rw-r--r-- 1 500 sandbox 152714 Mar 23 2015 libecpg.a
-rw-r--r-- 1 500 sandbox 18852 Mar 23 2015 libecpg_compat.a
-rwxr-xr-x 1 500 sandbox 23327 Mar 23 2015 libecpg_compat.so.3.6
lrwxrwxrwx 1 500 sandbox 14 Apr 11 2017 libecpg.so -> libecpg.so.6.6
-rwxr-xr-x 1 500 sandbox 254702 Mar 23 2015 libedit.so.0
-rw-r--r-- 1 500 sandbox 415515 Mar 23 2015 libgssapi_krb5.so.
drwxrwxr-x 2 500 sandbox 4096 Mar 23 2015 pkgconfig
drwxrwxr-x 3 500 sandbox 4096 Mar 23 2015 postgresql
-
Add and export the following variables in the Netprobe start script:
Variable Value POSTGRES_LIB /usr/lib/postgresql/14/lib LD_LIBRARY_PATH <Existing path>:${POSTGRES_LIB} -
Save the changes done to the start script.
-
Exit the text editor.
-
Restart the Netprobe.
Success
You have successfully defined the database variables and their values in the Netprobe start script. Go to the Gateway Setup Editor to Connect to a PostgreSQL database in SQL Toolkit configuration.
Windows Copied
- Modify the Path system variable of the Windows host.
existing path; C:\Program Files\PostgreSQL\psqlODBC\bin
- Locate the PostgreSQL client library file -
libpq.dll
. Below is an example of script that shows you the PostgreSQL file:
C:\Program Files\PostgreSQL\psqlODBC\bin>dir
Volume in drive C has no label.
Volume Serial Number is 1846-3FFA
Directory of C:\Program Files\PostgreSQL\psqlODBC\bin
04/11/2017 06:43 PM DIR. .
04/11/2017 06:43 PM DIR..
03/17/2017 02:15 PM 31,232 capi.dll
03/17/2017 02:15 PM 1,659,904 libeay32.dll
03/17/2017 02:15 PM 1,690,490 libiconv-2.dll
11 File(s) 5,591,085 bytes
2 Dir(s) 3,842,527,232 bytes free
C:\Program Files\PostgreSQL\psqlODBC\bin
- Click Start on your computer.
- Right-click Computer, and click Properties.
- Click Advanced system settings.
- Click Environment Variables.
- Click the Path system variable.
- Click Edit… to append the path of the
libmysql.dll
file. - Click OK to save the changes in the Edit System Variable screen.
- Click OK to save the changes in the Environment Variables screen.
Note
You have successfully defined the path variables of the Windows host. Go to the Gateway Setup Editor to Connect to a PostgreSQL database in SQL Toolkit configuration.
Solaris Copied
-
Locate the PostgreSQL client library file -
libpq.so
. -
Add and export the following variables in the start script:
Variable Value POSTGRES_LIB /usr/postgres/9.4-pgdg/lib LD_LIBRARY_PATH <Existing path>:${POSTGRES_LIB} -
Save the changes done to the start script.
-
Exit the text editor.
-
Restart the Netprobe.
Note
You have successfully defined the database variables and their values in the Netprobe start script. Go to the Gateway Setup Editor.
Sybase ASE (SAP ASE) database Copied
The plugin behaviour depends on the Sybase client library referenced in these environment variables. If wide table and columns are used, Sybase client library must met the version supported by Geneos.
Linux Copied
- Locate the Sybase client library file –
libsybintl_r64.so
. Below is an example that shows you where to locate the Sybase client library file:
[root@pabo]# pwd
/opt/database_clients/sybase/OCS-15_0/lib
[root@pabo]# ls -l
total 25720
-rwxr-xr-x 1 root root 219202 Dec 8 2011 libsybblk64.a
-rwxr-xr-x 1 root root 136044 Dec 8 2011 libsybblk64.so
-rwxr-xr-x 1 root root 219564 Dec 8 2011 libsybblk_r64.a
-rwxr-xr-x 1 root root 83511 Dec 8 2011 libsybcs.so
-rwxr-xr-x 1 root root 1220366 Dec 8 2011 libsybct64.a
-rwxr-xr-x 1 root root 56235 Dec 8 2011 libsybdldap64.so.15.7.0.1
-rwxr-xr-x 1 root root 50541 Dec 8 2011 libsybdldap.so.15.7.0.1
-rwxr-xr-x 1 root root 865832 Dec 8 2011 libsybfssl64.so.15.7.0.1
- Locate the Sybase
lib3p64
folder. For example:
[root@pabo OCS-15_0]# pwd
/opt/database_clients/sybase/OCS-15_0
[root@pabo OCS-15_0]# ls -l
total 2900
drwxr-xr-x 2 root root 4096 Jun 3 2014 bin
drwxr-xr-x 2 root root 4096 Nov 4 2016 config
drwxr-xr-x 2 root root 4096 Sep 4 2013 devlib
drwxr-xr-x 3 root root 4096 Jul 3 16:29 lib3p64
drwxr-xr-x 5 root root 4096 Sep 4 2013 sample
drwxr-xr-x 2 root root 4096 Sep 4 2013 scripts
drwxr-xr-x 3 root root 4096 May 28 2014 sybhelp
drwxr-xr-x 2 root root 4096 Sep 4 2013 xappdefaults
- Locate the Sybase interfaces file. For example:
[root@pabo sybase]# pwd
/opt/database_clients/sybase
[root@pabo sybase]# ls -l
total 68
drwxr-xr-x 8 root root 4096 Jun 9 00:30 backup
drwxr-xr-x 59 root root 4096 Sep 4 2013 charsets
-rwxr-xr-x 1 root root 567 Sep 4 2013 SYBASE.env
drwxr-xr-x 2 root root 4096 Sep 4 2013 Sybase_Install_Registry
-rwxr-xr-x 1 root root 841 Sep 4 2013 SYBASE.sh
-rwxr-xr-x 1 508 515 1212 Jul 23 2014 sybinit.err
drwxr-xr-x 4 root root 4096 Sep 4 2013 sybuninstall
This database uses the libraries that comes with the SAP ASE database. Add the following variables in the Netprobe start script:
Variable | Value |
---|---|
SYBASE | /path/to/sybase/home |
SYBASE_LIB | /path/to/sybase/lib |
SYBASE_LIB3P64 | /path/to/sybase/lib3p64 |
LD_LIBRARY_PATH | <Existing path>:${SYBASE_LIB}:${SYBASE_LIB3P64} |
- Add the SYBASE variable.
- Enter the path of the folder which contains the interfaces file in the SYBASE variable.
- Export the SYBASE variable:
export SYBASE=/opt/database_clients/Sybase
- Add the SYBASE_LIB variable.
- Enter the path of the folder which contains the
libsybintl_r64.so
file in the SYBASE_LIB variable. - Export the SYBASE_LIB variable:
export SYBASE_LIB=/opt/database_clients/sybase/OCS-15_0/lib
- Add the SYBASE_LIB3P64 variable.
- Enter the path of the
lib3p64
folder in the SYBASE_LIB3P64 variable:
export LD_LIBRARY_PATH=${NP_LIB}:${SYBASE_LIB}:${SYBASE_LIB3P64}
- Add the SYBASE_LIB and SYBASE_LIB3P64 variables into the LD_LIBRARY_PATH variable:
- Save the changes done to the start script.
- Exit the text editor.
- Add the following to
/opt/sap/locale/locales.dat
.
locale = en_UK, us_english, iso_1
- Add the following to the interface file.
GENEOSDB_AWS
master tcp ether ec2-52-62-125-137.ap-southeast-2.compute.amazonaws.com 5000
query tcp ether ec2-52-62-125-137.ap-southeast-2.compute.amazonaws.com 5000
- Run the following command:
source /opt/sap/./SYBASE.sh
- Restart the Netprobe.
Success
You have successfully defined the database variables and their values in the Netprobe start script. Go to the Gateway Setup Editor to Connect to a Sybase database in SQL Toolkit configuration.
Windows Copied
-
Configure the Windows environment and Sybase client.
-
Locate the Sybase
lib3p64
folder. -
Locate the Sybase interfaces file,
sql.ini
. -
Modify the Path system variable of the Windows host.
-
Click Start on your computer.
-
Right-click Computer, and click Properties.
-
Click Advanced system settings.
-
Click Environment Variables.
-
Click the Path system variable.
-
Click Edit… to append the path to
libsybct64.dll
andlib3p64
file. -
Click OK to save the changes in the Edit System Variable screen.
-
Click OK to save the changes in the Environment Variables screen.
-
Add the SYBASE system variable in the Windowshost.
- Click New… in the System variables group.
- Enter the SYBASE name in the Variable name field.
- Enter the path of the folder where the
ini
folder is located in the Variable value field. - Click OK to save the changes in the New System Variable screen.
- Click OK to save the changes in the Environment Variables screen.
-
Restart the Netprobe.
Success
You have successfully defined the path variables of the Windows host. Go to the Gateway Setup Editor to Connect to a Sybase database in SQL Toolkit configuration.
AIX Copied
export SYBASE=/opt/sybase
export SYBASE_LIB=/opt/sybase/OCS-15_0/lib
export SYBASE_LIB3P64=/opt/sybase/OCS-15_0/lib3p64
export LIBPPATH=$SYBASE_LIB:$SYBASE_LIB3P64:$LIBPATH
Configure Sybase using OCS Copied
Linux Copied
- In the Netprobe start script, add the variable SYBASE_OCS. The value must be
OCS_<ocs version>
.
export SYBASE_OCS=OCS-15_0
- Export the SYBASE_OCS variable.
- Save the script.
- Add the following to
/opt/sap/locale/locales.dat
.
locale = en_UK, us_english, iso_1
- Add the following to the interface file.
GENEOSDB_AWS
master tcp ether ec2-52-62-125-137.ap-southeast-2.compute.amazonaws.com 5000
query tcp ether ec2-52-62-125-137.ap-southeast-2.compute.amazonaws.com 5000
- Run the following command:
source /opt/sap/./SYBASE.sh
- Restart the Netprobe.
Windows Copied
-
Configure the Windows environment.
-
Add the SYBASE system variable in the Windows host.
-
Click Start on your computer.
-
Right-click Computer, and then click Properties.
-
Click Advanced system settings.
-
Click Environment Variables.
-
Click New… in the System variables group.
-
Enter the SYBASE_OCS in the Variable name field.
-
Enter the OCS version in the Variable value field.
-
Click OK to save the changes in the New System Variable screen.
-
Click OK to save the changes in the Environment Variables screen.
-
Restart the Netprobe.
-
Modify the Application Name setting in your SQL Toolkit sampler.
Field Description SYBASE_OCS Containing the OCS_* folder name. Example: SYBASE_OCS=OCS-15_0ocs.cfg Includes the desired Netprobe application name in the file. Example: [Netprobe] CS_SEC_ENCRYPTION = CS_TRUEApplication Name Same value defined in the ocs.cfg file.
The runtime configuration file ocs.cfg
is used by Client-Library applications to set the following:
- Property values
- Server option values
- Server capabilities
- Debugging options
By using ocs.cfg
, applications eliminate the need to call the routines to set the values.
This allows you to change the application settings without recompiling the code.
Note
By default, Client-Library does not read theocs.cfg
. However, all Client-Library based applications attempt to read the file if the file name exists in$SYBASE/$SYBASE_OCS/config
.
The application must set the properties to enable Client-Library to use this file.
IBM Db2 database Copied
Linux Copied
- Locate the client library file -
libdb2.so
. Below is an example of an IBM Db2 Data server file:
$ cd DB2LIB is located at /opt/ibm/db2/V11.5/lib64
$ ls -l libdb2.so*
lrwxrwxrwx. 1 root root 12 Jun 11 2019 libdb2.so -> libdb2.so.1
-r-xr-xr-x. 1 bin bin 42566992 Jun 11 2019 libdb2.so.1
- Locate the home directory of the Db2 Data Server Client instance created to connect to the target Db2 database:
$ cd /home/db2inst1/sqllib/
$ ls -l
total 120
drwxr-sr-x. 2 db2inst1 db2iadm1 4096 Apr 25 21:40 adm
drwxr-s---. 2 db2inst1 db2iadm1 4096 Apr 25 21:40 backup
lrwxrwxrwx. 1 root db2iadm1 31 Apr 25 21:40 bin -> /opt/lib/database/db2/V10.5/bin
/opt/lib/database/db2/V10.5/conv
drwxrwsr-t. 2 db2inst1 db2iadm1 4096 Apr 25 21:40 ctrl
drwxrwsr-t. 2 db2inst1 db2iadm1 4096 Apr 25 21:40 ctrlha
-rwxr-xr-x. 1 db2inst1 db2iadm1 12147 Apr 25 21:40 db2cshrc
drwxrwsrwt. 2 db2inst1 db2iadm1 4096 Apr 25 21:40 db2dump
-rwxr-xr-x. 1 db2inst1 db2iadm1 7962 Apr 26 00:50 db2profile
Note
The instance name will be the value of the variable DB2INSTANCE. The path will be the value of the variable DB2DIR.
-
Add and export the following variables in the Netprobe start script:
Variable Value DB2Instance export DB2INSTANCE=db2inst1 DB2DIR export DB2DIR=/home/${DB2INSTANCE}/sqllib DB2LIB export DB2LIB=${DB_CLIENT_HOME}/db2/V10.5/lib64 LD_LIBRARY_PATH export LD_LIBRARY_PATH=${DB2LIB} -
Save the changes done to the start script.
-
Exit the text editor.
-
Run the following command:
source /home/db2inst1/sqllib/db2profile
- Restart the Netprobe.
Note
You have successfully defined the database variables and their values in the Netprobe start script. Go to the Gateway Setup Editor toConnect to a Db2 database in SQL Toolkit configuration.
Windows Copied
- Locate the client library file -
db2cli64.dll
:
C: >cd C:\database_libs\db2\SQLLIB\lib
C:>dir
Volume in drive C has no label.
Volume Serial Number is 1846-3FFA
Directory of C:\database_libs\db2\SQLLIB\lib
04/26/2018 05:31 PM DIR .
04/26/2018 05:31 PM DIR ..
05/30/2013 12:13 AM 634,362 db2api.lib
05/30/2013 12:13 AM 2,546 db2apie.lib
05/30/2013 12:13 AM 4,964 db2psmd.lib
04/26/2018 05:31 PM DIR Win32
6 File(s) 835,144 bytes
3 Dir(s) 5,418,590,208 bytes free
- Modify the Path variable of the Windows host.
- Edit the Path system variable in the Environment Variables.
- Click Edit... to append the path of the
db2cli64.dll
file. - Click OK to save the changes in the New System Variable screen.
- Click OK to save the changes in the Environment Variables screen.
Note
If your database is already attached to a node, then you need to uncatalog them in order to successfully connect to the DB server by running the following:
db2 uncatalog database <database name> db2 uncatalog database <node name>
For example:
db2 uncatalog database SAMPLE db2 uncatalog database DB2INST1
Success
You have successfully defined the path variables of the Windows host. Go to the Gateway Setup Editor to Connect to a Db2 database in SQL Toolkit configuration.
AIX Copied
If you wish to run the Netprobe on a different machine to that on which the Db2 server is running, then you would need to download and install the Db2 Client package from IBM’s website. You should then follow the instructions in the “Quick Beginnings for DB2 Clients” document to set-up communications between the client and the server. This document can be found on IBM’s website. Finally, you would need to configure the Netprobe environment, so that the client libraries are available to it.
export DB2LIB=/opt/db2/V11.5/lib64
export LIBPATH=$DB2LIB:$LIBPATH
Solaris Copied
If you wish to run the Netprobe on a different machine to that on which the Db2 server is running, then you would need to download and install the Db2 Client package from IBM’s website. You should then follow the instructions in the “Quick Beginnings for DB2 Clients” document to set-up communications between the client and the server. This document can be found on IBM’s website. Finally, you would need to configure the Netprobe environment, so that the client libraries are available to it.
setenv LD_LIBRARY_PATH /opt/IBM/db2/V9.7/lib32
Configure the SQL Toolkit sampler Copied
For more information on plugin configuration, see SQL Toolkit configuration.
- Open your Gateway Setup Editor
- Go to Samplers > New Sampler to create a new sampler.
- Input a name for your new sampler.
- Select
SQL Toolkit
in the Plugin dropdown list.
-
Select the database where you will connect the plugin to on the Database menu. For more information on the database configuration in your SQL toolkit sampler, see the following:
- Connect to a Db2 database in SQL Toolkit configuration
- Connect to a MySQL database in SQL Toolkit configuration
- Connect to an Oracle database in SQL Toolkit configuration
- Connect to a PostgreSQL database in SQL Toolkit configuration
- Connect to an SQL Server database in SQL Toolkit configuration
- Connect to a Sybase database in SQL Toolkit configuration
Note
The Database dropdown list displays all the supported databases regardless of their availability on the underlying system the Netprobe is running on. The Administrator must ensure that the appropriate database client libraries are correctly installed and configured before expecting the selected one to work. For more information, see Configure the Netprobe and database client libraries.
Adjust the maximum database connections Copied
The probe has a default value of 10
, which means that no more than ten simultaneous open connections can be made to all databases configured on the Netprobe.
Before the sampler configuration starts, you can limit the total number of database for each Netprobe. This limit is set to ensure the configured database plugins do not consume all available database sessions.
To configure the maxDatabaseConnections
in Netprobe:
-
In Gateway Setup Editor, open the host Netprobe where the SQL Toolkit is running.
-
Go to the Managed entities to verify the host Netprobe. This will resolve the following error:
Error: SQL-Toolkit Fail maximum connections have been exceeded (0)
. -
Click the Advanced tab in the Probe section.
-
Enter the desired number of connections in the Max database connections field.
This sets the maximum amount of connections that a Netprobe can make to any database. For example, if:
- One Managed Entity belonging to one Netprobe uses three SQL Toolkit plugins.
- One Sybase plugin and one Oracle plugin.
- Two Managed Entities belonging to one Netprobe uses the same SQL Toolkit plugin.
This setup uses ten database connections in total. If the Netprobe has the default value of 10
, then there is no additional database connections can be made.
Set SQL Toolkit DB authentication Copied
To require authentication when configuring the database connection, set your username and password:
- Enter your credentials in the Connection > User Name and Connection > Password fields.
- Select AES 256 bit Encryption on the Password menu to set an encrypted password.
- Confirm the password, and click OK.
Manage unsupported data types Copied
SQL Toolkit plugin does not support the following data types:
SA_dtUnknown
— UnknownSA_dtInterval
— Interval (MySQL specific)SA_dtLongBinary
— Long binary dataSA_dtBLob
— BLob dataSA_dtCLob
— CLob dataSA_dtCursor
— Oracle REF CURSORSA_dtSpecificToDBMS
— server-specific and not interpreted by SQLAPI++
If you use any of these data types to execute database queries, Active Console will unable to display the queries correctly:
In the example above, the COL2
column contains a clob
data type in Oracle database. To manage queries that return unsupported data types in SQL Toolkit, you may rewrite the query with SQL functions that convert the data to readable formats. For example:
-
You can use the
cast
andsubstr
functions for conversion. Thesubstr
function is use to reduce the output to1000
characters if the source data is huge. -
Configure the SQL query in the sampler:
SELECT col1, cast(substr(col2,1,1000) as varchar(1000)) AS col2 FROM clob_table
Success
Active Console now displays the dataview with the readable formats.
Interval data type Copied
SQL Toolkit plugin does not support the Interval
data type specific to MySQL and Oracle databases. Active Console might display the following error messages:
- MySQL database —
unsupported::interval
. - Oracle —
ORA-01406: fetched column value was truncated
. If you encounter this problem, you may update to newer version of Netprobe.