Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation  Back up to About Overview 
  
[+] Expand All
[-] Collapse All

Current Sessions Table Fields

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

The table also contains settings for keys and indexes:

System Core Fields

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

Caution: We strongly recommend that you not edit this section of the file. If any required Core field is not present in the CST, Steel-Belted Radius Carrier SSR cannot boot.

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

#=======================================================================
##########################################################################
This CST schema is customizable, but CONSULT THE DOCUMENTATION FIRST!! #
##########################################################################
CREATE TABLE Sbr_CurrentSessions
  (
    #-------------------------------------------------------------------
    SYSTEM CORE FIELDS
    #-------------------------------------------------------------------
    Sbr_UniqueSessionId     BINARY(16)
                            NOT NULL /*UNIQUE*/,  *is* "UNIQUE", but dont
declare it so (MySQL bug)
    Sbr_CreationTime        TIMESTAMP
                            NOT NULL DEFAULT 0,
    Sbr_ExpirationTime      TIMESTAMP
                            NOT NULL DEFAULT 0,
    Sbr_Ipv4Address         INT UNSIGNED
                            DEFAULT NULL,
    Sbr_IpPoolOrdinal       SMALLINT UNSIGNED
                            DEFAULT NULL,
    Sbr_NasName             VARCHAR(24) CHARSET utf8 COLLATE utf8_general_ci
                            NOT NULL,
    Sbr_SessionState        TINYINT UNSIGNED
                            NOT NULL DEFAULT 0,
    Sbr_UserConcurrencyId   VARCHAR(84) CHARSET utf8 COLLATE utf8_general_ci
                            DEFAULT NULL,                           
    Sbr_MobileIpType        TINYINT UNSIGNED
                DEFAULT 0,
Sbr_3gpp2ReqType        INT UNSIGNED
                            DEFAULT 0,
    Sbr_WimaxClientType     TINYINT UNSIGNED
                            NOT NULL DEFAULT 0,
    Sbr_WimaxAcctFlows      VARBINARY(4095)
                            DEFAULT NULL,
   Sbr_3gpp2HomeAgentAddr   INT UNSIGNED
                            DEFAULT NULL,

The datatypes and sizes for System Core fields are specified Table 24. 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.

Table 24: System Core Fields and Specifications

Name

Description

SQL Datatype and Size

Sbr_UniqueSessionId

Internally generated identifier unique within the scope of the CST. The value is generated by a proprietary algorithm. The field acts at the Primary Key for the CST.

BINARY(16).

Fixed.

Sbr_CreationTime

The time at which this session was created.

TIMESTAMP.

Fixed.

Sbr_ExpirationTime

The time at which this session expires. The value may be updated during operation, for example, by session keepalive messages.

TIMESTAMP.

Fixed.

Sbr_Ipv4Address

The IPv4 address associated with this session (if any). Compare the RADIUS attribute Framed-IP-Address.

INT UNSIGNED.

Fixed (interpreted as IPv4 address).

Sbr_IpPoolOrdinal

Internal implementation artifact, used by Steel-Belted Radius Carrier SSR IPv4 address pools.

SMALLINT UNSIGNED.

Fixed (determined by IpPools table).

Sbr_NasName

NAS name as assigned by Steel-Belted Radius Carrier, using (in preferential order):

  1. RADIUS attribute NAS-IP-Address (or NAS-IPv6-Address, if available)
  2. RADIUS attribute NAS-Identifier
  3. Actual IPv4 (or IPv6, if available) address from which the TCP/IP packet was sent.

VARCHAR(24) utf8.

Customizable type and size.

Sbr_SessionState

Internal implementation artifact, used to manage status of sessions.

TINYINT UNSIGNED.

Fixed.

Sbr_UserConcurrencyID

Internal implementation artifact (username concatenated with integer), used by Steel-Belted Radius Carrier SSR to manage ‘user concurrency’ feature.

VARCHAR(32) utf8.

Customizable type and size, but must be the same type and size as the Id field in the Sbr_User Concurrency table.

System Feature Fields

One or more of the System Feature fields listed in Table 25 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:

DEFAULT NULL,
    #-------------------------------------------------------------------
    SYSTEM FEATURE FIELDS
    #-------------------------------------------------------------------
Sbr_AcctAutoStop        VARBINARY(1023)
                           DEFAULT NULL,
Sbr_SessionTimeout      INT UNSIGNED
                           DEFAULT NULL,
Sbr_ClassAttribute      VARBINARY(1024)
                           DEFAULT NULL,

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

Table 25: System Feature Fields and Specifications

Name

Description

SQL Datatype & Size

Sbr_AcctAutoStop

"Account Auto Stop" feature.

BINARY(1023).

Fixed.

Sbr_SessionTimeout

"Session Timeout on Missed Account Stop" feature. RADIUS attribute Session-Timeout.

INT UNSIGNED.

Fixed.

Sbr_ClassAttribute

"Use Single Class Attribute" feature.

VARBINARY(1024).

Customizable type and size.

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:

#-------------------------------------------------------------------
    SYSTEM OPTIONAL FIELDS
    #-------------------------------------------------------------------
    Sbr_UserName            VARCHAR(24) CHARSET utf8 COLLATE utf8_general_ci
                            DEFAULT NULL,
    Sbr_AcctSessionId       VARCHAR(24) CHARSET utf8 COLLATE utf8_general_ci
                            DEFAULT NULL,
   Sbr_TransactionId       BINARY(12)
   DEFAULT NULL,
   Sbr_NasPortType         INT UNSIGNED
                           DEFAULT NULL,
   Sbr_NasPort             INT UNSIGNED
   DEFAULT NULL,
   Sbr_CallingStationId    VARCHAR(24) CHARSET utf8 COLLATE utf8_general_ci
  DEFAULT NULL,
   Sbr_CalledStationId     VARCHAR(24) CHARSET utf8 COLLATE utf8_general_ci
    DEFAULT NULL,
   Sbr_MobileCorrelationId VARCHAR(32) CHARSET utf8 COLLATE utf8_general_ci
DEFAULT NULL,

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

Table 26: System Optional Fields and Specifications

Name

Description

SQL Datatype & Size

Sbr_UserName

RADIUS attribute User-Name (as presented by Steel-Belted Radius Carrier).

VARCHAR(24) utf8.

Customizable type and size.

Sbr_TransactionId

Internal, proprietary implementation artifact.

BINARY(12).

Fixed.

Sbr_NasPortType

RADIUS attribute NAS-Port-Type.

INT UNSIGNED.

Fixed.

Sbr_NasPort

RADIUS attribute NAS-Port.

INT UNSIGNED.

Fixed.

Sbr_CallingStationId

RADIUS attribute Calling-Station-Id.

VARCHAR(24) utf8.

Customizable type and size.

Sbr_CalledStationId

RADIUS attribute Called-Station-Id.

VARCHAR(24) uft8.

Customizable type and size.

Sbr_AcctSessionId

RADIUS attribute Acct-Session-Id. This attribute is enabled by default.*

VARCHAR(24) utf8.

Customizable type and size.

Sbr_MobileCorrelationId

RADIUS attribute Mobile-Session-Id.

VARCHAR(24) uft8.

Customizable type and size.

* 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

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:

ADMIN RADATTR FIELDS
    #-------------------------------------------------------------------
    WimaxSessionId          VARBINARY(32)
                            DEFAULT NULL,
    AcctMultiSessionId      VARCHAR(32) CHARSET utf8 COLLATE utf8_general_ci
                            DEFAULT NULL,
    FunkOuterUserName       VARCHAR(84) CHARSET utf8 COLLATE utf8_general_ci
                            DEFAULT NULL,
    #RadAttrField1          INT UNSIGNED
                          DEFAULT NULL,
    #RadAttrField2          VARCHAR(24) CHARSET utf8 COLLATE utf8_general_ci
                          DEFAULT NULL,
    #RadAttrField3          VARBINARY(32)
                          DEFAULT NULL,
#-------------------------------------------------------------------

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

Table 27: RadAttr Fields and Specifications

Name

Description

SQL Datatype & Size

WimaxSessionId

Unique WiMAX session ID

VARBINARY(32)

Null

AcctMultiSessionId

Unique Accounting Multiple Session ID

VARCHAR(32) CHARSET utf8 COLLATE utf8_general_ci

Null

FunkOuterUserName

Unique outer authentication username

VARCHAR(84) CHARSET utf8 COLLATE utf8_general_ci

Null

#RadAttrField1

INT UNSIGNED

Null

#RadAttrField2

VARCHAR(24) CHARSET utf8 COLLATE utf8_general_ci

Null

#RadAttrField3

VARBINARY(32)

Null

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.

Caution: You must correctly declare the CST schema in CurrentSessions.sql using the MySQL implementation of SQL, or the table may not work correctly. Always check CST modifications in a test environment before putting them into production use.

 

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:

    ADMIN RADATTR FIELDS
    #-------------------------------------------------------------------
    WimaxSessionId          VARBINARY(32)
    DEFAULT NULL,
    .... 
    threegppImsi VARCHAR(24) CHARSET utf8 COLLATE utf8_general_ci
    DEFAULT NULL,
    threegppGgsnAddressINT UNSIGNED
    DEFAULT NULL,

     

  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:

    [AcctRequest]
    ;===========================================================================
    threegppImsi=3GPP-IMSI
    threegppGgsnAddress=3GPP-GGSN-Address
  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.

Note: Be particularly careful with a RadAttr fields of type TIMESTAMP. If one is in the CST schema but you fail to declare the field type in sessionTable.ini, then no sessions are created in the CST. Every purported CST record that Steel-Belted Radius Carrier SSR presents to NDB has a NULL value in the declared TIMESTAMP field. Because TIMESTAMP fields must be non-NULL unless they are explicitly declared as TIMESTAMP NULL, NDB refuses the request.

We recommend that every RadAttr TIMESTAMP field always be declared as TIMESTAMP NULL because you can rarely guarantee that the required RADIUS attribute will always be present.

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

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:

RadAttrFieldName = Radius-Attribute-Name@#

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:

RadAttrFieldName = Radius-Attribute-Name@N

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:

RadAttrFieldName = Radius-Attribute-Name@^

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:

RadAttrFieldName = Radius-Attribute-Name@$

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.

Note: The RadAttrFieldName field must be declared in the CST schema to be of [VAR]CHAR type. If the RadAttrFieldName field is of a type other than [VAR]CHAR, Steel-Belted Radius Carrier reports an error.

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:

RadAttrFieldName = Radius-Attribute-Name@"…"

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.

Note: The RadAttrFieldName field must be declared in the CST schema to be of [VAR]BINARY type. If the RadAttrFieldName field is of a type other than [VAR]BINARY, Steel-Belted Radius Carrier reports an error.

Syntax:

RadAttrFieldName = Radius-Attribute-Name@*

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

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:

    #-------------------------------------------------------------------
    ADMIN PRIVATE FIELDS
    #-------------------------------------------------------------------
   #PrivateField1           INT UNSIGNED
                          DEFAULT NULL,
   #PrivateField2           VARCHAR(24) CHARSET utf8 COLLATE utf8_general_ci
                          DEFAULT NULL,
   #PrivateField3           BINARY(32)
                          DEFAULT NULL,

System Keys and Indexes

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

Caution: We strongly recommend that you not edit this section of the file. If any required key is not present in the CST, functions that depend upon it fail.

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

#-------------------------------------------------------------------
    SYSTEM KEYS/INDEXES
#-------------------------------------------------------------------
PRIMARY KEY USING HASH                   (Sbr_UniqueSessionId),
INDEX Sbr_NasName_Idx         (Sbr_NasName),
INDEX Sbr_ExpirationTime_Idx  (Sbr_ExpirationTime),
INDEX AcctMultiSessionId_Idx  (AcctMultiSessionId),
INDEX Sbr_MobileCorrelationId_Idx (Sbr_MobileCorrelationId),
INDEX Sbr_AcctSessionId_Idx (Sbr_AcctSessionId),
INDEX Sbr_UserName_Idx (Sbr_UserName),
INDEX Sbr_CallingStationId_Idx (Sbr_CallingStationId),
INDEX Sbr_CalledStationId_Idx (Sbr_CalledStationId),
INDEX Sbr_Ipv4Address_Idx (Sbr_Ipv4Address),
INDEX Sbr_TransactionId_Idx (Sbr_TransactionId )
      

Admin Keys and Indexes

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

Caution: We strongly recommend that you not edit this section of the file; it contains system-generated entries. If any required key is not present in the CST, functions that depend upon it fail.

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

#-------------------------------------------------------------------
    ADMIN KEYS/INDEXES
    #-------------------------------------------------------------------
   #,
    INDEX Some_Idx USING HASH (What, Ever)
  )
  ENGINE = ndbcluster  NOTE: CreateDB.sh fiddles with this line!
  ;
#=======================================================================
Copyright (C) 2007-9, Juniper Networks, Inc.  All rights reserved.

Modified: 2017-03-07