Russian Apache: Configuration

[an error occurred while processing the directive] How to Configure (ver. PL18 and newer)

All the aforementioned capabilities of the server are adjusted via config files. The directives used for this purpose are described below.

(Configuring of old versions - PL16 and earlier - is described in a separate document.)

Some Notes

All directives, except for CharsetDecl and CharsetRecodeTable, may be specified wherever desirable: in the configuration of the server, virtual server, in <Directory>, <Location>, or .htaccess. The CharsetDecl and CharsetRecodeTable directives may be given only in the configuration of the server or virtual server.
When directives are used in <Directory>, <Location>, or .htaccess, the following rule applies: if some directive (for example, CharsetAgent) is defined, all the "upper-level" directives with this name are cancelled. This behavior differs from Apache's standard behavior, where the contents of the directives are merged - that is, a definition in .htaccess works exactly as if this directive were used right after the directive with the same name in httpd.conf. This deviation from the standard is very easy to explain: if we can override, emulation of merging is very simple (one should just copy the relevant entries from the higher-level .htaccess or from httpd.conf), but the converse is not true.

Directives Used for Configuration

Charset (Encoding) and Recoding Table Declarations

CharsetDecl

Serves to declare the charset (in Russia, the term encoding is the established one) and to specify the corresponding language. In further directives, one may mention only one of the names earlier declared as the charset name.
Context: server, virtual server
Default: no defaults
Syntax:

       CharsetDecl CharsetName Language [Flags]

CharsetName

The official name of the encoding (for example, windows-1251, koi8-r, ibm866, iso8859-5, etc.). It is used in other directives for references to this encoding and in the Content-type: text/html; charset=CharsetName header when the document is given to the client.

Language

Name of the language to which this encoding corresponds. This name should be defined within conf/srm.conf in the AddLanguage and LanguagePriority directives.

Flags

Supported since ver. PL22. An optional field describing the parameters of the given charset. Possible values:

S - (Suppress) - to suppress the output of charset=... for the given charset in the HTTP response.

Examples:

 CharsetDecl iso-8859-5  ru
 CharsetDecl ibm866  ru
 CharsetDecl windows-1251  ru
 CharsetDecl koi8-r  ru
 CharsetDecl koi7 ru S

Each directive describes only one charset. If there are several virtual servers, each of them inherits the charset descriptions from the main server only if not a single charset is described in the <VirtualServer> directive and not a single CharsetRecodeTable directive is present.
The CharsetDecl directives should precede all other directives of the module in the config file.

CharsetRecodeTable Serves for describing the rules of conversion from one encoding to another.
Context: server, virtual server
Default: no defaults
Syntax:

 CharsetRecodeTable Charset1 Charset2 table_from [table_to]

Charset1, Charset2: Two charset names (earlier described by the CharsetDecl directive) between which the recoding takes place.
table_from: The name of the file containing the table that describes the conversion from Charset1 to Charset2. The filename is specified in relation to the root directory of the server ($SERVERROOT).
table_to: The name of the file containing the table that describes the conversion from Charset2 to Charset1. It may be absent; in this case, the server will automatically generate the reverse table from table_from.

For each pair of charsets, two equivalent CharsetRecodeTable descriptions are possible. The two directives given below have a fully identical effect:

 CharsetRecodeTable koi8-r windows-1251 koi-win.tab win-koi.tab
 CharsetRecodeTable windows-1251 koi8-r win-koi.tab koi-win.tab

Which of them is to be used is up to one's taste.

If several equivalent directives are specified in the server configuration, only the last one will be used in further work.

If the configuration of the virtual server contains at least one CharsetDecl or CharsetRecodeTable directive, the CharsetDecl/CharsetRecodeTable descriptions are not inherited from the main server.

CharsetWideRecodeTable

Serves for describing the rules of recoding in the "character -> string" format (e.g., for supporting VOLAPUK).
Context: server, virtual server
Default: no defaults
Syntax:

 CharsetWideRecodeTable CharsetFrom CharsetTo table

CharsetFrom, CharsetTo: Two charset names (earlier described by the CharsetDecl directive) between which the recoding described by the rule takes place.
table: The name of the file containing the table that describes the recoding from Charset1 to Charset2. The filename is specified in relation to the root directory of the server ($SERVERROOT). The file format is very simple: each line consists of a letter to be recoded, a space character, and the corresponding string.

For example:

 CharsetWideRecodeTable koi8-r koi7 conf/koi-tran.tab

If several equivalent directives are specified in the server configuration, only the last one will be used in further work.

In constrast to the CharsetRecodeTable directive, the reverse recoding table (from CharsetTo to CharsetFrom) is not constructed automatically.

CharsetAlias

Serves for describing the aliases of the charsets specified.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults
Syntax:

 CharsetAlias Official_Name Alias1 Alias2 Alias3 ...

Official_Name

The official name of the charset in question. Should be defined prior to this directive by the CharsetDecl directive.

Alias1 Alias2 ...

The aliases for the given charset.

Examples:

 CharsetAlias iso_8859-5:1988 iso-ir-144 iso_8859-5 cyrillic iso-8859-5
 CharsetAlias iso_8859-5:1988 iso8859-5 iso-8859.5 iso8859.5 iso
 CharsetAlias ibm866 csibm866 866 cp866 x-cp866 x-ibm866 cp-866 alt
 CharsetAlias windows-1251 win x-cp1251 cp1251 cp-1251

Aliases are used for determination of the client's encoding by the Accept: and Accept-Charset: headers, by the server-hostname prefix, or by the URI prefix (see the CharsetSelectionOrder directive).

Directives Responsible for Determination of the Client's Encoding

CharsetSelectionOrder

This directive specifies the order in which the server applies the rules that determine the necessary charset for providing the document to the client.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: CharsetSelectionOrder Portnumber Hostname Dirprefix Useragent
Syntax:

 CharsetSelectionOrder Rule1 Rule2 Rule3 ...

Rule1, Rule2, Rule3

the string specifying the order in which the server analyzes different parameters of the request with the aim of determining the client's preferences. As the Rule name, one may use

Portnumber - the charset is determined according to the number of the port that was addressed. The correspondence between the encoding and the port number is described by the CharsetByPort directive. The possibility to associate a port number with an encoding has appeared since ver. PL20.2.
Hostname - the charset is determined by a substring in the server hostname. That is, if the server hostname (up to the first period) begins from a charset name or alias, this charset will be selected as the client's one (that is, if we address the win-www.domain host, the encoding with the name/alias 'win' will be selected).
Dirprefix - the charset is determined according to the directory prefix. That is, if the first part of the URI (between the first and second slash or between /~username/ and the third slash) matches the name or alias of some charset, this will be the charset selected as the client's one.
Useragent - the charset is determined according to the User-Agent HTTP header (see the CharsetAgent directive).

Notes on the Use of This Directive
To determine the charset that will be used to send the document to the user, we first analyze the Accept-Charset and Accept HTTP headers (the second one is analyzed only if this possibility is provided during server compilation, see installation instructions). If these headers are present and the charset requested is known to the (virtual) server, the document will be sent in accordance with the client's desire. If the server does not recognize the requested charset and "any" charset (Accept-Charset: *) is not requested, the behavior of the server depends on the presence of the CharsetErrReject flag: if it is set to On, the server will return an error to the user.

If the charset cannot be determined by Accept-Charset, the serves makes an attempt to determine it in accordance with the CharsetSelectionOrder directive in the order described by this directive.
To determine (establish) it by the hostname, the first characters of the server's (virtual server's) hostname should match the name or alias of some charset that is known to the server.
To establish the charset by the directory prefix, the name or alias of some charset should match the first element of the path in the URL (for a request like /~username/path/to/file.html, they should match the first element of the path after ~username).
To determine the client's charset by the User-Agent HTTP header (that is, by the user's WWW browser), the server searches the User-Agent header for one of the substrings specified in the CharsetAgent directive.

CharsetPriority

Serves for setting the priorities of the charsets configured. It may be of importance if the client's request specifies equal weight coefficients for different charsets.
The highest-priority charset among those described by this directive will be used as the default one if such a default charset was set by the CharsetDefault directive.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults
Syntax:

 CharsetPriority Charset1 Charset2 Charset3 ...

Charset1 Charset2 ..

The charset names are mentioned in the order of decreasing priority (the leftmost one has the highest priority). All the charset names should be defined prior to this directive by the CharsetDecl directive.

Example:

     CharsetPriority windows-1251 koi8-r ibm866

Here, the charset names should be only official names rather than aliases.

CharsetDefault

Sets the default charset name for the given server.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: If CharsetDefault is not defined but CharsetPriotity is defined, the highest-priority charset from CharsetPriority will be used.
Syntax:

 CharsetDefault Charset_Name

Charset_Name: The official default charset name for the given server defined by the CharsetDecl directive.

Example:

 CharsetDefault koi8-r

This is the charset that will be provided to the client if all other ways of charset determination fail to work.

CharsetByPort (supported since ver. PL20.2)

This directive allows one to associate the number of a TCP port with an encoding.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults
Syntax:

 CharsetByPort Charset_Name port_number

Charset_Name: The name of the charset described by the CharsetDecl directive.
port_number: The number of the port.

Example:

 CharsetByPort koi8-r 8101

(if port 8101 is addressed, the koi8-r encoding is to be used).
Attention: this directive is closely related to the CharsetSelectionOrder directive. For example, if you have CharsetSelectionOrder Hostname, the CharsetPort directive has no effect on the server behavior (just like CharsetAgent etc.).

CharsetAgent

Sets the charset that may be used for finding the client-identifying substring in the client's request. The server searches for this substring in the User-Agent field of the request.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults
Syntax:

 CharsetAgent Charset_Name Pattern1 Pattern2 Pattern3 ...

Charset_Name

The official name of the charset

Pattern1 Pattern2 ...

The patterns for search in the User-Agent field of the client's request.

Examples:

 CharsetAgent windows-1251 AIR_Mosaic IWENG/1 MSIE WinMosaic (Windows (WinNT;
 CharsetAgent windows-1251 (Win16; (Win95; (16-bit)
 CharsetAgent koi8-r Arena Ariadna Macintosh OmniWeb Sextant PRD (X11
 CharsetAgent ibm866 DosLynx

Each Pattern is a substring rather than a regexp. If the User-Agent: header contains several substrings declared by the CharsetAgent directive, then the longest matching substring will be taken into account.

CharsetStrictURIMatch (supported since ver. PL21.3)

Specifies the required degree of matching for the rules used for comparing the hostname/dirname with the names of known encodings during charset selection by Hostname/Dirprefix
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: CharsetStrictURIMatch Off
Syntax:

CharsetStrictURIMatch On|Off

Off: In the Off mode, the encoding may be selected by the hostname/directory name if the first few characters of Hostname/Dirname match the name/alias of some encoding. For example, if the server knows the "win" encoding, it will select this encoding when addressing the /winnuke/ directory (naturally, in accordance with the CharsetSelectionOrder directive).
On: In this mode, the behavior of the server is more rigorous. It will check for matching between the encoding name and the whole host part in the server name/whole directory name. That is, knowing the "win" encoding and addressing http://winnuke.somewhere.domain, the server will not select the encoding by the hostname. The same applies to directory names.

Rules for Processing Local Files

CharsetSourceEnc

Sets the charset used for storing documents on disk.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults
Syntax:

 CharsetSourceEnc Charsetname

Charsetname: The name of the charset earlier described by the CharsetDecl directive.

This directive allows one to specify the encoding of HTML/CGI/SSI files on the disk. It may be set in .htaccess as well; thus, the tree of documents may be stored on disk in an arbitrary mixture of encodings. See also the CharsetByExtension directive. If the file storage encoding cannot be determined (that is, neither the CharsetSourceEnc directive nor the CharsetByExtension directive for the given extension are specified), the server will return an error message to the client and place the relevant information in error_log.

CharsetByExtension

This directive allows one to re-establish the charset for files with a certain extension.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults
Syntax:

 CharsetByExtension Charsetname .ext1 .ext2 ....

Charsetname: The name of the charset earlier described by the CharsetDecl directive
ext1,ext2,...: The list of extensions for files whose encoding will be regarded as Charsetname. The starting period in the extension may be either typed or not.

This directive allows one to specify the encoding of files with a definite extension. Its priority is higher than that of CharsetSourceEnc. If it is not defined for a given directory, the server uses (with the same higher priority) the "higher-level" definition (from .htaccess in a higher-level directory or from httpd.conf). To cancel a higher-level definition, one should use an empty CharsetByExtension directive. The file extension may contain any characters, including the period. The use of the slash character as part of the extension is senseless, because Apache believes that a slash may not be part of a filename.

CharsetProcessType (supported since ver. PL21.2)

This directive allows one to tell the server that some additional MIME types other than text/* should be recoded. Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults, but the server will always recode the text/* type
Syntax:

 CharsetProcessType mime-type

mime-type: The MIME type to be also recoded (in the type/ or type/subtype form).

In some rare cases, one has to recode some additional files aside from those with the MIME type text/*. In such cases, the MIME types of these files should be specified by this directive. One may mention both particular types (for example, image/jpeg) and whole classes (image/).

Example:

 CharsetProcessType image/jpeg application/

CharsetBrokenAccept (supported since ver. PL21.2)

This directive allows one to specify the User-Agent/Accept-Charset combination that should be ignored during determination of the client's encoding.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults
Syntax:

 CharsetBrokenAccept Agent-Substring accept_charset_string

Agent-Substring: A substring in the User-Agent header (i.e., in the type of the client's software).
accept_charset_string: The whole string from the Accept-Charset header of the given client's software.

If the User-Agent header contains the Agent-Substring substring and the Accept-Charset header received from the client fully matches accept_charset_string, the server will ignore the Accept-Charset header received from the client and try to determine the encoding by some other attributes.

This directive became necessary after the appearance of Netscape Communicator 4.x: by default, this program sends the string "iso-8859-1,*,utf-8" in the Accept-Charset header. If one of the charsets configured has the name of iso-8859-1, the server will always show this encoding to the client, which is not always right.

Example:

 CharsetBrokenAccept "Mozilla/4." "iso-8859-1,*,utf-8"

AddHandler strip-meta-http

This directive "activates" removal of the <META HTTP-EQUIV=..> tag from HTML files when they are being sent to the client.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults
Syntax:

 AddHandler strip-meta-http .ext1 .ext2 .....

AddHandler strip-meta-http: These are "magic words" (for explanation, see Apache's documentation). Actually, AddHandler is the directive of Apache's mime_module, and strip-meta-http is the name of the handler.
ext1, ext2: The list of extensions specifying the files from which <META HTTP-EQUIV...> should be removed. These files will be processed as usual plain HTML (that is, rather than CGI or.shtml, depending on the extensions).

This directive is aimed at "turning on" the removal of <META HTTP-EQUIV...> tags from the documents showed to the clients. These tags are inserted, for example, by Microsoft FrontPage. The reason why these tags should be removed is described in a separate document. If AddHandler specifies several handlers for the same extension, the server will activate one of them depending on the configuration.

Miscellaneous

CharsetBadAgent

Some client programs inadequately react to MIME, for example, when they receive a header like

 Content-type: text/html; charset=koi8-r; level=3

To prevent the server from sending charset=... to such client programs, these clients should be described by the CharsetBadAgent directive.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults
Syntax:

 CharsetBadAgent Pattern1 Pattern2 Pattern3 ...

Pattern1 Pattern2 ...: Substrings in the User-agent field of the client's request, such that the server will not send charset=... upon finding one of them.
Example:: BadAgent lynx/2.1 arena

Each Pattern is a substring rather than a regexp.

As Andrey Chernov rightly noted, specifying only the browser name without the actual version in this directive probably will mean future trouble. Unfortunately, up to ver. PL14 inclusive, the configuration file distributed together with Apache-RUS contained this error: Lynx and MSIE were specified as Bad Agents. Since ver. PL15, this error has been removed. The correct entry (at present) looks as follows:

 CharsetBadAgent arena Lynx/2.0 Lynx/2.1 Lynx/2.2 Lynx/2.3 Lynx/2.4 "MSIE 2.0;"

CharsetErrReject

This directive specifies the server's actions upon receiving an unknown charset in the client's request.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: CharestErrReject Off
Syntax:

 CharsetErrReject On|Off

When this parameter is set to On, the server will not send the document to the client if it cannot satisfy the request received in the Accept/Accept-Charset headers: the client will receive a message that there was an error in the request. When the parameter is set to Off, the server will try to determine the charset in some other way (see the CharsetSelectionOrder directive) and send the document in the form thus obtained.

CharsetMatchLanguage

This directive specifies the cases when the server will provide charset=xxx in the Content-Type: header.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: CharsetMatchLanguage On
Syntax:

 CharsetMatchLanguage On|Off

When this parameter is set to On (the default value), the server will include charset=xxx in the Content-Type header if the following three conditions are simultaneously satisfied:

The client's browser is not a Bad Agent
The MultiViews option is on
The language described by the AddLanguage directive for this document type is the same as the language described for the charset in question by the CharsetDecl directive.

When this flag is set to Off, the server checks only if the first condition (the correspondence between User-Agent and the Bad Agent list) is satisfied.

CharsetRecodeHeaders (supported since ver. PL20)

This directive turns on the recoding of headers that are included in the HTTP response.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: CharsetRecodeHeaders Off
Syntax:

 CharsetRecodeHeaders On|Off

When this parameter is set to On, the headers provided by the server will be recoded. By default, no such recoding is conducted, because earlier versions did not recode them, and some serious compatibility problems may arise. This directive should be used if headers may contain a Russian text (or, in general, a text in another language that should be recoded), smth like Location: /some.cgi?��.

CharsetTurnOff (supported since ver. PL20)

This directive turns the whole charset-processing module off. That is, there will be no recoding at all for the given <Directory>, <Location>, etc.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: CharsetTurnOff Off
Syntax:

 CharsetTurnOff On|Off

CharsetRecodeFilenames (supported since ver. PL21)

This directive turns on the recoding of filenames in the HTTP request.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: CharsetRecodeFilenames On (for compatibility with earlier versions)
Syntax:

 CharsetRecodeFilenames On|Off

When this parameter is set to On, the filenames in the URL will be recoded. By default, such a recoding does take place (for compatibility with earlier versions), but it is potentially harmful and works in a strange way: all Alias, Redirect, etc. directives receive the nonrecoded name, the permissions check is also conducted for the nonrecoded name, and only then it is recoded. Therefore, the default behavior may be changed after we wait a certain time.
It is not recommended to use recoding of filenames. See also some notes on this subject.

CharsetSoftRedirect (supported since ver. PL21.1)

This directive serves for substituting the Redirect directive (from mod_alias) in the case of work with recoding according to port number.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults
Syntax:

 CharsetSoftRedirect [status] old-url new-url

Parameters:

status

(optional parameter) - describes the HTTP status code that will be sent to the client. Its possible values are as follows:

permanent - Redirect returns status 301 (permanent redirect)
temp - Redirect returns status 302 (temporary redirect) - the default value
seeother - status 303 (See Other)
gone - status 410 (Document removed) - indicates that the document no longer exists. In this case, the third argument (new_url) should be absent.

old-url

the "old" URL - the one to be redirected. Specified in relation to the server root

new-url

the "new" URL - the one to be used instead of the old one.

This directive serves for substituting the standard Redirect directive in the case of recoding according to port number. The problem with the standard Redirect is that new-url should be specified as the complete URL, with the protocol, server name, and port number indicated. At the same time, if the document is redirected "within the given server", the protocol, the server name, and the port number seldom change for the same client but may differ for different clients. CharsetSoftRedirect substitutes the current port and server hostname during redirect.

Example:

 CharsetSoftRedirect temp /index.html /new-index.html

CharsetSoftRedirectPermanent (supported since ver. PL21.1)

This directive serves for substituting the RedirectPermanent directive (from mod_alias) in the case of work with recoding according to port number.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults
Syntax:

 CharsetSoftRedirectPermanent old-url new-url

Parameters:

old-url: the "old" URL - the one to be redicted. Specified in relation to the server root
new-url: the "new" URL - the one to be used instead of the old one.

This directive is similar to CharsetSoftRedirect permanent old-url new-url

Example:

 CharsetSoftRedirectPermanent /index.html /new-index.html

CharsetSoftRedirectTemp (supported since ver. PL21.1)

This directive serves for substituting the RedirectTemp directive (from mod_alias) in the case of work with recoding according to port number.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: no defaults
Syntax:

 CharsetSoftRedirectTemp old-url new-url

Parameters:

old-url: the "old" URL - the one to be redicted. Specified in relation to the server root
new-url: the "new" URL - the one to be used instead of the old one.

This directive is similar to CharsetSoftRedirect temp old-url new-url

Example:

 CharsetSoftRedirectTemp /index.html /new-index.html

CharsetOverrideExpires (supported since ver. PL21.2)

This directive specifies the server behavior in the case when the document should be made noncacheable with the use of the Expires: header but this header has already been inserted by some other module.
Context: server, virtual server, <Directory>, <Location>, .htaccess
Default: On
Syntax:

CharsetOverrideExpires On|Off

In the On mode, the server will substitute the contents of the Expires header by its own (usually 01 Jan 1970) in case the document currently sent should be made noncacheable. In the Off mode, the contents set by other modules or by a CGI script will be preserved.

[an error occurred while processing the directive]