Russian Apache Switch to English
Switch to Russian koi8-r
windows=1251
cp-866
iso8859-5
Russian Apache Now it works Notes Download How to install How to configure Status and support
Brief intro FAQ Mailing list Acknowlegments Site search Powered by Russian Apache
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
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:
  1. 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:
  1. The client's browser is not a Bad Agent
  2. The MultiViews option is on
  3. 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.






:

[ Russian Apache ] [ How it works ] [ Some notes ] [ Download ] [ How to install ] [ How to setup ] [ Status & support ]
[ Introduction ] [ FAQ ] [ Mailing list ] [ Acknowledgments ] [ Search ] [ Powered by Russian Apache ]

"Russian Apache" includes software developed by the Apache Group for use in the Apache HTTP server project (http://www.apache.org/)
See Apache LICENSE.
Copyright (C) 1995-2001 The Apache Group. All rights reserved.
Copyright (C) 1996 Dm. Kryukov; Copyright (C) 1997-2009 Alex Tutubalin. Design (C) 1998 Max Smolev.