Linux-UNIX: Discover database instances

Enable S-TAP to periodically discover database instances and send the results to the current active S-TAP system.

The Guardium® Discovery Agent is a software agent that is automatically installed with the S-TAP package on a database server. The instance discovery agent reports database instances, listener, and port information to the Guardium system. Discovery does not find and report on every detail of the database instances on the server.

Auto-discovery is enabled by default during installation. It runs once daily. When discovery runs, it identifies the user modifications in the guard_tap.ini, and does not overwrite them with the discovered database details.

Guardium recommends that you leave the parameter values at their defaults. The parameters are described in Linux-UNIX: Discovery parameters.

Database types that are supported by S-TAP discovery are listed in the Guardium support matrix.

You can define rules to manage inspection engine creation on discovered databases. For more information, see Database discovered instances rules.

The discovery bundle is not installed in a worker zone or WPAR; the discovery agent that is running on the global zone collects information from other zones. Limitation: On Solaris zones architecture, when Db2 instances are running on worker zones, Discovery does not discover the Db2 shared memory parameters.

Newly discovered database instances can be seen in the Discovered Instances report. From this report, datasources and inspection engines can quickly be added to Guardium using the Actions menu.

If databases on the database server are not operational (started) or are added later, the Discovery Agent can still discover these instances. Go to Manage > Activity Monitoring > S-TAP Control, click Send command, and select Run Database Instance Discovery.

S-TAP Discovery can be run manually but this action is not suggested. The main reason to run it manually is for debugging purposes. If a new request comes in from the user interface while a scheduled discovery is running, the new request is ignored.

Note: Once you activate A-TAP, you no longer need to run the S-TAP Discovery instance as it is already replaced by A-TAP.
You can run Discovery from a local command line on the database server (/usr/local/guardium/guard_stap/guard_discovery) by using one of these flags:
  • --update-tap flag: edits the guard_tap.ini to add or update inspection engines
  • --send-to-sqlguard flag (or with no flag, which is the default): sends the found changes to the Guardium system, where they appear in the Discovered Instances report
  • --print-output flag: prints the found changes to stdout (for debugging)
If the S-TAP is running as "user" (and not guardium), the discovery functionality is limited. The following message displays: 
WARNING: Discovery is enabled and STAP is running as user guardium.
The discovery function is limited when STAP runs as user guardium.
Discovery is most effective when 'tap_run_as_root=1'
Note: To avoid an instance where S-TAP discovery does not open the Informix database, it is recommended to start Informix databases by using the full path to the executable.

Discovery also uses these parameters:

  • tap_ip: the S-TAP with which the database instance is associated.
  • sqlguard_ip: S-TAP discovery results are sent to this IP. (The Guardium system with primary=1 in the SQLguard parameters. )

Using Exit discovery

The Exit discovery feature allows database auto-discovery to discover any databases that have Exit protocols and add those instances to Discovered Instances report. By default, Exit discovery is disabled.

Guardium provides several ways to enable or disable Exit discovery.
  • From the S-TAP Configuration page in the Guardium GUI - Select or clear Use exit db type to enable or disable Exit discovery .
  • From GIM - To enable Exit discovery, set the STAP_USE_EXIT_DB_TYPE GIM parameter to 1. When STAP_USE_EXIT_DB_TYPE GIM is enabled, set KTAP_ENABLED=0 to disable KTAP.

    To disable Exit discovery, set STAP_USE_EXIT_DB_TYPE GIM=0 (the default).

  • By using the update_stap_config GuardAPI or REST API - For example, to enable Exit discovery for Informix, use the following command:
    grdapi update_stap_config stapHost=2.2.2.2 updateValue=TAP.USE_EXIT_DB_TYPE:1,TAP.DB_EXIT_LIST:Informix

Setting up Exit discovery:

  • When you install an S-TAP, you can set the STAP_USE_EXIT_DB_TYPE parameter to 1. In this case, K-TAP is disabled and Guardium discovers the Exit inspection engine and adds it to guard_tap.ini file as use_exit_db_type=1.
  • You can also update an existing S-TAP to use Exit discovery. Update the S-TAP configuration through the GIM GUI to set STAP_USE_EXIT_DB_TYPE to 1.
  • When STAP_USE_EXIT_DB_TYPE is set to 1, you can also set STAP_DB_EXIT_LIST to specify which database Exits to discover. For more information, see STAP_DB_EXIT_LIST in Linux-UNIX: General parameters.

You can also run discovery from the S-TAP control page in the UI, which updates the inspection engine immediately if the Replace Inspection Engines box is selected. For more information, see Linux-UNIX: Configuring S-TAP in the S-TAP Control page.

Note: When Exit discovery is on, you can monitor only databases that support Exit protocols.