The SESM installation process uses default values and values you enter during installation to configure the sample portal applications. Read this section if you want to change or fine-tune configuration after installation.

The SESM portal applications use the following MBeans:

To change attributes in these MBeans, you can either:

Make changes using the Agent View running on the application management port. For example, use the Agent View for NWSP. You can access the Agent View from the CDAT main window.
Edit the application MBean configuration file. For example, edit the nwsp.xml file for NWSP.

The installation process configures all three of the sample portal applications (NWSP, WAP, and PDA) using the same default port numbers. These port numbers are:

Application port—8080
Application management port—8180

Each sample portal application uses a different MBean configuration file. The files are located in a directory named for the application under the SESM installation directory:

nwsp

config
   nwsp.xml

wap

config
   wap.xml

pda

config
   pda.xml

Logger MBean

The Logger MBean configures both logging and debugging tools. The logging tool traces business events in the SESM portal. The debugging mechanism produces messages useful to developers in debugging applications. Table 5-1 describes the attributes in the Logger MBean.

Table 5-1: SESM Portal Application—Logger MBean

Attribute Name	Explanation
debug	Turns debugging on or off. That is, it controls whether Log.debug calls executed by the SESM application are displayed in the log file. Note Logging remains on regardless of this value. That is, all Log.trace and Log.warning calls executed in the SESM application are written to the log file regardless of the value of the debug attribute. To turn off logging, comment out the entire Logger MBean. Values for this attribute are: false—The application produces trace messages but not debug messages. The trace messages record business activity performed by the SESM portal. This setting is the normal, recommended setting for production environments. The trace messages provide important information for diagnosing configuration problems. true—The application produces trace and debug messages. This setting is intended for development environments to debug portal code behavior. The logging of debug messages can affect performance; hence, this setting is not recommended for production environments. The following parameters control the contents of debug messages that the application generates: logFrame, logStack, logThread, debugPatterns, and debugThreads. The following parameters control the types of logging messages produced: trace and warning. Installed default: false
debugPatterns	By specifying one or more patterns, you turn on a filtering mechanism that excludes any message that does not match the pattern. The patterns are file, class, or method names. Pattern matching is based on substring matches. For example, if you specify the pattern RADIUS, the software focuses on RADIUS messages. To specify multiple patterns, separate the patterns using a comma. Installed default: empty, which means that you receive all messages.
debugThreads	Specifies a specific thread name for which to show debugging messages. You can specify multiple thread names, separating them using a comma. For example: 6,13,22. By default, no thread name is specified. Because each user interaction with the SESM web application takes place in a thread named for that user, this parameter can be used to focus the logging trace on a specific user activity. Enter a list of thread names separated by commas. Installed default: empty
debugVerbosity	Specifies the level of detail in debugging messages. When the debug attribute is set to false, this attribute is ignored. Values are MAX, MED, or LOW. Installed default: LOW
logDateFormat	Specifies format of dates in the log file. Installed default: yyyyMMdd:HHmmss.SSS
logFile	Specifies the filename and location for the logging (tracing) of business events performed by the SESM application. The installed default is: application.home/logs/yyyy_mm_dd.application.log Where: application.home—A property whose value is set in the SESM start script. See Table 9-1. logs—A constant. All log files appear in the logs subdirectory under the application directory. yyyy_mm_dd —The year, month, and day that the file was created. application.log—A constant identifying the application log files.
logFrame	Controls whether or not to log the calling member function. Installed default: false
logStack	Controls whether or not to log stack traces. Installed default: false
logThread	Controls whether or not to log thread IDs. Installed default: true
logToErr	Controls whether or not to route log messages to stderr, in addition to the log file. This parameter is useful for monitoring the SESM web application at the command line. Displaying output to stderr is not recommended for production deployments. Installed default: true
trace	Controls whether or not to log trace messages. These messages indicate entry and exit to code points. Installed default: true
warning	Controls whether or not to log warning messages (nonfatal exceptions). Installed default: true

ManagementConsole MBean

The ManagementConsole MBean configures the portal's management console port, including valid user names and passwords for accessing the console. See the "Configuring the ManagementConsole MBean" section for more information.

SESM MBean

The SESM MBean configures SESM features and options, including the SESM mode.Table 5-2 describes the attributes in the SESM MBean.

Table 5-2: SESM Portal Application—SESM MBean

Attribute Name	Explanation
mode	An SESM portal runs in one of the following modes. RADIUS—In this mode, the SESM web application communicates with SSG and a RADIUS server. LDAP—In this mode, the SESM web application communicates with SSG and an LDAP directory. Demo—In this mode, the SESM web application does not communicate with other components. Rather, it simulates communication by reading data from a Merit flat file. This mode is intended for demonstrations only, when network components such as SSG, RADIUS, or an LDAP directory are not available. The value for mode is a Java system property named: `sesm.mode` This system property is different from most of the other system properties used in the MBean configuration files, in that, by default, the startup script does not set this system property. Therefore, the application runs in the mode specified in the MBean configuration file unless you explicitly override that value at run time. The installation program sets the default value to match the type of installation you perform (RADIUS, LDAP, or Demo.) To change the mode, you can: Reinstall the software. Edit the MBean configuration files, changing the mode and other attributes, as appropriate. Use the mode option on the SESM application startup script command line. This command line option provides a way to quickly switch between modes for testing purposes. You might need to alter the start script to access a different set of MBean configuration files for each mode, or use some other method to ensure that the attributes match the mode you are using. The syntax is: On Solaris: `jetty/bin/startNWSP.sh -mode {Demo \| RADIUS \| LDAP}` On Windows: `jetty\bin\startNWSP.cmd {Demo \| RADIUS \| LDAP}` The best way to change the SESM mode is to reinstall the software. Several other configuration attributes must be aligned with the mode for SESM to run properly in the selected mode. Also, you might not have all of the appropriate components to run in a mode other than the one you installed. For example, a demo installation does not install the SPE component.
singleSignOn	Enables or disables the single sign-on feature. true—Subscribers only need to authenticate during a session. Single sign-on offers the following advantages: Subscribers can stop the browser or navigate away from the SESM portal pages, and then return to the SESM pages later and not be required to reauthenticate. Subscribers do not need to reauthenticate if SESM automatic memory management clears sessions from the SESM portal. Point-to-point protocol (PPP) clients do not need to authenticate to the SESM portal. Instead, the SESM portal uses the PPP authenticated identity from SSG. false—Subscribers are required to reauthenticate for all of the cases described above. Installed default: true
autoConnect	Specifies if SESM should send connection requests to SSG for the services marked for auto connection in the subscriber's profile. Values are: false—SESM does not send connection requests to SSG true—SESM sends connection requests to SSG In RADIUS mode, set this attribute to false, because SSG automatically makes the connections immediately after authentication. You do not need SESM to request those connections. In LDAP mode, the SSG performs automatic connections if it obtains a service list from the RDP. If SSG does not obtain the service list from RDP, you should set this attribute to true. The Add Services option, which is set during RDP installation, controls whether or not the RDP returns a service list to SSG. The Add Services option configures RDP to either: Return a service list to SSG—SSG performs automatic connections for services marked as auto connect in a subscriber's profile. In this configuration, set the autoConnect attribute to false. Not return a service list to SSG—SSG cannot perform automatic connections. The advantage to this configuration is that it saves memory on the SSG device. In this configuration, set the autoConnect attribute to true.
profileCache Period	Specifies the time in seconds that a service or group object must be idle in the cache before its resources are deallocated from memory. Installed default: 600
sessionCachePeriod	The minimum time in seconds that an SESM session can be in memory without being accessed. If this value is 0 or undefined, the application calculates a value as: profileCachePeriod * 2. Installed default: 1200
confirmMutex Disconnect	Controls the action of the SESM portal if a subscriber is currently connected to a service in a mutually exclusive service group and then selects another service in that group. true—The SESM portal displays an error message to the subscriber stating that the current service must be disconnected before selecting the newly selected service. false—The SESM portal sends a request to SSG to disconnect the current service before sending the request to connect to the newly selected service. Installed default: false
memRequired	The minimum memory that must be available for the application to create a new SESM session or authenticate a subscriber. If this amount of memory is not available, the subscriber receives a "server busy" message. SESM applications include automatic memory management features that constantly work to free unused memory. If this attribute is set correctly, the application does not run out of memory. If this attribute is set too small, the application might run out of memory and terminate abnormally. The installed default is correct for the NWSP application. You might need to adjust the value for customized applications. If subscribers are receiving the server busy message too frequently, increase the amount of memory reserved for the application. This value is set in the startup script. See the "SESM Portal Application Memory Requirements" section for more information. Installed default: 10485760

SESMDemoMode MBean

The SESMDemoMode MBean configures SESM in demo mode. Table 5-3 describes the attributes in the SESMDemoMode MBean.

Table 5-3: SESM Portal Application—SESMDemoMode MBean

Attribute Name	Explanation
demoDataFile	Specifies the file that contains data for Demo mode. The installed value is: application.home/config/aaa.properties Where: application.home is a system property The SESM start script derives the value for application.home from an expected (installed) directory structure. To change the value of application.home, edit the start script.

DESSMode MBean

The DESSMode MBean configures SPE attributes used by the SESM application. Table 5-4 describes the attributes in the DESSMode MBean.

Table 5-4: SESM Portal Application—DESSMode MBean

Attribute Name	Explanation
tokenCheckInterval	The time in seconds between checking the authorization tokens. Default: 300 seconds
tokenMaxAge	The length of time in seconds a token can remain in cache without being used before it is deleted. Default: 600 seconds
naming	The component in distinguished name (dn) that the LDAP directory uses to allow access to the directory. For example: cn—Indicates the common name (cn) used in an NDS directory uid—Indicates the unique identifier (uid) used in an iPlanet directory

Attribute Name

Explanation

tokenCheckInterval

The time in seconds between checking the authorization tokens.

Default: 300 seconds

tokenMaxAge

The length of time in seconds a token can remain in cache without being used before it is deleted.

Default: 600 seconds

naming

The component in distinguished name (dn) that the LDAP directory uses to allow access to the directory. For example:

cn—Indicates the common name (cn) used in an NDS directory

uid—Indicates the unique identifier (uid) used in an iPlanet directory

SSG MBean

The SSG MBean configures communication between SESM web applications and SSGs. The MBean also includes attributes that determine which SSG should handle a subscriber request. Table 5-5 describes the attributes in the SSG MBean.

Table 5-5: SESM Portal Application—SSG MBean

Object	Attribute Name	Explanation
SSG	SSGIPPolicyClass	Sets the policy to use for mapping SSGs to subscribers. Installed default: com.cisco.sesm.ssg.DefaultSSGIPPolicy The DefaultSSGIPPolicy is implemented using the attributes described in the rest of this table. Other policies are subsets of DefaultSSGIPPolicy. Deployers might also implement customized policies of their own. See the javadoc for more information.
Global attributes The global attributes apply to all SSGs that the SESM web application might communicate with. To determine how an SSG is configured, use the show run command on the SSG host.	PORT	The global value for RADIUS ports on the SSG hosts. This value must match the value configured on the SSG device using the following command: `ssg radius-helper authenticationPort` You can create subnet entries in the MBean configuration file to override this global value for specific SSGs.
	TIMEOUTSECS	The number of seconds the SESM web application waits before timing out RADIUS packets that it sends to SSG. You cannot override this global value. Installed default: 5
	RETRIES	The number of times the SESM web application resends a RADIUS packet to SSG if no response is received. You cannot override this global value. Installed default: 3
	SECRET	The global value for the RADIUS protocol shared secret used for communication between the SESM web application and the SSGs. This value must match the value entered on the SSG device using the ssg radius-helper key command. You can create subnet entries in the MBean configuration file to override this global value for specific SSGs.
	MASK	The global value for the mask that the SESM web application applies to incoming subscriber IP addresses to derive an IP address for the SSG. You can create subnet entries in the MBean configuration file to override this global value for specific subnets.
SSG global attributes (continued)	THROTTLE	The global value for the maximum number of simultaneous requests that SESM portals can send to an SSG. The RADIUS protocol queues additional requests and issues them as the SSG returns responses or timeout messages for previous requests. If set correctly, this throttle attribute prevents the situation in which the SSG receives requests at a faster rate than it can handle, causing the SESM application to time out waiting for responses. Set the throttle value according to the ability of the SSG device to process access requests from a client. If the SESM portal times out while waiting for responses from the SSG, try adjusting this value lower. Installed default: 20
	BUNDLE_LENGTH	The global value for the port bundle length that SSGs use when the port-bundle host key feature is enabled. The port bundle length is the number of bits that SSG uses to indicate bundled slots. For example, a value of 4 indicates 16 bundled slots. This value must match the value used in the following command on the SSG host: `ssg port-map length` Default: You set this value during installation.
	PORT_BUNDLE_ HOST_KEY_ SWITCH	The global value indicating whether or not the port-bundle host key feature is enabled on the SSGs. If BUNDLE_LENGTH is zero, then the value of this switch is important. true—The SSGs have port-bundle host key enabled with a 0 bundle length. false—The SSGs do not have port-bundle host key enabled. If BUNDLE_LENGTH is non-zero, this switch is ignored, because a nonzero value implies the use of the host key feature.
	MIN_LOCAL_PORT MAX_LOCAL_PORT	Together, these two attributes specify a range of UDP ports for RADIUS protocol requests from the SESM portal application to the SSG. By using these attributes, you restrict the source ports used by NWSP to only the ports in the specified range. For example, you might want to restrict port usage if a firewall separates SESM from other components. In that case, you can configure the firewall to allow traffic through the specified range of ports. You can create subnet entries in the MBean configuration file to override this global value for specific SSGs.
SSG subnet entries Use subnet entries to override the global values or to map client subnets to specific SSGs when the port-bundle host key feature is not being used. See the "Associating SSGs with Subscriber Requests" section on page 5-15 for more information about using subnet entries.	Subnet entries use positional arguments.	The format for a subnet entry is: `<Call name="setSubnetAttribute"> <Arg>subnetAddress</Arg> <Arg>subnetMask</Arg> <Arg>argumentName</Arg> <Arg>argumentValue</Arg> </Call>` The call to setSubnetAttribute has four positional arguments: 1. subnetAddress is the subnet for which you are explicitly setting a value, overriding the globally set value. 2. subnetMask is the mask that can be applied to the subscriber's IP address to derive the subnet. 3. argumentName is the argument that you are explicitly setting: PORT—The SSG port for the specified subnet. Overrides the globally-set SSG port. MASK—The mask used on the subscriber's IP address to derive the subnet. Overrides the globally-set mask. SECRET—The shared secret used between SESM and SSG. Overrides the globally-set shared secret. BUNDLE_LENGTH—The host key bundle length used on the SSG. Overrides the globally-set bundle length. Bundle length is the number of bits that SSG uses for the port bundle feature. For example, a value of 4 indicates 16 bundled slots. A value of 0 indicates that the SSG is not using the port-bundle host key mechanism. This value must match the value used in the following command on the SSG host: `ssg port-map length` IP—Explicitly sets the IP address for the SSG that services the specified subnetAddress. THROTTLE—The maximum number of simultaneous requests that SESM portals can send to the SSG. Overrides the globally set throttle value. SESSION_LOCATION and SESSION_BRAND—The location or brand associated with the specified subnet. Valid values are defined as arbitrary properties in the WebApp MBean. See the "Configuring Location Awareness" section on page 5-22 for more information. MIN_LOCAL_PORT and MAX_LOCAL_PORT—The range of UDP ports used by the SESM portal to send messages to the SSG. Overrides the globally set range. 4. argumentValue is the value for argumentName.

AAA MBean

The AAA MBean configures communication between the SESM web application and the RADIUS servers, which occurs only when the SESM application is running in RADIUS mode.

Table 5-6 describes the attributes in the AAA MBean.

Table 5-6: SESM Portal Application—AAA MBean

Attribute Name	Explanation
throttle	The maximum number of simultaneous requests that SESM web applications can send to a RADIUS server. This is a RADIUS protocol attribute. The RADIUS protocol queues additional requests and issues them as the server returns responses or timeout messages for previous requests. Installed default: 256
timeOut	The number of seconds the SESM web application waits before timing out RADIUS packets that it sends to the AAA server. Installed default: 4
maxRetries	The number of times the SESM web application resends packets to the AAA server if no response is received. Installed default: 3
primaryIP	The IP address or the host name of the primary AAA server.
primaryPort	The port number that the primary RADIUS server listens on. Default: 1812
secret	The shared secret used between the RADIUS server and the SESM web application. The shared secret must be the same for the primary and secondary servers. It must match the secret specified when you configured SESM as a NAS client on the RADIUS server. Default: `cisco`.
secondaryIP	The IP address or host name of the secondary AAA server. If you are not using a secondary RADIUS server, reenter the primary server.
secondaryPort	The port number that the secondary RADIUS server listens on. If you are not using a secondary server, reenter the primary server. Default: 1812
servicePassword	The password that the SESM web application uses to request service profiles from the RADIUS server. It must match the service password values used in the service profiles in the RADIUS database. Default: `servicecisco`
serviceGroupPassword	The password that the SESM web application uses to request group profiles from the RADIUS server. It must match the service group password values used in the service group profiles in the RADIUS database. Default: `groupcisco`

Firewall MBean

The Firewall MBean configures fields on the NWSP My Firewall page. Table 5-7 describes the attributes in the Firewall MBean. For more information about configuring and using the SESM firewall features, see the "Personal Firewalls" section.

Firewall Protocols and Applications

The Firewall MBean defines a list of firewall protocols and firewall applications, which are SESM concepts used in a different way than the OSI protocol and application concepts. You can specify ACLs on firewall applications, but not on firewall protocols.

A firewall protocol defines components used to build the firewall applications. They consist of any Layer 3 or Layer 4 protocol and an optional port. (The combination of a lower layer protocol and a port might define an OSI layer 7 application, such as FTP.) For example, the following are some firewall protocols, shown as they are defined to the Firewall MBean:

<Key>ip</Key>
<Value>ip</Value>
 
<Key>tcp</Key>
<Value>tcp</Value>
 
<Key>ftp</Key>
<Value>tcp, 21</Value>
 
<Key>https</Key>
<Value>tcp,443</Value>
 
<Key>imap</Key>
<Value>tcp,143</Value>

The firewall applications are the items that are displayed on the My Firewall page in the Applications/Protocols column. They are the items on which ACLs are applied. A firewall application consists of one or more firewall protocols. For example:

<Key>ip</Key>
<Value>ip</Value>
 
<Key>tcp</Key>
<Value>tcp</Value>
 
<Key>ftp</Key>
<Value>ftp</Value>
 
<Key>email</Key>
<Value>smtp,pop2,pop3,imap</Value>
 
<Key>www</Key>
<Value>http,https</Value>

SESM includes many predefined firewall protocols and firewall applications. You can see all of these predefined values by accessing the NWSP Agent View. In the Firewall MBean, click in the value column for the read-only attributes AllApplicationDescriptions and AllProtocolDescriptions.

You can use the customProtocols and customApplications attributes in the Firewall MBean to define additional firewall protocols and firewall applications.

Table 5-7: SESM Portal Application—Firewall MBean

Attribute Name	Explanation
customProtocols	Defines additional firewall protocols. Each item in the array consists of two elements: Key—Names the firewall protocol. The name can be anything. Value—The lower layer protocol (OSI Layer 3 or 4 protocol) and an optional port, separated by a comma. The lower layer protocol value must be a protocol that the SSG host is configured to accept. For example: `<Key>tcp</Key> <Value>tcp</Value> <Key>ftp</Key> <Value>tcp, 21</Value>` See the "Firewall Protocols and Applications" section for a definition and more examples of firewall protocols. Several firewall protocols are predefined in SESM and do not need to be explicitly defined here.
customApplications	Defines additional firewall applications. Each item in the array consists of two elements: Key—Names the firewall application. The name can be anything. Value—A list of firewall protocols that comprise the application, separated by commas. Valid values are the SESM predefined and custom firewall protocols. To see a list of all defined protocols, open the portal's Agent View management console and click in the value column of the AllProtocolDescriptions attribute, a read-only attribute in the Firewall MBean. `<Key>ftp</Key> <Value>ftp</Value> <Key>www</Key> <Value>http,https</Value>` See the "Firewall Protocols and Applications" section for a definition and more examples of firewall applications.
displayApplications	Specifies the firewall applications that appear on the NWSP My Firewall page, in the Applications/Protocols column. Items in this list must be defined as predefined or custom firewall applications. To see a list of all defined applications, open the portal's Agent View management console and click in the value column of the AllApplicationsDescriptions attribute, a read-only attribute in the Firewall MBean. The text that represents the application on the My Firewall page is configured as a resource bundle in the portal application's directory. For example, for NWSP, resources are in: nwsp/webapp/WEB-INF/classes/messages[_locale].properties. The portal searches its resource bundles for the resource firewallAppNameDescription, where firewallAppName is the application defined in the Firewall MBean. If a matching resource is not found, then firewallAppName is displayed on the My Firewall page. For example, consider the following firewall application: www The portal searches for a resource named wwwDescription, and displays the text in the appropriate language on the My Firewall page. (In the installed files, this is World-Wide-Web for the en locale.) If the wwwDescription resource did not exist, then www would appear on the My Firewall page.
direction	Specifies direction (in or out) for the default access control direction in the ACLs created by SESM. See the "ACLs Generated from Entries on the Firewall Pages" section for more information about created ACLs. Value values for direction are: in—Upstream, from the subscriber out—Downstream, to the subscriber All connections have a return path. A block on in also affects traffic traveling in the opposite direction, and vice-versa. For any ACL, the choice of whether to control the in or out direction is a matter of preference.
returnOption	Sets the return option for TCP applications. Recommended values are: permit and default. Default refers to the Permit/Deny All Else button on the My Farewell page. Default: permit Note You can alter the My Firewall JSP to add a button allowing the subscriber to choose the TCP return option. The JSP contains commented-out code for an ipPermission button, which you could copy to implement a return TCP permission button.

WebApp MBean

The WebApp MBean configures options of the SESM portal application, including:

Attributes that control the behavior of the application
Attributes that control captive portal service redirections handled by NWSP
Context parameters, which are used by an application for any arbitrary reason. The nwsp.xml file contains an example of using context parameters to control web page content based on location.

Table 5-8 describes the attributes in the WebApp MBean.

Table 5-8: SESM Portal Application—WebApp MBean

Attribute Name	Explanation
confirmAtServiceLogon	Controls whether or not the application prompts the user for confirmation before it acts on a request to start a service. Default: FALSE
confirmAtServiceLogoff	Controls whether or not the application prompts the user for confirmation before it acts on a request to log off. Default: TRUE
confirmAtAccountLogoff	Controls whether or not the application prompts the user for confirmation before it acts on a request to log off of the SESM application. Default: TRUE
disconnectWhenUnsubscribe	Controls whether SESM requests the SSG to disconnect an existing service connection if the subscriber unsubscribes from that service. Applies to LDAP mode only.
sessionTimeOut	The number of seconds of inactivity allowed before the application closes a session. This value overrides the timeout value in the nwsp.jetty.xml file. Default: 7200
usernameMinLength usernameMaxLength passwordMinLength passwordMaxLength	These attributes control the length of user names and passwords. A value of 0 is valid for usernameMinLength and passwordMinLength. Configuration files from SESM releases earlier than Release 3.1(7) that use the credentialMaxLength attribute are valid. The value in credentialMaxLength sets usernameMaxLength and passwordMaxLength values. Defaults for usernameMinLength and passwordMinLength: 1 Defaults for usernameMaxLength and passwordMaxLength: 30
prepaidRedirectionURL serviceNotGivenURI defaultURI serviceSubscriptionURI noSubscribePermissionURI serviceStartURI serviceLogonURI	These attributes are related to the captive portal solution. See Table 11-4 for explanations of these attributes.
addDimension entries	You can create arbitrary attributes and associate them with subscriber requests in the manner described in the "Arbitrary Attributes" section.

Location MBean

The Location MBean defines locations and associated attributes for the location awareness feature based on complete ID attributes. Table 5-9 describes the attributes in the Location MBean. For more information about configuring location awareness, see "Location Awareness" section.

Table 5-9: SESM Portal Application—Location MBean

Attribute Name Explanation

Attribute Name	Explanation
locationService	Defines the SESM class containing the logic for location determination. You can change this attribute to point to a customized service provider interface (SPI) class.
locations	Defines an array of location values. Each location in the array consists of the following items: Note Configure locations by editing the configuration file, not by using AgentView. name—Names the location. The location can be any value, but it must match your intended usage. parameters—An array of one or more elements defining the attributes for the location. Each item in the parameters array consists of a class name and attribute values required for the class. The following class names are valid: com.cisco.sesm.core.location.IPRangeParam—Associates this location with a specified range of edge session IP addresses. The edge session IP address is the value passed from the SSG to SESM in standard RADIUS attribute number 8, FRAMED_IP_ADDRESS. IPRangeParam requires two attributes defining the start and end of the IP address range `<New class="com.cisco.sesm.core.location.IPRangeParam"> <Set name="start" type="String">10.0.0.0</Set> <Set name="end" type="String">10.10.0.0</Set> </New>` com.cisco.sesm.core.location.VPIRangeParam—Associates this location with a specified range of virtual path identifier (VPI). The edge session VPI is the value passed from the SSG to SESM in the RADIUS VSA (attribute number 26), Account-Info subattribute (number 250), subattribute code $VP. Although SSG passes both the VPI and the virtual channel identifier (the VPI/VCI attribute), SESM Release 3.1(7) uses only the VPI. VPIRangeParam requires two attributes defining the start and end of the VPI range. `<New class="com.cisco.sesm.core.location.VPIRangeParam"> <Set name="start" type="int">1</Set> <Set name="end" type="int">2</Set> </New>` com.cisco.sesm.core.location.SubInterfaceParam—Associates this location with a specified subinterface. Subinterface ranges are not permitted in SESM Release 3.1(7).The edge session subinterface is the value passed from the SSG to SESM in the RADIUS VSA (attribute number 26), Account-Info subattribute (number 250), subattribute code $SI. Some examples of subinterface values are: Ethernet0/0, FastEthernet4/0, or ATM2/0. SubInterfaceParam requires one attribute defining the subinterface to associate with the location: `<New class="com.cisco.sesm.core.location.SubInterfaceParam"> <Set name="subInterface" type="String">Ethernet0/0</Set> </New>` The parameters array can define multiple attributes for a location. In that case, an edge session is associated with the location only when the session attributes match all of the attributes defined for the location.

locationService

Defines the SESM class containing the logic for location determination. You can change this attribute to point to a customized service provider interface (SPI) class.

locations

Defines an array of location values. Each location in the array consists of the following items:

Note Configure locations by editing the configuration file, not by using AgentView.

name—Names the location. The location can be any value, but it must match your intended usage.
parameters—An array of one or more elements defining the attributes for the location. Each item in the parameters array consists of a class name and attribute values required for the class. The following class names are valid:

com.cisco.sesm.core.location.IPRangeParam—Associates this location with a specified range of edge session IP addresses. The edge session IP address is the value passed from the SSG to SESM in standard RADIUS attribute number 8, FRAMED_IP_ADDRESS.

: IPRangeParam requires two attributes defining the start and end of the IP address range

<New class="com.cisco.sesm.core.location.IPRangeParam">
<Set name="start" type="String">10.0.0.0</Set>
<Set name="end" type="String">10.10.0.0</Set>
</New>

com.cisco.sesm.core.location.VPIRangeParam—Associates this location with a specified range of virtual path identifier (VPI). The edge session VPI is the value passed from the SSG to SESM in the RADIUS VSA (attribute number 26), Account-Info subattribute (number 250), subattribute code $VP. Although SSG passes both the VPI and the virtual channel identifier (the VPI/VCI attribute), SESM Release 3.1(7) uses only the VPI.

: VPIRangeParam requires two attributes defining the start and end of the VPI range.

<New class="com.cisco.sesm.core.location.VPIRangeParam">
<Set name="start" type="int">1</Set>
<Set name="end" type="int">2</Set>
</New>

com.cisco.sesm.core.location.SubInterfaceParam—Associates this location with a specified subinterface. Subinterface ranges are not permitted in SESM Release 3.1(7).The edge session subinterface is the value passed from the SSG to SESM in the RADIUS VSA (attribute number 26), Account-Info subattribute (number 250), subattribute code $SI. Some examples of subinterface values are: Ethernet0/0, FastEthernet4/0, or ATM2/0.

: SubInterfaceParam requires one attribute defining the subinterface to associate with the location:

<New class="com.cisco.sesm.core.location.SubInterfaceParam">
<Set name="subInterface" type="String">Ethernet0/0</Set>
</New>

: The parameters array can define multiple attributes for a location. In that case, an edge session is associated with the location only when the session attributes match all of the attributes defined for the location.

Associating SSGs with Subscriber Requests

A typical SESM deployment consists of multiple SSGs. The installation process configures communication with one SSG when you choose the appropriate options. This section describes how to configure communication with additional SSGs. It includes the following topics:

Setting SSG Global and Subnet Entries

You can set the attributes that associate an SSG with subscriber requests globally, by client subnet, or for a specific client IP address, as follows:

Global attribute elements—A global setting applies to all SSGs. For example, a global shared secret setting means that all SSGs are configured using the same secret. The global attributes are: PORT, SECRET, MASK, and BUNDLE_LENGTH.

Subnet attribute elements—The subnet attributes apply to a specific subnet and override the global attribute value. The subnet attributes are optional; if any of them are not specifically coded, the global attribute value is used. Subnet attributes that you can supply are: PORT, SECRET, MASK, BUNDLE_LENGTH, and IP. The IP attribute is the IP address of the SSG for a specified subnet.

: You can also specify some optional session information in a subnet entry, using the SESSION_LOCATION and SESSION_BRAND attributes.

A specific client IP address can be specified in a subnet element.

Using Port-bundle Host Key with Identical SSG Configurations

The easiest way to associate the correct SSG with each subscriber request is to use the port-bundle host key feature on all SSGs, and configure certain attributes identically on all of the SSG hosts. We recommend using the port-bundle host key feature unless you require backward compatibility with SSD Release 2.5(1).

Note To use the port-bundle host key feature, the SSG device must be running Cisco IOS Release 12.2(2)B or later and the SSG port-bundle host key feature must be configured appropriately.

When the port-bundle host key feature is enabled on an SSG, the SSG replaces the subscriber IP address in the request with a software token (or key) when it forwards the request to SESM. The SESM application uses this key in its responses to SSG, and the SSG does an internal translation to an actual host object.

The key is a unique combination of an SSG IP address from a range of IP addresses and a port number from a range of port numbers, as follows:

: IP_address:port

The IP address and port ranges are configured on each SSG. The key uniquely identifies each subscriber currently logged on to SESM, even when multiple subscribers are using the same IP address.

To use the port-bundle host key feature to associate SSGs, follow these procedures:

1. Enable and configure the port-bundle host key feature on all of the SSGs, as described in the Configuring the Port-Bundle Host Key Feature on SSG.

2. Configure the same values on all of the SSG hosts for the following attributes:

Port—The SSG port on the SSG host. Specify the port that SSG uses to listen for RADIUS requests from an SESM application. Configure this value on the SSG device using the following command:

ssg radius-helper authenticationPort

Shared secret—The shared secret used for communication between SSG and an SESM application. Configure this value on the SSG device with the following command:

ssg radius-helper key

Port bundle length—The number of bits that SSG uses for port bundling when the port-bundle host key feature is enabled. This value must be 0 or 4. Configure this value on the SSG device with the following command:

ssg port-map length

3. When the SESM installation program prompts you, enter the globally-configured values in Step 2. These values are saved as global elements in the SSG MBean, as the following example illustrates.

Example Using Port-Bundle Host Key

When the port-bundle host key feature is enabled and configured, you can set all parameters globally.

<Configure name="com.cisco.aggbu:name=SSG">
<Call name="setGlobalAttribute"><Arg>PORT</Arg><Arg>1812</Arg></Call>
<Call name="setGlobalAttribute"><Arg>SECRET</Arg><Arg>cisco</Arg></Call>
<Call name="setGlobalAttribute"><Arg>MASK</Arg><Arg>255.255.255.255</Arg></Call>
<Call name="setGlobalAttribute"><Arg>BUNDLE_LENGTH</Arg><Arg>4</Arg></Call>
</Configure>

In this example, all SSGs are configured to use a port of 1812 and a shared RADIUS secret of cisco. The BUNDLE_LENGTH of 4 indicates that port-bundle host key is configured on all SSGs.

The MASK attribute specifies the mask that SESM applies to the client (source) IP address in a received message to determine the client's subnet, and, from that, the SSG IP address. However, when a host key is used, the client (source) IP address is the SSG IP address. The SESM installation program provides the default mask of 255.255.255.255.

Using Port-bundle Host Key with Varying SSG Configurations

If port-bundle host key is enabled on all SSGs, but some are configured differently, you can configure the global case and then specifically configure exceptions. For example, if all but one SSG is assigned the same shared secret, you can configure the shared secret attribute globally, and then add one subnet entry to configure the different secret for the single SSG.

The installation program lets you provide one set of SSG global attribute values and one subnet entry. It records these attribute values in the <Configure name="SSG"> section of the application MBean configuration file, as illustrated in the following example.

Example Using Port-bundle Host Key with One Noncomplying SSG

In this example, port-bundle host key is enabled on all SSGs. In addition, all SSGs are using the same port, secret, and client IP address mask, except that one SSG uses a different port. In this case, you can set all parameters globally, and then use one subnet entry to define:

The client subnet being serviced by the SSG that uses the nonconforming port.
The port value that overrides the globally-set port value.

In the following example, the SSG that services subnet 10.1.1.0 uses port 1245.

<Configure name="com.cisco.aggbu:name=SSG">
<Call name="setGlobalAttribute"><Arg>PORT</Arg><Arg>1812</Arg></Call>
<Call name="setGlobalAttribute"><Arg>SECRET</Arg><Arg>cisco</Arg></Call>
<Call name="setGlobalAttribute"><Arg>MASK</Arg><Arg>255.255.255.255</Arg></Call>
<Call name="setGlobalAttribute"><Arg>BUNDLE_LENGTH</Arg><Arg>4</Arg></Call>
<Call name="setSubnetAttribute"><Arg>10.1.1.0</Arg><Arg>255.255.255.0</Arg><Arg>PORT
</Arg><Arg>1245</Arg></Call>
</Configure>

Specifically Mapping SSGs to Subscriber Subnets

Each request arriving at an SESM web application contains a source, or client, IP address. SESM uses this client IP address to determine which SSG should handle each request.

If the configuration file explicitly provides an SSG IP address for a subnet or a specific client IP address, SESM uses that SSG. You code an explicit IP address in a <subnet> element. The MASK value in the subnet element specifies whether the element applies to a subnet or to a specific subscriber IP address. The <IP> parameter in the subnet element specifies the SSG IP address.

: For example, the following subnet entry explicitly sets the SSG IP address to 10.6.7.1 for subnet 10.2.0.0:

<Call name="setSubnetAttribute">

<Arg>10.2.0.0</Arg><Arg>255.255.0.0</Arg><Arg>IP</Arg><Arg>10.6.7.1</Arg></Call>

If an explicit IP address for the SSG is not provided, SESM masks the subscriber's IP address to determine the SSG that should handle the request.

: Use masking as follows:

Example Mapping Client Subnets to SSGs

In this example, port-bundle host key is not being used. In this case, you must explicitly define the mapping from subscriber subnet to the SSG IP address.

<Configure name="com.cisco.aggbu:name=SSG">
<Call name="setGlobalAttribute"><Arg>PORT</Arg><Arg>1645</Arg></Call>
<Call name="setGlobalAttribute"><Arg>SECRET</Arg><Arg>cisco</Arg></Call>
<Call name="setGlobalAttribute"><Arg>MASK</Arg><Arg>255.255.255.255</Arg></Call>
<Call name="setGlobalAttribute"><Arg>BUNDLE_LENGTH</Arg><Arg>0</Arg></Call>
<Call name="setSubnetAttribute"><Arg>10.1.1.0</Arg><Arg>255.255.255.0</Arg><Arg>IP
</Arg><Arg>10.21.1.2</Arg></Call>
<Call name="setSubnetAttribute"><Arg>10.1.2.0</Arg><Arg>255.255.255.0</Arg><Arg>IP
</Arg><Arg>10.21.2.2</Arg></Call>
<Call name="setSubnetAttribute"><Arg>10.1.3.0</Arg><Arg>255.255.255.0</Arg><Arg>IP
</Arg><Arg>10.21.3.2</Arg></Call>
<Call name="setSubnetAttribute"><Arg>10.1.4.0</Arg><Arg>255.255.255.0</Arg><Arg>IP
</Arg><Arg>10.21.4.2</Arg></Call>
</Configure>

Configuring a Customized SESM Application

The Cisco SESM is a collection of components for creating specialized Java 2 Platform, Enterprise Edition (J2EE) web server applications. J2EE provides a framework for using various Java-based components to develop multi-tiered applications. The multi-tiered application (as opposed to the 2-tiered client server application) provides many opportunities for isolating and controlling functional pieces of a large application. For more information about the J2EE development platform, see:

: http://java.sun.com/j2ee/

SESM Application Definition

A Cisco SESM application consists of the following:

SESM servlets and classes—The SESM API defines the SESM classes, including the configurable MBeans, used to implement the application functionality.

ConfigAgent—The ConfigAgent is a Cisco developed MBean that configures other MBeans. It configures MBeans that are registered with the JMX server by applying parameter values from .xml files. Because .xml files are easily maintained and changed by system administrators, applications that use ConfigAgent are highly configurable without recompiling. Chapter 4 in this guide explains all of the configurable parameters in all of the MBeans.

Java Server Pages(JSPs)—JSPs offer a way to deliver dynamic content in web pages. Web developers at the deployment site can control their subscriber's SESM experience through the JSPs. The Cisco Subscriber Edge Services Manager Web Developer Guide provides instructions for defining and compiling JSPs.

Images—Images are used by the JSPs and control the look and feel and branding aspects of an SESM application. The Cisco Subscriber Edge Services Manager Web Developer Guide provides instructions for changing images and incorporating them into the JSPs.

SESM Application Names

The SESM application name that you use for a customized application is arbitrary, but it must match in all of the following locations:

The name of the application-specific subdirectory under the installation directory. For example, the directory that holds all application specific information for the NWSP application is:

<installDir>nwsp

Application parameter inside the application startup script. In the installed scripts, the application name is hard coded on the line that calls the generic start script. For example, for the NWSP application on Windows NT, the call line is:

call "%SCRIPTDIR%start.cmd" nwsp %PORTNO%

Name of the application's configuration file in the jetty subdirectory. For example, for the NWSP application, the configuration filename is:

nwsp.jetty.xml

An application name in the startup script tells the ConfigAgent which configuration file to open. The application name is passed to ConfigAgent by the application startup scripts. The application name might also be used in other ways. For example, you can configure the parameter that defines the Jetty Server log filename to incorporate the application name in the log filename.

Creating Configuration Files and Startup Scripts

Application developers at your site might make changes to the delivered NWSP sample application, producing a customized application. Customized applications require their own set of configuration files, although the files might be very similar to those provided for the sample application.

To create the required configuration files and startup scripts for a customized SESM application that will run in a Jetty server, follow these steps:

Step 1 Create a configuration file for the new application in the container's config directory. You can copy the nwsp.jetty.xml file and appropriately rename it. For example:

jetty

config

newApplication.jetty.xml

Step 2 Edit the new file.

Step 3 Create a startup script for the new application by copying the startNWSP script and appropriately renaming the copy. For example:

jetty

bin

startNewApplication

Step 4 Edit the new file, changing the application name and the port number parameters.

Step 5 Copy the nwsp directory structure, and rename the nwsp objects appropriately. For example, copy:

nwsp

config

nwsp.xml

docroot
docs

Step 6 See the Cisco Subscriber Edge Services Manager Web Developer Guide for information about customizing the JSPs, images, and other components. That guide also describes how to update the docroot folder, recompile affected components, and edit the web.xml file.

Table of Contents

Example Using Port-Bundle Host Key

Example Using Port-bundle Host Key with One Noncomplying SSG

Example Mapping Client Subnets to SSGs