Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="./images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 (9.0.112) - Introduction</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="./images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="index.html">Docs Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li></ul></div><div><h2>User Guide</h2><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="host-manager-howto.html">6) Host Manager</a></li><li><a href="realm-howto.html">7) Realms and AAA</a></li><li><a href="security-manager-howto.html">8) Security Manager</a></li><li><a href="jndi-resources-howto.html">9) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">10) JDBC DataSources</a></li><li><a href="class-loader-howto.html">11) Classloading</a></li><li><a href="jasper-howto.html">12) JSPs</a></li><li><a href="ssl-howto.html">13) SSL/TLS</a></li><li><a href="ssi-howto.html">14) SSI</a></li><li><a href="cgi-howto.html">15) CGI</a></li><li><a href="proxy-howto.html">16) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">17) MBeans Descriptors</a></li><li><a href="default-servlet.html">18) Default Servlet</a></li><li><a href="cluster-howto.html">19) Clustering</a></li><li><a href="balancer-howto.html">20) Load Balancer</a></li><li><a href="connectors.html">21) Connectors</a></li><li><a href="monitoring.html">22) Monitoring and Management</a></li><li><a href="logging.html">23) Logging</a></li><li><a href="apr.html">24) APR/Native</a></li><li><a href="virtual-hosting-howto.html">25) Virtual Hosting</a></li><li><a href="aio.html">26) Advanced IO</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li><li><a href="rewrite.html">33) Rewrite</a></li><li><a href="cdi.html">34) CDI 2 and JAX-RS</a></li><li><a href="graal.html">35) AOT/GraalVM Support</a></li></ul></div><div><h2>Reference</h2><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet 4.0 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.3 Javadocs</a></li><li><a href="elapi/index.html">EL 3.0 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="jaspicapi/index.html">JASPIC 1.1 Javadocs</a></li><li><a href="annotationapi/index.html">Common Annotations 1.3 Javadocs</a></li><li><a href="https://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul></div><div><h2>Apache Tomcat Development</h2><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Tomcat+Versions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>Introduction</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Terminology">Terminology</a></li><li><a href="#Directories_and_Files">Directories and Files</a></li><li><a href="#CATALINA_HOME_and_CATALINA_BASE">CATALINA_HOME and CATALINA_BASE</a><ol><li><a href="#Why_Use_CATALINA_BASE">Why Use CATALINA_BASE</a></li><li><a href="#Contents_of_CATALINA_BASE">Contents of CATALINA_BASE</a></li><li><a href="#How_to_Use_CATALINA_BASE">How to Use CATALINA_BASE</a></li></ol></li><li><a href="#Configuring_Tomcat">Configuring Tomcat</a></li><li><a href="#Where_to_Go_for_Help">Where to Go for Help</a></li></ul>
6 
</div><h3 id="Introduction">Introduction</h3><div class="text">
7 
 
8 
<p>For administrators and web developers alike, there are some important bits
9 
of information you should familiarize yourself with before starting out. This
10 
document serves as a brief introduction to some of the concepts and
11 
terminology behind the Tomcat container. As well, where to go when you need
12 
help.</p>
13 
 
14 
</div><h3 id="Terminology">Terminology</h3><div class="text">
15 
 
16 
<p>In the course of reading these documents, you will run across a number of
17 
terms; some specific to Tomcat, and others defined by the
18 
<a href="https://cwiki.apache.org/confluence/display/TOMCAT/Specifications">Servlet and
19 
JSP specifications</a>.</p>
20 
 
21 
<ul>
22 
<li><strong>Context</strong> - In a nutshell, a Context is a
23 
    web application.</li>
24 
</ul>
25 
<p>That is it. If you find any more terms we need to add to this section, please
26 
do let us know.</p>
27 
 
28 
</div><h3 id="Directories_and_Files">Directories and Files</h3><div class="text">
29 
 
30 
<p>These are some of the key tomcat directories:</p>
31 
 
32 
<ul>
33 
<li><strong>/bin</strong> - Startup, shutdown, and other scripts. The
34 
    <code>*.sh</code> files (for Unix systems) are functional duplicates of
35 
    the <code>*.bat</code> files (for Windows systems).  Since the Win32
36 
    command-line lacks certain functionality, there are some additional
37 
    files in here.</li>
38 
<li><strong>/conf</strong> - Configuration files and related DTDs.  The most
39 
    important file in here is server.xml.  It is the main configuration file
40 
    for the container.</li>
41 
<li><strong>/logs</strong> - Log files are here by default.</li>
42 
<li><strong>/webapps</strong> - This is where your webapps go.</li>
43 
</ul>
44 
 
45 
</div><h3 id="CATALINA_HOME_and_CATALINA_BASE">CATALINA_HOME and CATALINA_BASE</h3><div class="text">
46 
  <p>Throughout the documentation, there are references to the two following
47 
    properties:
48 
    <ul>
49 
      <li>
50 
        <strong>CATALINA_HOME</strong>: Represents the root of your Tomcat
51 
        installation, for example <code>/home/tomcat/apache-tomcat-9.0.10</code>
52 
        or <code>C:\Program Files\apache-tomcat-9.0.10</code>.
53 
      </li>
54 
      <li>
55 
        <strong>CATALINA_BASE</strong>: Represents the root of a runtime
56 
        configuration of a specific Tomcat instance. If you want to have
57 
        multiple Tomcat instances on one machine, use the <code>CATALINA_BASE</code>
58 
        property.
59 
      </li>
60 
    </ul>
61 
  </p>
62 
  <p>
63 
    If you set the properties to different locations, the CATALINA_HOME location
64 
    contains static sources, such as <code>.jar</code> files, or binary files.
65 
    The CATALINA_BASE location contains configuration files, log files, deployed
66 
    applications, and other runtime requirements.
67 
  </p>
68 
  <div class="subsection"><h4 id="Why_Use_CATALINA_BASE">Why Use CATALINA_BASE</h4><div class="text">
69 
    <p>
70 
      By default, CATALINA_HOME and CATALINA_BASE point to the same directory.
71 
      Set CATALINA_BASE manually when you require running multiple Tomcat
72 
      instances on one machine. Doing so provides the following benefits:
73 
    </p>
74 
    <ul>
75 
      <li>
76 
        Easier management of upgrading to a newer version of Tomcat. Because all
77 
        instances with single CATALINA_HOME location share one set of
78 
        <code>.jar</code> files and binary files, you can easily upgrade the files
79 
        to newer version and have the change propagated to all Tomcat instances
80 
        using the same CATALINA_HOME directory.
81 
      </li>
82 
      <li>
83 
        Avoiding duplication of the same static <code>.jar</code> files.
84 
      </li>
85 
      <li>
86 
        The possibility to share certain settings, for example the <code>setenv</code> shell
87 
        or bat script file (depending on your operating system).
88 
      </li>
89 
    </ul>
90 
  </div></div>
91 
  <div class="subsection"><h4 id="Contents_of_CATALINA_BASE">Contents of CATALINA_BASE</h4><div class="text">
92 
    <p>
93 
      Before you start using CATALINA_BASE, first consider and create the
94 
      directory tree used by CATALINA_BASE. Note that if you do not create
95 
      all the recommended directories, Tomcat creates the directories
96 
      automatically. If it fails to create the necessary directory, for example
97 
      due to permission issues, Tomcat will either fail to start, or may not
98 
      function correctly.
99 
    </p>
100 
    <p>
101 
      Consider the following list of directories:
102 
      <ul>
103 
        <li>
104 
          <p>
105 
            The <code>bin</code> directory with the <code>setenv.sh</code>,
106 
            <code>setenv.bat</code>, and <code>tomcat-juli.jar</code> files.
107 
          </p>
108 
          <p>
109 
            <i>Recommended:</i> No.
110 
          </p>
111 
          <p>
112 
            <i>Order of lookup:</i> CATALINA_BASE is checked first; fallback is provided
113 
            to CATALINA_HOME.
114 
          </p>
115 
        </li>
116 
        <li>
117 
          <p>
118 
            The <code>lib</code> directory with further resources to be added on
119 
            classpath.
120 
          </p>
121 
          <p>
122 
            <i>Recommended:</i> Yes, if your application depends on external libraries.
123 
          </p>
124 
          <p>
125 
            <i>Order of lookup:</i> CATALINA_BASE is checked first; CATALINA_HOME is
126 
            loaded second.
127 
          </p>
128 
        </li>
129 
        <li>
130 
          <p>
131 
            The <code>logs</code> directory for instance-specific log files.
132 
          </p>
133 
          <p>
134 
            <i>Recommended:</i> Yes.
135 
          </p>
136 
        </li>
137 
        <li>
138 
          <p>
139 
            The <code>webapps</code> directory for automatically loaded web
140 
            applications.
141 
          </p>
142 
          <p>
143 
            <i>Recommended:</i> Yes, if you want to deploy applications.
144 
          </p>
145 
          <p>
146 
            <i>Order of lookup:</i> CATALINA_BASE only.
147 
          </p>
148 
        </li>
149 
        <li>
150 
          <p>
151 
            The <code>work</code> directory that contains temporary working
152 
            directories for the deployed web applications.
153 
          </p>
154 
          <p>
155 
            <i>Recommended:</i> Yes.
156 
          </p>
157 
        </li>
158 
        <li>
159 
          <p>
160 
            The <code>temp</code> directory used by the JVM for temporary files.
161 
          </p>
162 
          <p>
163 
            <i>Recommended:</i> Yes.
164 
          </p>
165 
        </li>
166 
      </ul>
167 
    </p>
168 
    <p>
169 
      We recommend you not to change the <code>tomcat-juli.jar</code> file.
170 
      However, in case you require your own logging implementation, you can
171 
      replace the <code>tomcat-juli.jar</code> file in a CATALINA_BASE location
172 
      for the specific Tomcat instance.
173 
    </p>
174 
    <p>
175 
      We also recommend you copy all configuration files from the
176 
      <code>CATALINA_HOME/conf</code> directory into the
177 
      <code>CATALINA_BASE/conf/</code> directory. In case a configuration file
178 
      is missing in CATALINA_BASE, there is no fallback to CATALINA_HOME.
179 
      Consequently, this may cause failure.
180 
    </p>
181 
    <p>
182 
      At minimum, CATALINA_BASE must contain:
183 
      <ul>
184 
        <li>conf/server.xml</li>
185 
        <li>conf/web.xml</li>
186 
      </ul>
187 
      That includes the <code>conf</code> directory. Otherwise, Tomcat fails
188 
      to start, or fails to function properly.
189 
    </p>
190 
    <p>
191 
      For advanced configuration information, see the
192 
      <a href="https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt">
193 
        RUNNING.txt
194 
      </a> file.
195 
    </p>
196 
  </div></div>
197 
  <div class="subsection"><h4 id="How_to_Use_CATALINA_BASE">How to Use CATALINA_BASE</h4><div class="text">
198 
    <p>
199 
      The CATALINA_BASE property is an environment variable. You can set it
200 
      before you execute the Tomcat start script, for example:
201 
      <ul>
202 
        <li>On Unix: <code>CATALINA_BASE=/tmp/tomcat_base1 bin/catalina.sh start</code></li>
203 
        <li>On Windows: <code>CATALINA_BASE=C:\tomcat_base1 bin/catalina.bat start</code></li>
204 
      </ul>
205 
    </p>
206 
  </div></div>
207 
</div><h3 id="Configuring_Tomcat">Configuring Tomcat</h3><div class="text">
208 
 
209 
<p>This section will acquaint you with the basic information used during
210 
the configuration of the container.</p>
211 
 
212 
<p>All of the information in the configuration files is read at startup,
213 
meaning that any change to the files necessitates a restart of the container.
214 
</p>
215 
 
216 
</div><h3 id="Where_to_Go_for_Help">Where to Go for Help</h3><div class="text">
217 
 
218 
<p>While we've done our best to ensure that these documents are clearly
219 
written and easy to understand, we may have missed something.  Provided
220 
below are various web sites and mailing lists in case you get stuck.</p>
221 
 
222 
<p>Keep in mind that some of the issues and solutions vary between the
223 
major versions of Tomcat.  As you search around the web, there will be
224 
some documentation that is not relevant to Tomcat 9, but
225 
only to earlier versions.</p>
226 
 
227 
<ul>
228 
<li>Current document - most documents will list potential hangups. Be sure
229 
    to fully read the relevant documentation as it will save you much time
230 
    and effort. There's nothing like scouring the web only to find out that
231 
    the answer was right in front of you all along!</li>
232 
<li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">Tomcat FAQ</a></li>
233 
<li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/">Tomcat WIKI</a></li>
234 
<li>Tomcat mailing list archives - numerous sites archive the Tomcat mailing
235 
    lists. Since the links change over time, clicking here will search
236 
    <a href="https://www.google.com/search?q=tomcat+mailing+list+archives">Google</a>.
237 
    </li>
238 
<li>The TOMCAT-USER mailing list, which you can subscribe to
239 
    <a href="https://tomcat.apache.org/lists.html">here</a>. If you don't
240 
    get a reply, then there's a good chance that your question was probably
241 
    answered in the list archives or one of the FAQs.  Although questions
242 
    about web application development in general are sometimes asked and
243 
    answered, please focus your questions on Tomcat-specific issues.</li>
244 
<li>The TOMCAT-DEV mailing list, which you can subscribe to
245 
    <a href="https://tomcat.apache.org/lists.html">here</a>.  This list is
246 
    <strong>reserved</strong> for discussions about the development of Tomcat
247 
    itself.  Questions about Tomcat configuration, and the problems you run
248 
    into while developing and running applications, will normally be more
249 
    appropriate on the TOMCAT-USER list instead.</li>
250 
</ul>
251 
 
252 
<p>And, if you think something should be in the docs, by all means let us know
253 
on the TOMCAT-DEV list.</p>
254 
 
255 
</div></div></div></div></div><footer><div id="footer">
256 
    Copyright &copy; 1999-2025, The Apache Software Foundation
257 
    <br>
258 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
259 
    are either registered trademarks or trademarks of the Apache Software
260 
    Foundation.
261 
    </div></footer></div></body></html>