



= Logtee Module

The `logtee` module writes the log messages to a socket or to a
file.  Each instance of the module can send log messages to one,
and only one, destination.

NOTE: Multiple `logtee`s modules may be used for any given request.
The `logtee` modules will not affect normal logging output.
i.e. This logging is *in addition* to any other logging that is
done by the server.



## Configuration Settings


delimiter::  Custom line delimiters.

Defaults to `\n` (newline) but may be any UTF8 multi-character
string.



format:: The default format string.

Additional expansions are available:

[options="header,autowidth"]
|===
| Option           | Description
| `%{Log-Message}` | The log message
| `%{Log-Level}`	  | Debugging level
| `%{Log-Type}`	  | Error, Warn, Info, Debug etc...
|===

NOTE: Format could contain markup (JSON for example), but it's up
to the user to call the appropriate escaping function.



buffer_depth::

The number of log messages we buffer before discarding.

The module writes log messages to a ring buffer between
processing requests and checking whether the output socket is
writable, so this should be not set to < `1000`.

If an error occurs (connection failed, out of disk space
etc...) the ring buffer will be used to temporarily buffer
log data until the error is cleared.

This limit is applied per worker thread.



destination:: What should be done with log messages.

May be one of:

[options="header,autowidth"]
|===
| Option | Description
| file   | Write to a file - NYI.
| tcp    | Write to a TCP socket.
| udp    | Write to a UDP socket.
| unix   | Write to a UNIX socket.
|===

NOTE: Syslog output via `syslog()` is not explicitly supported,
but you may use one of the other transports to talk directly to
a syslog daemon.



connection_timeout:: How long we wait for a connection or file to open.

If a connection takes longer than this to open, the module returns `fail`.



reconnection_delay::

How long to wait after a connection or file has become
unusable, to try and re-open the connection or file.



.File as the destination for log output


filename:: The file where the logs will go.



permissions:: The Unix-style permissions on the log file.

Depending on format string, the log file may contain secret or
private information about users.  Keep the file permissions as
restrictive as possible.



group:: The Unix group which owns the log file.

The user that freeradius runs as must be in the specified
group, otherwise it will not be possible to set the group.



escape_filenames::

Most file systems can handle nearly the full range of UTF-8
characters.  Ones that can deal with a limited range should
set this to `yes`.



.UNIX socket-file as the destination for log outputx


filename:: Full path to the `unix socket` file.



.TCP-server as the destination for log output


server:: Server to connect to.



port:: Port to connect to.



.UDP-server as the destination for log output


server:: Server to connect to.



port:: Port to connect to.


== Default Configuration

```
logtee {
#	delimiter = "\n"
	format = "%{Log-Type} - %{Log-Level} - %{Log-Message}"
#	buffer_depth = 1000000
	destination = 'file'
	connection_timeout = 1.0
	reconnection_delay = 1.0
	file {
		filename = ${logdir}/linelog
		permissions = 0600
#		group = ${security.group}
		escape_filenames = no
	}
	unix {
		filename = /path/to/unix.socket
	}
	tcp {
		server = "example.org"
		port = 514
	}
	udp {
		server = "example.org"
		port = 514
	}
}
```
