Linux-UNIX: General parameters

These parameters define basic properties of the S-TAP running on a database server and the server on which it is installed, and do not fall into any of the other categories.

These parameters are stored in the [TAP] section of the S-TAP properties file.DB2_SHMEM_DRIVER_INSTALLED
Table 1. S-TAP configuration parameters in the [TAP] section
GUI GIM guard_tap.ini Default value Description
  tap_type   The type of installed S-TAP agent:
  • stap=UNIX
  • ztap=Z/OS
Version tap_version   Read only. The S-TAP® version that is installed on the DB server, added to the file during installation or upgrade only.
S-TAP Host STAP_TAP_IP tap_ip   Read only. IP address or hostname for the database server system on which S-TAP is installed.
Force server IP   force_server_ip 0 Forces the reported server IP of database to be the value stored in tap_ip. Valid values:
  • 0: Disabled
  • 1: Enabled
Private tap IP private_tap_ip   If this parameter is defined, the database uses it for the S-TAP communication. (Relevant when the S-TAP is deployed in a private network; the external, public IP address of the S-TAP is defined by tap_ip. See Linux-UNIX: Configure a public and private address for an S-TAP.
Devices STAP_DEVICES devices none Which interfaces to listen on. Use ifconfig to find the correct interface.
All can control STAP_ALL_CAN_CONTROL all_can_control 0 Defines which Guardium system control this S-TAP. Valid values:
  • 0: S-TAP is controlled by the primary Guardium system only.
  • 1: S-TAP can be controlled by any Guardium system.
Load balancing STAP_PARTICIPATE_IN_LOAD_BALANCING participate_in_load_balancing 0  
initial_balancer_tap_group   The S-TAP group name to associate with this S-TAP (by the central manager load balancer) when installing an S-TAP. The group name is sent with each request.
initial_balancer_mu_group   The managed unit group name to associate with this S-TAP (by the central manager load balancer) when installing an S-TAP. The group name is sent with each request.
external_load_balancing 1 To use an S-TAP with Guardium Insights, this parameter must be set to 1, which sets load balancing for the Guardium Insights connections.
TENANT_ID tenant_id   To use an S-TAP with Guardium Insights, the Guardium Insights tenant ID is required, including the TNT_ prefix. For example:
tenant_id=TNT_N5YBRAPBWRYAPFLQWABCDE
  STAP_CONNECTION_TIMEOUT_SEC connection_timeout_sec 10 Number of seconds after which the S-TAP considers a Guardium server to be unavailable. It can have any integer value. Can be set when pushing to a group of DB servers via GIM.
  STAP_USE_EXIT_DB_TYPE use_exit_db_type 0 Allows database auto-discovery to discover any databases that have Exit protocols and add those instances to Discovered Instances report.
Valid values:
  • 0: Do not autodiscover databases that have Exit protocols.
  • 1: Discover databases that have Exit protocols. For more information, see Using Exit discovery.
TLS Use STAP_USE_TLS use_tls 0
Use SSL to encrypt traffic between the S-TAP and the Guardium appliance. Valid values:
  • 0: Do not encrypt. The traffic between the agent and Guardium system is in clear text.
  • 1: Use SSL to encrypt traffic between the agent and the Guardium system. This adds ~15% of CPU usage to the sniffer's S-TAP server but does not affect the sniffer's other modules.

Guardium recommends encrypting network traffic between the S-TAP and the collector whenever possible: only in cases where the performance is a higher priority than security should this be disabled.

Can be set when pushing to a group of DB servers via GIM.
TLS Failover STAP_FAILOVER_TLS failover_tls 0 Deprecated in v10.5.
Wait for DB exec STAP_WAIT_FOR_DB_EXEC wait_for_db_exec 0 When S-TAP restarts, either from a system reboot or user initiated S-TAP stop / start commands, S-TAP polls all databases that have been configured to be monitored and begins monitoring all valid configurations. Any configuration anomalies (either on the database side or the S-TAP side) that limits S-TAP ability to monitor a database does not limit the S-TAP from monitoring other databases with valid configurations. This parameter determines the S-TAP response, and its status in the S-TAP Control page, if a DB instance is not available (db_install_dir or db_exec_file is not accessible) during IE validation, after an S-TAP or DB restart. Valid values:
  • 0 and less: S-TAP logs an event message with the event type CONF_ERROR when a DB instance is detected as unavailable for certain DB(PROTOCOL) during the S-TAP starting time. S-TAP also logs a CONF_ERROR if a DB changes its status from available to unavailable during the periodic check (every 15 minutes). These event messages change the S-TAP status in the GUI to yellow with the instruction to correct the parameter or set WAIT_FOR_DB_EXEC > 0. When a DB instance status changes from unavailable to available, a WARNING message is sent to the sniffer, but the GUI status does not change automatically. You need to click info icon to open the S-TAP event log and click Accept.
  • greater than 0: A WARNING is logged for any unavailable database during S-TAP startup time or during a periodic check. The time interval of the periodic check is the value of wait_for_db_exec, in minutes. A warning message is also sent when an unavailable DB instance becomes available. Since the periodic check needs to get status of the database file configured for each inspection engine, and it consumes the CPUs, the value should not be less than the number of inspection engines.
See Linux-UNIX: Configuring S-TAP in the S-TAP Control page for more details on the S-TAP Status page. Before setting this property to a positive value, be sure to set all other necessary configuration properties and test that the S-TAP starts and collects data correctly. This property can be modified using GIM GUI (STAP_WAIT_FOR_DB_EXEC), and the guard_tap.ini configuration file.
Dynamic ring buffers enable_dynamic_ring_buffers 0 Dynamically adds and removes S-TAP buffers for each main connection during peak traffic, to prevent an overflow in the S-TAP buffer. If S-TAP failover happens, data in all buffers is moved to the new buffers.

Valid values:

  • 0: Disabled
  • 1: Enabled
  STAP_RUN_AS_ROOT tap_run_as_root 1 Run S-TAP as user root or as user guardium. Valid values:
  • 0: Run as guardium user
  • 1: Run as root
In some cases you need to run the S-TAP as guardium (and not root). This can cause other issues and should only be used when necessary. Running S-TAP as the guardium user can cause a database or protocol to stop working because of permission levels. Verify that the database path or exec file gives the Guardium user read permission. Depending on your environment, typical limitations are:
  • wait_for_db_exec might not work. For cluster, check the database path or exec file for Guardium user read permission.
  • Database on AIX® WPAR and Solaris Zones may not work, check the permission to access the install path or exec file
  • For Oracle BEQ, restart S-TAP after starting or restarting the database.
  • For Informix® shared memory, restart S-TAP after starting or restarting the database.
  • For DB2 shared memory, if shmctl failed because of permission issue, then in most cases S-TAP should be changed to run as root.
    • If shared memory segment has read permission by group, then make sure the DB2 instance has been added to user (Guardium) group. But still on each server, only one set of configuration of DB2® can be supported.
    • If shared memory segment has read permission by db2 user only, then S-TAP has to run as root. (open a DB2 shared memory session, run command ipcs -ma, check MODE on the output)
Can be set when pushing to a group of DB servers via GIM.
  STAP_TAP_BUF_DIR tap_buf_dir NULL Location of S-TAP buffer file if S-TAP is using map file. Default location is $inidir/buffers

Can be set when pushing to a group of DB servers via GIM.
  STAP_TAP_LOG_DIR tap_log_dir NULL Location of S-TAP log files: guard_stap.stdout.tx, guard_stap.stderr.txt, guard_stap.fam.txt. By default, log files are written in /tmp.

Can be set when pushing to a group of DB servers via GIM.
Alternate ips STAP_ALTERNATE_IPS alternate_ips NULL Additional IP addresses for the database server system on which the S-TAP is installed. If there are no additional IP addresses, enter the property exactly as shown (with no values).
  tee_msg_buf_len 128  
  STAP_BUFFER_FILE_SIZE buffer_file_size 50 Advanced. Size in MB of the buffer allocated for the packets queue. If the buffer size is set too large, the S-TAP might not be able to start. Maximum size is 2000MB.
  STAP_BUFFER_MMAP_FILE buffer_mmap_file 0 How to map S-TAP and Guardium system communication buffer. Valid values:
  • 0: Use an anonymous file
  • 1: Use an mmap file
Can be set when pushing to a group of DB servers via GIM.
  STAP_BUF_MSG_TIME_INTERVAL buf_msg_time_interval 5 Interval, in minutes, to log S-TAP buffer overflow message. Can be set when pushing to a group of DB servers via GIM.
    buffer_percentage_for_priority_packet 1 Allows you to adjust the buffer percentage for priority packets. Increasing the value reserves more space for priority packets.

When Guardium reaches the buffer usage maximum (that is, 100% - buffer_percentage_for_priority_packet, non-priority packets are dropped to help ensure that priority packets get through.

The range is 1 (1%, the default) to 5 (5%).
Trace files dir tracefiles_dir   The directory in which access tracer files are stored.
Compres. Level STAP_COMPRESSION_LEVEL compression_level 0 Increase the compression level to lower the number of bytes between the S-TAP and the collector. Changing the compression level is recommended where latency is high between the data centers, to reduce travel time. Compression might impact performance on both ends (S-TAP and collector (sniffer)). The disk usage is not affected by compression. Valid values:
  • 0: No compression
  • 1: Best speed
  • 9: Highest compression
  STAP_MIN_BYTES_TO_COMPRESS min_bytes_to_compress 500 Advanced. Minimum number of bytes to compress when compression is enabled.

Can be set when pushing to a group of DB servers via GIM.
  STAP_TAP_MIN_HEARTBEAT_INTERVAL tap_min_heartbeat_interval 20 Maximum time the S-TAP attempts to write to the primary Guardium system buffer before attempting to write to the secondary Guardium buffer. Also see connection_timeout_sec for S-TAP failover to secondary collector. Should be greater than or equal to connection_timeout_sec

Can be set when pushing to a group of DB servers via GIM.
  STAP_MSG_AGGREGATE_TIMEOUT msg_aggregate_timeout 100 Time interval, in milliseconds, for K-TAP packets to aggregate before notifying S-TAP of ready data. Can be any integer value.

Can be set when pushing to a group of DB servers via GIM.
  STAP_MSG_COUNT_WATERMARK msg_count_watermark 64 Maximum number of KTAP packets to aggregate before notifying S-TAP of ready data. Can be any integer value.

Can be set when pushing to a group of DB servers via GIM.
  STAP_LOG_PROGRAM_NAME log_program_name 0 Controls sending source program name to the Guardium system. Valid values:
  • 0: Don't send source_program name.
  • 1: Send source_program name.
When enabled, can boost performance, but you can't tell which program name was using the connection (though all other connection information like user and client address are available).

Can be set when pushing to a group of DB servers via GIM.
  STAP_MAX_SERVER_WRITE_SIZE max_server_write_size 65536 The maximum number of bytes that the S-TAP sends to the Guardium system at once. Can be any integer value.

Can be set when pushing to a group of DB servers via GIM.
  guardium_ca_path NULL Location of the Certificate Authority certificate.
  sqlguard_cert_cn NULL The common name to expect from the Sqlguard certificate.
  guardium_crl_path NULL The path to the Certificate Revocation list file or directory.
  STAP_TAP_FAILOVER_SESSION_SIZE tap_failover_session_size 1024 The maximum number of entries in the session failover file per Guardium system. Valid values:
  • 0: Failover feature is disabled.
  • Positive integer: Number of retries

Can be set when pushing to a group of DB servers via GIM.
  STAP_TAP_FAILOVER_SESSION_QUIESCE tap_failover_session_quiesce 240 Time, in seconds, to keep failover session info after failover. After this time interval, unused sessions in the failover list from the previous active servers are removed from the current active server, including cleaning the sessions' policies and removing the sessions from the firewalled and scrubbed lists.

Can be set when pushing to a group of DB servers via GIM.
Kerberos plugin directory STAP_KERBEROS_PLUGIN_DIR kerberos_plugin_dir NULL The Kerberos plugin file location.
  STAP_DB_IGNORE_RESPONSE db_ignore_response NULL
Responses from the database include result sets, database exceptions (such as SQL errors), and failed login messages. If you do not need to monitor all responses, use this parameter to configure which DB types are response-ignored. db_ignore_response starts when the session traffic reaches the threshold db_ignore_response_bypass_bytes. Valid values:
  • none: No response is ignored
  • all: The responses from all DBs are ignored
  • Comma-separated list of DB types to be response-ignored, for example: MYSQL,DB2
Note: If using db_ignore_response=all to set the Oracle database response to be ignored (not captured to reduce traffic load), then be aware that more than just database server responses are involved. Database server responses can also contain important database protocol metadata information used by the application for following database requests interpretation. For example, Login Failed and SQL Exceptions.
  STAP_STATISTIC stap_statistic 0 Interval at which S-TAP sends statistic information about S-TAP/K-TAP to sniffer. Valid values:
  • Positive integer: Number of hours
  • Negative integer: Number of minutes
  • 0: Do not send
  stap_statistic_version 1 S-TAP statistics are version-specific to the collector. Valid values:
  • 0: Guardium V9
  • 1: Guardium V10 and higher
  STAP_UPLOAD_FEATURE upload_feature 1 Whether or not the S-TAP uploads snapshots and new K-TAP modules to the GIM server to which it reports. Valid values:
  • 0: Disabled
  • 1: Enabled for all (snapshots and K-TAP modules)
  • 2: Enabled for snapshot; disable for K-TAP modules
  STAP_UPLOAD_SNAPSHOTS upload_snapshots 1 Controls automatic upload of snapshots using the file upload mechanism. Valid values:
  • 0: Disabled
  • 1: Enabled
  add_to_verification schedule 0 Add the Inspection Engines defined in guard_tap.ini to the S-TAP Verification schedule. S-TAP verification tests traffic capture. Valid values:
  • 0: Disabled
  • 1: Enabled
  STAP_DB_IGNORE_BYPASS_BYTES db_ignore_response_bypass_bytes 4096 db_ignore_response starts when bypass bytes are reached. Relevent only if db_ignore_response is set to all, or is not set to none.
  STAP_DB_IGNORE_RESETS_PER_REQUEST db_ignore_response_resets_per_request 0 Specifies when the db_ignore_response restarts its counter. Valid values:
  • 0: The total length is counted for all client-to-server packets, starting with the first packet of the session.
  • 1: Count restarts after every client-to-server packet (reset per session).
  STAP_DB_IGNORE_RESPONSE_FILTER db_ignore_response_filter 0.0.0.0/0.0.0.0 Comma separated list of IP/MASKs to be response-ignored. By default it filters all TCP traffic. Any DB responses of the type specified by db_ignore_response to the specified IP/MASKs are ignored. Valid values:
  • 0: No filtering of responses occurs
  • 0.0.0.0/0.0.0.0: All IPs are filtered
  STAP_DB_IGNORE_RESPONSE_LOCAL db_ignore_response_local 1 Filtering of local DB responses. TCP traffic is not considered local traffic for this parameter. Valid values:
  • 0: Disabled
  • 1: Enabled
  debug_snapshot 0 Advanced. Collects a debug dump from a STAP. Should be triggered from the GUI (S-TAP Control > S-TAP commands). After triggering a dump from the GUI, the parameter reverts to its default of 0.
  debug_snapshot_level 1 Advanced. The value of tap_debug_output_level that is run for the debug dump. Valid values:
  • 1: Basic debug
  • 4: Verbose debug
  debug_snapshot_time 60 Advanced. The time interval, in seconds, for which the diagnostic runs. The value can be any integer value.
Restricted logging force_log_limited 0 Controls restricted logging on the collector. Use this to evaluate the number of records affected by an SQL command, while masking the actual query. This parameter can only be set by user root on the DB server. Valid values:
  • 0: Unrestricted.
  • 1: Log with masking. Only logins are allowed (sent packets are flagged with LOGALWAYSMASK). Forces encryption to be on in the S-TAP regardless of any other settings; traffic is sent to the collector only after the collector has indicated that it is aware of the parameter value. Otherwise, the S-TAP logs a message that traffic can't be sent, and its status is red in the S-TAP Control page.
  • 2: All packets are allowed (sent packets are flagged with LOGACCESSONLY)
  STAP_UID_CHAIN_TRAC hunter_trace 0 Turns on the collection of UID chains. When enabled, captures the UID but without IP in the string. Use this setting for local TCP/IP connections including Solaris zones and AIX WPARs, and remote TCP/IP connections when appserver_installed = 1. Valid values:
  • 0: Disabled
  • 1: Enabled
See more information in Linux-UNIX: UID chains. Can be set when pushing to a group of DB servers via GIM.
Load Balancer IP STAP_LOAD_BALANCER_IP load_balancer_ip   Required for enterprise load balancing. If blank, enterprise load balancing is disabled.
The IP address or hostname of the central manager or managed unit this S-TAP uses for load balancing.
Managed Units STAP_LOAD_BALANCER_NUM_MUS load_balancer_num_mus 1 The number of managed units the enterprise load balancer allocates for this S-TAP.
Load balancer node affinity STAP_LOAD_BALANCER_NODE_AFFINITY load_balancer_node_affinity   Whether the S-TAP connects to more than one managed unit, for enterprise load balancing. Some scenarios need all traffic to go to the same collector. With Oracle ATAP, for example, the analyzed client IP only shows if both the encrypted and unencrypted sessions go to the same managed unit. Valid values:
  • 0: Disabled. The S-TAP traffic goes to, at a maximum, the number of managed units specified by load_balancer_num_mus.
  • 1: Enabled. The S-TAP traffic goes to one managed unit, and has, at a maximum, the number of connections (to that managed unit) specified by load_balancer_num_mus.
See load_balancer_num_mus
  merge_with_template 0 Specifies whether the configuration from the collector is merged with the template config file when it is pushed to S-TAP. Valid values:
  • 0: Disabled (comments in guard_tap.ini are lost).
  • 1: Enabled (comments in guard_tap.ini are preserved).
  STAP_SHMID_BLACKLIST shmid_blacklist NULL Comma separated list of shared memory IDs, each one related to a particular process (owner). that the K-TAP filters.

Can only be set per Guardium system when updating using GIM.
  STAP_SHMID_BLACKLIST_WAIT shmid_blacklist_wait 0 Wait to activate interception until shmid_blacklist items are discovered. Valid values:
  • 0: Disabled
  • 1: Enabled
Can be set when pushing to a group of DB servers via GIM.
  STAP_BLACKLIST_SHMEM_OPS_BY_PROC blacklist_shmem_ops_by_proc NULL K-TAP filters the the shmem interception by this comma separated list of processes.

Can only be set per Guardium system when updating using GIM.
  fam_enable 1 Global enable/disable for FAM. Valid values:
  • 0: Disabled
  • 1: Enabled

FAM rules must be defined in order for FAM to run. If rules are not defined, enabling this parameter opens a connection to the Guardium system on port 16022 (or 16023 if using encryption), but FAM remains essentially disabled.
Include client IP in UID chain for SSH daemon STAP_UID_CHAIN_SSHD_IP uid_chain_sshd_ip 0 Add an SSH client IP:port pair to the UID chain when SSH is identified as one of the processes in the chain. Valid values:
  • 0: Disabled
  • 1: Enabled
See more information in Linux-UNIX: UID chains. Can be set when pushing to a group of DB servers via GIM.
Cassandra audit STAP_CASSANDRA_AUDIT_ENABLED cassandra_audit_enabled 0 Create file appender pipe for Cassandra/Datastax with native audit logging. Valid values:
  • 0: Disabled
  • 1: Enabled
Can be set when pushing to a group of DB servers via GIM.
Cassandra audit delimiter STAP_CASSANDRA_AUDIT_DELIMITER cassandra_audit_delimiter GUARD_DELIM Cassandra audit reader delimiter. Valid values:
  • Printable ASCII characters a-z A-Z 0-9 - _ ! @ # $ % ^ & * ( )
Can be set when pushing to a group of DB servers via GIM.
    exit_lib_num_threads   Hidden parameter. The number of shared memory segments created by the S-TAP. The number of requests for shared memory segments (from the exit library) is equal to the number of instances on the database. The value of this parameter should be equal to or greater than the number of database instances. The default is 10, the maximum is 20.