rlm_attr_filter

Synopsis

The attr_filter module filters attributes in a packet. It can delete attributes or permit them to have only certain values. The format of the file is the same as the users file. See the files module for a description of the users file format.

The filters that are applied depend on which operators are used. The format is the same as the users file, e.g., Attribute-Name Operator Value. The Attribute-Name can be any RADIUS attribute. The Operator is given in the table below. The Value is a string that is valid for Attribute-Name.

Default configuration

Processing Sections

authorize

When listed in the authorize section, the attr_filter module filters the request packet.

accounting

When listed in the accounting section, the attr_filter module filters the reply packet.

post-auth

When listed in the post-auth section, the attr_filter module filters the reply packet.

preacct

When listed in the preacct section, the attr_filter module filters the request packet.

pre-proxy

When listed in the pre-proxy section, the attr_filter module filters the proxy packet.

post-proxy

When listed in the post-proxy section, the attr_filter module filters the proxy_reply packet.

recv-coa

When listed in the recv-coa section, the attr_filter module filters the request packet.

send-coa

When listed in the send-coa section, the attr_filter module filters the reply packet.

Return Codes: The module returns the same set of return codes for all of the processing sections.
: noop The key attribute was not found, or it was found but no filter matched.
: fail The key could not be dynamically expanded, or there was an error processing a filter.
: updated The packet was successfully filtered.

Expansions

None.

Table 1. Operators for filtering
`Operator`	Meaning
`=*`	allow this attribute, no matter what the Value
`==`	allow attributes with only Value
`<`	allow attributes that have value less than Value
`<=`	allow attributes that have value less than or equal to Value
`>`	allow attributes that have value greater than Value
`>=`	allow attributes that have value greater than or equal to Value

Any attribute that is not listed in the filter is removed. The attr_filter module does not create attributes, unlike the unlang filtering. For example, the following unlang configuration creates an Acct-Input-Gigawords attribute with value 0, if that attribute does not already exist:

Example of a filter in unlang

 update request {
	Acct-Input-Gigawords >= 0
 }

A similar attr_filter rule is the following:

Example of a filter in the attr_filter file.

 DEFAULT
	Acct-Input-Gigawords >= 0

This rule requires that existing attributes have value greater than or equal to zero. It does not create an attribute. After running the filter, the attribute still may not exist in the request.

For many situations, the unlang filtering is better. The attr_filter module is left over from very early versions of the server, when unlang did not exist.

Examples

The following are a few examples of filter rules.

Filter almost everything

 DEFAULT
 Vendor-Specific =* ANY,
 Message-Authenticator =* ANY,
 Proxy-State =* ANY

The filter allows any Vendor-Specific attribute, including all VSAs. It allows Message-Authenticator and Proxy-State with any Value. All other attributes are deleted.

Note that the special value ANY serves as a place-holder, which allows any value for the attribute.

Allow only short sessions

 DEFAULT
	Session-Timeout < 86400

This filter allows Session-Timeout to be no more than one day (86400 seconds).

The filter rules serve two purposes. First, to enforce the RFC requirements on packet contents. And second, to serve as a "double check" on returned values.

The filter rules are editable because some vendors choose to ignore the RFC requirements. If the rules were hard-coded into the server source code, then they could not be changed, and FreeRADIUS would be incompatible with equipment from that vendor.

Allowing the rules to be edited means that the default rules can be applied in normal situations, but they can still be changed for unusual circumstances.

The second purpose of the rules is to act as a "double check" on the returned values. For example, a site may allow junior administrators to edit rules in an SQL database. These junior administrators may make mistakes and give users too much access. The attr_filter rules can then apply the over-all limits on user access. The filter rules can be set once by a senior administrator and then rarely edited.

Directives

filename

Syntax: filename = filename
Default: none
Description: The name of the file containing the filter rules. The format of the file is the same as the users file. See the files module for a description of its syntax.

key

Syntax: key = string
Default: %{User-Name}
Description: The key to use for each entry in the file. The key is dynamically expanded at run-time. See the files module for a description of how the key works.

Default Instances

The server ships with a number of different instantiations of the module. Each instance is intended to filter one specific kind of packet. These instances are listed below.

access_challenge

Defaults: key = %{User-Name} filename = ${modconfdir}/${.:name}/filter/access_challenge
Description: Enforces RFC requirements on the contents of Access-Challenge packets. The RFCs require that Access-Challenge packets contain only a limited set of attributes. The default rules in the access_challenge file enforce that limitation.

access_reject

Defaults: key = %{User-Name} filename = ${modconfdir}/${.:name}/filter/access_reject
Description: Enforces RFC requirements on the contents of Access-Reject packets. The RFCs require that Access-Challenge packets contain only a limited set of attributes. The default rules in the access_reject file enforce that limitation.

accounting_response

Defaults: key = %{User-Name} filename = ${modconfdir}/${.:name}/filter/accounting_response
Description: Enforces RFC requirements on the contents of Accounting-Response packets. This means that the Accounting-Response packet should be empty, i.e., it should contain no attributes.

pre-proxy

Defaults: key = %{Realm} filename = ${modconfdir}/${.:name}/filter/pre-proxy
Description: Enforces RFC requirements on the contents of Access-Request packets proxied to a home server.

post-proxy

Defaults: key = %{Realm} filename = ${modconfdir}/${.:name}/filter/post-proxy
Description: Enforces RFC requirements on the contents of packets received from a home server.
: The filter is applied to all packets, including Access-Accept, Access-Challenge, and Access-Reject.