Table Of Contents
Cisco Subscriber Edge Services Manager SDK Overview
This white paper describes Cisco Subscriber Edge Services Manager (SESM) software architecture and platform SDK. The guiding principles of the SESM system architecture are interoperability and integration. Interoperability is discussed in the SESM System Architecture paper. This paper focuses on integration as enabled by the J2EE1 (Java 2 Enterprise Edition) based SESM platform SDK.
A Brief Introduction to SESM
Cisco SESM is an extensible solution for providing on-demand value-added billable services and access control at the network edge. Internet service providers (ISPs) and network access providers (NAPs) deploy SESM solutions to provide value-added services to their subscriber base and management capabilities to their administrators.
Cisco SESM encompasses:
•Subscriber and service management
•RADIUS AAA, LDAP and RDBMS integration
•Subscriber web portals
•Post and prepaid time and volume billing
•Integrated management for solution components
Cisco SESM can be deployed across all broadband access types, including Digital Subscriber Line (DSL), mobile, PWLAN, ETTx, Cable and Dial. It supports multiple devices, locales, brands, service types and mechanisms of policy control.
Cisco SESM interoperates with the Cisco service gateway products: The Service Selection Gateway (SSG), Service Gateway (SG), and Content Services Gateway (CSG). These are generically referred to as "gateways" in this document. The gateways are, classically speaking, points of enforcement for the policy decisions made by the components of the SESM solution.
Cisco SESM provides a distributed, highly scalable solution on a standards-based platform for building integrated applications for subscriber management and service delivery at the edge. It is designed for extensibility and OSS integration. It is suitable for deployment in service provider and network access provider environments.
Cisco SESM has been thoroughly tested and globally deployed in a wide variety of service provider environments. It has been serving subscribers for many years. The Cisco SESM platform SDK is based on a well-established suite of core components and is designed to evolve and adapt with the changing requirements of service providers and end users.
Figure 1 illustrates family of applications that make up the SESM solution today. As the SESM solution continues to evolve, the list of components that it encompasses will expand to address further features required in this space.
SESM Family of Applications
•SESM Web Portals (NWSP, WAP, PDA)—J2EE Web application, ships with the Jetty server as a bundled package. Different web portal applications include: NWSP exhibits all SESM features; PDA, specialized for PDAs; WAP, specialized for WAP applications.
•SESM Captive Portal—Applies L5-7 policy management for L3/4 redirection.
•SESM Message Portal—Displays message for subscribers based on their profile. Used for new service advertisement or system messages.
•SESM Web Services Gateway—SOAP-based interface supporting integration for session control and service activation.
•RADIUS Data Proxy—Protocol translation between RADIUS and various data sources.
•Cisco Distributed Administration Tool (CDAT)—Subscriber and service management.
•Application Management—Java Management Extensions (JMX) based application management for all solution components.
A Brief Introduction to J2EE
To better understand the SESM architecture, it is important to understand that it is based on a J2EE platform. This section is a brief introduction to the essential elements of J2EE 1.4. For the complete, 280-page specification, please visit:
J2EE is a set of coordinated specifications and practices that focus on developing, deploying, and managing multi-tier applications for both client and server deployments. It builds on Java 2 Platform, Standard Edition (J2SE). J2EE adds the capabilities required for enterprise applications.
Figure 2 is borrowed from the Sun J2EE page http://java.sun.com/j2ee/. It illustrates that the J2EE platform is a combination of tools and blueprints, i.e. the "how to" bit, and technologies, i.e. "with what". J2EE is not just a set of technologies, but also a description of how to use them.
J2EE and SESM
The J2EE platform defines a set of standard services—APIs and protocols—required to build enterprise applications. This is a growing list (see www.jcp.org for a description of the Java Community Process, the means by which the Java platform is extended).
•Servlets and JavaServer Pages (JSPs—SESM web portals are based on these technologies which will be familiar to most web developers. For details on this technology, please visit:
•HTTP and HTTPS—basis of secure interoperability for web portals and the Web Services Gateway
•Java Transaction API (JTA)—SESM will use the JTA for transactional control of services over multiple edge devices in the future. For detailed information about this technology, please visit:
•RMI-IIOP—used where SESM extensions interoperate with IIOP interfaces defined in third party solution elements. For detailed information about this technology, please visit:
•Java IDL—used for RMI interoperation between Java applications (ie: remote application management). For detailed information about this technology, please visit:
•Java Database Connectivity (JDBC)—used where SESM components integrate with RDBMSs (ie: by the SPE component). For detailed information about this technology, please visit:
•Java Messaging Service (JMS)—SESM uses JMS where integration with message buses is required. For detailed information about this technology, please visit:
•Java Naming and Directory Interface (JNDI)—SESM uses JNDI as the interface for integrating with LDAP directories, e.g. the SPE, and to support the standard J2EE programming model for object lookups. For detailed information about this technology, please visit:
•JavaMail and JavaBeans Activation Framework—SESM would use JavaMail for sending mail notifications. The Activation Framework is required by JavaMail. For detailed information about this technology, please visit:
•Java API for XML Parsing (JAXP)—SESM uses public domain implementations of this API for a wide variety of XML related tasks. For detailed information about this technology, please visit:
•J2EE Connector Architecture—Defines the design goals for connectors used by SESM. For detailed information about this technology, please visit:
•Security Services—SESM security is evolving to this standard. For detailed information about this technology, please visit:
•Web Services—Implemented by the Web Services Gateway (WSG). For detailed information about this technology, please visit:
•Management—All SESM applications are managed via JMX. For detailed information about this technology, please visit:
•Deployment—All SESM web portal applications and the WSG are bundled as Web Archive Resource (WAR) files suitable for deployment in third party J2EE servers. The other SESM applications are also compatible with J2EE servers and will evolve to better fit the model, e.g. by making use of container based security. For detailed information about this technology, please visit:
Why is J2EE Important?
•Consistent programming, deployment and management model—Not only does J2EE provide the standard services, it also defines how to use them so that extensions to J2EE will be consistent with the existing interfaces. Further, all J2EE applications are also deployed and managed identically, so that the environment can be standardized.
•Time to Market—J2EE uses "containers" to simplify development. It categorizes separate business logic from resource and lifecycle management, which means that developers can focus on writing business logic rather than writing enterprise infrastructure. A J2EE server is the implementation of a container for server type applications.
•Freedom of choice—J2EE technology is a set of standards that vendors can implement. The vendors are free to compete on implementations but not on standards or APIs. Sun supplies a comprehensive J2EE Compatibility Test Suite (CTS) to J2EE licensees.
•Simplified interoperability—J2EE technology makes it easier to connect the applications and systems already deployed and bring those capabilities to the web, cell phones, and devices. J2EE offers Java Message Service, CORBA, Web Services etc.
J2EE is important because it provides a blueprint for a complete enterprise-computing solution on the Java platform. The blueprint design guidelines for J2EE describe the application model and best practises for using J2EE. The application model offers a simplified approach to developing highly available and scalable Internet- and Intranet-based solutions.
Where the previous section briefly reviewed J2EE, this section describes how SESM uses and extends J2EE.
SESM Software Architecture
SESM Software Architecture
The core of the SESM applications are the SESM Sessions that hold the state of the edge gateway devices, control interaction with those gateways, and enforce policy control as defined by the various data sources with which the system interacts.
The SESM Session interacts with the other parts of the SESM Model for accounts, services, subscriptions, authorization, and other business model services. These business model services are implemented via plug-in components to the SESM platform as described later in this document.
SESM SDK Component Libraries
The SESM SDK is an extension of J2EE for applications that interact with the gateways. Like the J2EE platform itself, it has evolved over time.
The Cisco SESM solution components all share one of two basic architectures for web applications, e.g. the web portals and the web services gateway, or for server applications such as the RADIUS Data Proxy.
The libraries that are used to build the SESM applications are divided between SESM specific code and public domain code. As the J2EE specification evolves and provides support for parts of what are SESM today, the SESM platform will evolve to use the J2EE standards.
SESM Specific Libraries
These are the libraries that the SESM SDK is based on presented in the order that they are typically encountered when an application starts up. The documentation for these components can be found in the docs directory of the SESM distribution.
•Types (com.cisco.sesm.types.jar)—basic types used in SESM
•Util (com.cisco.sesm.util.jar)—basic utilities used in SESM
•JMX (com.cisco.sesm.jmx.jar)—simple JMX-based container for reading JMX configuration files which, in turn, start up other containers, such as Jetty. Also includes adaptors for persistence and configuration. All SESM applications are started via this mechanism.
•Logging (com.cisco.sesm.logging.jar)—basic logging utilities
•Extensible Request Proxy (com.cisco.sesm.erp.jar)—provides interfaces and classes for the Extensible Request Proxy (ERP) framework. For examples of applications based on ERP, see the RADIUS Data Proxy (RDP) and Service SSG simulator.
•Internationalisation and Localisation (com.cisco.sesm.i18nl10n.jar)—support for internationalisation of messages and exceptions, and localisation using locales for formats and character encoding including a JSP taglib for web applications. Used in web applications and exceptions.
•Application Management (com.cisco.sesm.appmgmt.remotemanagement.jar)—tools for RMI based JMX.
•Jetty (com.cisco.sesm.jetty.jar)—Jetty specific handlers for the tcp-redirect and Port Bundle Host Key (PBHK) features and JMX MBeans for their configuration.
•RADIUS (com.cisco.sesm.radius.jar)—RFC compliant RADIUS implementation
•Platform (com.cisco.sesm.platform.jar)—SESM platform extensions base classes, factories and MemoryContext JNDI implementation
•Web applications (com.cisco.sesm.webapps.jar)—MVC based web application toolkit used for the web portals
•Model (com.cisco.sesm.model.jar)—business model for SESM applications and associated classes for system services and SPIs. Also includes web portal specific Controller classes (see the Web Applications library)
Public Domain Libraries
In addition to the SESM specific libraries, SESM also ships with a number of public domain implementations of J2EE services.
•Jetty—Servlet container that uses the Jasper JSP compiler. Jetty is available from
http://jetty.mortbay.org/jetty/index.html. The Jetty libraries are available in the jetty/lib directory of the SESM distribution.
The following are distributed in the redist directory of the SESM distribution:
•Axis—implementation of Simple Object Access Protocol (SOAP) used by SESM with associated tools for SOAP based applications. Axis is available from http://ws.apache.org/axis/.
•Java API for XML Parsing (JAXP)—Java API for XML Parsing with the Crimson implementation from Apache. Crimson is available from http://xml.apache.org/crimson/.
•Java Management Extensions (JMX)—reference implementation from Sun. The JMX RI is available from
•Java Naming and Directory interfaces (JNDI)—JNDI and LDAP implementation from Sun. The JNDI classes and various implementations are available from http://java.sun.com/products/jndi.
•Log4J—The log4J API is a commonly logging API. Log4J may be found at
•MX4J—An open source implementation of the JMX 1.1 specification and associated tools. MX4J may be found at http://jakarta.apache.org/log4j/docs/index.html.
•Jakarta Regular Expressions Library—Regular expression tools. The Jakarta distribution may be found at
•UII—A Struts based Cisco proprietary library for web based administration applications.
•Web JMX Library—The Web JMX library implements an enhanced, as compared to the Sun RI, JMX Agent View interface. The Web JMX project may be found at http://sourceforge.net/projects/webjmx.
•Subscriber Policy Engine (SPE)—An implementation of authorization, authentication, self care and subscriber management. The SPE is a Cisco proprietary product.
How it all Fits Together
The various components described above comprise the toolkit used to build the SESM applications. Following is a description of the applications that tend to be grouped into web applications, (ie: web, captive and message portals, or servers like the RDP). All the applications components are configured and managed via JMX MBeans and are designed to be deployed in containers, which are also configured and managed by JMX.
All SESM applications are started via the JMX backbone. The basic steps are illustrated in Figure 4:
SESM Applications and the JMX Backbone
This sequence is started by the invocation of com.cisco.sesm.jmx.Main illustrated below:java -classpath $CLASSPATH com.cisco.sesm.jmx.Main $CONFIG_FILES
Where $CONFIG_FILES files is a list of XML MBean configuration files for the application containers. In this way, for example, the Jetty server is started up. It, in turn, will load the web.xml J2EE deployment descriptor. The deployment descriptor will identify the MBean configuration files for the components that a specific application requires.
Management, configuration, monitoring and control, is implemented via standard JMX interfaces. SESM ships with an application management tool which is built on top of the JMX Agent View interfaces. There are also various toolkits available to create SNMP MIBs from MBeans, to be able to send traps from MBeans and to integrate JMX with other network management platforms. See http://java.sun.com/products/JavaManagement/index.html.
Integration with the Web Portals
The SESM web portals display web pages and are used by subscribers to interact with the SESM solution.
SESM Web Portal
There are several points of integration for the SESM web portals, which depend on what already exists in the target environment. This is not a mutually exclusive list; rather, more than one of these options can be employed in a given deployment.
Changing the look and feel of the web portal applications - This is the typical first step where the JSPs that make up the web applications are changed to reflect the desired branding of the deployer. In this case, the SESM solution is typically deployed in a "turnkey" fashion in which no other J2EE servers are deployed.
Deploying the web application in an existing web application container—This is a possible next step where there is already a J2EE server available. In this case the WAR file that packages the SESM web applications would be deployed using the server's deployment tools and the JMX backbone would be that of the server.
Using the SESM Model in an existing application—When J2EE based web applications already exist, and only business logic for gateways interaction is required, then the SESM Model API can be called from existing, or new, web applications.
Plugging in different implementations of the system services—This would apply wherever the SESM Model is used. Each system service, shown at the bottom of the diagram above, has a Service Provider Interface (SPI) that supports the development of alternative implementations. Which implementation is used for a given system service is configured in the application's deployment descriptors. SESM ships with a number of different implementations as part of the standard distribution. The list of system services and bundled extensions continues to grow as more features are added to the platform.
Integration with the Captive Portal
The Captive Portal is used to control what happens when an application request, layers 5-7, is redirected to Layer 3-4 (i.e. when the destination IP address or port number of a request from an application is changed, and the application layers in the protocol request still have the previous IP address or domain and port number encode in them). This is analogous to the Network Address Translation (NAT) function performed by a router.
An example would be what happens when an HTTP request is redirected from an unauthenticated client:
1. The gateway will change the destination address and port of the IP packets, so that they are directed to the Captive Portal with the port number used to signal the reason for redirection.
2. The Captive Portal will send an HTTP redirect to the client, so the client can request authentication from a web portal.
3. The web browser will receive pages from the web server to which it makes requests, and on the correct port, so all will be well.
If the gateway simply redirected to the web portal for authentication then two issues could arise:
1. The web portal would not respond to the request as the target of the HTTP request—domain name or IP address—wouldn't match any configured listener.
2. Even if the web portal had a promiscuous listener (ie: one that accepted requests from any domain), and did reply, the domain of the web portal would not match the domain of the original request; therefore, so cookie- based sessions would not work.
The Captive Portal is configured and extended through the use of request handlers and redirection parameters. The request handlers are parameterised by the redirection parameters for various responses to a redirection, such as the HTTP redirect example above. Additionally, new handlers may be written for specific redirect functions.
The Captive Portal uses the same Model, system services, and plugin implementations as the web portal applications, and can thus be extended through those mechanisms.
Integration with the RDP
The RADIUS Data Proxy (RDP) is built from the ERP framework. The ERP framework is designed for generic handing and despatching of requests for different protocol types. The RDP is an ERP framework specialization for RADIUS.
The basic function of the RDP is to receive a RADIUS request, determine is the request type, and call the appropriate handlers for the request (ie: SPE authorisation, proxy authentication, domain based accounting proxy). The basic functions of RADIUS are authentication, authorization, and accounting. RADIUS can also be used for configuration, provisioning, pre-paid billing, and additional services. It handles these complex issues using the RDP.
The means by which the RDP is extended is by implementation or extension of the handler interfaces or classes in the com.cisco.sesm,.rdp package and configuration to use the new extensions.
The RDP can be configured to split the authentication and authorization parts of the request, so the authentication request will go to the original RADIUS servers and the authorization query will go to the LDAP Directory. The RDP will combine the data from the authentication request and the authorization query to form a single response to the original query.
It is common that the workflow—subscriber provisioning, billing, etc.—associated with the existing RADIUS infrastructure is such that authentication must continue to flow through the existing RADIUS server. Introducing the Cisco gateways requires that additional VSAs be added to the Access Accept sent back to the gateway RADIUS client to activate services.
The RDP can also be configured to use a Merit format file for authentication and authorization. It is fully RFC-compliant.
Integration with the Web Services Gateway
Web Services denotes a collection of technologies focused on Simple Object Access Protocol (SOAP) and the Web Services Description Language (WSDL).
SOAP is a remote procedure call (RPC) technology. It encapsulates the RPC data in a request sent over HTTP. The procedures, or methods, that can be called, and data that can be exchanged, are described in WSDL. For SESM, this is the sesm.wsdl file in the wsg/wsdl directory of the SESM distribution.
WSDL declares a heterogeneous interface, which is language independent. To get a specific language binding for a given interface described in WSDL, the interface description file is compiled by a WSDL compiler to create server and client stubs in the specified target languages.
In SESM, the SESM Web Services Gateway implements these stubs to create an SOAP/HTTP server. For testing the wsgClient which provides a CLI for interacting with the SESM WSG by sending SOAP/HTTP requests.
The WSG enables session and service control and session status queries, and uses Web Services Security for access control for requestors of the interface.
The Web Services Gateway uses the same Model, system services, and plugin implementations as the web portal applications, so it can be extended through those mechanisms.
Summary of Integration Options
The SESM solution is built on the J2EE platform. If the deployment environment is J2EE compliant, the first point of integration can be the SESM components in an already existing application.
The next point of integration is to deploy the SESM applications within any J2EE servers or Java web servers already deployed. It is possible to add the SESM Servlets and libraries to an existing application's deployment descriptor, and to change the look and feel of the JSPs to merge them at the JSP level whilst leaving all else separate.
In either of the two cases above, it is possible to extend the system services with new implementations. This is also true of using the WSG, which is based on the same toolkit as the web portals, but with a SOAP interface instead of Servlets and JSPs. The WSG can also be used a standalone controller for the gateways.
The RDP be extended by adding new handlers, or configuring existing ones, to proxy to different solutions components.
Likewise, the Captive Portal can be extended with new handlers and configuration.
The SESM platform is easy to extend and integrate in a wide variety of different ways, as all SESM code is documented in the SESM SDK package, and many of the components that it uses are standard third party components, combined with the J2EE platform.
The SESM Platform uses the Jetty J2EE server for a ready to deploy solution. The Java platform means that Cisco SESM can be deployed on a wide variety of server platforms, including Solaris 7, 8 and 9, RedHat, SUSE Linux, Windows 2000 and Windows XP.
The Subscriber Policy Engine (SPE) will interoperate with LDAP directories and RDBMSs from a variety of vendors.
More SESM documentation can be found at
J2EE is specified at http://java.sun.com/j2ee/1 The Java programming language and all related terms are trademarks and copyright of Sun Microsystems. Sun created Java and are the guardians of the platform specifications.