Current Sessions Table Fields

The CST and the CurrentSessions.sql contain several types of fields:

•  System Core Fields

•  System Feature Fields

•  System Optional Fields

•  RadAttr Fields

•  Admin Private Fields

The table also contains settings for keys and indexes:

•  System Keys and Indexes

•  Admin Keys and Indexes

System Core Fields

System Core Fields

The System Core fields are required for basic operation of SBR Carrier SSR.

The System Core Fields section of CurrentSessions.sql looks like this:

The datatypes and sizes for System Core fields are specified Table 22. Some of these datatypes and sizes are fixed. The ones that may be changed have default values specified in the table. These defaults are a starting point to use during pre-production prototyping.

System Feature Fields

System Feature Fields

One or more of the System Feature fields listed in Table 23 must be present in the CST for Steel-Belted Radius Carrier to run in a special feature enabled mode. If a required System Feature field is not present in the CST, Steel-Belted Radius Carrier boots, but the special feature is disabled.

The System Feature Fields section of CurrentSessions.sql looks like this:

Table 23 describes the System Feature Fields, SQL datatypes, and sizes.

System Optional Fields

System Optional Fields

System optional fields can provide useful information about a session, but none are required, so you may comment out unnecessary fields.

The System Optional Fields section of CurrentSessions.sql looks like this:

Table 24 describes System Optional Fields, SQL datatypes, and sizes.

* The Acct-Session-Id RADIUS attribute is commonly used in CoA/DM packing lists for router requirements. Packing lists represent the router’s requirements for a valid DM or CoA request. Attributes that are not in the CST must come from the actual query to fulfill the request.

To have data available for queries using the command line utility (SessionControl.sh) for CoA/DM requests, you must configure this attribute in the packing list. If the Sbr_AcctSessionId does not exist in the CST or is not found by the query itself, the request fails.

RadAttr Fields

RadAttr Fields

The System Core, System Feature, and System Optional fields are sufficient for most deployments, but if a site has requirements for CST information that cannot be supported by the System fields, you can add RadAttr fields to the CST. RadAttr fields are designed to capture data from RADIUS packet attributes. You must be knowledgeable about RADIUS attributes, how they are used in the network, and which attributes to incorporate into the CST.

You can add as many as 64 RadAttr fields to the CST, but fields beyond the 64th are not populated by Steel-Belted Radius Carrier.

The Admin Radattr Fields section of CurrentSessions.sql looks like this:

Table 25 describes Admin RadAttr Fields, SQL datatypes, and sizes.

RadAttr fields are similar to some of the System Core and Optional fields, but differ in that the System fields are supported natively and are processed by Steel-Belted Radius Carrier. The RadAttr fields work with raw values extracted from RADIUS packets.

When you create a field, follow these guidelines:

• The RadAttrFieldName for a field may be any legal SQL name, except that its first three characters cannot be the reserved System prefix Sbr (in any letter case combination).

• Each RadAttrFieldName can occur only once in the sessionTable.ini file. A RadAttrFieldName specifies a column name in the CST, and duplicate column names are illegal in SQL tables.

• You can declare a RadAttrFieldName in the CST schema but not declare it in the sessionTable.ini file. For example, you can declare the PrivateFieldName name in the CST schema, but not in the sessionTable.ini because you can define Private fields in the CST to hold any non-SBR Carrier data you want. This is useful where a third-party application accesses the CST.

• Valid Radius-Attribute-Names occur in Steel-Belted Radius Carrier dictionary files, as embodied in the SBR Carrier internal master dictionary (which includes attributes defined in files having .dct, .dcm, .dci, and .dcx extensions in the SBR Carrier installation root directory). For information about SBR Carrier dictionaries, refer to the readme.dct and dictiona.dcm files.

RadAttr Fields and the sessionTable.ini File

RadAttr Fields and the sessionTable.ini File

The procedure for adding RadAttr fields is more involved than just editing the CurrentSessions.sql file because an additional file, the sessionTable.ini, maps RadAttr CST field names to RADIUS attributes. Each addition of a RadAttr field in the CurrentSessions.sql file requires a corresponding entry in sessionTable.ini that defines the data used to populate the field and when to extract the data from the RADIUS packet.

RADIUS attributes can be generated by Steel-Belted Radius Carrier at four capture points, events that apply only to RadAttr fields:

• [AuthRequest]

• [AuthResponse]

• [AcctRequest]

• [AcctResponse]

Each RadAttr CST field requires at least one capture point to identify when RADIUS attributes are loaded in the field. Specify one or more capture-points by placing the field entry in one or more of the four capture point sections of the sessionTable.ini file.

One Radius-Attribute-Name can be captured multiple times, at different capture-points, by using multiple (different) RadAttrFieldNames, all of which are mapped to the same Radius-Attribute-Name.

If a RADIUS attribute is not present when a session’s RADIUS packet is scanned at a capture point event, the corresponding CST field is not updated. If the specified attribute does not occur in a packet at any capture point, the session displays a null value in the CST field.

If a session experiences multiple occurrences of packets at the same capture-point carrying the same Radius-Attribute-Name, the values of subsequent occurrences overwrite the values of preceding occurrences in the RadAttrFieldName field. For example, if a session receives multiple Accounting-Start packets, then the AcctRequest and AcctResponse capture-points are exercised more than once for that session, with the result that the captured Radius-Attribute-Name/ RadAddrFieldnames are updated multiple times. Thus, the CST always reflects the most recent values from each capture-point.

Creating RadAttr Field-to-Attribute Mappings

To support customizable CST fields requires a new configuration file, (sessionTable.ini), which is located in the Steel-Belted Radius Carrier installation root directory. The sessionTable.ini file maps RadAttrFieldName RadAttr CST fields to Radius-Attribute-Name RADIUS attributes:

RadAttrFieldName = Radius-Attribute-Name

How to Define RadAttr Fields

Defining a RadAttr field is a three-step procedure:

1. Create the field in the CurrentSessions.sql file.

   Add the RadAttrFieldName field to the CST schema in CurrentSessions.sql.

   For example:

    

2. Edit the sessionTable.ini file.

   Add the RadAttrFieldName = Radius-Attribute-Name field-to-attribute mapping line to the sessionTable.ini file in the appropriate capture point section or in several sections.

   This example supports the fields you entered Step 1:

3. Optionally, edit the ShowSessions.sh file.

   Add the RadAttrFieldName to ShowSessions.sh, if you want it to appear in the ShowSessions.sh command. You can customize the formatting of RadAttr fields, following the guidelines of the System fields in ShowSessions.sh.

After completing the preceding procedure for RadAttr fields and customizing System fields as needed, you must delete the existing database and create a new one that invokes your updated files. Then run ShowSessions.sh to verify that everything is working correctly.

Multi-Valued Attributes

Multi-Valued Attributes

The sessionTable.ini file supports a special syntax to support multi-valued attributes. The RADIUS protocol permits certain attributes to be multi-valued, meaning that two or more instances of the attribute can occur in a single RADIUS packet. System fields in the CST always involve single-valued attributes. RadAttr fields in the CST can be single-valued or multi-valued.

For RadAttr fields in the CST, we support multi-valued attributes with the six MVA facilities defined in the list that follows. Any field-to-attribute mapping (in sessionTable.ini) can have its Radius-Attribute-Name optionally appended with one (but no more than one) multi-valued attribute @ extension.

MVA-Count

The MVA-Count extension stores the count (0, 1, or more) of attributes of the specified Radius-Attribute-Name (occurring in the RADIUS packet being scanned at the specified capture-point). Declare RadAttrFieldName as an INT UNSIGNED field in the CST schema. If you declare it to be [VAR]CHAR or [VAR]BINARY, the field is automatically formatted.

Syntax:

MVA-Index

The MVA-Index extension stores the value of the Nth attribute (where N is equal to or greater than 1) of the Radius-Attribute-Name occurring in the RADIUS packet being scanned at the specified capture-point. For example, @1 means to store the first value of the specified Radius-Attribute-Name. If the packet carries fewer than N attributes of the designated type, a value of null is stored.

In this case, N is a 1-based, not 0-based, integer. Thus, N denotes a positive number in the range 1–2038, expressed in standard base-10 notation. Specifying a value for N outside this range is an error.

Syntax:

MVA-First

The MVA-First extension stores the first value of the Radius-Attribute-Name attribute occurring in the RADIUS packet being scanned at the specified capture-point. MVA-First extension is synonymous with the Radius-Attribute-Name@1 extension.

Syntax:

MVA-Last

The MVA-Last extension stores the last value of the Radius-Attribute-Name attribute occurring in the RADIUS packet being scanned at the specified capture-point.

Syntax:

MVA-CharString-Concat

The MVA-CharString-Concat extension treats the potentially multiple values of Radius-Attribute-Name as text strings. It concatenates them using the specified string “…”, as a field delimiter between successive values. Ensure that values of the Radius-Attribute-Name attribute are the natural CHAR datatype. If they are not, the appropriate unnatural conversion is applied.

The value of the delimiter string cannot contain the 2-character sequence @” (at-sign/double-quote) or internal NULL characters. The delimiter string can consist of any arbitrary (single-byte) characters, such as comma, colon, space, tab, and new line characters. This facility supports C/C++-language backslash-escaping (meta character) conventions. For example, to include a backslash character in a delimiter string or in a character data-value, enter it as: \\.

Syntax:

MVA-ByteString-Concat

The MVA-ByteString-Concat extension treats the potentially multiple values of Radius-Attribute-Name as byte strings. It concatenates them using a length and value representation: every value is represented by a one-byte length header that identifies the length of the data value in the range 1–253 and is followed by the data value. The concatenation terminates with a one-byte 0-value trailer that indicates a data of length 0, such as the end of the concatenated byte-string. Ensure that values of the Radius-Attribute-Name attribute are of the natural BYTE datatype. If they are not, the appropriate unnatural conversion is applied.

Syntax:

Using MVA Facilities

Using MVA Facilities

The syntax of the MVA facilities supports single-valued attributes and multi-valued attributes. For single-valued attributes, @1, @^, @$, and no-@-extension returns the value of the attribute. The @"…" and @* extensions return one item in the concatenation; no delimiter appears for @"…", while the 0-byte terminator immediately follows the first item in the list for @*.

Any field-to-attribute mapping in sessionTable.ini (whether its Radius-Attribute-Name is single-valued or multi-valued) that does not contain an MVA @ extension is considered to be equivalent to the same field-to-attribute mapping with an @^ extension appended to it.

In both the @"…" and the @* cases, the individual values in the MVA are listed in the order they occur in the RADIUS packet. According to the RADIUS protocol, attribute sequence is significant.

Ensure that the size of a CST field is large enough to hold all content that may be generated, especially for MVA-concatenated fields (@"…" and @*). One option you can use to solve the problem is to combine the MVA-concatenation facilities with the MVA-count facility (@#).

From the natural/unnatural design viewpoint, the MVA facilities lie somewhere in between; they can best be described as semi-natural, in two different ways:

• The @#, @N, @^, and @$ facilities, which deal only with single values, can be considered to be both natural and unnatural:

  • They are natural in the sense of the previously defined natural RADIUS datatype SQL datatype mappings.

  • They are unnatural in the sense that they can be subjected to the unnatural RADIUS datatype SQL datatype mappings (the same way that no-@-extension can).

• The @"…" and @* facilities, which deal with true multi-values, are necessarily non natural, because a concatenation operation does not exist in SQL. This leads to degrees of semi-naturalness:

  • In the case of CHAR values, it is (semi-)natural to separate concatenated items with a delimiter (field separator). However, the choice of the delimiter itself is conventional (unnatural).

  • In the case of BYTE values, it is (semi-)natural to format the concatenated items in header/footer format, but there is no canonical way to do that because there are many protocol transfer syntaxes in existence — consider the difference between the format we support versus ASN1/BER, for example.

  • In the case of INT/ADDR/TIME values, there is no well-defined concept of concatenation. MVAs in this case become unnatural to some extent, but it does seem natural to first convert the INT/ADDR/TIME values to CHAR/BYTE values, and then to concatenate those together.

Admin Private Fields

Admin Private Fields

You can add Private fields to the CST. Private fields are not processed by Steel-Belted Radius Carrier, and can include any information captured by or relevant to tools in the environment.

The Admin Private Fields section of CurrentSessions.sql looks like this:

System Keys and Indexes

System Keys and Indexes

This section of the file contains keys and indexes that are required for system operation.

The System Keys and Indexes section of CurrentSessions.sql looks like this:

Admin Keys and Indexes

Admin Keys and Indexes

This section of the file contains keys and indexes that are required for system operation.

The System Keys and Indexes section of CurrentSessions.sql looks like this: