Overview of Classification Scripts
The SAE uses classification scripts to determine whether it manages router interfaces, to select default policies, to find subscriber profiles, and to choose DHCP profiles. The SAE has three classification scripts:
- Interface classification script—When a subscriber's IP interface comes up on the router, the router sends the subscriber's login and interface information to the SAE. The SAE runs the interface classification script to determine whether the SAE manages the interface and if so, what default policies to send to the router.
- Subscriber classification script—If the SAE is managing the interface, the SAE uses the login and interface information that the router sends to run the subscriber classification script to determine which subscriber profile to load into memory.
- DHCP classification script—For DHCP subscribers, the SAE runs DHCP classification scripts to choose DHCP profiles.
How Classification Scripts Work
Classification scripts are organized into rules. Each rule has a target and one or more match conditions.
- A target is the result of the classification script. For example, the result of subscriber classification scripts is an LDAP search string that is used to find a unique subscriber profile. The result of interface classification scripts is a policy group.
- Conditions are match criteria. The script attempts to match conditions in the script with information sent from the router. For example, match conditions for a subscriber classification script might be login type or domain name. Match conditions for an interface classification script could be interface IP address or interface description.
Each script can have multiple targets, and each target can have multiple conditions. When an object needs classification, the script processes the targets in turn. Within each target, the script processes conditions sequentially. When it finds that the classification conditions for a target match, it returns the target to the SAE. If the script does not find any targets that can be matched, the classifier engine returns a no-match message to the SAE.
Because classification scripts examine conditions sequentially as the conditions appear in the script, you should put more specific conditions at the beginning of the script and less specific conditions at the end of the script.
Interface Classification Scripts
When a subscriber's IP interface comes up on the router, the router sends the subscriber's login and interface information to the SAE. For example, the router might send the following information:
IP address=0.0.0.0Virtual router name=default@erx5_ssp58Interface name=FastEthernet3/1.1PPP login name (PPP)=pebbles@virneo.netUser IP address (PPP)=192.168.55.5Interface speed=100000000Interface description=P3/1.1Interface alias=1st pppoe intRADIUS class=nullThe SAE invokes the interface classification script and provides to the script the information that it received from the router. The script engine matches the information sent from the router to the conditions in the interface classification script. The script examines each condition in sequential order to find a match.
- If it finds a match, the script processing stops, and the target for that condition is returned to the SAE. The target is the path of a policy group. This policy group is the default policy. The SAE installs the policy on the interface and begins managing the interface.
- If it does not find a match, the script sends a no-match message to the SAE. The SAE does not manage the interface; that is, the policies installed through RADIUS or the CLI remain in effect. The SAE does not install policies.
Subscriber Classification Scripts
When the SAE begins managing an interface, it determines whether a subscriber is associated with the interface by running the subscriber classification script. The SAE also runs the subscriber classification script when certain login events occur. See SRC-PE Subscribers and Subscriptions Guide, Chapter 3, Subscriber Logins and Service Activation for a description of login event types.
To find the matching subscriber profile, the SAE uses interface information that it received from the router when the interface became operational (for example, virtual router name, interface name, interface alias). It also uses login information that it received from the router or the portal application when the subscriber attempted to log in (for example, subscriber IP address, login name, or login event type).
When the SAE runs the subscriber classification script, the script engine matches the information sent from the router to the conditions in the subscriber classification script. The script examines each condition in sequential order to find a match.
- If it finds a match, the script processing stops, and the target for the matching condition is returned to the SAE. The target is an LDAP query that uniquely identifies a subscriber profile. The SAE loads the subscriber entry and uses the entry to create a subscriber session in memory.
- If it does not find a match, the script sends a no-match message to the SAE. The SAE does not load a subscriber session onto the interface, and services cannot be activated for this session.
DHCP Classification Scripts
- DHCP classification scripts choose DHCP profiles. See SRC-PE Subscribers and Subscriptions Guide, Chapter 8, Overview of Plug-Ins Included with the SAE for information about how DHCP classification scripts are used.
Classification Targets
A target is the result of the classification script that gets returned to the SAE. There are two special types of targets:
- No-match targets—Targets that begin with a - (single dash) are interpreted as no match. If the conditions of this target are matched, a no-match message is returned to SAE. You can use this type of target to exclude certain patterns or to shortcut known nonmatches. To speed up processing, use this target to specify interfaces that you do not want the SAE to manage.
- Script targets—The content of the script rule is interpreted when the classifier is initially loaded. The script rule can contain definitions of custom functions, which can be called during the matching process. Because you can insert arbitrary code into a script, you can use classification scripts to perform arbitrary tasks.
Because script targets use * (asterisks), you cannot use * in other types of targets.
Target Expressions
A target can contain expressions. These expressions can refer to an object in the SAE's memory or configuration, to specific matching conditions, or to another function or script.
Suppose the classification object in a subscriber classifier contains a field called userName. The classifier target uniqueId=<- userName -> is expanded to contain the actual content of the userName field before it is returned to the SAE; for example, for userName=juser, uniqueId=juser is returned.
Target expressions are enclosed in angle brackets and hyphens; for example, <-retailerDn->. The classifier expands expressions before it returns the target to the SAE. The expression is interpreted by an embedded Python interpreter and can contain variables and Python operations. In the simplest case an expression can be a single variable that is replaced with its current contents. Available variable names are all fields of the object passed to the classifier and names created with regular expression matching.
Because a scripting interpreter interprets expressions, more complex operations are possible. Examples are:
- Indexing—var[index] returns the element index of a sequence. The first element is at index 0.
- Slicing—var[start : end] creates a substring of the variable var starting at index startup to, but not including, index end; for example, var=Hello, var[2:4] = ll
Classification Conditions
You can configure multiple classification conditions for a rule. For example:
rule rule-2 {target /ent/EntDefault;condition {"pppLoginName=\"\"";"&interfaceName!=\"fastEthernet0*\"";"&interfaceName!=\"null*\"";"&interfaceName!=\"loopback*\"";If you prefix a condition with an & (ampersand) character, the condition is examined only if the previous condition matches.
If you prefix a condition with a | (pipe) character, the condition is examined only if the previous conditions have not produced a positive match.
You can use glob or regular expression matching to configure each target's conditions.
Glob Matching
field = matchorfield != matchwhere match is a pattern similar to UNIX filename matching. Glob matches are case insensitive. "field != match" is true, if field=match is not true.
- *—Matches any substring.
- ?—Matches any single character.
- [range]—Matches a single character in the specified range. Ranges can have the form a-z or abcd.
- [!range]—Matches a single character outside the specified range.
- C—Matches the single character c.
The available field names are described for the specific classifiers. Examples are:
- interfaceName = fastEthernet3/0 # matches the string "fastEthernet3/0" directly.
- interfaceName = fast*3/1 # matches any string that starts with "fast" and ends with "3/1"
- interfaceName = fast*3/1.* # starts with "fast", contains "3/1." arbitrary ending
- interfaceName = fast*3/[2-57] # starts with "fast", contains "3/" followed by 2,3,4,5 or 7
Regular Expression Matching
Regular expression matches are of the form:
field =~ reorfield !~ rewhere field !~ re is true if field =~ re is not true. The regular expression is re. For a complete description of the syntax, see: http://www.python.org/doc/2.0/lib/re-syntax.html
You can group regular expressions with pairs of parentheses. If such an expression matches, the contents of the groups are made available for target expressions. Group number n is available as G[n], where n is the number of the opening parenthesis of the group. You can also name groups by using the special notation (?P<name>...).
ifAlias =~ "SSP(.*) "# match a string starting with "SSP". The remainder is stored # in the variable "G[1]"ifAlias =~ (?P<dn>name=(?P<name>[^,]*).*) # match a string starting with "name=". The whole match is # stored in the variable "dn". A submatch which does not # contain any ","-characters and starts after "name=" # is stored in variable "name"