Section 3.31. <Handler attribute=value,attribute=value, ....>

3.31. <Handler attribute=value,attribute=value, ....>

This begins a <Handler> clause. When using the <Handler> clause, all requests with a specific set of attributes are handled in the same way. You can configure one or more <Handler> clauses into your server, possibly with a different AuthBy authentication methods for each.

The difference between <Handler> and <Realm> is that <Handler> groups together requests based on the value of any attributes in the request, not just the user's realm as <Realm> does. That makes <Handler> clauses more powerful but they are not required as often. A common situation is that you need to distinguish between authentication methods based on the user's realm. Use <Handler> instead of <Realm> if you need to choose authentication methods based on other attribute than Realm, such as Called-Station-Id, Request-Type, or some other attribute in the incoming RADIUS request.

In <Handler checklist> the checklist expression is a list of request attributes that must all match before <Handler> is used to handle the request. The format is similar as a list of check items in a user file: a list of attribute=value pairs, separated by commas. For more information, see Section 7.1. Check items.

If you omit the expression name from the <Handler> line, the clause matches all requests.

When Radiator looks for <Handler> to match an incoming request, it searches each <Handler> clause in the order in which they appear in your configuration file. It continues searching until <Handler> is found where every check item in the expression matches the request. If any check item does not match, it continues onto the next <Handler> until all the Handlers are exhausted. If none of the <Handler> clauses match, Access-Request is rejected and Accounting-Request is accepted.

Radiator uses the following algorithm to find the <Realm> or <Handler> to handle each request:

Look for a Realm with an exact match on the realm name.
Look for a matching regular expression Realm.
Look for a <Realm DEFAULT>.
Look at each Handler in the order they appear in the configuration file until one where all the check items match the request.
Ignore the request.

It is possible to use both <Handler> and <Realm> clauses in the same configuration file but it is not recommended. Using them together may lead to complicated handler selections and behaviour.

The following example configuration uses 3 authentication methods used in different requests:

<AuthBy SQL>
This used when Called-Station-Id is 662543 and Service-Type is Framed-User.
<AuthBy DBM>
This is used when Called-Station-Id is 678771 and Realm is open.com.au.
<AuthBy RADIUS>
This is used authenticating all the requests that do not match to the previous criteria.

<Handler Called-Station-Id=662543,Service-Type=Framed-User>
      <AuthBy SQL>
            ......
      </AuthBy>
</Handler>
<Handler Called-Station-Id=678771,Realm=open.com.au>
      <AuthBy DBM>
            .....
      </AuthBy>
</Handler>
# Handles anything that was not handled above:
<Handler>
      <AuthBy RADIUS>
            .......
      </AuthBy>
</Handler>

All instances of the given attribute are checked, so it is possible to define a check that requires a request to contain multiple values. Here are 2 examples of multiple values, both of them are allowed:

# Request has attributes in a following order:
# OSC-Group-Identifier=A
# OSC-Group-Identifier=B

# Does match
<Handler OSC-Group-Identifier=B>
    ....
</Handler>

# Request has attributes in a following order:
# OSC-Group-Identifier=A
# OSC-Group-Identifier=B

# Does not match
<Handler OSC-Group-Identifier=B,OSC-Group-Identifier=C>
    ....
</Handler>

# Does match
<Handler OSC-Group-Identifier=B,OSC-Group-Identifier=A>
    ....
</Handler>

3.31.1. RewriteUsername

This is an optional parameter. It enables you to alter the username in authentication and accounting requests. For more details and examples, see Section 8. Rewriting user names.

3.31.2. RewriteFunction

This optional parameter allows you to define you own special Perl function to rewrite user names. You can define an arbitrarily complex Perl function that might call external programs, search in databases or whatever. The user name is changed to whatever is returned by this function.

If you define a RewriteFunction for a Realm or Handler, it will be used in preference to any RewriteUsername. RewriteUsername will be ignored for that Realm or Handler.

# Strip out NULs, trailing realms, translate to
# lower case and remove single quotes
RewriteFunction sub { my($a) = shift; $a =~ s/[\000]//g; $a =~
s/^([^@]+).*/$1/; $a =~ tr/[A-Z]/[a-z]/; $a =~ s/'//g; $a; }

3.31.3. AcctLogFileName

The names of the files used to log Accounting-Request messages in the standard radius accounting log format. All Accounting-Request messages will be logged to the files, regardless of their Acct-Status-Type. For more information about log file format, see Section 9.5. Accounting log file. If no AcctLogFileName is defined, accounting messages will not be logged for this realm. The default is no logging. The file name can include special formatting characters as described in Section 3.3. Special formatters, which means that, for example, using the %c specifier, you can maintain separate accounting log files for each Client. The AcctLogFileName files are always opened written and closed for each message, so you can safely rotate them at any time.

If the AuthBy module you select does no special accounting logging, you may want to enable this parameter for the Realm. Note that logging to AcctLogFileName is in addition to any recording that a specific AuthBy module might do (such as, say, AuthBy SQL). The user name that is recorded in the log file is the rewritten user name when RewriteUsername is enabled.

You can specify any number of AcctLogFileName parameters. Each one will result in a separate accounting log file. If need to modify accounting messages and log the modified result, consider using an AcctLog.

If the file name starts with a vertical bar character (‘|’) then the rest of the filename is assumed to be a program to which the output is to be piped. Otherwise the output will be appended to the named file:

# Pipe to my-log-prog
AcctLogFileName |/usr/local/bin/my-log-prog

Tip

You can change the logging format with AcctLogFileFormat:

# Log all accounting to a single log file in LogDir
AcctLogFileName %L/details

3.31.4. AcctLogFileFormat

This optional parameter is used to alter the format of the accounting log file from the standard radius format when AcctLogFileFormatHook is not defined. AcctLogFileFormat is a string containing special formatting characters. It specifies the format for each line to be printed to the accounting log file. A newline will be automatically appended. It is most useful if you use the %{attribute} style of formatting characters (to print the value of the attributes in the current packet).

AcctLogFileFormat %{Timestamp} %{Acct-Session-Id}\
%{User-Name}

3.31.5. AcctLogFileFormatHook

Specifies an optional Perl hook that will is used to alter the format of the accounting log file from the standard radius format when defined. The hook must return the formatted accounting record. A newline will be automatically appended. By default no hook is defined and AcctLogFileFormat or the default format is used. The hook parameter is the reference to the current request.

See goodies/logformat.cfg for a sample configuration file with JSON format.

Tip

Consider installing Cpanel::JSON::XS or JSON::XS for higher performance JSON encoding.

3.31.6. AccountingHandled

This parameter forces Radiator to acknowledge Accounting requests, even if the AuthBy modules for the Realm or Handler would have normally ignored the request. This is useful if you do not really want to record Accounting requests, but your NAS keeps retransmitting unless it gets an acknowledgment.

Note

All backend processing, such as SQL queries, is done first, before the reply is sent back to the NAS.

# My AuthBy SQL ignores accounting
AccountingHandled

3.31.7. AccountingAccepted

This is a flag parameter. When set, it forces Radiator to acknowledge an Accounting request when it is received, even if the AuthBy modules for the Realm or Handler would otherwise ignore or reject the request. This is useful if you want to send an acknowledge to NAS immediately. Usually this parameter is not used.

3.31.8. PreProcessingHook

This optional parameter allows you to define a Perl function that will be called during packet processing. PreProcessingHook is called for each request before per-Realm user name rewriting, before accounting log files are written, and before any PreAuthHooks. A reference to the current request is passed as the first argument, and a reference to the reply packet currently being constructed is passed as the second argument.

The hook code is compiled by Perl when Radiator starts up. Compilation errors in your hook code will be reported to the log file at start-up time. Runtime errors in your hook will also be reported to the log file when your hook executes. Multiline hooks (i.e. with trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should not use trailing comments in your hook.

PreProcessingHook can be an arbitrarily complicated Perl function, that might run external processes, consult databases, change the contents of the current request or many other things.

# Fake a new attribute into the request, so its logged in the
# accounting log file
PreProcessingHook sub { ${$_[0]}->add_attr('My-Realm', \
      'some.realm.com');}

3.31.9. PostProcessingHook

This optional parameter allows you to define a Perl function that will be called during packet processing. PostProcessingHook is called for each request after all authentication methods have been called and just before a reply is sent back to the requesting NAS. A reference to the current request is passed as the first argument, and a reference to the reply packet currently being constructed is passed as the second argument. If the processing results in no reply (for example, if the request is proxied) then PostProcessingHook is not called.

The hook code is compiled by Perl when Radiator starts up. Compilation errors in your hook code will be reported to the log file at start-up time. Runtime errors in your hook will also be reported to the log file when your hook executes. Multiline hooks (i.e. with trailing backslashes (\)) are parsed by Radiator into one long line. Therefore, you should not use trailing comments in your hook.

PostProcessingHook can be an arbitrarily complicated Perl function, that might run external processes, consult databases, change the contents of the current reply or many other things.

# Fake a new attribute into the reply
PostProcessingHook sub { ${$_[1]}->add_attr('Class', \
      'billing rate 1');}

3.31.10. PreAuthHook

This optional parameter allows you to define a Perl function that will be called during packet processing. PreAuthHook is called for each request after per-Realm user name rewriting and before it is passed to any AuthBy clauses. A reference to the current request is passed as the first argument, and a reference to the reply packet currently being constructed is passed as the second argument.

The hook code is compiled by Perl when Radiator starts up. Compilation errors in your hook code will be reported to the log file at start-up time. Runtime errors in your hook will also be reported to the log file when your hook executes. Multiline hooks (i.e. with trailing backslashes (\)) are parsed by Radiator into one long line. Therefore you should not use trailing comments in your hook.

PreAuthHook can be an arbitrarily complicated Perl function, that might run external processes, consult databases, change the contents of the current request or many other things.

# Fake a new attribute into the request
PreAuthHook sub { ${$_[0]}->add_attr('test-attr', \
      'test-value');}

3.31.11. PostAuthHook

This optional parameter allows you to define a Perl function that is called during packet processing. PostAuthHook is called for each request after it has been passed to all the AuthBy clauses. A reference to the current request is passed as the first argument, and a reference to the reply packet currently being constructed is passed as the second argument. The third argument is a reference to the result of the authentication ($main::ACCEPT, $main::REJECT and so on). The fourth argument is a reference to a string variable holding the reason for a reject, or undefined if none is available. To change the type of reply, set the reference to third argument.

The hook code is compiled by Perl when Radiator starts up. Compilation errors in your hook code are reported to the log file at start-up time. Runtime errors in your hook are also reported to the log file when your hook is executed. Multiline hooks, with trailing backslashes (\), are parsed by Radiator into a one long line. Therefore do not use trailing comments in your hook.

PostAuthHook can be an arbitrarily complicated Perl function, that might run external processes, consult databases, change the contents of the current request or many other things.

# Add some reply attributes to the reply message
# if it is a REJECT and there is 1 or fewer there already
PostAuthHook sub { ${$_[1]}->add_attr('test-attr', \
      'test-value') \
      if ${$_[2]} == $main::REJECT \
      && ${$_[1]}->attr_count() <= 1; }

3.31.12. AuthByPolicy

This parameter allows you to control how multiple AuthBy clauses in this Handler or Realm are used. For more information, see Section 3.38.1. AuthByPolicy.

3.31.13. AuthBy

This specifies that the Handler is to be authenticated with an <AuthBy> clause that is defined elsewhere. The argument must specify the Identifier of the AuthBy clause to use. The AuthBy clause may be defined anywhere else: at the top level, or in a Realm or Handler clause. You can have as many AuthBy parameters as you wish. They will be used in the order that they appear in the configuration file (subject to AuthByPolicy) in the same way as <AuthBy > clauses.

Tip

This is a convenient way to reuse the same authenticator for many Realms or Handlers.

<AuthBy xxxxxx>
      Identifier myidentifier
</AuthBy>
<Realm xxxxxx>
      # This authenticates through the AuthBy defined above
      AuthBy myidentifier
</Realm>

3.31.14. Identifier

This optional parameter acts as a label that can be useful for custom code in hooks. It is not used by the standard Radiator code.

3.31.15. StripFromRequest

Strips the named attributes from the request before passing it to any authentication modules. The value is a comma separated list of attribute names. StripFromRequest removes attributes from the request before AddToRequest adds any to the request. There is no default.

# Remove any NAS-IP-Address,NAS-Port attributes
StripFromRequest NAS-IP-Address,NAS-Port

3.31.16. AddToRequest

Adds attributes to the request before passing it to any authentication modules. Value is a list of comma separated attribute value pairs all on one line, exactly as for any reply item. StripFromRequest removes attributes from the request before AddToRequest and AddToRequestIfNotExist adds any to the request. You can use any of the special % formats in the attribute values. There is no default.

# Append a Filter-ID and host name
AddToRequest Calling-Station-Id=1,Login-IP-Host=%h

3.31.17. AddToRequestIfNotExist

Adds attributes to the request before passing it to any authentication modules. Unlike AddToRequest, an attribute will only be added if it does not already exist in the request. Value is a list of comma separated attribute value pairs all on one line, exactly as for any reply item. StripFromRequest removes attributes from the request before AddToRequest and AddToRequestIfNotExist adds any to the request. You can use any of the special % formats in the attribute values. There is no default.

# Append a Filter-ID and host name if they are not there already
AddToRequestIfNotExist Calling-Station-Id=1,Login-IP-Host=%h

3.31.18. <AuthBy xxxxxx>

This marks the beginning of an AuthBy clause in a Handler or Realm, which defines how to authenticate and record accounting information for all the users in this Realm or Handler. The xxxxxx is the name of a specific AuthBy module. For more information about configuring specific AuthBy clauses, see the relevant sections.

You can have 0 or more AuthBy clauses in a Handler or Realm. The AuthBy clauses will be executed in order until the AuthByPolicy for the Realm or Handler is satisfied.

<AuthBy xxxxxx> both defines an authentication method and specifies where it should be used.

Note that something like

<Realm xxxxxx>
      <AuthBy xxxxxx>
            ....
      </AuthBy>
      ....
</Realm>

Is equivalent to

<AuthBy xxxxxx>
      Identifier myidentifier
      .....
</AuthBy>
<Realm xxxxxx>
      # This authenticates through the AuthBy defined above
      AuthBy myidentifier
      ....
</Realm>

3.31.19. UsernameCharset

This optional parameter checks that every user name consists only of the characters in the specified character set. This can be useful to reject requests that have user names that cannot be valid. The value of the parameter is a Perl character set specification. See your Perl reference manual for details about how to construct Perl character set specifications. Note that the some special characters must be escaped with a backslash. This parameter is not set by default and no character set check is done.

UsernameCharset is available as a global and Handler level parameter. The character set checks are done for both User-Name attribute and EAP identity.

When a request is processed by a Handler, User-Name attribute must pass both global and per Handler UsernameCharset checks. When an EAP-Response/Identity message is handled by an AuthBy, the EAP identity must pass both global and per Handler UsernameCharset checks. The Handler is the last Handler that processed the request before it was passed to the AuthBy.

This example permits only alphanumeric, period, underscore, the @-sign, and dash. Note that a dash at the end of character class needs not to be escaped with a backslash:

UsernameCharset a-zA-Z0-9._@-

3.31.20. RejectHasReason

Normally, when Radiator rejects an Access-Request, it sets the reply message to "Request Denied". This optional parameter forces Radiator to put an additional Reply- Message into Access-Reject indicating why the rejection occurred. This may be useful for debugging in some cases, since some NASs will display the Reply-Message during an interactive login. However it should be noted that some PPP clients do not show the Reply-Message to the end user.

# Show any rejection reason to the end user (maybe)
RejectHasReason

3.31.21. SessionDatabase

This optional parameter specifies a particular Session Database to use for the enclosing Realm or Handler. The value of the parameter must be the Identifier of a SessionDatabase clause. The default behaviour is to use the last global SessionDatabase specified in the configuration file. If no SessionDatabases are specified in the configuration file, then the default INTERNAL session database will be used.

SessionDatabaseOptions is available for changing how a Handler uses its session database. For more information, see Section 3.31.22. SessionDatabaseOptions.

Tip

The user name used to access the session database depends on the setting of SessionDatabaseUseRewrittenName and SessionDatabaseOptions.

Tip

This is an advanced use parameter. Only very unusual configurations need this parameter to be set. The default behaviour suits for most situations.

<Handler xxxxxx>
      # If this was not here, we would default to
      # myspecialsessiondb2 (the last one in the config file)
      SessionDatabase myspecialsessiondb1
      .....
</Handler>
<SessionDatabase SQL>
      Identifier myspecialsessiondb1
      ....
</SessionDatabase>
<SessionDatabase SQL>
      Identifier myspecialsessiondb2
      .... 
</SessionDatabase>

3.31.22. SessionDatabaseOptions

SessionDatabaseOptions allows controlling how Handler communicates with its session database.

The following options are available:

NoDeleteBeforeAuthentication suppresses the call to delete a session from session database when Access-Request is received. Calling delete is useful, for example, when a NAS port can only have a single active session. An Access-Request indicates that a new session is starting and calling delete allows to clear the old session if its accounting Stop was lost.
AddBeforeAuthentication causes this Handler to add a new session before passing the Access-Request to AuthBys
AddAfterAuthentication causes this Handler to add a new session after successful authentication without waiting for Accounting Start
UseRewrittenName tells the Handler to use rewritten user name with session database. If the option is set, the rewritten user name (as rewritten by RewriteUsername etc) is used. Otherwise the original User-Name attribute from the request is used.
NoDeleteOnSessionStop replaces a call to delete a session from session database with a call to update a session when an accounting stop is received. This allows the session database to hold records of ended sessions.

Enabling UseRewrittenName provides the same functionality as setting the SessionDatabaseUseRewrittenName (for more information, see Section 3.31.23. SessionDatabaseUseRewrittenName). New configurations must use this option instead of setting the configuration parameter.

You can enter multiple options by separating them with commas. Here is an example how to skip session delete during authentication:

SessionDatabaseOptions NoDeleteBeforeAuthentication

3.31.23. SessionDatabaseUseRewrittenName

This optional parameter controls the user name used to update and access the session database for this Handler. If SessionDatabaseUseRewrittenName is true, the rewritten user name (as rewritten by RewriteUsername and the others) is used. Otherwise the original User-Name attribute from the request is used. This is false by default.

New configurations must use SessionDatabaseOptions to control this and any other possible options. For more information, see Section 3.31.22. SessionDatabaseOptions.

3.31.24. AcctLog

This specifies that the Handler is to log all accounting messages with an <AcctLog> clause that is defined elsewhere. The argument must specify the Identifier of the AcctLog clause to use. The AcctLog clause may be defined anywhere else: at the top level, or in a Realm or Handler clause. You can have as many AcctLog parameters as you wish. They will be used in the order that they appear in the configuration file in the same way as

<AcctLog
                     xxxxxx>

clauses.

Tip

This is a convenient way to reuse the same authentication logger for many Realms or Handlers.

<AcctLog xxxxxx>
      Identifier myacctlogidentifier
      ....
</AuthLog>
<Handler xxxxxx>
      # This logs through the AcctLog defined above
      AcctLog myacctlogidentifier
</Handler>

3.31.25. AuthLog

This specifies that the Handler is to log all authentications with an <AuthLog> clause that is defined elsewhere. The argument must specify the Identifier of the AuthLog clause to use. The AuthLog clause may be defined anywhere else: at the top level, or in a Realm or Handler clause. You can have as many AuthLog parameters as you wish. They will be used in the order that they appear in the configuration file in the same way as

<AuthLog
                     xxxxxx>

clauses.

Tip

This is a convenient way to reuse the same authentication logger for many Realms or Handlers.

<AuthLog xxxxxx>
      Identifier myidentifier
      ....
</AuthLog>
<Handler xxxxxx>
      # This logs through the AuthLog defined above
      AuthLog myidentifier
</Handler>

3.31.26. <AuthLog xxxxxx>

Indicates that logging of authentication success and failure should be handled in a special way.

<AuthLog
                     FILE>

, <AuthLog SQL> and <AuthLog SYSLOG> are currently supported. When authentication is complete, each of the AuthLog clauses defined for the handler will be executed in order. For each AuthLog, the authentication details will be logged according to the parameters for that clause. You can have as many <AuthLog xxxxxx> clauses as you wish, or none at all.

<AuthLog
                     xxxxxx>

both defines a logging method and specifies where it should be used.

Note that something like

<Handler xxxx>
      <AuthLog xxxxxx>
            ....
      </AuthLog>
      ....
</Handler>

Is identical to

<AuthLog xxxxxx>
      Identifier myidentifier
</AuthLog>
<Handler xxxxxx>
      # This log through the AuthLog defined above
      AuthLog myidentifier
</Handler>

3.31.27. PacketTrace

This optional flag forces all packets that pass through this module to be logged at trace level 5 until they have been completely processed. This is useful for logging packets that pass through this clause in more detail than other clauses during testing or debugging. The packet tracing stays in effect until it passes through another clause with PacketTrace set off or 0.

PacketTrace is available for the following clauses:

Client
Handler
Realm
AuthBy
ServerDIAMETER
ServerRADSEC
ServerTACACSPLUS

Here is an example of using PacketTrace:

# Debug any packets that pass through here
PacketTrace

3.31.28. LogRejectLevel

Log level for rejected authentication attempts. Defaults to global LogRejectLevel value.

3.31.29. DefaultReply

This is similar to Section 3.14.20. AddToReply except it adds attributes to an Access-Accept only if there would otherwise be no reply attributes. StripFromReply does never remove any attributes added by DefaultReply. Value is a list of comma separated attribute value pairs all on one line, exactly as for any reply item. You can use any of the special % formats in the attribute values. There is no default.

Although this parameter can be used in any AuthBy method, it is most useful in methods like <AuthBy UNIX> and <AuthBy SYSTEM>, which do not have a way of specifying per-user reply items. In other AuthBy methods you can also very easily set up a standard set of reply items for all users, yet you can still override reply items on a per-user basis.

# If the user had no reply items set some
DefaultReply Service-Type=Framed,Framed-Protocol=PPP

3.31.30. StripFromReply

Strips the named attributes from Access-Accepts before replying to the originating client. The value is a comma separated list of RADIUS attribute names. StripFromReply removes attributes from the reply before AddToReply adds any to the reply. There is no default. This is useful, for example, with AuthBy RADIUS to prevent downstream RADIUS servers sending attributes you do not like back to your NAS.

# Remove dangerous attributes from the reply
StripFromReply Framed-IP-Netmask,Framed-Compression

3.31.31. AllowInReply

This optional parameter is the complement to StripFromReply: It specifies the only attributes that are permitted in an Access-Accept. It is useful, for example, to limit the attributes that are passed back to the NAS from a proxy server. This way you can prevent downstream customer RADIUS servers from sending back illegal or troublesome attributes to your NAS.

AllowInReply does not prevent other attributes being added locally by DefaultReply, AddToReply and AddToReplyIfNotExist.

# Only permit a limited set of reply attributes.
AllowInReply Session-Timeout, Framed-IP-Address

3.31.32. AddToReply

Adds attributes to reply packets. Value is a list of comma separated attribute value pairs all on one line, exactly as for any reply item. StripFromReply removes attributes from the reply before AddToReply adds any to the reply. You can use any of the special % formats in the attribute values. There is no default. AddToReply adds attributes to replies to all types of request that are handled by this clause.

Although this parameter can be used in any AuthBy method, it is most useful in methods like AuthBy UNIX, which don’t have a way of specifying per-user reply items.

# Append some necessary attributes for our pops
AddToReply cisco-avpair="ip:addr_pool=mypool"

3.31.33. AddToReplyIfNotExist

This is similar to AddToReply, but only adds an attribute to a reply if and only if it is not already present in the reply. Therefore, it can be used to add, but not override a reply attribute. This is contributed by Vincent Gillet <vgi@oleane.net>.

3.31.34. AddExtraCheck

This is a string that adds check items before passing to the authentication modules. The value is a list of comma-separated check items value pairs.

3.31.35. RejectReason

This optional parameter specifies a string that is used as the Reply-Message if <AuthBy INTERNAL> rejects a request. The enclosing Realm or Handler must also have RejectHasReason enabled.

Here is an example of using RejectReason:

RejectReason Your account has been disabled

3.31.36. DynamicReply

This optional parameter specifies a reply item that will be eligible for run-time variable substitution. That means that you can use any of the % substitutions in Section 3.3. Special formatters in that reply item. You can specify any number of DynamicReply lines, one for each reply item you want to do replacements on. Any packet-specific replacement values will come from the Access-Accept message being constructed, and not from the incoming Access-Request. That means that special characters like %n will not be replaced by the received User-Name, because User-Name is in the request, but not the reply.

In the following example, substitution is enabled for USR-IP-Input-Filter in an AuthBy clause. When a user authenticates, the %a in the filter will be replaced by the users IP Address, which makes the filter an anti-spoof filter.

<AuthBy whatever>
      ......
      UseAddressHint
      DynamicReply USR-IP-Input-Filter
</AuthBy>

In the users file:

DEFAULT User-Password = "UNIX"
      Framed-IP-Address = 255.255.255.254,
      Framed-Routing = None,
      Framed-IP-Netmask = 255.255.255.255,
      USR-IP-Input-Filter = "1 REJECT src-addr != %a;",
      Service-Type = Framed-User

Note

This parameter used to be called Dynamic. That name is still recognised as a synonym for DynamicReply.

3.31.37. MaxSessions

This parameter allows you to apply a simple limit to the number of simultaneous sessions a user in this Realm is permitted to have. It is most common to limit users to either one session at a time or unlimited, but Radiator also supports other numbers.

MaxSessions works by looking at each accounting request for a realm when it arrives. Whenever Start is seen for a user, the count of their number if current sessions is incremented, and whenever a Stop is seen, it is decremented. When an access request is received, the number of sessions current for that user is compared to MaxSessions. If the user already has MaxSessions sessions or more, Radiator replies with an access denial. By setting MaxSessions to 0, you can temporarily deny access to all users in the realm.

MaxSessions applies a hard limit that cannot be overridden by DefaultSimultaneousUse parameter or by per-user Simultaneous-Use check items. For more information, see Section 3.32.14. DefaultSimultaneousUse. For many applications, you may wish to consider using DefaultSimultaneousUse instead of MaxSessions. You can control the maximum number of sessions on a per-user basis with the Simultaneous-Use check item. For more information, see Section 7.1.16. Simultaneous-Use.

The session count for each user is stored entirely within Radiator (unless you specify a SessionDatabase clause). This means that if you restart or reinitialise Radiator, it will lose count of the number of current sessions for each user. Radiator can use SNMP to confirm whether a user is already logged in or not. For more information, see Section 3.14.35. NasType.

Note that if Radiator fails to receive an accounting Stop request, it may result in incorrectly assume the users are not permitted to log in when, in fact, they are. Correct this by restarting Radiator, or by sending an artificial accounting stop for the user using the radpwtst utility or by configuring Radiator to query the NAS directly. For more information, see Section 6.1. radpwtst and Section 3.14.35. NasType.

# Limit all users in this realm to max of 1 session
MaxSessions 1

Tip

You can set the maximum number of simultaneous sessions for individual users with the Simultaneous-Use check item. In this case, the smaller of MaxSessions and the users Simultaneous-Use will apply.

3.31.38. AutoClass

This optional parameter will force Radiator to automatically reply with a Class attribute with Access-Accept. The Class attribute should be echoed back by the NAS with the subsequent Accounting-Request messages that relate to this authentication. The Class attribute works in conjunction with tracing identifier, for more information about logging authentication and accounting messages, see Section 3.7.4. LogTraceId. AutoClass is currently experimental.

Even if you do not plan to use tracing identifier, enabling AutoClass may be useful for matching authentication logs with accounting sessions.

# Turn on global LogTraceId
LogTraceId

# Generate a Class attribute that NAS will echo back
<Handler ...>
      ......
      AutoClass
</Handler>

AutoClass supports optional parameters for further Class attribute formatting. These arguments are added to the values that AutoClass adds by default. The currently support arguments are uuid and formatted which add a hex value UUID or Radiator formatted string. The format is specified after a whitespace, see below for an example. The default is not to do further formatting.

# Add a v3 UUID to Class
AutoClass uuid

Note

Perl module Data::UUID is required for the uuid parameter.

# Add the farm instance to Class
AutoClass formatted %O

3.31.39. WtmpFileName

The name of a Unix SVR4 wtmp format file to log Accounting-Request messages. All Accounting-Request messages will be logged. If WtmpFileName is not defined, no messages will be logged in this format. The default is no logging. The file name can include Section 3.3. Special formatters, which means that, for example, using the %c specifier, you can maintain separate accounting log files for each Client. The WtmpFileName file is always opened written and closed for each message, so you can safely rotate it at any time. Start messages are logged as USER_PROCESS (7), all other messages are logged as DEAD_PROCESS (8).

You may wish to use your standard Unix administration tools (such as last(1)) to process information in the wtmp file.

Tip

Red Hat Enterprise Linux 6.1 and later uses a modified format for wtmp files, compared with earlier versions. In order to use tools like last on a wtmp file produced by Radiator, you will need to use the -o flag (which specifies lib5c format).

3.31.40. FramedGroup

This optional parameter acts similarly to Framed-Group reply items, but it applies to all Access-Requests authenticated by this clause. If FramedGroup is set and a matching FramedGroupBaseAddress is set in the Client from where the request came, then a Framed-IP-Address reply item is automatically calculated by adding the NASPort in the request to the FramedGroupBaseAddress specified by FramedGroup. For more information, see Section 3.14.38. FramedGroupBaseAddress.

Note

You can override the value of FramedGroup for a single user by setting a Framed-Group reply item for the user.

# Work out the users IP address from the first 
# FramedGroupBaseAddress specified in out client
FramedGroup 0

3.31.41. PasswordLogFileName

The name of file to log authentication attempts to. Attempts where the user is not found, are not logged. The default is no logging. The file name can include Section 3.3. Special formatters, which means that using the %C, %c and %R specifiers, you can maintain separate password log files for each Realm or Client or a combination.

Each login attempt that generates a password check will be logged to the file, one attempt per line. For more information about file format, see Section 9.6. Password log file.

# Help desk want to see all password attempts
PasswordLogFileName %L/password.log

If the file name starts with a vertical bar character ('|') then the rest of the filename is assumed to be a program to which the output is to be piped. Otherwise the output will be appended to the named file:

# Pipe to my-log-prog
PasswordLogFileName |/usr/local/bin/my-log-prog

3.31.42. ExcludeFromPasswordLog

For security reasons, you can exclude certain users from the passwords logged to PasswordLogFileName. The value is a white space separated list of user names.

# Do not log password from our sysadmin or root
ExcludeFromPasswordLog root admin ceo nocboss

3.31.43. ExcludeRegexFromPasswordLog

Similar to ExcludeFromPasswordLog, but the value is a Perl regular expression.

# Do not log password from anyone that begins with root
ExcludeRegexFromPasswordLog ^root

3.31.44. HandleAscendAccessEventRequest

This optional parameter causes Radiator to respond to Ascend-Access-Event-Request messages. These messages are sent by some types of specially configured Ascend NASs. They contain a count of the number of sessions the NAS thinks it currently has in each Class.

When HandleAscendAccessEventRequest is enabled, it causes Radiator to confirm that its SQL Session Database is up to date. If the session counters do not agree, Radiator will use snmpwalk to confirm the existence of its sessions, deleting from the SQL Session Database the ones that do not really exist.

Tip

HandleAscendAccessEventRequest requires that an SQL Session Database is configured for this Handler or Realm. See Section 3.31.21. SessionDatabase.

Tip

You must set NasType to Ascend for the SNMP session confirmation to work correctly.

# handle Ascend-Access-Event-Request messages
HandleAscendAccessEventRequest