I'm leaning towards WONTFIX for this.

As far as I recall, no configuration files are read from CATALINA_HOME. They are always read, and only read, from CATALINA_BASE. I don't think making the default web.xml an exception is a good idea.

Fair enough, then I request the documentation be made a little clearer. The section "Advanced Configuration - Multiple Tomcat Instances" in RUNNING.txt, states 

* conf - Server configuration files (including server.xml)


which is a little open to interpretation, especially after the bin section specifies a subset of files. I can see how it can be interpreted either way though. Perhaps remove "(including server files)" and add a sentence or two below stating everything is required to be copied and pointing out which files definitely need editing (server.xml at a minimum), and which probably don't.

Further, if these files are required in CATALINA_BASE (when different to CATALINA_HOME), then an INFO message saying it isn't present is misleading also. Shouldn't it be a WARN at a minimum, indicating that certain functionality will not be available?

The documentation is open-sourced.  You can make the changes exactly as you see fit and propose them as a patch.

See https://github.com/apache/tomcat/tree/trunk/webapps/docs

I'm +1 on this request. We often tell people "don't modify conf/web.xml" or "don't modify conf/context.xml", but we are encouraging people to make "local" copies of those files like CATALINA_BASE/conf/web.xml.

(In reply to Mark Thomas from comment #1)
> As far as I recall, no configuration files are read from CATALINA_HOME. They
> are always read, and only read, from CATALINA_BASE. I don't think making the
> default web.xml an exception is a good idea.

Counterexamples: if CATALINA_BASE/conf/context.xml is not present, CATALINA_HOME/conf/context.xml will be read instead. Also, CATALINA_HOME/bin/setenv.sh is executed if CATALINA_BASE/bin/setenv.sh does not exist (this may be considered something other than a "configuration file", but I think it helps illustrate the point).

There are at least *some* files that Tomcat will fall-back to in CATALINA_HOME if they are not present in CATALINA_BASE. It's "surprising"[1] to find out that a "stock" configuration file -- one users are actively discouraged from editing -- does not enjoy this kind of fall-back semantics.

[1] https://en.wikipedia.org/wiki/Principle_of_least_astonishment

Removing an unmodified CATALINA_BASE/conf/web.xml also allows upgrades/downgrades to be more seamless because CATALINA_BASE's web.xml does not have to match the version of Tomcat being used.

(In reply to Christopher Schultz from comment #4)

<snip/>

> (In reply to Mark Thomas from comment #1)
> > As far as I recall, no configuration files are read from CATALINA_HOME. They
> > are always read, and only read, from CATALINA_BASE. I don't think making the
> > default web.xml an exception is a good idea.
> 
> Counterexamples: if CATALINA_BASE/conf/context.xml is not present,
> CATALINA_HOME/conf/context.xml will be read instead.

Code reference please. The only code I can find always reads from CATALINA_BASE.

> Also,
> CATALINA_HOME/bin/setenv.sh is executed if CATALINA_BASE/bin/setenv.sh does
> not exist (this may be considered something other than a "configuration
> file", but I think it helps illustrate the point).

That is historical. Originally, it was read only from CATALINA_HOME. The point was made (bug 43594) that it made more sense to be read from CATALINA_BASE. The fall-back to CATALINA_HOME is there for backwards compatibility.
 
> There are at least *some* files that Tomcat will fall-back to in
> CATALINA_HOME if they are not present in CATALINA_BASE. It's "surprising"[1]
> to find out that a "stock" configuration file -- one users are actively
> discouraged from editing -- does not enjoy this kind of fall-back semantics.
> 
> [1] https://en.wikipedia.org/wiki/Principle_of_least_astonishment

As far as I can tell there is a single file and it behaves this way for backwards compatibility reasons. In all other cases configuration is read only from CATALINA_BASE. I would argue that it is more surprising to change that.

Additionally, web.xml has merging rules applied to it. Is the proposal that CATALINA_BASE/conf/web.xml is merged on top of CATALINA_HOME/conf/web.xml or only CATALINA_BASE/conf/web.xml is used?

With the former option, a complex process will get more complex and user applications might break - in theory a security issue be introduced. That means the behaviour needs to be made optional which creates more complexity.

With the latter option, the same issues exists except the merging complexity.

Overall, this seems like an awful lot of effort to address a documentation issue that looks like it could be fixed with a couple of sentences.

(In reply to Mark Thomas from comment #6)
> (In reply to Christopher Schultz from comment #4)
> > (In reply to Mark Thomas from comment #1)
> > > As far as I recall, no configuration files are read from CATALINA_HOME. They
> > > are always read, and only read, from CATALINA_BASE. I don't think making the
> > > default web.xml an exception is a good idea.
> > 
> > Counterexamples: if CATALINA_BASE/conf/context.xml is not present,
> > CATALINA_HOME/conf/context.xml will be read instead.
> 
> Code reference please. The only code I can find always reads from
> CATALINA_BASE.

I don't have a code reference, but I have a long history of applications that have no CATALINA_BASE/conf/context.xml and they seem to be working fine. Maybe a missing CATALINA_BASE/conf/context.xml doesn't represent a problem because the default has very little configured inside it. If I "touch webapps/[app]/WEB-INF/web.xml" Tomcat will reload the web application. Perhaps that's a default buried deeply within the code somewhere, or perhaps it's configured somewhere I'm not looking.

I had always assumed that CATALINA_HOME/conf/context.xml was being used. Perhaps it is not.

> > Also,
> > CATALINA_HOME/bin/setenv.sh is executed if CATALINA_BASE/bin/setenv.sh does
> > not exist (this may be considered something other than a "configuration
> > file", but I think it helps illustrate the point).
> 
> That is historical. Originally, it was read only from CATALINA_HOME. The
> point was made (bug 43594) that it made more sense to be read from
> CATALINA_BASE. The fall-back to CATALINA_HOME is there for backwards
> compatibility.
>  
> > There are at least *some* files that Tomcat will fall-back to in
> > CATALINA_HOME if they are not present in CATALINA_BASE. It's "surprising"[1]
> > to find out that a "stock" configuration file -- one users are actively
> > discouraged from editing -- does not enjoy this kind of fall-back semantics.
> > 
> > [1] https://en.wikipedia.org/wiki/Principle_of_least_astonishment
> 
> As far as I can tell there is a single file and it behaves this way for
> backwards compatibility reasons. In all other cases configuration is read
> only from CATALINA_BASE. I would argue that it is more surprising to change
> that.
> 
> Additionally, web.xml has merging rules applied to it. Is the proposal that
> CATALINA_BASE/conf/web.xml is merged on top of CATALINA_HOME/conf/web.xml or
> only CATALINA_BASE/conf/web.xml is used?

My proposal would be that they all be merged together using the same rules, with the application's web.xml overriding the items in CATALINA_BASE/conf/web.xml, those overriding the items in CATALINA_HOME/conf/web.xml as necessary.

That would allow a CATALINA_BASE/conf/web.xml to add e.g. a JNDI mapping for all local applications, but wouldn't have to specify all the details for e.g. the JSP servlet and the default servlet.

> With the former option, a complex process will get more complex and user
> applications might break - in theory a security issue be introduced. That
> means the behaviour needs to be made optional which creates more complexity.

Hmm.

Is this any more of a problem that merging WEB-INF/web.xml with CATALINA_BASE/conf/web.xml?

> With the latter option, the same issues exists except the merging complexity.
> 
> Overall, this seems like an awful lot of effort to address a documentation
> issue that looks like it could be fixed with a couple of sentences.

This is definitely true. The question is whether or not there is a good reason to support this kind of thing at all. I think it would be nice to be able to make a small change to web.xml for a single Tomcat instance without having to configure everything that CATALINA_HOME/conf/web.xml configures. This provides a reduction in maintenance costs for the user, and makes CATALINA_BASE more compatible across versions of Tomcat.

This is an enhancement rather than a bug so changing the classification.