GIM server allocation

Remotely connect to a preinstalled and inactive (not connected to any collector) GIM agent and make it connect to some collector without the need to access the database server.

Overview

Use the following process (also called GIM auto-discovery) to remotely connect to a preinstalled and inactive GIM agent and make it connect to a collector without accessing the database server.

  1. An inactive GIM client runs in listener mode and waits for a connection from any collector.
  2. From the collector's graphic user interface (GUI) or the GuardAPI, you can send the IP address of any collector to the inactive GIM client.
  3. The inactive GIM client accepts the collector's IP address and connects to it.

If GIM is installed without specifying a collector's IP address (--sqlguardip), it runs in listener mode. When the GIM agent is running in server mode, it accepts messages only from verified collectors over SSL that have certificate authentication and shared secret verification. After 30 (or more) consecutive authentication failures, the GIM agent stops listening for requests and runs in server mode. This action prevents denial of service (DoS) attacks.

You can define your own certificates, shared secret, and port number. To use other certificates, specify the certificate/key full path name in the installation parameters: --key_file and --cert_file. See also Creating and managing custom GIM certificates.

To set a shared secret other than the default one, use the GuardAPI command grdapi gim_set_global_param paramName=gim_listener_default_shared_secret paramValue=<password>. The shared secret must be identical on the database server and collector.

Note: Do not specify the unencrypted shared secret in the command line.

To use a port other than the default one, specify the port in the installation parameter --listener_port. Set the GIM global parameter gim_listener_default_port with the new port in the GIM Global Parameters.

Note: The default or user-defined port must be enabled in the firewall.

Parameters

The following list describes the GIM installation parameters:

  • --sqlguardip - Sets the collector IP address/hostname that the GIM client is connecting to. If it is not specified, the GIM client runs in “Listener mode".
  • --ca_file - Full file name path to the certificate authority PEM file.
  • --key_file - Full file name path to the private key PEM file.
  • --cert_file - Full file name path to the certificate PEM file.
  • --shared_secret - specify a shared secret to verify collectors.
  • --listener_port - specify a port number that is different than the default.
  • --no_listener - disables GIM from running in "Listener mode" even if --sqlguardip is not specified.
Taking any of the following actions causes the GIM agent to exit server mode and process the request.
  • Update parameters
  • Install modules
  • Uninstall GIM directly on the database server
If the GIM client cannot connect to the designated collector, it returns to server mode. After the GIM agent is assigned to a valid collector's IP address or hostname, you cannot set the GIM server to run in server mode again. All new GIM agent server mode parameters appear as READ-ONLY.
Note: The following parameters must exist in the file system or the installation fails:
  • ca_file
  • key_file
  • cert_file
Additional command-line parameter

GIM and Consolidated Installers for GIM have an additional command-line parameter:

--allow_ip_hostname_combo <0|1>

This command-line parameter sets the GIM_ALLOW_IP_HOST_COMBO GIM parameter. Enter 0 (the default) to disable, and 1 to enable.

When --allow_ip_hostname_combo <0|1> is enabled,
  • If GIM_CLIENT_IP is different than the db server's hostname, GIM_CLIENTS.GIM_CLIENT_NAME is set to hostname_<GIM_CLIENT_IP>
  • If GIM_CLIENT_IP is an IP address, the GIM hostname is set to <hostname>_<GIM_CLIENT_IP> This naming convention allows GIM clients to be unique across database servers with a common hostname.
  • Restriction: You cannot set GIM_CLIENT_IP with a common hostname. Using a common hostname is considered as an attempt to register with a duplicate identifier.

Setting GIM in server mode global parameters

You can set up the server mode GIM parameters by using the following GuardAPI command:

grdapi gim_set_global_param
paramName=gim_listener_default_shared_secret
paramValue=<password>

This value is encrypted and stored in the database. The value must be identical to the unencrypted value as the shared secret if you install the GIM agent on the database server.

To set up a new default server mode GIM port, use the following GuardAPI command:

grdapi gim_set_global_param paramName=gim_listener_default_port paramValue=<port number>

This value must be identical to the unencrypted value of the shared secret if you install the GIM agent on the database server.

Note: If you use a different port or shared secret, you must specify the shared secret or port every time you connect the collector IP/hostname to the server mode GIM agent.

GIM remote activation

Use GIM remote activation to remotely connect to a preinstalled GIM agent and connect it to a collector without accessing the database server. To use GIM remote activation, browse to Manage > Module Installation > GIM Remote Activation.

Enter the following information:

  1. Host name or IP address or Server group - You can either:
    • Enter the database IP address or host name where GIM is running in listener mode.
    • To activate a group of GIM clients in listener mode, select a server group from the list.
    Note: If the collector can use either IPv4 or IPv6 addresses, but this appliance supports IPv6 only, enter the IPv6 IP address to prevent errors.
  2. GIM Listener Port - Enter the port number if it is different than the GIM Global setting. The default is 8445.
  3. GIM Listener Password - Enter the shared secret if it is different than the GIM Global setting.
  4. Guardium hostname or IP address - Specify the hostname or IP address of the Guardium appliance where you want the GIM client to connect. If you leave this field blank, the GIM client connects to the Guardium appliance from which it was activated.
  5. Click Submit to save your changes or Reset to exit without saving.
Note: You must either enter an IP address or hostname or select a server group, but the GIM listener port and GIM listener password (shared secret) are optional. When you install the GIM client in listener mode, you cannot change the settings of the shared secret and certificates unless you reinstall the GIM client.

Creating a GIM auto-discovery process

Create a GIM auto-discovery process to identify and associate GIM clients that are installed in listener mode. You can also activate GIM clients that are installed in listener mode by using Deploy monitoring agents.
  1. Navigate to Discover > Database Discovery > GIM Auto-discovery Configuration.
  2. Create a GIM auto-discovery process by clicking the new icon.
  3. In Process name, provide a name for the process and then click Apply.
  4. Define hosts to scan for GIM clients that were installed in listener mode using the Add hosts and ports to process section.
    1. Identify a host or subnet to scan in Host(s). Wildcard characters are allowed. For example, to select all addresses that begin with 192.168.2, use 192.168.2.*.
    2. To add the host or subnet to the GIM auto-discovery process, click Add scan.
    3. Repeat the previous steps to define multiple hosts or subnets to include in the GIM auto-discovery process.
    Note:
    • If you have a dual stack configuration, define scans for both the IPV4 and the IPV6 addresses.
    • Modify existing host or subnet scans by typing over the existing value and clicking Apply to save the changes.
    • Remove scans by clicking the Delete this task icon. If a task has scan results dependent upon it, the scan cannot be deleted.
  5. Run the GIM auto-discovery process by clicking Run Once Now or define a schedule for running the process by clicking Modify Schedule. For more information, see Scheduling.
  6. After the process has completed, click View Results to see a list of discovered GIM clients and associate those clients with Guardium systems.
    1. Select the GIM clients to associate.
    2. Click Associate to assign the clients to the current Guardium system or click Assign Collector to assign the clients to another Guardium system in your environment.
    3. Use the Results dialog to review the status of client association. After you associate the GIM clients, the clients are no longer in listener mode and are not shown in the GIM Auto-Discovery Results Viewer window.
    4. Click Close to close the results window.

GIM global parameters

Define your own shared secret or GIM listener port through the user interface.

  1. To open the GIM Global Parameters, click Manage > Module Installation > GIM Global Parameters.
  2. Select gim_listener_default_shared_secret to set the shared secret or gim_listener_default_port to set the port.
  3. Click the Edit selected parameter icon to edit the selected parameter.
  4. Change the value and click Save to change the parameter or Close to return to the page.