Section 3.106. <AuthLog FILE>

3.106. <AuthLog FILE>

This clause logs the authentication successes and failures to a flat file. You can define as many <AuthLog FILE> clauses as you need to at the top level or within the Realm or Handler clauses. Each clause can specify different logging conditions and a different log file.

Here is an example of using

<AuthLog
                  FILE>

# This auth logger logs both success and failure to a file. It
# also log authentications that are ignored.
<AuthLog FILE>
      Identifier myauthlogger
      Filename %L/authlog
      LogSuccess 1
      LogFailure 1
      LogIgnore  1
</AuthLog>
<Realm DEFAULT>
      <AuthBy FILE>
            Filename %D/users
      </AuthBy>
      # Log authentication results to a file
      AuthLog myauthlogger
</Realm>

<AuthLog FILE> understands also the same parameters as all AuthLogs. For more information, see Section 3.105. <AuthLog xxxxxx>.

3.106.1. Filename

This optional parameter specifies the name of the file where authentication log messages are to be written. You can use any of the special characters defined. For more information about special characters, see Section 3.3. Special formatters. The default value is %L/password.log. Special character %0 is replaced by the result of the authentication and %1 by the reason string.

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

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

3.106.2. SuccessFormat

This optional parameter specifies the format that is to be used to log authentication successes in Filename when LogFormatHook is not defined. You can use any of the special characters. For more information about special characters, see Section 3.3. Special formatters. %0 is replaced by the message severity level, %1 by the reason string (usually an empty string for success), and %2 by the tracing identifier. The default is %l:%U:%P:OK. This logs time stamp in long format, current User-Name, decoded password and text OK.

CAUTION

The default SuccessFormat logs the plaintext password entered by the user. Some organisations prefer that user passwords are not logged. In that case, SuccessFormat that does not include the %P (decoded password) special character is preferable.

3.106.3. FailureFormat

This optional parameter specifies the format that is to be used to log authentication failures in Filename when LogFormatHook is not defined. You can use any of the special characters defined. For more information about special characters, see Section 3.3. Special formatters. Also %0 is replaced by the message severity level, %1 by the reason string and %2 by the tracing identifier. The default value is %l:%U:%P:FAIL. This logs time stamp in long format, current User-Name, decoded password and text FAIL.

CAUTION

The default FailureFormat logs the plaintext password entered by the user. Some organisations prefer that user passwords are not logged. In that case, FailureFormat that does not include the %P (decoded password) special character is preferable.

3.106.4. IgnoreFormat

This optional parameter specifies the format that is to be used to log ignored authentication requests in Filename when LogFormatHook is not defined. You can use any of the special characters defined. For more information about special characters, see Section 3.3. Special formatters. Also %0 is replaced by the message severity level, %1 by the reason string and %2 by the tracing identifier. The default value is %l:%U:%P:IGNORE. This logs time stamp in long format, current User-Name, decoded password and text IGNORE.

CAUTION

The default IgnoreFormat logs the plaintext password entered by the user. Some organisations prefer that user passwords are not logged. In that case, IgnoreFormat that does not include the %P (decoded password) special character is preferable.

3.106.5. LogFormatHook

This specifies an optional Perl hook that runs for each log message when defined. The hook must return the formatted log message. By default no hook is defined and SuccessFormat and FailureFormat are used for formatting. The hook parameters are the message severity level, the reason string, a reference to the current request a tracing identifier string.

Here is an example of using LogFormatHook:

# This auth logger logs both success and failure to a file in
# JSON format. The JSON Perl module must be installed.
<AuthLog FILE>
      Identifier myauthlogger-json
      Filename %L/authlog.json
      LogFormatHook sub { Radius::LogFormat::format_authlog_json(@_); }
      LogSuccess 1
      LogFailure 1
</AuthLog>

For more examples, see goodies/logformat.cfg.

Note

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