From: Rich Bowen Date: Fri, 19 Jun 2026 14:22:34 +0000 (+0000) Subject: docs: howto/htaccess.xml editorial cleanup X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=1c6aa3f5bce50a95e2994d9c475820df21a3aea8;p=thirdparty%2Fapache%2Fhttpd.git docs: howto/htaccess.xml editorial cleanup - Update example log dates to 2026 - Change error log highlight blocks from language="config" to "sh" - Remove filler phrases: "in order to", "a lot of", "it is important to remember that", "simply" - Convert inline "Note that..." prose to blocks git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1935518 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/howto/htaccess.xml b/docs/manual/howto/htaccess.xml index 16c1d2a369..721d0071a5 100644 --- a/docs/manual/howto/htaccess.xml +++ b/docs/manual/howto/htaccess.xml @@ -76,9 +76,11 @@ configuration files directly.

if you would rather call the file .config then you can put the following in your server configuration file:

- + + AccessFileName ".config" - + +

Directives in .htaccess files use the same syntax as @@ -93,7 +95,7 @@ AccessFileName ".config" directives to permit (see below). If a directive is permitted, the documentation for that directive will contain an Override section, specifying what value must be in AllowOverride in order for that + module="core">AllowOverride for that directive to be permitted.

The default value of Override line reads FileInfo. Thus, you must have at least - AllowOverride FileInfo in order for this directive to be + AllowOverride FileInfo for this directive to be honored in .htaccess files.

@@ -145,35 +147,37 @@ AccessFileName ".config" .htaccess file is loaded every time a document is requested.

-

Further note that httpd must look for .htaccess files - in all higher-level directories, in order to have a full complement of - directives that it must apply. (See section on how +

Additionally, httpd must look for .htaccess files + in all higher-level directories to assemble the full set of applicable + directives. (See section on how directives are applied.) Thus, if a file is requested out of a directory /www/htdocs/example, httpd must look for the following files:

- + + /.htaccess /www/.htaccess /www/htdocs/.htaccess /www/htdocs/example/.htaccess - + +

And so, for each file access out of that directory, there are 4 additional file-system accesses, even if none of those files are - present. (Note that this would only be the case if + present. (This would only be the case if .htaccess files were enabled for /, which is not usually the case.)

Security: You are permitting users to modify server configuration, which may result in changes over which you have no control. Carefully consider whether you want to give - your users this privilege. Note also that giving users less + your users this privilege. Giving users less privileges than they need will lead to additional technical support requests. Make sure you clearly tell your users what level of privileges you have given them. Specifying exactly what you have set AllowOverride to, and pointing them - to the relevant documentation, will save yourself a lot of confusion + to the relevant documentation, prevents confusion later.

If you need to grant .htaccess access but want to @@ -183,56 +187,62 @@ AccessFileName ".config" finer-grained control than AllowOverride alone:

- + + # Allow only specific directives, not entire categories AllowOverride None AllowOverrideList Redirect RedirectMatch RewriteEngine RewriteRule RewriteCond - + +

With this configuration, any directive not explicitly listed will cause a server error if encountered in a .htaccess file. This is a useful middle ground between full override access and no override access.

-

Note that it is completely equivalent to put a .htaccess - file in a directory /www/htdocs/example containing a - directive, and to put that same directive in a Directory section - <Directory "/www/htdocs/example"> in your main server +

Placing a directive in a .htaccess + file in a directory /www/htdocs/example is completely equivalent to placing that same directive in a + <Directory "/www/htdocs/example"> section in your main server configuration:

.htaccess file in /www/htdocs/example:

Contents of .htaccess file in <code>/www/htdocs/example</code> - + + AddType text/example ".exm" - + + Section from your <code>httpd.conf</code> file - + + <Directory "/www/htdocs/example"> - AddType text/example ".exm" +AddType text/example ".exm" </Directory> - + +

The use of .htaccess files can be disabled completely by setting the AllowOverride directive to none:

- + + AllowOverride None - + +
How directives are applied

The configuration directives found in a .htaccess file are applied to the directory in which the .htaccess file - is found, and to all subdirectories thereof. However, it is important - to also remember that there may have been .htaccess files + is found, and to all subdirectories thereof. Remember that there may have been .htaccess files in directories higher up. Directives are applied in the order that they are found. Therefore, a .htaccess file in a particular directory may override directives found in .htaccess files @@ -245,21 +255,25 @@ AllowOverride None

In the directory /www/htdocs/example1 we have a .htaccess file containing the following:

- + + Options +ExecCGI - + + -

(Note: you must have "AllowOverride Options" in effect + You must have "AllowOverride Options" in effect to permit the use of the "Options" directive in - .htaccess files.)

+ .htaccess files.

In the directory /www/htdocs/example1/example2 we have a .htaccess file containing:

- + + Options Includes - + +

Because of this second .htaccess file, in the directory /www/htdocs/example1/example2, CGI execution is not @@ -282,15 +296,17 @@ Options Includes prevent script execution while allowing anything else to be set in .htaccess you can use:

- + + <Directory "/www/htdocs"> - AllowOverride All +AllowOverride All </Directory> <Location "/"> - Options +IncludesNoExec -ExecCGI +Options +IncludesNoExec -ExecCGI </Location> - + + This example assumes that your DocumentRoot is /www/htdocs. @@ -308,16 +324,18 @@ Options Includes

.htaccess file contents:

- + + AuthType Basic AuthName "Password Required" AuthUserFile "/www/passwords/password.file" AuthGroupFile "/www/passwords/group.file" Require group admins - + + -

Note that AllowOverride AuthConfig must be in effect - for these directives to have any effect.

+ AllowOverride AuthConfig must be in effect + for these directives to have any effect.

Please see the authentication tutorial for a more complete discussion of authentication and authorization.

@@ -330,15 +348,17 @@ Require group admins configuration directives, placed in a .htaccess file in the desired directory:

- + + Options +Includes AddType text/html "shtml" AddHandler server-parsed shtml - + + -

Note that AllowOverride Options and AllowOverride + AllowOverride Options and AllowOverride FileInfo must both be in effect for these directives to have any - effect.

+ effect.

Please see the SSI tutorial for a more complete discussion of server-side includes.

@@ -351,6 +371,7 @@ changes things a bit. In particular, rules are taken to be relative to the current directory, rather than being the original requested URI. Consider the following examples:

+ # In httpd.conf RewriteRule "^/images/(.+)\.jpg" "/images/$1.png" @@ -361,6 +382,7 @@ RewriteRule "^images/(.+)\.jpg" "images/$1.png" # In .htaccess in images/ RewriteRule "^(.+)\.jpg" "$1.png" +

In a .htaccess in your document directory, the leading slash is removed from the value supplied to RewriteRule, and in the it. Thus, your regular expression needs to omit that portion as well.

-

Also note that in .htaccess context, regular expressions are +

In .htaccess context, regular expressions are recompiled on every request, whereas in the main server configuration they are compiled once and cached.

@@ -390,23 +412,27 @@ further details on using mod_rewrite.

execution of CGI programs in a particular directory. This may be implemented with the following configuration:

- + + Options +ExecCGI AddHandler cgi-script "cgi" "py" - + +

Alternately, if you wish to have all files in the given directory be considered to be CGI programs, this may be done with the following configuration:

- + + Options +ExecCGI SetHandler cgi-script - + + -

Note that AllowOverride Options and AllowOverride + AllowOverride Options and AllowOverride FileInfo must both be in effect for these directives to have any - effect.

+ effect.

Please see the CGI tutorial for a more complete discussion of CGI programming and configuration.

@@ -427,9 +453,11 @@ SetHandler cgi-script nonsense word in your .htaccess file and reload the page:

- + + TestMe - + +

If a server error (HTTP 500) is not generated, then you almost certainly have AllowOverride @@ -440,13 +468,14 @@ TestMe that the directive used in your .htaccess file is not permitted.

- -[Tue May 06 09:12:31.528374 2025] [core:alert] [pid 12345] [client 192.168.1.50:54321] /var/www/html/.htaccess: DirectoryIndex not allowed here - + + +[Thu Jun 18 09:12:31.528374 2026] [core:alert] [pid 12345] [client 192.168.1.50:54321] /var/www/html/.htaccess: DirectoryIndex not allowed here + +

This will indicate either that you've used a directive that is - never permitted in .htaccess files, or that you simply - don't have AllowOverride set to + never permitted in .htaccess files, or that you don't have AllowOverride set to a level sufficient for the directive you've used. Consult the documentation for that particular directive to determine which is the case.

@@ -454,9 +483,11 @@ TestMe

Alternately, it may tell you that you had a syntax error in your usage of the directive itself.

- -[Tue May 06 09:14:02.946218 2025] [core:alert] [pid 12345] [client 192.168.1.50:54321] /var/www/html/.htaccess: RewriteCond: bad flag delimiters - + + +[Thu Jun 18 09:14:02.946218 2026] [core:alert] [pid 12345] [client 192.168.1.50:54321] /var/www/html/.htaccess: RewriteCond: bad flag delimiters + +

In this case, the error message should be specific to the particular syntax error that you have committed.