Tomcat server.xml配置示例

本文由 ImportNew

几乎所有容器类型的应用都会包含一个名为 server.xml 的文件结构。基本上，其中的每个元数据或者配置都是容器完成初始化所需要的。正是由于这些内容都是可配置的，使得软件设计者或架构师可以在容器运行时或销毁时（停止）的情况下注入需要的服务。明白这一点，其重要性不亚于明白代码或软件的工作机制。

对于这篇文章，我们将通过分析 server.xml 文件来理解和配置 appache tomcat 服务器。

准备工作：

• 安装 Apache Tomcat 7。（从 apache tomcat 的网站获取源码）

安装教程可以点击这里。

1、Tomcat 安装目录

安装完成 的tomcat，被放在了你的本地存储中。对于 windows ，通常在 “ Program Files ” 文件夹下，对于 Mac 或者 Linux，可能在 /user/var/opt 或 /User/<>/Application 文件夹下。进入该目录，可以看到下面这几个文件和文件夹：

• bin：Tomcat 二进制启动脚本。
• conf：应用于所有 webapp 的全局配置。默认会提供如下配置：
  • catalina.policy 提供特殊的安全策略。
  • 两个 Properties 文件：catalina.properties 和 logging.properties ，
  • 四个 XML 配置文件：server.xml（Tomcat 主配置文件）、web.xml（web 应用全局部署描述）、context.xml（Tomcat 特殊配置全局选项）和 tomcat-user.xml（授权和访问控制用户名，密码和角色数据库）。

  每个引擎在conf 目录下都有一个对应的子目录，例如Catalina，反过来对于每个 host 都有一个二级子目录，比如localhost。可以将上下文信息配置放在这里（类似于 context.xml ，但是对于每个在 host 下的 webapp ，该文件命名为 webapp.xml ）。

• lib：确保目录下的 JAR-file 对于所有 webapp 都有效。默认安装包括 servlet-api.jar（Servlet），jasper.jar（JSP）和 jasper-el.jar（EL）。外部的 JAR 文件也可以放在这里，如 MySQL JDBC 驱动（mysql-connector-java-5.1.{xx}-bin.jar )和 JSTL（jstl.jar 和 standard.jar）。
• logs：包括引擎日志文件 Catalina.{yyyy-mm-dd}.log ，host 日志文件 localhost.{yyyy-mm-dd}.log，和其它应用的日志文件，如 manager 和 host-manager。访问日志（由 AccessLogValve 创建）也放在这里。

• webapps：默认为 appBase – web应用的根目录。
• work: contains the translated servlet source files and classes of JSP/JSF. Organized in hierarchy of engine name (Catalina), host name (localhost), webapp name, followed by the Java classes package structure.
• temp：临时文件。

2、Tomcat 架构

Tomcat 是一个 HTTP 服务器。也是一个servlet 容器，可以执行 Java Servlet，将 JavaServer Page（JSP）和 JavaServerFaces（JSF）转换为 Java Servlet。Tomcat 采用了层次化和模块化的架构，如下：

图片1.0 Tomcat 架构

3、主配置文件（server.xml）

server.xml

“server.xml” 是 Tomcat 的主配置文件，在 <CATALINA_HOME>conf 目录下可以看到。重构后（删掉注释和格式化后）的默认”server.xml“文件如下：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

<?xml version='1.0' encoding='utf-8'?> <Server port="8005" shutdown="SHUTDOWN">   <Listener className="org.apache.catalina.core.JasperListener" />   <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />   <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />   <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />   <Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" />   <GlobalNamingResources>     <Resource name="UserDatabase" auth="Container"               type="org.apache.catalina.UserDatabase"               description="User database that can be updated and saved"               factory="org.apache.catalina.users.MemoryUserDatabaseFactory"               pathname="conf/tomcat-users.xml" />   </GlobalNamingResources>   <Service name="Catalina">     <Connector port="8080" protocol="HTTP/1.1"                connectionTimeout="20000"                redirectPort="8443" />     <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />     <Engine name="Catalina" defaultHost="localhost">       <Realm className="org.apache.catalina.realm.LockOutRealm">         <Realm className="org.apache.catalina.realm.UserDatabaseRealm"                resourceName="UserDatabase"/>       </Realm>       <Host name="localhost"  appBase="webapps"             unpackWARs="true" autoDeploy="true">         <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"                prefix="localhost_access_log." suffix=".txt"                pattern="%h %l %u %t "%r" %s %b" />       </Host>     </Engine>   </Service> </Server>

3.1、Server

Server（第二行）是*组件，代表一个 Tomcat 实例。可以包含一个或多个 Services ，其中每个 Service 都有自己的 Engines 和 Connectors。

1	<Server port="8005" shutdown="SHUTDOWN"> ...... </Server>

3.1.1、基本属性

• className：使用 Java 实现类的名称。这个类必须实现 org.apache.catalina.Server 接口。如果没有指定类名，将会使用标准实现。
• address： server 在这个 TCP/IP 地址上监听一个 shutdown 命令。如果没有指定地址，将会使用 localhost。
• port：server 在这个端口上监听一个 shutdown 命令。设置为 -1 表示禁用 shutdown 命令。
• shutdown：连接到指定端口的 TCP/IP 收到这个命令字符后，将会关闭 Tomcat。

3.2、Listeners

Server 可以包含几个监听器。一个监听器监听指定事件，并对其作出响应。

JasperListener 作用于 Jasper JSP 引擎，该引擎负责对更新后的 JSP 页面进行重编译。

1	Listener className="org.apache.catalina.core.JasperListener" />

GlobalResourcesLifecycleListener 作用于全局资源，保证 JNDI 对资源的可达性，比如数据库。

1	<Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />

3.2.1、基本属性

• SSLEngine：使用的SSLEngine名称。off：不使用 SSL，on：使用 SSL 但不指定引擎。默认值是 on。会初始化本地 SSL 引擎，对于使用 SSLEnabled 属性的 APR/native connector 来讲，该选项必须可用。
• SSLRandomSeed：指定伪随机数生成器（PRNG）的随机数种子源，默认值为 builtin。在开发环境下，可能要将其设置为 /dev/urandom , 以获得更快地启动速度。
• FIPSMode：设置为 on 会请求 OpenSSL 进入 FIPS 模式（如果 OpenSSL 已经处于 FIPS 模式，将会保留该模式）。设置为 enter 会强制 OpenSSL 进入 FIPS 模式（如果 OpenSSL 已经处于 FIPS 模式，将会产生一个错误）。设置为 require 要求 OpenSSL 已经处于 FIPS 模式（如果 OpenSSL 当前没有处于 FIPS 模式将会产生一个错误）。

3.3、全局命名资源

9到15行的元素定义了 JNDI（Java 命名和目录接口）资源，其允许 Java 软件客户端通过名称搜寻和查找数据。

默认配置通过10到14行的元素定义了一个名称为 UserDatabase 的 JNDI，通过”conf/tomcat-users.xml“得到了一个用于用户授权的内存数据库。

1 2 3 4 5 6 7

<GlobalNamingResources>   <Resource name="UserDatabase" auth="Container"             type="org.apache.catalina.UserDatabase"             description="User database that can be updated and saved"             factory="org.apache.catalina.users.MemoryUserDatabaseFactory"             pathname="conf/tomcat-users.xml" /> </GlobalNamingResources>

你也可以定义其它全局化JNDI资源来实现连接池，比如 MySQL 数据库。

3.4、Services

一个 Service 可以连接一个或多个 Connectors 到一个引擎。默认配置定义了一个名为“Catalina”的 Service ，连接了两个 Connectors：HTTP 和 AJP 到当前的引擎。

1	<Service name="Catalina"> ...... </Service>

3.4.1、基本属性

• className：该实现使用的 Java 类名称。这个类必须实现 org.apache.catalina.Service 接口。如果没有指定类名称，将会使用标准实现。
• name：Service 的显示名称，如果采用了标准的 Catalina 组件，将会包含日志信息。每个 Service 与某个特定的 Server 关联的名称必须是唯一的。

3.5、Connectors

一个 Connector 关联到一个 TCP 端口，负责处理 Service 与客户端之间的交互。默认配置定义了两个 Connectors。

HTTP/1.1：处理 HTTP 请求，使得 Tomcat 成为了一个 HTTP 服务器。客户端可以通过 Connector 向服务器发送 HTTP 请求，接收服务器端的 HTTP 响应信息。

1	<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />

与生产服务默认使用80端口不同，Tomcat HTTP 服务默认在 TCP 端口8080上运行 。你可以选择1024到65535之间的任意数字作为端口号来运行 Tomcat 服务器，前提是该端口没有被任何其它应用使用。connectionTimeOut 属性定义了这个 connector 在链接获得同意之后，获得请求 URI line（请求信息）响应的最大等待时间毫秒数。默认为20秒。redirect 属性会把 SSL 请求重定向到 TCP 的8443端口。AJP/1.3：Apache JServ Protocol connector 处理 Tomcat 服务器与 Apache HTTP 服务器之间的交互。

1	<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

可以将 Tomcat 和 Apache HTTP 服务运行在一起，Apache HTTP 服务器处理静态请求和 PHP；Tomcat 服务器负责处理 Java Servlet/JSP 。可以参阅“Tomcat 与 Apache 协同工作如何配置”。

3.6、容器

包含了 Engine、Host、Context和 Cluster 的 Tomcat 称为容器。*的是 Engine，最底层的是 Context。某些组件，比如 Realm 和 Valve，也可以放在容器中。

3.7、引擎

引擎是容器中*别的部分。可以包含一个或多个 Host。Tomcat 服务器可以配置为运行在多个主机名上，包括虚拟主机。

1	<Engine name="Catalina" defaultHost="localhost"/>

Catalina 引擎 从 HTTP connector 接收 HTTP 请求，并根据请求头部信息中主机名或 IP 地址重定向到正确的主机上。

3.7.1、基本属性

• backgroundProcessorDelay —— 这个值表示了在这个引擎和它的子容器上调用 backgroundProcess 方法之间间隔的秒数，包括所有 host 和 context。值为非负时不会调用子容器（意味着其使用自身的处理线程）。设置为正值会产生一个衍生线程。等待指定的时间之后，该线程会在这个引擎和它的所有子容器上调用 backgroundProcess 方法。如果没有指定，默认值为10，即会有10秒的延迟。
• className：实现该引擎使用的 Java 类名。该类必须实现 org.apache.catalina.Engine 接口。如果没有指定，会使用标准值（下面有定义）。
• defaultHost：默认主机名，定义了处理指向该服务器的请求所在主机的名称，但名称不是在这个文件中配置。
• jvmRoute：在负载均衡场景下必须定义该参数，来保证 session affinity 可用，对于集群中所有 Tomcat 服务器来讲定义的名称必须是唯一的， 该名称将会被添加到生成的会话标示符中，因此，允许前端代理总是将特定会话转发到同一个 Tomcat 实例。
• name：Engine 的逻辑名称，用在日志和错误信息中。当在相同的 Server 中使用多个 Service 元素时，每个 Engine 必须指定一个唯一的名称。
• startStopThreads：Engine 在启动 Host 子元素时将会并发使用的线程数目。如果设置为0，将会使用 Runtime.getRuntime().availableProcessors() 的值。设置为负数，将会使用  Runtime.getRuntime().availableProcessors() + value 的值，如果结果小于1，将会使用 1 个线程。如果没有指定，默认值为 1 。

3.8、Realm

一个 Realm（域）就是一个包含 user、password 和 role 认证（比如访问控制）的数据库。你可以在任何容器中定义 Realm ，例如 Engine、Host、Context 和 Cluster。

1 2 3

<Realm className="org.apache.catalina.realm.LockOutRealm">   <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/> </Realm>

默认配置定义了一个 Catalina Engine 的 Realm（UserDatabaseRealm），对用户访问 engine 的权限进行控制。其使用定义在 GlobalNamingResources 中，名字为 UserDatabase 的 JNDI。

除了 UserDatabaseRealm 以外，还有：JDBCRealm（授权用户是否可以通过 JDBC 驱动链接到关系型数据库）；DataSourceRealm（通过 JNDI 连到数据源）；JNDIRealm（连接到一个 LDAP 目录）和 MemoryRealm （将 XML 文件加载到内存）。

3.8.1、基本属性

• className：使用 Java 实现类的名称。这个类必须实现 org.apache.catalina.Realm 接口。

3.9、Hosts

一个 Host 定义了在 Engine 下的一个虚拟机，反过来其又支持多个 Context（web 应用）。

1	<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true"/>

默认配置定义了一个名为 localhost 的主机。appBase 属性定义了所有 webapp 的根目录，在这种情况下是 webapps。默认情况下，每一个 webapp 的 URL 和它所在的目录名称相同。例如，默认的 Tomcat 安装目录的 webapps 下提供了四个 web 应用：docs、examples、host-manager 和 manager。只有 ROOT 是个例外，它用一个空字符串定义。也就是说，它的 URL 是  http://localhost:8080/。unpackWARs 属性指定了放到 webapps 目录下的 WAR-file 是否应该被解压。对于 unpackWARs=”false“，Tomcat 将会直接从 WAR-file 运行应用，而不解压，这可能导致应用运行变慢。autoDeploy 属性指定了是否自动部署放到 webapps 目录下的应用。

3.9.1、基本属性

• appBase：虚拟机应用的根目录。该目录是一个可能包含部署到虚拟机上 web 应用的路径名。也可能是一个指定的绝对路径名，或者是一个相对于 $CATALINA_BASE 目录的路径名。如果没有指定，默认会使用 webapps。
• xmlBase：虚拟机 XML 根目录。该目录是一个可能包含部署到虚拟机上context XML 描述符的路径名。也可能是一个指定的绝对路径名，或者是一个相对于 $CATALINA_BASE 目录的路径名。如果没有指定，默认会使用 conf/ 目录。
• createDirs：如果设置为 true，Tomcat 将会在启动阶段，尝试创建一个由 appBase 和 xmlBase 属性定义的目录。默认值是 true。如果设置为 true ，并且目录创建失败，将会打印出一个错误信息，但是不会终止启动过程。
• autoDeploy：该属性的值指明了在 Tomcat 运行的时候，是否需要定时检查新的或者更新后的 web 应用。如果为 true，Tomcat 会定时检查 appBase 和 xmlBase 目录，并对找到的新 web 应用和 context XML 描述符进行部署。更新 web 应用 或 XML 上下文描述符将会触发 web 应用的重载。默认值为 true。
• backgroundProcessorDelay：表示在调用这台主机的 backgroundProcess 方法和它的子容器方法，包括所有的 context，之间延迟的秒数。如果延迟值不是负数的话，不会调用子容器（意味着会使用它们自己的处理线程）。设置为正数会产生衍生线程。在等待指定的时间之后，线程将会在该 host 上调用 backgroundProcess 方法，包括它的所有子容器。host将会使用后台进程执行web 应用部署相关的任务。如果没有指定，默认值为-1，意味着 host 将会依赖于它的父引擎的后台处理线程。
• className：使用的 Java 实现类的名称。该类必须实现 org.apache.catalina.Host 接口。
• deployIgnore：一个正则表达式，定义了在自动部署和启动时部署的情况下需要忽略的目录。这就允许你在版本控制系统中保持自己的配置，例如，不会将 .svn 或者 CVS 文件夹部署到 appBase 目录下。该正则表达式是相对于 appBase 的。同时也是固定的，意味着是相对于整个文件或目录的名称进行的。因此，foo 只会匹配名称为 foo 的文件或目录，而不会匹配foo.war、foobar或者 myfooapp 这样的名称。如果想让“foo”匹配任意名称，可以使用 .*foo.*。
• deployOnStartup：指定在 Tomcat 启动时是否需要自动部署host下的 web 应用。默认值为 true。
• failCtxIfServletStartFails：设置为 true时，如果它的任意一个 load-on-startup>=0 的 servlet 停止自身启动后，停止启动它的每一个子 context 。每一个子 context 可能覆盖这个属性。如果没有指定，将会使用默认值 false。
• name：通常是虚拟主机的网络名称，注册在你的域名服务器上。无论指定的主机名称是什么样的，Tomcat 在内部都会将其转换为小写。嵌套在 Engine 内部的 Host ，其中必须有一个 Host 的名称匹配 Engine 的默认 Host 设置。 
• startStopThreads：Host 在启动子 Context 元素时会并发使用的线程数。如果自动部署被使用的话将会使用该线程池部署新的 Context。值为0时将会使用 Runtime.getRuntime().availableProcessors() 的值。值为负数时将会使用 Runtime.getRuntime().availableProcessors() 加上该值得和，而和小于1时将会使用1个线程。如果没有指定，会使用默认值1。
• undeployOldVersion：该选项的值决定 Tomcat，即自动部署进程部分，是否会检查并发部署的过时 web 应用，任何找到的应用都会被移除。只有在 autoDeploy 为 true 的情况下才会生效。如果没有指定将会使用默认值 false。

3.10、集群

Tomcat 支持服务器集群。它可以复制整个集群的会话和上下文属性。也可以部署一个 WAR 文件到所有的集群上。

3.10.1、基本属性

• className：集群主类，当前只有一个是有效的， org.apache.catalina.ha.tcp.SimpleTcpCluster。
• channelSendOptions： 组通讯（tribe channel）发送选项，默认为8。该选项被用来标志所有的信息通过 SimpleTcpCluster 发送。该标志指定怎样发送信息，是一个简单的逻辑或。
• channelStartOptions：设置集群使用对象的启动和停止标志。默认是 Channel.DEFAULT，会启动所有的 channel 服务，包括发送者、接收者、组播发送者和组播接收者。
• heartbeatBackgroundEnabled：标志是否在容器的后台线程中调用 channel 的心跳检测。默认是 false。当设置为 true 时，不要忘了禁用 channel 心跳检测线程。
• notifyLifecycleListenerOnFailure：当所有的 ClusterListener 不能接收 channel 消息时，该标志位决定是否通知 LifecycleListeners。默认是 false。

3.11、Valve

Valve （阀门）作为请求的前置处理程序，可以在请求发送到应用之前拦截 HTTP 请求。可以定义在任何容器中，比如 Engine、Host、Context和 Cluster。默认配置中，AccessLogValve 会拦截 HTTP 请求，并在日志文件中创建一个日志切入点，如下：

1 2 3

<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"        prefix="localhost_access_log." suffix=".txt"        pattern="%h %l %u %t "%r" %s %b" />

3.11.1、基本属性

• className：设置为 org.apache.catalina.ha.tcp.ReplicationValve
  • filter —— 对于已知文件扩展名或 url ，可以在请求中使用 Valve 通知 cluster 没有修改 session，对于本次变化 cluster 没有必要通知 session 管理者。如果请求匹配该过滤器模型，cluster 会假设 session 没有发生变化。一个filter 样例大概是这样的 filter=“.*.gif|.*.js|.*.jpeg|.*.jpg|.*.png|.*.htm|.*.html|.*.css|.*.txt”。filter 使用  java.util.regex 的正则表达式。
• primaryIndicator：布尔值。如果为 true，replication valve 将会把 primaryIndicatorName 属性定义的名称插入到 request 属性中。该值无论是 Boolean.TRUE 或者 Boolean.FALSE，都会被放入 request 属性中。
• primaryIndicatorName：默认值为 org.apache.catalina.ha.tcp.isPrimarySession，这个值定义了一个 request 属性的名称，值是一个布尔值，表示会话所在的服务器是否为主服务器。
• statistics：布尔值。如果想让 valve 收集请求的统计数据，设置为 true。默认值为 false

以下是其它一些 valve：

• RemoteAddrValve：阻截来自特定的 IP 地址的请求。
• RemoteHostValve：阻截基于主机名称的请求。
• RequestDumperValve：记录了请求的详细信息。
• SingleSignOn Valve：当置于a下时，允许单点登录到该主机下的所有应用上。

更多信息见于 server.xml 文件的顶层和嵌套级别的元素和属性，可以在这里查看。

4、可选配置（server-<name>.xml）

4.1、包括 server-.xml文件

现在，如果我们想要为应用修改 server.xml 文件该怎么做？不能仅仅因为一个应用修改 server.xml 文件，因为它可能会对所有应用部署的初始化产生影响。对于指定的应用如何隔离指定的变化？

答案就是：创建一个 server-<name>.xml

server-.xml 是一个自定义的文件，包含了对于一个指定 app 需要隔离的配置变化。所有这种格式的文件都会在 server.xml 文件之后被调用。

4.2、使用自定义的 server-<name>.xml 代替 server.xml

不推荐这么做，但如果想满足下自己好奇心的除外，你可以通过编辑 catalina.bat 文件来使用你自己的 server.xml 作为替代。

1	catalina.bat start -config confserver-<name>.xml

总的来讲，无论是 serve.xml 还是你自己的 server-<name>.xml 文件，都是 container 的核心配置。对于应用开发者和发布管理员来讲，是一种在部署 J2EE 应用的容器中放入资源文件的补充策略。其它无论以何种方式实现的 J2EE 标准容器（厂商），都有相同的配置文件，允许自定义注入和绑定，同时允许在部署、重新部署和卸载时控制哪些服务是有效的。