From 812876ad84ade0a7181de71c1feea1e35c2c0f11 Mon Sep 17 00:00:00 2001 From: Henning Brauer Date: Mon, 17 Nov 2003 19:13:44 +0000 Subject: these are gone since some time too --- .../httpd/htdocs/manual/content-negotiation.html | 674 --------------------- .../httpd/htdocs/manual/mod/mod_log_config.html | 408 ------------- 2 files changed, 1082 deletions(-) delete mode 100644 usr.sbin/httpd/htdocs/manual/content-negotiation.html delete mode 100644 usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html (limited to 'usr.sbin/httpd/htdocs') diff --git a/usr.sbin/httpd/htdocs/manual/content-negotiation.html b/usr.sbin/httpd/htdocs/manual/content-negotiation.html deleted file mode 100644 index 909d9f90155..00000000000 --- a/usr.sbin/httpd/htdocs/manual/content-negotiation.html +++ /dev/null @@ -1,674 +0,0 @@ - - - - - - - Apache Content Negotiation - - - - -

- -

Apache HTTP Server

- - - -

Content Negotiation

- -

Apache's support for content negotiation has been updated to - meet the HTTP/1.1 specification. It can choose the best - representation of a resource based on the browser-supplied - preferences for media type, languages, character set and - encoding. It is also implements a couple of features to give - more intelligent handling of requests from browsers which send - incomplete negotiation information.

- -

Content negotiation is provided by the mod_negotiation module, - which is compiled in by default.

- -

About Content Negotiation

- -

A resource may be available in several different - representations. For example, it might be available in - different languages or different media types, or a combination. - One way of selecting the most appropriate choice is to give the - user an index page, and let them select. However it is often - possible for the server to choose automatically. This works - because browsers can send as part of each request information - about what representations they prefer. For example, a browser - could indicate that it would like to see information in French, - if possible, else English will do. Browsers indicate their - preferences by headers in the request. To request only French - representations, the browser would send

-  Accept-Language: fr
-

- -

Note that this preference will only be applied when there is - a choice of representations and they vary by language.

- -

As an example of a more complex request, this browser has - been configured to accept French and English, but prefer - French, and to accept various media types, preferring HTML over - plain text or other text types, and preferring GIF or JPEG over - other media types, but also allowing any other media type as a - last resort:

-  Accept-Language: fr; q=1.0, en; q=0.5
-  Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
-        image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
-

- Apache 1.2 supports 'server driven' content negotiation, as - defined in the HTTP/1.1 specification. It fully supports the - Accept, Accept-Language, Accept-Charset and Accept-Encoding - request headers. Apache 1.3.4 also supports 'transparent' - content negotiation, which is an experimental negotiation - protocol defined in RFC 2295 and RFC 2296. It does not offer - support for 'feature negotiation' as defined in these RFCs. - -

A resource is a conceptual entity - identified by a URI (RFC 2396). An HTTP server like Apache - provides access to representations of the - resource(s) within its namespace, with each representation in - the form of a sequence of bytes with a defined media type, - character set, encoding, etc. Each resource may be associated - with zero, one, or more than one representation at any given - time. If multiple representations are available, the resource - is referred to as negotiable and each of its - representations is termed a variant. The ways - in which the variants for a negotiable resource vary are called - the dimensions of negotiation.

- -

Negotiation in Apache

- -

In order to negotiate a resource, the server needs to be - given information about each of the variants. This is done in - one of two ways:

- -

Using a type map (i.e., a *.var - file) which names the files containing the variants - explicitly, or
Using a 'MultiViews' search, where the server does an - implicit filename pattern match and chooses from among the - results.

- -

Using a type-map file

- -

A type map is a document which is associated with the - handler named type-map (or, for - backwards-compatibility with older Apache configurations, the - mime type application/x-type-map). Note that to - use this feature, you must have a handler set in the - configuration that defines a file suffix as - type-map; this is best done with a

-  AddHandler type-map .var
-

- in the server configuration file. See the comments in the - sample config file for more details. - -

Type map files have an entry for each available variant; - these entries consist of contiguous HTTP-format header lines. - Entries for different variants are separated by blank lines. - Blank lines are illegal within an entry. It is conventional to - begin a map file with an entry for the combined entity as a - whole (although this is not required, and if present will be - ignored). An example map file is:

-  URI: foo
-
-  URI: foo.en.html
-  Content-type: text/html
-  Content-language: en
-
-  URI: foo.fr.de.html
-  Content-type: text/html;charset=iso-8859-2
-  Content-language: fr, de
-

- If the variants have different source qualities, that may be - indicated by the "qs" parameter to the media type, as in this - picture (available as jpeg, gif, or ASCII-art): -

-  URI: foo
-
-  URI: foo.jpeg
-  Content-type: image/jpeg; qs=0.8
-
-  URI: foo.gif
-  Content-type: image/gif; qs=0.5
-
-  URI: foo.txt
-  Content-type: text/plain; qs=0.01
-

- -

qs values can vary in the range 0.000 to 1.000. Note that - any variant with a qs value of 0.000 will never be chosen. - Variants with no 'qs' parameter value are given a qs factor of - 1.0. The qs parameter indicates the relative 'quality' of this - variant compared to the other available variants, independent - of the client's capabilities. For example, a jpeg file is - usually of higher source quality than an ascii file if it is - attempting to represent a photograph. However, if the resource - being represented is an original ascii art, then an ascii - representation would have a higher source quality than a jpeg - representation. A qs value is therefore specific to a given - variant depending on the nature of the resource it - represents.

- -

The full list of headers recognized is:

- -

URI:: uri of the file containing the variant (of the given - media type, encoded with the given content encoding). These - are interpreted as URLs relative to the map file; they must - be on the same server (!), and they must refer to files to - which the client would be granted access if they were to be - requested directly.
Content-Type:: media type --- charset, level and "qs" parameters may be - given. These are often referred to as MIME types; typical - media types are image/gif, - text/plain, or - text/html; level=3.
Content-Language:: The languages of the variant, specified as an Internet - standard language tag from RFC 1766 (e.g., - en for English, kr for Korean, - etc.).
Content-Encoding:: If the file is compressed, or otherwise encoded, rather - than containing the actual raw data, this says how that was - done. Apache only recognizes encodings that are defined by an - AddEncoding - directive. This normally includes the encodings - x-compress for compress'd files, and - x-gzip for gzip'd files. The x- - prefix is ignored for encoding comparisons.
Content-Length:: The size of the file. Specifying content lengths in the - type-map allows the server to compare file sizes without - checking the actual files.
Description:: A human-readable textual description of the variant. If - Apache cannot find any appropriate variant to return, it will - return an error response which lists all available variants - instead. Such a variant list will include the human-readable - variant descriptions.

- -

Multiviews

- -

MultiViews is a per-directory option, meaning - it can be set with an Options directive within a - <Directory>, <Location> - or <Files> section in - access.conf, or (if AllowOverride is - properly set) in .htaccess files. Note that - Options All does not set MultiViews; - you have to ask for it by name.

- -

The effect of MultiViews is as follows: if the - server receives a request for /some/dir/foo, if - /some/dir has MultiViews enabled, and - /some/dir/foo does not exist, then the - server reads the directory looking for files named foo.*, and - effectively fakes up a type map which names all those files, - assigning them the same media types and content-encodings it - would have if the client had asked for one of them by name. It - then chooses the best match to the client's requirements.

- -

MultiViews may also apply to searches for the - file named by the DirectoryIndex directive, if the - server is trying to index a directory. If the configuration - files specify

-  DirectoryIndex index
-

- then the server will arbitrate between index.html - and index.html3 if both are present. If neither - are present, and index.cgi is there, the server - will run it. - -

If one of the files found when reading the directive is a - CGI script, it's not obvious what should happen. The code gives - that case special treatment --- if the request was a POST, or a - GET with QUERY_ARGS or PATH_INFO, the script is given an - extremely high quality rating, and generally invoked; otherwise - it is given an extremely low quality rating, which generally - causes one of the other views (if any) to be retrieved.

- -

The Negotiation Methods

- After Apache has obtained a list of the variants for a given - resource, either from a type-map file or from the filenames in - the directory, it invokes one of two methods to decide on the - 'best' variant to return, if any. It is not necessary to know - any of the details of how negotiation actually takes place in - order to use Apache's content negotiation features. However the - rest of this document explains the methods used for those - interested. - -

There are two negotiation methods:

- -

Server driven negotiation with the Apache - algorithm is used in the normal case. The Apache - algorithm is explained in more detail below. When this - algorithm is used, Apache can sometimes 'fiddle' the quality - factor of a particular dimension to achieve a better result. - The ways Apache can fiddle quality factors is explained in - more detail below.
Transparent content negotiation is used - when the browser specifically requests this through the - mechanism defined in RFC 2295. This negotiation method gives - the browser full control over deciding on the 'best' variant, - the result is therefore dependent on the specific algorithms - used by the browser. As part of the transparent negotiation - process, the browser can ask Apache to run the 'remote - variant selection algorithm' defined in RFC 2296.

- -

Dimensions of Negotiation

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Dimension	Notes
Media Type	Browser indicates preferences with the Accept header - field. Each item can have an associated quality factor. - Variant description can also have a quality factor (the - "qs" parameter).
Language	Browser indicates preferences with the Accept-Language - header field. Each item can have a quality factor. Variants - can be associated with none, one or more than one - language.
Encoding	Browser indicates preference with the Accept-Encoding - header field. Each item can have a quality factor.
Charset	Browser indicates preference with the Accept-Charset - header field. Each item can have a quality factor. Variants - can indicate a charset as a parameter of the media - type.

- -

Apache Negotiation Algorithm

- -

Apache can use the following algorithm to select the 'best' - variant (if any) to return to the browser. This algorithm is - not further configurable. It operates as follows:

- -

First, for each dimension of the negotiation, check the - appropriate Accept* header field and assign a - quality to each variant. If the Accept* header for - any dimension implies that this variant is not acceptable, - eliminate it. If no variants remain, go to step 4.
- Select the 'best' variant by a process of elimination. Each - of the following tests is applied in order. Any variants - not selected at each test are eliminated. After each test, - if only one variant remains, select it as the best match - and proceed to step 3. If more than one variant remains, - move on to the next test. - -
1. Multiply the quality factor from the Accept header - with the quality-of-source factor for this variant's - media type, and select the variants with the highest - value.
2. Select the variants with the highest language quality - factor.
3. Select the variants with the best language match, - using either the order of languages in the - Accept-Language header (if present), or else the order of - languages in the LanguagePriority directive - (if present).
4. Select the variants with the highest 'level' media - parameter (used to give the version of text/html media - types).
5. Select variants with the best charset media - parameters, as given on the Accept-Charset header line. - Charset ISO-8859-1 is acceptable unless explicitly - excluded. Variants with a text/* media type - but not explicitly associated with a particular charset - are assumed to be in ISO-8859-1.
6. Select those variants which have associated charset - media parameters that are not ISO-8859-1. If - there are no such variants, select all variants - instead.
7. Select the variants with the best encoding. If there - are variants with an encoding that is acceptable to the - user-agent, select only these variants. Otherwise if - there is a mix of encoded and non-encoded variants, - select only the unencoded variants. If either all - variants are encoded or all variants are not encoded, - select all variants.
8. Select the variants with the smallest content - length.
9. Select the first variant of those remaining. This - will be either the first listed in the type-map file, or - when variants are read from the directory, the one whose - file name comes first when sorted using ASCII code - order.
-
The algorithm has now selected one 'best' variant, so - return it as the response. The HTTP response header Vary is - set to indicate the dimensions of negotiation (browsers and - caches can use this information when caching the resource). - End.
To get here means no variant was selected (because none - are acceptable to the browser). Return a 406 status (meaning - "No acceptable representation") with a response body - consisting of an HTML document listing the available - variants. Also set the HTTP Vary header to indicate the - dimensions of variance.
- -
You should be aware that the error message returned by Apache is - neccessarily rather terse and might confuse some users (even though it - lists the available alternatives). If you want to avoid users seeing this - error page, you should organize your documents such that a document in a - default language (or with a default encoding etc.) is always returned if a - document is not available in any of the languages, encodings etc. the - browser asked for.
- -
In particular, if you want a document in a default language to - be returned if a document is not available in any of the languages - a browser asked for, you should create a document with no language - attribute set. See Variants with no - Language below for details.

- -

Fiddling with Quality - Values

- -

Apache sometimes changes the quality values from what would - be expected by a strict interpretation of the Apache - negotiation algorithm above. This is to get a better result - from the algorithm for browsers which do not send full or - accurate information. Some of the most popular browsers send - Accept header information which would otherwise result in the - selection of the wrong variant in many cases. If a browser - sends full and correct information these fiddles will not be - applied.

- -

Media Types and Wildcards

- -

The Accept: request header indicates preferences for media - types. It can also include 'wildcard' media types, such as - "image/*" or "*/*" where the * matches any string. So a request - including:

-  Accept: image/*, */*
-

- would indicate that any type starting "image/" is acceptable, - as is any other type (so the first "image/*" is redundant). - Some browsers routinely send wildcards in addition to explicit - types they can handle. For example: -

-  Accept: text/html, text/plain, image/gif, image/jpeg, */*
-

- The intention of this is to indicate that the explicitly listed - types are preferred, but if a different representation is - available, that is ok too. However under the basic algorithm, - as given above, the */* wildcard has exactly equal preference - to all the other types, so they are not being preferred. The - browser should really have sent a request with a lower quality - (preference) value for *.*, such as: -

-  Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
-

- The explicit types have no quality factor, so they default to a - preference of 1.0 (the highest). The wildcard */* is given a - low preference of 0.01, so other types will only be returned if - no variant matches an explicitly listed type. - -

If the Accept: header contains no q factors at all, - Apache sets the q value of "*/*", if present, to 0.01 to - emulate the desired behavior. It also sets the q value of - wildcards of the format "type/*" to 0.02 (so these are - preferred over matches against "*/*". If any media type on the - Accept: header contains a q factor, these special values are - not applied, so requests from browsers which send the - correct information to start with work as expected.

- -

Variants with no Language

- -

If some of the variants for a particular resource have a - language attribute, and some do not, those variants with no - language are given a very low language quality factor of - 0.001.

- -

The reason for setting this language quality factor for variant - with no language to a very low value is to allow for a default - variant which can be supplied if none of the other variants match - the browser's language preferences. This allows you to avoid users - seeing a "406" error page if their browser is set to only accept - languages which you do not offer for the ressource that was - requested.

- -

For example, consider the situation with Multiviews enabled and - three variants:

- -

foo.en.html, language en
foo.fr.html, language en
foo.html, no language

- -

The meaning of a variant with no language is that it is always - acceptable to the browser. If the request is for foo - and the Accept-Language header includes either en or fr (or both) - one of foo.en.html or foo.fr.html will be returned. If the browser - does not list either en or fr as acceptable, foo.html will be - returned instead. If the client requests foo.html - instead, then no negotation will occur since the exact match - will be returned. To avoid this problem, it is sometimes helpful - to name the "no language" variant foo.html.html to assure - that Multiviews and language negotiation will come into play.

- -

Extensions to Transparent Content Negotiation

- Apache extends the transparent content negotiation protocol - (RFC 2295) as follows. A new {encoding ..} element - is used in variant lists to label variants which are available - with a specific content-encoding only. The implementation of - the RVSA/1.0 algorithm (RFC 2296) is extended to recognize - encoded variants in the list, and to use them as candidate - variants whenever their encodings are acceptable according to - the Accept-Encoding request header. The RVSA/1.0 implementation - does not round computed quality factors to 5 decimal places - before choosing the best variant. - -

Note on hyperlinks and naming conventions

- -

If you are using language negotiation you can choose between - different naming conventions, because files can have more than - one extension, and the order of the extensions is normally - irrelevant (see mod_mime - documentation for details).

- -

A typical file has a MIME-type extension (e.g., - html), maybe an encoding extension (e.g., - gz), and of course a language extension - (e.g., en) when we have different - language variants of this file.

- -

Examples:

- -

foo.en.html
foo.html.en
foo.en.html.gz

- -

Here some more examples of filenames together with valid and - invalid hyperlinks:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Filename	Valid hyperlink	Invalid hyperlink
foo.html.en	foo - foo.html	-
foo.en.html	foo	foo.html
foo.html.en.gz	foo - foo.html	foo.gz - foo.html.gz
foo.en.html.gz	foo	foo.html - foo.html.gz - foo.gz
foo.gz.html.en	foo - foo.gz - foo.gz.html	foo.html
foo.html.gz.en	foo - foo.html - foo.html.gz	foo.gz

- -

Looking at the table above you will notice that it is always - possible to use the name without any extensions in an hyperlink - (e.g., foo). The advantage is that you - can hide the actual type of a document rsp. file and can change - it later, e.g., from html to - shtml or cgi without changing any - hyperlink references.

- -

If you want to continue to use a MIME-type in your - hyperlinks (e.g. foo.html) the language - extension (including an encoding extension if there is one) - must be on the right hand side of the MIME-type extension - (e.g., foo.html.en).

- -

Note on Caching

- -

When a cache stores a representation, it associates it with - the request URL. The next time that URL is requested, the cache - can use the stored representation. But, if the resource is - negotiable at the server, this might result in only the first - requested variant being cached and subsequent cache hits might - return the wrong response. To prevent this, Apache normally - marks all responses that are returned after content negotiation - as non-cacheable by HTTP/1.0 clients. Apache also supports the - HTTP/1.1 protocol features to allow caching of negotiated - responses.

- -

For requests which come from a HTTP/1.0 compliant client - (either a browser or a cache), the directive - CacheNegotiatedDocs can be used to allow caching of - responses which were subject to negotiation. This directive can - be given in the server config or virtual host, and takes no - arguments. It has no effect on requests from HTTP/1.1 clients. -

- -

Apache HTTP Server

- -

- - - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html b/usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html deleted file mode 100644 index 67627c51d6e..00000000000 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_log_config.html +++ /dev/null @@ -1,408 +0,0 @@ - - - - - - - Apache module mod_log_config - - - - -

- -

Apache HTTP Server Version 1.3

- - -

Module mod_log_config

- -

This module provides for logging of the requests made to the - server, using the Common Log Format or a user-specified - format.

- -

Status: Base
- Source File: - mod_log_config.c
- Module Identifier: - config_log_module
- Compatibility: Was an extension - module prior to Apache 1.2.

- -

Summary

- -

This module provides for flexible logging of client - requests. Logs are written in a customizable format, and may be - written directly to a file, or to an external program. - Conditional logging is provided so that individual requests may - be included or excluded from the logs based on characteristics - of the request.

- -

Three directives are provided by this module: - TransferLog to create a log file, - LogFormat to set a custom format, and - CustomLog to define a log file and format in one - step. The TransferLog and CustomLog - directives can be used multiple times in each server to cause - each request to be logged to multiple files.

- -

Directives

- -

CookieLog
CustomLog
LogFormat
TransferLog

- -

Custom Log Formats

- -

The format argument to the LogFormat and - CustomLog directives is a string. This string is - logged to the log file for each request. It can contain literal - characters copied into the log files and the c-type control - characters "\n" and "\t" to represent new-lines and tabs. - Literal quotes and back-slashes should be escaped with - back-slashes.

- -

The characteristics of the request itself are logged by - placing "%" directives in the format string, which are replaced - in the log file by the values as follows:

-%...a:          Remote IP-address
-%...A:          Local IP-address
-%...B:          Bytes sent, excluding HTTP headers.
-%...b:          Bytes sent, excluding HTTP headers. In CLF format
-        i.e. a '-' rather than a 0 when no bytes are sent.
-%...c:          Connection status when response is completed.
-                'X' = connection aborted before the response completed.
-                '+' = connection may be kept alive after the response is sent.
-                '-' = connection will be closed after the response is sent.
-%...{FOOBAR}e:  The contents of the environment variable FOOBAR
-%...f:          Filename
-%...h:          Remote host
-%...H       The request protocol
-%...{Foobar}i:  The contents of Foobar: header line(s) in the request
-                sent to the server.
-%...l:          Remote logname (from identd, if supplied)
-%...m       The request method
-%...{Foobar}n:  The contents of note "Foobar" from another module.
-%...{Foobar}o:  The contents of Foobar: header line(s) in the reply.
-%...p:          The canonical Port of the server serving the request
-%...P:          The process ID of the child that serviced the request.
-%...q       The query string (prepended with a ? if a query string exists,
-        otherwise an empty string)
-%...r:          First line of request
-%...s:          Status.  For requests that got internally redirected, this is
-                the status of the *original* request --- %...>s for the last.
-%...t:          Time, in common log format time format (standard english format)
-%...{format}t:  The time, in the form given by format, which should
-                be in strftime(3) format. (potentially localized)
-%...T:          The time taken to serve the request, in seconds.
-%...u:          Remote user (from auth; may be bogus if return status (%s) is 401)
-%...U:          The URL path requested, not including any query string.
-%...v:          The canonical ServerName of the server serving the request.
-%...V:          The server name according to the UseCanonicalName setting.
-

- -

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). 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.

- -

Note that there is no escaping performed on the strings from - %...r, %...i and %...o. This is mainly to comply with the - requirements of the Common Log Format. This implies that - clients can insert control characters into the log, so care - should be taken when dealing with raw log files.

- -

Some commonly used log format strings are:

- -

Common Log Format (CLF): "%h %l %u %t \"%r\" %>s %b"
Common Log Format with Virtual Host: "%v %h %l %u %t \"%r\" %>s %b"
NCSA extended/combined log format: "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" - \"%{User-agent}i\""
Referer log format: "%{Referer}i -> %U"
Agent (Browser) log format: "%{User-agent}i"

- -

Note that the canonical ServerName and Port of the server serving the - request are used for %v and %p - respectively. This happens regardless of the UseCanonicalName setting - because otherwise log analysis programs would have to duplicate - the entire vhost matching algorithm in order to decide what - host really served the request.

- -

Security Considerations

- -

See the security tips - document for details on why your security could be compromised - if the directory where logfiles are stored is writable by - anyone other than the user that starts the server.

- -

Compatibility notes

- -

This module is based on mod_log_config distributed with - previous Apache releases, now updated to handle multiple - logs. There is now no need to re-configure Apache to use - configuration log formats.
The module also implements the CookieLog - directive, used to log user-tracking information created by - mod_usertrack. The use of - CookieLog is deprecated, and a - CustomLog should be defined to log user-tracking - information instead.
As of Apache 1.3.5, this module allows conditional - logging based upon the setting of environment variables. That is, you - can control whether a request should be logged or not based - upon whether an arbitrary environment variable is defined or - not. This is configurable on a per-logfile - basis.
Beginning with Apache 1.3.5, the mod_log_config module - has also subsumed the RefererIgnore - functionality from mod_log_referer. The effect - of RefererIgnore can be achieved by combinations - of SetEnvIf - directives and conditional CustomLog - definitions.

- -

CookieLog - directive

- -

Syntax: CookieLog - filename
- Context: server config, virtual - host
- Module: mod_cookies
- Compatibility: Only available - in Apache 1.2 and above

- -

The CookieLog directive sets the filename for logging of - cookies. The filename is relative to the ServerRoot. This directive is - included only for compatibility with mod_cookies, and is deprecated.

- -

CustomLog directive

- -

Syntax: CustomLog - file|pipe format|nickname - [env=[!]environment-variable]
- Context: server config, virtual - host
- Status: Base
- Compatibility: Nickname only - available in Apache 1.3 or later. Conditional logging available - in 1.3.5 or later.
- Module: mod_log_config

- -

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.

- -

The first argument, which specifies the location to which - the logs will be written, can take on one of the following two - types of values:

- -

file: A filename, relative to the ServerRoot.
pipe: The pipe character "|", followed by the path - to a program to receive the log information on its standard - input. 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.

- -

The second argument specifies what will be written to the - log file. It can specify either a nickname defined by - a previous LogFormat directive, or it - can be an explicit format string as described in the - log formats section.

- -

For example, the following two sets of directives have - exactly the same effect:

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

- -

The third argument is optional and allows the decision on - whether or not to log a particular request to be based on the - presence or absence of a particular variable in the server - environment. 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. For - example, if you want to record requests for all GIF - images on your server in a separate logfile but not in your main - log, you can use:

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

- -

LogFormat - directive

- -

Syntax: LogFormat - format|nickname [nickname]
- Default: LogFormat "%h %l - %u %t \"%r\" %>s %b"
- Context: server config, virtual - host
- Status: Base
- Compatibility: Nickname only - available in Apache 1.3 or later
- Module: mod_log_config

- -

This directive specifies the format of the access log - file.

- -

The LogFormat directive can take one of two - forms. In the first form, where only one argument is specified, - this directive sets the log format which will be used by logs - specified in subsequent TransferLog - directives. The single argument can specify an explicit - format as discussed in custom log - formats section above. Alternatively, it can use a - nickname to refer to a log format defined in a - previous LogFormat directive as described - below.

- -

The second form of the LogFormat directive - associates an explicit format with a - nickname. This nickname can then be used in - subsequent LogFormat or CustomLog directives rather than - repeating the entire format string. A LogFormat - directive which 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. Therefore, it will not affect subsequent TransferLog directives.

- -

For example:

- - LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common - -

- -

TransferLog - directive

- -

Syntax: TransferLog - file|pipe
- Default: none
- Context: server config, virtual - host
- Status: Base
- Module: mod_log_config

- -

This directive has exactly the same arguments and effect as - the CustomLog directive, with the - exception that it does not allow the log format to be specified - explicitly or for conditional logging of requests. Instead, the - log format is determined by the most recently specified LogFormat directive (that does not define - a nickname). Common Log Format is used if no other format has - been specified.

- -

Example:

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

- -

Apache HTTP Server Version 1.3

- - - - -- cgit v1.2.3