3.26. <Log SYSLOG>

This optional clause creates a SYSLOG logger, which logs all messages with a priority level of Trace or more to the syslog system. <Log SYSLOG> requires Sys::Syslog. The logging is in addition to any logging to the file defined by LogFile. For more information, see Section 3.7.13. LogFile.
Messages are logged to syslog with priority levels that depend on the severity of the message. There are 5 defined priority levels and they are logged to the equivalent syslog priority. See the Trace parameter for a description of the priority levels supported.
Ensure that your host's syslog is configured to do something with err, warning, notice, info, and debug priority messages from the Syslog facility you specify, otherwise you do not see any messages. See /etc/syslog.conf or its equivalent on your system.
The logger becomes active when it is encountered in the configuration file. It logs parse errors from later in the configuration file and subsequent run-time events. Parse errors from earlier in the configuration file are not logged through this clause.
You can place a <Log xxxxxx> clause inside any clause in the configuration file. This causes messages originating from within that clauses code to be logged with the logger prior to being logged with any global loggers. This can be handy for debugging or tracing only certain Realms or AuthBy clauses:
      # This will log messages from within the Handler
      <Log SYSLOG>
            #Trace 2

3.26.1. Facility

The name of the syslog facility that will be logged to. The default is user.
# Log to the syslog facility called 'auth'
Facility auth

3.26.2. Trace

This defines the priority level of messages to be traced. For more information, see Section 3.7.3. Trace.
Packet dumps appear only if the global Trace level is set to 4 or more.

3.26.3. IgnorePacketTrace

Exclude this logger from PacketTrace debugging.

3.26.4. Identifier

This optional parameter acts as a label that can be useful for custom code in hooks. It can also be referred to by <Log xxxxxx> in any other clause.
<AuthBy whatever>
      # With an Identifier, can refer to this logger from 
      # other clauses
      <Log SYSLOG>
            Identifier mylogger
            Facility user
<AuthBy whatever>
      # This AuthBy will log to the Log SYSLOG above
      Log mylogger

3.26.5. LogSock

This optional parameter specifies what type of socket to use to connect to the syslog server. The possible values are:
  • native
  • eventlog
  • unix
  • inet
    This means that TCP is tried first, then UDP.
  • tcp
  • udp
  • stream
  • pipe
  • console
The default is to use the Sys::Syslog default of native, tcp, udp, unix, pipe, stream, console.
Due to limitations in the Sys::Syslog Perl module, if you have multiple <AuthLog SYSLOG>, <AcctLog SYSLOG> or <Log SYSLOG> clauses and if any one has LogSock defined, all of them must have LogSock defined.
If you use TCP, we recommend you to define both LogHost and LogPort. If you have not defined LogPort and you see error "TCP service unavailable", this means Sys::Syslog is unable to find the destination port. To resolve this, either use LogPort to define the port or add syslog/tcp or syslogng/tcp definitions to /etc/services file. For more information about LogPort, see Section 3.26.10. LogPort.

3.26.6. LogPath

When LogSock is set to unix or stream or pipe, this optional parameter specifies the syslog path. Defaults to _PATH_LOG macro (if your system defines it).
LogPath /run/mysyslog/log.sock

3.26.7. LogHost

When LogSock is set to tcp or udp or inet, this optional parameter specifies the name or address of the syslog host. Defaults to the local host. Special formatters are supported. For more information, see Section 3.3. Special formatters
The LogHost parameter is passed directly to Perl's Sys::Syslog module which will likely do a DNS query for each logged message. This can cause performance problems and high number of DNS requests with verbose log levels. It is recommended to not set LogSock and let the local syslog to do remote logging.
Sys::Syslog does not support IPv6. To log over IPv6, leave LogSock unset and let the local syslog do remote logging over IPv6.
# Log to a remote host via syslog over udp:
LogSock udp
LogHost your.syslog.host.com

3.26.8. LogOpt

This optional parameter allows control over the syslog options passed to Sys::Syslog::openlog. LogOpt is a comma separated list of words from the set:
  • cons
  • ndelay
  • nofatal
  • nowait
  • perror
  • pid
As described in the Perl Sys::Syslog documentation.
Defaults to pid. Special characters are supported.
LogOpt pid,perror

3.26.9. LogIdent

This optional string parameter specifies an alternative ident name Sys::Syslog prepends to every syslog message. Defaults to the executable name used to run radiusd. Special formatters are supported. For more information, see Section 3.3. Special formatters
# Also log server farm instance number
LogIdent %h-%O

3.26.10. LogPort

This optional parameter specifies an alternative TCP or UDP destination port on the syslog host. There is no default, which means Sys::Syslog chooses the port. Here is an example of using LogPort:
LogPort 5514
This parameter requires Sys::Syslog 0.28 or later.

3.26.11. LogFormat

This optional parameter permits you to customise the log string when LogFormatHook is not defined. Special formatting characters are permitted. The variables are replaced as follows:
  • %0 by the message severity as an integer
  • %1 by the severity as a string
  • %2 by the log message
  • %3 by tracing identifier string
When using <Log FILE>, there is no default value for LogFormat and the format is similar to LogFormat %l:%1:%2.
When using <Log SYSLOG>, there is no default value for LogFormat and the format is similar to LogFormat %2.

3.26.12. LogFormatHook

This specifies an optional Perl hook that runs for each log message when defined. By default, no hook is defined and LogFormat or the default format is used. The hook must return a single value. If the value is defined, it is used as the message to log. An undefined value causes the Log clause to return without logging. This allows LogFormatHook to function as a filter to suppress unwanted log messages.
The hook parameters are the following:
  • Message severity (integer)
  • Log message
  • Reference to the current request
  • Tracing identifier (string)
See goodies/logformat.cfg for a sample configuration file with JSON and CEF (ArcSight Common Event Format) formats.
Consider installing Cpanel::JSON::XS or JSON::XS for higher performance JSON encoding.

3.26.13. MaxMessageLength

This optional parameter specifies a maximum message length (in characters) for each message to be logged. If specified, each log message is truncated to the specified number of characters prior to logging. Defaults to 0, which means no truncation.