Using the Command-Line Administrator Interface

The CiscoSecure ACS command-line interface (CLI) enables the system administrator to carry out simple CiscoSecure administration tasks from a UNIX command line.

Using this CLI, the system administrator can either issue single CiscoSecure administration commands and arguments from the UNIX shell or create scripts that execute a sequence of commands.

The following commands are included in this chapter:

• AddProfile

• DeleteProfile

• ViewProfile

• ChangeParent

• ChangePassword

• UpdatePassword

Preparing to Run the CLI Remotely

If you run the CiscoSecure ACS CLI from a remote workstation, the data stream between the CLI and the ACS database server is encrypted.

Prepare the remote workstation as follows:

Step 1 Copy the /CLI directory from the host where you installed the CiscoSecure ACS to the remote workstation where you want to run the CLI.

Step 2 Install Java 1.1 or later on the remote workstation.

Step 3 Set an environment variable, JAVA_HOME, to the root directory where Java is installed.

For example, if Java was installed on /export/home/java, JAVA_HOME should be set to /export/home/java.

Caution

If you install the CiscoSecure ACS CLI on a remote workstation, be sure that workstation is in a secure location or is set up in some other way to ensure secure access to it. The CiscoSecure ACS CLI is not password protected. Any person sitting at the remote workstation and running the CiscoSecure ACS CLI can access the CiscoSecure ACS server without logging in.

Running the CLI

You can run the CiscoSecure CLI from either the host machine for CiscoSecure ACS or from a remote workstation with a UNIX window.

•If you are at the host machine—Log in as root and change to the CLI directory. Enter the CiscoSecure ACS command lines from the UNIX command line prompt.

•If you are at a remote workstation—Change to the CLI directory. Enter the CiscoSecure ACS command lines from the UNIX command line prompt.

The remaining sections in this chapter describe the syntax and usage of the CiscoSecure ACS command lines.

AddProfile

To add a user or group profile to the CiscoSecure database, use the AddProfile command.

Command Syntax

AddProfile [-h host] -p port [-id client] {-u user | -g group} [-pr parent-group] [-pw password-pair] [-prv password-trio] [-a profile-info] [-s] [-q]

Syntax Description

Table 17-1 Add Profile Command Switches
Switch	Command Type	Description
-h	host (optional)	Name of the host where the CiscoSecure native database is located—almost always the same host where the CiscoSecure ACS is installed. Required if using this command remotely.
-p	port	CiscoSecure ACS database server port with which to communicate.
-id	client ID (optional)	Client ID. Required when using this command remotely.
-u	user	Name of user to add. If a -g switch is used, this cannot appear.
-g	group	Name of group to add. If a -u switch is used, this cannot appear.
-pr	parent group (optional)	Name of group to which the user will be added. Not specifying a group adds the profile to Root.
-pw	password pair¹ (optional) type, password or type	Defines which passwords to add to the user's profile. •If you add a password type that requires a password specification (clear, ARAP, PAP, DES, String, Outbound PAP), enter type, password. For example: `-pw ARAP,2sAmzpwRd` •If you add a password type that does not require a password specification (SYSTEM, SKEY, NO_PASSWORD, CRYPTO, ENIGMA,SDI), enter type. For example: `-pw SDI`
-prv	password trio² (optional) type, password or type, privilege level	Defines which password and privilege level requirement (if necessary) to add to the user's profile. •If you add a password type that requires a password type specification (clear, ARAP, PAP, DES, String, Outbound PAP), enter type, password, privilege level. For example: `-prv clear,2sAmzpwRd,13` •If you add a password type that does not require a password specification (SYSTEM, SKEY, NO_PASSWORD, CRYPTO, ENIGMA,SDI), enter type and privilege level. For example: `-prv SDI,13`
-a	profile info (optional)	Additional profile information to add to the user's^³ profile. This switch is free-formatted to provide user flexibility. Use \n to generate a new line in the profile statement. For example: `-a 'shell = {\nAny 0700 - 0900\n}'` results in: `shell = {` `Any 0700 - 0900 }` Multiple attribute-value (A/V) pairs are supported by stringing additional A/V pairs to the -a switch. `-a 'shell = {\nAny 0700 - 0900\n} \nset = noescape\n}'` results in: `user = joe {` `shell = {` `Any 0700 - 0900` `}` `set=noescape` `}` Note The -a switch has a 256-character limit on the length of the free-formatted string you can enter with this switch. Longer strings should be entered in a flat file and that file referenced by the -s switch, described below.
-s	additional profile info (optional)	Allows the user to add additional profile information from either standard input or a specified file. Use the -s switch without parameters for standard input. Use the -s switch followed by a filename to include information contained in that file. This switch can be used in conjunction with the -a switch.
-q	suppress output (optional)	Used to suppress user output.

¹The -pw and -prv switches are mutually exclusive. Use the -pw switch when creating profiles with passwords but no privilege-level requirements;

²Use the -prv switch when creating profiles with password and privilege-level requirements.

³In the AddProfile command line, a single quote at the start and end of data provided by the -a switch is required.

System Messages

Table 17-2 Add Profile Command System Messages
Message	RC¹	Description
No Error	0	Indicates no error occurred. The user has been successfully added.
Input Error	1	Error in the data provided by the users.
Connection Error	66	Cannot connect to the database server.
Socket Error	64	Error occurred establishing a socket.
Stream Error	65	Error occurred establishing a data stream.
Password Error	13	Invalid password or password type was entered.
User not added	2	User was not successfully added.

¹RC = return code.

Example

In the following example, issued from a UNIX workstation, the user, user_joe, is added to the parent group1 located on the server, mymachine. The password specified for user_joe is joepw11 with AppleTalk Remote Access Protocol (ARAP) authentication. The specified service is a default protocol with the noted permissions:

AddProfile -h mymachine -p 9900 -id 100 -u user_joe -pr group1 -pw arap,

joepw11 -a 'service={\ndefault attribute = permit \nset priv-lvl+15\n}'

In the second example, also issued from a UNIX workstation, group acctg1 is added to parent group1. Because no parent is specified, acctg1 is added to the Root:

AddProfile -h mymachine -p 9900 -id 100 -g acctg1 -pw arap, joepw11 -a 'service=slip{\n 
default attribute = permit \nset nocallback-verify = 1 \n}' \n}'

DeleteProfile

To delete a user or group profile from the CiscoSecure database, use the DeleteProfile command.

Command Syntax

DeleteProfile [-h host] -p port [-id client] {-u user | -g group} [-q]

Syntax Description

Table 17-3 DeleteProfile Command Switches
Switch	Command Type	Description
-h	host (optional)	Name of the host where the CiscoSecure native database is located—almost always the same host where the CiscoSecure ACS is installed. Required if using this command remotely.
-p	port	CiscoSecure ACS database server port with which to communicate.
-id	clientID (optional)	Client's ID.
-u	user	Name of user to delete. If the -g switch is used, this cannot appear.
-g	group	Name of group to delete. If the -u switch is used, this cannot appear.
-q	suppress output (optional)	Used to suppress user output.

System Messages

Table 17-4 Delete Profile Command System Messages
Message	RC¹	Description
No Error	0	Indicates no error occurred. The user has been successfully deleted.
Input Error	1	Error in the data provided by the users.
Connection Error	66	Cannot connect to the database server.
Socket Error	64	Error occurred establishing a socket.
Stream Error	65	Error occurred when creating a data stream between the command line and the ACS database server.
No username	3	The command line switches did not contain a username.
User not deleted	2	User was not successfully deleted.

¹RC = Return code.

Example

In the following example, the user, user_joe, is deleted from the database:

DeleteProfile -h mymachine -p 9900 -id 100 -u user_joe

ViewProfile

To view a user or group profile stored in the CiscoSecure database server, use the ViewProfile command.

Command Syntax

View Profile -h host -p port [-id client] {-u user | -g group} [-q]

Syntax Description

Table 17-5 View Profile Command Switches
Switch	Command Type	Description
-h	host (optional)	Name of the host where the CiscoSecure native database is located—almost always the same host where the CiscoSecure ACS is installed. Required if using command remotely
-p	port	The CiscoSecure ACS database server port with which to communicate.
-id	client (optional)	Client ID. Required when using the command remotely.
-u	user	Name of user to view. If the -g switch is used, this cannot appear.
-g	group	Name of group profile to display. If the -u switch is used, this cannot appear.
-q	suppress output (optional)	Used to suppress user output.

System Messages

Table 17-6 View Profile Command System Messages
Message	RC¹	Description
No Error	0	Indicates no error. The profile is displayed.
Input Error	1	Error in the data provided by the users.
Connection Error	66	Cannot connect to the database server.
Socket Error	64	Error occurred establishing a socket.
Stream Error	65	Error occurred when creating a data stream between the command line and the DBServer.
User or Group not found	3	The CiscoSecure ACS database server could not find the user or group requested.

¹RC = Return code.

Examples

In the following example command requests, the user profile, user_joe:

ViewProfile -h mymachine -p 9900 -id 100 -u user_joe

In the second example, the command requests a view of the group profile, joes_group:

ViewProfile -h mymachine -p 9900 -id 100 -g joes_group

ChangeParent

To change the parent of a user or group within the CiscoSecure database, use the ChangeParent command. This command is generally used to transfer a user from one group to another.

Command Syntax

To change a user's parent:

ChangeParent [-h host] -p port [-id client] -u user -dg destination-group

To change a group's parent:

ChangeParent [-h host] -p port [-id client] -sg sourcegroup -dg destination-group

Syntax Description

Table 17-7 Change Parent Command Switches
Switch	Command Type	Description
-h	host (optional)	Name of the host where the CiscoSecure native database is located—almost always the same host where the CiscoSecure ACS is installed. Required if using this command remotely.
-p	port	CiscoSecure ACS database server port with which to communicate.
-id	client (optional)	Client ID.
-u	user	Name of user to move. This command line will only support one -u or -sg switch at a time.
-sg	source group	Name of group to move. This command line will only support one -u or -sg switch at a time.
-dg	destination group	Name of group that will become the parent of the group or user specified in either the -u or -sg switch.
-q	suppress output (optional)	Suppresses user output.

System Messages

Table 17-8 Change Parent Command System Messages
Message	RC¹	Description
No Error	0	Indicates no error. The parent was successfully changed.
Input Error	1	Error in the data provided by the users.
Connection Error	66	Cannot connect to the ACS database server.
Socket Error	64	Error occurred establishing a socket.
Stream Error	65	Error occurred establishing a data stream.
Profile not moved	3	Group or user profile was not moved to its destination group.
Destination group does not exist	5	Destination group profile does not exist in the CiscoSecure database.
Profile does not exist	4	User or group profile does not exist.

¹RC = Return code.

Examples

In the following example, the user, user_joe, is shifted from its old parent, oldparent, to its new parent, newparent:

ChangeParent -h mymachine -p 9900 -id 100 -u user_joe -dg newparent

In the second example, the group, child_group, is shifted from its old parent, oldparent, to its new parent, newparent:

ChangeParent -h mymachine -p 9900 -id 100 -sg oldparent -dg newparent

ChangePassword

To change a user or group password, use the ChangePassword command.

Command Syntax

To change a user password:

ChangePassword [-h host] -p port [-id client] -u user -pr password-type -opw old-password -npw new-password

To change a group password:

ChangePassword [-h host] -p port [-id client] -g group -pr password-type -opw old-password -npw new-password

Syntax Description

Table 17-9 Change Password Command Switches
Switch	Command Type	Description
-h	host (optional)	Name of the host where the CiscoSecure native database is located—almost always the same host where the CiscoSecure ACS is installed. Required if using command remotely.
-p	port	CiscoSecure ACS database server port with which to communicate.
-id	client (optional)	Client ID.
-u	user	User's name whose passwords are being changed.
-g	group	Group's name whose passwords are being changed.
-pr	Protocol type	Type of protocol being changed, such as CHAP, ARAP, PAP, and so on.
-opw	old password	Old password.
-npw	new password	New password.
-q	suppress output (Optional)	Suppresses user output.

System Messages

Table 17-10 Change Password Command System Messages
Message	RC¹	Description
No Error	0	Indicates no error. The password has been successfully changed.
Input Error	1	Error in the data provided by the users.
Connection Error	66	Cannot connect to the ACS database server.
Socket Error	64	Error occurred establishing a socket.
Stream Error	65	Error occurred establishing a data stream between the ChangePassword and CiscoSecure.
Password Error	3	Invalid password type or password was provided in the -opw, -npw, or -pr switches.
Incorrect Old Password	4	Password supplied using the -opw switch does not match the user's current password for the password validation type provided in -pr.
Password Not Changed	5	Password did not change.

¹RC = return code.

Examples

In the following example, the password of the user user_joe is changed from joesold1 to joesnew1:

ChangePassword -h mymachine -p 9900 -id 100 -u user_joe -pr ARAP -opw joesold1 -npw 
joesnew1

In the second example, the password of the group group1 is changed from oldgroup1 to newgroup1:

ChangePassword -h mymachine -p 9900 -id 100 -g group1 -pr ARAP -opw oldgroup1 -npw 
newgroup1

UpdatePassword

To assign a new password to a user or group account even if the user or group members have forgotten the old password, use the UpdatePassword command.

The UpdatePassword command works identically as the ChangePassword command except that it does not require the old password to be specified.

To change a user's forgotten password enter:

UpdatePassword [-h host] -p port [-id client] -u user -pr password-type -npw new-password

To change a group's forgotten password enter:

UpdatePassword [-h host] -p port [-id client] -g group -pr password-type -npw new-password

Table 17-11 describes the UpdatePassword switches:

Table 17-11 UpdatePassword Command Switches
Switch	Command Type	Description
-h	host (optional)	Name of the host where the CiscoSecure native database is located—almost always the same host where the CiscoSecure ACS is installed. Required if using command remotely.
-p	port	CiscoSecure ACS database server port with which to communicate.
-id	client (optional)	Client ID.
-u	user	User's name whose passwords are being changed.
-g	group	Group's name whose passwords are being changed.
-pr	Protocol type	Type of protocol being changed, such as CHAP, ARAP, PAP, and so on.
-npw	new password	New password.
-q	suppress output (Optional)	Suppresses user output.

The following table describes system messages that might be returned for UpdatePassword:

Table 17-12 UpdatePassword Command System Messages
Message	RC¹	Description
No Error	0	Indicates no error. The password has been successfully changed.
Input Error	1	Error in the data provided by the users.
Connection Error	66	Cannot connect to the ACS database server.
Socket Error	64	Error occurred establishing a socket.
Stream Error	65	Error occurred establishing a data stream between the ChangePassword and CiscoSecure.
Password Error	3	Invalid password type or password was provided in the -npw, or -pr switches.
Password Not Changed	5	Password did not change.

¹RC = return code.

In the following example, the password of the user user_joe is changed to mynewpassword:

UpdatePassword -h mymachine -p 9900 -id 100 -u user_joe -pr ARAP -npw mynewpassword

In the second example, the password of the group group1 is changed to ournewpassword:

UpdatePassword -h mymachine -p 9900 -id 100 -g group1 -pr ARAP -npw ournewpassword

Command-Line Parameter Errors

These errors are generated by invalid command syntax. Use these errors to diagnose and troubleshoot problems that might arise while using the command line.

Table 17-13 Command-Line Parameter Error Messages
Error Message	RC¹	Meaning/Solution
Too many values	11	Too many values supplied on the command line. Check the syntax for this command and eliminate the unsupported values.
Invalid port	12	An invalid port was specified. Enter the correct port number.
Invalid parameter	14	Invalid parameter switch has been entered. Check the syntax for this command and eliminate the unsupported switch.
Invalid client ID	15	Client ID provided is invalid. Make sure the ID you entered is within the accepted range or is not already being used by another client.
Invalid number	16	An invalid number was passed in a command line switch. Make sure that one of the values you entered at the command line was not out of range or in an incorrect format.
Parameter already supplied	17	A parameter switch was used more than once. Eliminate the redundant switch.
Invalid character	18	A parameter containing an invalid character was entered. Remove or edit the character(s) that are not allowed.
Invalid protocol	19	A parameter switch value contains an invalid protocol. Check the command-line options to make sure you have entered an acceptable protocol choice.

¹RC = return code.

Table Of Contents