# Module mod_log_config

This module is contained in the `mod_log_config.c` file, and is not compiled in by default. It provides for logging of the requests made to the server, using a user-specified format.

## Summary

This is an EXPERIMENTAL module, which implements the TransferLog directive (same as the common log module), and an additional directive, LogFormat. Bugs would not surprise me.

The argument to the LogFormat is a string, which can include literal characters copied into the log files, and `%' directives as follows:

    %...h:          Remote host
    %...l:          Remote logname (from identd, if supplied)
    %...u:          Remote user (from auth; may be bogus if return
                    status (%s) is 401)
    %...t:          Time, in common log format time format
    %...r:          First line of request
    %...s:          Status.  For requests that got internally redirected,
                    this is status of the original request --- %...>s
                    for the last.
    %...b:          Bytes sent.
    %...{Foobar}i:  The contents of Foobar: header line(s) in the request
                    sent to the client.
    %...{Foobar}o:  The contents of Foobar: header line(s) in the reply.

The `...' can be nothing at all (e.g. `"%h %u %r %s %b"`), or it can indicate conditions for inclusion of the item (which will cause it to be replaced with `-' if the condition is not met). Note that there is no escaping performed on the strings from %r, %...i and %...o; some with long memories may remember that I thought this was a bad idea, once upon a time, and I'm still not comfortable with it, but it is difficult to see how to `do the right thing' with all of `%..i', unless we URL-escape everything and break with CLF.

The forms of condition are a list of HTTP status codes, which may or may not be preceded by `!'. Thus, `%400,501{User-agent}i' logs User-agent: on 400 errors and 501 errors (Bad Request, Not Implemented) only; `%!200,304,302{Referer}i' logs Referer: on all requests which did not return some sort of normal status.

The default LogFormat reproduces CLF; see below.

The way this is supposed to work with virtual hosts is as follows: a virtual host can have its own LogFormat, or its own TransferLog. If it doesn't have its own LogFormat, it inherits from the main server. If it doesn't have its own TransferLog, it writes to the same descriptor (meaning the same process for `| ...').

That means that you can do things like:

> `<VirtualHost hosta.com>
> LogFormat "hosta ..."
> ...
> </VirtualHost>
> <VirtualHost hosta.com>
> LogFormat "hostb ..."
> ...
> </VirtualHost>`

... to have different virtual servers write into the same log file, but have some indication which host they came from, though a %v directive may well be a better way to handle this. Look for more changes to come to this format.

## Directives

- LogFormat
- TransferLog

## LogFormat

Syntax: LogFormat string
Default: `LogFormat "%h %l %u %t \"%r\" %s %b"`
Context: server config, virtual host
Status: Experimental
Module: mod_log_config

This sets the format of the logfile.

## TransferLog

Syntax: TransferLog file-pipe
Default: `TransferLog logs/transfer_log`
Context: server config, virtual host
Status: Experimental
Module: mod_log_config

The TransferLog directive sets the name of the file to which the server will log the incoming requests. File-pipe is one of

A filename
  A filename relative to the ServerRoot.
`|' followed by a command
  A program to receive the agent log information on its standard input. Note the a new program will not be started for a VirtualHost if it inherits the TransferLog from the main server.

Security: if a program is used, then it will be run under the user who started httpd. This will be root if the server was started by root; be sure that the program is secure.