-
null
The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter describes the objects you use to configure and operate your Cisco Access Registrar RADIUS server.
Cisco AR is configured and operated through a set of objects. These objects are arranged in a hierarchy, with some of the objects containing subobjects; just as in a UNIX file system, in which directories can contain subdirectories. All of the objects, except those that are merely lists, contain properties that define the attributes or behavior of the object.
This chapter describes the following Cisco AR objects:
•Radius— root of the configuration hierarchy
•UserLists—contains individual UserLists, which in turn contain users
•UserGroups—contains individual UserGroups
•Policies—contains individual Policies
•Clients—contains individual Clients
•Vendors—contains individual Vendors
•Scripts—contains individual Scripts
•Services—contains individual Services
•Session Managers—contains individual Session Managers
•Resource Managers—contains individual Resource Managers
•Profiles—contains individual Profiles
•Rules—contains individual Rules
•Translations—contains individual Translations
•TranslationGroups—contains individual Translation Groups
•Remote Servers—contains individual RemoteServers
•Advanced—contains advanced properties, Ports, Interfaces, Reply Messages, and the Attribute dictionary
The Radius object is the root of the hierarchy. For each installation of the Cisco AR server, there is one instance of the Radius object. You reach all other objects in the hierarchy from the Radius. The following is a listing of the RADIUS server object:
[ //localhost/Radius ]
Name = Radius
Description =
Version = 1.7R0
IncomingScript~ =
OutgoingScript~ =
DefaultAuthenticationService~ = local-users
DefaultAuthorizationService~ = local-users
DefaultAccountingService~ = local-file
DefaultSessionService~ =
DefaultSessionManager~ = session-mgr-1
UserLists/
UserGroups/
Policies/
Clients/
Vendors/
Scripts/
Services/
SessionManagers/
ResourceManagers/
Profiles/
Rules/
Translations/
TranslationGroups/
RemoteServers/
Advanced/
Replication/
Table 4-1 lists the Radius properties. You you can set or change Radius properties using the Cisco AR aregcmd commands.
Note When a field is listed as required, it means a value must be supplied; that is, the value must be set. You can use the default (if it is supplied) or you can change it to something else, but you cannot unset it. You must supply values for the required fields and for which no defaults exist.
.
The remaining Cisco AR objects are subobjects of the Radius object.
The UserLists object contains all of the individual UserLists, which in turn, contain the specific users stored within Cisco AR. Cisco AR references each specific UserList by name from a Service whose type is set to local. When Cisco AR receives a request, it directs it to a Service. When the Service has its type property set to local, the Service looks up the user's entry in the specific UserList and authenticates and/or authorizes the user against that entry.
Note User names might not include the forward slash (/) character. If the Cisco AR server receives an access request packet with a User-Name attribute containing a forward slash character and the Cisco AR server uses an internal UserList to look up users, the server produces an error (AX_EINVAL) and might fail. If user names require a forward slash, use a script to translate the slash to an acceptable, unused character.
You can have more than one UserList in the UserLists object. Therefore, use the UserLists object to divide your user community by organization. For example, you might have separate UserLists objects for Company A and B, or you might have separate UserLists objects for different departments within a company.
Using separate UserLists objects allows you to have the same name in different lists. For example, if your company has three people named Bob
and they work in different departments, you could create a UserList for each department, and each Bob could use his own name. Using UserLists lets you avoid the problem of Bob1
, Bob2
, and so on.
If you have more than one UserList, you can have a script Cisco AR can run in response to requests. The script chooses the Service, and the Service specifies the actual UserList which contains the user. The alternative is dynamic properties.
The subobjects are the Users listed by name. Table 4-2 lists the UserLists object properties.
|
|
---|---|
Name |
Required; must be unique in UserLists. |
Description |
Optional description of the UserList. |
The Users object contains all of the information necessary to authenticate a user or authorize a user. Users in local UserLists can have multiple profiles. Table 4-3 lists the Users object properties.
The HiddenAttributes property in the user object provides a concatenation of all user-level reply attributes. The Cisco AR server uses the HiddenAttributes property to construct and populate a virtual attributes directory.
The HiddenAttributes property is, in fact, hidden. It is not displayed and cannot be set or modified using aregcmd, but when an administrator issues a save, all values from the user's Attributes directory go into the HiddenAttributes property and the persistent storage.
The attributes are added in a replace-if-present-add-if-not manner as used in the UserGroup-Base-Profile and User-Base-Profile. The order of application of the attributes is as follows:
•UserGroup Base Profile
•UserGroup Attributes
•User Base Profile
•User Attributes
The UserGroups objects allow you to maintain common authentication and authorization attributes in one location, and then have many users reference them. By having a central location for attributes, you can make modifications in one place instead of having to make individual changes throughout your user community.
For example, you can use several UserGroups to separate users by the services they use, such as a group specifying PPP and another for Telnet.
Table 4-4 lists the UserGroups properties.
A Policy is a set of rules applied to an Access-Request. If you are using Policies, the first one that must be created is SelectPolicy.
Table 4-5 lists the properties required for a given Policy.
|
|
---|---|
Name |
Required; must be unique in the Policies list |
Description |
Optional description of the Policy |
Grouping |
Optional grouping of rules |
All NASs and proxy clients that communicate directly with Cisco AR must have an entry in the Clients list. This is required because NAS and proxy clients share a secret with the RADIUS server which is used to encrypt passwords and to sign responses. Table 4-6 lists the Client object properties.
The Vendor object provides a central location for specifying all of the request and response processing a particular NAS or Proxy vendor requires. Depending on the vendor, it might be necessary to map attributes in the request from one set to another, or to filter out certain attributes before sending the response to the client. For more information about standard RADIUS attributes, see Appendix C, "RADIUS Attributes."
Note When you have also set /Radius/IncomingScript, Cisco AR runs that script before the vendor's script. Conversely, when you have set a /Radius/Outgoing script, Cisco AR runs the vendor's script before that script.
Table 4-7 lists the Vendor object properties.
The Script objects define the function Cisco AR invokes whenever the Script is referenced by name from other objects in the configuration.
You can write three types of scripts:
•REX (RADIUS EXtension) scripts are written in C or C++, and thus are compiled functions that reside in shared libraries
•Tcl scripts are written in Tcl, and are interpreted functions defined in source files.
•Java scripts
Note For more information about how to write scripts and how to incorporate them into Cisco AR, see Chapter 9, "Using Extension Points."
Table 4-8 lists the Script object properties.
The InitEntryPoint properties allow you to perform initialization before processing and then cleanup before stopping the server. For example, when Cisco AR unloads the script (when it stops the RADIUS server) it calls the InitEntryPoint again to allow it to perform any clean-up operations as a result of its initialization. One use of the function might be to allow the script to close an open Accounting log file before stopping the RADIUS server.
Note When you use a Cisco AR file service, Cisco AR automatically closes any opened files. However, if you write scripts that manipulate files, you are responsible for closing them.
Note If you have more than one extension point script (defined under /Radius/Scripts) using the same Java class, only one instance of the class is created and used for all the extension point scripts.
Cisco AR supports authentication, authorization, and accounting (AAA) services. In addition to the variety of built-in AAA services (specified in the Type property), Cisco AR also enables you to add new AAA services through custom shared libraries.
Table 4-9 lists the common Services properties. There are additional properties depending on the type of service.
Note OutagePolicy also applies to Accounting-Requests. If an Accounting-Request is directed to an unavailable Service, then the values in Table 4-10 apply.
This section lists the types of services available in Cisco AR 4.1 with their required and optional properties. The service you specify determines what additional information you must provide.
The Domain Authentication service type, domain-auth, is used with a Remote Server of the same type to provide support for authentication against Windows Domain Controller/Active Directory (WDC/AD). The following example lists the default configuration for a domain-auth service which are all common service properties described in Table 4-9:
[ //localhost/Radius/Services/wdc ]
Name = wdc
Description =
Type = domain-auth
IncomingScript~ =
OutgoingScript~ =
OutagePolicy~ = RejectAll
OutageScript~ =
MultipleServersPolicy = Failover
RemoteServers/
Cisco AR supports Extensible Authentication Protocol (EAP) and Protected EAP (PEAP) to provide a common protocol for differing authentication mechanisms. EAP enables the dynamic selection of the authentication mechanism at authentication time based on information transmitted in the Access-Request. Cisco AR provides the following EAP services:
•EAP-FAST
•EAP-GTC
•EAP-LEAP
•EAP-MD5
•EAP-MSChapV2
•EAP-Negotiate
•EAP-SIM
•EAP-Transport Level Security (TLS)
•EAP-Tunneled TLS (TTLS)
•PEAP Version 0 (Microsoft PEAP)
•PEAP Version 1 (Cisco PEAP)
Refer to Chapter 8, "Extensible Authentication Protocols," for detailed information about properties used in EAP-type services.
Specify the file service when you want Cisco AR's RADIUS Server to perform local accounting using a specific file. Every file Service in your configuration will cause a file with the configured name to be created when the server is started, even if the service is not being invoked by any request packets. Table 4-11 lists the properties used for a file service.
Cisco AR opens the file when it starts the RADIUS server and closes the file when you stop the server. You can depend on Cisco AR flushes the accounting record to disk before it acknowledges the request.
Based on the maximum file size and age you have specified, Cisco AR closes the accounting file, moves it to a new name, and reopens the file as a new file. The name Cisco AR gives this accounting file depends on its creation and modification dates.
•If the file was created and modified on the same date, the file name is
FileNamePrefix-<yyyymmdd>-<n>.log. The date is displayed as year, month, day, number.
•If the file was created on one day and modified on another, the file name is FileNamePrefix-<yyyymmdd>-<yyyymmdd>-<n>.log. The dates are creation, modification, and number.
A group service contains a list of references to other services and specifies whether the responses from each of the services should be handled as a logical AND or a logical OR function. You specify AND or OR in the Result-Rule attribute of Group Services. The default value is AND.
Table 4-12 lists the properties used to configure a group service.
If Result-Rule is set to AND, the response from the Group Service is positive if each of the services referenced return a positive result. The response is negative if any of the services reference return a negative result. If Result-Rule is set to OR, the response from the Group Service is positive if any of the services referenced return a positive result. The response is negative if all the referenced services return a negative result.
When the Result-Rule attribute is set to AND or OR, each referenced service is accessed sequentially, and the Group Service waits for a response from the first referenced service before moving on to the next service (if necessary). If a service takes a long time to respond, that causes a delay in sending the request to the next referenced server.
The ResultRule settings parallel-and and parallel-or are similar to the AND and OR settings except that they ask each referenced service to process the request simultaneously instead of asking each referenced server sequentially, thereby saving processing time.
A parallel-and setting might respond with its own reply as soon as it receives a negative response, but otherwise must wait for all responses before it can respond with a positive reply. Likewise, a parallel-or might respond as soon as it receives a positive response, but otherwise must wait for all responses before it can reply with a negative response.
If a service referenced from a Group Service is of type RADIUS and if Accounting-Requests are being processed by the Group Service, setting the AckAccounting property in the remote server will affect the behavior of the parallel-or Group Service. This is because if AckAccounting is set to FALSE, the RADIUS Remote Server will not wait for the response from the remote server but returns a response immediately. Since the Group Service is set to parallel-or, once it receives the response from the RADIUS service, it is free to send a response itself. This will have the effect that a response is sent very quickly from the Group Service acknowledging the Accounting-Request and responses from the other referenced services are handled as the arrive.
Note that since AckAccounting was set to FALSE, there is no guarantee that the Remote Server successfully processed the request. Since it is a RADIUS Remote Server, the Cisco AR server attempts for MaxTries to send the request to the server and to get back an acknowledgement, but if that fails, there will be no indication to the client about that event. The acknowledgement to the client has been sent long before.
Specify the java service type when you want to create a custom service and use a script for authentication, authorization, or accounting. Table 4-13 lists the properties required to configure a java service.
A java service uses an extension point script to provide the service's functionality and handles both RADIUS and TACACS requests for authentication, authorization, and accounting.
Specify the ldap service type when you want to use a particular LDAP remote server for authentication and/or authorization. Table 4-14 lists the properties used to configure an LDAP service.
When using LDAP for authentication and a local database for authorization, ensure that the usernames in both locations are identical with regard to case sensitivity.
\
Specify local when you want the Cisco AR server to perform the authentication and authorization using a specific UserList. For more information, see the "UserLists" section. Table 4-15 lists the properties used to configure a local service.
Specify odbc when you want to use an ODBC service for authentication, authorization and accounting through an ODBC data store. Use an ODBC service to authenticate and authorize an access requests by querying user information through ODBC and to insert accounting records into a data store through ODBC. Table 4-16 lists the properties used to configure an ODBC service.
\
Specify the radius service type when you want to use a particular RADIUS remote server for authentication and authorization. Table 4-17 lists the properties used to configure a RADIUS service.
Cisco AR 4.1 supports a new service type called radius-query that can be used to query cached data through Radius packets. This radius-query service contains a list of session managers to be queried from and a list of (cached) attributes to be returned in the Access-Accept packet in response to a Radius Query request. Cisco AR 4.1 also supports caching and querying of multi-valued attributes.
The Radius Query service should be selected through an extension point script or through the Rule and Policy Engine by setting it to a new environment variable named Query-Service. The reason for this is that the Radius Query request comes in as an Access-Request and the server has no way of knowing whether it is a Radius Query request or normal authentication request. Setting the Query-Service environment variable tells the Cisco AR server that the request is a Radius Query request so the Cisco AR server can process the request with the radius-query service set in the Query-Service environment variable.
When a Radius Query service is selected to process an Access-Request, it queries the configured list of Session Managers for a matching record using the QueryKey value configured in the session-cache Resource Manager referenced under these Session Managers as key. If a matching record is found, an Access-Accept containing a list of cached attributes present (based on the configuration) in the matched record is sent back to the client. If the session cache contains a multi-valued attribute, all values of that attribute are returned in the response as a multi-valued attribute. If there is no matching record, an Access-Reject packet is sent to the client.
Cisco AR 4.1 introduces scripting points at the Session Manager level along with automated programmable interfaces (APIs) to access cached information present in the session record. You can use these scripting points and APIs to write extension point scrips to modify the cached information.
The following example shows the default configuration of a radius-query service:
[ //localhost/Radius/Services/radius-query ]
Name = radius-query
Description =
Type = radius-query
IncomingScript~ =
OutgoingScript~ =
SessionManagersToBeQueried/
AttributesToBeReturned/
Table 4-18 lists the properties used to configure a Radius Query service.
When an Access-Request packet is received by the Cisco AR server, the session-cache Resource Manager caches the configured attributes in the session with the configured QueryKey as the key to the cached data. In the TAL solution, the QueryKey will usually be Framed-IP-Address. If an Accounting-Requestor Accounting-Start packet is received for the same session, the cached data is updated if necessary. If there is a multi-valued attribute in the Access-Request packet or Accounting-Request packet, the Cisco AR server caches all the values of that attributes.
In TAL, when the SSG receives an IP packet originating from a user unknown to the SSG, it sends an Access-Request packet to the Cisco AR server in which the User-Name and Framed-IP-Address attributes both contain the user's source IP address, and the Service-Type is set to Outbound, among other attributes. These attributes and their values distinguish Radius Query requests from normal authentication requests in TAL.
Note In solutions other than TAL, the criterion that distinguishes Radius Query requests from normal authentication requests might be different.
A new environment variable, Query-Service, can be set to the name of a radius-query service, in an extension point script, or through the Rule and Policy engine so the Cisco AR server knows the current request is a Radius Query request and processes it with the radius-query service value set in the Query-Service environment variable.
Cisco AR 4.1 provides several new API calls you can use to get, put, and delete the cached attributes present in the session record. The entry point function changes slightly to take a fifth argument which is a pointer to a structure containing the new API calls:
typedef int (REXAPI * RexEntryPointFunction)
(
int iScriptingPoint,
rex_AttributeDictionary_t* pRequest,
rex_AttributeDictionary_t* pResponse,
rex_EnvironmentDictionary_t* pRadius,
rex_SessionRecord_t* pSession
);
However, you can continue to write extension point scripts with four arguments as well, for example without the pSession argument.
The following are API calls and their functionality. All these API calls fail gracefully when they are invoked from any scripting point other than the Session Manager scripting points.
const char* get
const char* get(
rex_SessionRecord_t* pSession,
const char* pszAttribute,
int <iIndex>,
abool_t* <pbMore>
)
This API returns the value of the <iIndex>'d instance of the attribute cached in the session, represented as a string. When the session does not contain the attribute, an empty string is returned. When <pbMore> is non-zero, this method sets <pbMore> to TRUE when more instances of the same attribute exist after the one returned and to FALSE otherwise. This can be used to determine whether another call to get() method should be made to retrieve other instances of the same attribute.
abool_t put
abool_t put(
rex_SessionRecord_t* pSession,
const char* pszAttribute,
const char* <pszValue>,
int <iIndex>
)
When <iIndex> equals the special value REX_REPLACE, this method replaces any existing instances of <pszAttribute> with a single value in the session. When <iIndex> equals the special value REX_APPEND, it appends a new instance of <pszAttribute> to the end of the list of existing instances of <pszAttribute>. When <iIndex> equals the special value REX_AUGMENT, this method only puts <pszAttribute> when it does not already exist. Otherwise, a new instance of <pszAttribute> is inserted/replaced at the position indicated. This method returns TRUE if it is able to cache the attribute successfully and FALSE otherwise.
abool_t remove
abool_t remove(
rex_SessionRecord_t* pSession,
const char* pszAttribute,
int <iIndex>
)
This method removes the <pszAttribute> from the session. When <iIndex> equals the special value REX_REMOVE_ALL, this method removes any existing instances of <pszAttribute>. Otherwise, it removes the instance of <pszAttribute> at the position indicated. It returns FALSE when <pszAttribute> is not present at any index in the session record and returns TRUE otherwise.
rex_SessionInfo_t*
rex_SessionInfo_t* getSessionInfo(rex_SessionRecord_t* pSession )
This method returns the pointer to a structure that contains the other session-related information, like Session Id, Session Start time, Session Last Accessed Time, present in the session record. The structure that holds this information will appear as follows:
typedef struct rex_SessionInfo_s
{
auint32_t iSessionId;
auint32_t tSessionStartTime;
auint32_t tSessionLastAccessedTime;
} rex_SessionInfo_t;
To use the extension point scripts written in Tcl, define the procedure at the session manager level as shown below:
proc test { request response environ session } {
}
There is a fourth argument session that needs to be passed to the Tcl procedure and the API calls that are intended to operate on the session record need to use this session dictionary.
API calls in Tcl have the same meaning with same number arguments and return values as described in Rex. The only difference is that the API getSessionInfo will not return a structure as in Rex but it will return the info as a string, as in the following example:
Session-ID=1, Session-Start-Time=1102099334, Session-Last-Accessed-Time=1102099334
There are two new interfaces ExtensionForSession and ExtensionForSessionWithInitialization and the customers whishing to use the extension point scripts written in Java at the session manager level needs to implement one of these interfaces.
The runExtension method of these interfaces will look as below:
public int runExtension
( int iExtensionPoint,
AttributeDictionary request,
AttributeDictionary response,
EnvironmentDictionary environment,
SessionRecord session
);
API calls that are intended to operate on session record needs to use this `session' dictionary.
API calls in Java have the same meaning with same number arguments and return values as described in Rex. The only difference is that the API getSessionInfo will not return a structure as in Rex but it will return the info as a string. For example:
Session-ID=1, Session-Start-Time=1102099334, Session-Last-Accessed-Time=1102099334
Existing scripts written in any of these three languages will not be affected with the introduction of the new `session dictionary' argument. And the customers can use a script with any number of arguments (i.e with or without the last `session dictionary' argument) at any extension point script. If there is no session to operate on, for example when the customer is trying to use session dictionary argument at an extension point other than session manager's, the Cisco AR gracefully returns an error logging the appropriate message.
The simple replace or add if it does not exist model can still be used for simple modifications as before without the need to write a script. If the cached attributes are updated in the IncomingScript and if customers do not want them to be touched or updated again when the processing reaches session-cache resource manager, they can set the OverwriteAttributes property of the session-cache resource manager to FALSE so that the session-cache resource manager will not operate on this packet.
Specify the rex service type when you want to create a custom service and use a script for authentication, authorization, or accounting. Table 4-19 lists the properties required to configure a rex service.
For more information about scripting, see Chapter 9, "Using Extension Points." For more information about using the REX Attribute dictionary, see Appendix A, "Cisco Access Registrar Tcl and REX Dictionaries."
You can use Session Managers to track user sessions. The Session Managers monitor the flow of requests from each NAS and detect the session state. When requests come through to the Session Manager, it creates sessions, allocates resources from appropriate Resource Managers, and frees and deletes sessions when users log out.
The Session Manager enables you to allocate dynamic resources to users for the lifetime of their session. You can define one or more Session Managers and have each one manage the sessions for a particular group or company.
Note Session record size is limited by the operating system (OS) paging size (8 KB in Solaris and 4 KB in Linux). If a request triggers creation of a session that exceeds the OS paging size, the request will be dropped and the session will not be created.
Note If the disk partition where Cisco AR stores session backing store data (usually the disk partition where Cisco AR is installed, such as /opt/CSCOar) is full, the subsequent packets that try to create sessions will be dropped and no sessions will be created due to lack of disk space.
Session Managers use Resource Managers, which in turn, manage a pool of resources of a particular type. Table 4-20 lists the Session Manager properties.
Cisco AR 4.1 adds the IncomingScript and OutGoingScript properties. The IncomingScript is run as soon as the session is acquired. The OutGoingScript is run just before the session is written to backing store.
You can manage sessions with the two aregcmd session management commands: query-sessions and release-sessions. For more information about these two commands, see the "query-sessions" section on page 2-8 and the "release-sessions" section on page 2-8.
Cisco AR Sessions can be created by two types of RADIUS packets:
•Access-Requests
•Accounting-Requests with an Acct-Status-Type attribute with a value of Start.
This allows Cisco AR to monitor Sessions even when it is not allocating resources. For example, when Cisco AR is being used as an "Accounting-Only" server (only receiving Accounting requests), it can create a Session for each Accounting "Start" packet it successfully processes. The corresponding Accounting "Stop" request will clean up the Session. Note, if a Session already exists for that NAS/NAS-Port/User (created by an Access-Request), Cisco AR will not create a new one.
When you do not want Cisco AR to create Sessions for Accounting "Start" requests, simply set the AllowAccountingStartToCreateSession property on the SessionManager to FALSE.
Session Notes are named text messages attached to a Session and are stored with the Session data, including resources allocated for a specific user session. This data, including Session Notes, can be retrieved and viewed using the aregcmd command query-sessions.
--> query-sessions /Radius/SessionManagers/session-mgr-2
sessions for /Radius/SessionManagers/session-mgr-2:
S257 NAS: localhost, NAS-Port:1, User-Name: user1, Time: 00:00:08,
IPX 0x1, GSL 1, USL 1, NOTES: "Date" "Today is 12/14/98.", "Requested
IP Address" "1.2.3.4", "Framed-IP-Address" "11.21.31.4"
Session Notes can be created by Scripts using the Environment dictionary passed into each or by the Cisco AR server. When more than one Session Note is added, the Session-Notes entry should be a comma-separated list of entry names.
For a TCL script:
Step 1 The Script should create an Environment dictionary entry using the Session Note name as the entry name, and the Session Note text as the entry value. For example:
$environ put "Date" "Today is 12/15/98"
$environ put "Request IP Address" "1.2.3.4"
Step 2 The Script should create or set an Environment dictionary entry with the name Session-Notes with a value that contains the name of the entries created. For example:
$environ put "Session-Notes" "Date, Requested_IP_Address"
For a REX script:
Step 1 The Script should create an Environment dictionary entry using the Session Note name as the entry name, and the Session Note text as the entry value. For example:
pEnviron-->put(pEnviron, Date, "Today is 12/15/98.");
pEnviron-->put(pEnviron, Request_IP_Address, "1.2.3.4");
Step 2 The Script should create/set an Environment dictionary entry with the name Session-Notes with a value that contains the name of the first entry created. For example:
pEnviron-->put(pEnviron, "Session-Notes", "Date, Requested_IP_Address");
Note Scripts creating Session Notes must be executed before the Session Management step takes place while processing a packet.
Cisco AR will automatically create a Session Note if a packet is passed to a SessionManager and it already contains a Framed-IP-Address attribute in the packet's Response dictionary. This IP address could come from a Profile, RemoteServer response, or from a previously executed script. For example, a Session output containing Session Notes when using the aregcmd command query-session would be as follows:
sessions for /Radius/SessionManagers/session-mgr-2:
S257 NAS: localhost, NAS-Port:1, User-Name: user1, Time: 00:00:08, IPX 0x1, GSL 1, USL 1, NOTES: "Date" "Today is 12/14/98.", "Requested IP Address" "1.2.3.4", "Framed-IP-Address" "11.21.31.4"
Session Notes are also copied into the Environment dictionary after Session Management. The Session-Notes Environment dictionary entry will contain the names of all the Environment dictionary entries containing Session Notes.
Two new environment variables, Group-Session-Limit and Current-Group-Count (see rex.h), are set if the group session limit resource is allocated for a packet. These variables allow a script to see how close the group is to its session limit; one way to use this information is to implement a script-based soft limit. For example, you could use the Class attribute to mark sessions that have exceeded a soft limit of 80% -- as hard coded in the script (in a Tcl script called from /Radius/OutgoingScript):
set softlimit [ expr 0.8 * [ $environ get Group-Session-Limit ] ]
if { [ $environ get Current-Group-Count ] < $softlimit } {
$response put Class 0
} else {
$response put Class 1
}
Note The soft limit itself is hard coded in the script; soft limits are not directly supported in the server. The action to be taken when the soft limit is exceeded (for example, Class = 1, and then the accounting software branches on the value of Class) is also the responsibility of the script and/or external software.
All the session objects are maintained in one dictionary keyed by a string. You can define the keying material to the session dictionary through a newly introduced environment variable, Session-Key.
If the Session-Key is presented at the time of session manager process, it will be used as the key to the session object for this session. The Session-Key is of type string. By default, the Session-Key is not set. Its value should come from attributes in the incoming packet and is typically set by scripts. For example, CLID can be used to set the value of Session-Key.
Use the function UseCLIDAsSessionKey as defined in the script rexscript.c to specify that the Calling-Station-Id attribute that should be used as the session key to correlate requests for the same session. This is a typical case for 3G mobile user session correlation. You can provide your own script to define other attributes as the session key.
In the absence of the Session-Key variable, the key to the session will be created based on the string concatenated by the value of the NAS-Identifier and the NAS-Port.
There is a new option with-key available in aregcmd for query-sessions and release-sessions to access sessions by Session-Key.
Resource Managers allow you to allocate dynamic resources to user sessions. The following lists the different types of Resource Managers.
•IP-Dynamic—manages a pool of IP addresses that allows you to dynamically allocate IP addresses from a pool of addresses
•IP-Per-NAS-Port—allows you to associate ports to specific IP addresses, and thus ensure each NAS port always gets the same IP address
•IPX-Dynamic—manages a pool of IPX network addresses
•Subnet-Dynamic—manages a pool of subnet addresses
•Group-Session-Limit—manages concurrent sessions for a group of users; that is, it keeps track of how many sessions are active and denies new sessions once the configured limit has been reached
•User-Session-Limit—manages per-user concurrent sessions; that is, it keeps track of how many sessions each user has and denies the user a new session once the configured limit has been reached
•Home-Agent—manages a pool of on-demand IP addresses
•USR-VPN—manages Virtual Private Networks (VPNs) that use USR NAS Clients.
Each Resource Manager is responsible for examining the request and deciding whether to allocate a resource for the user, do nothing, or cause Cisco AR to reject the request.
Table 4-21 lists the Resource Manager properties.
A number of different types of Resource Managers exist that allow you to manage IP addresses dynamically or statically, limit sessions on a per group or per user basis, or manage a Virtual Private Network. See Appendix A, "Cisco Access Registrar Tcl and REX Dictionaries," for information on how to override these individual Resource Managers.
The Gateway subobject includes a list of names of the Frame Relay Gateways for which to encrypt the session key.
If you use this Resource Manager, supply the information listed in Table 4-22.
Group-Session-Limit allows you to manage concurrent sessions for a group of users; that is, it keeps track of how many sessions are active and denies new sessions once the configured limit has been reached.
When you use this Resource Manager, you must set the GroupSessionLimit property to the maximum number of concurrent sessions for all users.
Home-Agent is a new resource manager that supports dynamic HA assignment. You configure the home-agent resource manager with a list of IP addresses. The AR server assigns those addresses to clients whose request dictionary has the right attributes to indicate that an assignment should be done. This is similar to the ip-dynamic resource manager.
Unlike the ip-dynamic resource manager, HAs are not exclusively allocated to an individual session but are shared among a set of sessions.
Detailed configuration information for the Home-Agent resource manager is found in Chapter 17, "Wireless Support." When you use this Resource Manager, you must set the Home-Agent-IPAddresses property to a single IP address or a range of IP addresses.
IP-Dynamic allows you to manage a pool of IP addresses from which you dynamically allocate IP addresses.
When you use the IP-Dynamic Resource Manager, provide values for the properties listed in Table 4-23.
IP-Per-NAS-Port allows you to associate specific IP addresses with specific NAS ports and thus ensures each NAS port always gets the same IP address.
When you use this Resource Manager, provide values for the properties listed in Table 4-24.
Note You must have the same number of IP addresses and ports.
An IPX-Dynamic Resource Manager allows you to dynamically manage a pool of IPX networks. When you use the IPX-Dynamic Resource Manager, you must set the Networks property to a valid set of numbers which correspond to your networks.
Note You cannot use IPX network number 0x0. If you attempt to configure a Resource Manager with an IPX network number of 0x0, validation will fail.
The session-cache Resource Manager supports the Identity Cache feature. You use session-cache Resource Managers to define the RADIUS attributes to store in cache. Set the QueryKey property to the XML attribute you want to key on such as XML-Address-format-IPv4 and list all attributes to be cached in the AttributesToBeCached subdirectory. Use the QueryMappings subdirectory to map XML attributes to RADIUS attributes.
Note Session record size is limited by the operating system (OS) paging size (8 KB in Solaris and 4 KB in Linux). If a request triggers creation of a session that exceeds the OS paging size, the request will be dropped and the session will not be created.
If the disk partition where Cisco AR stores session backing store data (usually the disk partition where Cisco AR is installed, such as /opt/CSCOar) is full, the subsequent packets that try to create sessions will be dropped and no sessions will be created due to lack of disk space.
The subnet-dynamic Resource Manager supports the On Demand Address Pool feature. You use subnet-dynamic resource managers to provide pools of subnet addresses. Following is an example of the configuration of a subnet dynamic resource manager:
/Radius/ResourceManagers/newResourceMgr
Name = newResourceMgr
Description =
Type = subnet-dynamic
Subnet-Mask = 255.255.255.0
SubnetAddresses/
10.1.0.0-10.1.10.0
11.1.0.0-11.1.10.0
When you use the subnet-dynamic Resource Manager, provide values for the properties listed in Table 4-26.
User-Session-Limit allows you to manage per-user concurrent sessions; that is, it keeps track of how many sessions each user has and denies the user a new session once the configured limit has been reached.
When you use the user-session-limit Resource Manager, set the user-session-limit property to the maximum number of concurrent sessions for a particular user.
USR-VPN allows you to set up a Virtual Private Network (VPN) using a US Robotics NAS.
When you use this Resource Manager, provide values for the properties listed in Table 4-27.
You use Profiles to group RADIUS attributes that belong together, such as attributes that are appropriate for a particular class of PPP or Telnet user. You can reference profiles by name from either the UserGroup or the User properties. Thus, if the specifications of a particular profile change, you can make the change in a single place and have it propagated throughout your user community.
Although you can use UserGroups or Profiles in a similar manner, choosing whether to use one rather than the other depends on your site. When you require some choice in determining how to authorize or authenticate a user session, then creating specific profiles, and creating a group that uses a script to choose among them is more flexible.
In such a situation, you might create a default group, and then write a script that selects the appropriate profile based on the specific request. The benefit to this technique is each user can have a single entry, and use the appropriate profile depending on the way they log in.
Table 4-28 lists the Profile properties.
Attributes are specific RADIUS components of requests and responses defined in the Request and Response Attribute dictionaries. Use the aregcmd command set to assign values to attributes.
For a complete list of the attributes, see Appendix C, "RADIUS Attributes." When setting a value for a STRING-type attribute such as Connect-Info (which starts with an integer), you must use the hexadecimal representation of the integer. For example, to set the attribute Connect-Info to a value of 7:7, use a set command like the following:
set Connect-Info 37:3A:37
Translations add new attributes to a packet or change an existing attribute from one value to another. The Translations subdirectory lists all definitions of Translations the RADIUS server can apply to certain packets.
Under the /Radius/Translations directory, any translation to insert, substitute, or translate attributes can be added. The following is a sample configuration under the /Radius/Translations directory:
cd /Radius/Translations
Add T1
cd T1
Set DeleAttrs Session-Timeout,Called-Station-Id
cd Attributes
Set Calling-Station-Id 18009998888
DeleAttrs is the set of attributes to be deleted from the packet. Each attribute is comma separated and no spaces are allowed between attributes. All attribute value pairs under the attributes subdirectory are the attributes and values that are going to be added or translated to the packet.
Under the /Radius/Translations/T1/Attributes directory, inserted or translated attribute value pairs can be set. These attribute value pairs are either added to the packet or replaced with the new value.
If a translation applies to an Access-Request packet, by referencing the definition of that translation, the CAR server modifies the Request dictionary and inserts, filters and substitutes the attributes accordingly. You can set many translations for one packet and the CAR server applies these translations sequentially.
Note Later translations can overwrite previous translations.
Table 4-29 lists the Translation properties.
You can add translation groups for different user groups under TranslationGroups. All Translations under the Translations subdirectory are applied to those packets that fall into the groups. The groups are integrated with the CAR Rule engine.
The CAR Administrator can use any RADIUS attribute to determine the Translation Group. The incoming and outgoing translation group can be different translation groups. For example, you can set one translation group for incoming translations and one for outgoing translations.
Under the /Radius/TranslationGroups directory, translations can be grouped and applied to certain sets of packets, which are referred to in a rule. The following is a sample configuration under the /Radius/TranslationGroups directory:
cd /Radius/TranslationGroups
Add CiscoIncoming
cd CiscoIncoming
cd Translations
Set 1 T1
The translation group is referenced through the Cisco AR Policy Engine in the /Radius/Rules/<RuleName>/Attributes directory. Incoming-Translation-Groups are set to a translation group (for example CiscoIncoming) and Outgoing-Translation-Groups to another translation group (for example CiscoOutgoing). Table 4-30 lists the Translation Group properties.
Cisco AR 4.1 provides the following RemoteServer protocol types:
•LDAP
•ODBC
You can use the RemoteServers object to specify the properties of the remote servers to which Services proxy requests. RemoteServers are referenced by name from the RemoteServers list in either the radius, ldap or tacacs-udp Services.
Table 4-31 lists the common RemoteServers properties.
The Remote Server protocol you specify determines what additional information you must provide. The following are the protocols available in Cisco AR 4.1 with their required and optional fields.
The domain-auth Remote Server is used with the Windows Domain Authentication feature. Cisco AR 4.1 supports the Windows Domain Controller/Active Directory (WDC/AD) and enables you to authenticate users present in a WDC/AD using the CiscoSecure Remote Agent (CSRA).
Note You can download the CiscoSecure Remote Agent from http://www.cisco.com/cgi-bin/tablebuild.pl/acs-soleng-3des. The file to download is Remote-Agent-ACSse-win-v3.3.2.2-K9.zip, described as Remote Agent for Windows for Solution Engine, 3.3.2.2, dated 28-OCT-2004.
During authentication, the user credentials are sent to the CSRA, which authenticates the credentials with the WDC/AD. The user optionally can specify the domain name along with their UserID when they log in. If the domain is not specified, authentication is first performed with the local WDC/AD (default domain as specified in the remote server configuration), then with all the other trusted domain controllers, one by one until the user is found in any of the trusted WDC/ADs.
This failover to other domains is taken care by the local (default) WDC/AD. The local WDC/AD maintains a list of trusted domains and when the user is not found in the local AD, the WDC queries the trusted WDC/ADs, to see if any one those had the user in it. If any of the WDC/ADs has the user, those credentials would be used to authenticate the user.
The WDC/AD authentication stops at the first hit and does not check other domains even if the user credentials do not match (resulting in an authentication failure). When a domain is specified, authentication is performed only on that domain. This domain should be either the local WDC/AD or one of the trusted WDC/ADs.
A 128-bit Blowfish (variant) encryption algorithm secures the communication between the Cisco AR and CSRA. The session key for this encryption is negotiated when the connection is established.
The following is the default configuration of a domain-auth Remote Server.
[ //localhost/Radius/RemoteServers/domain-auth ]
Name = newone
Description =
Protocol = domain-auth
HostName =
Port = 2004
ReactivateTimerInterval = 300000
DefaultDomain =
Timeout = 15
AgentConnections = 15
DefaultUserGroup =
GroupMaps/
Table 4-32 lists and defines the domain-auth RemoteServer properties.
Users can optionally be authorized using WDC/AD using a list of groups the user belongs to in WDC/AD. This list of groups is mapped to an internal group in the Cisco AR server using the GroupMaps property. An optional default group can also be configured using the DefaultUserGroup property.
When a hit is made, the corresponding group is taken, even if there might be a better match further down the list. For example, if the user is part of groups A, B, C, and D, and if a map for Groups A, B, and C is listed before a map for Groups A, B, C, and D, the map for Groups A, B, and C will be taken. This requires the administrator to configure more specific mapping before the general mapping.
The list of groups from the WDC/AD is copied to a new environment variable named Windows-Domain-Groups to permit mapping to a more appropriate group at the next relevant scripting point.
The dynamic-dns RemoteServer is used with the Dynamic DNS feature. The following is the default configuration of a dynamic-dns RemoteServer.
[ //localhost/Radius/RemoteServers/ddns ]
Name = ddns
Description =
Protocol = dynamic-dns
IPAddress =
Port = 53
MaxTries = 3
InitialTimeout = 2000
MaxDNSRenamingRetries = 3
TrimHostName = TRUE
ForwardZoneTSIGKey =
ReverseZoneTSIGKey =
Table 4-33 lists and defines the dynamic-dns RemoteServer properties.
ldap specifies an LDAP server. When you specify the ldap protocol, provide the information listed in Table 4-34.
For any LDAP remote service, the server might perform the environment mappings at any time. This means that if the service is set to either authentication and authorization, authentication-only, or authorization-only, environment mappings will take place. RADIUS mappings will take place only if the service is set to perform authorization. Checkitem mappings will take place only if the service is set to perform authentication. Previously environment mappings only occurred when the service was set for both authentication and authorization.
The following is the default configuration of a map gateway RemoteServer.
[ //localhost/Radius/RemoteServers/map-gateway ]
Name = map-gateway
Description =
Protocol = map-gateway
IPAddress =
Port = 0
ReactivateTimerInterval = 300000
SharedSecret =
MaxTries = 3
InitialTimeout = 2000
odbc specifies an ODBC server. Cisco AR provides a RemoteServer object (and a service) to support Open Database Connectivity (ODBC), an open specification that provides application developers a vendor-independent API with which to access data sources. Table 4-35 lists the odbc server attributes.
For any ODBC remote service, the server might perform the environment mappings at any time. This means that if the service is set to either authentication and authorization, authentication-only, or authorization-only, environment mappings will take place. RADIUS mappings will take place only if the service is set to perform authorization. Checkitem mappings will take place only if the service is set to perform authentication. Previously environment mappings only occurred when the service was set for both authentication and authorization.
If you use the Oracle Accounting feature, you must configure an ODBC-Accounting RemoteServer object. Table 4-36 lists and defines the ODBC-Accounting RemoteServer properties.
|
|
---|---|
Name |
Name of the remote server; this property is mandatory, and there is no default |
Description |
Optional description of server |
Protocol |
Must be set to odbc-accounting |
ReactivateTimerInterval |
Mandatory time interval (in milliseconds) to activate an inactive server; defaults to 300000 ms. |
Timeout |
Mandatory time interval (in seconds) to wait for SQL operation to complete; defaults to 15 seconds |
DataSourceConnections |
Mandatory number of connections to be established; defaults to 8 |
ODBCDataSource |
Name of the ODBCDataSource to use and must refer to one entry in the list of ODBC datasources configured under /Radius/Advanced/ODBCDataSources. Mandatory; no default |
KeepAliveTimerInterval |
Mandatory time interval to send a keepalive to keep the idle connection active; defaults to zero (0) meaning the option is disabled |
BufferAccountingPackets |
Mandatory, TRUE or FALSE, determines whether to buffer the accounting packets to local file, defaults to TRUE which means that packet buffering is enabled. Note When set to TRUE, a constant flow of incoming accounting packets can fill the buffer backing store files in /cisco-ar/data/odbc beyond the size configured in MaximumBufferFileSize. Configure BackingStoreDiscThreshold in /Radius/Advanced when using ODBC accounting. See Advanced for information about how to configure BackingStoreDiscThreshold. |
MaximumBufferFileSize |
Mandatory if BufferAccountingPackets is set to TRUE, determines the maximum buffer file size, defaults to 10 Megabyte) |
NumberOfRetriesForBufferdPacket |
Mandatory if BufferAccountingPackets is set to TRUE. A number greater than zero determines the number of attempts to be made to insert the buffered packet into Oracle. Defaults to 3. |
The following is the default configuration of a prepaid-crb RemoteServer. The Filename property is the name of the required shared library provided by the billing vendor.
[ //localhost/Radius/RemoteServers/prepaid-crb ]
Name = prepaid-crb
Description =
Protocol = prepaid-crb
IPAddress =
Port = 0
Filename =
Connections = 8
The following is the default configuration of a prepaid-is835c RemoteServer. The Filename property is the name of the required shared library provided by the billing vendor.
[ //localhost/Radius/RemoteServers/prepaid-is835c ]
Name = prepaid-is835c
Description =
Protocol = prepaid-is835c
IPAddress =
Port = 0
Filename =
Connections = 8
radius specifies a RADIUS server. When you specify the radius protocol, supply the information in Table 4-37.
A Rule is a function that selects services based on all input information used by the function.
Advanced objects let you configure system-level properties and the Attribute dictionary. Under normal system operation, you should not need to change the system-level properties.
Note The notation required means Cisco AR needs a value for this property. For most of these properties, you can use system defaults.
Table 4-38 lists the Advanced properties.
|
|
---|---|
LogServerActivity |
Required; the default is FALSE, which means Cisco AR logs all responses except Access-Accepts and Access-Challenges. Accepting the default reduces the load on the server by reducing that amount of information it must log. Note, the client is probably sending accounting requests to an accounting server, so the Access-Accept requests are being indirectly logged. When you set it to TRUE, Cisco AR logs all responses to the server log file. |
MaximumNumberOfRadiusPackets |
Required; the default is 1024. This is a critical property you should set high enough to allow for the maximum number of simultaneous requests. When more requests come in than there are packets allocated, Cisco AR will drop those additional requests. |
PerPacketHeapSize |
Required; the default is 6500. This property sets the size of the initial heap for each packet. The heap is the dynamic memory a request can use during its lifetime. By preallocating the heap size at the beginning of request processing, we can minimize the cost of memory allocations. If PerPacketHeapSize is too low, Cisco AR will ask the system for memory more often. If PerPacketHeapSize is too high, Cisco AR will allocate too much memory for the request causing the system to use more memory than required. |
UDPPacketSize |
Required; the default is 4096. RFC 2138 specifies the maximum packet length can be 4096 bytes. Do not change this value. |
RequireNASsBehindProxyBeInClientList |
Required; the default is FALSE. If you accept the default, Cisco AR only uses the source IP address to identify the immediate client that sent the request. Leaving it FALSE is useful when this RADIUS Server should only know about the proxy server and should treat requests as if they came from the proxy server. This might be the case with some environments that buy bulk dial service from a third party and thus do not need to, or are unable to, list all of the NASs behind the third party's proxy server. When you set it to TRUE, you must list all of the NASs behind the Proxy in the Clients list. For more information about this property, see "Using the RequireNASsBehindProxyBeInClientList Property" section. |
AAAFileServiceSyncInterval |
Required; specified in milliseconds, the default is 75. This property governs how often the file AAA service processes accounting requests and writes the accounting records to the file. You can lower the number to reduce the delay in acknowledging the Account-Request at the expense of more frequent flushing of the accounting file to disk. You can raise the number to reduce the cost of flushing to disk, at the expense of increasing the delays in acknowledging the Accounting-Requests. The default value was determined to provide a reasonable compromise between the two alternatives. |
SessionBackingStoreSynchronizationInterval |
Required; specified in milliseconds, the default is 100. If you change this value it must be a number greater than zero. This property governs how often the Session Manager backing store writes updated session information to disk. You can lower the number to reduce the delay in acknowledging requests at the expense of more frequent flushing of the file containing the session data to disk. You can raise the number to reduce the cost of flushing to disk at the expense of increasing delays in acknowledging requests. The default value was determined to provide a reasonable compromise between the two alternatives. |
BackingStoreDiscThreshold |
Required; the default is 10 gigabytes. The value of BackingStoreDisc- BackingStoreDiscThreshold is used with session management and ODBC accounting and ensures that any data log files generated will not cross the BackingStoreDiscThreshold. |
SessionBackingStorePruneInterval |
Required; specifies the sleep time interval of the session backing store pruning thread. The recommended and default value is 6 hours, but you can modify this based on the traffic patterns you experience. With SessionBackingStorePruneInterval set to 6 hours, pruning will occur 6 hours after you restart or reload the Cisco AR server and recur every 6 hours. You can set a very low value for this property to make pruning continuous, but there might not be enough data accumulated for the pruning to occur and pruning might be less effective compared to the default setting. |
PacketBackingStorePruneInterval |
Required; specifies the sleep time interval of the packet backing store pruning thread. The recommended value is 6 hours, but you can modify this based on the traffic patterns you experience. When PacketBackingStorePruneInterval is set to 6 hours, pruning will occur 6 hours after you restart or reload the Cisco AR server and recur every 6 hours. You can set a very low value for this property to make pruning continuous, but there might not be enough data accumulated for the pruning to occur and pruning might be less effective compared to the default setting. |
RemoteLDAPServiceThreadTimerInterval |
Required; specified in milliseconds, the default is 10. This property governs how often the ldap RemoteServer thread checks to see if any results have arrived from the remote LDAP server. You can modify it to improve the throughput of the server when it proxies requests to a remote LDAP server. |
InitialBackgroundTimerSleepTime |
Required; the default is 5. This property specifies the amount of time the time queue should initially sleep before beginning processing. This property is only used for initial synchronization and should not be changed. |
MinimumSocketBufferSize |
Required; the default is 65536 (64 K). This property governs how deep the system's buffer size is for queueing UDP datagrams until Cisco AR can read and process them. The default is probably sufficient for most sites. You can, however, raise or lower it as necessary. |
CertificateDBPath |
Required if you are using an LDAP RemoteServer and you want Cisco AR to use SSL when communicating with that LDAP RemoteServer. This property specifies the path to the directory containing the client certificates to be used when establishing an SSL connection to an LDAP RemoteServer. This directory must contain the cert7.db and cert5.db certificates and the key3.db and key.db files database used by Netscape Navigator 3.x (and above) or the ServerCert.db certificate database used by Netscape 2.x servers. |
LogFileSize |
Required; the default is 1 Megabyte. This property specifies the maximum size of the RADIUS server log file. The value for the LogFileSize field is a string composed of two parts; a number, and a units indicator (<n> <units>) in which the unit is one of: K, kilobyte, kilobytes, M, megabyte, megabytes, G, gigabyte, or gigabytes. The LogFileSize property does not apply to the config_mcd_1_log or agent_server_1_log files. See Modifying File Sizes for Agent Server and MCD Server Logs, page 24-3 to configure these files. Note This does not apply to the trace log. |
LogFileCount |
Required; the default is 2. This property specifies the number of log files to be kept on the system. A new log file is created when the log file size reaches LogFileCount. The LogFileCount property does not apply to the config_mcd_1_log or agent_server_1_log files. See Modifying File Sizes for Agent Server and MCD Server Logs, page 24-3 to configure these files. |
TraceFileSize |
Required; the default is 1 GB. This property specifies the size of the trace files to be kept on the system. A new trace file is created when the trace file size reaches TraceFileSize. The value for the TraceFileSize field is a string composed of two parts; a number, and a units indicator (<n> <units>) in which the unit is one of: K, kilobyte, kilobytes, M, megabyte, megabytes, G, gigabyte, or gigabytes. |
TraceFileCount |
Required; this value can be set from 1-100, and the default is 2. This property specifies the number of trace files to maintain. A value of 1 indicates that no file rolling occurs. |
UseAdvancedDuplicateDetection |
Required; the default is FALSE. Set this property to TRUE when you want Cisco AR to use a more robust duplicate request filtering algorithm. For more information on this property, see the "Advance Duplicate Detection Feature" section. |
AdvancedDuplicateDetectionMemoryInterval |
Required when the Advanced Duplicate Detection feature is enabled. This property specifies how long (in milliseconds) Cisco AR should remember a request. You must specify a number greater than zero. The default is 10,000. |
DetectOutOfOrderAccountingPackets |
Optional; used to detect accounting packets that arrive out of sequential order. The default is FALSE. This property is useful when using accounting and session management in a RADIUS proxy service. Note The following functionality is introduced in Cisco AR 4.1.4. When the DetectOutOfOrderAccountingPacket property is enabled (set to TRUE), a new Class attribute is included in all outgoing Accept packets. The value for this Class attribute will contain the session magic number. The client will echo this value in the accounting packets, and this will be used for comparison. The session magic number is a unique number created for all sessions when the session is created or reused and the DetectOutOfOrderAccountingPacket property is set to TRUE. The DetectOutOfOrderAccountingPacket property is used to detect out-of-order Accounting-Stop packets in roaming scenarios by comparing the session magic number value in the session with the session magic number value contained in the Accounting packet. The value of 0xffffffff is considered by the Cisco AR server to be a wild card magic number. If any accounting stop packets contain the value of 0xffffffff, it will pass the session magic validation even if the session's magic number is some thing else. The format of the class attribute is as follows: <4-byte Magic Prefix><4-byte server IP address><4-byte Magic value> |
DefaultReturnedSubnetSizeIfNoMatch |
Optional; used with the ODAP feature and reflects the returned size of the subnet if no matched subnet is found. There are three options to select if an exactly matched subnet does not exist: Bigger, Smaller, and Exact. The default is Bigger. |
ClasspathForJavaExtensions |
A string which is the classpath to be used to locate Java classes and jar files containing the classes required for loading the Java extensions, either Java extension points or services. Note The classpath will always contain the directory $INSTALLDIR/scripts/radius/java and all of the jar files in that directory. |
JavaVMOptions |
A string that can contain options to be passed to the JRE upon startup. JavaVMOptions should be used only when requested by Cisco TAC. |
MaximumODBCResultSize |
Specifies maximum size in bytes for an ODBC mapping. This parameter affects both ODBC result sizes and the trace log buffer for tracing script calls that access any of the dictionaries. (Default value is 256.) |
ARIsCaseInsensitive |
When set to FALSE, requires that you provide exact path names with regard to upper and lower case for all objects, subobjects, and properties. The default setting, TRUE, allows you to enter paths such as /rad/serv instead of /Rad/Serv. Note Cisco AR always authenticates the RADIUS attribute User-Name with regard to upper and lower case, regardless of the setting of this flag. |
RemoteRadiusServerInterface |
When set, specifies the local interface to bind to when creating the RemoteRadiusServer socket. If not set, the Cisco AR binds to IPADDR_ANY. |
ODBCEnvironmentMultiValueDelimiter |
Optional; allows you to specify a character that separates multi-valued attributes in the marker list when using Oracle (or ODBC) accounting |
PacketBackingStoreSyncInterval |
The minimum value is 1 and the maximum is a 32-bit unsigned integer. The default is 75. |
ListenForDynamicAuthorizationRequests |
Must be set to TRUE when using the Change of Authorization (CoA) feature or Packet of Disconnect (POD) feature. Default is FALSE. |
MaximumNumberOfXMLPackets |
Required when using identity caching. Indicates the maximum number of XML packets to be sent or received. The minimum value is 1 and the maximum is a 32-bit unsigned integer. The default is 1024. |
XMLUDPPacketSize |
Required when using identity caching. Indicates the maximum size of XML packets to be sent or received. The minimum value is 1 and the maximum is a 32-bit unsigned integer. The default is 4096. |
RollingEncryptionKeyChangePeriod |
Used in conjunction with the session-cache ResourceManager, this property specifies the length of time a given EncryptionKey will be used before a new one is created. When the session-cache ResourceManager caches User-Password attributes, Cisco AR encrypts the User-Password so it is not stored in memory or persisted on disk in clear text. Cisco AR uses up to 255 encryption keys, using a new one after each RollingEncryptionKeyChangePeriod expires. If RollingEncryptionKeyChangePeriod is set to 2 days, Cisco AR will create and begin using a new EncryptionKey every two days. The oldest key will be retired, and Cisco AR will re-encrypt any User-Passwords that used the old key with the new key. This way, if the RollingEncryptionKeyChangePeriod is set to 1 day, no key will be older than 255 days. |
SessionPurgeInterval |
Optional; the SessionPurgeInterval property determines the time interval at which to check for timed-out sessions. If no value is set, the session timeout feature is disabled. The checks are performed in the background when system resources are available, so checks might not always occur at the exact time set. The minimum recommended value for SessionPurgeInterval is 60 minutes. The SessionPurgeInterval value is comprised of a number and a units indicator, as in n units, where a unit is one of minutes, hours, days, or weeks. |
EapBadMessagePolicy |
Set to one of two values: SilentDiscard (the default) or RejectFailure. When set to SilentDiscard, the Cisco AR server silently discards and ignores bad EAP messages unless the protocol specification explicitly requires a failure message. When set to RejectFailure, the Cisco AR server sends RADIUS Access-Rejects messages with embedded EAP-Failure in response to bad EAP messages as described in Internet RFC 3579. |
StaleSessionTimeout |
Required; the default value is "1 hour." Specifies the time interval to maintain a session when a client does not respond to Accounting-Stop notification. When the Cisco AR server does not receive an Accounting-Response from a client after sending an Accounting-Stop packet, Cisco AR maintains the session for the time interval configured in this property before releasing the session. This property is stored as a string composed of two parts: a number and a unit indicator (<n> <units>) similar to the MaxFileAge property where the unit is one of: M, Minute, Minutes, H, Hour, Hours, D, Day, Days, W, Week, or Weeks. |
Ports/ |
Optional; allows you to use ports other than the default, 1645 and 1646. You can use this option to configure Cisco AR to use other ports,. If you add additional ports, however, Access Registrar will use the added ports and no longer use ports 1645 and 1646. These ports can still be used by adding them to the list of ports to use. For more information, refer to "Ports" section. |
Interfaces |
Optional; refer to "Interfaces" section |
ReplyMessages |
Optional; refer to "Reply Messages" section. |
AttributeDictionary |
Optional; refer to "Attribute Dictionary" section. |
SNMP |
Optional; refer to "SNMP" section. |
RFC Compliance/ |
Optional; enables you to modify the Cisco AR server to behave in a way that might deviate from RFC compliance in a special use case scenario. When AllowRejectAttrs is set to FALSE, Reply-Message attributes will not be passed in an Access Reject packet. When AllowRejectAttrs is set to TRUE, attributes will be allowed to pass in an Access Reject packet. When AllowEAPRejectAttrs is set to FALSE, Reply-Message attributes will not be passed in an Access Reject packet if the packet contains EAP-Message attribute. When AllowEAPRejectAttrs is set to TRUE, attributes will be allowed to pass in an Access Reject packet even if the packet contains EAP-Message attribute. Note Changing the state of either of these properties requires you to reload the Cisco AR server. |
DDNS |
This subdirectory holds the SynthesizeReverseZone property and a list of Transaction Signatures (TSIG) keys. |
SynthesizeReverseZone |
This property exists under DDNS and controls whether Cisco AR automatically generates the name of the reverse zone (in-addr.arpa) that is updated with PTR records. If this attribute is enabled and the resource manager does not have an explicit ReverseZoneName property configured, the server uses the IP address and DNSHostBytes property to generate the reverse zone name. The default value is TRUE. |
ODBCDataSources |
A list of ODBC data sets and their associated environments including operating system, DBMS, and network platform used to access the DBMS an application wants to access. Required when using Oracle (or ODBC) accounting. |
AttributeGroups |
Includes a Default subdirectory with an Attributes subdirectory that contains commonly-used attributes for Change of Authorization (CoA) and Packet of Disconnect (POD). You can add new attributes to the default group or create a new group as necessary. |
KeyStores |
Used to protect the security and integrity of the PACs it issues. •NumberOfKeys—Number (from 1-1024) that specifies the maximum number of keys stored for EAP-FAST. •RolloverPeriod—Specifies the amount of time between key updates. |
NumberOfRemoteUDPServerSockets |
Required; the default value for this property is 4. The NumberOfRemoteUDPServerSockets property allows you to configure the number of source ports used while proxying requests to a remote radius server. If the NumberOfRemoteUDPServerSockets property is set to a value n, all remote servers share and use n sockets. The NumberOfRemoteUDPServerSockets value comprises a number, as in n, where n should be less than or equal to the current process file descriptor limit divided by 2. |
MaximumIncomingRequestRate |
Optional; the default value for this property is 0. The MaximumIncomingRequestRate property is used to limit the incoming traffic in terms of "allowed requests per second". Serves as a soft limit. The MaximumIncomingRequestRate property comprises a number n, where n can be any nonzero value. |
MaximumOutstandingRequests |
Optional; the default value for this property is 0. The MaximumOutstandingRequests property is used to limit the incoming traffic in terms of "requests processed". Serves as a hard limit. The MaximumOutstandingRequests property comprises a number n, where n can be any nonzero value. |
You can use the property RequireNASsBehindProxyBeInClientList to require NASs that send requests indirectly through a proxy to be listed in the Clients list or to allow the proxy to represent them all.
•When you want to ensure the proxy is only sending requests from NASs known to this server, set the property to TRUE, and list all of the NASs using this proxy. This increases memory usage.
•When it is impossible to know all of the NASs using this proxy or when you do not care, set the property to FALSE. Cisco AR will use the proxy's IP address to identify the origin of the request.
Cisco AR automatically detects and handles duplicate requests it is currently working on. It also provides an optional, more complex mechanism to handle duplicate requests that can be received by the server after it has completed processing the original request. These duplicate requests can consume extra processing power, and, if received out of order (as RADIUS is a UDP-based protocol) might cause Session Management problems.
One solution is the Advanced Duplicate Detection feature which causes Cisco AR to remember requests it has seen, as well as the response sent to that request, for a configurable amount of time.
To enable this feature, perform the following:
•Set the UseAdvancedDuplicateDetection property in the /Radius/Advanced section of the configuration to TRUE.
•Set the AdvancedDuplicateDetectionMemoryInterval in the /Radius/Advanced section to specify how long (in milliseconds) Cisco AR should remember a request.
Note Enabling this feature causes Cisco AR to keep more of its preallocated packet buffers in use for a longer period of time. The number of preallocated buffers is controlled by the MaximumNumberOfRadiusPackets property in the /Radius/Advanced section of the configuration. This property might need to be increased (which will increase the amount of memory used by Cisco AR) when the Advanced Duplicate Detection feature is enabled.
Cisco AR 3.5.4 has been enhanced to implement fatal error packet handling for Extensible Authentication Protocol (EAP) messages as described in section 2.2 of Internet RFC 3579 which states the following:
A RADIUS server determining that a fatal error has occurred must send an Access-Reject containing an EAP-Message attribute encapsulating EAP-Failure.
Because this enhancement is a deviation from various EAP specifications, you must explicitly enable this feature through a new configuration property in /Radius/Advanced named EapBadMessagePolicy.
You can set the EapBadMessagePolicy property to one of two values: SilentDiscard (the default) or RejectFailure. When set to SilentDiscard, the Cisco AR server silently discards and ignores bad EAP messages unless the protocol specification explicitly requires a failure message. When set to RejectFailure, the Cisco AR server sends RADIUS Access-Rejects messages with embedded EAP-Failure in response to bad EAP messages as described in Internet RFC 3579.
The implementation of EAP authentication methods in Cisco AR 3.5.3 (and earlier releases) behaves as described in Internet RFC 2284 (EAP) and related EAP method specifications. These specify silent discard as the standard way to handle all EAP error conditions. Any EAP response message from the client that contains an error or is received in an invalid authenticator state is discarded and there is no error response.
In a configuration where EAP requests are proxied between RADIUS servers using RADIUS messages (EAP over RADIUS), the silent discard of an EAP message means that no RADIUS response message is sent back to the originating RADIUS server. Because of this, the RADIUS server originating the request eventually declares the destination RADIUS server dead and fails over to a backup server (if so configured).
The Ports list specifies which ports to listen to for requests. When you specify a port, Cisco AR makes no distinction between the port used to receive Access-Requests and the port used to receive Accounting-Requests. Either request can come in on either port.
Most NASs send Access-Requests to port 1645 and Accounting-Requests to 1646, however, Cisco AR does not check.
When you do not specify any ports, Cisco AR reads the /etc/services file for the ports to use for access and accounting requests. If none are defined, Cisco AR uses the standard ports (1645 and 1646).
The Interfaces list specifies the interfaces on which the RADIUS server receives and sends requests. You specify an interface by its IP address.
•When you list an IP address, Cisco AR uses that interface to send and receive Access-Requests.
•When no interfaces are listed, the server performs an interface discover and uses all interfaces of the server, physical and logical (virtual).
The Reply Messages list allows you to choose the reply message based on the reason the request was rejected. Each of the following properties (except Default) corresponds to a reason why the packet was rejected. The Reply Message properties allows you to substitute your own text string for the defined errors. After you set the property (with the set command) and the reason occurs, Cisco AR sends the NAS that message in the Access-Reject packet as a Reply-Message attribute.
You might want to substitute your own messages to prevent users from getting too much information about why their requests failed. For example, you might not want users to know the password was invalid to prevent hackers from accessing your system. In such a case, you might specify the text string "unauthorized access
" for the property UserPasswordInvalid.
Table 4-39 lists the Reply Message properties.
The Attribute dictionary allows you to specify the attributes to the RADIUS server. Cisco AR comes with the standard RADIUS attributes (as defined by the RFC 2865) as well as the attributes required to support the major NASs. For more information about the standard attributes, see Appendix C, "RADIUS Attributes."
All RADIUS requests and responses consist of one or more attributes, such as the user's name, the user's password, the type of service the NAS should provide to the user, or the IP address the user should use for the session.
In the request and response packets, an attribute is composed of a number (between 1-255) that specifies the type of attribute to use, a length that specifies the entire attribute length, and a value. How the value is interpreted depends on its type. When it is a username, the value is a string. When it is the NAS's IP address, the value is an IP address, and so on.
Table 4-40 lists the Attribute dictionary properties.
|
|
---|---|
Name |
Required; must be unique in the Attribute dictionary list within the same context. Although it should be an attribute defined in the RFC, the name can be any attribute defined by your client. The NAS typically comes with a list of attributes it uses. Attributes are referenced in the Profile and by Scripts by this name. The accounting file service also uses this name when printing the attribute. |
Description |
Optional description of the attribute. |
Attribute |
Required; must be a number between 1-255. It must be unique within the Attribute dictionary list. |
Type |
Required; must be set to one of the types listed in Table 4-41. The type governs how the value is interpreted and printed. |
Types are required and must be one of the following listed in Table 4-41.
Table 4-42 lists the Vendor properties.
Table 4-43 lists the five properties of the SNMP directory.
If Enabled and MasterAgentEnabled are both TRUE, arservagt will start and stop the SNMP daemon (snmpd). If either of these properties is FALSE, if the AR server is not using SNMP or if your site uses a different master agent, arservagt will not start your master agent.