Linux-UNIX: guardctl utility commands for A-TAP

The guardctl utility is the A-TAP management tool. Understand these commands before starting to work with A-TAPs.

guardctl utility

There are two methods of managing your A-TAPs: either as user root for all functions, or as a db user. The db user option can configure, activate, deactivate, and instrument A-TAP, but cannot perform all functions. This means that the non-root user can handle day to day activities of the A-TAP, without requiring the root user. The guardctl help window lists the permitted commands for the logged-in user. The functionality is:
  • When activating an A-TAP instance not as root, the current user must be the db_user specified in the instance configuration, and must be specified as the db_user for the matching inspection engine in the S-TAP configuration.
  • A non-root user cannot manage (configure, active, deactivate, and instrument) an A-TAP instance that was initially configured by the root user.
  • The root user can activate and deactivate a non-root created A-TAP instance, but must specify the instance name as ${DB_USER}/${DB_INSTANCE}
Authorizing the user is optional. If you have db_user specified in the guard_tap.ini, you don't need to authorize the user, but you still may. If db_user is not specified in the guard_tap.ini, you must authorize the user and cannot perform any actions as non-root with guardctl.

The guardctl utility is installed under <guardium_base>/guard_stap directory where <guardium_base> is the directory where Guardium® software is installed. In the case of a GIM installation guardctl it is installed under <guardium_base>/modules/ATAP/current/files/bin.

Syntax

<guardium_base>/xxx/guardctl [<parameter>=value>] [<parameter>=<value> ...] <command> [-q | -v | -qv]

See parameters in Linux-UNIX: Database-specific guardctl parameters.

Note: Hyphen and underscore are interchangeable in the guardctl parameters.

-q, -v, -qv flags

Use these flags to manage the output:
  • -q (quiet): suppress all output except name/value pairs
  • -v (value pairs): add name/value pairs related to each command
  • -qv: outputs name/value pairs only

The output depends on the type of command.

  • Commands that take action across all configured instances
    • Print all name/value pairs for each instance except overall_rv and overall_msg
    • Print overall_rv name/value pair at end where value is
      • 0 (success) if and only if all report success
      • 1 (failure) if any report any failure
    • Print overall_msg name/value pair at end
    • Returns the value reported in the “overall_rv” name/value pair
  • Commands that take action on a single instance
    • Print all name/value pairs except overall_rv and overall_msg
    • Returns the value reported in the “rv” name/value pair
  • Commands that store parameters, print parameters, or check status
    • Does not print name/value pairs
Name/Value pairs output looks like:
db_instance: ${db_instance}
db_user: ${db_user}
db_base: ${db_base}
db_home: ${db_base}
db_version: ${db_version}
db_type: ${db_type}
is_active: ${is_active} (“yes” or “no”)
is_instrumented: ${is_db_instrumented} (“yes” or “no”)
msg: some string
rv: ${retval}
overall_rv: ${retval} 
overall_msg: (string)

commands

Command Description
activate Activates A-TAP for the specified database instance using the stored parameters. Outputs Name/Value pairs if -v or -qv specified. Activating an instance that's already active (whether DB is running or not) does not generate an error.
authorize-user Adds the user to 'guardium' authorization group.
db_console_log Enables the A-TAP console log. Valid values:
  • 0: disable, log only error level info
  • 1: enable
Default = 0
deactivate Deactivates the A-TAP for the specified, single database instance. Outputs Name/Value pairs if -v or -qv specified. Deactivating an instance that's already inactive (whether DB is running or not) does not generate an error.
deactivate-all Deactivates A-TAP for a specified list of database instances. If no database instances are specified, all active A-TAPs are deactivated. Outputs Name/Value pairs for each instance, if -v or -qv specified. You can optionally specify the db-type to deactivate a group (e.g. all Oracle). For additional name/value pair, specify “overall_rv={0,1}” at end. Returns success (0) if rv=0 for every instance. Returns failure (1) if at least one instance reports rv != 0.
deinstrument Removes instrumentation for the specified Oracle DB. Not required from v10.1 and higher. If deinstrumentation is required, it is done automatically during deactivate. Outputs Name/Value pairs if -v or -qv specified.Deinstrumenting an instance that is not instrumented does not generate an error, even if the is DB running, regardless of activation status.
dump-params Dumps current values of parameters
get-statistics Get A-TAP statistics. Statistics includes information about which ATAPs are active, which are inactive, and which are in an incorrect in-between state (this shouldn't happen, it usually occurs when someone updates the DB while ATAP is active).
help Default command, prints the list of supported commands, parameters and their default values. Use this to see which commands you can execute, depending on your user type.
instrument Explicitly creates relinked instrumented Oracle. If instrumentation is required, it is usually done automatically during activate. Manual instrumentation is only required for Oracle versions <= 10 on AIX. Instrumenting an already instrumented instance returns an error. Outputs Name/Value pairs if -v or -qv specified.
is-active Returns 1 if there is at least one A-TAP activated instance. Otherwise, returns 0.
is-user-authorized Checks whether the db-user (running A-TAP) is authorized to the guardium group, and can log database traffic to K-TAP/S-TAP.
list-active Lists database instance user names of all active A-TAP database instances. Outputs Name/Value pairs if -v or -qv specified.
list-configured Lists database instances with configured but inactive A-TAPs. Outputs Name/Value pairs if -v or -qv specified.
oracle-relink Calls the utility provided by oracle to relink the DB binary.
prepare-libs Prepares libraries for use in Zone/WPAR installation
repair Run this command if the DB is (accidentally) upgraded while the A-TAP is active. It renames the -guard-original and -guard-instrumented files. Returns success on successful repair or if repair is not necessary. Does not touch the current DB executable. Outputs Name/Value pairs if -v or -qv specified. From v10.1.4, it is called automatically on activate and deactivate.
restore-active-ataps Restores the active state of the A-TAPs previously saved via save-active-ataps. If an instance fails to activate (due to DB running or some other error), then the remaining instances still attempt to activate. This command can be run multiple times without problem, since activating an already active instance is not an error.

save-active-ataps

 Saves the configurations for the currently active A-TAPs in a single file so that they can be restored later to an active state. Useful prior to deactivate-all when preparing to upgrade DBs.
store-conf Stores the configuration for a particular database instance
store-system-conf Stores the system configuration parameters