Cisco Secure ACS Command-Line Database Utility

Table of Contents

Cisco Secure ACS Command-Line Database Utility

Cisco Secure ACS Command-Line Database Utility

This appendix contains details on the Cisco Secure ACS command-line utility, CSUtil.exe. You can use CSUtil to import username, password, and group information all at once from a standard text file to back up and maintain your database.


Note   You can also perform these and similar tasks through the Cisco Secure ACS hypertext markup language (HTML) interface, using the ACS System Backup, ACS System Restore, Database Replication, and RDBMS Synchronization features. For more information on these features, see "Database Information Management."

Database Import Utility

This section describes how to import a text file into the CiscoSecure user database to add new users to the database or modify users' authentication information. When you install Cisco Secure ACS in the default location, CSUtil is located in the following directory:

    C:\Program Files\CiscoSecure ACS v2.6\Utils

Creating the Text File

You can run the CSUtil utility either online or offline. If you run CSUtil online, database updates are performed while the Cisco Secure ACS continues to run. This slows down the performance of CSUtil.

If you run CSUtil offline, database updates are written directly to the CiscoSecure user database, but CSAuth is stopped. The import is much faster, but services are down as long as CSAuth is stopped.

Enter the following information on a single line with fields separated by colons:

  • Username—

    • ADD—Add user information to the CiscoSecure user database. If the username already exists, no information is changed.

    • UPDATE—Update the information associated with the existing username in the CiscoSecure user database.


Note   If the username does not exist, an error message appears. If this happens, use the add keyword.

  • DELETE—Remove the user information from the CiscoSecure user database.

  • Authentication type
    • CSDB—Authenticate the username against the CiscoSecure user database.

    • EXT_LDAP—Authenticate the username against the generic LDAP user database.

    • EXT_NT—Authenticate the username against the Windows NT/2000 user database.

    • EXT_NDS—Authenticate the username against the Novell NDS user database.

    • EXT_SDI—Authenticate the username against the SDI user database.

    • EXT_ANPI—Authenticate the username against the AXENT user database.

    • EXT_ENIGMA—Authenticate the username against the SafeWord user database.

    • CHAP—Require a CHAP password for authentication.

  • User Group
    • PROFILE—Group number to which the user is assigned. This must be a number from 0 to 99, not a name.


Note   If you do not provide a profile number, the user is added to the default group.

The following examples show the syntax for the import text file:

  • CiscoSecure authentication:

    ADD:user01:CSDB:userpassword:PROFILE:1
  • WindowsNT Database authentication:

    ADD:user02:NT::PROFILE:2
  • CHAP and CiscoSecure authentication:

    ADD:chapuser:CSDB:hello:CHAP:chappw:PROFILE:3

Note   These entries are case-sensitive. The colons are mandatory delimiters.

The following is an example import text file:

    OFFLINE
    ADD:user01:CSDB:userpassword:PROFILE:1
    ADD:user02:NT::PROFILE:2
    ADD:chapuser:CSDB:hello:CHAP:chappw:PROFILE:3
    ADD:mary:EXT_NT:CHAP:achappassword
    ADD:joe:EXT_SDI:
    ADD:vanessa:CSDB:vanessaspassword
    ADD:juan:CSDB_UNIX:unixpassword
    ADD:fobar:ZXT_LDAP::PROFILE:10

Importing User Information from a Text File

The following is a list of arguments used with CSUtil. Cisco Secure ACS executes arguments in order from left to right.

CSUtil [-q] [-c] [-d] [-g] [-i filename] [-l filename] [-e errornumber] [-b filename] [-r filename] [-f] [-n] [-s] [-y] [-x]

  • -q—Quiet mode. Does not prompt; use before other options.

  • -b—Backup system to named file. See the "Database Backup and Restore Utility" section for more information.

  • -c—Recalculate database CRC values.

  • -d—Export whole database to DUMP.TXT.

  • -e—Decode error number to ASCII message.

  • -f—Fix group assignments if this system was ever upgraded from EasyACS.

  • -g—Export group information only to GROUP.TXT.

  • -i—Import users from IMPORT.TXT or named file.

  • -l—Load database from DUMP.TXT or named file (use -n -l to initialize and load).

  • -n—Create new database and index.

  • -r—Restore system from named file. See the "Database Backup and Restore Utility" section for more information.

  • -s—Make database smaller by removing deleted users.

  • -x—Display help information.

  • -y—Dump Windows NT/2000 Registry configuration information to SETUP.TXT.

After you finish creating the import text file, follow these steps:


Step 1   Merge the import text file with the current CiscoSecure user database:

    csutil -i filename.txt

Note   The database is modified, not destroyed. The information should scroll as information is being modified or merged with the existing database.

Step 2   Using the following command, overwrite the current CiscoSecure user database with the import text file:

    csutil -n -i filename.txt

Note   The existing database is reinitialized and the text file is imported.

Step 3   Using the following command, store group configurations in the groups.txt file, remove all users, and then reload the group configurations and add user information from the import.txt file:

    csutil -g -n -l groups.txt -i import.txt

Caution All user information is destroyed. Group information still exists in the groups.txt file and can be used with the import.txt file to add new users with existing group information. There is no warning when information is overwritten.


Database Backup and Restore Utility

To facilitate backup and restoration of the Cisco Secure ACS server's configuration data and database, the CSUtil.exe utility is provided in the Cisco Secure ACS UTILS directory.

  • csutil -b—Creates a complete backup of all Cisco Secure ACS data

  • csutil -r—Restores a Cisco Secure ACS server from the backup file

CSUtils Backup

To perform a backup of the Cisco Secure ACS user and group data, follow these steps:


Step 1   At a Windows NT/2000 command prompt (DOS window), type the following commands:

The users_and_groups.txt file can then be backed up to tape and stored somewhere safe.

Step 2   To use csutil -b to create a backup file, type the following:

    csutil -b filename

This creates the following files in Utils\SysBackups\directory\:

  • REGISTRY.DAT
  • USER.DAT
  • USER.IDX
  • VARSDB.MDB
  • A compressed backup file named with the current date and time in the format yyyymmddhhmm.zip. This file is written to the Cisco Secure ACS\utils\dbcheckpoint directory. Each backup creates a file that does not overwrite existing files. The data is stored in compressed format and, therefore, takes up little space. The system administrator must still perform the necessary file management to maintain adequate disk space.


Note   Cisco strongly recommends that you perform the above procedure as a part of a general backup regimen that includes backups of the Windows NT Registry. This will enable you to recover your system rapidly if a serious system failure occurs.


CSUtils Restore

To restore from the backup file, follow these steps:


Step 1   At a Windows NT/2000 command prompt (DOS window), type

    Net stop csauth

and then press Enter.

Step 2   Type

    CSUtil -l users_and groups.txt

and then press Enter.

Step 3   Type

    Net start csauth
    


and then press Enter.


Database Maintenance

Unexpected database file size growth can cause problems with the database. To avoid these problems, Cisco Secure ACS enables you to institute a database maintenance schedule that periodically compacts the database. For your convenience, a Windows NT/2000 batch command file, DB_compact.cmd, is included in the Cisco Secure ACS Utils directory.

The VarsDB.MDB file used by Cisco Secure ACS is based on Microsoft ODBC technology. Like most RDMBSes, ODBC uses a deletion scheme that does not actually remove records from the database when they are deleted—records are simply marked as deleted and do not show up in queries. To actually purge the database of the deleted records, you need to run a separate process called compaction. In small databases with low transaction rates, it is not particularly important to regularly compact the database because the database will stay a relatively consistent size. In a large database environment with large numbers of deletions, the database file can grow significantly over time. If compaction is not carried out, this can have serious effects on the overall operation of the system.

To avoid unexpected and problematic database file size growth, institute a database maintenance regimen that periodically compacts the database. For your convenience, a Windows NT/2000 batch command file, DB_compact.cmd, is included in the Cisco Secure ACS Utils directory. DB_compact.cmd executes the following commands:

  • net stop CSAuth—Stop the Cisco Secure ACS.

  • csutil -d—Dump the database to a temporary file (DUMP.TXT).

  • csutil -n—Initialize the database.

  • csutil -l—Reload the database.

  • net start CSAuth—Restart Cisco Secure ACS.

Because the authentication service is stopped while these commands execute, authentication service is interrupted.


Note   Back up the Cisco Secure ACS database before you run DB_compact.cmd.

Although DB_compact.cmd should not negatively affect Cisco Secure ACS operation, there is always the possibility of unexpected results with compaction operations. Therefore, it is best to back up the database before database compaction. Then, if something does go wrong when DB_compact.cmd runs, a current backup will be available and service can be restored quickly. See "Database Backup and Restore Utility" section for information on how to use the command-line utility to back up the Cisco Secure ACS database.