Module mod_log_config

Module mod_log_config supports directives for the IBM® HTTP Server for i Web server.

Summary

The module mod_log_config provides for logging of the requests made to the server, using the Common Log Format or a user-specified format. There are 3 directives that control log file creation in this module. The TransferLog, LogFormat, and CustomLog directives are used for log file creation. The TransferLog directive is used to create a log file. The LogFormat directive is used to set a custom format. The CustomLog directive to define a log file and format in one go. The TransferLog and CustomLog directives can be used multiple times in each server to cause each request to be logged to multiple files. The other directives in this module control log file archiving. See Log formats for HTTP Server for information on the log file formats supported on HTTP Server.

Use with virtual hosts

If a <VirtualHost> section does not contain any TransferLog or CustomLog directives, the logs defined for the main server will be used. If it does contain one or more of these directives, requests serviced by this virtual host will only be logged in the log files defined within its definition, not in any of the main server's log files. See the examples below.

Security considerations

See Security tips for HTTP Server for details on why your security could be compromised if the directory where log files are stored is writable by anyone other than the user that starts the server.

Directives

CustomLog

Module: mod_log_config
Syntax: CustomLog file-or-pipe format-or-nickname [env=[!]environment-variable]
Default: none
Context: server config, virtual host
Override: none
Origin: Apache
Usage Considerations: The directive can be specified multiple times in the same configuration file. This is how one would generate multiple log files for the same server instance. For example, if you want an access log, agent log, and referer log, you could specify this directive three separate times with a different file and format. Log files created with CustomLog will be created with a CCSID of UTF-8 (1208) for Integrated File System.
Example: See below.

The CustomLog directive is used to log requests to the server. A log format is specified, and the logging can optionally be made conditional on request characteristics using environment variables.

Parameter One: file-or-pipe
  • The file-or-pipe value indicates the filename to which log records should be written. This is used exactly like the argument to TransferLog; that is, it is either a full path or relative to the current server root. If a pipe is specified, it would be the name of a program that would receive the log file information on standard in. A pipe is specified by using the pipe character (|) followed by a path to the program name (no space between them). The program name can be either a path to a QSYS program object or an IFS path to a symbolic link. The symbolic link would then link to a QSYS program. Data written to the pipe from the server will be in the FSCCSID that is in use by the server.
Parameter Two: format-or-nickname
  • If the value is format, it specifies a format for each line of the log file. The options available for the format are exactly the same as for the argument of the LogFormat directive. If the format includes any spaces (which it will in almost all cases) they should be enclosed in double quotes. If the argument is nickname, that nickname will tie back to a LogFormat directive with the same specified nickname.

    If the nickname "DDS" is specified, the server will create a DDS log file and each record will contain the format described by file QHTTPSVR/QAZHBLOG. When the second argument is "DDS", a path name to a file in the QSYS.LIB file system must also be specified. When "DDS" is specified, it is not necessary to use the Logformat directive to define the format. The nickname "DDS" is a special nickname that is predefined in HTTP Server.

Parameter Three: [env=[!]environment-variable]
  • The optional env= clause controls whether a particular request will be logged in the specified file or not. If the specified environment variable is set for the request (or is not set, in the case of a 'env=!name' clause), then the request will be logged. Environment variables can be set on a per-request basis using the mod_setenvif and/or mod_rewrite modules.

    There is no way to specify conditional logging for requests handled by Fast Response Cache Accelerator (FRCA). That is, environment variable conditions have no affect on the selection of FRCA requests that are logged. If FRCA is being used and a FRCACustomLog is not configured, all requests handled by FRCA will be logged in the CustomLog. The environment variable conditions continue to apply to requests not served from FRCA.

For example, if you want to record requests for all GIF images on your server in a separate log file, but not your main log, you can use: 

SetEnvIf Request_URI \.gif$ fig-image 
CustomLog gif-requests.log common env-gif-image 
CustomLog nongif-requests.log common env=!gif-image

Examples of CustomLog:

# CustomLog with format nickname
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common 

# CustomLog in QSYS with format nickname 
LogFormat "%h %l %u %t \"%r\" %>s %b" common 
CustomLog /QSYS.LIB/MYLIB.LIB/MYLOG.FILE common 

# CustomLog with explicit format string 
CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b" 

# CustomLog with env specified 
SetEnvIf Request_URI \.gif$ gif-image 
CustomLog gif-requests.log common env=gif-image 
CustomLog nongif-requests.log common env=!gif-image 

# CustomLog defining a piped log 
LogFormat "%h %l %u %t \"%r\" %>s %b" common 
CustomLog |/QSYS.LIB/MYLIB.LIB/CUSTOMPIPE.PGM common

For IFS files, the user must create the directories that contain the log file and must grant the QTMHHTTP user write access to the directory. For QSYS.LIB logs, the user must create the library that contains the logs. The server will create the file and members in the specified library.

Note: It is recommended that HTTP Server create the QSYS.LIB log file. If the QSYS.LIB log file is created with a record length that is too small, log information may be truncated and lost. By default the server creates all QSYS.LIB log files with a record size of 512 or greater.

If the filename does not begin with a slash (/) then it is assumed to be relative to the ServerRoot. If LogCycle is active and if the path ends without a (/) character, then the path is considered to be the complete log file name. In this case, the server will add an extension in the format QCYYMMDDHH, where these variables have the following values:

  • Q is a default value that indicates to the server that this is a log file.
  • C is the century indicator (0 for pre-2000, 1 for post-2000).
  • YY is the year indicator.
  • MM is the month indicator.
  • DD is the day indicator.
  • HH is the hour indicator (00 = 00:00 (midnight), 23=23:00).
    Note: This variable will not be generated for filesystem QDLS

    For example, a path of "/logs/errorlog" results in a file such as "/logs/errorlog.Q100030300".

If LogCycle is active and if the path ends with a (/) character, then the path is considered to be the directory that will contain the log file. In this case, the server will create log files named in the QCYYMMDDHH format. For example, a path of "/logs/errorlog/" results in a file such as "/logs/errorlog/Q100030300". If LogCycle is active and the logfile is in the QSYS filesystem, the name must end in the file component of the IFS path. Example: 

# Config file directives
LogCycle Daily
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog /QSYS.LIB/MYLIB.LIB/MYLOGS.FILE common

The resulting daily log rollovers will be of the form /QSYS.LIB/MYLIB.LIB/MYLOGS.FILE/Qcyymmddhh.MBR.

LogCycle Hourly is not valid if the logfile is in the QDLS filesystem as that filesystem only supports 8 character file names and 3 character extensions. For QDLS, the path given on the CustomLog directive must be a directory. For example

CustomLog /QDLS/MYPATH/LOGS/ common

If LogCycle is not active, no special naming is used. The name of the log file given on the CustomLog directive is used as given for the name of the log file. If the name is a directory, a default name of http.log will be concatenated to the directory name to create the log file. For example: 

# Config file directives 
LogCycle Off 
LogFormat "%h %l %u %t \"%r\" %>s %b" common 
CustomLog /logs/path/ common

The resulting log file will be /logs/path/http.log.

Security: See Security tips for HTTP Server for details on why your security could be compromised if the directory where log files are stored is writable by anyone other than the user that starts the server. 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).

FRCACustomLog

Module: mod_log_config
Syntax: FRCACustomLog file-or-pipe file format-or-nickname
Default: none
Context: server config
Override: none
Origin: IBM
Usage Considerations: The directive can be specified multiple times in the same configuration file. This is how one would generate multiple log files for the same server instance. For example, if you want an access log, agent log, and referer log, you could specify this directive three separate times with a different file and format. Log files created with FRCACustomLog will be created with a CCSID of UTF-8 (1208) for Integrated File System.
Example: See below.

The FRCACustomLog directive is used to log FRCA requests to the server.

Parameter One: file-or-pipe file
  • The file-or-pipe file value indicates the filename to which log records should be written. It is either a full path or relative to the current server root. If a pipe is specified, it would be the name of a program that would receive the log file information on standard in. A pipe is specified by using the pipe character "|" followed by a path to the program name (no space between them). The program name can be either a path to a QSYS program object or an IFS path to a symbolic link. The symbolic link would then link to a QSYS program. Note that data written to the pipe from the server will be in the FSCCSID that is in use by the server.
Parameter Two: format-or-nickname
  • The format-or-nickname argument specifies a format or nickname for each line of the log file . If it is a format, it specifies a format for each line of the log file. The options available for the format are exactly the same as for the argument of the LogFormat directive. If the format includes any spaces (which it will in almost all cases) they should be enclosed in double quotes. If the argument is a nickname, that nickname will tie back to a LogFormat directive with the same specified nickname.

    If the nickname "DDS" is specified, the server will create a DDS log file and each record will contain the format described by file QHTTPSVR/QAZHBLOG. When the second argument is "DDS" a path name to a file in the QSYS.LIB file system must also be specified. When "DDS" is specified, it is not necessary to use the Logformat directive to define the format. The nickname "DDS" is a special nickname that is pre-defined in the server. See directive Logformat for additional considerations for the DDS nickname.

Examples of FRCACustomLog:

# FRCACustomLog with format nickname
LogFormat "%h %l %u %t \"%r\" %>s %b" common
FRCACustomLog logs/FRCAaccess_log common

# FRCACustomLog in QSYS with format nickname
LogFormat "%h %l %u %t \"%r\" %>s %b" common
FRCACustomLog /QSYS.LIB/MYLIB.LIB/MYFRCALOG.FILE common

# CustomLog in QSYS with DDS format 
FRCACustomLog /QSYS.LIB/MYLIB.LIB/FRCADDSLOG.FILE DDS 

# FRCACustomLog with explicit format string
FRCACustomLog logs/FRCAaccess_log "%h %l %u %t \"%r\" %>s %b"

# FRCACustomLog defining a piped log
LogFormat "%h %l %u %t \"%r\" %>s %b" common
FRCACustomLog |/QSYS.LIB/MYLIB.LIB/PIPELOG.PGM common

For IFS log files and QSYS log files, the user must create the directories that contain the log file and must grant the QTMHHTTP user write access to the directory. For QSYS.LIB logs, the user must create the library that contains the logs. The server will create the file and members in the specified library.

Note: It is recommended that HTTP Server create the QSYS.LIB log file. If the QSYS.LIB log file is created with a record length that is too small, log information may be truncated and lost. By default the server creates all QSYS.LIB log files with a record size of 512 or greater.

If the filename does not begin with a slash (/) then it is assumed to be relative to the ServerRoot. If LogCycle is active and if the path ends without a (/) character, then the path is considered to be the complete log file name. In this case, the server will add an extension in the format QCYYMMDDHH, where these variables have the following values:

  • Q is a default value that indicates to the server that this is a log file.
  • C is the century indicator (0 for pre-2000, 1 for post-2000).
  • YY is the year indicator.
  • MM is the month indicator.
  • DD is the day indicator.
  • HH is the hour indicator (00 = 00:00 (midnight), 23=23:00).
    Note: this variable will not be generated for filesystem QDLS

    For example, a path of "/logs/errorlog" results in a file such as "/logs/errorlog.Q100030300".

If LogCycle is active and if the path ends with a (/) character, then the path is considered to be the directory that will contain the log file. In this case, the server will create log files named in the QCYYMMDDHH format. For example, a path of "/logs/errorlog/" results in a file such as "/logs/errorlog/Q100030300". If LogCycle is active and the logfile is in the QSYS filesystem, the name must end in the file component of the IFS path. Example: 

# Config file directives
LogCycle Daily
LogFormat "%h %l %u %t \"%r\" %>s %b" common
FRCACustomLog /QSYS.LIB/MYLIB.LIB/MYLOGS.FILE common

The resulting daily log rollovers will be of the form /QSYS.LIB/MYLIB.LIB/MYLOGS.FILE/Qcyymmddhh.MBR.

LogCycle Hourly is not valid if the logfile is in the QDLS filesystem as that filesystem only supports 8 character file names and 3 character extensions. Also for QDLS, the path given on the FRCACustomLog directive must be a directory. For example: 

FRCACustomLog /QDLS/MYPATH/LOGS/ common

The resulting log files would be /QDLS/MYPATH/LOGS/Qcyymmdd.

If LogCycle is not active, no special naming is used. The name of the log file given on the FRCACustomLog directive is used as given for the name of the log file. If the name is a directory, a default name of http.log will be concatenated to the directory name to create the log file. For example: 

# Config file directives 
LogCycle Off 
LogFormat "%h %l %u %t \"%r\" %>s %b" common 
CustomLog /logs/path/ common

The resulting log file will be /logs/path/http.log.

If FRCACustomLog is in the configuration, FRCA requests will be logged to the file specified on the FRCACustomLog directive. All non-FRCA related requests will be logged to any other custom logs configured with the CustomLog directive. Example: 

LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common
FRCACustomLog logs/FRCAaccess_log common

All FRCA requests will be logged to logs/FRCAaccess_log and all non-FRCA requests will be logged to logs/access_log. If FRCACustomLog is not specified in the configuration of the server instance, ALL requests are logged to any custom logs configured with CustomLog including FRCA requests.

LogFormat

Module: mod_log_config
Syntax: LogFormat format [nickname]
Default: LogFormat "%h %l %u %t \"%r\" %s %b"
Context: server config, virtual host
Override: none
Origin: Apache
Usage Considerations: The directive can be specified multiple times in the same configuration file. This is how one would generate multiple log file formats. For example, if you want an access log, agent log, and referer log, you could specify this directive three separate times to define the formats of your log files.
Example: LogFormat "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\""

The LogFormat directive sets the format of the default log file named by the TransferLog directive. See the section on Custom Log Formats for details on the format arguments. If you include a nickname for the format on the directive line, you can use that nickname in FRCACutomLog and CustomLog directives rather than repeating the entire format string.

Parameter One: format
  • The format parameter sets the format of the default log file named by the TransferLog directive. See the section on Custom Log Formats for details on the format arguments.
Parameter Two: [nickname]
  • The optional nickname parameter allows you to include a nickname for the format on the directive line.

A LogFormat directive that defines a nickname does nothing else. That is, it only defines the nickname, it doesn't actually apply the format and make it the default.

If LogFormat is used without a nickname, then any TransferLog directive that does not specify a format will use the format defined with this directive, if it happened to be the most recent LogFormat directive in the configuration file. If another LogFormat directive (without a nickname) is placed in the configuration file, then that format becomes the new log format to be used on subsequent TransferLog directives.

The nickname "DDS" is a log format reserved for use in configuring data description specification (DDS) log files. The server will automatically recognize this format and create a DDS log file based on QHTTPSVR/QAZHBLOG. The "DDS" nickname should not be used when defining a new LogFormat. A LogFormat directive with a nickname of "DDS" will be ignored by the server. The server will assume a DDS file in QSYS.LIB when the "DDS" nickname appears on the CustomLog or FRCACustomLog directives.

See Log formats for HTTP Server for information on the log file formats supported on HTTP Server.

TransferLog

Module: mod_log_config
Syntax: TransferLog file-or-pipe
Default: none
Context: server config, virtual host
Override: none
Origin: Apache
Usage Considerations: The directive can be specified multiple times in the same configuration file. This is how one would generate multiple log files for the same server instance. For example, if you want an access log, agent log, and referer log, you could specify this directive three separate times with a different file and most recent LogFormat. Log files created with TransferLog will be created with a CCSID of UTF-8 (1208) for Integrated File System.
Example: TransferLog logs/access_log

The TransferLog directive adds a log file in the format defined by the most recent LogFormat directive, or Common Log Format. This is only if no other default format has been specified.

Parameter: file-or-pipe
  • The file-or-pipe parameter specifies either a filename relative to the ServerRoot or a program to pipe to. Use the pipe symbol (|) followed by a program to receive the log information in its standard input. Data written to the pipe from the server will be in UTF-8 (1208) in use by the server. The new program will not be started for a VirtualHost if it inherits the TransferLog from the main server.

Examples of TransferLog:

# IFS example 
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" 
TransferLog logs/access_log 

# QSYS example 
LogFormat "%h %l %u %t \"%r\" %>s %b" 
TransferLog /QSYS.LIB/MYLIB.LIB/MYLOGS.FILE 

# Piped log example 
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" 
TransferLog |/QSYS.LIB/MYLIB.LIB/TRANSPIPE.PGM

For IFS files, the user must create the directories that contain the log file and must grant the QTMHHTTP user write access to the directory. For QSYS.LIB logs, the user must create the library that contains the logs. The server will create the file and members in the specified library. If the filename does not begin with a slash (/) then it is assumed to be relative to the ServerRoot. If LogCycle is active and if the path ends without a (/) character, then the path is considered to be the complete log file name. In this case, the server will add an extension in the format QCYYMMDDHH, where these variables have the following values:

  • Q is a default value that indicates to the server that this is a log file.
  • C is the century indicator (0 for pre-2000, 1 for post-2000).
  • YY is the year indicator.
  • MM is the month indicator.
  • DD is the day indicator.
  • HH is the hour indicator (00 = 00:00 (midnight), 23=23:00).
    Note: this variable will not be generated for filesystem QDLS

    For example, a path of "/logs/errorlog" results in a file such as "/logs/errorlog.Q100030300".

If LogCycle is active and if the path ends with a (/) character, then the path is considered to be the directory that will contain the log file. In this case, the server will create log files named in the QCYYMMDDHH format. For example, a path of "/logs/errorlog/" results in a file such as "/logs/errorlog/Q100030300". If LogCycle is active and the logfile is in the QSYS filesystem, the name must end in the file component of the IFS path. For example: 

# Config file directives
LogCycle Daily
LogFormat "%h %l %u %t \"%r\" %>s %b" common
TransferLog /QSYS.LIB/MYLIB.LIB/MYLOGS.FILE

The resulting daily log rollovers will be of the form /QSYS.LIB/MYLIB.LIB/MYLOGS.FILE/Qcyymmddhh.MBR.

LogCycle Hourly is not valid if the logfile is in the QDLS filesystem as that filesystem only supports 8 character file names and 3 character extensions. If LogCycle is not active, no special naming is used. The name of the log file given on the TransferLog directive is used as given for the name of the log file. If the name is a directory, a default name of http.log will be concatenated to the directory name to create the log file. For example: 

# Config file directives 
LogCycle Off 
LogFormat "%h %l %u %t \"%r\" %>s %b" common 
CustomLog /logs/path/ common

The resulting log file will be /logs/path/http.log.

Note: See Security tips for HTTP Server for details on why your security could be compromised if the directory where log files are stored is writable by anyone other than the user that starts the server. 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).
Note: When possible, you should use CustomLog in place of TransferLog.