Bug 43372 - Document multiple extension behavior explicitly for each directive
Summary: Document multiple extension behavior explicitly for each directive
Alias: None
Product: Apache httpd-2
Classification: Unclassified
Component: Documentation (show other bugs)
Version: 2.5-HEAD
Hardware: Other other
: P2 major (vote)
Target Milestone: ---
Assignee: HTTP Server Documentation List
Depends on:
Reported: 2007-09-12 21:27 UTC by Sean Middleditch
Modified: 2007-09-15 15:15 UTC (History)
0 users


Note You need to log in before you can comment on or make changes to this bug.
Description Sean Middleditch 2007-09-12 21:27:30 UTC
The documentation does not at all make clear that AddType will scan a file name
for an extension instead of using the end of the filename as the extension. 
That is, the following directive:

AddHandler x-httpd-php .php

Will cause all of the following files to be marked as x-httpd-php files:


In some cases, this can result in a huge security hole when using AddHandler to
register handlers for PHP or other script/CGI engines.  Some distributions of
Apache are shipping with AddHandler directives for certain script engine modules
where AddType directives should be used, resulting in security vulnerabilities
for applications that allow users to upload files and only using extension
checks (admittedly a fault in the application, but it's apparently common).

The documentation for AddHandler simply doesn't make it obvious that this will
occur, which I believe is why many experienced Apache distribution maintainers
and administrators are using AddHandler instead of AddType when they shouldn't be.

(Note that I have filed bugs to alter the default configurations for the Apache
distributions I've found with this configuration error already.  This bug is for
a documentation enhancement, not for a change in any particular distribution's
dfault configuration.)
Comment 1 Joshua Slive 2007-09-13 07:49:09 UTC
It appears you haven't read
(on the same page as the AddHandler docs)
(linked directly from the AddHandler docs)

Also, AddType has exactly the same behavior and should NOT be used in place of

But I'll give you that, even though this is already well-documented, it is still
a moderately common user error. So I'll accept that it would be a good idea to
explicitly mention this behavior in the text of all the Add* directives.
Comment 2 Joshua Slive 2007-09-13 10:47:00 UTC
Fixed in docs.
Comment 3 Sean Middleditch 2007-09-13 14:35:39 UTC
Yes, admittedly I didn't look hard enough.  I guess at least some vendors'
Apache distribution maintainers are as equally negligent in reading docs as I
am.  :)

"Also, AddType has exactly the same behavior and should NOT be used in place of

This is not true so far as I can tell.  I've switched the two directives on the
config in question and the behavior most definitetely did change.  I double
checked: the following file is executed by mod_php when using AddHandler, but is
not when using AddType:


The following is correctly executed in both configurations:

Comment 4 Joshua Slive 2007-09-13 17:21:08 UTC
That's only because when you have two extensions applying the same type of
meta-data (content-type in this case), the last one wins. But it doesn't avoid
any security problems that might be caused by forgetting about multiple
extensions, because test.php.foo would still be treated as a cgi script.

So please don't use AddType to set handlers. It causes many other problems.
Comment 5 Sean Middleditch 2007-09-13 18:47:13 UTC
What then is the correct way to ensure that only files with a particular final
extension are handled by certain handler?

The multiple-extension documentation states what happens with multiple
extensions, but doesn't really say how to fix such setups.  Even in a
non-security situation, things like phpDocumentor generate files with names like
foo.php.html that are always getting passed to mod_php on this vendor's config.
 I'd like to pass on to them the correct information for fixing the problem if
AddType is not right.
Comment 6 Joshua Slive 2007-09-14 06:23:52 UTC
The correct solution is not to assume that only the last extension matters. Unix
has used multiple significant extensions for a long time; this is not an Apache
invention. (Other good solutions including only turning on php handler
processing in places where it is really required, rather than turning it on
globally. It is usually easy enough to designate certain directories for php
execution and make sure that non-php files don't get put there.)

But if you really want a match-only-final-extension solution, I recently added
one here:
Comment 7 Sean Middleditch 2007-09-14 13:49:57 UTC
Heh, so far as I'm concerned, the proper solution is to _never_ match on file
extension when possible.  Unfortunately, too much software out there of the Perl
and PHP varieties don't do that.  :/

It seems that this is frequently believed by other distributions.  I've checked
the configurations on a number of servers, and most Linux distributions, Apache
control panels, and a few other custom distributions of Apache all are using
AddType instead of AddHandler.  What problems could that cause?  These systems
seem to work great, but I'd like to understand things a bit better.

By the way, thanks for explaining all of this and updating the docs to be more
explicit.  You rock.
Comment 8 Joshua Slive 2007-09-15 07:28:26 UTC
AddType will mess up any module that expects to be able to act on the real
content-type of a resource, rather than the "magic" type used for activating
handlers. This includes at least mod_negotiation and mod_security.

The error is so widespread because php's docs show AddType. That has long ago
been reported as a bug in their bug database, but it has never been fixed.
Comment 9 Sean Middleditch 2007-09-15 15:15:43 UTC
Ah.  I'd warrant that's because of the difficulty of ensuring that only the last
extension is used for invoking a handler.  Your solution works, but I wonder if
maybe it would just be simpler (especially in terms of documenting behavior) to
add a directive that does the same thing, or modifying AddHandler to somehow be
able to specify that only the last extension should be used.  I think people
will always go for the simplest configuration directive that works, so if it
comes down to the file matching plus sethandler call vs something as simple as
AddType, people will go for the latter.

Hate to say it, but the multi-extension behavior really is just not what most
people want with CGI-based handlers, and the behavior that people want (and is
secure and doesn't break anything else) is what Apache should make the easiest
to configure.

Just adding a single directive that combines the FilesMatch functionality with
the SetHandler behavior would go a long way towards fixing commonly broken
setups, perhaps.  Something like:

SetFileHandler x-foo \.foo$

Duplicate functionality isn't usually a good thing, but if you're really having
that many problems with configurations in the wild (which definitely seems to be
the case), I'd say it's safe to assume the current mechanisms are just too obtuse.