CiscoSecure ACS 2.4 for Windows NT User Guide
CiscoSecure ACS Command-Line Database Utility

Table of Contents

CiscoSecure ACS Command-Line Database Utility
Database Import Utility
Database Backup and Restore Utility
Database Maintenance

CiscoSecure ACS Command-Line Database Utility

This appendix contains details on the CiscoSecure 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 CiscoSecure 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 CiscoSecure ACS in the default location, CSUtil is located in the following directory:

C:\Program Files\CiscoSecure ACS v2.4\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 CiscoSecure 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 displays. 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 Directory Services user database.
    • EXT_NT—Authenticate the username against the Windows NT 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:
  • Windows NT Database authentication:
  • CHAP and CiscoSecure authentication:

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

The following is an example import text file:


Importing User Information from a Text File

The following is a list of arguments used with CSUtil. CiscoSecure 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 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   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   Store group configurations in the groups.txt file and removes all users. It then reloads the group configurations and adds user information from the import.txt file:

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

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 CiscoSecure ACS's configuration data and database, the CSUtil.exe utility is provided in the CiscoSecure ACS UTILS directory.

  • csutil -b—Creates a complete backup of all CiscoSecure ACS data
  • csutil -r—Restores a CiscoSecure ACS server from the backup file

CSUtils Backup

To perform a backup of the CiscoSecure ACS user and group data, execute the following instructions from the Windows NT command prompt (DOS window):

Net stop csauth—Stop the CSAuth authentication service to allow backup to take place.

Csutil -d users_and_groups.txt—Back up the users and groups data to a text file called users_and_groups.txt. To back up only the group data, use the command with a -g instead of a -d command switch.

Net start csauth—Restart the CSAuth authentication service.

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

To use CSUtil -b to create a backup file, enter:

csutil -b filename

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

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

Note      Cisco strongly recommends that you perform regular system backups as part of a comprehensive disaster recovery regimen.

CSUtils Restore

To restore from the backup file, execute the following instructions:

Net stop csauth
CSUtil -l users_and groups.txt
Net start csauth

Cisco strongly recommends that the above procedure be carried out as a part of a general backup regimen that includes backups of the Windows NT Registry using the tools supplied with Windows NT for this purpose. This will allow you to recover your system rapidly if a serious system failure occurs.

Database Maintenance

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

The VarsDB.MDB file used by CiscoSecure 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 batch command file, DB_compact.cmd, is included in the CiscoSecure ACS Utils directory. DB_compact.cmd executes the following commands:

  • net stop CSAuth—Stop the CiscoSecure 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 CiscoSecure ACS.

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

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

Although DB_compact.cmd should not negatively affect CiscoSecure 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 the "Database Backup and Restore Utility" section for information on how to back up the CiscoSecure ACS database using the command-line utility.