Using the CiscoSecure GRS Command-Line Options and Utilities

You can perform most of the same tasks using the command-line interface (CLI) as you can using the graphical user interface (GUI). For information on using the GUI to configure CiscoSecure GRS, see the chapter "Configuring CiscoSecure GRS." The interface you use is strictly a matter of personal preference.

Setting the Environment Variables

If you do not use the start_grs script, you must set the data store access and environment variables as described in the following sections.

Instead of using these commands, you can use the source command to set these variables automatically. The following example is for Bourne shell. Enter:

source /opt/CSCOgrs/etc/grs.sh

Database Access Variables (Oracle only)

If you are using an Oracle database as a data store, set the following database access variables:

• ORACLE_HOME--Gives the location of the Oracle database. For example:

ORACLE_HOME=/opt/app/oracle/product/7.3.2

• ORACLE_SID--The name of the Oracle database server. For example:

ORACLE_SID=SERVER1

In this example, SERVER1 is the name assigned by the database administrator to the machine on which Oracle is running.

Environment Variable

(Optional) Set the $PATH environment variable. The following example is for Bourne shell. Enter:

PATH=/opt/CSCOgrs/bin:$PATH
export PATH

The following example is for C shell. Enter:

sentenv PATH /opt/CSCOgrs/bin:$PATH

CiscoSecure GRS Commands

This section describes two commands you can use with CiscoSecure GRS:

• start_grs

• stop_grs

---

Note Use the scripts provided for your convenience rather than the commands; the scripts enable fault tolerance, auto-restart, and other CiscoSecure GRS features.

---

start_grs

This command starts CiscoSecure GRS, sets up all the necessary environment variables for CiscoSecure GRS, and invokes the CiscoSecure GRS daemon grs_d.

The CiscoSecure GRS daemon grs_d enables fault tolerance for CiscoSecure GRS. Specifically, grs_d has the following functions:

• Starts CiscoSecure GRS

• Monitors the grs daemon and when the daemon exits:

  • Restarts the grs daemon the number of times configured

  • Sends notification via e-mail to any configured e-mail address(es)

• Logs the times that the grs daemon starts and stops to the grs_d.log file

• Logs the cause of termination to the grs_d.log file. In the following example, CiscoSecure GRS was killed with the -9 option:
  [/export/grs/bin/grs -x] exit, pid=21603, abnormal termination, signal number = 9
  Wed Oct 8 15:17:13 1997
  [/export/grs/bin/grs -x] restarted, pid 21610, count remains: 4
  
  

To start CiscoSecure GRS, enter:

./start_grs -v

-v version--displays the version information for CiscoSecure GRS and exits.

stop_grs

This command stops grs_d and CiscoSecure GRS.

Enter:

./stop_grs

This command has no options.

---

Note Using the UNIX kill command on a CiscoSecure GRS process causes the process to restart if the restart count has not yet reached 0. This is recorded in the grs_d.log file as a normal exit with exit code -1. We strongly recommend that you use the stop_grs utility to cleanly stop CiscoSecure GRS.

---

CiscoSecure GRS Utilities

The CiscoSecure GRS utilities are used to add, update, and remove entries from the CiscoSecure GRS data store.We recommend that you use these tools instead of issuing SQL commands directly, because the tools automatically ensure the integrity of the relationships needed for CiscoSecure GRS to operate correctly.

Caution  If you are using a flatfile database, do not edit the .db files.

The utilities log messages to $GRSHOME/logfiles/grsdbutils.log. The utility commands first read the global specification file, $GRSHOME/etc/grs.spc. The grs.spc file has all the necessary information to understand the contents of the .dat data files in $GRSHOME/data.

---

Note You must exit the GUI before you run the CiscoSecure GRS utilities.

---

Five utilities are supplied with CiscoSecure GRS:

• create_dbtables

• grsdbadd

• grsdbdelete

• grsdbview

• grsfile2db

---

Note The error message log file, grsdbutils.log, keeps a record of where and when an error occurred. The error file grsdbutils.err contains the records that caused the error. Both files are located in $GRSHOME/logfiles. You can delete these files when they get too large.

---

create_dbtables

Use the create_dbtables utility to change from a flatfile data store to an Oracle database. This utility allows you to recreate the database without restarting CiscoSecure GRS. Follow these steps:

Step 1 Modify the create_dbtables script. Change the line:

/bin/sqlplus n/a/n/a@NONE @$GRSHOME/etc/create

to:

/bin/sqlplus <valid databaseuser>/<valid password>@<valid DBServer)@$GRSHOME/etc/create

The tables are created automatically.

Step 2 Populate the tables by using the GUI or CLI. See the section "grsfile2db" and the appendix "Changing CiscoSecure GRS Data Stores."

grsdbadd

The grsdbadd utility adds records to the data store. Enter:

grsdbadd -v domain -v nas -h

-v view name of the view (domain or NAS)

-h displays the online help

Error messages are sent to stderr.

Examples:

grsdbadd -v domain
grsdbadd -v nas
grsdbadd -h

grsdbdelete

This utility deletes records from the data store. Enter:

grsdbdelete -v domain -k domainname -k nasname -h

-v view name of the view (domain, NAS, or vendor)

-k key keyword to search by (domain name or NAS name)

-h displays the online help

Error messages are sent to stderr.

Examples:

grsdbdelete -v domain
grsdbdelete -v nas
grsdbdelete -v vendor
grsdbdelete -k domainname
grsdbdelete -k nasname
grsdbdelete -h

grsdbview

The grsdbview utility displays the records in the data store. Different combinations of options let you view different combinations of data. Running grsdbview with no options provides a summary of all data stored in the data store. If you do not specify an output file, the view is output to stdout. If you are using grsdbview without parameters, pipe it through more. Enter:

grsdbview -v view -k key -o outputfile -h

-v view name of the view (domain, ippool, nas, or vendor)

-k key keyword to search by (domain name, IP pool name, NAS name, or vendor keyword)

-h displays the online help

-o outputfile produces an output object file named outputfile

Examples:

grsdbview -v domain -k domainname -o outputfile
grsdbview -v ippool -k poolname -o outputfile
grsdbview -v nas -k nasname -o outputfile
grsdbview -v vendor -o outputfile
grsdbview -v translation -o outputfile
grsdbview -v filtering -o outputfile
grsdbview -h

Generating a List of Translated Attributes

To generate a list of the attributes that are translated, enter the following at the root directory:

grsdbview -v translation

Generating a List of Filtered Attributes

To generate a list of the attributes that are filtered, enter the following at the root directory:

grsdbview -v filtering

grsfile2db

The grsfile2db utility updates and inserts records in the data store. By default, it inserts and updates data from all the files in the $GRSHOME/data directory, but you can update a single data file using the -f command-line option. Enter:

grsfile2db -f datafiles -h

-f is used to update a single data file

datafiles represents the names of files containing data to be loaded into the data store. The following are valid file names:

• acs.dat

• attribute.dat

• domainconfig.dat

• ipaddressrange.dat

• ippool.dat

• nas.dat

• vendor.dat

-h displays the online help

To add a large amount of data to your database, follow these steps:

Step 1 Copy the sample .dat files from the $GRSHOME/samples directory to $GRSHOME/data directory.

Step 2 Modify domainconfig.dat and acs.dat for the local and remote domains. (For an explanation of the parameters in these files, see the $GRSHOME/etc/grs.spc file.) If you are going to use range checking, you must also modify the .dat files for ipaddressrange and ippool.

Step 3 To load the data from all the datafiles in the $GRSHOME/dbutils directory, enter:

grsfile2db

To load the data from a single datafile, enter:

grsfile2db -f datafile

where datafile is the name of the file from which you want to import data.

For example, to import new ACS data, enter:

grsfile2db -f acs.dat

The data in the file(s) is imported to the data store.

Minimum Configuration for CiscoSecure GRS Using the Command-Line Interface

Follow these steps to set up CiscoSecure GRS initial configuration using the command-line utilities:

Step 1 Make sure the GUI is not running.

Step 2 Run grsdbadd.

Step 3 Select option 1, Add Domain, ACS, IpPool, IpAddr Record(s).

Step 4 Select option 1, Add Domain information.

Step 5 Enter the Local Domain name, _LOCAL_ACS_.

Step 6 Enter the default values for the remaining entries.

Step 7 Exit Add Domain Record.

Step 8 Select option 2, Add ACS information.

Step 9 Enter the Local Domain name, _LOCAL_ACS_.

Step 10 Enter the name or IP address of the local ACS host.

Step 11 Enter the remaining information for the local ACS.

Step 12 Exit Add ACS Record.

Step 13 Click Exit again.

Step 14 Select option 2, Add NAS Record(s).

Step 15 Enter the required information for either the default TACACS+ NAS (_DEFAULT_TACACS_NAS_) or the default RADIUS NAS (_DEFAULT_RADIUS_NAS_).

Step 16 Exit grsdbadd. The information required to start CiscoSecure GRS is now created in the data store.