-
User Guide for Cisco Secure ACS for Windows Server Version 3.3
-
Preface
-
Overview
-
Deployment Considerations
-
Interface Configuration
-
Network Configuration
-
Shared Profile Components
-
User Group Management
-
User Management
-
System Configuration: Basic
-
System Configuration: Advanced
-
System Configuration: Authentication and Certificates
-
Logs and Reports
-
Administrators and Administrative Policy
-
User Databases
-
Network Admission Control
-
Unknown User Policy
-
User Group Mapping and Specification
-
Troubleshooting
-
TACACS+ Attribute-Value Pairs
-
RADIUS Attributes
-
CSUtil Database Utility
-
VPDN Processing
-
RDBMS Synchronization Import Definitions
-
Internal Architecture
-
Index
-
Feedback
Table Of Contents
Location of CSUtil.exe and Related Files
Displaying Command-Line Syntax
Backing Up Cisco Secure ACS with CSUtil.exe
Restoring Cisco Secure ACS with CSUtil.exe
Creating a CiscoSecure User Database
Creating a Cisco Secure ACS Database Dump File
Loading the Cisco Secure ACS Database from a Dump File
Compacting the CiscoSecure User Database
User and AAA Client Import Option
Importing User and AAA Client Information
User and AAA Client Import File Format
About User and AAA Client Import File Format
Exporting User List to a Text File
Exporting Group Information to a Text File
Exporting Registry Information to a Text File
User-Defined RADIUS Vendors and VSA Sets
About User-Defined RADIUS Vendors and VSA Sets
Adding a Custom RADIUS Vendor and VSA Set
Deleting a Custom RADIUS Vendor and VSA Set
Exporting Custom RADIUS Vendor and VSA Sets
About the RADIUS Vendor/VSA Import File
Example RADIUS Vendor/VSA Import File
Posture Validation Attribute Definition File
Exporting Posture Validation Attribute Definitions
Importing Posture Validation Attribute Definitions
Deleting a Posture Validation Attribute Definition
Default Posture Validation Attribute Definition File
CSUtil Database Utility
This appendix details the Cisco Secure Access Control Server (ACS) for Windows Server command-line utility, CSUtil.exe. Among its several functions, CSUtil.exe enables you to add, change, and delete users from a colon-delimited text file. You can also use the utility to add and delete AAA client configurations.
Note
You can accomplish similar tasks using the ACS System Backup, ACS System Restore, Database Replication, and RDBMS Synchronization features. For more information on these features, see "System Configuration: Advanced".
This chapter contains the following topics:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Location of CSUtil.exe and Related Files
When you install Cisco Secure ACS in the default location, CSUtil.exe is located in the following directory:
C:\Program Files\CiscoSecure ACS vX.X\Utilswhere X.X is the version of your Cisco Secure ACS software. Regardless of where you install Cisco Secure ACS, CSUtil.exe is located in the Utils directory.
Files generated by or accessed by CSUtil.exe are also located in the Utils directory.
CSUtil.exe Syntax
The syntax for the CSUtil.exe command is as follows:
CSUtil.exe [-q] [-c] [-d] [-g] [-i filename] [[-p] -l filename] [-e -number] [-b filename] [-r filename] [-f] [-n] [-u] [-x] [-y] [-listUDV] [-addUDV slot filename] [-delUDV slot] [-t -filepath full filepath] [-passwd password] {-a | -g group number | -u username | -f user list filepath}] [-addAVP filename] [-delAVP vendor-ID application-ID attribute-ID] [-dumpAVP filename]
Note
You can combine many of the options in a single use of CSUtil.exe. If you are new to using CSUtil.exe, we recommend performing only one option at a time, with the exception of those options, such as -p, that must be used in conjunction with other options.
Experienced CSUtil.exe users may find it useful to combine CSUtil.exe options, such as in the following example, which would first import AAA client configurations and then generate a dump of all Cisco Secure ACS internal data:
CSUtil.exe -i newnases.txt -dCSUtil.exe Options
CSUtil.exe can perform several actions. The options, listed below in alphabetical order, are detailed in later sections of this chapter.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Displaying Command-Line Syntax
CSUtil.exe displays command-line syntax for any one of the following reasons:
•
•
•
For more information about CSUtil.exe syntax, see CSUtil.exe Syntax.
To display command-line syntax for CSUtil.exe, follow these steps:
Step 1
Step 2
CSUtil.exe -xPress Enter.
CSUtil.exe displays its command-line syntax.
Backing Up Cisco Secure ACS with CSUtil.exe
You can use the -b option to create a system backup of all Cisco Secure ACS internal data. The resulting backup file has the same data as the backup files produced by the ACS Backup feature found in the HTML interface. For more information about the ACS Backup feature, see Cisco Secure ACS Backup.
Note
To back up Cisco Secure ACS with CSUtil.exe, follow these steps:
Step 1
Step 2
CSUtil.exe -b filenamewhere filename is the name of the backup file. Press Enter.
CSUtil.exe displays a confirmation prompt.
Step 3
CSUtil.exe generates a complete backup of all Cisco Secure ACS internal data, including user accounts and system configuration. This process may take a few minutes.
Note
Restoring Cisco Secure ACS with CSUtil.exe
You can use the -r option to restore all Cisco Secure ACS internal data. The backup file from which you restore Cisco Secure ACS can be one generated by the CSUtil.exe -b option or by the ACS Backup feature in the HTML interface.
Cisco Secure ACS backup files contain two types of data:
•
•
You can restore either user and group data or system configuration, or both. For more information about the ACS Backup feature, see Cisco Secure ACS Backup.
Note
To restore Cisco Secure ACS with CSUtil.exe, follow these steps:
Step 1
Step 2
•
CSUtil.exe -r all filenamewhere filename is the name of the backup file. Press Enter.
•
CSUtil.exe -r users filenamewhere filename is the name of the backup file. Press Enter.
•
CSUtil.exe -r config filenamewhere filename is the name of the backup file. Press Enter.
CSUtil.exe displays a confirmation prompt.
Step 3
CSUtil.exe restores the specified portions of your Cisco Secure ACS data. This process may take a few minutes.
Note
Creating a CiscoSecure User Database
You can use the -n option to create a CiscoSecure user database.
Note
Caution
To create a CiscoSecure user database, follow these steps:
Step 1
Step 2
Step 3
net stop csauthand press Enter.
The CSAuth service stops.
Step 4
CSUtil.exe -nand press Enter.
CSUtil.exe displays a confirmation prompt.
Step 5
The CiscoSecure user database is initialized. This process may take a few minutes.
Step 6
net start csauthand press Enter.
Creating a Cisco Secure ACS Database Dump File
You can use the -d option to dump all contents of the CiscoSecure user database into a text file. This provides a thorough and compressible backup of all Cisco Secure ACS internal data.
Using the -l option, you can reload the Cisco Secure ACS internal data from a dump file created by the -d option. For more information about the -l option, see Loading the Cisco Secure ACS Database from a Dump File.
Note
To dump all Cisco Secure ACS internal data into a text file, follow these steps:
Step 1
Step 2
net stop csauthand press Enter.
The CSAuth service stops.
Step 3
CSUtil.exe -dand press Enter.
CSUtil.exe displays a confirmation prompt.
Step 4
CSUtil.exe creates the dump.txt file. This process may take a few minutes.
Step 5
net start csauthand press Enter.
Loading the Cisco Secure ACS Database from a Dump File
You can use the -l option to overwrite all Cisco Secure ACS internal data from a dump text file. This option replaces the existing all Cisco Secure ACS internal data with the data in the dump text file. In effect, the -l option initializes all Cisco Secure ACS internal data before loading it from the dump text file. Dump text files are created using the -d option. While the -d option only produces dump text files that are named dump.txt, the -l option allows for loading renamed dump files. For more information about creating dump text files, see Creating a Cisco Secure ACS Database Dump File.
You can use the -p option in conjunction with the -l option to reset password-aging counters.
Note
To load all Cisco Secure ACS internal data from a text file, follow these steps:
Step 1
Step 2
net stop csauthand press Enter.
The CSAuth service stops.
Step 3
CSUtil.exe -l filenamewhere filename is the name of the dump file you want CSUtil.exe to use to load Cisco Secure ACS internal data. Press Enter.
CSUtil.exe displays a confirmation prompt for overwriting all Cisco Secure ACS internal data with the data in the dump text file.
Note
Step 4
CSUtil.exe initializes all Cisco Secure ACS internal data, and then loads Cisco Secure ACS with the information in the dump file specified. This process may take a few minutes.
Step 5
net start csauthand press Enter.
Compacting the CiscoSecure User Database
Like many relational databases, the CiscoSecure user database handles the deletion of records by marking deleted records as deleted but not removing the records from the database. Over time, your CiscoSecure user database may be substantially larger than is required by the number of users it contains. To reduce the CiscoSecure user database size, you can compact it periodically.
Compacting the CiscoSecure user database consists of using in conjunction three CSUtil.exe options:
•
•
•
Additionally, if you want to automate this process, consider using the -q option to suppress the confirmation prompts that otherwise appear before CSUtil.exe performs the -n and -l options.
Note
To compact the CiscoSecure user database, follow these steps:
Step 1
Step 2
net stop csauthand press Enter.
The CSAuth service stops.
Step 3
CSUtil.exe -d -n -lPress Enter.
Tip
If you do not use the -q option, CSUtil.exe displays a confirmation prompt for initializing the database and then for loading the database. For more information about the effects of the -n option, see Creating a CiscoSecure User Database. For more information about the effects of the -l option, see Loading the Cisco Secure ACS Database from a Dump File.
Step 4
CSUtil.exe dumps all Cisco Secure ACS internal data to dump.txt, initializes the CiscoSecure user database, and reloads all Cisco Secure ACS internal data from dump.txt. This process may take a few minutes.
Step 5
net start csauthand press Enter.
User and AAA Client Import Option
The -i option enables you to update Cisco Secure ACS with data from a colon-delimited text file. You can also update AAA client definitions.
For user accounts, you can add users, change user information such as passwords, or delete users. For AAA client definitions, you can add or delete AAA clients.
This section contains the following topics:
•
•
–
Importing User and AAA Client Information
To import user or AAA client information, follow these steps:
Step 1
Step 2
Step 3
Step 4
Step 5
CSUtil.exe -i filenamewhere filename is the name of the import text file you want CSUtil.exe to use to update Cisco Secure ACS. Press Enter.
CSUtil.exe displays a confirmation prompt for updating the database.
Step 6
Cisco Secure ACS is updated with the information in the import text file specified. This process may take a few minutes.
If the import text file contained AAA client configuration data, CSUtil.exe warns you that you need to restart CSTacacs and CSRadius for these changes to take effect.
Step 7
a.
net stop csradiusand press Enter.
The CSRadius service stops.
b.
net start csradiusand press Enter.
Step 8
a.
net stop cstacacsand press Enter.
The CSTacacs service stops.
b.
net start cstacacsand press Enter.
User and AAA Client Import File Format
This section contains the following topics:
•
About User and AAA Client Import File Format
The import file can contain six different line types, as discussed in following topics. The first line of the import file must be one of the tokens defined in Table D-1.
Each line of a CSUtil.exe import file is a series of colon-separated tokens. Some of the tokens are followed by values. Values, like tokens, are colon-delimited. For tokens that require values, CSUtil.exe expects the value of the token to be in the colon-delimited field immediately following the token.
ONLINE or OFFLINE Statement
CSUtil.exe requires an ONLINE or OFFLINE token in an import text file. The file must begin with a line that contains only an ONLINE or OFFLINE token. The ONLINE and OFFLINE tokens are described in Table D-1.
ADD Statements
ADD statements are optional. Only the ADD token and its value are required to add a user to Cisco Secure ACS. The valid tokens for ADD statements are listed in Table D-2.
Note
For example, the following ADD statement would create an account with the username "John", assign it to Group 3, and specify that John should be authenticated by the CiscoSecure user database with the password "closedmondays":
ADD:John:PROFILE:3:CSDB:closedmondaysUPDATE Statements
UPDATE statements are optional. They make changes to existing user accounts. Only the UPDATE token and its value are required by CSUtil.exe, but if no other tokens are included, no changes are made to the user account. You can use the UPDATE statement to update the group a user is assigned to or to update which database Cisco Secure ACS uses to authenticate the user. The valid tokens for UPDATE statements are listed in Table D-3.
For example, the following UPDATE statement causes CSUtil.exe to update the account with username "John", assign it to Group 50, specify that John should be authenticated by a UNIX-encrypted password, with a separate CHAP password "goodoldchap":
UPDATE:John:PROFILE:50:CSDB_UNIX:3Al3qf9:CHAP:goodoldchapDELETE Statements
DELETE statements are optional. The DELETE token and its value are required to delete a user account from Cisco Secure ACS. The DELETE token, detailed in Table D-4, is the only token in a DELETE statement.
Table D-4 UPDATE Statement Tokens
DELETE
Yes
username
The name of the user account that is to be deleted.
For example, the following DELETE statement causes CSUtil.exe to permanently remove the account with username "John" from the CiscoSecure user database:
DELETE:JohnADD_NAS Statements
ADD_NAS statements are optional. The ADD_NAS, IP, KEY, and VENDOR tokens and their values are required to add a AAA client definition to Cisco Secure ACS. The valid tokens for ADD_NAS statements are listed in Table D-5.
Table D-5 ADD_NAS Statement Tokens
ADD_NAS
Yes
AAA client name
The name of the AAA client that is to be added.
IP
Yes
IP address
The IP address of the AAA client being added. Use a pipe (|) between IP addresses to import devices with multiple IPs.
KEY
Yes
Shared secret
The shared secret for the AAA client.
VENDOR
Yes
See description
The authentication protocol the AAA client uses. For RADIUS, this includes the VSA.
Note
•
•
•
•
•
•
•
•
•
•
•
NDG
No
NDG name
The name of the Network Device Group to which the AAA client is to be added.
SINGLE_CON
No
Y or N
For AAA clients using TACACS+ only, the value set for this TOKEN specifies whether the Single Connect TACACS+ AAA Client option is enabled. For more information, see Adding a AAA Client.
KEEPALIVE
No
Y or N
For AAA clients using TACACS+ only, the value set for this token specifies whether the Log Update/Watchdog Packets from this Access Server option is enabled. For more information, see Adding a AAA Client.
For example, the following ADD_NAS statement causes CSUtil.exe to add a AAA client with the name "SVR2-T+", using TACACS+ with the single connection and keep alive packet options enabled:
ADD_NAS:SVR2-T+:IP:IP address:KEY:shared secret:VENDOR:"TACACS+ (Cisco IOS)":NDG:"East Coast":SINGLE_CON:Y:KEEPALIVE:YDEL_NAS Statements
DEL_NAS statements are optional. The DEL_NAS token, detailed in Table D-6, is the only token in a DEL_NAS statement. DEL_NAS statements delete AAA client definitions from Cisco Secure ACS.
Table D-6 DEL_NAS Statement Tokens
DEL_NAS
Yes
AAA client name
The name of the AAA client that is to be deleted.
For example, the following DEL_NAS statement causes CSUtil.exe to delete a AAA client with the name "SVR2-T+":
DEL_NAS:SVR2-T+Import File Example
The following is an example import text file:
OFFLINE ADD:user01:CSDB:userpassword:PROFILE:1 ADD:user02:EXT_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 UPDATE:foobar:PROFILE:10 DELETE:paul ADD_NAS:SVR2-T+:IP:209.165.202.136:KEY:A87il032bzg:VENDOR:"TACACS+ (Cisco IOS)":NDG:"East Coast" DEL_NAS:SVR16-RADExporting User List to a Text File
You can use the -u option to export a list of all users in the CiscoSecure user database to a text file named users.txt. The users.txt file organizes users by group. Within each group, users are listed in the order that their user accounts were created in the CiscoSecure user database. For example, if accounts were created for Pat, Dana, and Lloyd, in that order, users.txt lists them in that order as well, rather than alphabetically.
Note
To export user information from the CiscoSecure user database into a text file, follow these steps:
Step 1
Step 2
net stop csauthand press Enter.
The CSAuth service stops.
Step 3
CSUtil.exe -uand press Enter.
CSUtil.exe exports information for all users in the CiscoSecure user database to a file named users.txt.
Step 4
net start csauthand press Enter.
Exporting Group Information to a Text File
You can use the -g option to export group configuration data, including device command sets, from the CiscoSecure user database to a text file named groups.txt. The groups.txt file is useful primarily for debugging purposes while working with the TAC.
Note
To export group information from the CiscoSecure user database to a text file, follow these steps:
Step 1
Step 2
net stop csauthand press Enter.
The CSAuth service stops.
Step 3
CSUtil.exe -gand press Enter.
CSUtil.exe exports information for all groups in the CiscoSecure user database to a file named groups.txt.
Step 4
net start csauthand press Enter.
Exporting Registry Information to a Text File
You can use the -y option to export Windows Registry information for Cisco Secure ACS. CSUtil.exe exports the Registry information to a file named setup.txt. The setup.txt file is primarily useful for debugging purposes while working with the TAC.
To export Registry information from Cisco Secure ACS to a text file, follow these steps:
Step 1
Step 2
CSUtil.exe -yand press Enter.
CSUtil.exe exports Windows Registry information for Cisco Secure ACS to a file named setup.txt.
Decoding Error Numbers
You can use the -e option to decode error numbers found in Cisco Secure ACS service logs. These are error codes internal to Cisco Secure ACS. For example, the CSRadius log could contain a message similar to the following:
CSRadius/Logs/RDS.log:RDS 05/22/2001 10:09:02 E 2152 4756 Error -1087 authenticating geddy - no NAS response sentIn this example, the error code number that you could use CSUtil.exe to decode is "-1087":
C:\Program Files\CiscoSecure ACS vx.x\Utils: CSUtil.exe -e -1087 CSUtil v3.0(1.14), Copyright 1997-2001, Cisco Systems Inc Code -1087 : External database reported error during authentication
Note
For more information about Cisco Secure ACS service logs, see Service Logs.
To decode an error number from a Cisco Secure ACS service log, follow these steps:
Step 1
Step 2
CSUtil.exe -e -numberwhere number is the error number found in the Cisco Secure ACS service log. Press Enter.
Note
CSUtil.exe displays the text message equivalent to the error number specified.
Recalculating CRC Values
The -c option is for use by the TAC. Its purpose is to resolve CRC (cyclical redundancy check) value conflicts between files manually copied into your Cisco Secure ACS directories and the values recorded in the Windows Registry.
Note
User-Defined RADIUS Vendors and VSA Sets
This section provides information and procedures about user-defined RADIUS vendors and VSAs.
This section contains the following topics:
•
•
•
•
•
•
About User-Defined RADIUS Vendors and VSA Sets
In addition to supporting a set of predefined RADIUS vendors and vendor-specific attributes (VSAs), Cisco Secure ACS supports RADIUS vendors and VSAs that you define. We recommend that you use RDBMS Synchronization to add and configure custom RADIUS vendors; however, you can use CSUtil.exe to accomplish the same custom RADIUS vendor and VSA configurations that you can accomplish using RDBMS Synchronization. Custom RADIUS vendor and VSA configuration created by either of these two features—RDBMS Synchronization or CSUtil.exe—can be modified by the other feature. Choosing one feature for configuring custom RADIUS vendors and VSAs does not preclude using the other feature. For more information about RDMBS Synchronization, see RDBMS Synchronization.
Vendors you add must be IETF-compliant; therefore, all VSAs that you add must be sub-attributes of IETF RADIUS attribute number 26. You can define up to ten custom RADIUS vendors, numbered 0 (zero) through 9. CSUtil.exe allows only one instance of any given vendor, as defined by the unique vendor IETF ID number and by the vendor name.
Note
Adding a Custom RADIUS Vendor and VSA Set
You can use the -addUDV option to add up to ten custom RADIUS vendors and VSA sets to Cisco Secure ACS. Each RADIUS vendor and VSA set is added to one of ten possible user-defined RADIUS vendor slots.
Note
Before You Begin
•
•
•
To add a custom RADIUS VSA to Cisco Secure ACS, follow these steps:
Step 1
Step 2
CSUtil.exe -addUDV slot-number filenamewhere slot-number is an unused Cisco Secure ACS RADIUS vendor slot and filename is the name of a RADIUS vendor/VSA import file. The filename can include a relative or absolute path to the RADIUS vendor/VSA import file. Press Enter.
For example, to add the RADIUS vendor defined in d:\acs\myvsa.ini to slot 5, the command would be:
CSUtil.exe -addUDV 5 d:\acs\myvsa.iniCSUtil.exe displays a confirmation prompt.
Step 3
CSUtil.exe halts Cisco Secure ACS services, parses the vendor/VSA input file, and adds the new RADIUS vendor and VSAs to Cisco Secure ACS. This process may take a few minutes. After it is complete, CSUtil.exe restarts Cisco Secure ACS services.
Note
Deleting a Custom RADIUS Vendor and VSA Set
You can use the -delUDV option to delete a custom RADIUS vendor from Cisco Secure ACS.
Note
Before You Begin
Verify that, in the Network Configuration section of the Cisco Secure ACS HTML interface, no AAA client uses the RADIUS vendor. For more information about configuring AAA clients, see AAA Client Configuration.
Verify that your RADIUS accounting log does not contain attributes from the RADIUS vendor you want to delete. For more information about configuring your RADIUS accounting log, see Accounting Logs.
To delete a custom RADIUS vendor and VSA set from Cisco Secure ACS, follow these steps:
Step 1
Step 2
CSUtil.exe -delUDV slot-numberwhere slot-number is the slot containing the RADIUS vendor that you want to delete. Press Enter.
Note
CSUtil.exe displays a confirmation prompt.
Step 3
CSUtil.exe displays a second confirmation prompt.
Step 4
CSUtil.exe halts Cisco Secure ACS services, deletes the specified RADIUS vendor from Cisco Secure ACS. This process may take a few minutes. After it is complete, CSUtil.exe restarts Cisco Secure ACS services.
Listing Custom RADIUS Vendors
You can use the -listUDV option to determine what custom RADIUS vendors are defined in Cisco Secure ACS. This option also enables you to determine which of the ten possible custom RADIUS vendor slots are in use and which RADIUS vendor occupies each used slot.
To list all custom RADIUS vendors defined in Cisco Secure ACS, follow these steps:
Step 1
Step 2
CSUtil.exe -listUDVPress Enter.
CSUtil.exe lists each user-defined RADIUS vendor slot in slot number order. CSUtil.exe lists slots that do not contain a custom RADIUS vendor as "Unassigned". An unassigned slot is empty. You can add a custom RADIUS vendor to any slot listed as "Unassigned".
Exporting Custom RADIUS Vendor and VSA Sets
You can export all custom RADIUS vendor and VSA sets to files. Each vendor and VSA set is saved to a separate file. The files created by this option are in the same format as RADIUS vendor/VSA import files. This option is particularly useful if you need to modify a custom RADIUS vendor and VSA set and you have misplaced the original file used to import the set.
Note
Cisco Secure ACS places all exported vendor/VSA files in a subdirectory of the directory containing CSUtil.exe. The subdirectory is named System UDVs. For more information about the location of CSUtil.exe, see Location of CSUtil.exe and Related Files.
Each exported vendor/VSA file is named UDV_n.ini, where n is the slot number currently occupied by the custom RADIUS vendor and VSA set. For example, if vendor Widget occupies slot 4, the exported file created by CSUtil.exe is UDV_4.ini.
To export custom RADIUS vendor and VSA sets to files, follow these steps:
Step 1
Step 2
CSUtil.exe -dumpUDVPress Enter.
For each custom RADIUS vendor and VSA set currently configured in Cisco Secure ACS, CSUtil.exe writes a file in the System UDVs subdirectory.
RADIUS Vendor/VSA Import File
To import a custom RADIUS vendor and VSA set into Cisco Secure ACS, you must define the RADIUS vendor and VSA set in an import file. This section details the format and content of RADIUS VSA import files.
We recommend that you archive RADIUS vendor/VSA import files. During upgrades, the Utils directory, where CSUtil.exe is located, is replaced, including all its contents. Backing up RADIUS vendor/VSA import files ensures that you can recover your custom RADIUS vendors and VSAs after reinstallation or upgrading to a later release.
This section contains the following topics:
•
•
•
About the RADIUS Vendor/VSA Import File
RADIUS Vendor/VSA import files use a Windows .ini file format. Each RADIUS vendor/VSA import file comprises three types of sections, detailed in Table D-7. Each section comprises a section header and a set of keys and values. The order of the sections in the RADIUS vendor/VSA import file is irrelevant.
Table D-7 RADIUS VSA Import File Section Types
Vendor and VSA set definition
Yes
1
Defines the RADIUS vendor and VSA set. For more information, see Vendor and VSA Set Definition.
Attribute definition
Yes
1 to 255
Defines a single attribute of the VSA set. For more information, see Attribute Definition.
Enumeration
No
0 to 255
Defines enumerations for attributes with integer data types. For more information, see Enumeration Definition.
Vendor and VSA Set Definition
Each RADIUS vendor/VSA import file must have one vendor and VSA set section. The section header must be "[User Defined Vendor]". Table D-8 lists valid keys for the vendor and VSA set section.
For example, the following vendor and VSA set section defines the vendor "Widget", whose IETF-assigned vendor number is 9999. Vendor Widget has 4 VSAs (thus requiring 4 attribute definition sections):
[User Defined Vendor] Name=Widget IETF Code=9999 VSA 1=widget-encryption VSA 2=widget-admin-interface VSA 3=widget-group VSA 4=widget-admin-encryptionAttribute Definition
Each RADIUS vendor/VSA import file must have one attribute definition section for each attribute defined in the vendor and VSA set section. The section header of each attribute definition section must match the attribute name defined for that attribute in the vendor and VSA set section. Table D-8 lists the valid keys for an attribute definition section.
Table D-9 Attribute Definition Keys
Type
Yes
See Description
The data type of the attribute. It must be one of the following:
•
•
•
If the attribute is an integer, the Enums key is valid.
Profile
Yes
See Description
The attribute profile defines if the attribute is used for authorization or accounting (or both). At least one of the following two values must be present in the Profile key definition:
•
•
In addition, you can use the value "MULTI" to allow several instances of the attribute per RADIUS message.
Combinations are valid. For example:
Profile=MULTI OUTor
Profile=IN OUTEnums
No (only valid when the TYPE value is INTEGER)
Enumera-
tions section nameThe name of the enumeration section.
Note
For example, the following attribute definition section defines the widget-encryption VSA, which is an integer used for authorization, and for which enumerations exist in the Encryption-Types enumeration section:
[widget-encryption] Type=INTEGER Profile=OUT Enums=Encryption-TypesEnumeration Definition
Enumeration definitions enable you to associate a text-based name for each valid numeric value of an integer-type attribute. In the Group Setup and User Setup sections of the Cisco Secure ACS HTML interface, the text values you define appear in lists associated with the attributes that use the enumerations. Enumeration definition sections are required only if an attribute definition section references them. Only attributes that are integer-type attributes can reference an enumeration definition section.
The section header of each enumeration definition section must match the value of an Enums key that references it. An enumeration definition section can be referenced by more than one Enums key, thus allowing for reuse of common enumeration definitions. An enumeration definition section can have up to 1000 keys.
Table D-10 lists the valid keys for an enumeration definition section.
For example, the following enumerations definition section defines the Encryption-Types enumeration, which associates the string value 56-bit with the integer 0 and the string value 128-bit with the integer 1:
[Encryption-Types] 0=56-bit 1=128-bitExample RADIUS Vendor/VSA Import File
The example RADIUS vendor/VSA import file, below, defines the vendor Widget, whose IETF number is 9999. The vendor Widget has 5 VSAs. Of those attributes, 4 are for authorization and one is for accounting. Only one attribute can have multiple instances in a single RADIUS message. Two attributes have enumerations for their valid integer values and they share the same enumeration definition section.
[User Defined Vendor] Name=Widget IETF Code=9999 VSA 1=widget-encryption VSA 2=widget-admin-interface VSA 3=widget-group VSA 4=widget-admin-encryption VSA 5=widget-remote-address [widget-encryption] Type=INTEGER Profile=OUT Enums=Encryption-Types [widget-admin-interface] Type=IPADDR Profile=OUT [widget-group] Type=STRING Profile=MULTI OUT [widget-admin-encryption] Type=INTEGER Profile=OUT Enums=Encryption-Types [widget-remote-address] Type=STRING Profile=IN [Encryption-Types] 0=56-bit 1=128-bit 2=256-bitPAC File Generation
You can use the -t option to generate PAC files for use with EAP-FAST clients. For more information about PACs and EAP-FAST, see EAP-FAST Authentication.
This section contains the following topics:
•
PAC File Options and Examples
When you use the -t option generate PAC files with CSUtil.exe, you have the following additional options.
•
–
Note
–
Note
–
Tip
–
Lists of usernames should contain one username per line with no additional spaces or other characters.
For example, if list.txt in d:\temp\pacs contains the following usernames:
seaniemop jwiedman echamberlainand you ran CSUtil.exe -t -f d:\temp\pacs\list.txt, CSUtil.exe generates three PAC files: seaniemop.pac, jwiedman.pac, and echamberlain.pac.
Tip
•
Note
PAC passwords can contain any character, are between four and 128 characters long, and case sensitive. While CSUtil.exe does not enforce strong password rules, we recommend that you use a strong password, that is, your PAC password should:
–
–
–
–
Generating PAC Files
Note
For more information about PACs, see About PACs.
To generate PAC files, follow these steps:
Step 1
•
•
•
Step 2
Step 3
CSUtil.exe -t additional argumentswhere additional arguments represents at least one option for specifying which users to generate PAC files for. You can also use the options to specify filepath and password.
Press Enter.
CSUtil.exe generates the PAC files for each user specified. The PAC files are named with the username plus a ".pac" file extension. For example, a PAC file for the username seaniemop would be seaniemop.pac and a PAC file for the domain-qualified username ENGINEERING\augustin would be ENGINEERING_augustin.pac.
If you specified a filepath, the PAC files are saved where you specified. You can distribute the PAC files to the applicable end-user clients.
Posture Validation Attributes
You can use CSUtil.exe to export, add, and delete posture validation attributes, which are essential to Network Admission Control (NAC). For more information about NAC, see "Network Admission Control".
This section contains the following topics:
•
•
•
•
•
Posture Validation Attribute Definition File
A posture validation attribute definition file is a text file that contains one or more posture validation attribute definitions. Each definition consists of a definition header and several values, described below. For an example of the contents of a posture validation attribute definition file, see Default Posture Validation Attribute Definition File.
With the exception of the attribute definition header, each attribute definition value must be formatted as follows:
name=value
where name is the value name and value is a string or integer, as specified in the list below.
Tip
Example D-1 shows an example of a posture validation attribute definition, including a comment after the attribute definition:
Example D-1 Example Attribute Definition
[attr#0] vendor-id=9 vendor-name=Cisco application-id=1 application-name=PA attribute-id=00001 attribute-name=Application-Posture-Token attribute-profile=out attribute-type=unsigned integer ; attribute 1 is reserved for the APTA posture validation attribute is uniquely defined by the combination of its vendor ID, application ID, and attribute ID. The following list provides details of these values and of each line required in an attribute definition:
•
Tip
•
Vendor IDs have one or more applications associated with them, identified by the application-id value.
•
Note
•
•
Note
•
Note
•
•
–
–
–
•
Valid values of attribute-type are:
–
–
–
–
–
–
–
–
For more information about attribute data types, see NAC Attribute Data Types.
Exporting Posture Validation Attribute Definitions
The -dumpAVP option exports the current posture validation attributes to an attribute definition file. For an explanation of the contents of a posture validation attribute definition file, see Posture Validation Attribute Definition File. For an example of an attribute definition file, see Default Posture Validation Attribute Definition File.
To export posture validation attributes, follow these steps:
Step 1
Step 2
CSUtil.exe -dumpavp filenamewhere filename is the name of the file in which you want CSUtil.exe to write all attribute definitions. Press Enter.
Tip
Step 3
•
Tip
•
CSUtil.exe writes all posture validation attribute definitions in the file specified. To view the contents of the file, use the text editor of your choice.
Importing Posture Validation Attribute Definitions
The -addAVP option imports into Cisco Secure ACS posture validation attribute definitions from an attribute definition file. For an explanation of the contents of a posture validation attribute definition file, see Posture Validation Attribute Definition File. For an example of an attribute definition file, see Default Posture Validation Attribute Definition File.
Before You Begin
Because completing this procedure requires restarting the CSAuth service, which temporarily suspends authentication services, consider performing this procedure when demand for Cisco Secure ACS services is low.
Use the steps in Exporting Posture Validation Attribute Definitions, to create a backup of posture validation attribute definitions. You can also use the exported attribute definition file to double-check the vendor ID, application ID, and attribute ID of current posture validation attributes.
To import posture validation attributes, follow these steps:
Step 1
Step 2
Step 3
CSUtil.exe -addavp filenamewhere filename is the name of the file in which you want CSUtil.exe to write all attribute definitions. Press Enter.
Tip
CSUtil.exe adds or modifies the attributes specified in the file. An example of a successful addition of nine posture validation attributes follows:
C:.../Utils 21: csutil -addavp myavp.txt CSUtil v3.3(1.6), Copyright 1997-2001, Cisco Systems Inc Attribute 9876:1:11 (Calliope) added to registry Attribute 9876:1:3 (Clio) added to registry Attribute 9876:1:4 (Erato) added to registry Attribute 9876:1:5 (Euterpe) added to registry Attribute 9876:1:6 (Melpomene) added to registry Attribute 9876:1:7 (Polyhymnia) added to registry Attribute 9876:1:8 (Terpsichore) added to registry Attribute 9876:1:9 (Thalia) added to registry Attribute 9876:1:10 (Urania) added to registry AVPs from 'myavp.txt' were successfully addedStep 4
Caution
To restart the CSAuth, CSLog, and CSAdmin services, enter the following commands at the command prompt, allowing the computer time to perform each command:
net stop csauth net start csauth net stop cslog net start cslog net stop csadmin net start csadminCisco Secure ACS begins using the imported posture validation attributes. Attributes that have an attribute type of in or in out are available in the HTML interface when you define local policy rules.
Deleting a Posture Validation Attribute Definition
The -delAVP option deletes a single posture validation attribute from Cisco Secure ACS.
Before You Begin
Because completing this procedure requires restarting the CSAuth service, which temporarily suspends authentication services, consider performing this procedure when demand for Cisco Secure ACS services is low.
Use the steps in Exporting Posture Validation Attribute Definitions, to create a backup of posture validation attribute definitions. You can also use the exported attribute definition file to double-check the vendor ID, application ID, and attribute ID of the posture validation attribute you want to delete.
To delete posture validation attributes, follow these steps:
Step 1
Step 2
CSUtil.exe -delavp vendor-ID application-ID attribute-IDFor more information about vendor, application, and attribute IDs, see Posture Validation Attribute Definition File.
CSUtil.exe prompts you to confirm the attribute deletion.
Step 3
•
Tip
•
CSUtil.exe deletes from its internal database the posture validation attribute you specified. In the following example, CSUtil.exe deleted an attribute with a vendor ID of 9876, an application ID of 1, and an attribute ID of 1.
CSUtil v3.3, Copyright 1997-2004, Cisco Systems Inc Are you sure you want to delete vendor 9876; application 1; attribute 1? (y/n) y Vendor 9876; application 1; attribute 1 was successfully deletedStep 4
Caution
To restart the CSAuth, CSLog, and CSAdmin services, enter the following commands at the command prompt, allowing the computer time to perform each command:
net stop csauth net start csauth net stop cslog net start cslog net stop csadmin net start csadminDeleted posture validation attributes no longer are available in Cisco Secure ACS.
Default Posture Validation Attribute Definition File
Example D-2 provides the definitions for the posture validation attributes that we provide with Cisco Secure ACS. Should you need to reset the default attributes to their original definitions, use Example D-2 to create a posture validation attribute definition file. For more information about the format of an attribute definition file, see Posture Validation Attribute Definition File.
Example D-2 Default Posture Validation Attribute Definitions
[attr#0] vendor-id=9 vendor-name=Cisco application-id=1 application-name=PA attribute-id=00001 attribute-name=Application-Posture-Token attribute-profile=out attribute-type=unsigned integer [attr#1] vendor-id=9 vendor-name=Cisco application-id=1 application-name=PA attribute-id=00002 attribute-name=System-Posture-Token attribute-profile=out attribute-type=unsigned integer [attr#2] vendor-id=9 vendor-name=Cisco application-id=1 application-name=PA attribute-id=00003 attribute-name=PA-Name attribute-profile=in out attribute-type=string [attr#3] vendor-id=9 vendor-name=Cisco application-id=1 application-name=PA attribute-id=00004 attribute-name=PA-Version attribute-profile=in out attribute-type=version [attr#4] vendor-id=9 vendor-name=Cisco application-id=1 application-name=PA attribute-id=00005 attribute-name=OS-Type attribute-profile=in out attribute-type=string [attr#5] vendor-id=9 vendor-name=Cisco application-id=1 application-name=PA attribute-id=00006 attribute-name=OS-Version attribute-profile=in out attribute-type=version [attr#6] vendor-id=9 vendor-name=Cisco application-id=1 application-name=PA attribute-id=00007 attribute-name=PA-User-Notification attribute-profile=out attribute-type=string [attr#7] vendor-id=9 vendor-name=Cisco application-id=2 application-name=Host attribute-id=00001 attribute-name=Application-Posture-Token attribute-profile=out attribute-type=unsigned integer [attr#8] vendor-id=9 vendor-name=Cisco application-id=2 application-name=Host attribute-id=00002 attribute-name=System-Posture-Token attribute-profile=out attribute-type=unsigned integer [attr#9] vendor-id=9 vendor-name=Cisco application-id=2 application-name=Host attribute-id=00006 attribute-name=ServicePacks attribute-profile=in attribute-type=string [attr#10] vendor-id=9 vendor-name=Cisco application-id=2 application-name=Host attribute-id=00007 attribute-name=HotFixes attribute-profile=in attribute-type=string [attr#11] vendor-id=9 vendor-name=Cisco application-id=2 application-name=Host attribute-id=00008 attribute-name=HostFQDN attribute-profile=in attribute-type=string [attr#12] vendor-id=9 vendor-name=Cisco application-id=5 application-name=HIP attribute-id=00001 attribute-name=Application-Posture-Token attribute-profile=out attribute-type=unsigned integer [attr#13] vendor-id=9 vendor-name=Cisco application-id=5 application-name=HIP attribute-id=00002 attribute-name=System-Posture-Token attribute-profile=out attribute-type=unsigned integer [attr#14] vendor-id=9 vendor-name=Cisco application-id=5 application-name=HIP attribute-id=00005 attribute-name=CSAVersion attribute-profile=in attribute-type=version [attr#15] vendor-id=9 vendor-name=Cisco application-id=5 application-name=HIP attribute-id=00009 attribute-name=CSAOperationalState attribute-profile=in attribute-type=unsigned integer [attr#16] vendor-id=9 vendor-name=Cisco application-id=5 application-name=HIP attribute-id=00011 attribute-name=TimeSinceLastSuccessfulPoll attribute-profile=in attribute-type=unsigned integer [attr#17] vendor-id=9 vendor-name=Cisco application-id=5 application-name=HIP attribute-id=32768 attribute-name=CSAMCName attribute-profile=in attribute-type=string [attr#18] vendor-id=9 vendor-name=Cisco application-id=5 application-name=HIP attribute-id=32769 attribute-name=CSAStates attribute-profile=in attribute-type=string [attr#19] vendor-id=393 vendor-name=Symantec application-id=3 application-name=AV attribute-id=00001 attribute-name=Application-Posture-Token attribute-profile=out attribute-type=unsigned integer [attr#20] vendor-id=393 vendor-name=Symantec application-id=3 application-name=AV attribute-id=00002 attribute-name=System-Posture-Token attribute-profile=out attribute-type=unsigned integer [attr#21] vendor-id=393 vendor-name=Symantec application-id=3 application-name=AV attribute-id=00003 attribute-name=Software-Name attribute-profile=in out attribute-type=string [attr#22] vendor-id=393 vendor-name=Symantec application-id=3 application-name=AV attribute-id=00004 attribute-name=Software-ID attribute-profile=in out attribute-type=unsigned integer [attr#23] vendor-id=393 vendor-name=Symantec application-id=3 application-name=AV attribute-id=00005 attribute-name=Software-Version attribute-profile=in out attribute-type=version [attr#24] vendor-id=393 vendor-name=Symantec application-id=3 application-name=AV attribute-id=00006 attribute-name=Scan-Engine-Version attribute-profile=in out attribute-type=version [attr#25] vendor-id=393 vendor-name=Symantec application-id=3 application-name=AV attribute-id=00007 attribute-name=Dat-Version attribute-profile=in out attribute-type=version [attr#26] vendor-id=393 vendor-name=Symantec application-id=3 application-name=AV attribute-id=00008 attribute-name=Dat-Date attribute-profile=in out attribute-type=date [attr#27] vendor-id=393 vendor-name=Symantec application-id=3 application-name=AV attribute-id=00009 attribute-name=Protection-Enabled attribute-profile=in out attribute-type=unsigned integer [attr#28] vendor-id=393 vendor-name=Symantec application-id=3 application-name=AV attribute-id=00010 attribute-name=Action attribute-profile=out attribute-type=string [attr#29] vendor-id=3401 vendor-name=NAI application-id=3 application-name=AV attribute-id=00001 attribute-name=Application-Posture-Token attribute-profile=out attribute-type=unsigned integer [attr#30] vendor-id=3401 vendor-name=NAI application-id=3 application-name=AV attribute-id=00002 attribute-name=System-Posture-Token attribute-profile=out attribute-type=unsigned integer [attr#31] vendor-id=3401 vendor-name=NAI application-id=3 application-name=AV attribute-id=00003 attribute-name=Software-Name attribute-profile=in out attribute-type=string [attr#32] vendor-id=3401 vendor-name=NAI application-id=3 application-name=AV attribute-id=00004 attribute-name=Software-ID attribute-profile=in out attribute-type=unsigned integer [attr#33] vendor-id=3401 vendor-name=NAI application-id=3 application-name=AV attribute-id=00005 attribute-name=Software-Version attribute-profile=in out attribute-type=version [attr#34] vendor-id=3401 vendor-name=NAI application-id=3 application-name=AV attribute-id=00006 attribute-name=Scan-Engine-Version attribute-profile=in out attribute-type=version [attr#35] vendor-id=3401 vendor-name=NAI application-id=3 application-name=AV attribute-id=00007 attribute-name=Dat-Version attribute-profile=in out attribute-type=version [attr#36] vendor-id=3401 vendor-name=NAI application-id=3 application-name=AV attribute-id=00008 attribute-name=Dat-Date attribute-profile=in out attribute-type=date [attr#37] vendor-id=3401 vendor-name=NAI application-id=3 application-name=AV attribute-id=00009 attribute-name=Protection-Enabled attribute-profile=in out attribute-type=unsigned integer [attr#38] vendor-id=3401 vendor-name=NAI application-id=3 application-name=AV attribute-id=00010 attribute-name=Action attribute-profile=out attribute-type=string [attr#39] vendor-id=6101 vendor-name=Trend application-id=3 application-name=AV attribute-id=00001 attribute-name=Application-Posture-Token attribute-profile=out attribute-type=unsigned integer [attr#40] vendor-id=6101 vendor-name=Trend application-id=3 application-name=AV attribute-id=00002 attribute-name=System-Posture-Token attribute-profile=out attribute-type=unsigned integer [attr#41] vendor-id=6101 vendor-name=Trend application-id=3 application-name=AV attribute-id=00003 attribute-name=Software-Name attribute-profile=in out attribute-type=string [attr#42] vendor-id=6101 vendor-name=Trend application-id=3 application-name=AV attribute-id=00004 attribute-name=Software-ID attribute-profile=in out attribute-type=unsigned integer [attr#43] vendor-id=6101 vendor-name=Trend application-id=3 application-name=AV attribute-id=00005 attribute-name=Software-Version attribute-profile=in out attribute-type=version [attr#44] vendor-id=6101 vendor-name=Trend application-id=3 application-name=AV attribute-id=00006 attribute-name=Scan-Engine-Version attribute-profile=in out attribute-type=version [attr#45] vendor-id=6101 vendor-name=Trend application-id=3 application-name=AV attribute-id=00007 attribute-name=Dat-Version attribute-profile=in out attribute-type=version [attr#46] vendor-id=6101 vendor-name=Trend application-id=3 application-name=AV attribute-id=00008 attribute-name=Dat-Date attribute-profile=in out attribute-type=date [attr#47] vendor-id=6101 vendor-name=Trend application-id=3 application-name=AV attribute-id=00009 attribute-name=Protection-Enabled attribute-profile=in out attribute-type=unsigned integer [attr#48] vendor-id=6101 vendor-name=Trend application-id=3 application-name=AV attribute-id=00010 attribute-name=Action attribute-profile=out attribute-type=string [attr#49] vendor-id=10000 vendor-name=out application-id=1 application-name=CNAC attribute-id=00001 attribute-name=Application-Posture-Token attribute-profile=out attribute-type=string [attr#50] vendor-id=10000 vendor-name=out application-id=1 application-name=CNAC attribute-id=00002 attribute-name=System-Posture-Token attribute-profile=out attribute-type=string [attr#51] vendor-id=10000 vendor-name=out application-id=1 application-name=CNAC attribute-id=00003 attribute-name=Reason attribute-profile=out attribute-type=string
