File Handling CLI Commands

Use these commands to backup and restore system information. Many of these tasks can be performed from Guardium® user interface.

About Archived Data File Names

When Guardium data is archived (or exported to an aggregator), there is a separate file for each day of data. Depending on how your export/purge or archive/purge operation is configured, you may have multiple copies of data exported for the same day. Archive and export data file names have the same format:

<daysequence>-<hostname.domain>-w<run_datestamp>-d<data_date>.dbdump.enc

daysequence is a number representing the date of the archived data, expressed as the number of days since year 0. The same date appears in yyyy-mm-dd format in the data_date portion of the name.

hostname.domain is the host name of the Guardium appliance on which the archive was created, followed by a dot character and the domain name.

run_datestamp is the date that the data was archived or exported, in yyyymmdd.hhmmss format.

data_date is the date of the archived data, in  yyyy-mm-dd format.

For example: 732423-g1.guardium.com-w20050425.040042-d2005-04-22.dbdump.enc

backup config

These commands back up and restore configuration information from the internal administration tables. The backup config command stores data in the /media/backup directory. The backup config command removes license and other machine-specific information. The backup system command provides a more comprehensive backup of the configuration and the entire system.

Syntax

backup config

restore config

backup system

This topic applies to backup and restore operations for the Guardium internal database. You can back up or restore either configuration information only, or the entire system (data plus configuration information, except for the shared secret key files, which are backed up and restored separately, see the aggregator backup keys file and aggregator restore keys file commands). These commands stop all inspection engines and web services and restart them after the operation completes.

Before restoring a file, be sure that the appliance has the system shared secret of the system that created that file (otherwise, it will not be able to decrypt the information). See About the System Shared Secret in the Guardium Administrator Guide.
Note: System restore must be done to the same patch level  of the system backup. For example, if a customer backed up the appliance when it was on Version 7.0, Patch 7 and then wishes to restore this backup into a newly-built appliance, then there is a need to first install Version 7.0, Patches 1 to 7 on the appliance and only then to restore the file.
There are two commands involved in the restore process:
  • import file, which returns an archived backup file to the system
  • restore system, which restores the system from a backup file previously returned by an import file operation.

For all backup, import and restore commands, you will receive a series of prompts to supply some combination of the following items, depending on which storage systems are configured, and the type of restore operation. Respond to each prompt as appropriate for your operation. The following table describes the information for which you may be prompted.

Note:

One copy of the SCP/FTP/TSM/Centera file transfer is saved, regardless if the transfer was successful or failed. As certain files may take hours to regenerate (for example, system backup), having a readily available copy (in particular if the file transfer failed) is of value to the user. Only one copy of each type of file is retained (archive/system backup/configuration backup/etc.)

Backup system will copy the current license, metering and number of datasources, and then backup the data. Restore system will restore the data and then restore the license, metering and number of datasources. This sequence applies to the regular restore system. Restore from a previous system will require re-configuring license, metering and number of datasources.

When configuring backups, value of zero '0' for the port number indicates that the default port is being used for that protocol and no need to change.

Table 1. backup system
Item Description

SCP, FTP, TSM, Centera, Snapshot

Select the method to use to transfer the file. TSM and Centera will be displayed only if those storage methods that have been enabled (see the store storage-method command)

Data or Configuration

Select Configuration to back up definitions and configuration information only, or select Data to back up data in addition to configuration information.

restore from archive or restore from backup

Select restore from archive to restore archived data, or select restore from backup to restore configuration information.

normal or upgrade

If restoring from the same software version of Guardium, select normal. If restoring configuration information following software  upgrade of the Guardium appliance, select upgrade.

host

The remote host for the backup file.

remote directory

The directory for the backup file. For FTP, the directory is relative to the FTP root directory for the FTP user account used. For SSH, the directory path is a full directory path. For Windows SSH servers, use Unix-style path names with forward slashes, rather than Windows-style backslashes.

username

The user account name to use for the operation (for backup operations, this user must have write/execute permission for the directory specified).

Note: For Windows, a domain user is accepted with the format of domain\user

password

The password for the username.

file name

The file name for the archive or backup file. See Archived Data Names.

A user can select multiple files by using the wildcard character * in the file name. Support of the wildcard character * is permitted when using transfer methods FTP, SCP and Snapshot. Support of the wildcard character * is not permitted on transfer methods TSM or Centera.

Centera server

Enter the Centera server name. If using PEA files, use the following  format:  <Host name/IP>? <full PEA file name>, for example:

128.221.200.56?/var/centera/us_profile_rwqe.pea.txt

Centera clipID

For a Centera restore operation, the Content Address returned from the backup operation. For example:

6M4B15U4JM4LBeDGKCPF9VQO3UA

After you have supplied all of the information required for the backup or restore operation, a series of messages will be displayed informing you of the results of the operation. For example, for a restore system operation the messages should look something like this (depending on the type of restore and storage method used):

gpg: Signature made Thu Feb 22 11:38:01 2009 EST using DSA key ID 2348FF9E gpg: Good signature from "Backup Signer <support@guardium.com>" Proceeding to shutdown services Proceeding to startup services Safekeeping admin.xreg Safekeeping client.xreg Safekeeping controllers.xreg Safekeeping controls.xreg Safekeeping guardium-portlets.xreg Safekeeping local-portlets.xreg Safekeeping local-security.xreg Safekeeping local-skins.xreg Safekeeping media.xreg Safekeeping portlets.xreg Safekeeping security.xreg Safekeeping skins.xreg guard_sniffer.pl -reorder Recovery procedure was successful. ok

Prevent backup/archive scripts from filling up /var

The backup process will check for room in /var before running and fail. This process will also warn the user if there is insufficient space for backup.

The archive process will check the size of the static tables and make sure there is room in /var to create the archive.

An error is now logged in the logfile and GUI if the backup is over 50%

Example:

ERROR: /var backup space is at 60% used. Insufficient disk space for backup. CLI> backup system     1. DATA     2. CONFIGURATION  Please enter the number of your choice: (q to quit) 1      1. SCP     2. CONFIGURED DESTINATION  Enter the number of your choice: (q to quit) 2 Make sure destination is configured in the GUI under the System Backup option Please wait, this may take some time.

backup profile

Use this command to maintain the backup profile data (patch mechanism).

The backup file will be copied to the destination according to the backup profile.  If the parameter indicating whether to keep the backup file is “1” AND there is enough disk space the backup file will be kept within the system, otherwise removed.

All four fields must be filled in - backup destination host, backup destination directory, backup destination user, and backup destination password.

Syntax

show backup profile

Example

patch backup flag is 1    patch backup automatic recovery flag is 1    patch backup dest host is    patch backup dest dir is    patch backup dest user is    patch backup dest pass is    ok    

Syntax

store backup profile

Example

Do you want to set up for automatic recovery? (y/n)    Enter the patch backup destination host:    Enter the patch backup destination directory:    Enter the patch backup destination user:    Enter the patch backup destination password:

export audit-data

Exports audit data from the specified date (yyyy-mm-dd) from various internal Guardium tables to a compressed archive file. The data from a specified date will be stored in a compressed archive file, in the /var/dump directory. The file created will be identified in the messages produced by the system. See the example. Use this command only under the direction of Guardium Support.

Note: Only users with admin role may run this command .

Syntax

export audit-data <yyyy-mm-dd>

Example

If you enter the audit-data command for the date 2005-09-16, a set of messages similar to the following will be created: CLI> export audit-data 2005-09-16 2005-09-16 Extracting  GDM_ACCESS  Data ... Extracting  GDM_CONSTRUCT  Data ... Extracting  GDM_SENTENCE  Data ... Extracting  GDM_OBJECT  Data ... Extracting  GDM_FIELD  Data ... Extracting  GDM_CONSTRUCT_TEXT  Data ... Extracting  GDM_SESSION  Data ... Extracting  GDM_EXCEPTION  Data ... Extracting  GDM_POLICY_VIOLATIONS_LOG  Data ... Extracting  GDM_CONSTRUCT_INSTANCE  Data ... Generating tar file ...  /var/csvGenerationTmp ~ GDM_ACCESS.txt GDM_CONSTRUCT.txt GDM_CONSTRUCT_INSTANCE.txt GDM_CONSTRUCT_TEXT.txt GDM_EXCEPTION.txt GDM_FIELD.txt GDM_OBJECT.txt GDM_POLICY_VIOLATIONS_LOG.txt GDM_SENTENCE.txt GDM_SESSION.txt ~ Generation completed, CSV Files saved to /var/dump/732570-supp2.guardium.com-w20050919110317-d2005-09-16.exp.tgz ok

The data from each of the named internal database tables is written to a text file, in CSV format. The name of the archive file ends with exp.tgz and the remainder of the name is formed as described in About Archived Data File Names.

You can use the export file command to transfer this file to another system.

delete audit-data

Use this command only under the direction of Guardium Support. This command is used to remove compressed audit data files. You will be prompted to enter an index number to identify the file to be removed. See Archived Data File Names, for information about how archived data file names are formed.

You will be prompted to identify the file to be removed.

Syntax

delete audit-data

show audit-data

Use this command to display any files that were created by executing the CLI command, export audit-data. For more information about audit data files, see export audit-data.

Syntax

show audit-data <yyyy-mm-dd>

export file

This command exports a single file named filename from the /var/IBM/Guardium/data/dump, /var/log or /var/IBM/Guardium/data/importdir directory.

Use this command only under the direction of Guardium Support. To export Guardium data to an aggregator or to archive data, use the appropriate menu commands on the Administration Console panel.

Syntax

export file </local_path/filename> <user@host:/path/filename>

local_path must be one of the following: /var/IBM/Guardium/data/dump, /var/log or /var/IBM/Guardium/data/importdir

fileserver

Use this command to start an HTTPS-based file server running on the Guardium appliance. This facility is intended to ease the task of uploading patches to the unit or downloading debugging information from the unit. Each time this facility starts, it deletes any files in the directory to which it uploads patches.

Note: Any operation that generates a file that the fileserver will access should finish before the fileserver is started (so that the file is available for the fileserver).

Syntax

fileserver [https://ip address:8445] [duration]

ip address is an optional parameter that allows access to the fileserver from the indicated IP address. By default (without the parameter), access is restricted to the IP address of the SSH client that started the fileserver.

duration is an optional parameter that specifies the number of seconds that the fileserver is active. After the specified number of seconds, the fileserver shuts down automatically. The duration can be any number of seconds from 60 to 3600.

In case of a security setup where browser sessions are redirected through a proxy server, the IP address of the fileserver client will not be the same as SSH client that started the fileserver. Instead, the fileserver client will have the IP address of the proxy server, and this address must be passing the optional ip address parameter. To find the proxy IP address, check your browser settings or the client IP addresses shown in the Logins to Guardium report in the Guardium Monitor interface.

Example

To start the file, enter the fileserver command:

CLI> fileserver <ip address> <duration>

Starting the file server. You can find it at https://(name of appliance):8445

Press ENTER to stop the file server.

Open the fileserver in a browser window, and do one of the following:

  • To upload a patch, click Upload a patch and follow the directions.
  • To download log data, click Sqlguard logs, navigate to the file you want and download as you would any other file.

When you are done, return to the CLI session and press Enter to terminate the session.

How to access the VA and Entitlement scripts using fileserver

Instructions

From the CLI, run "fileserver <your desktop IP> 3600"

Vulnerability Assessment:

Open a browser and go to: https://<appliance ip>/log/debug-logs/gdmmonitor_scripts/

Choose the file matching your database type

Entitlements:

Open a browser and go to: https://<appliance ip>/log/debug-logs/entitlemnts_monitor_role/

Choose the file matching your database type

import file

See backup config and restore config.

In import file CLI command, user can use wildcard * for the file name in method scp, ftp and snapshot.

Syntax

import file

import tsm config

Uploads a TSM client configuration file to the Guardium appliance. You must do this before performing any archiving or backup operations using TSM. You will always need to upload a dsm.sys file, and if that file includes multiple servername sections, you will also need to upload a dsm.opt file. For information about how to create these files, check with your company’s TSM administrator.

You will be prompted for a password for the user account on the specified host.

Syntax

import tsm config <user@host:/path/[ dsm.sys | dsm.opt ]>

Parameters

user@host - User account to access the file on the specified host.

/path/[ dsm.sys | dsm.opt ] - Full path filename of the file to import.

Note: In setting up TSM on each collector, if the initial configuration fails, a notification error results which says the test file could not be sent. Logging into the collector as root, and then running a dsmc archive command to the TSM server, the TSM file, with the same credentials, now succeeds. Returning to the GUI, and configuring with the same options used before, the configuration now succeeds as well.  

If tsm config has passwordaccess=generate, the password stored in a local file, is sought. The root user needs to run the dsmc command once to create this local password file.

After uploading the tsm config file, if tsm config has a passwordaccess generate prompt, passwordaccess is set to be generated.
Would you like to run a dsmc command now to ensure password is set locally (y/n)?     If the answer is y, run a "dsmc query options>>/dev/null" command, which will prompt user for password.

import tsm property

Use this CLI command to upload a file to /opt/tivoli/tsm/client/ba/bin/guard_tsm.properties.

The file size should be 1K.

Syntax

import tsm property user@host:file

This command will upload the input file to /opt/tivoli/tsm/client/ba/bin/guard_tsm.properties

restore config

These commands back up and restore configuration information from the internal administration tables. The backup config command stores data in the /media/backup directory. The backup config command removes license and other machine-specific information. The backup system command provides a more comprehensive backup of the configuration and the entire system.

When restoring a configuration, you must restore a backup that is of the same version and patch level as the original appliance where the backup was created.

Syntax

backup config

restore config

restore db-from-prev-version

This command takes a backup from the immediate past system (backup data must be provided, configuration backup is optional) and performs a restore on a newer system. It includes upgrading the data, portlets, etc.

Perform a full system backup prior to upgrading your Guardium system. If for some reason the upgrade fails and leaves the machine in a way that can not be used, instead of trying to fix and re-run the upgrade, rebuild the machine as the latest system, setting up this latest system with only the basic network information (IP, resolver, route, system hostname and domain).

The result will be the latest system with the data and customization (if configuration file is provided) from the previous system.

First, try a regular upgrade from the previous system to the latest system. If this is not successful, then use the backup as an alternative way to upgrade from the previous system to the latest system.

Note: Older data being restored to an aggregator (not to investigation center), and outside the merge period, will not be visible until the merge period is changed and the merge process rerun.

To run this command, back up the current server for both data and configuration. Once the backup is complete, install the latest release onto the same server. Next, import both the data and configuration file from CLI via the import file command. Then after the two backup files are imported, run, again from CLI, the command restore db-from-prev-version. This restores the backup files (data and configuration) from the older version to the newly installed server.
Note: If you are using Guardium in a non-English language, the restore CLI command sets some strings, including report headers, to English. To view these strings in the non-English language, run the store language CLI command after you run the restore CLI command.

The optional parameter "override" is applicable only to a restore of a Central Manager appliance from backup.

By default, when a user executes the "restore db-from-prev-version" command on a Central Manager appliance, we preserve the existing configuration information on this Central Manager that links to the Managed Units that it manages.

When the user adds "override" to the restore command, the existing Central Manager /Managed Units configuration is overridden by the Central Manager /Managed Units configuration from the backup data.

Syntax

restore db-from-prev-version [override]

Examples

restore db-from-prev-version

restore db-from-prev-version override

Note: Managed units and S-TAP associations in "Associate S-TAPs and Managed Units" are not restored when using this CLI command. The user will have to define associations again.
Syntax
restore db-from-prev-version
This procedure will restore and upgrade a previous backup on a newly-installed latest system. If the older files are currently located on a remote system, use the "import file" cli command to transfer them locally prior to running this procedure. The imported files will be put in the /var/dump/ directory. Continue (y/n)? 
Note:

Answering Y (yes) to the following questions during the execution of the CLI command, restore db-from-prev-version, will result in all non-canned/customized reports and panes to compress into one pane with the name of v.x.0 Custom Reports.

Answering N (no) to the same questions will result in all panes being restored to what they were in previous version.

Update portal layout (panes and menus structure) to the new v8 default (current instances of custom reports will be copied to the new layout, as well as parameter changes on predefined reports) for the user admin? (y/n) n  Update portal layout (panes and menus structure) to the new v8 default (current instances of custom reports will be copied to the new layout, as well as parameter changes on predefined reports) for all other users? (y/n)

restore keystore

Use this command only under direction from Technical Support.

Use this command to restore certifications and private keys used by the Web servlet container environment (Tomcat).

Syntax

restore keystore

restore pre-patch-backup

Use this command only under direction from Technical Support.

Use this command to recover the pre-patch-backup when the appliance database is up or down.

Syntax

restore pre-patchbackup Please enter the information to retrieve the file: Is the file in the local system? (y/n) n Start to recover with the backup profile parameters. Please check the recovery status in the log /var/log/guard/diag/depot/patch_installer.log ok -------------------------------------- If answer 'n', abort the operation. If answer 'y', need to enter the file name.

restore system

This topic applies to backup and restore operations for the Guardium internal database. You can back up or restore either configuration information only, or the entire system (data plus configuration information, except for the shared secret key files, which are backed up and restored separately, see the aggregator backup keys file and aggregator restore keys file commands). These commands stop all inspection engines and web services and restart them after the operation completes.

Before restoring a file, be sure that the appliance has the system shared secret of the system that created that file (otherwise, it will not be able to decrypt the information). See About the System Shared Secret in the Guardium Administrator Guide.

Note: System restore must be done to the same patch level  of the system backup.
There are two commands involved in the restore process:
  • import file, which returns an archived backup file to the system
  • restore system, which restores the system from a backup file previously returned by an import file operation.

For all backup, import and restore commands, you will receive a series of prompts to supply some combination of the following items, depending on which storage systems are configured, and the type of restore operation. Respond to each prompt as appropriate for your operation. The following table describes the information for which you may be prompted.

Note:

One copy of the SCP/FTP/TSM/Centera file transfer is saved, regardless if the transfer was successful or failed. As certain files may take hours to regenerate (for example, system backup), having a readily available copy (in particular if the file transfer failed) is of value to the user. Only one copy of each type of file is retained (archive/system backup/configuration backup/etc.)

Backup system will copy the current license, metering and number of datasources, and then backup the data. Restore system will restore the data and then restore the license, metering and number of datasources. This sequence applies to the regular restore system. Restore from a previous system will require re-configuring license, metering and number of datasources.

Table 2. restore system
Item Description

SCP, FTP, TSM, Centera, Snapshot

Select the method to use to transfer the file. TSM and Centera will be displayed only if those storage methods that have been enabled (see the store storage-method command)

Data or Configuration

Select Configuration to back up definitions and configuration information only, or select Data to back up data in addition to configuration information.

restore from archive or restore from backup

Select restore from archive to restore archived data, or select restore from backup to restore configuration information.

normal or upgrade

If restoring from the same software version of Guardium, select normal. If restoring configuration information following software  upgrade of the Guardium appliance, select upgrade.

host

The remote host for the backup file.

remote directory

The directory for the backup file. For FTP, the directory is relative to the FTP root directory for the FTP user account used. For SSH, the directory path is a full directory path. For Windows SSH servers, use Unix-style path names with forward slashes, rather than Windows-style backslashes.

username

The user account name to use for the operation (for backup operations, this user must have write/execute permission for the directory specified).

Note: For Windows, a domain user is accepted with the format of domain\user

password

The password for the username.

file name

The file name for the archive or backup file. See Archived Data files names.

A user can select multiple files by using the wildcard character * in the file name. Support of the wildcard character * is permitted when using transfer methods FTP, SCP and Snapshot. Support of the wildcard character * is not permitted on transfer methods TSM or Centera.

Centera server

Enter the Centera server name. If using PEA files, use the following  format:  <Host name/IP>? <full PEA file name>, for example:

128.221.200.56?/var/centera/us_profile_rwqe.pea.txt

Note the ? between the server IPs and Pea file name.

This IP address and the .PEA file comes from EMC Centera. The question mark is required when configuring the path. The .../var/centera/... path name is important as the backup may fail if the path name is not followed. The .PEA file gives permissions, username and password authentication per Centera backup request.

Centera clipID

For a Centera restore operation, the Content Address returned from the backup operation. For example:

6M4B15U4JM4LBeDGKCPF9VQO3UA

After you have supplied all of the information required for the backup or restore operation, a series of messages will be displayed informing you of the results of the operation. For example, for a restore system operation the messages should look something like this (depending on the type of restore and storage method used):

gpg: Signature made Thu Feb 22 11:38:01 2009 EST using DSA key ID 2348FF9E gpg: Good signature from "Backup Signer <support@guardium.com>" Proceeding to shutdown services Proceeding to startup services Safekeeping admin.xreg Safekeeping client.xreg Safekeeping controllers.xreg Safekeeping controls.xreg Safekeeping guardium-portlets.xreg Safekeeping local-portlets.xreg Safekeeping local-security.xreg Safekeeping local-skins.xreg Safekeeping media.xreg Safekeeping portlets.xreg Safekeeping security.xreg Safekeeping skins.xreg guard_sniffer.pl -reorder Recovery procedure was successful. ok

set up help (secondary disk for backup)

Install a secondary disk or for backup on R610 R710 appliances. Place it slot number 2 and proceed with set up snapshotdisk to configure the partition, format the drive, and mount it. The two CLI choices are set up help and set up snapshotdisk.

Syntax

setup [help | snapshotdisk | vmware_tools]

store tsm authorization

When backupinitiationroot is set to ON in TSM servers, then only root and authorized users can perform backup/archive. When backupinitiationroot is set on and password access in DSM.SYS is set to “generate”, Guardium backup and archive to TSM will fail with the error message:

ANS1708E Backup operation failed. Only a root user can do this operation

Non-root users must be authorized to perform backup and archive.

This authorization is enabled by executing the CLI command

Store tsm authorization backupinitiationroot on

This authorization is disabled by executing the CLI command:

Store tsm authorization backupinitiationroot off

Syntax

store tsm authorization backupinitationiroot <on/off>

Show command

show tsm authorization backupinitationiroot <on/off>

This CLI command displays on, if non-root Guardium users are authorized to perform backup and archive when backupinitiationroot is set to ON in TSM servers. Otherwise, it displays off.

store language

Use this CLI command to change from the baseline English and convert the database to the desired language. Installation of Guardium is always in English. A Guardium system can be changed to Japanese, Chinese (Traditional or Simplified), French,, Spanish, German or Portuguese after an installation.

The CLI command, store language, is considered a setup of the appliance and is intended to be run during the initial setup of the appliance.

Running this CLI command, after deployment of the appliance in a specific language, can change the information already captured, stored, customized, archived or exported.

Note: After switching from English to a desired language, it is not possible to revert back to English, using this CLI command. The Guardium system must be reinstalled in English.

Syntax

CLI> store language [English | Japanese | SimplifiedChinese | TraditionalChinese | French | German | Spanish | Portuguese]

Show command

show language

set up vmware tools

Use this CLI command to install VMware that runs on the ESX infrastructure.

Syntax

setup vmware_tools [ install | uninstall ]

Step 1: Open the VM client/console and select the VM instance that contains the IBM Guardium appliance. Right-click the instance, select (from the popup menu) Guest => Install/upgrade VMware tools. This enables the instance to access the VMware tools via a mount point.

Step 2: Run the CLI command (from within the VM client/console), setup vmware_tools install, to install VM tools.

Vmware kernel panic after a reboot

VMware ESX 4.1 Virtual machine running Guardium might get a kernel panic after a reboot.

To correct this situation, VMware recommends: Install update 2 on ESX4.1 or Set CPU/MMU virtualization to Use software only instruction set and MMU Virtualization. This option is found under Settings/ Options/ CPU/MMU Use software for instruction set and MMU Virtualization.