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

filter.ini File

The filter.ini file lets you set up rules for filtering attributes and structured attributes into and out of RADIUS packets.

Note: Use the Web GUI to maintain settings in the filter.ini file. Do not edit the filter.ini file manually.

Filter Rules

Each filter in the filter.ini file consists of the filter name in square brackets ([ name ]) followed by the rules for that filter.

Each rule takes one of the following three forms:

keyword attribute value
keyword attribute
keyword

Table 67 lists valid syntax combinations.

Table 67: Filter Syntax

filter.ini Rule Syntax

Function

ALLOW

This keyword by itself specifies that all attributes, regardless of value, are to be allowed in the packet.

ALLOW attribute

This rule specifies that this attribute is allowed in the packet, regardless of its value.

ALLOW attribute value

The rule lists a specific attribute/value pair to allow in the packet.

ALLOW_UNKNOWN vendorID

This rule specifies that all attributes, regardless of whether they are included in the dictionary of the sending NAS, are included when proxying the message to the target (outbound filters) or before returning the proxy response (inbound filters).

Optionally, a Vendor Id may accompany the directive. When used with a global EXCLUDE_UNKNOWN, this rule overrides the exclusion of attributes from the specified vendor ID.

EXCLUDE

The keyword by itself specifies that all attributes, regardless of value, are to be excluded from the packet.

EXCLUDE is the default action for a filter.

EXCLUDE attribute

The rule specifies that this attribute is excluded from the packet, regardless of its value.

EXCLUDE attribute value

The rule specifies an attribute/value pair to exclude from the packet.

EXCLUDE_UNKNOWN vendorID

This rule specifies that all attributes that are not included in the dictionary of the sending NAS are deleted before proxying the message to the target (outbound filters) or before returning the proxy response (inbound filters).

Optionally, a Vendor Id may accompany the directive. If included, only attributes from the specified vendor are excluded.

ADD attribute value

The rule lists a specific attribute/value pair to add to the packet. The attribute is added after all other rules are processed.

REPLACE attr1 WITH attr2

The rule specifies that any occurrence of attr1 is replaced by attr2, which retains attr1’s value.

REPLACE attr1 WITH attr2 v2

The rule specifies that any occurrence of attr1 (regardless of value) is replaced by attr2 whose value is set to v2.

REPLACE attr1 v1 WITH attr2

The rule specifies that any occurrence of attr1 whose value is v1 is replaced by attr2 (which keeps value v1).

REPLACE attr1 v1 WITH attr2 v2

The rule specifies that any occurrence of attr1 whose value is v1 is replaced by attr2 having a value v2.

Note: You cannot replace a subattribute with a parent attribute, or vice versa.

An attribute is ADDed to a packet only if it is legal to do so. Some attributes can appear only once in a RADIUS packet; others can appear multiple times. If an attribute that is the subject of an ADD rule is already present in the packet (after processing ALLOW and EXCLUDE rules) and the attribute can only appear once, the ADD rule is not processed and the second instance of the attribute is not added.

The Steel-Belted Radius Carrier dictionary file radius.dct provides string aliases for certain integer values defined in the RADIUS standard. You can use these strings in attribute filter rules.

Note: Filter rules provide you with tremendous flexibility. However, Steel-Belted Radius Carrier does not prevent you from creating an invalid RADIUS packet. Some attributes are not appropriate for certain types of requests. For example, adding a pooled Framed-Ip-Address attribute to an accounting request can cause a loss of available IP addresses.

Order of Filter Rules

The order of rules is important. General default rules that take no parameters, such as ALLOW (allow all attributes unless otherwise specified) or EXCLUDE (exclude all attributes unless otherwise specified) must appear as the first rule in the filter. Later rules supersede earlier rules; the last applicable rule “wins.” ADD and REPLACE rules are applied after the ALLOW and EXCLUDE rules.

More specific rules with more parameters (ADD attribute value) act as exceptions to less specific rules with fewer parameters (ALLOW attribute, EXCLUDE). For example, you might want to ALLOW a certain attribute and EXCLUDE one or more specific values for that attribute. Or you might EXCLUDE all attributes, ALLOW specific attributes, and ADD specific attribute/value pairs.

You can use two basic approaches to designing a filter:

  • Start the rule list with a default EXCLUDE rule (no parameters) and add ALLOW rules for any attributes or attribute/value pairs that you want to insert into the packet. ADD and REPLACE rules may be used.
  • Start the rule list with a default ALLOW rule (no parameters) and add EXCLUDE rules for any attributes or attribute/value pairs that you want to remove from the packet. ADD and REPLACE rules may be used.

The default action for filter.ini is EXCLUDE. If a filter does not contain any rules, the filter removes all attributes from a packet when the filter is applied.

Examples

Here are a few examples of how to use the filter rules.

Allow all attributes except any undefined attributes (attributes with no .dct definition):

[exclude_all_unknown]
ALLOW
EXCLUDE_UNKNOWN

Allow all attributes except undefined attributes for vendor 12345:

[exclude_specific_unknown]
ALLOW
EXCLUDE_UNKNOWN 12345

Allow all known attributes, disallow undefined attributes, but allow undefined attributes for vendor 12345:

[exclude_all_unknown_except_specific]
ALLOW
EXCLUDE_UNKNOWN
ALLOW_UNKNOWN 12345

Values in Filter Rules

The value of an attribute is interpreted based on the type of the attribute in its attribute dictionary. Table 68 lists the meaning of each attribute type.

Table 68: Filter Rule Values

Attribute Type

Function

hexadecimal

A hexadecimal value is specified as a string. Special characters may be included using escape codes.

int1, int4, integer

1- or 4-byte unsigned decimal number (integer is equivalent to int4).

Note: The Steel-Belted Radius Carrier dictionary file radius.dct provides string aliases for certain integer values defined in the RADIUS standard. You can use these strings in attribute filter rules.

ipaddr, ipaddr-pool

An IP address in dotted notation; for example:

EXCLUDE NAS-IP-Address 127.0.0.1

string

String attribute (includes null terminator). A string is specified as text. The text may be enclosed in double-quotes ("). The text is interpreted as a regular expression. Backslash (\) is the escape character. Escape codes are interpreted as:

Code Meaning

\a 7

\b 8

\f 12

\n 10

\r 13

\t 9

\v 11

\nnnnnn is a decimal value between 0 and 255

\xnnnn is a hexadecimal value between 00 and FF

\c c is a single character, interpreted literally

Literal backslashes (\) within a string and double-quotes (“) within quoted strings are prefixed with an escape character. For example:

ADD Reply-Message Session limit is one hour

ADD Reply-Message "Session limit is one hour"

ADD Reply-Message "Your username is \"George\""

time

A time value is specified with a string indicating date and time:

yyyy/mm/dd hh:mm:ss

The date portion is mandatory; the time portion may be specified to whatever degree of precision is required, or may be omitted entirely. For example:

2006/4/3 14:00:00

and

2006/4/3 14

both refer to April 3, 2006 at 2:00 p.m.

For example:

ADD Ascend-PW-Expiration 2006/4/3

Referencing Attribute Filters

Steel-Belted Radius Carrier attribute filtering provides flexibility in packet processing. You can use the same filter for all packets in all realms. You can apply filtering to some realms, and not others. (To disable filtering for a realm, omit filtering parameters from the *.pro, *.dir, peapauth.aut, or ttlsauth.aut file.) Filtering is often used only for packets that are routed out to realms (the FilterOut parameter).

To reference the filtering rules defined in the filter.ini file in proxy or directed realm configurations, you must use the FilterOut and FilterIn parameters in the [Auth] and [Acct] sections of a RADIUS realm configuration file.

The full syntax used is:

[Auth]
FilterIn=name1
FilterOut=name2
[Auth]
FilterIn=name3
FilterOut=name4

where name1, name2, and so forth provide the names of filters, sections in the filter.ini file called [ name1 ], [ name2 ], and so forth. The name values in this syntax are completely independent of each other. They may be all the same, all different, or some combination of same and different.

When using the FilterIn and FilterOut parameters in the [Auth] and [Acct] sections, be sure to use the filter name without the square brackets (“name”, not “[name]”).

Note: If a [name] section is not found in the filter.ini file, it is equivalent to assigning a filter that EXCLUDEs all attributes. In other words, assigning a filter name that cannot be found causes the final packet to be emptied of all attributes.

Note: Do not allocate IP addresses from Steel-Belted Radius Carrier IP address pools in accounting filters. These addresses are allocated but never released.

Modified: 2018-01-11