[Contents] [Prev] [Next] [Index] [Report an Error] [No Frames]


XML Structure

The data that controls rendering is expressed in XML format in a sequence of nested tags. This code shows the tag hierarchy.

<controlledDeviceModels>
<controlledDeviceModel ...> 
    <capabilities> 
     ... 
    </capabilities>

    <serviceTemplates> 
    <serviceTemplate ...> 
        <mode ... > 
            <attributes>
            ...
            </attributes>

            <variables>
            ...
            </variables>

            </attributes> 
        </mode>
    </serviceTemplates>
</controlledDeviceModel>
</controlledDeviceModels>

capabilities and serviceTemplates are at the same level; so are attributes and variables.

Table 40 lists all the basic tags, their parameters, and a brief description.




Table 40: Main XML Elements
Element
Attributes
Description
Can I Create a New One?
controlledDeviceModel

id

model

vendor

dictionary

Highest level specification of the router.

Yes

capability

Activation Modification Bundle

Specifies access behavior, modification of existing service, and whether multiple CoAs can attach to one VSA.

No

serviceTemplate

name

Specifies the services available to your router. Router specific.

Yes

mode

attribute

variable

Subelement of serviceTemplate.

No

attribute

name

value

One of the following:

  • InitialAuthorization
  • Activation
  • Deactivation
  • AbortSession

Yes

variable

name

value

format

Controls rendering process behavior.

Yes

The following sections discuss each tag in order.

controlledDeviceModel

The controlledDeviceModel tag is the top node of the template. Specify the make and model of your router and its dictionary. Table 41 lists the controlledDeviceModel attributes.

Table 41: controlledDeviceModels Attributes
Attribute
Description

id

The name of the router

vendor

The brand of the router.

model

The model name of the router. The model name must match the one specified in the RADIUS User Interface. See Creating and Naming a Diameter or RADIUS Remote Network Element.

dictionary

An optional override of the default dictionary. The dictionary defines router-specific VSAs.

See Creating and Naming a Diameter or RADIUS Remote Network Element for setting the default dictionary.


Syntax

<controlledDeviceModel id="router_model" vendor="router_vendor" 
model="router_model" dictionary="dictionary_name"> 

capability

The capability tag specifies the activation behavior of services and how the router handles multiple requests. Table 42 lists the capability tags.

Table 42: capability Name and Value Pairs
Name
Value

Activation

"None" (default value) indicates that the router is not capable of activating services during initial authorization or activation.

"Access-Accept" indicates that the router supports activating services in RADIUS Access-Accept messages only.requests,

"CoA" indicates that the router supports activating services in CoA only.

"Both" enables both Access-Accept and CoA requests.

Modification

"false" -- (default value) this attribute must be set to false.

Bundle

This parameter indicates whether and how the router handles multiple service activations/deactivations in one CoA.

"None" (default value) indicates no bundling.

"Single" indicates the router to accept multiple requests.


Syntax

<capability name="Activation" value="string" /> 
<capability name="Modification" value="string" /> 
<capability name="Bundle" value="string" /> 

serviceTemplate

Use the serviceTemplate tag to specify any services that you want to enable for your router. What services are available vary from router to router, so it is important that you understand the properties of your router to successfully implement custom services.

The following elements are inside the serviceTemplate:

Modes

Service templates have as children groups of data, called modes, that each service must specify. Modes contain attributes and variables, which are explained in the next sections.

The modes are mandatory elements of a serviceTemplate. You must use the provided modes; you cannot create new modes.

The modes are as follows:

Attributes

All modes have attributes. Attributes define which RADIUS or Diameter attributes are generated as a result of rendering. All attributes create data that appears in the RADIUS attributes (such as VSAs) generated by the rendering process. It is important to understand that modes are the very core of the rendering process.

Modes can also have variables, which control the rendering process.

NOTE: The deviceModels.xml file contains examples of each of the service templates, their modes, and their modes' associated attributes and variables


Table 43 lists the attributes, explains their parameters, and describes their behavior.

Table 43: Attributes for All Modes  
Attribute
Description

requiredAttribute

In requiredAttribute, if the renderer finds the attribute in the downstream AAA server response, it copies the value into the RADIUS message for the router. Otherwise, the rendering fails. The IMS AAA server notifies the policy server of the failure.

<requiredAttribute name="string" copyFrom="string"/>

The name must match a defined RADIUS attribute in the downstream AAA server response.

Optionally, you can use copyFrom. If copyFrom is present, the renderer looks up the attribute specified by copyFrom in the downstream AAA Server response. In the absence of copyFrom, the renderer looks up the attribute specified by name.

For example,

<requiredAttribute name = "Acct-Session-Id"/>

overrideAttribute

In overrideAttribute, whether or not the renderer finds the attribute in the downstream AAA server response, it creates the attribute name with the specified value.

<overrideAttribute name="string" value="string" />

For example,

<overrideAttribute name = "Unisphere-Service-Timeout" value="5" />

defaultAttribute

In defaultAttribute, if renderer finds the attribute in the downstream AAA server response, it copies the value into the RADIUS message. Otherwise, it creates the attribute name with the specified value.

<defaultAttribute name="string" value="string" copyFrom="string"/>

For example,

<defaultAttribute name = "Unisphere-Service-Timeout" value="5" copyFrom="Session-Timeout"/>

Optionally, you can use copyFrom. If copyFrom is present, the renderer looks up the attribute specified by copyFrom in the downstream AAA Server response. In the absence of copyFrom, the renderer looks up the attribute specified by name.

attribute

In attribute, if the renderer finds the attribute in the downstream AAA server response, it copies the value into the RADIUS message for the router. Otherwise, no action occurs. Unlike requiredAttribute, the rendering does not fail in this case.

<attribute name="string" copyFrom="string"/>

For example,

<attribute name = "Unisphere-Service-Timeout" copyFrom="Session-Timeout"/>

Optionally, you can use copyFrom. If copyFrom is present, the renderer looks up the attribute specified by copyFrom in the downstream AAA Server response. In the absence of copyFrom, the renderer looks up the attribute specified by name.

parametrizedAttribute

parametrizedAttribute is the most powerful and flexible part of the template. It generates attribute values using a format specification, which makes it the most flexible of the attributes. Unlike the other attributes, Use this syntax to specify a name and format:

<parametrizedAttribute name="string" format =" $(p1) $(p2) ... $(pn) [$p(n+1)]"/>


format behaves much like sprintf in C; you can intersperse literal text in between parameter definitions. Unlike sprintf, format supports optional parameter definition. If the optional parameter is absent, it, and any literal text included in the square brackets, is ignored.
All parameters come from the SRC as input to rendering.

If you need to use restricted characters in your strings, use the backslash convention: \$, \', \", \[, \], \(, \).

Optionally, you can use copyFrom. If copyFrom is present, the renderer looks up the attribute specified by copyFrom in the downstream AAA Server response. In the absence of copyFrom, the renderer looks up the attribute specified by name.


Variables

Variables are subtags under modes. You can use them to render information that is not part of RADIUS attributes. They provide inner logic for the rendering process. Nothing defined by variables will appear in VSAs sent to the router.

Variables have three parameters, described in Table 44.

Table 44: Variables
Parameter
Description

name

The variable name

value

The value, usually an integer

format

The data type, "integer" or "string"


For example, to set up a CoA request for a custom service, use this code:

<variables> 
<variable name="RadiusCode" value="43" format="integer" /> 
<!-- 43 is CoA request 
</variables> 

This gives the renderer the RADIUS code to create a RADIUS CoA request. The value 43 comes from RFC 3576 (http://www.ietf.org/rfc/rfc3576.txt?number=3576). RadiusCode is the name of an internal variable the IMS AAA Server uses to format RADIUS messages.

A rule for processing variables: while rendering, when the IMS AAA encounters a variable with a new value, and that variable already has a different value, the rendering stops and sends the results to the policy server. It generates a RADIUS message and resumes rendering with the new value. Thus, it creates two VSAs, one each for the variable values. This correlates with the Bundle capability. See capability.

Overriding the Service Correlation ID

You can also use variables to override the serviceCorrelationId mode. For example,

variable name= "CreateServiceCorrelationId" value="0"

overrides serviceCorrelationId, so no identification number is created.

serviceTemplates (Global)

The global section is a unique serviceTemplate that specifies rendering used as part of any mode of any other service template. It is used to control rendering of service-independent requests, such as AbortSession. This template is unique in that its modes, attributes, and variables are available to all services that you define. It is therefore a mandatory part of any router XML definition file.

The global template is called in every possible scenario. You can use it to render a request to the policy server.

Table 45 lists the modes and attributes of the global section.

Table 45: serviceTemplate -- Global Section
Mode
Description

Authentication

Use Authentication mode for optional rendering of the request in the case of an initialAuthorization. Usually this mode is empty, since no additional rendering is required.

Unlike modes in the other serviceTemplates, this mode renders requests to the policy server and not to the router.

Accounting

Use Accounting mode to control the rendering of the accounting request sent to the policy server. Accounting is a post-authorization service, and it uses the ID numbers and names from the service activation rendering.

AbortSession

Use AbortSession mode for rendering of RADIUS disconnect request (DM) upon policy server abort session request.


For example,

<serviceTemplate description="global section"> 
<mode name="Authentication"> 
<attributes targetDictionary="diameter" /> 
</mode> 
<mode name="Accounting"> 
<attributes targetDictionary="diameter"> 
<attribute name="Juniper-Service-Correlation-Id" 
copyFrom="Unisphere-Service-Session" /> 
</attributes> 
</mode> 
<mode name="AbortSession"> 
<attributes> 
<requiredAttribute name="Acct-Session-Id" /> 
</attributes> 
<variables> 
<variable name="RadiusCode" value="40" format="integer" /> 
</variables> 
</mode> 
</serviceTemplate>

Some Provided Services

Juniper Networks provides some useful serviceTemplates:

Table 46 describes the modes associated with tiered services.

Table 46: Tiered Services
Service
Modes

content_provider_tiered

InitialAuthorization
Activation
Deactivation
ServiceCorrelationId
ServiceProfileDownload (Cisco only)

internet_tiered

InitialAuthorization
Activation
Deactivation
ServiceCorrelationId
ServiceProfileDownload (Cisco only)

guided_entrance

InitialAuthorization
Activation
Deactivation
ServiceCorrelationId
ServiceProfileDownload (Cisco only)


Tagged Attributes

Juniper Networks IMS AAA Server supports tagged attributes, which are an extension of the RADIUS protocol. Refer to RFC 2868 (http://www.ietf.org/rfc/rfc2868.txt?number=2868) for a description of this feature.

If you have Bundle="single" and want to send a single CoA activating two services, these activations requests must have the same RADIUS attributes, but with different values. To discriminate between attributes from two separate activation requests, you must use a unique tag for each. The tags provide a means of grouping attributes in the same RADIUS packet. For example,

<attributes> 
<requiredAttribute name="Acct-Session-Id" /> 
<overrideAttribute name="IncrementTag.function" value="" /> 
<parameterizedAttribute name="Unisphere-Activate-Service" 
format="internet_tiered\($(upstreamBandwidth),$(downstreamBandwidth)\)" 
/> 
<defaultAttribute name="Unisphere-Service-Stats" value="1" /> 

Two things to keep in mind:

You can place more than one tag function in a template mode. This generates two separate groups of tagged attributes. If the policy server activates two services, the fijnal CoA request contains the following attribures:

Unisphere-Activate-Service with tage value 1.
Unisphere-Service-Stats with tage value 1.
Unisphere-Activate-Service with tage value 2.
Unisphere-Service-Stats with tage value 2.

In normal operation, however, we recommend one group for each service activation request.

Caveat (Cisco Only)

Cisco Routers require an additional step to complete service activation. When the IMS AAA Server activates a service on a Cisco router, the router sends an extra Access-Request to the IMS AAA to retrieve the service profile. IMS AAA then sends back an Access-Accept response with VSAs representing the service profile. In response to the extra Access-Request, the IMS AAA Server has to send all VSAs generated by the previous rendering process. The router then activates the service. This means that the IMS AAA Server has to render the activation twice. In the second rendering a special mode, serviceProfileDownload is used.

This activation process is different from the usual scenario. Extra Access-Requests happen prior to the IMS AAA Server response to a policy server request. therefore, you can minimize the first rendering and place most of the work in the policy server download mode by doing the following:

See your Cisco documentation for more information.


[Contents] [Prev] [Next] [Index] [Report an Error] [No Frames]