This chapter describes how to configure the logging modules available with Oracle Communications Billing and Revenue Management (BRM) RADIUS Manager.
Caution:
Only administrators with advanced RADIUS skills should attempt to implement custom configurations.Before reading this chapter you should be familiar with:
RADIUS Manager provides two logging modules. The most basic logging module is mod_logging, used to log RADIUS requests to text files. The module mod_cdr enables you to create custom CDR log files.
Use the mod_logging module to log RADIUS requests to text files. This is the simplest logging module available with RADIUS Manager. There is less overhead using this module than with custom log files. The resulting log files are human readable so that they can be used for debugging purposes.This module allows you to mask attributes, such as user name and password, for security reasons.
All RADIUS request types are accepted by this module. Once requests are processed they are passed to the next module in the module chain. Requests are logged to the log files you specify.
The mod_logging module can be configured to log requests of any type. This is a support module, so no response is sent back to the client NAS.
Each element of the incoming request is checked against the corresponding element in mod_logging block of the RADIUS configuration file BRM_home/apps/radius/config, where BRM_home is the directory in which BRM components are installed.
If a match is found, the request is logged according to the configuration parameters.
Searching continues with the next configuration element in the request. This permits a single request to be logged to multiple destinations.
Requests are logged to the specified files using a fixed, text-based format which includes the date, time, and source of the request.
No global ($CONFIG block) configurations are supported. Configure each instance of the mod_logging module in the $MODULES section of the RADIUS configuration file (BRM_home/apps/radius/config.) The mandatory type entry is mod_logging.
Use the check element to search for matching elements. The check element matches attribute-value pairs in the request. If the value pair in the request matches the criteria set in the check element, the request is processed. If any attribute in the check element is not matched in the request, then the check fails. After the check fails, the request is passed on to the next module in the chain.
The mask entry allows you to mask out attributes. Masking allows you block out attributes for security reasons. In general, it is a good idea to block out the user name and password as well as any other sensitive user information. Any attribute in the data dictionary can be masked out. Masked attributes are shown as "XXXXX" in the log file.
Use the dest element to specify the destination file where RADIUS requests are to be logged. If the directory you specify doesn't exist, it is created. Any instance of %n in this value are expanded with the NAS identifier. This uses the standard algorithm:
If the NAS-Identifier exists, use it;
Otherwise, if the NAS-IP-Address exists, use it;
Otherwise, use the address of the source of the request.
Note:
No options are available for this module.The following example logs Accounting-Stop requests to a detail file.
# logging configuration to log all Accounting-Stop requests to a detail file
logging_stop {
type=mod_logging
dest="/opt/portal//radius/%n/detail"example"
check {
Acct-Status-Type=Stop
Pseudo-Request-Type=Accounting-Request
}
}
# logging configuration to log all requests to a debugging file
# mask out the User-Password attribute (it shows as "XXXX")
logging_all {
type=mod_logging
dest="/tmp/logs/%n"
mask {
User-Password
}
}
In a scenario where the accounting request from a particular terminal server should just be logged and not processed, a mod_null module worker class should be added to the chain to perform the reply action. The following example shows how to configure the module to reply.
## Just want to log the accounting record to file
## Need to add a mod_null after mod_logging to reply to the NAS
just_log {
type=mod_logging
dest="/tmp/logs/%n"
check {
NAS-Identifier = "TESTING NAS"
}
}
## Note that the check attribute is identical to [just_log] module worker class
just_log_reply {
type=mod_null
check {
NAS-Identifier = "TESTING NAS"
}
action = ack
}
Use the module mod_cdr to create custom call detail record (CDR) files for logging RADIUS events. RADIUS events such as access and accounting requests can be logged in a record oriented, field separated format. The format, name, and location of the log file, as well as any rotation schemes, can all be customized. This allows you to design log files which may be processed later using scripts, cron jobs, or other applications such as the UE Loader.
In addition, this module enables you to:
Send RADIUS messages to different CDR log files.
Use naming conventions and rotation schemes for log files across RADIUS invocations.
Configure delimiters.
Use string literals.
Include multiple instances of mod_cdr to handle different scenarios and types of RADIUS messages.
Use dynamic reconfiguration.
Limitations of mod_cdr:
Does not create a response to send to a client NAS.
Does not support masking of attributes.
Custom log files generated by mod_cdr are useful in many different scenarios. The module, mod_cdr, is particularly useful in cases where log files needs to be processed at a later time. For example:
Recovering usage information. If BRM goes down while RADIUS is sending data, then the mod_cdr module lets you continue to log incoming requests. Later when the system is back up, this information can be imported into BRM using an application such as UE Loader using the mod_cdr generated log file.
Moving usage information. If a customer wants to move usage data from one BRM installation to another and the usage information from the original site came through a RADIUS system using mod_cdr, then the usage information can be imported using the log file generated by mod_cdr.
The mod_cdr module offers you great flexibility in configuring log files. Because of this, it's important to consider your overall system needs before beginning the configuration process. Use the following checklist when evaluating your unique system requirements.
Destination of the Log File
Where do I want the log files written?
Will other applications, scripts, or cron jobs need to read the log files? Does this effect where the log files are archived?
How Log Files Will Be Used
Who or what applications are consumers of the log files?
Do I need to match the configuration of my log files with another application such as UE Loader?
What is the standard operating procedure for moving mod_cdr output to any consumer applications?
Will a consumer application need to read the _CURRENT file while it's being written?
Number and Size of Log Files
Do I want to set a maximum number of records per log file?
Do any consumer applications I plan to use have a limitation on the numbers of records per log file and does this match with my configuration for mod_cdr?
Rotation Schemes
Do I want to periodically rotate log files?
Do I want to implement a time-based rotation scheme (such as hours, days, months)?
How does the time-based rotation scheme I've chosen impact the size and number of log files generated?
If I choose to rotate by a maximum number of records, do I want to continue incrementing to a large number or begin overwriting at a specified number of records?
Do I want to separate records by NAS?
Do I want to filter RADIUS messages by type (such as Stop and Start requests)?
Do I need to log different types of RADIUS messages to different files?
Use these instructions to create a custom configuration of mod_cdr in the RADIUS configuration file. The mandatory module type setting is mod_cdr.
If you wish to log only specific types of RADIUS messages, set the check type field. This example shows the format of the check entry.
check {
Acct-Status-Type=Stop
Pseudo-Request-Type=Accounting-Request
}
The attribute order defines how attributes appear in the resulting log files. List the RADIUS attributes in the order they should be logged. If an entry in the attribute order list is not a RADIUS attribute, then a warning message is logged to the appropriate log file.
attribute-order {
# attribute-order {
User-Name
User-Password
"This is an example of a string literal"
NAS-Identifier
NAS-Port
Pseudo-Request-Source
Pseudo-Request-Type
}
Delimiter values separate fields, records, and string literals. Only single character delimiters are supported. If the log files are to be processed by another application, such as UE Loader, then these must match the special delimiters required by that application.
Note:
Take care when entering special characters such as the end of line. Precede the end of line with a "\".field-delimiter=" " record-delimiter="\n"
Any entries that are not in the RADIUS dictionary are treated as string literals. If you wish to use a string literal which is the same as a dictionary entry, enclose the attribute in escape character delimited quotes. If you include string literals, then define the start and end delimiters for string literals.
string-literal-start-delimiter="[" string-literal-end-delimiter="]"
If you wish to add special characters for blank fields then, mod_cdr will replace the blank field with a blank-field entry. If not specified, then the blank-field is left empty.
blank-field="-"
If you wish to include special characters set insert-escape-character entry. This field can be set to true or false. When set to true, fields with a special delimiter character in them get the escape character "\" inserted in front of them. The default is false.
insert-escape-char=true
Use the password-cleartext field to define whether you want password fields to be encoded or not. If set to true, then password fields are put in the log file as a clear text password. If set to false, then the password field is encoded. The default is true.
password-cleartext=true
You can pre-append the RADIUS request type by setting the prepend-type entry to true. This is useful when you need to analyze or sort log files by types of RADIUS request.
This field can be set to true or false and maps two types of RADIUS packets, Pseudo_Request and Account_Status_Type into one easy to read field. The default is false. If set to true, the record will have the RADIUS type appended in front of the record. Values can include:
ACCESS_REQUEST
START_ACCOUNTING_REQUEST
STOP_ACCOUNTING_REQUEST
ACCOUNTING_ON_REQUEST
ACCOUNTING_OFF_REQUEST
ACCOUNTING_REQUEST_OTHER, OTHER
In the rotate-log block set the entries for max-record and max-increment values.
The max-record field defines the maximum number of records to be included in a log file.
The max-increment field defines the maximum number of records defined for the numeric counter (%N value). When the number of log files (%N value) exceeds the max-increment value, then the counter starts back at 1.
Note:
If either max-record or max-increment is set to -1, then the feature is disabled.
rotate-log {
max-record=100000
max-increment-value=10
}
The dest entry is used to define the file name and optionally the path name of the destination file. The dest entry is highly configurable and is core to the operation of mod_cdr. In it's simplest configuration, the dest entry requires only the file name of the destination file. However, by combining the options listed below, this entry can be used to define a full path and filename which specifies the numeric counter, the NAS option, and the rotation scheme for log files.
The default for the dest field is:
dest=logs/cdr_log.%N
This default setting archives log files to the log directory in a file named cdr_log. A numeric counter indicates the number of the log file. The resulting file will be named call_cdr.log.1. On the next rotation, the file will be named call_cdr.log.2 and so on.
When customizing the dest field, the only required entry is the file name for the destination file.
dest=ThisIsAFileName
The full path name can also be added.
dest=logdirectory/ThisIsAFileName
A numeric counter can be added to the destination file name. The %N option is a numeric counter designating the log file rotation number. The %N option may appear anywhere within the dest field.
Note:
If you add the %N numeric counter, then you should consider using the max-increment field to set an upper limit on the number of log files generated.dest=logdirectory/ThisIsAFileName%N
If messages from different NAS need to be recorded in separate log files then use the %n option. When the %n option is used the NAS identifier gets substituted as part of the destination file name.
dest=logdirectory/ThisIsAFileName%N%n
Log files may be rotated based on time-based rotation schemes.Table 7-1 describes the options available.
Table 7-1 Options for Time-Based Rotation Schemes
| Options | Description |
|---|---|
|
%a |
Abbreviated weekday name |
|
%A |
Full weekday name |
|
%b |
Abbreviated month name |
|
%B |
Full month name |
|
%c |
Local date and time representation |
|
%d |
Day of the month |
|
%H |
Hour - 24 hours clock (00-23) |
|
%I |
Hour - 12 hour clock (01-12) |
|
%j |
Day of the year (001-366) |
|
%m |
Month (01-12) |
|
%M |
Minute (00-59) |
|
%p |
Local equivalent of AM or PM |
|
%S |
Second (00-59) |
|
%U |
Week number of the year (00-51) Sunday as first day of week |
|
%w |
Weekday (0-6) Sunday is 0 |
|
%W |
Week number of the year (00-51) Sunday as first day of week |
|
%x |
Local date presentation |
|
%X |
Local time presentation |
|
%y |
Year without century (00-99) |
|
%Y |
Year with century |
By using the time based rotation options listed above, you can configure mod_cdr to rotate log files according to prescribed time periods such minutes, hours, days, months, etc.
In the example below the log files will be stored in the /var/portal/7.5/radius directory. The destination log file name includes the NAS option, a numeric counter, and the log files will be rotated each day of the year (using the %j option.)
dest="/var/portal/7.5/radius/cdr/call_cdr_%n.%j.%N.log"
When setting up rotation schemes use these general guidelines.
If the dest string does not have a %N option or time stamp pattern, then the log file never gets rotated.
If the dest string does not have %N option but does includes a time stamp, then the file is rotated when the time pattern is changed.
If the dest string has a %N option, but does not have a time stamp, then the file is rotated when the maximum number of records (max_record) is exceeded.
If the dest string has both a %N option and a time stamp, then the file gets rotated when the maximum number of records (max_record) is reached or when the time pattern changes, whichever changes first.
The current file is the log file which is currently being written. It is designated with a special suffix _CURRENT.
<%N>.<Module_Name>._CURRENT
<%N> is the current number of rotation file.
<Module_Name> is the module name.
__CURRENT indicates that this is the current log file.
After the current log file is complete, it is renamed and archived. A new log file is created and given the special _CURRENT suffix. Once the log file has been renamed and archived, you can copy or move the file to another location or process it. It's not recommended that you move the _CURRENT file unless you are sure that the file won't grow anymore. If the __CURRENT CDR file does not exist, then mod_cdr won't be able to recreate previously set values such as %N across RADIUS server invocations.
Note:
Changing the dest pattern during a RADIUS invocation may create an orphan __CURRENT file. If this happens, be sure to clear the orphan __CURRENT file.After the current (_CURRENT) file has been rotated out, it becomes an archive file. It is moved into the cdr_archive directory and renamed using a special time-based suffix.
For example:
dest="/var/someDir/%n/CDR.%d"
If the value of %d (designating the day of the month) is 05, and the NAS is 150.151.152.153, then, before mod_cdr writes to a file, it checks to see whether a file with this name already exists:
/var/someDir/150.151.152.153/cdr_archive/cdr.05.Jan-05-1999.10.05
If an archive file by this name does not exist, then mod_cdr creates the file and writes the data to this file.
If an archive file by this name already exists, then the existing archive file is copied to the backup directory (cdr_backup) and renamed. The existing archive file is then overwritten.
If a backup archive file by this name already exists in the cdr_backup directory, then that backup file is overwritten.