Installation and Configuration Guide for Cisco Secure ACS Remote Agents 4.0 - Configuring and Maintaining a Remote Agent [Cisco Secure Access Control Server Solution Engine]

Table Of Contents

Configuring and Maintaining a Remote Agent

Configuring a Remote Agent

CSAgent.ini Location

CSAgent.ini Settings

Sample CSAgent.ini

Changing CSAgent.ini Settings

Maintaining a Remote Agent

Stopping and Starting Remote Agent Services

File and Directory Structure

Retrieving Support Logs

Running CSAgent in Debug Mode

Sample CSAgent Debug Output

Sample Debug Output for a Windows Remote Agent

Sample Debug Output for a Solaris Remote Agent

Configuring and Maintaining a Remote Agent

This chapter provides information about configuring and maintaining a Cisco Secure Access Control Server (ACS) Remote Agent, for Windows or Solaris.

This chapter contains the following topics:

•Configuring a Remote Agent

•Maintaining a Remote Agent

Configuring a Remote Agent

You do all manual configuration of ACS Remote Agent by configuring the CSAgent.ini file. This section describes how to configure ACS Remote Agent by using the CSAgent.ini file.

This section contains the following topics:

•CSAgent.ini Location

•CSAgent.ini Settings

•Sample CSAgent.ini

•Changing CSAgent.ini Settings

CSAgent.ini Location

When you install ACS Remote Agent for Windows in the default location, CSAgent.ini is located in the directory C:\Program Files\Cisco\CiscoSecure ACS Agent

When you install ACS Remote Agent for Solaris, CSAgent.ini is located in the directory /opt/CSCOacsag

Regardless of where you install the remote agent, CSAgent.ini is located in the highest directory of the remote agent installation.

For more information about the directory structure created when you install a remote agent, see File and Directory Structure.

CSAgent.ini Settings

You do all manual configuration of ACS Remote Agent by configuring the CSAgent.ini file. This topic discusses the settings possible in CSAgent.ini.

CSAgent.ini has one section for each service provided by the remote agent, one each for CSAgent and CSLogAgent. If you are using ACS Remote Agent for Windows, CSAgent.ini also contains a section for CSWinAgent. Each section of CSAgent.ini has several options for configuring the applicable service. All options have the format:
OptionName=Value 
where OptionName is the name of the option and Value is the setting for that option. For options that accept multiple values, separate the values with commas (,).
OptionName=Value1,. . .,ValueN 
Optional settings can be disabled using a semicolon (;) at the beginning of the line. For example, the PermittedClients option is not mandatory and is disabled by default.
; PermittedClients=192.168.1.*,10.49.*.* 
The following list describes each option. For an example of a CSAgent.ini file, see Sample CSAgent.ini.

•CSAgent section—You can configure the following options for the CSAgent service.

–Port—The TCP port that the CSAgent service listens on. The default value is 2004. An ACS Solution Engine (ACS SE) using the remote agent first contacts the agent on this port.

Note The port number provided here must match the port number specified in ACS when you configure it to communicate with the remote agent.

–ConfigProviderHost—The IP address or the hostname of the ACS SE that is the configuration provider for the remote agent. The default value is the IP address or hostname specified during the installation process. If you specify a hostname, make sure that DNS is functioning correctly on your network or that the computer running the remote agent has a hosts file entry for the ACS SE.

–ConfigProviderPort—The TCP port of the ACS SE that is the configuration provider for the remote agent. This is the port that the appliance listens to for communications from the remote agent. The default is 2003.

Note It is highly unlikely that you will need to change the ConfigProviderPort value from the default of 2003. The port that an appliance listens to is not configurable.

–Agents—The agent services that CSAgent should enable. The default setting is determined at installation, when you specify which services should be active.

If you are using ACS Remote Agent for Solaris, the only valid service is CSLogAgent.

If you are using ACS Remote Agent for Windows, the two valid services are CSLogAgent and CSWinAgent. You can enable either service, or both services. If both services are enabled, the order in which you list them is irrelevant.

–PermittedClients—A comma-separated list of IP addresses from which CSAgent will accept requests. This setting is disabled by default. If you enable this option, the remote agent provides services only to appliances whose IP addresses are included in the list of IP addresses.

Note Restrictions imposed by the CSAgent PermittedClients value override restrictions imposed by the CSLogAgent or CSWinAgent PermittedClients values. ACS SEs with IP addresses not included in the PermittedClients value in the CSAgent section are always denied remote agent services, even if you have included the IP addresses in the PermittedClients values of the CSLogAgent or CSWinAgent sections.

In each IP address you specify, you have three options for each octet in the address:

–Number—You can specify a number, for example, 10.3.157.98.

–Numeric Range—You can specify the low and high numbers of the range in the octet, separated by a hyphen (-), for example, 10.3.157.10-50.

–Wildcard—You can use an asterisk (*) to match all numbers in that octet, for example, 10.3.157.*.

As a further example, the PermittedClients value can use these options in each IP address in its list.
PermittedClients=10.3.157.10-50,10.3.157.52,10.3.158.* 
•CSLogAgent section—You can configure the following options for the CSLogAgent service.

–Executable—The directory path and executable file name for the CSLogAgent service. This option is intended primarily for support use. The path can be relative to the directory containing CSAgent.exe. For information about the directory containing CSAgent.exe, see File and Directory Structure.

–Port—The TCP port that CSLogAgent listens to for ACS SE messages, other than accounting records. The default value is 2006.

–AccountingPort—The TCP port that CSLogAgent listens to for accounting records from ACS SEs. The default value is 2007.

–PermittedClients—A comma-separated list of IP addresses that CSLogAgent will accept requests from. This setting is disabled by default, which has the effect of a PermittedClients value of *.*.*.*. If you enable this option, the remote agent provides logging services only to appliances whose IP addresses are included in the list of IP addresses. If you also enable the PermittedClients value in the CSAgent section, the CSLogAgent PermittedClients value provides a means to restrict the remote agent logging service to a subset of the IP addresses specified in the CSAgent PermittedClients value.

Note You cannot use the CSLogAgent PermittedClients value to permit an IP address that the CSAgent PermittedClients value does not permit.

In each IP address you specify, you have three options for each octet in the address:

–Number—You can specify a number, for example, 10.3.157.98.

–Numeric Range—You can specify the low and high numbers of the range in the octet, separated by a hyphen (-), for example, 10.3.157.10-50.

–Wildcard—You can use an asterisk (*) to match all numbers in that octet, for example, 10.3.157.*.

•CSUnixOutput—Whether CSLogAgent records logs in comma-separated value (CSV) format or in the format that ACS Remote Agent for Solaris uses.

Note The CSUnixOutput option is applicable only to ACS Remote Agent for Solaris. The CSUnixOutput option does not exist in the CSAgent.ini file of a Windows remote agent.

The only valid values for this option are:

–0—Zero (0) specifies that the remote agent records logs in CSV format and that log filenames end with .csv. In CSV format, each record in the log is written on a single line, with values separated into columns by commas (,). The names of the columns appear at the top of each column. An abbreviated example of the first two lines of a CSV log is:
Date,Time,User-Name,Acct-Status-Type 
11/26/2003,10:48:36,jwiedman,Start 
–1—Zero (0) specifies that the remote agent records logs in CSUnix format and that log filenames end with .log. In CSUnix log format, each record in the log is written on multiple lines, beginning with the date and time. After the date, each line of a record includes the name of the attribute recorded, an equal sign (=), and the attribute value. Records are separated by two blank lines. An abbreviated example of a single record in CSUnix format is:
Tue Nov 26 10:48:36 2003 
   User-Name = "jwiedman" 
   Acct-Status-Type = Start 
•CSWinAgent section—You can configure the following options for the CSWinAgent service.

Note CSWinAgent is applicable only to ACS Remote Agent for Windows. The CSWinAgent section does not exist in the CSAgent.ini file of a Solaris remote agent.

–Executable—The directory path and executable file name for the CSWinAgent service. This option is intended primarily for support use. The path can be relative to the directory containing CSAgent.exe. For information about the directory containing CSAgent.exe, see File and Directory Structure.

–Port—The TCP port that CSWinAgent listens to for ACS SE messages. The default value is 2005.

–PermittedClients—A comma-separated list of IP addresses that CSWinAgent will accept requests from. This setting is disabled by default, which has the effect of a PermittedClients value of *.*.*.*. If you enable this option, the remote agent provides Windows authentication services only to appliances whose IP addresses are included in the list of IP addresses. If you also enable the PermittedClients value in the CSAgent section, the CSWinAgent PermittedClients value provides a means to restrict the remote agent Windows authentication service to a subset of the IP addresses specified in the CSAgent PermittedClients value.

Note You cannot use the CSWinAgent PermittedClients value to permit an IP address that the CSAgent PermittedClients value does not permit.

In each IP address you specify, you have three options for each octet in the address:

–Number—You can specify a number, for example, 10.3.157.98.

–Numeric Range—You can specify the low and high numbers of the range in the octet, separated by a hyphen (-), for example, 10.3.157.10-50.

–Wildcard—You can use an asterisk (*) to match all numbers in that octet, for example, 10.3.157.*.

The PermittedClients value can use these options in each IP address in its list, for example:
PermittedClients=10.3.157.10-50,10.3.157.52,10.3.158.*
Sample CSAgent.ini

The following sample CSAgent.ini file combines all options for Windows and Solaris remote agents. With the exception of the CSWinAgent section, this example file is valid for a Solaris remote agent. With the exception of the CSUnixOutput option, this example file is valid for a Windows remote agent.

Settings for your CSAgent.ini file will differ. For information about each setting in the CSAgent.ini file, see CSAgent.ini Settings.
[CSAgent] 
 
; This is the main service's configuration section... 
; To change the local port: 
; Port=2004 
 
; To set the config provider hostname/IP address: 
; ConfigProviderHost=servername 
; or  
; ConfigProviderHost=127.0.0.1 
ConfigProviderHost=192.168.1.102 
 
; To set the config provider port: 
ConfigProviderPort=2003 
 
; To define the list of agents to activate: 
;Agents=CSLogAgent,CSWinAgent 
Agents=CSWinAgent 
 
; To define a list of permitted clients 
; PermittedClients=192.168.1.*,10.49.*.* 
 
[CSLogAgent] 
 
; This is the log agent's configuration section...  
; Name of the agent's executable: 
Executable=..\CSLogAgent\CSLogAgent.exe 
 
; To change the local port: 
Port=2006 
 
; To change the accounting port: 
AccountingPort=2007 
 
; PermittedClients=192.168.1.*,10.49.*.* 
 
; Use CSUnix output format 
; possible values: 0 - csv, 1 - CSUnix format 
; default is no (0) 
; This option doesn't exist in a Windows remote agent CSAgent.ini file 
CSUnixOutput=1 
 
[CSWinAgent] 
 
; This is the Windows agent's configuration section... 
; This section doesn't exist in a Solaris remote agent CSAgent.ini file 
; Name of the agent's executable: 
Executable=..\CSWinAgent\CSWinAgent.exe 
 
; To change the local port: 
Port=2005 
 
; PermittedClients=192.168.1.*,10.49.*.* 
Changing CSAgent.ini Settings

You configure ACS Remote Agent by specifying settings in its CSAgent.ini file. Some default settings are determined at installation while others are preset by Cisco. You can change any of the settings in the CSAgent.ini file using this procedure.

Before You Begin

If you are using remote agents in a production environment, consider making changes when use of remote agent services is low. Putting changes to CSAgent.ini into effect requires restarting the CSAgent service. While CSAgent is restarting, no remote agent services are available.

To change CSAgent.ini settings:

Step 1 Using ASCII text editor, open the CSAgent.ini file for the remote agent you want to configure.

Tip If you chose the default installation directory, the CSAgent.ini file for a Windows remote agent is located at C:\Program Files\Cisco\CiscoSecure ACS Agent. For a Solaris remote agent, the CSAgent.ini file is located at /opt/CSCOacsag.

Step 2 Change the settings you want to modify. For more information about settings and their significance, see CSAgent.ini Settings.

Note Editing CSAgent.ini for the Solaris remote agent requires root access. If you cannot access the computer running the remote agent as root, use the sudo command, for example, sudo vi CSAgent.ini.

Step 3 Save your changes. If you have no further changes to make, close the CSAgent.ini file.

Step 4 Restart the CSAgent service. If you do not restart CSAgent, the agent does not implement the changes. For detailed steps, see Stopping and Starting Remote Agent Services.

Note Restarting the CSAgent service briefly interrupts all services provided by the remote agent. Consider performing this step when use of remote agent services is low.

During startup, the remote agent notifies its configuration provider of its configuration, including changes to CSAgent.ini that are relevant to the configuration provider. After startup is complete, remote agent services are available.

Maintaining a Remote Agent

This section provides information about maintaining and debugging a remote agent.

This section contains the following topics:

•Stopping and Starting Remote Agent Services

•File and Directory Structure

•Retrieving Support Logs

•Running CSAgent in Debug Mode

•Sample CSAgent Debug Output

Stopping and Starting Remote Agent Services

CSAgent controls the CSLogAgent and CSWinAgent applications. To stop or start any part of the remote agent, you must stop or start CSAgent.

Before You Begin

While CSAgent is stopped, no remote agent services are available. If you are restarting remote agent services, consider restarting CSAgent when use of remote agent services is low.

To stop or restart Windows remote agent services:

Step 1 Use a user account that has local administrator privileges to log in to the computer running the Windows remote agent.

Step 2 Open an MS DOS command prompt.

Step 3 To stop remote agent services, type:
net stop csagent 
Press Enter.

The CSAgent service stops, as do the CSLogAgent and CSWinAgent applications, if they were running. Remote agent services are unavailable to any appliance.

Step 4 To start remote agent services, type:
net start csagent 
Press Enter.

The CSAgent service starts. CSAgent also starts the remote agent services that the CSAgent.ini specifies. After startup is complete, the applicable remote agent services are available.

To stop or restart Solaris remote agent services:

Step 1 On the computer running the Solaris remote agent, access a shell command prompt as the root user.

Tip If you do not have root access to the computer running the remote agent, use the sudo command to execute the commands in the following steps.

Step 2 To stop remote agent processes, type:
/etc/init.d/csagent stop 
Press Enter.

Tip You can also use the kill command to stop remote agent processes. To list remote agent processes, use the command: ps -ef | grep "CS[AL]"

The CSAgent service stops, as does CSLogAgent if it was running. Remote agent services are unavailable to any appliance.

Step 3 To start remote agent processes, type:
/etc/init.d/csagent start 
Press Enter.

Tip You can also start the CSAgent process using this command: /opt/CSCOacsag/CSAgent/CSAgent &. The CSAgent process reads the CSAgent.ini file and starts the CSLogAgent process if the .ini file indicates that the log service is enabled.

The CSAgent service starts. CSAgent also starts the remote agent services that the CSAgent.ini specifies. After startup is complete, the applicable remote agent services are available.

File and Directory Structure

When you install ACS Remote Agent for Windows, you select an installation location, the default location being C:\Program Files\Cisco\CiscoSecure ACS Agent. When you install ACS Remote Agent for Solaris, the installation location is /opt/CSCOacsag. Regardless of where you choose to install the remote agent, the files and directories created at that location are the same.

The following list describes those directories and their contents:

•CSAgent—Contains files required by the CSAgent service and a Logs directory for CSAgent service logging.

•CSLogAgent—Contains files required by CSLogAgent, a Logs directory for CSLogAgent service logging, and a Datafile directory for information from the configuration provider.

•CSWinAgent—Contains files required by CSWinAgent and a Logs directory for CSWinAgent service logging. This directory is only present in installations of the Windows remote agent.

•Logs—Contains the following directories for storing accounting and administrative reports from appliances:

–AdminAudit—Contains CSV files for Administrative Audit logs.

–Backup and Restore—Contains CSV files for ACS Backup and Restore logs.

–DbSync—Contains CSV files for RDBMS Synchronization logs.

–Failed Attempts—Contains CSV files for Failed Attempts logs.

–Passed Authentications—Contains CSV files for Passed Authentications logs.

–RADIUS Accounting—Contains CSV files for RADIUS Accounting logs.

–ServiceMonitoring—Contains CSV files for ACS Service Monitoring logs.

–TACACS+ Accounting—Contains CSV files for TACACS+ Accounting logs.

–TACACS+ Administration—Contains CSV files for TACACS+ Administration logs.

–VoIP Accounting—Contains CSV files for VoIP Accounting logs.

The logging files that appear in the directories depend upon the logging configuration of the configuration provider.

•Support—Contains other files that remote agent services use, particularly CSLogAgent. The Support directory also is where the remote agent places cabinet files requested by an appliance Support feature. For more information about how the Support feature uses this directory, see Retrieving Support Logs.

Retrieving Support Logs

ACS SE includes a feature called Support, found in the System Configuration section of the HTML Interface. When you select the Run Support Now option on the Support page of an appliance that is configured to use a remote agent for any service, the appliance instructs the remote agent to collect copies of its diagnostic logs. The Windows agent produces a cabinet file containing the log files. The Solaris agent produces a .tar file containing the log files.

The remote agent places the resulting support file in the Support directory under the remote agent installation directory. Any previous support file is overwritten when a new one is created.

To retrieve the support file, on the computer running the remote agent, access the Support folder under the remote agent installation directory. For more information about the directory structure under the installation directory, see File and Directory Structure.

Running CSAgent in Debug Mode

CSAgent support a debug mode that enables you to see error messages as they occur and other normal diagnostic output. The debug mode is helpful if you encounter difficulty running a remote agent; or, if you suspect communication problems between a remote agent and appliances configured to use it, especially its configuration provider.

For examples of debug output, see Sample Debug Output for a Windows Remote Agent.

To run a Windows remote agent in debug mode:

Step 1 Use a user account that has local administrator privileges to log in to the computer running the Windows remote agent.

Note When debugging Windows authentication with Active Directory, you may need to log in with a user account that has been granted the Act as part of the operating system local security privilege. For more information, see Windows Authentication Configuration.

Step 2 Open an MS DOS command prompt.

Step 3 Change directories to the location of the CSAgent.exe file. The CSAgent.exe file is located in the CSAgent folder under the installation directory of the remote agent. For more information about the directory structure under the installation directory, see File and Directory Structure.

Step 4 If CSAgent is running, type:
net stop csagent 
Press Enter.

The CSAgent service stops. Remote agent services are unavailable to any appliance.

Step 5 Type:
csagent.exe -z -p 
Press Enter.

Tip To view the version of CSAgent.exe, type csagent.exe -v and press Enter.

The CSAgent service starts. For each remote agent service enabled in the CSAgent.ini file, a console window opens. For example, if CSLogAgent and CSWinAgent are enabled in the CSAgent.ini file, two console windows open, one for each service. The console windows show debug output for the applicable service. The command window where you entered the CSAgent command displays debug output from CSAgent. For a sample of debug output, see Sample Debug Output for a Windows Remote Agent.

Step 6 To end the debugging session, press Enter.

The debug session ends. All remote agent services stop. The Console window for CSWinAgent or CSLogAgent closes.

For information about restarting the remote agent, see Stopping and Starting Remote Agent Services.

To run a Solaris remote agent in debug mode:

Step 1 On the computer running the Solaris remote agent, access a shell command prompt as the root user.

Tip If you do not have root access to the computer running the remote agent, use the sudo command to execute the commands in the following steps.

Step 2 If the remote agent is running, type:
/etc/init.d/csagent stop 
Press Enter.

Tip You can also use the kill command to stop remote agent processes. To list remote agent processes, use the command: ps -ef | grep "CS[AL]"

The CSAgent service stops, as does CSLogAgent if it was running. Remote agent services are unavailable to any appliance.

Step 3 Change directories to the CSAgent directory. Type:
cd /opt/CSCOacsag/CSAgent 
Press Enter.

Step 4 Type:
CSAgent -z -p 
Press Enter.

Tip To view the version of CSAgent, type CSAgent -v and press Enter.

The CSAgent service starts. Output is shown in the shell that you used to run the remote agent. For a sample of debug output, see Sample Debug Output for a Windows Remote Agent.

Step 5 To end the debugging session, press Enter.

Note If you press Ctrl + C to end the debug session, the CSLogAgent process is not stopped. In this event, use the ps command to determine the process ID of CSLogAgent and use the kill command to stop it.

The debug session ends. All remote agent processes stop.

For information about restarting the remote agent, see Stopping and Starting Remote Agent Services.

Sample CSAgent Debug Output

This section provides sample output of remote agents run in debug mode. Much of the startup output for remote agents in debug mode reflects the settings made in the CSAgent.ini file. Startup output also show various steps in establishing contact with the configuration provider for the remote agent.

This section contains the following topics:

•Sample Debug Output for a Windows Remote Agent

•Sample Debug Output for a Solaris Remote Agent

Sample Debug Output for a Windows Remote Agent

This topic shows normal debug output from a Windows remote agent, including CSAgent, CSLogAgent, and CSWinAgent.

The following output is from CSAgent at startup:
D:...\CSAgent 33: csagent -p -z 
Debug printing on.. 
Running CSAgent server from command line.. 
CSAgent server starting ============================== 
Running as console application. 
Will listen on port 2004 
Configuration will be fetched from 192.168.12.208:2003 
Agents: CSLogAgent,CSWinAgent 
CSLogAgent File: ..\CSLogAgent\CSLogAgent.exe 
CSLogAgent Port: 2006 
CSWinAgent File: ..\CSWinAgent\CSWinAgent.exe 
CSWinAgent Port: 2005 
2 agents configured 
Permitted CSAgent Clients: 192.168.12.1-127  
Hit Return/Enter to stop... 
 
Watchdog activated 
Listener activated 
CSLogAgent launched 
CSWinAgent launched 
The following normal output is from CSAgent after you press Enter to end the debug session:
Service stopping 
Shutting down EndPoint library 
Listener terminating 
The following output is from CSLogAgent:
CSLogAgent server starting ============================== 
Running as console application. 
Configuration will be fetched from 192.168.12.208:2003 
Permitted CSLogAgent Clients: *.*.*.* 
Cant get max number of connections maxNumberOfConnections using default 32 
Agent library initialisedAgentLib: Attempting to connect to config provider at 
192.168.12.208:2003 
AgentLib: Connection established, handle 0x7e4af8 
AgentLib: GetLogConfig reply received 
AgentLib: Disconnecting from config provider, handle 0x7e4af8 
Config downloaded 
Will listen on port 2007 
Will not log to a datafile. 
Stream thread  N  started 
Stream  N  waiting for connection 
Will use the Loglib library. 
Listening thread started...  
The following output is from CSWinAgent:
CSWinAgent server starting ============================== 
Running as console application. 
Will listen on port 2005 
Permitted CSWinAgent Clients: *.*.*.* 
NTLIB: Library behaviour mode 2 
NTLIB: Initialising locally 
NTLIB: The local computer name is ENG-IIS-WEST2 
NTLIB: We are NOT a domain controller 
NTLIB: We are a member of the ENGINEERING domain 
Listener activated 
Sample Debug Output for a Solaris Remote Agent

The following is startup output from a Solaris remote agent that is configured to run CSLogAgent:
cmi-xdm5:5> CSAgent -z -p 
Running CSAgent server from command line.. 
Debug printing on.. 
CSAgent server starting ============================== 
Running as console application. 
Will listen on port 2004 
Configuration will be fetched from 192.168.12.208:2003 
Agents: CSLogAgent 
CSLogAgent File: /opt/CSCOacsag/CSLogAgent/CSLogAgent 
CSLogAgent Port: 2006 
1 agents configured 
Permitted CSAgent Clients: *.*.*.* 
Listener activated 
Hit Return/Enter to stop... 
 
Watchdog activated 
check_sys_limits set max file descriptors to 1024 
Running CSLogAgent server from command line.. 
CSLogAgent server starting ============================== 
Running as console application. 
Configuration will be fetched from 192.168.12.208:2003 
Permitted CSLogAgent Clients: *.*.*.* 
Cant get max number of connections maxNumberOfConnections using default 32 
CreateProcess cd /opt/CSCOacsag/CSLogAgent; /opt/CSCOacsag/CSLogAgent/CSLogAgent -z & pid 
= 8686 
CSLogAgent launched 
Agent library initialised 
AgentLib: Attempting to connect to config provider at 192.168.12.208:2003 
AgentLib: Connection established, handle 0x916c8 
AgentLib: GetLogConfig reply received 
AgentLib: Disconnecting from config provider, handle 0x916c8 
Config downloaded 
Will listen on port 2007 
Will not log to a datafile. 
g_started_ok=1 
Listening thread started... 
 
Rollover on /opt/CSCOacsag/Logs/Failed Attempts\Failed Attempts active.csv reset to 
manual. 
Rollover on /opt/CSCOacsag/Logs/RADIUS Accounting\RADIUS Accounting active.csv reset to 
manual. 
Rollover on /opt/CSCOacsag/Logs/TACACS+ Accounting\TACACS+ Accounting active.csv reset to 
manual. 
Rollover on /opt/CSCOacsag/Logs/TACACS+ Administration\Tacacs+ Administration active.csv 
reset to manual. 
Will use the Loglib library. 
Stream thread  N  started 
Stream  N  waiting for connection 
The following is normal output when you press Enter to end the debug session:
Service stopping 
Shutting down EndPoint library 
Watchdog done. send kill to 8714 

	Installation and Configuration Guide for Cisco Secure ACS Remote Agents 4.0
	Configuring and Maintaining a Remote Agent
Installation and Configuration Guide for Cisco Secure ACS Remote Agents 4.0 Preface Introduction to ACS Remote Services Installing ACS Remote Agent for Windows Installing ACS Remote Agent for Solaris Configuring and Maintaining a Remote Agent Index	Download this chapter Configuring and Maintaining a Remote Agent Download the complete book Installation and Configuration Guide for ACS Remote Agents 4.0 (full book PDF) (PDF - 710 KB) Feedback Table Of Contents Configuring and Maintaining a Remote Agent Configuring a Remote Agent CSAgent.ini Location CSAgent.ini Settings Sample CSAgent.ini Changing CSAgent.ini Settings Maintaining a Remote Agent Stopping and Starting Remote Agent Services File and Directory Structure Retrieving Support Logs Running CSAgent in Debug Mode Sample CSAgent Debug Output Sample Debug Output for a Windows Remote Agent Sample Debug Output for a Solaris Remote Agent Configuring and Maintaining a Remote Agent This chapter provides information about configuring and maintaining a Cisco Secure Access Control Server (ACS) Remote Agent, for Windows or Solaris. This chapter contains the following topics: •Configuring a Remote Agent •Maintaining a Remote Agent Configuring a Remote Agent You do all manual configuration of ACS Remote Agent by configuring the CSAgent.ini file. This section describes how to configure ACS Remote Agent by using the CSAgent.ini file. This section contains the following topics: •CSAgent.ini Location •CSAgent.ini Settings •Sample CSAgent.ini •Changing CSAgent.ini Settings CSAgent.ini Location When you install ACS Remote Agent for Windows in the default location, CSAgent.ini is located in the directory C:\Program Files\Cisco\CiscoSecure ACS Agent When you install ACS Remote Agent for Solaris, CSAgent.ini is located in the directory /opt/CSCOacsag Regardless of where you install the remote agent, CSAgent.ini is located in the highest directory of the remote agent installation. For more information about the directory structure created when you install a remote agent, see File and Directory Structure. CSAgent.ini Settings You do all manual configuration of ACS Remote Agent by configuring the CSAgent.ini file. This topic discusses the settings possible in CSAgent.ini. CSAgent.ini has one section for each service provided by the remote agent, one each for CSAgent and CSLogAgent. If you are using ACS Remote Agent for Windows, CSAgent.ini also contains a section for CSWinAgent. Each section of CSAgent.ini has several options for configuring the applicable service. All options have the format: OptionName=Value where OptionName is the name of the option and Value is the setting for that option. For options that accept multiple values, separate the values with commas (,). OptionName=Value1,. . .,ValueN Optional settings can be disabled using a semicolon (;) at the beginning of the line. For example, the PermittedClients option is not mandatory and is disabled by default. ; PermittedClients=192.168.1.,10.49..* The following list describes each option. For an example of a CSAgent.ini file, see Sample CSAgent.ini. •CSAgent section—You can configure the following options for the CSAgent service. –Port—The TCP port that the CSAgent service listens on. The default value is 2004. An ACS Solution Engine (ACS SE) using the remote agent first contacts the agent on this port. Note The port number provided here must match the port number specified in ACS when you configure it to communicate with the remote agent. –ConfigProviderHost—The IP address or the hostname of the ACS SE that is the configuration provider for the remote agent. The default value is the IP address or hostname specified during the installation process. If you specify a hostname, make sure that DNS is functioning correctly on your network or that the computer running the remote agent has a hosts file entry for the ACS SE. –ConfigProviderPort—The TCP port of the ACS SE that is the configuration provider for the remote agent. This is the port that the appliance listens to for communications from the remote agent. The default is 2003. Note It is highly unlikely that you will need to change the ConfigProviderPort value from the default of 2003. The port that an appliance listens to is not configurable. –Agents—The agent services that CSAgent should enable. The default setting is determined at installation, when you specify which services should be active. If you are using ACS Remote Agent for Solaris, the only valid service is CSLogAgent. If you are using ACS Remote Agent for Windows, the two valid services are CSLogAgent and CSWinAgent. You can enable either service, or both services. If both services are enabled, the order in which you list them is irrelevant. –PermittedClients—A comma-separated list of IP addresses from which CSAgent will accept requests. This setting is disabled by default. If you enable this option, the remote agent provides services only to appliances whose IP addresses are included in the list of IP addresses. Note Restrictions imposed by the CSAgent PermittedClients value override restrictions imposed by the CSLogAgent or CSWinAgent PermittedClients values. ACS SEs with IP addresses not included in the PermittedClients value in the CSAgent section are always denied remote agent services, even if you have included the IP addresses in the PermittedClients values of the CSLogAgent or CSWinAgent sections. In each IP address you specify, you have three options for each octet in the address: –Number—You can specify a number, for example, 10.3.157.98. –Numeric Range—You can specify the low and high numbers of the range in the octet, separated by a hyphen (-), for example, 10.3.157.10-50. –Wildcard—You can use an asterisk () to match all numbers in that octet, for example, 10.3.157.. As a further example, the PermittedClients value can use these options in each IP address in its list. PermittedClients=10.3.157.10-50,10.3.157.52,10.3.158.* •CSLogAgent section—You can configure the following options for the CSLogAgent service. –Executable—The directory path and executable file name for the CSLogAgent service. This option is intended primarily for support use. The path can be relative to the directory containing CSAgent.exe. For information about the directory containing CSAgent.exe, see File and Directory Structure. –Port—The TCP port that CSLogAgent listens to for ACS SE messages, other than accounting records. The default value is 2006. –AccountingPort—The TCP port that CSLogAgent listens to for accounting records from ACS SEs. The default value is 2007. –PermittedClients—A comma-separated list of IP addresses that CSLogAgent will accept requests from. This setting is disabled by default, which has the effect of a PermittedClients value of `...`. If you enable this option, the remote agent provides logging services only to appliances whose IP addresses are included in the list of IP addresses. If you also enable the PermittedClients value in the CSAgent section, the CSLogAgent PermittedClients value provides a means to restrict the remote agent logging service to a subset of the IP addresses specified in the CSAgent PermittedClients value. Note You cannot use the CSLogAgent PermittedClients value to permit an IP address that the CSAgent PermittedClients value does not permit. In each IP address you specify, you have three options for each octet in the address: –Number—You can specify a number, for example, 10.3.157.98. –Numeric Range—You can specify the low and high numbers of the range in the octet, separated by a hyphen (-), for example, 10.3.157.10-50. –Wildcard—You can use an asterisk () to match all numbers in that octet, for example, 10.3.157.. •CSUnixOutput—Whether CSLogAgent records logs in comma-separated value (CSV) format or in the format that ACS Remote Agent for Solaris uses. Note The CSUnixOutput option is applicable only to ACS Remote Agent for Solaris. The CSUnixOutput option does not exist in the CSAgent.ini file of a Windows remote agent. The only valid values for this option are: –0—Zero (0) specifies that the remote agent records logs in CSV format and that log filenames end with .csv. In CSV format, each record in the log is written on a single line, with values separated into columns by commas (,). The names of the columns appear at the top of each column. An abbreviated example of the first two lines of a CSV log is: Date,Time,User-Name,Acct-Status-Type 11/26/2003,10:48:36,jwiedman,Start –1—Zero (0) specifies that the remote agent records logs in CSUnix format and that log filenames end with .log. In CSUnix log format, each record in the log is written on multiple lines, beginning with the date and time. After the date, each line of a record includes the name of the attribute recorded, an equal sign (=), and the attribute value. Records are separated by two blank lines. An abbreviated example of a single record in CSUnix format is: Tue Nov 26 10:48:36 2003 User-Name = "jwiedman" Acct-Status-Type = Start •CSWinAgent section—You can configure the following options for the CSWinAgent service. Note CSWinAgent is applicable only to ACS Remote Agent for Windows. The CSWinAgent section does not exist in the CSAgent.ini file of a Solaris remote agent. –Executable—The directory path and executable file name for the CSWinAgent service. This option is intended primarily for support use. The path can be relative to the directory containing CSAgent.exe. For information about the directory containing CSAgent.exe, see File and Directory Structure. –Port—The TCP port that CSWinAgent listens to for ACS SE messages. The default value is 2005. –PermittedClients—A comma-separated list of IP addresses that CSWinAgent will accept requests from. This setting is disabled by default, which has the effect of a PermittedClients value of `...`. If you enable this option, the remote agent provides Windows authentication services only to appliances whose IP addresses are included in the list of IP addresses. If you also enable the PermittedClients value in the CSAgent section, the CSWinAgent PermittedClients value provides a means to restrict the remote agent Windows authentication service to a subset of the IP addresses specified in the CSAgent PermittedClients value. Note You cannot use the CSWinAgent PermittedClients value to permit an IP address that the CSAgent PermittedClients value does not permit. In each IP address you specify, you have three options for each octet in the address: –Number—You can specify a number, for example, 10.3.157.98. –Numeric Range—You can specify the low and high numbers of the range in the octet, separated by a hyphen (-), for example, 10.3.157.10-50. –Wildcard—You can use an asterisk () to match all numbers in that octet, for example, 10.3.157.. The PermittedClients value can use these options in each IP address in its list, for example: PermittedClients=10.3.157.10-50,10.3.157.52,10.3.158.* Sample CSAgent.ini The following sample CSAgent.ini file combines all options for Windows and Solaris remote agents. With the exception of the CSWinAgent section, this example file is valid for a Solaris remote agent. With the exception of the CSUnixOutput option, this example file is valid for a Windows remote agent. Settings for your CSAgent.ini file will differ. For information about each setting in the CSAgent.ini file, see CSAgent.ini Settings. [CSAgent] ; This is the main service's configuration section... ; To change the local port: ; Port=2004 ; To set the config provider hostname/IP address: ; ConfigProviderHost=servername ; or ; ConfigProviderHost=127.0.0.1 ConfigProviderHost=192.168.1.102 ; To set the config provider port: ConfigProviderPort=2003 ; To define the list of agents to activate: ;Agents=CSLogAgent,CSWinAgent Agents=CSWinAgent ; To define a list of permitted clients ; PermittedClients=192.168.1.,10.49..* [CSLogAgent] ; This is the log agent's configuration section... ; Name of the agent's executable: Executable=..\CSLogAgent\CSLogAgent.exe ; To change the local port: Port=2006 ; To change the accounting port: AccountingPort=2007 ; PermittedClients=192.168.1.,10.49..* ; Use CSUnix output format ; possible values: 0 - csv, 1 - CSUnix format ; default is no (0) ; This option doesn't exist in a Windows remote agent CSAgent.ini file CSUnixOutput=1 [CSWinAgent] ; This is the Windows agent's configuration section... ; This section doesn't exist in a Solaris remote agent CSAgent.ini file ; Name of the agent's executable: Executable=..\CSWinAgent\CSWinAgent.exe ; To change the local port: Port=2005 ; PermittedClients=192.168.1.,10.49..* Changing CSAgent.ini Settings You configure ACS Remote Agent by specifying settings in its CSAgent.ini file. Some default settings are determined at installation while others are preset by Cisco. You can change any of the settings in the CSAgent.ini file using this procedure. Before You Begin If you are using remote agents in a production environment, consider making changes when use of remote agent services is low. Putting changes to CSAgent.ini into effect requires restarting the CSAgent service. While CSAgent is restarting, no remote agent services are available. To change CSAgent.ini settings: Step 1 Using ASCII text editor, open the CSAgent.ini file for the remote agent you want to configure. Tip If you chose the default installation directory, the CSAgent.ini file for a Windows remote agent is located at C:\Program Files\Cisco\CiscoSecure ACS Agent. For a Solaris remote agent, the CSAgent.ini file is located at /opt/CSCOacsag. Step 2 Change the settings you want to modify. For more information about settings and their significance, see CSAgent.ini Settings. Note Editing CSAgent.ini for the Solaris remote agent requires root access. If you cannot access the computer running the remote agent as root, use the sudo command, for example, sudo vi CSAgent.ini. Step 3 Save your changes. If you have no further changes to make, close the CSAgent.ini file. Step 4 Restart the CSAgent service. If you do not restart CSAgent, the agent does not implement the changes. For detailed steps, see Stopping and Starting Remote Agent Services. Note Restarting the CSAgent service briefly interrupts all services provided by the remote agent. Consider performing this step when use of remote agent services is low. During startup, the remote agent notifies its configuration provider of its configuration, including changes to CSAgent.ini that are relevant to the configuration provider. After startup is complete, remote agent services are available. Maintaining a Remote Agent This section provides information about maintaining and debugging a remote agent. This section contains the following topics: •Stopping and Starting Remote Agent Services •File and Directory Structure •Retrieving Support Logs •Running CSAgent in Debug Mode •Sample CSAgent Debug Output Stopping and Starting Remote Agent Services CSAgent controls the CSLogAgent and CSWinAgent applications. To stop or start any part of the remote agent, you must stop or start CSAgent. Before You Begin While CSAgent is stopped, no remote agent services are available. If you are restarting remote agent services, consider restarting CSAgent when use of remote agent services is low. To stop or restart Windows remote agent services: Step 1 Use a user account that has local administrator privileges to log in to the computer running the Windows remote agent. Step 2 Open an MS DOS command prompt. Step 3 To stop remote agent services, type: net stop csagent Press Enter. The CSAgent service stops, as do the CSLogAgent and CSWinAgent applications, if they were running. Remote agent services are unavailable to any appliance. Step 4 To start remote agent services, type: net start csagent Press Enter. The CSAgent service starts. CSAgent also starts the remote agent services that the CSAgent.ini specifies. After startup is complete, the applicable remote agent services are available. To stop or restart Solaris remote agent services: Step 1 On the computer running the Solaris remote agent, access a shell command prompt as the root user. Tip If you do not have root access to the computer running the remote agent, use the sudo command to execute the commands in the following steps. Step 2 To stop remote agent processes, type: /etc/init.d/csagent stop Press Enter. Tip You can also use the kill command to stop remote agent processes. To list remote agent processes, use the command: ps -ef \| grep "CS[AL]" The CSAgent service stops, as does CSLogAgent if it was running. Remote agent services are unavailable to any appliance. Step 3 To start remote agent processes, type: /etc/init.d/csagent start Press Enter. Tip You can also start the CSAgent process using this command: /opt/CSCOacsag/CSAgent/CSAgent &. The CSAgent process reads the CSAgent.ini file and starts the CSLogAgent process if the .ini file indicates that the log service is enabled. The CSAgent service starts. CSAgent also starts the remote agent services that the CSAgent.ini specifies. After startup is complete, the applicable remote agent services are available. File and Directory Structure When you install ACS Remote Agent for Windows, you select an installation location, the default location being C:\Program Files\Cisco\CiscoSecure ACS Agent. When you install ACS Remote Agent for Solaris, the installation location is /opt/CSCOacsag. Regardless of where you choose to install the remote agent, the files and directories created at that location are the same. The following list describes those directories and their contents: •CSAgent—Contains files required by the CSAgent service and a Logs directory for CSAgent service logging. •CSLogAgent—Contains files required by CSLogAgent, a Logs directory for CSLogAgent service logging, and a Datafile directory for information from the configuration provider. •CSWinAgent—Contains files required by CSWinAgent and a Logs directory for CSWinAgent service logging. This directory is only present in installations of the Windows remote agent. •Logs—Contains the following directories for storing accounting and administrative reports from appliances: –AdminAudit—Contains CSV files for Administrative Audit logs. –Backup and Restore—Contains CSV files for ACS Backup and Restore logs. –DbSync—Contains CSV files for RDBMS Synchronization logs. –Failed Attempts—Contains CSV files for Failed Attempts logs. –Passed Authentications—Contains CSV files for Passed Authentications logs. –RADIUS Accounting—Contains CSV files for RADIUS Accounting logs. –ServiceMonitoring—Contains CSV files for ACS Service Monitoring logs. –TACACS+ Accounting—Contains CSV files for TACACS+ Accounting logs. –TACACS+ Administration—Contains CSV files for TACACS+ Administration logs. –VoIP Accounting—Contains CSV files for VoIP Accounting logs. The logging files that appear in the directories depend upon the logging configuration of the configuration provider. •Support—Contains other files that remote agent services use, particularly CSLogAgent. The Support directory also is where the remote agent places cabinet files requested by an appliance Support feature. For more information about how the Support feature uses this directory, see Retrieving Support Logs. Retrieving Support Logs ACS SE includes a feature called Support, found in the System Configuration section of the HTML Interface. When you select the Run Support Now option on the Support page of an appliance that is configured to use a remote agent for any service, the appliance instructs the remote agent to collect copies of its diagnostic logs. The Windows agent produces a cabinet file containing the log files. The Solaris agent produces a .tar file containing the log files. The remote agent places the resulting support file in the Support directory under the remote agent installation directory. Any previous support file is overwritten when a new one is created. To retrieve the support file, on the computer running the remote agent, access the Support folder under the remote agent installation directory. For more information about the directory structure under the installation directory, see File and Directory Structure. Running CSAgent in Debug Mode CSAgent support a debug mode that enables you to see error messages as they occur and other normal diagnostic output. The debug mode is helpful if you encounter difficulty running a remote agent; or, if you suspect communication problems between a remote agent and appliances configured to use it, especially its configuration provider. For examples of debug output, see Sample Debug Output for a Windows Remote Agent. To run a Windows remote agent in debug mode: Step 1 Use a user account that has local administrator privileges to log in to the computer running the Windows remote agent. Note When debugging Windows authentication with Active Directory, you may need to log in with a user account that has been granted the Act as part of the operating system local security privilege. For more information, see Windows Authentication Configuration. Step 2 Open an MS DOS command prompt. Step 3 Change directories to the location of the CSAgent.exe file. The CSAgent.exe file is located in the CSAgent folder under the installation directory of the remote agent. For more information about the directory structure under the installation directory, see File and Directory Structure. Step 4 If CSAgent is running, type: net stop csagent Press Enter. The CSAgent service stops. Remote agent services are unavailable to any appliance. Step 5 Type: csagent.exe -z -p Press Enter. Tip To view the version of CSAgent.exe, type csagent.exe -v and press Enter. The CSAgent service starts. For each remote agent service enabled in the CSAgent.ini file, a console window opens. For example, if CSLogAgent and CSWinAgent are enabled in the CSAgent.ini file, two console windows open, one for each service. The console windows show debug output for the applicable service. The command window where you entered the CSAgent command displays debug output from CSAgent. For a sample of debug output, see Sample Debug Output for a Windows Remote Agent. Step 6 To end the debugging session, press Enter. The debug session ends. All remote agent services stop. The Console window for CSWinAgent or CSLogAgent closes. For information about restarting the remote agent, see Stopping and Starting Remote Agent Services. To run a Solaris remote agent in debug mode: Step 1 On the computer running the Solaris remote agent, access a shell command prompt as the root user. Tip If you do not have root access to the computer running the remote agent, use the sudo command to execute the commands in the following steps. Step 2 If the remote agent is running, type: /etc/init.d/csagent stop Press Enter. Tip You can also use the kill command to stop remote agent processes. To list remote agent processes, use the command: ps -ef \| grep "CS[AL]" The CSAgent service stops, as does CSLogAgent if it was running. Remote agent services are unavailable to any appliance. Step 3 Change directories to the CSAgent directory. Type: cd /opt/CSCOacsag/CSAgent Press Enter. Step 4 Type: CSAgent -z -p Press Enter. Tip To view the version of CSAgent, type CSAgent -v and press Enter. The CSAgent service starts. Output is shown in the shell that you used to run the remote agent. For a sample of debug output, see Sample Debug Output for a Windows Remote Agent. Step 5 To end the debugging session, press Enter. Note If you press Ctrl + C to end the debug session, the CSLogAgent process is not stopped. In this event, use the ps command to determine the process ID of CSLogAgent and use the kill command to stop it. The debug session ends. All remote agent processes stop. For information about restarting the remote agent, see Stopping and Starting Remote Agent Services. Sample CSAgent Debug Output This section provides sample output of remote agents run in debug mode. Much of the startup output for remote agents in debug mode reflects the settings made in the CSAgent.ini file. Startup output also show various steps in establishing contact with the configuration provider for the remote agent. This section contains the following topics: •Sample Debug Output for a Windows Remote Agent •Sample Debug Output for a Solaris Remote Agent Sample Debug Output for a Windows Remote Agent This topic shows normal debug output from a Windows remote agent, including CSAgent, CSLogAgent, and CSWinAgent. The following output is from CSAgent at startup: D:...\CSAgent 33: csagent -p -z Debug printing on.. Running CSAgent server from command line.. CSAgent server starting ============================== Running as console application. Will listen on port 2004 Configuration will be fetched from 192.168.12.208:2003 Agents: CSLogAgent,CSWinAgent CSLogAgent File: ..\CSLogAgent\CSLogAgent.exe CSLogAgent Port: 2006 CSWinAgent File: ..\CSWinAgent\CSWinAgent.exe CSWinAgent Port: 2005 2 agents configured Permitted CSAgent Clients: 192.168.12.1-127 Hit Return/Enter to stop... Watchdog activated Listener activated CSLogAgent launched CSWinAgent launched The following normal output is from CSAgent after you press Enter to end the debug session: Service stopping Shutting down EndPoint library Listener terminating The following output is from CSLogAgent: CSLogAgent server starting ============================== Running as console application. Configuration will be fetched from 192.168.12.208:2003 Permitted CSLogAgent Clients: ... Cant get max number of connections maxNumberOfConnections using default 32 Agent library initialisedAgentLib: Attempting to connect to config provider at 192.168.12.208:2003 AgentLib: Connection established, handle 0x7e4af8 AgentLib: GetLogConfig reply received AgentLib: Disconnecting from config provider, handle 0x7e4af8 Config downloaded Will listen on port 2007 Will not log to a datafile. Stream thread N started Stream N waiting for connection Will use the Loglib library. Listening thread started... The following output is from CSWinAgent: CSWinAgent server starting ============================== Running as console application. Will listen on port 2005 Permitted CSWinAgent Clients: ... NTLIB: Library behaviour mode 2 NTLIB: Initialising locally NTLIB: The local computer name is ENG-IIS-WEST2 NTLIB: We are NOT a domain controller NTLIB: We are a member of the ENGINEERING domain Listener activated Sample Debug Output for a Solaris Remote Agent The following is startup output from a Solaris remote agent that is configured to run CSLogAgent: cmi-xdm5:5> CSAgent -z -p Running CSAgent server from command line.. Debug printing on.. CSAgent server starting ============================== Running as console application. Will listen on port 2004 Configuration will be fetched from 192.168.12.208:2003 Agents: CSLogAgent CSLogAgent File: /opt/CSCOacsag/CSLogAgent/CSLogAgent CSLogAgent Port: 2006 1 agents configured Permitted CSAgent Clients: ... Listener activated Hit Return/Enter to stop... Watchdog activated check_sys_limits set max file descriptors to 1024 Running CSLogAgent server from command line.. CSLogAgent server starting ============================== Running as console application. Configuration will be fetched from 192.168.12.208:2003 Permitted CSLogAgent Clients: ... Cant get max number of connections maxNumberOfConnections using default 32 CreateProcess cd /opt/CSCOacsag/CSLogAgent; /opt/CSCOacsag/CSLogAgent/CSLogAgent -z & pid = 8686 CSLogAgent launched Agent library initialised AgentLib: Attempting to connect to config provider at 192.168.12.208:2003 AgentLib: Connection established, handle 0x916c8 AgentLib: GetLogConfig reply received AgentLib: Disconnecting from config provider, handle 0x916c8 Config downloaded Will listen on port 2007 Will not log to a datafile. g_started_ok=1 Listening thread started... Rollover on /opt/CSCOacsag/Logs/Failed Attempts\Failed Attempts active.csv reset to manual. Rollover on /opt/CSCOacsag/Logs/RADIUS Accounting\RADIUS Accounting active.csv reset to manual. Rollover on /opt/CSCOacsag/Logs/TACACS+ Accounting\TACACS+ Accounting active.csv reset to manual. Rollover on /opt/CSCOacsag/Logs/TACACS+ Administration\Tacacs+ Administration active.csv reset to manual. Will use the Loglib library. Stream thread N started Stream N waiting for connection The following is normal output when you press Enter to end the debug session: Service stopping Shutting down EndPoint library Watchdog done. send kill to 8714
	Terms & Conditions \| Privacy Statement \| Cookie Policy \| Trademarks