Apache Tomcat9 版本9.0.14, 2018年12月6日
这是Apache Tomcat Servlet / JSP容器的文档包的顶级入口点 。的Apache Tomcat 9.0版本实现了Servlet 4.0和JavaServer Pages 2.3 规范从 Java社区进程,并包含许多额外的功能,使开发和部署Web应用程序和Web服务的有用平台。
从导航菜单(左侧)中选择一个链接,深入查看可用的更详细的文档。下面更详细地描述了每个可用的手册。
以下文档将帮助您下载和安装Apache Tomcat,并使用许多Apache Tomcat功能。
/WEB-INF/web.xml
)的简介。https
协议提供请求。参考
以下文档面向负责安装,配置和操作Apache Tomcat服务器的系统管理员。
conf/server.xml
文件的所有可用元素和属性。Apache Tomcat开发人员
以下文档适用于希望为Apache Tomcat项目开发做出贡献的Java开发人员。
对于管理员和Web开发人员来说,在开始之前,您应该熟悉一些重要的信息。本文档简要介绍了Tomcat容器背后的一些概念和术语。同样,告诉你,当您需要帮助时,去哪里寻求帮助。
术语
在阅读这些文件的过程中,您将遇到许多术语; 一些特定于Tomcat的,以及其他由Servlet和JSP规范定义的 。
这就对了。如果您发现我们需要在此部分添加更多字词,请告知我们。
目录和文件
这些是一些关键的tomcat目录:
*.sh
文件(对于Unix系统)是*.bat
文件的功能重复(对于Windows系统)。由于Win32命令行缺少某些功能,因此这里有一些额外的文件。CATALINA_HOME和CATALINA_BASE
在整个文档中,引用了以下两个属性:
/home/tomcat/apache-tomcat-9.0.10
或C:\Program Files\apache-tomcat-9.0.10
。CATALINA_BASE
属性。如果将属性设置为其他位置,则CATALINA_HOME位置包含静态源,例如.jar
文件或二进制文件。CATALINA_BASE位置包含配置文件,日志文件,已部署的应用程序和其他运行时要求。
为什么使用CATALINA_BASE
默认情况下,CATALINA_HOME和CATALINA_BASE指向同一目录。当您需要在一台计算机上运行多个Tomcat实例时,请手动设置CATALINA_BASE。这样做有以下好处:
.jar
文件和二进制文件,因此您可以轻松地将文件升级到较新版本,并使用相同的CATALIA_HOME目录将更改传播到所有Tomcat实例。.jar
文件。setenv
shell或bat脚本文件(取决于您的操作系统)。CATALINA_BASE的内容
在开始使用CATALINA_BASE之前,首先考虑并创建CATALINA_BASE使用的目录树。请注意,如果您不创建所有推荐的目录,Tomcat会自动创建目录。如果无法创建必要的目录,例如由于权限问题,Tomcat将无法启动,或者可能无法正常运行。
请考虑以下目录列表:
在bin
与目录setenv.sh
, setenv.bat
和tomcat-juli.jar
文件。
推荐:不。
查找顺序:首先检查CATALINA_BASE; 回退提供给CATALINA_HOME。
lib
具有要在类路径上添加的更多资源 的目录。
推荐:是的,如果您的应用程序依赖于外部库。
查找顺序:首先检查CATALINA_BASE; CATALINA_HOME第二次加载。
该logs
目录实例特定的日志文件。
推荐:是的。
webapps
自动加载的Web应用程序 的目录。
推荐:是的,如果要部署应用程序。
查找顺序:仅限CATALINA_BASE。
该work
包含用于部署的Web应用程序的临时工作目录目录。
推荐:是的。
该temp
临时文件使用的JVM目录。
推荐:是的。
我们建议您不要更改tomcat-juli.jar
文件。但是,如果您需要自己的日志记录实现,则可以替换tomcat-juli.jar
特定Tomcat实例的CATALINA_BASE位置中的文件。
我们还建议您将CATALINA_HOME/conf
目录中的所有配置文件复制 到 CATALINA_BASE/conf/
目录中。如果CATALINA_BASE中缺少配置文件,则不会回退到CATALINA_HOME。因此,这可能会导致失败。
至少,CATALINA_BASE必须包含:
那包括conf
目录。否则,Tomcat无法启动或无法正常运行。
有关高级配置信息,请参阅 RUNNING.txt 文件。
如何使用CATALINA_BASE
CATALINA_BASE属性是一个环境变量。您可以在执行Tomcat启动脚本之前进行设置,例如:
CATALINA_BASE=/tmp/tomcat_base1 bin/catalina.sh start
CATALINA_BASE=C:\tomcat_base1 bin/catalina.bat start
配置Tomcat
本节将使您了解容器配置期间使用的基本信息。
配置文件中的所有信息都在启动时读取,这意味着对文件的任何更改都需要重新启动容器。
寻求帮助
虽然我们已尽最大努力确保这些文件清晰易读,但我们可能错过了一些内容。下面提供了各种网站和邮件列表,以防您遇到困难。请记住,Tomcat的主要版本之间的一些问题和解决方案各不相同。当您在网上搜索时,会有一些与Tomcat 9无关的文档,但仅限于早期版本。
并且,如果您认为某些内容应该在文档中,请务必在TOMCAT-DEV列表中告知我们。
有几种方法可以将Tomcat设置为在不同平台上运行。这方面的主要文档是一个名为RUNNING.txt的文件 。如果以下信息无法回答您的一些问题,我们建议您参考该文件。
Windows
使用Windows安装程序可以轻松地在Windows上安装Tomcat。它的界面和功能类似于其他基于向导的安装程序,只有少数感兴趣的项目。
/C=<config file>
命令行参数覆盖安装程序使用的默认值。配置文件name=value
在单独的行上使用每对的格式 。可用配置选项的名称是: /C=...
一起使用/S
, /D=
可以执行Apache Tomcat的完全配置的无人参与安装。安装程序将创建允许启动和配置Tomcat的快捷方式。请务必注意,Tomcat管理Web应用程序只能在Tomcat运行时使用。
Unix守护进程
可以使用commons-daemon项目中的jsvc工具将Tomcat作为守护程序运行。jsvc的源代码压缩包包含在Tomcat二进制文件中,需要编译。构建jsvc需要C ANSI编译器(例如GCC),GNU Autoconf和JDK。
在运行脚本之前,JAVA_HOME
应将环境变量设置为JDK的基本路径。或者,在调用./configure
脚本时,可以使用--with-java
参数指定JDK的路径,例如./configure --with-java=/usr/java
。
使用以下命令应该会生成位于该$CATALINA_HOME/bin
文件夹中的已编译的jsvc二进制文件。这假设使用了GNU TAR,这CATALINA_HOME
是一个指向Tomcat安装基本路径的环境变量。
请注意,您应该在FreeBSD系统上使用GNU make(gmake)而不是本机BSD make。
cd $CATALINA_HOME/bin
tar xvfz commons-daemon-native.tar.gz
cd commons-daemon-1.1.x-native-src/unix
./configure
make
cp jsvc ../..
cd ../..
然后可以使用以下命令将Tomcat作为守护程序运行。
CATALINA_BASE=$CATALINA_HOME
cd $CATALINA_HOME
./bin/jsvc \-classpath $CATALINA_HOME/bin/bootstrap.jar:$CATALINA_HOME/bin/tomcat-juli.jar \-outfile $CATALINA_BASE/logs/catalina.out \-errfile $CATALINA_BASE/logs/catalina.err \-Dcatalina.home=$CATALINA_HOME \-Dcatalina.base=$CATALINA_BASE \-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager \-Djava.util.logging.config.file=$CATALINA_BASE/conf/logging.properties \org.apache.catalina.startup.Bootstrap
在Java 9上运行时,您需要在启动jsvc时另外指定以下内容以避免在关闭时发出警告。
...
--add-opens=java.base/java.lang=ALL-UNNAMED \
--add-opens=java.base/java.io=ALL-UNNAMED \
--add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED \
...
您可能还需要指定-jvm server
JVM是否默认使用服务器VM而不是客户端VM。这已在OSX上观察到。
jsvc还有其他有用的参数,例如-user
在守护进程初始化完成后它会切换到另一个用户。例如,这允许将Tomcat作为非特权用户运行,同时仍然可以使用特权端口。请注意,如果您使用此选项并以root身份启动Tomcat,则需要禁用org.apache.catalina.security.SecurityListener
以root身份运行时阻止Tomcat启动的 检查。
jsvc --help
将返回完整的jsvc使用信息。特别是,该-debug
选项对于调试运行jsvc的问题很有用。
该文件$CATALINA_HOME/bin/daemon.sh
可用作模板,以便在启动时/etc/init.d
使用jsvc 自动启动Tomcat 。
请注意,Commons-Daemon JAR文件必须位于运行时类路径上才能以这种方式运行Tomcat。Commons-Daemon JAR文件位于bootstrap.jar清单的Class-Path条目中,但如果您获得Commons-Daemon类的ClassNotFoundException或NoClassDefFoundError,则在启动jsvc时将Commons-Daemon JAR添加到-cp参数。
部署是用于将Web应用程序(第三方WAR或您自己的自定义Web应用程序)安装到Tomcat服务器的过程中的术语。
Web应用程序部署可以在Tomcat服务器中以多种方式完成。
在Tomcat管理器是一个可以交互使用(通过HTML GUI)或以编程方式(通过基于URL的API)来部署和管理Web应用程序的Web应用程序。
有许多方法可以执行依赖Manager Web应用程序的部署。Apache Tomcat为Apache Ant构建工具提供任务。 Apache Tomcat Maven插件 项目提供与Apache Maven的集成。还有一个名为Client Deployer的工具,可以从命令行使用它,并提供其他功能,例如编译和验证Web应用程序以及将Web应用程序打包到Web应用程序资源(WAR)文件中。
安装
静态部署Web应用程序不需要安装,因为Tomcat提供了开箱即用的功能。尽管Tomcat Manager手册中详细说明了某些配置,但Tomcat Manager的部署功能也不需要任何安装 。但是,如果您希望使用Tomcat客户端部署程序(TCD),则需要安装。
TCD未与Tomcat核心发行版一起打包,因此必须从“下载”区域单独下载。下载通常标记为 apache-tomcat-9.0.x-deployer。
TCD具有Apache Ant 1.6.2+和Java安装的先决条件。您的环境应定义指向Ant安装根目录的ANT_HOME环境值,以及指向Java安装的JAVA_HOME值。此外,您应该确保Ant的ant命令,并且Java javac编译器命令从您的操作系统提供的命令shell运行。
关于上下文的一个词
在谈论Web应用程序的部署时,需要理解Context的概念 。Context是Tomcat称之为Web应用程序的。
为了在Tomcat中配置Context, 需要一个Context Descriptor。上下文描述符只是一个XML文件,它包含上下文的Tomcat相关配置,例如命名资源或会话管理器配置。在早期版本的Tomcat中,Context Descriptor配置的内容通常存储在Tomcat的主配置文件server.xml中,但现在不建议这样做(尽管它目前仍然有效)。
上下文描述符不仅帮助Tomcat知道如何配置上下文,而且其他工具(如Tomcat Manager和TCD)通常使用这些上下文描述符来正确执行其角色。
上下文描述符的位置是:
(1)中的文件名为[webappname] .xml,但(2)中的文件名为context.xml。如果没有为Context提供Context Descriptor,Tomcat将使用默认值配置Context。
在Tomcat启动时部署
如果您对使用Tomcat Manager或TCD不感兴趣,那么您需要将Web应用程序静态部署到Tomcat,然后是Tomcat启动。您为此类部署部署Web应用程序的位置称为appBase
每个主机指定的位置。您可以将所谓的展开的Web应用程序(即非压缩的)复制到此位置,或压缩的Web应用程序资源.WAR文件。
appBase
仅当主机的deployOnStartup
属性为“true”时,将在Tomcat启动时部署 由主机(默认主机为“localhost”)属性指定的位置中的Web应用程序(默认appBase为“$ CATALINA_BASE / webapps”)。
在这种情况下,Tomcat启动时将发生以下部署顺序:
在正在运行的Tomcat服务器上部署
可以将Web应用程序部署到正在运行的Tomcat服务器。
如果Host autoDeploy
属性为“true”,则Host将尝试根据需要动态部署和更新Web应用程序,例如,如果将新的.WAR放入其中appBase
。为此,主机需要启用后台处理,这是默认配置。
autoDeploy
设置为“true”,运行Tomcat允许:
appBase
。appBase
。unpackWARs
属性设置为“false”,则不会发生爆炸,在这种情况下,Web应用程序将简单地重新部署为压缩存档。$CATALINA_BASE/conf/[enginename]/[hostname]/
目录中,则重新部署Web应用程序 。请注意,也可以在加载程序中配置Web应用程序重新加载,在这种情况下,将跟踪已加载的类以进行更改。
使用Tomcat Manager进行部署
Tomcat Manager包含在自己的手册页中。
使用客户端部署程序包进行部署
最后,可以使用Tomcat Client Deployer实现Web应用程序的部署。这是一个包,可用于验证,编译,压缩到.WAR,以及将Web应用程序部署到生产或开发Tomcat服务器。应该注意,此功能使用Tomcat Manager,因此目标Tomcat服务器应该运行。
假设用户熟悉Apache Ant以使用TCD。Apache Ant是一个脚本化的构建工具。TCD预先打包了要使用的构建脚本。只需要对Apache Ant有一定的了解(本页前面列出的安装,熟悉使用操作系统命令shell和配置环境变量)。
TCD包括Ant任务,部署前用于JSP编译的Jasper页面编译器,以及验证Web应用程序上下文描述符的任务。验证器任务(类org.apache.catalina.ant.ValidatorTask
)仅允许一个参数:爆炸Web应用程序的基本路径。
TCD使用爆炸的Web应用程序作为输入(请参阅下面使用的属性列表)。以部署程序编程部署的Web应用程序可以包括上下文描述符 /META-INF/context.xml
。
TCD包含一个即用型Ant脚本,具有以下目标:
compile
(默认):编译并验证Web应用程序。这可以单独使用,也不需要运行Tomcat服务器。已编译的应用程序将仅在关联的 Tomcat XYZ服务器版本上运行,并且无法保证在另一个Tomcat版本上运行,因为Jasper生成的代码取决于其运行时组件。还应注意,此目标还将自动编译位于/WEB-INF/classes
Web应用程序文件夹中的任何Java源文件 。deploy
:将Web应用程序(已编译或未编译)部署到Tomcat服务器。undeploy
:取消部署Web应用程序start
:启动Web应用程序reload
:重新加载Web应用程序stop
:停止Web应用程序为了配置部署,请创建deployer.properties
在TCD安装目录root中调用的文件。在此文件中,每行添加以下name = value对:此外,您需要确保已为目标Tomcat Manager(TCD使用)设置了用户,否则TCD将不会使用Tomcat Manager进行身份验证,部署将失败。要执行此操作,请参阅Tomcat Manager页面。
build
:默认情况下,使用的构建文件夹 ${build}/webapp/${path}
(${build}
默认情况下指向${basedir}/build
)。在compile
目标执行结束后,Web应用程序.WAR将位于 ${build}/webapp/${path}.war
。webapp
:包含将被编译和验证的爆炸Web应用程序的目录。默认情况下,该文件夹是 myapp
。path
:默认情况下,部署Web应用程序的上下文路径/myapp
。url
:正在运行的Tomcat服务器的Tomcat Manager Web应用程序的绝对URL,将用于部署和取消部署Web应用程序。默认情况下,部署者将尝试访问在localhost上运行的Tomcat实例 http://localhost:8080/manager/text
。username
:Tomcat Manager用户名(用户应该具有manager-script的角色)password
:Tomcat Manager密码。
在许多生产环境中,具有部署新Web应用程序或取消部署现有Web应用程序的功能非常有用,而无需关闭并重新启动整个容器。此外,即使您尚未将其声明为reloadable
在Tomcat服务器配置文件中,也可以请求现有应用程序重新加载自身。
为了支持这些功能,Tomcat包括一个支持以下功能的Web应用程序(默认安装在上下文路径上/manager
):
/WEB-INF/classes
或的内容更改/WEB-INF/lib
。<ResourceLink>
嵌套在<Context>
部署描述中的元素的部署工具。默认的Tomcat安装包括Manager。要将Manager Web应用程序的实例添加Context
到新主机,请在manager.xml
文件$CATALINA_BASE/conf/[enginename]/[hostname]
夹中安装 上下文配置文件 。这是一个例子:
<Context privileged="true" antiResourceLocking="false"docBase="${catalina.home}/webapps/manager"><Valve className="org.apache.catalina.valves.RemoteAddrValve"allow="127\.0\.0\.1" />
</Context>
如果您将Tomcat配置为支持多个虚拟主机(网站),则需要为每个虚拟主机配置一个Manager。
有三种方法可以使用Manager Web应用程序。
localhost
您的网站主机名:http://localhost:8080/manager/html
。配置Manager Application Access
下面的描述使用变量名$ CATALINA_BASE来引用解析大多数相对路径的基目录。如果尚未通过设置CATALINA_BASE目录为多个实例配置Tomcat,则$ CATALINA_BASE将设置为$ CATALINA_HOME的值,即已安装Tomcat的目录。
使用默认设置发送Tomcat是非常不安全的,这些设置允许Internet上的任何人在您的服务器上执行Manager应用程序。因此,Manager应用程序出厂时要求尝试使用它的任何人必须使用具有与之关联的manager-xxx角色之一的用户名和密码进行身份验证(角色名称取决于所需的功能)。此外,默认用户文件($CATALINA_BASE/conf/tomcat-users.xml
)中没有分配给这些角色的用户名。因此,默认情况下完全禁用对Manager应用程序的访问。
您可以web.xml
在Manager Web应用程序的文件中找到角色名称。可用的角色是:
HTML接口受到CSRF(跨站点请求伪造)攻击的保护,但文本和JMX接口无法受到保护。这意味着当使用Web浏览器访问Manager应用程序时,允许访问文本和JMX界面的用户必须小心谨慎。为了保持CSRF保护:
注意,JMX代理接口实际上是Tomcat的低级根类管理接口。如果他知道要调用什么命令,那么可以做很多事情。启用manager-jmx角色时应该谨慎 。
要启用对Manager Web应用程序的访问,您必须创建新的用户名/密码组合并将其中一个manager-xxx角色与其关联 ,或者将manager-xxx角色添加 到某些现有用户名/密码组合中。由于本文档的大部分内容都描述了使用文本界面,因此本示例将使用角色名称管理器脚本。具体如何配置用户名/密码取决于 您使用的Realm实现:
$CATALINA_BASE/conf/server.xml
。MemoryUserDatabase和MemoryRealm都默认读取存储在的XML格式文件 $CATALINA_BASE/conf/tomcat-users.xml
,可以使用任何文本编辑器进行编辑。此文件包含<user>
每个用户的XML ,可能如下所示: <user username="craigmcc" password="secret" roles="standard,manager-script" />
它定义了此人用于登录的用户名和密码,以及与其关联的角色名称。您可以将manager-script角色添加到roles
一个或多个现有用户的逗号分隔 属性,和/或使用该分配的角色创建新用户。第一次尝试发出下一节中描述的Manager命令之一时,您将面临使用BASIC身份验证登录的挑战。您输入的用户名和密码无关紧要,只要它们在用户数据库中标识拥有角色管理器脚本的有效用户即可。
除了密码限制之外,远程IP地址或主机可以通过添加RemoteAddrValve
或来限制对Manager Web应用程序的访问RemoteHostValve
。有关 详情,请参阅阀门文档 以下是通过IP地址限制对localhost的访问的示例:
<Context privileged="true"><Valve className="org.apache.catalina.valves.RemoteAddrValve"allow="127\.0\.0\.1"/>
</Context>
HTML用户友好界面
Manager Web应用程序的用户友好HTML界面位于
http://{host}:{port}/manager/html
如上所述,您需要manager-gui 角色才能访问它。有一个单独的文档,提供有关此接口的帮助。看到:
HTML接口受到CSRF(跨站点请求伪造)攻击的保护。每次访问HTML页面都会生成一个随机令牌,该令牌存储在您的会话中,并包含在页面上的所有链接中。如果您的下一个操作没有正确的令牌值,则该操作将被拒绝。如果令牌已过期,您可以从Manager的主页面或列表应用程序页面重新开始 。
支持的Manager命令
Manager应用程序知道如何处理的所有命令都在单个请求URI中指定,如下所示:
http://{host}:{port}/manager/text/{command}?{parameters}
where {host}
和{port}
表示运行Tomcat的主机名和端口号,{command}
表示要执行的Manager命令,并 {parameters}
表示特定于该命令的查询参数。在下面的插图中,根据您的安装自定义主机和端口。
这些命令通常由HTTP GET请求执行。该 /deploy
命令具有由HTTP PUT请求执行的表单。
常用参数
大多数命令接受以下一个或多个查询参数:
/deploy
命令,并且是于该命令的唯一可接受的格式。每个命令都将返回text/plain
格式的响应(即没有HTML标记的纯ASCII),使人和程序都能轻松阅读)。响应的第一行将以OK
或开头 FAIL
,表示请求的命令是否成功。如果失败,第一行的其余部分将包含遇到的问题的描述。一些命令包括如下所述的附加信息行。
国际化注 - Manager应用程序在资源包中查找其消息字符串,因此可能已为您的平台翻译了字符串。以下示例显示了消息的英文版本。
远程部署新的应用程序存档(WAR)
http://localhost:8080/manager/text/deploy?path=/foo
上载在此HTTP PUT请求中指定为请求数据的Web应用程序归档(WAR)文件,将其安装到appBase
相应虚拟主机的目录中,然后启动,appBase
从指定路径派生添加到WAR文件的WAR文件的名称。稍后可以使用该/undeploy
命令取消部署应用程序(并删除相应的WAR文件)。
该命令由HTTP PUT请求执行。
.WAR文件可以包括Tomcat特定的部署配置,方法是在其中包含Context配置XML文件 /META-INF/context.xml
。
网址参数包括:
update
:设置为true时,将首先取消部署任何现有更新。默认值设置为false。tag
:指定标记名称,这允许将部署的webapp与标记或标签相关联。如果取消部署Web应用程序,则可以在需要时仅使用标记重新部署它。config
:格式文件中的Context配置“.xml”文件的URL :/absolute/path/to/a/context.xml。这必须是Web应用程序上下文配置“.xml”文件的绝对路径,该文件包含Context配置元素。注 - 该命令与命令的逻辑相反/undeploy
。
如果安装和启动成功,您将收到如下响应:
OK - Deployed application at context path /foo
否则,响应将以FAIL
错误消息开头并包含错误消息。可能的问题原因包括:
所有当前运行的Web应用程序的上下文路径必须是唯一的。因此,您必须使用此上下文路径取消部署现有Web应用程序,或为新应用程序选择其他上下文路径。该update
参数可以指定为URL上的参数,其值为true
避免此错误。在这种情况下,将在执行部署之前对现有应用程序执行取消部署。
尝试启动新的Web应用程序时遇到异常。检查Tomcat日志以获取详细信息,但可能的解释包括解析/WEB-INF/web.xml
文件时出现问题,或者在初始化应用程序事件侦听器和过滤器时遇到缺少的类。
从本地路径部署新应用程序
部署并启动附加到指定上下文的新Web应用程序 path
(任何其他Web应用程序都不得使用该应用程序)。此命令与命令的逻辑相反/undeploy
。
此命令由HTTP GET请求执行。可以使用许多不同的方法来使用deploy命令。
部署以前部署的Web应用程序
http://localhost:8080/manager/text/deploy?path=/footoo&tag=footag
这可用于部署先前部署的Web应用程序,该应用程序已使用该tag
属性进行部署。请注意,Manager webapp的工作目录将包含以前部署的WAR; 删除它会使部署失败。
按URL部署目录或WAR
部署位于Tomcat服务器上的Web应用程序目录或“.war”文件。如果未path
指定,则路径和版本从目录名称或war文件名派生。该war
参数指定file:
目录或Web应用程序归档(WAR)文件的URL(包括方案)。引用WAR文件的URL支持的语法在java.net.JarURLConnection
类的Javadocs页面上描述 。仅使用引用整个WAR文件的URL。
在此示例中,位于/path/to/foo
Tomcat服务器上的目录 中的Web应用程序将部署为名为的Web应用程序上下文/footoo
。
http://localhost:8080/manager/text/deploy?path=/footoo&war=file:/path/to/foo
在此示例中,/path/to/bar.war
Tomcat服务器上的“.war”文件被部署为名为的Web应用程序上下文 /bar
。请注意,没有path
参数,因此上下文路径默认为没有“.war”扩展名的Web应用程序归档文件的名称。
http://localhost:8080/manager/text/deploy?war=file:/path/to/bar.war
从主机appBase部署目录或战争
部署位于Host appBase目录中的Web应用程序目录或“.war”文件。路径和可选版本派生自目录或war文件名。
在此示例中,位于 foo
Tomcat服务器的Host appBase目录中指定的子目录中的Web应用程序被部署为名为的Web应用程序上下文/foo
。请注意,使用的上下文路径是Web应用程序目录的名称。
http://localhost:8080/manager/text/deploy?war=foo
在此示例中,bar.war
位于Tomcat服务器上的Host appBase目录中的“.war”文件被部署为名为的Web应用程序上下文/bar
。
http://localhost:8080/manager/text/deploy?war=bar.war
使用Context配置“.xml”文件进行部署
如果Host deployXML标志设置为true,则可以使用Context配置“.xml”文件和可选的“.war”文件或Web应用程序目录来部署Web应用程序。上下文path
使用上下文“.XML”配置文件部署Web应用程序时不被使用。
Context配置“.xml”文件可以包含Web应用程序的有效XML,就像它在Tomcat server.xml
配置文件中配置一样。这是一个例子:
<Context path="/foobar" docBase="/path/to/application/foobar">
</Context>
当可选war
参数设置为Web应用程序“.war”文件或目录的URL时,它将覆盖在上下文配置“.xml”文件中配置的任何docBase。
以下是使用Context配置“.xml”文件部署应用程序的示例。
http://localhost:8080/manager/text/deploy?config=file:/path/context.xml
以下是使用Context配置“.xml”文件和位于服务器上的Web应用程序“.war”文件部署应用程序的示例。
http://localhost:8080/manager/text/deploy?config=file:/path/context.xml&war=file:/path/bar.war
部署说明
如果主机配置了unpackWARs = true并且您部署了war文件,则war将被解压缩到Host appBase目录中的目录中。
如果应用程序war或目录安装在Host appBase目录中,并且Host配置了autoDeploy = true,或者Context路径必须与没有“.war”扩展名的目录名或war文件名匹配。
为了在不受信任的用户可以管理Web应用程序时的安全性,可以将Host deployXML标志设置为false。这可以防止不受信任的用户使用配置XML文件部署Web应用程序,还可以防止他们部署位于其主机appBase之外的应用程序目录或“.war”文件。
部署响应
如果安装和启动成功,您将收到如下响应:
OK - Deployed application at context path /foo
否则,响应将以FAIL
错误消息开头并包含错误消息。可能的问题原因包括:
所有当前运行的Web应用程序的上下文路径必须是唯一的。因此,您必须使用此上下文路径取消部署现有Web应用程序,或为新应用程序选择其他上下文路径。该update
参数可以指定为URL上的参数,其值为true
避免此错误。在这种情况下,将在执行部署之前对现有应用程序执行取消部署。
war
参数指定的URL 必须标识此服务器上包含Web应用程序的“解压缩”版本的目录,或包含此应用程序的Web应用程序归档(WAR)文件的绝对URL。更正war
参数指定的值。
尝试启动新的Web应用程序时遇到异常。检查Tomcat日志以获取详细信息,但可能的解释包括解析/WEB-INF/web.xml
文件时出现问题,或者在初始化应用程序事件侦听器和过滤器时遇到缺少的类。
您指定的目录或Web应用程序的URL无效。此类URL必须以此开头file:
,并且WAR文件的URL必须以“.war”结尾。
上下文路径必须以斜杠字符开头。要引用ROOT Web应用程序,请使用“/”。
如果应用程序war或目录安装在Host appBase目录中,并且Host配置了autoDeploy = true,则Context路径必须与没有“.war”扩展名的目录名或war文件名匹配。
如果Host deployXML标志设置为false,则尝试在Host appBase目录之外部署Web应用程序目录或“.war”文件时,将发生此错误。
列出当前部署的应用程序
http://localhost:8080/manager/text/list
列出所有当前部署的Web应用程序的上下文路径,当前状态(running
或 stopped
)和活动会话数。启动Tomcat后立即执行的典型响应可能如下所示:
OK - Listed applications for virtual host localhost
/webdav:running:0:webdav
/examples:running:0:examples
/manager:running:0:manager
/:running:0:ROOT
/test:running:0:test##2
/test:running:0:test##1
重新加载现有应用程序
http://localhost:8080/manager/text/reload?path=/examples
发信号通知现有应用程序关闭并重新加载。当Web应用程序上下文不可重新加载并且您在/WEB-INF/classes
目录中更新了类或属性文件或者在目录中添加或更新了jar文件 时,这非常有用/WEB-INF/lib
。
如果此命令成功,您将看到如下响应:
OK - Reloaded application at context path /examples
否则,响应将以FAIL
错误消息开头并包含错误消息。可能的问题原因包括:
尝试重新启动Web应用程序时遇到异常。检查Tomcat日志以获取详细信息。
上下文路径必须以斜杠字符开头。要引用ROOT Web应用程序,请使用“/”。
您指定的上下文路径上没有已部署的应用程序。
该path
参数是必需的。
当前,web.xml
直接从WAR文件部署Web应用程序时,不支持应用程序重新加载(以获取对类或文件的更改 )。它仅在从解压缩目录部署Web应用程序时才有效。如果你使用的是WAR文件,你应该undeploy
再deploy
或者 deploy
与update
参数应用程序再次拿起您的更改。
列出OS和JVM属性
http://localhost:8080/manager/text/serverinfo
列出有关Tomcat版本,操作系统和JVM属性的信息。
如果发生错误,响应将以FAIL
包含错误消息的方式开始并包含错误消息。可能的问题原因包括:
尝试枚举系统属性时遇到异常。检查Tomcat日志以获取详细信息。
列出可用的全局JNDI资源
http://localhost:8080/manager/text/resources[?type=xxxxx]
列出可在上下文配置文件的资源链接中使用的全局JNDI资源。如果指定type
request参数,则该值必须是您感兴趣的资源类型的完全限定Java类名称(例如,您将指定 javax.sql.DataSource
获取所有可用JDBC数据源的名称)。如果未指定type
request参数,则将返回所有类型的资源。
根据是否type
指定了请求参数,正常响应的第一行将是:
OK - Listed global resources of all types
要么
OK - Listed global resources of type xxxxx
每个资源后跟一行。每行由冒号字符(“:”)分隔的字段组成,如下所示:
global
属性中使用 <ResourceLink>
。如果发生错误,响应将以FAIL
包含错误消息的方式开始并包含错误消息。可能的问题原因包括:
尝试枚举全局JNDI资源时遇到异常。检查Tomcat日志以获取详细信息。
您运行的Tomcat服务器已配置为没有全局JNDI资源。
会话统计
http://localhost:8080/manager/text/sessions?path=/examples
显示Web应用程序的默认会话超时,以及在实际超时时间的一分钟范围内的当前活动会话数。例如,在重新启动Tomcat然后在/examples
Web应用程序中执行其中一个JSP示例后,您可能会得到以下内容:
OK - Session information for application at context path /examples
Default maximum session inactive interval 30 minutes
<1 minutes: 1 sessions
1 - <2 minutes: 1 sessions
过期会话
http://localhost:8080/manager/text/expire?path=/examples&idle=num
显示会话统计信息(如上面的/sessions
命令),并使空闲时间超过num
分钟的会话失效。要使所有会话到期,请使用&idle=0
。
OK - Session information for application at context path /examples
Default maximum session inactive interval 30 minutes
1 - <2 minutes: 1 sessions
3 - <4 minutes: 1 sessions
>0 minutes: 2 sessions were expired
实际上/sessions
并且/expire
是同一命令的同义词。不同之处在于存在idle
参数。
启动现有应用程序
http://localhost:8080/manager/text/start?path=/examples
发出停止的应用程序信号以重新启动,并使其自身再次可用 例如,如果应用程序所需的数据库暂时不可用,则停止和启动很有用。通常最好停止依赖此数据库的Web应用程序,而不是让用户不断遇到数据库异常。
如果此命令成功,您将看到如下响应:
OK - Started application at context path /examples
否则,响应将以FAIL
错误消息开头并包含错误消息。可能的问题原因包括:
尝试启动Web应用程序时遇到异常。检查Tomcat日志以获取详细信息。
上下文路径必须以斜杠字符开头。要引用ROOT Web应用程序,请使用“/”。
您指定的上下文路径上没有已部署的应用程序。
该path
参数是必需的。
停止现有的应用程序
http://localhost:8080/manager/text/stop?path=/examples
发信号通知现有应用程序使其自身不可用,但将其部署。应用程序停止时进入的任何请求都将看到HTTP错误404,此应用程序将在列表应用程序命令中显示为“已停止”。
如果此命令成功,您将看到如下响应:
OK - Stopped application at context path /examples
否则,响应将以FAIL
错误消息开头并包含错误消息。可能的问题原因包括:
尝试停止Web应用程序时遇到异常。检查Tomcat日志以获取详细信息。
上下文路径必须以斜杠字符开头。要引用ROOT Web应用程序,请使用“/”。
您指定的上下文路径上没有已部署的应用程序。
path
参数是必需的。取消部署现有应用程序
http://localhost:8080/manager/text/undeploy?path=/examples
警告 - 此命令将删除appBase
此虚拟主机的目录(通常为“webapps”)中存在的所有Web应用程序工件。这将删除应用程序.WAR(如果存在),应用程序目录来自解压缩形式的部署或.WAR扩展以及$CATALINA_BASE/conf/[enginename]/[hostname]/
目录中的XML上下文定义 。如果您只是想让应用程序停止服务,则应该使用该/stop
命令。
发信号通知现有应用程序正常关闭自身,并将其从Tomcat中删除(这也使得此上下文路径可供以后重用)。此外,如果文档根目录存在appBase
于此虚拟主机的目录(通常为“webapps”)中,则将其删除。此命令与命令的逻辑相反 /deploy
。
如果此命令成功,您将看到如下响应:
OK - Undeployed application at context path /examples
否则,响应将以FAIL
错误消息开头并包含错误消息。可能的问题原因包括:
尝试取消部署Web应用程序时遇到异常。检查Tomcat日志以获取详细信息。
上下文路径必须以斜杠字符开头。要引用ROOT Web应用程序,请使用“/”。
没有已指定名称的已部署应用程序。
path
参数是必需的。发现内存泄漏
http://localhost:8080/manager/text/findleaks[?statusLine=[true|false]]
查找泄漏诊断会触发完整的垃圾回收。它应该在生产系统中极其谨慎地使用。
查找泄漏诊断尝试识别在停止,重新加载或取消部署时导致内存泄漏的Web应用程序。应始终使用分析器确认结果。诊断使用StandardHost实现提供的其他功能。如果使用不扩展StandardHost的自定义主机,它将无法工作。
从Java代码中明确触发完整的垃圾收集被记录为不可靠。此外,根据所使用的JVM,还有禁用显式GC触发的选项,例如-XX:+DisableExplicitGC
。如果要确保诊断程序成功运行完整的GC,则需要使用GC日志记录,JConsole或类似工具进行检查。
如果此命令成功,您将看到如下响应:
/leaking-webapp
如果您希望在响应中看到状态行,则statusLine
在请求中包含 查询参数,其值为 true
。
已停止,重新加载或取消部署的Web应用程序的每个上下文路径,但先前运行的哪些类仍然加载到内存中,从而导致内存泄漏,将在新行上列出。如果应用程序已多次重新加载,则可能会多次列出。
如果命令不成功,则响应将以FAIL
并包含错误消息开头 。
连接器SSL / TLS密码信息
http://localhost:8080/manager/text/sslConnectorCiphers
SSL Connector / Ciphers诊断列出了当前为每个连接器配置的SSL / TLS密码。对于NIO和NIO2,列出了各个密码套件的名称。对于APR,返回SSLCipherSuite的值。
响应将如下所示:
OK - Connector / SSL Cipher information
Connector[HTTP/1.1-8080]SSL is not enabled for this connector
Connector[HTTP/1.1-8443]TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHATLS_DHE_RSA_WITH_AES_128_CBC_SHATLS_ECDH_RSA_WITH_AES_128_CBC_SHATLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA...
连接器SSL / TLS证书链信息
http://localhost:8080/manager/text/sslConnectorCerts
SSL Connector / Certs诊断列出了当前为每个虚拟主机配置的证书链。
响应将如下所示:
OK - Connector / Certificate Chain information
Connector[HTTP/1.1-8080]
SSL is not enabled for this connector
Connector[HTTP/1.1-8443]-_default_-RSA
[
[Version: V3Subject: CN=localhost, OU=Apache Tomcat PMC, O=The Apache Software Foundation, L=Wakefield, ST=MA, C=USSignature Algorithm: SHA256withRSA, OID = 1.2.840.113549.1.1.11...
连接器SSL / TLS可信证书信息
http://localhost:8080/manager/text/sslConnectorTrustedCerts
SSL Connector / Certs诊断列出了当前为每个虚拟主机配置的可信证书。
响应将如下所示:
OK - Connector / Trusted Certificate information
Connector[HTTP/1.1-8080]
SSL is not enabled for this connector
Connector[AJP/1.3-8009]
SSL is not enabled for this connector
Connector[HTTP/1.1-8443]-_default_
[
[Version: V3Subject: CN=Apache Tomcat Test CA, OU=Apache Tomcat PMC, O=The Apache Software Foundation, L=Wakefield, ST=MA, C=US...
重新加载TLS配置
http://localhost:8080/manager/text/sslReload?tlsHostName=name
重新加载TLS配置文件(证书和密钥文件,这不会触发重新解析server.xml)。要为所有主机重新加载文件,请不要指定tlsHostName
参数。
OK - Reloaded TLS configuration for [_default_]
线程转储
http://localhost:8080/manager/text/threaddump
编写JVM线程转储。
响应将如下所示:
OK - JVM thread dump
2014-12-08 07:24:40.080
Full thread dump Java HotSpot(TM) Client VM (25.25-b02 mixed mode):"http-nio-8080-exec-2" Id=26 cpu=46800300 ns usr=46800300 ns blocked 0 for -1 ms waited 0 for -1 msjava.lang.Thread.State: RUNNABLElocks java.util.concurrent.ThreadPoolExecutor$Worker@1738ad4at sun.management.ThreadImpl.dumpThreads0(Native Method)at sun.management.ThreadImpl.dumpAllThreads(ThreadImpl.java:446)at org.apache.tomcat.util.Diagnostics.getThreadDump(Diagnostics.java:440)at org.apache.tomcat.util.Diagnostics.getThreadDump(Diagnostics.java:409)at org.apache.catalina.manager.ManagerServlet.threadDump(ManagerServlet.java:557)at org.apache.catalina.manager.ManagerServlet.doGet(ManagerServlet.java:371)at javax.servlet.http.HttpServlet.service(HttpServlet.java:618)at javax.servlet.http.HttpServlet.service(HttpServlet.java:725)
...
VM信息
http://localhost:8080/manager/text/vminfo
编写有关Java虚拟机的一些诊断信息。
响应将如下所示:
OK - VM info
2014-12-08 07:27:32.578
Runtime information:vmName: Java HotSpot(TM) Client VMvmVersion: 25.25-b02vmVendor: Oracle CorporationspecName: Java Virtual Machine SpecificationspecVersion: 1.8specVendor: Oracle CorporationmanagementSpecVersion: 1.2name: ...startTime: 1418012458849uptime: 393855isBootClassPathSupported: trueOS information:
...
保存配置
http://localhost:8080/manager/text/save
如果指定不带任何参数,则此命令将服务器的当前配置保存到server.xml。如果需要,现有文件将重命名为备份。
如果使用与已path
部署的Web应用程序的路径匹配的参数进行指定,则该Web应用程序的配置将保存到xmlBase
当前主机的适当命名的context.xml文件中。
要使用该命令,必须存在StoreConfig MBean。通常,这是使用StoreConfigLifecycleListener配置的。
如果命令不成功,则响应将以FAIL
并包含错误消息开头 。
服务器状态
从以下链接中,您可以查看有关服务器的状态信息。manager-xxx角色中的任何一个都允许访问此页面。
http://localhost:8080/manager/status
http://localhost:8080/manager/status/all
以HTML格式显示服务器状态信息。
http://localhost:8080/manager/status?XML=true
http://localhost:8080/manager/status/all?XML=true
以XML格式显示服务器状态信息。
首先,您拥有服务器和JVM版本号,JVM提供程序,操作系统名称和编号,后跟体系结构类型。
其次,有关于JVM的内存使用情况的信息。
然后,有关于Tomcat AJP和HTTP连接器的信息。两者都有相同的信息:
线程信息:最大线程数,最小和最大备用线程数,当前线程数和当前线程忙数。
请求信息:最大处理时间和处理时间,请求和错误计数,接收和发送的字节数。
显示阶段,时间,发送字节,字节接收,客户端,VHost和请求的表。表中列出了所有现有线程。以下是可能的线程阶段列表:
“解析和准备请求”:正在解析请求标头或正在进行读取请求主体(如果已指定传输编码)的必要准备。
“服务”:线程正在处理请求并生成响应。此阶段遵循“解析和准备请求”阶段,并在“完成”阶段之前。此阶段始终至少有一个线程(服务器状态页面)。
“整理”:请求处理结束。仍在输出缓冲区中的任何剩余响应都将发送到客户端。如果适当地保持连接活动,则此阶段之后是“保持活动”,如果“保持活动”不合适,则“准备好”。
“Keep-Alive”:如果客户端发送另一个请求,则线程会保持对客户端的连接打开。如果收到另一个请求,则下一阶段将是“解析和准备请求”。如果在保持活动超时之前没有收到请求,则连接将关闭,下一阶段将为“就绪”。
“就绪”:线程处于静止状态并准备好使用。
如果您使用/status/all
命令,则可以使用有关每个已部署Web应用程序的其他信息。
使用JMX代理Servlet
什么是JMX代理Servlet
JMX代理Servlet是一个轻量级代理,用于获取和设置tomcat内部。(或者通过MBean公开的任何类)它的用法不是非常用户友好,但UI对于集成命令行脚本以监视和更改tomcat的内部非常有用。您可以使用代理执行两项操作:获取信息和设置信息。为了让您真正了解JMX代理Servlet,您应该对JMX有一个大致的了解。如果您不知道JMX是什么,那么请准备好混淆。
JMX Query命令
采取以下形式:
http://webserver/manager/jmxproxy/?qry=STUFF
STUFF
您希望执行的JMX查询在哪里。例如,以下是您可能希望运行的一些查询:
qry=*%3Atype%3DRequestProcessor%2C* --> type=RequestProcessor
它将找到可以处理请求并报告其状态的所有工作人员。qry=*%3Aj2eeType=Servlet%2c* --> j2eeType=Servlet
返回所有加载的servlet。qry=Catalina%3Atype%3DEnvironment%2Cresourcetype%3DGlobal%2Cname%3DsimpleValue --> Catalina:type=Environment,resourcetype=Global,name=simpleValue
它按给定名称查找特定MBean。您需要对此进行实验以真正了解其功能如果您不提供qry
参数,那么将显示所有MBean。我们真的建议查看tomcat源代码并理解JMX规范,以便更好地理解您可能运行的所有查询。
JMX获取命令
JXMProxyServlet还支持“get”命令,您可以使用该命令获取特定MBean属性的值。该get
命令的一般形式是:
http://webserver/manager/jmxproxy/?get=BEANNAME&att=MYATTRIBUTE&key=MYKEY
您必须提供以下参数:
get
:完整的bean名称att
:您要获取的属性key
:(可选)CompositeData MBean属性的键如果一切顺利,那么它会说OK,否则将显示错误消息。例如,假设我们希望获取当前堆内存数据:
http://webserver/manager/jmxproxy/?get=java.lang:type=Memory&att=HeapMemoryUsage
或者,如果您只想要“使用”密钥:
http://webserver/manager/jmxproxy/?get=java.lang:type=Memory&att=HeapMemoryUsage&key=used
JMX Set命令
现在你可以查询一个MBean,它是时候去挖掘Tomcat的内部了!set命令的一般形式是:
http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE
所以你需要提供3个请求参数:
set
:完整的bean名称att
:您要更改的属性val
:新的价值如果一切正常,那么它会说OK,否则将显示错误消息。例如,假设我们希望立即启动调试 ErrorReportValve
。以下将调试设置为10。
http://localhost:8080/manager/jmxproxy/?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost&att=debug&val=10
我的结果是(YMMV):
Result: ok
如果我传入一个错误的值,这就是我所看到的。这是我使用的URL,我尝试设置调试等于'cow':
http://localhost:8080/manager/jmxproxy/?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost&att=debug&val=cow
当我尝试时,我的结果是
Error: java.lang.NumberFormatException: For input string: "cow"
JMX Invoke命令
该invoke
命令允许在MBean上调用方法。该命令的一般形式是:
http://webserver/manager/jmxproxy/?invoke=BEANNAME&op=METHODNAME&ps=COMMASEPARATEDPARAMETERS
例如,要调用Service使用的findConnectors()
方法 :
http://localhost:8080/manager/jmxproxy/?invoke=Catalina%3Atype%3DService&op=findConnectors&ps=
使用Ant执行Manager命令
除了通过HTTP请求执行Manager命令的能力之外,如上所述,Tomcat还包含一组方便的Ant(版本1.4或更高版本)构建工具的任务定义。要使用这些命令,必须执行以下设置操作:
$ANT_HOME/bin
目录添加到PATH
环境变量中。manager-script
角色的用户名/密码组合。要在Ant中使用自定义任务,必须先使用<import>
元素声明它们 。因此,您的build.xml
文件可能如下所示:
<project name="My Application" default="compile" basedir="."><!-- Configure the directory into which the web application is built --><property name="build" value="${basedir}/build"/><!-- Configure the context path for this application --><property name="path" value="/myapp"/><!-- Configure properties to access the Manager application --><property name="url" value="http://localhost:8080/manager/text"/><property name="username" value="myusername"/><property name="password" value="mypassword"/><!-- Configure the path to the Tomcat installation --><property name="catalina.home" value="/usr/local/apache-tomcat"/><!-- Configure the custom Ant tasks for the Manager application --><import file="${catalina.home}/bin/catalina-tasks.xml"/><!-- Executable Targets --><target name="compile" description="Compile web application"><!-- ... construct web application in ${build} subdirectory, andgenerated a ${path}.war ... --></target><target name="deploy" description="Install web application"depends="compile"><deploy url="${url}" username="${username}" password="${password}"path="${path}" war="file:${build}${path}.war"/></target><target name="reload" description="Reload web application"depends="compile"><reload url="${url}" username="${username}" password="${password}"path="${path}"/></target><target name="undeploy" description="Remove web application"><undeploy url="${url}" username="${username}" password="${password}"path="${path}"/></target></project>
注意:通过上面的导入定义资源任务将覆盖Ant 1.7中添加的资源数据类型。如果您希望使用资源数据类型,则需要使用Ant的命名空间支持进行修改, catalina-tasks.xml
以将Tomcat任务分配给它们自己的命名空间。
现在,您可以执行命令,例如ant deploy
将应用程序部署到正在运行的Tomcat实例,或者ant reload
告诉Tomcat重新加载它。另请注意,此build.xml
文件中的大多数有趣值都定义为可替换属性,因此您可以从命令行覆盖它们的值。例如,您可能认为在build.xml
文件的源代码中包含真实管理员密码存在安全风险 。要避免这种情况,请省略password属性,并从命令行指定它:
ant -Dpassword=secret deploy
任务输出捕获
使用Ant版本1.6.2或更高版本,Catalina任务提供了在属性或外部文件中捕获其输出的选项。它们直接支持以下<redirector>
类型属性的子集 :
属性 | 描述 | 需要 |
---|---|---|
产量 | 要写入输出的文件的名称。如果错误流也未重定向到文件或属性,则它将显示在此输出中。 | 没有 |
错误 | 应重定向命令标准错误的文件。 | 没有 |
LOGERROR | 当您希望在Ant的日志中看到错误输出并且您将输出重定向到文件/属性时,将使用此属性。错误输出将不包含在输出文件/属性中。如果使用error或errorProperty 属性重定向错误,则无效。 | 没有 |
附加 | 是否应附加或覆盖输出和错误文件。默认为false 。 | 没有 |
createemptyfiles | 是否应该创建输出和错误文件,即使是空的。默认为true 。 | 没有 |
outputproperty | 应存储命令输出的属性的名称。除非将错误流重定向到单独的文件或流,否则此属性将包含错误输出。 | 没有 |
errorproperty | 应存储命令标准错误的属性的名称。 | 没有 |
还可以指定一些其他属性:
属性 | 描述 | 需要 |
---|---|---|
alwaysLog | 当您希望查看正在捕获的输出时,将使用此属性,该属性也显示在Ant的日志中。除非您正在捕获任务输出,否则不得使用它。默认为false 。 Ant 1.6.3 将直接支持该属性<redirector> | 没有 |
failonerror | 当您希望避免任何管理器命令处理错误终止ant执行时,将使用此属性。默认为true 。必须设置为false ,如果要捕获错误输出,否则执行将在捕获任何内容之前终止。 此属性仅作用于管理器命令执行,任何错误或缺少的命令属性仍将导致Ant执行终止。 | 没有 |
它们还支持嵌入<redirector>
在其中您可以指定其完整的属性集元素,但是input
,inputstring
并且 inputencoding
,即使接受,不使用,因为他们在这方面没有任何意义。有关元素属性的详细信息, 请参阅ant手册<redirector>
。
下面是一个示例构建文件摘录,显示了如何使用此输出重定向支持:
<target name="manager.deploy"depends="context.status"if="context.notInstalled"><deploy url="${mgr.url}"username="${mgr.username}"password="${mgr.password}"path="${mgr.context.path}"config="${mgr.context.descriptor}"/></target><target name="manager.deploy.war"depends="context.status"if="context.deployable"><deploy url="${mgr.url}"username="${mgr.username}"password="${mgr.password}"update="${mgr.update}"path="${mgr.context.path}"war="${mgr.war.file}"/></target><target name="context.status"><property name="running" value="${mgr.context.path}:running"/><property name="stopped" value="${mgr.context.path}:stopped"/><list url="${mgr.url}"outputproperty="ctx.status"username="${mgr.username}"password="${mgr.password}"></list><condition property="context.running"><contains string="${ctx.status}" substring="${running}"/></condition><condition property="context.stopped"><contains string="${ctx.status}" substring="${stopped}"/></condition><condition property="context.notInstalled"><and><isfalse value="${context.running}"/><isfalse value="${context.stopped}"/></and></condition><condition property="context.deployable"><or><istrue value="${context.notInstalled}"/><and><istrue value="${context.running}"/><istrue value="${mgr.update}"/></and><and><istrue value="${context.stopped}"/><istrue value="${mgr.update}"/></and></or></condition><condition property="context.undeployable"><or><istrue value="${context.running}"/><istrue value="${context.stopped}"/></or></condition></target>
警告:即使它没有多大意义,并且总是一个坏主意,不止一次调用Catalina任务,严重设置Ant任务取决于链可能导致在同一个Ant运行中多次调用任务,甚至如果不打算。当您从该任务捕获输出时,应该谨慎行事,因为这可能会导致意外情况:
append="true"
,在这种情况下,您将看到附加到文件的每个任务调用的输出。
在Tomcat的主机管理应用程序,您可以创建,删除,否则在Tomcat管理虚拟主机。本操作指南最好附有以下文档:
在Tomcat的主机管理应用程序是Tomcat安装的一部分,默认情况下可以通过如下的背景:/host-manager
。您可以通过以下方式使用主机管理器:
{server}:{port}/host-manager/html
。{server}:{port}/host-manager/text
。这两种方式都允许您添加,删除,启动和停止虚拟主机。可以使用该persist
命令预先进行更改。本文档重点介绍文本界面。有关图形界面的更多信息,请参阅 Host Manager App - HTML界面。
配置Manager Application Access
以下描述$CATALINA_HOME
用于引用基本Tomcat目录。例如C:/tomcat9
,它是您安装Tomcat的目录,或 /usr/share/tomcat9
。
Host Manager应用程序要求用户具有以下角色之一:
admin-gui
- 将此角色用于图形Web界面。admin-script
- 将此角色用于脚本Web界面。要启用对Host Manager应用程序的文本界面的访问,请为Tomcat用户授予适当的角色,或者创建具有正确角色的新角色。例如,打开${CATALINA_BASE}/conf/tomcat-users.xml
并输入以下内容:
<user username="test" password="chang3m3N#w" roles="admin-script"/>
无需进一步设置。现在访问时 {server}:{port}/host-manager/text/${COMMAND}
,您可以使用创建的凭据登录。例如:
$ curl -u ${USERNAME}:${PASSWORD} http://localhost:8080/host-manager/text/list
OK - Listed hosts
localhost:
请注意,如果使用,或 机制检索用户 DataSourceRealm
,请分别在数据库或目录服务器中添加适当的角色。 JDBCRealm
JNDIRealm
命令列表
支持以下命令:
在以下小节中,假定用户名和密码为 test:test。对于您的环境,请使用前面部分中创建的凭据。
列表命令
使用list命令查看Tomcat实例上的可用虚拟主机。
示例命令:
curl -u test:test http://localhost:8080/host-manager/text/list
响应示例:
OK - Listed hosts
localhost:
添加命令
使用add命令添加新的虚拟主机。用于add命令的参数:
示例命令:
curl -u test:test http://localhost:8080/host-manager/text/add?name=www.awesomeserver.com&aliases=awesomeserver.com&appBase/mnt/appDir&deployOnStartup=true
响应示例:
add: Adding host [www.awesomeserver.com]
删除命令
使用remove命令删除虚拟主机。用于remove命令的参数:
示例命令:
curl -u test:test http://localhost:8080/host-manager/text/remove?name=www.awesomeserver.com
响应示例:
remove: Removing host [www.awesomeserver.com]
启动命令
使用start命令启动虚拟主机。用于启动命令的参数:
示例命令:
curl -u test:test http://localhost:8080/host-manager/text/start?name=www.awesomeserver.com
响应示例:
OK - Host www.awesomeserver.com started
停止命令
使用stop命令停止虚拟主机。用于stop命令的参数:
示例命令:
curl -u test:test http://localhost:8080/host-manager/text/stop?name=www.awesomeserver.com
响应示例:
OK - Host www.awesomeserver.com stopped
坚持命令
使用persist命令将虚拟主机持久保存到 server.xml中。用于persist命令的参数:
默认情况下禁用此功能。要启用此选项,必须首先配置StoreConfigLifecycleListener
侦听器。为此,请将以下侦听器添加到server.xml:
<Listener className="org.apache.catalina.storeconfig.StoreConfigLifecycleListener"/>
示例命令:
curl -u test:test http://localhost:8080/host-manager/text/persist?name=www.awesomeserver.com
响应示例:
OK - Configuration persisted
手动输入示例:
<Host appBase="www.awesomeserver.com" name="www.awesomeserver.com" deployXML="false" unpackWARs="false">
</Host>
本文档介绍如何通过连接到用户名,密码和用户角色的现有“数据库” 来配置Tomcat以支持容器管理的安全性。如果您使用的是包含一个或多个<security-constraint>
元素的Web应用程序,以及<login-config>
定义用户如何验证自身身份的元素, 则只需要关注此问题 。如果您不使用这些功能,则可以安全地跳过本文档。
有关容器管理安全性的基本背景信息,请参阅Servlet规范(版本2.4),第12节。
有关利用Tomcat 的单点登录功能(允许用户在与虚拟主机关联的整个Web应用程序集中进行一次身份验证)的信息,请参阅 此处。
什么是领域?
一个领域是一个用户名和标识Web应用程序的有效用户(或一组Web应用程序)的密码“数据库”,加上名单的枚举角色与每个有效用户相关联。你可以把角色相似的群体在类Unix的操作系统,因为访问特定的Web应用程序资源被授予具有特定角色(而不是列举相关的用户名的列表)的所有用户。特定用户可以拥有与其用户名相关联的任意数量的角色。
尽管Servlet规范描述了应用程序声明其安全性要求的可移植机制(在 web.xml
部署描述符中),但是没有可定义servlet容器与关联用户和角色信息之间的接口的可移植API。但是,在许多情况下,需要将servlet容器“连接”到生产环境中已存在的某些现有认证数据库或机制。因此,Tomcat定义了一个Java接口(org.apache.catalina.Realm
),可以通过“插件”组件来实现,以建立此连接。提供了六个标准插件,支持与各种身份验证信息源的连接:
conf/tomcat-users.xml
)支持。conf/tomcat-users.xml
)初始化的。也可以编写自己的Realm
实现,并将其与Tomcat集成。为此,您需要:
org.apache.catalina.Realm
,配置领域
在深入了解标准Realm实现的细节之前,一般来说,了解Realm的配置方式非常重要。通常,您将在conf/server.xml
配置文件中添加一个XML元素,如下所示:
<Realm className="... class name for this implementation"... other attributes for this implementation .../>
该<Realm>
元素可以嵌套在以下任何一个Container
元素中。Realm元素的位置直接影响该Realm的“范围”(即哪些Web应用程序将共享相同的身份验证信息):
<Host>
或<Context>
元素中的Realm元素覆盖。<Context>
元素中的Realm元素覆盖。消化密码
对于每个标准Realm
实现,用户的密码(默认情况下)以明文形式存储。在许多环境中,这是不合需要的,因为认证数据的临时观察者可以收集足够的信息以成功登录,并冒充其他用户。为避免此问题,标准实现支持消化 用户密码的概念。这允许对存储的密码版本进行编码(以不易翻转的形式),但 Realm
实现仍然可以用于认证。
当标准领域通过检索存储的密码并将其与用户提供的值进行比较进行身份验证时,您可以通过在元素中放置元素来选择消化的密码 。支持SSHA,SHA或MD5算法之一的简单选择就是使用。必须将此元素配置为该类支持的摘要算法之一(SSHA,SHA或MD5)。选择此选项时,存储在密码中的密码内容必须是密码的明文版本,由指定的算法消化。 CredentialHandler
<Realm>
MessageDigestCredentialHandler
java.security.MessageDigest
Realm
当authenticate()
调用Realm 的方法时,用户指定的(明文)密码本身被相同的算法消化,并将结果与返回的值进行比较 Realm
。相等匹配意味着原始密码的明文版本与用户提供的密码版本相同,因此应该授权该用户。
要计算明文密码的消化值,需要支持两种便捷技术:
Digest()
方法 org.apache.catalina.realm.RealmBase
,将明文密码,摘要算法名称和编码作为参数传递。此方法将返回已消化的密码。CATALINA_HOME/bin/digest.[bat|sh] -a {algorithm} {cleartext-password}
此明文密码的消化版本将返回标准输出。如果使用具有DIGEST认证的消化密码,则用于生成摘要的明文不同,摘要必须使用MD5算法的一次迭代而不使用盐。在上面的例子中 {cleartext-password}
必须替换为 {username}:{realm}:{cleartext-password}
。例如,在开发环境中,这可能采用这种形式 testUser:Authentication required:testPassword
。值 {realm}
取自<realm-name>
Web应用程序的元素<login-config>
。如果未在web.xml中指定,Authentication required
则使用默认值。
使用支持使用平台默认以外的编码的用户名和/或密码
CATALINA_HOME/bin/digest.[bat|sh] -a {algorithm} -e {encoding} {input}
但需要注意确保输入正确传递到消化器。蒸煮器返回{input}:{digest}
。如果输入在返回中显示为已损坏,则摘要将无效。
摘要的输出格式是{salt}${iterations}${digest}
。如果salt长度为零且迭代计数为1,则输出将简化为{digest}
。
完整的语法CATALINA_HOME/bin/digest.[bat|sh]
是:
CATALINA_HOME/bin/digest.[bat|sh] [-a <algorithm>] [-e <encoding>][-i <iterations>] [-s <salt-length>] [-k <key-length>][-h <handler-class-name>] <credentials>
SHA-512
则将使用默认值Charset#defaultCharset()
)。示例应用
Tomcat附带的示例应用程序包括受安全约束保护的区域,利用基于表单的登录。要访问它,请将浏览器指向 http:// localhost:8080 / examples / jsp / security / protected /, 然后使用为默认UserDatabaseRealm描述的用户名和密码之一登录 。
经理申请
如果您希望使用Manager应用 程序在正在运行的Tomcat安装中部署和取消部署应用程序,则必须将“manager-gui”角色添加到所选Realm实现中的至少一个用户名。这是因为管理器Web应用程序本身使用安全约束,该约束要求角色“manager-gui”访问该应用程序的HTML界面内的任何请求URI。
出于安全原因,默认Realm中没有用户名(即使用 conf/tomcat-users.xml
被分配了“manager-gui”角色。因此,在Tomcat管理员专门为一个或多个用户分配此角色之前,没有人能够利用此应用程序的功能。
领域记录
由a记录的调试和异常消息将由Realm
与域的容器相关联的日志记录配置记录:其周围的Context, Host或 Engine。
JDBCRealm
介绍
JDBCRealm是Tomcat Realm
接口的实现, 它在通过JDBC驱动程序访问的关系数据库中查找用户。只要您的数据库结构符合以下要求,就可以使用大量的配置灵活性来适应现有的表名和列名:
Realm
应该识别的每个有效用户的行。要设置Tomcat以使用JDBCRealm,您需要执行以下步骤:
$CATALINA_HOME/lib
目录中放置要使用的JDBC驱动程序的副本 。请注意,只能识别JAR文件!<Realm>
在$CATALINA_BASE/conf/server.xml
文件中设置元素,如下所述 。领域元素属性
要配置JDBCRealm,您将创建一个<Realm>
元素并将其嵌套在您的$CATALINA_BASE/conf/server.xml
文件中,如上所述。JDBCRealm的属性在Realm配置文档中定义。
例
用于创建所需表的示例SQL脚本可能如下所示(根据特定数据库的需要调整语法):
create table users (user_name varchar(15) not null primary key,user_pass varchar(15) not null
);create table user_roles (user_name varchar(15) not null,role_name varchar(15) not null,primary key (user_name, role_name)
);
示例Realm
元素包含(注释掉)在默认$CATALINA_BASE/conf/server.xml
文件中。下面是使用名为“authority”的MySQL数据库的示例,该数据库使用上述表配置,并使用用户名“dbuser”和密码“dbpass”进行访问:
<Realm className="org.apache.catalina.realm.JDBCRealm"driverName="org.gjt.mm.mysql.Driver"connectionURL="jdbc:mysql://localhost/authority?user=dbuser&password=dbpass"userTable="users" userNameCol="user_name" userCredCol="user_pass"userRoleTable="user_roles" roleNameCol="role_name"/>
补充说明
JDBCRealm根据以下规则运行:
authenticate()
方法 Realm
。因此,您将立即反映您对数据库所做的任何更改(新用户,更改的密码或角色等)。DataSourceRealm
介绍
DataSourceRealm是Tomcat Realm
接口的一个实现, 它在通过名为JDBC DataSource的JNDI访问的关系数据库中查找用户。只要您的数据库结构符合以下要求,就可以使用大量的配置灵活性来适应现有的表名和列名:
Realm
应该识别的每个有效用户的行。快速开始
要设置Tomcat以使用DataSourceRealm,您需要执行以下步骤:
Realm
的localDataSource
适当属性,取决于JNDI的DataSource的定义在哪里。<Realm>
在$CATALINA_BASE/conf/server.xml
文件中设置元素,如下所述 。领域元素属性
要配置DataSourceRealm,您将创建一个<Realm>
元素并将其嵌套在您的$CATALINA_BASE/conf/server.xml
文件中,如上所述。DataSourceRealm的属性在Realm 配置文档中定义。
例
用于创建所需表的示例SQL脚本可能如下所示(根据特定数据库的需要调整语法):
create table users (user_name varchar(15) not null primary key,user_pass varchar(15) not null
);create table user_roles (user_name varchar(15) not null,role_name varchar(15) not null,primary key (user_name, role_name)
);
下面是使用名为“authority”的MySQL数据库的示例,该数据库使用上述表配置,并使用名为“java:/ comp / env / jdbc / authority”的JNDI JDBC DataSource进行访问。
<Realm className="org.apache.catalina.realm.DataSourceRealm"dataSourceName="jdbc/authority"userTable="users" userNameCol="user_name" userCredCol="user_pass"userRoleTable="user_roles" roleNameCol="role_name"/>
补充说明
DataSourceRealm根据以下规则运行:
authenticate()
方法 Realm
。因此,您将立即反映您对数据库所做的任何更改(新用户,更改的密码或角色等)。JNDIRealm
介绍
JNDIRealm是Tomcat Realm
接口的实现, 它在JNDI提供程序(通常是JNDI API类可用的标准LDAP提供程序)访问的LDAP目录服务器中查找用户。该领域支持使用目录进行身份验证的各种方法。
连接到目录
领域与目录的连接由connectionURL配置属性定义 。这是一个URL,其格式由JNDI提供程序定义。它通常是一个LDAP URL,它指定要连接的目录服务器的域名,以及可选的所需根命名上下文的端口号和可分辨名称(DN)。
如果您有多个提供程序,则可以配置 alternateURL。如果一个套接字连接不能对供应商在做的ConnectionURL的将尝试使用alternateURL。
在进行连接以搜索目录并检索用户和角色信息时,域将使用connectionName和 connectionPassword属性指定的用户名和密码对目录进行身份验证 。如果未指定这些属性,则连接是匿名的。在许多情况下这已足够。
选择用户的目录条目
每个可以进行身份验证的用户必须DirContext
通过与connectionURL属性定义 的初始元素对应的单个条目在目录中表示。此用户条目必须具有包含用于身份验证的用户名的属性。
通常,用户条目的可分辨名称包含用于身份验证的用户名,但对于所有用户而言都是相同的。在这种情况下,userPattern属性可用于指定DN,“{0}”标记用户名应替换的位置。
否则,领域必须搜索目录以查找包含用户名的唯一条目。以下属性配置此搜索:
true
,如果你想搜索的根的整个子树的用户群条目。false
请求单级搜索的默认值,仅包括顶级。验证用户
绑定模式
默认情况下,域通过绑定到具有该用户的条目的DN和用户呈现的密码的目录来验证用户。如果此简单绑定成功,则认为用户已通过身份验证。
出于安全原因,目录可以存储用户密码的摘要而不是明文版本(有关更多信息,请参阅 消化密码)。在这种情况下,作为简单绑定操作的一部分,目录自动计算用户提供的明文密码的正确摘要,然后再根据存储的值进行验证。因此,在绑定模式中,域不涉及摘要处理。未使用摘要属性,如果设置,将忽略该 属性。
比较模式
或者,领域可以从目录中检索存储的密码,并将其明确地与用户呈现的值进行比较。通过将userPassword属性设置为包含密码的用户条目中的目录属性的名称来配置此模式 。
比较模式有一些缺点。首先, 必须配置connectionName和 connectionPassword属性以允许领域读取目录中的用户密码。出于安全原因,这通常是不可取的; 实际上,许多目录实现甚至不允许目录管理器读取这些密码。此外,领域必须自己处理密码摘要,包括所用算法的变化以及在目录中表示密码哈希的方式。但是,领域有时可能需要访问存储的密码,例如,以支持HTTP摘要访问身份验证(RFC 2069)。(注意,HTTP摘要认证与存储库中用于用户信息的密码摘要的存储不同,如上所述)。
为用户分配角色
目录领域支持两种在目录中表示角色的方法:
角色作为显式目录条目
角色可以由显式目录条目表示。角色条目通常是LDAP组条目,其中一个属性包含角色的名称,另一个属性的值是该角色中用户的可分辨名称或用户名。以下属性配置目录搜索以查找与经过身份验证的用户关联的角色的名称:
true
,如果你想搜索的根的整个子树roleBase
条目。false
请求单级搜索的默认值,仅包括顶级。true
如果要在角色中嵌套角色,请设置为 。如果已配置,则将以递归方式尝试每个新找到的roleName和可分辨名称以进行新的角色搜索。默认值为false
。角色作为用户条目的属性
角色名称也可以保存为用户目录条目中属性的值。使用userRoleName指定此属性的名称。
可以使用两种角色表示方法的组合。
快速开始
要设置Tomcat以使用JNDIRealm,您需要按照以下步骤操作:
<Realm>
在$CATALINA_BASE/conf/server.xml
文件中设置元素,如下所述 。领域元素属性
要配置JNDIRealm,您将创建一个<Realm>
元素并将其嵌套在您的$CATALINA_BASE/conf/server.xml
文件中,如上所述。JNDIRealm的属性在Realm配置文档中定义。
例
在目录服务器中创建适当的模式超出了本文档的范围,因为它对每个目录服务器实现都是唯一的。在下面的示例中,我们假设您使用的是OpenLDAP目录服务器(版本2.0.11或更高版本)的分发版,可以从https://www.openldap.org下载 。假设您的slapd.conf
文件包含以下设置(以及其他设置):
database ldbm
suffix dc="mycompany",dc="com"
rootdn "cn=Manager,dc=mycompany,dc=com"
rootpw secret
我们假设connectionURL
目录服务器与Tomcat在同一台机器上运行。 有关配置和使用JNDI LDAP提供程序的详细信息,请参阅http://docs.oracle.com/javase/7/docs/technotes/guides/jndi/index.html。
接下来,假设此目录服务器已填充了如下所示的元素(以LDIF格式):
# Define top-level entry
dn: dc=mycompany,dc=com
objectClass: dcObject
dc:mycompany# Define an entry to contain people
# searches for users are based on this entry
dn: ou=people,dc=mycompany,dc=com
objectClass: organizationalUnit
ou: people# Define a user entry for Janet Jones
dn: uid=jjones,ou=people,dc=mycompany,dc=com
objectClass: inetOrgPerson
uid: jjones
sn: jones
cn: janet jones
mail: j.jones@mycompany.com
userPassword: janet# Define a user entry for Fred Bloggs
dn: uid=fbloggs,ou=people,dc=mycompany,dc=com
objectClass: inetOrgPerson
uid: fbloggs
sn: bloggs
cn: fred bloggs
mail: f.bloggs@mycompany.com
userPassword: fred# Define an entry to contain LDAP groups
# searches for roles are based on this entry
dn: ou=groups,dc=mycompany,dc=com
objectClass: organizationalUnit
ou: groups# Define an entry for the "tomcat" role
dn: cn=tomcat,ou=groups,dc=mycompany,dc=com
objectClass: groupOfUniqueNames
cn: tomcat
uniqueMember: uid=jjones,ou=people,dc=mycompany,dc=com
uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com# Define an entry for the "role1" role
dn: cn=role1,ou=groups,dc=mycompany,dc=com
objectClass: groupOfUniqueNames
cn: role1
uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com
Realm
如上所述配置的OpenLDAP目录服务器的示例元素可能如下所示,假设用户使用他们的uid(例如jjones)登录到应用程序,并且匿名连接足以搜索目录并检索角色信息:
<Realm className="org.apache.catalina.realm.JNDIRealm"connectionURL="ldap://localhost:389"userPattern="uid={0},ou=people,dc=mycompany,dc=com"roleBase="ou=groups,dc=mycompany,dc=com"roleName="cn"roleSearch="(uniqueMember={0})"
/>
使用此配置,域将通过将用户名替换为用户名来确定用户的可分辨名称 userPattern
,通过绑定到具有此DN的目录和从用户接收的密码进行身份验证,并搜索目录以查找用户的角色。
现在假设用户在登录时需要输入他们的电子邮件地址而不是用户ID。在这种情况下,领域必须在目录中搜索用户的条目。(当用户条目保存在可能与不同组织单位或公司位置相对应的多个子树中时,也需要进行搜索)。
此外,假设除了组条目之外,您还希望使用用户条目的属性来保存角色。现在Janet Jones的条目可能如下:
dn: uid=jjones,ou=people,dc=mycompany,dc=com
objectClass: inetOrgPerson
uid: jjones
sn: jones
cn: janet jones
mail: j.jones@mycompany.com
memberOf: role2
memberOf: role3
userPassword: janet
此领域配置将满足新要求:
<Realm className="org.apache.catalina.realm.JNDIRealm"connectionURL="ldap://localhost:389"userBase="ou=people,dc=mycompany,dc=com"userSearch="(mail={0})"userRoleName="memberOf"roleBase="ou=groups,dc=mycompany,dc=com"roleName="cn"roleSearch="(uniqueMember={0})"
/>
现在,当Janet Jones以“j.jones@mycompany.com”身份登录时,领域会在目录中搜索具有该值作为其邮件属性的唯一条目,并尝试uid=jjones,ou=people,dc=mycompany,dc=com
使用给定密码绑定到目录 。如果身份验证成功,则会为她分配三个角色:“role2”和“role3”,其目录条目中“memberOf”属性的值,以及“tomcat”,即唯一的组条目中“cn”属性的值她是会员。
最后,要通过从目录中检索密码并在领域中进行本地比较来验证用户,您可以使用如下的域配置:
<Realm className="org.apache.catalina.realm.JNDIRealm"connectionName="cn=Manager,dc=mycompany,dc=com"
connectionPassword="secret"connectionURL="ldap://localhost:389"userPassword="userPassword"userPattern="uid={0},ou=people,dc=mycompany,dc=com"roleBase="ou=groups,dc=mycompany,dc=com"roleName="cn"roleSearch="(uniqueMember={0})"
/>
但是,如上所述,用于身份验证的默认绑定模式通常是首选。
补充说明
JNDIRealm按照以下规则运作:
authenticate()
方法 Realm
。因此,您将立即反映您对目录所做的任何更改(新用户,更改的密码或角色等)。是UserDatabaseRealm
介绍
UserDatabaseRealm是Tomcat Realm
接口的实现, 它使用JNDI资源来存储用户信息。默认情况下,JNDI资源由XML文件支持。它不是为大规模生产用途而设计的。在启动时,UserDatabaseRealm从XML文档加载有关所有用户及其相应角色的信息(默认情况下,从中加载此文档 $CATALINA_BASE/conf/tomcat-users.xml
)。用户,他们的密码和他们的角色都可以动态编辑,通常是通过JMX。更改可能会保存并将反映在XML文件中。
领域元素属性
要配置UserDatabaseRealm,您将创建一个<Realm>
元素并将其嵌套在您的$CATALINA_BASE/conf/server.xml
文件中,如上所述。UserDatabaseRealm的属性在Realm 配置文档中定义。
用户文件格式
users文件使用与MemoryRealm相同的格式 。
例
Tomcat的默认安装配置了嵌套在<Engine>
元素内的UserDatabaseRealm ,因此它适用于所有虚拟主机和Web应用程序。该conf/tomcat-users.xml
文件的默认内容 是:
<tomcat-users><user username="tomcat" password="tomcat" roles="tomcat" /><user username="role1" password="tomcat" roles="role1" /><user username="both" password="tomcat" roles="tomcat,role1" />
</tomcat-users>
补充说明
UserDatabaseRealm根据以下规则运行:
authenticate()
方法 Realm
。MemoryRealm
介绍
MemoryRealm是Tomcat Realm
接口的简单演示实现。它不是为生产用途而设计的。在启动时,MemoryRealm从XML文档加载有关所有用户及其相应角色的信息(默认情况下,加载此文档$CATALINA_BASE/conf/tomcat-users.xml
)。在重新启动Tomcat之前,无法识别对此文件中数据的更改。
领域元素属性
要配置MemoryRealm,您将创建一个<Realm>
元素并将其嵌套在您的$CATALINA_BASE/conf/server.xml
文件中,如上所述。MemoryRealm的属性在Realm配置文档中定义。
用户文件格式
users文件(默认情况下,conf/tomcat-users.xml
必须是带有根元素的XML文档<tomcat-users>
。嵌套在根元素内部将是<user>
每个有效用户的元素,包含以下属性:
digest
属性未设置上 <Realm>
所描述的元素,或适当地消化此相反)。补充说明
MemoryRealm根据以下规则运行:
authenticate()
方法 Realm
。JAASRealm
介绍
JAASRealm是Tomcat Realm
接口的一个实现, 它通过Java身份验证和授权服务(JAAS)框架对用户进行身份验证,该框架现在作为标准Java SE API的一部分提供。
使用JAASRealm使开发人员能够将几乎任何可以想象的安全领域与Tomcat的CMA结合起来。
JAASRealm是基于JA 规范请求196的基于JAAS的J2EE v1.4 J2EE认证框架的Tomcat的原型,用于增强容器管理的安全性并促进其“可插入”认证机制,其实现与容器无关。
基于JAAS登录模块和主体(请参阅javax.security.auth.spi.LoginModule
和javax.security.Principal
),您可以开发自己的安全机制或包装另一个第三方机制,以便与Tomcat实现的CMA集成。
快速开始
要设置Tomcat以将JAASRealm与您自己的JAAS登录模块一起使用,您需要执行以下步骤:
javax.security.auth.login.LoginContext
)在开发LoginModule时,请注意JAASRealm的内置CallbackHandler
仅识别NameCallback
和PasswordCallback
目前。javax.security.Principal
,以便Tomcat可以告诉您从登录模块返回的哪些Principal是用户以及哪些是角色(请参阅参考资料org.apache.catalina.realm.JAASRealm
)。无论如何,返回的第一个Principal 始终被视为用户Principal。JAVA_OPTS=$JAVA_OPTS -Djava.security.auth.login.config==$CATALINA_BASE/conf/jaas.config
领域元素属性
要按照上面的步骤6配置JAASRealm,您需要创建一个<Realm>
元素并将其嵌套在节点中的 $CATALINA_BASE/conf/server.xml
文件中<Engine>
。JAASRealm的属性在Realm 配置文档中定义。
例
以下是server.xml代码段的外观示例。
<Realm className="org.apache.catalina.realm.JAASRealm"appName="MyFooRealm"userClassNames="org.foobar.realm.FooUser"roleClassNames="org.foobar.realm.FooRole"/>
您的登录模块负责为user(javax.security.auth.Subject
)创建和保存表示Principal的User和Role对象。如果您的登录模块没有创建用户对象但也没有抛出登录异常,那么Tomcat CMA将会中断,您将被留在http:// localhost:8080 / myapp / j_security_check URI或其他位置未指定的位置。
JAAS方法的灵活性有两方面:
补充说明
authenticate()
方法Realm
。因此,您将立即反映您在安全机制中所做的任何更改(新用户,更改的密码或角色等)。Realm
实现一样,如果<Realm>
元素server.xml
包含digest
属性,则支持消化密码; JAASRealm CallbackHandler
将在将密码传回给密码之前将其消化LoginModule
CombinedRealm
介绍
CombinedRealm是Tomcat Realm
接口的一种实现, 它通过一个或多个子域对用户进行身份验证。
使用CombinedRealm使开发人员能够组合相同或不同类型的多个领域。这可以用于针对不同的源进行身份验证,在一个Realm失败的情况下提供回退,或者用于需要多个域的任何其他目的。
子领域由定义CombinedRealm的Realm
元素内的嵌套元素 Realm
定义。将按照Realm
列出的顺序对每个进行身份验证。针对任何Realm的身份验证将足以验证用户身份。
领域元素属性
要配置CombinedRealm,创建一个<Realm>
在你的元素,其嵌套$CATALINA_BASE/conf/server.xml
在您的文件<Engine>
或<Host>
。您还可以嵌套在文件中的<Context>
节点 内context.xml
。
例
下面是一个示例,说明您的server.xml代码段应该如何使用UserDatabase Realm和DataSource Realm。
<Realm className="org.apache.catalina.realm.CombinedRealm" ><Realm className="org.apache.catalina.realm.UserDatabaseRealm"resourceName="UserDatabase"/><Realm className="org.apache.catalina.realm.DataSourceRealm"dataSourceName="jdbc/authority"userTable="users" userNameCol="user_name" userCredCol="user_pass"userRoleTable="user_roles" roleNameCol="role_name"/>
</Realm>
LockOutRealm
介绍
LockOutRealm是Tomcat Realm
接口的一个实现, 它扩展CombinedRealm以提供锁定功能,以便在给定时间段内有太多失败的身份验证尝试时提供用户锁定机制。
为确保正确操作,此领域中存在合理的同步程度。
此Realm不需要修改底层Realms或相关的用户存储机制。它通过记录所有失败的登录来实现这一点,包括那些不存在的用户。为了通过考虑向无效用户发出请求来防止DOS(从而导致此缓存增长),身份验证失败的用户列表的大小是有限的。
子领域由定义LockOutRealm的Realm
元素内的嵌套元素 Realm
定义。将按照Realm
列出的顺序对每个进行身份验证。针对任何Realm的身份验证将足以验证用户身份。
领域元素属性
要配置LockOutRealm,创建一个<Realm>
在你的元素,其嵌套$CATALINA_BASE/conf/server.xml
在您的文件<Engine>
或<Host>
。您还可以嵌套在文件中的<Context>
节点 内context.xml
。LockOutRealm的属性在Realm 配置文档中定义。
例
下面是一个示例,说明您的server.xml代码段应该如何向用户数据库领域添加锁定功能。
<Realm className="org.apache.catalina.realm.LockOutRealm" ><Realm className="org.apache.catalina.realm.UserDatabaseRealm"resourceName="UserDatabase"/>
</Realm>
背景
Java SecurityManager允许Web浏览器在其自己的沙箱中运行applet,以防止不受信任的代码访问本地文件系统上的文件,连接到加载applet的主机以外的主机,等等。以同样的方式,SecurityManager保护您免受浏览器中运行的不受信任的applet的影响,在运行Tomcat时使用SecurityManager可以保护您的服务器免受木马servlet,JSP,JSP bean和标记库的影响。甚至是无意中的错误。
想象一下,如果有权在您的站点上发布JSP的人无意中在JSP中包含以下内容:
<% System.exit(1); %>
每次这个JSP由Tomcat执行时,Tomcat都会退出。使用Java SecurityManager只是系统管理员可以用来保护服务器安全可靠的另一道防线。
警告 - 已使用Tomcat代码库进行安全审核。大多数关键包都受到保护,并且已经实施了新的安全包保护机制。尽管如此,在允许不受信任的用户发布Web应用程序,JSP,servlet,bean或标记库之前,请确保您对SecurityManager配置感到满意。 但是,使用SecurityManager运行肯定比没有安全管理器运行更好。
权限
权限类用于定义Tomcat加载的类的权限。有许多Permission类是JDK的标准部分,您可以创建自己的Permission类,以便在您自己的Web应用程序中使用。这两种技术都在Tomcat中使用。
标准权限
这只是适用于Tomcat的标准系统SecurityManager权限类的简短摘要。有关 更多信息,请参见http://docs.oracle.com/javase/7/docs/technotes/guides/security/。
java.home
。exit()
和 exec()
。还控制包访问/定义。使用SecurityManager配置Tomcat
策略文件格式
Java SecurityManager实现的安全策略在$CATALINA_BASE/conf/catalina.policy
文件中配置。此文件完全替换java.policy
JDK系统目录中存在的文件。catalina.policy
可以手动编辑该文件,也可以使用 Java 1.2或更高版本附带的 policytool应用程序。
catalina.policy
文件中的条目使用标准 java.policy
文件格式,如下所示:
// Example policy file entrygrant [signedBy <signer>,] [codeBase <code source>] {permission <class> [<name> [, <action list>]];
};
授予权限时,signedBy和codeBase条目是可选的。注释行以“//”开头,并以当前行的结尾结束。的codeBase
是在URL的形式,和用于文件的URL可以使用${java.home}
和${catalina.home}
属性(其扩展了由为它们定义的目录路径JAVA_HOME
, CATALINA_HOME
和CATALINA_BASE
环境变量)。
默认策略文件
默认$CATALINA_BASE/conf/catalina.policy
文件如下所示:
// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.// ============================================================================
// catalina.policy - Security Policy Permissions for Tomcat
//
// This file contains a default set of security policies to be enforced (by the
// JVM) when Catalina is executed with the "-security" option. In addition
// to the permissions granted here, the following additional permissions are
// granted to each web application:
//
// * Read access to the web application's document root directory
// * Read, write and delete access to the web application's working directory
// ============================================================================// ========== SYSTEM CODE PERMISSIONS =========================================// These permissions apply to javac
grant codeBase "file:${java.home}/lib/-" {permission java.security.AllPermission;
};// These permissions apply to all shared system extensions
grant codeBase "file:${java.home}/jre/lib/ext/-" {permission java.security.AllPermission;
};// These permissions apply to javac when ${java.home] points at $JAVA_HOME/jre
grant codeBase "file:${java.home}/../lib/-" {permission java.security.AllPermission;
};// These permissions apply to all shared system extensions when
// ${java.home} points at $JAVA_HOME/jre
grant codeBase "file:${java.home}/lib/ext/-" {permission java.security.AllPermission;
};// ========== CATALINA CODE PERMISSIONS =======================================// These permissions apply to the daemon code
grant codeBase "file:${catalina.home}/bin/commons-daemon.jar" {permission java.security.AllPermission;
};// These permissions apply to the logging API
// Note: If tomcat-juli.jar is in ${catalina.base} and not in ${catalina.home},
// update this section accordingly.
// grant codeBase "file:${catalina.base}/bin/tomcat-juli.jar" {..}
grant codeBase "file:${catalina.home}/bin/tomcat-juli.jar" {permission java.io.FilePermission"${java.home}${file.separator}lib${file.separator}logging.properties", "read";permission java.io.FilePermission"${catalina.base}${file.separator}conf${file.separator}logging.properties", "read";permission java.io.FilePermission"${catalina.base}${file.separator}logs", "read, write";permission java.io.FilePermission"${catalina.base}${file.separator}logs${file.separator}*", "read, write, delete";permission java.lang.RuntimePermission "shutdownHooks";permission java.lang.RuntimePermission "getClassLoader";permission java.lang.RuntimePermission "setContextClassLoader";permission java.lang.management.ManagementPermission "monitor";permission java.util.logging.LoggingPermission "control";permission java.util.PropertyPermission "java.util.logging.config.class", "read";permission java.util.PropertyPermission "java.util.logging.config.file", "read";permission java.util.PropertyPermission "org.apache.juli.AsyncLoggerPollInterval", "read";permission java.util.PropertyPermission "org.apache.juli.AsyncMaxRecordCount", "read";permission java.util.PropertyPermission "org.apache.juli.AsyncOverflowDropType", "read";permission java.util.PropertyPermission "org.apache.juli.ClassLoaderLogManager.debug", "read";permission java.util.PropertyPermission "catalina.base", "read";// Note: To enable per context logging configuration, permit read access to// the appropriate file. Be sure that the logging configuration is// secure before enabling such access.// E.g. for the examples web application (uncomment and unwrap// the following to be on a single line):// permission java.io.FilePermission "${catalina.base}${file.separator}// webapps${file.separator}examples${file.separator}WEB-INF// ${file.separator}classes${file.separator}logging.properties", "read";
};// These permissions apply to the server startup code
grant codeBase "file:${catalina.home}/bin/bootstrap.jar" {permission java.security.AllPermission;
};// These permissions apply to the servlet API classes
// and those that are shared across all class loaders
// located in the "lib" directory
grant codeBase "file:${catalina.home}/lib/-" {permission java.security.AllPermission;
};// If using a per instance lib directory, i.e. ${catalina.base}/lib,
// then the following permission will need to be uncommented
// grant codeBase "file:${catalina.base}/lib/-" {
// permission java.security.AllPermission;
// };// ========== WEB APPLICATION PERMISSIONS =====================================// These permissions are granted by default to all web applications
// In addition, a web application will be given a read FilePermission
// for all files and directories in its document root.
grant {// Required for JNDI lookup of named JDBC DataSource's and// javamail named MimePart DataSource used to send mailpermission java.util.PropertyPermission "java.home", "read";permission java.util.PropertyPermission "java.naming.*", "read";permission java.util.PropertyPermission "javax.sql.*", "read";// OS Specific properties to allow read accesspermission java.util.PropertyPermission "os.name", "read";permission java.util.PropertyPermission "os.version", "read";permission java.util.PropertyPermission "os.arch", "read";permission java.util.PropertyPermission "file.separator", "read";permission java.util.PropertyPermission "path.separator", "read";permission java.util.PropertyPermission "line.separator", "read";// JVM properties to allow read accesspermission java.util.PropertyPermission "java.version", "read";permission java.util.PropertyPermission "java.vendor", "read";permission java.util.PropertyPermission "java.vendor.url", "read";permission java.util.PropertyPermission "java.class.version", "read";permission java.util.PropertyPermission "java.specification.version", "read";permission java.util.PropertyPermission "java.specification.vendor", "read";permission java.util.PropertyPermission "java.specification.name", "read";permission java.util.PropertyPermission "java.vm.specification.version", "read";permission java.util.PropertyPermission "java.vm.specification.vendor", "read";permission java.util.PropertyPermission "java.vm.specification.name", "read";permission java.util.PropertyPermission "java.vm.version", "read";permission java.util.PropertyPermission "java.vm.vendor", "read";permission java.util.PropertyPermission "java.vm.name", "read";// Required for OpenJMXpermission java.lang.RuntimePermission "getAttribute";// Allow read of JAXP compliant XML parser debugpermission java.util.PropertyPermission "jaxp.debug", "read";// All JSPs need to be able to read this packagepermission java.lang.RuntimePermission "accessClassInPackage.org.apache.tomcat";// Precompiled JSPs need access to these packages.permission java.lang.RuntimePermission "accessClassInPackage.org.apache.jasper.el";permission java.lang.RuntimePermission "accessClassInPackage.org.apache.jasper.runtime";permission java.lang.RuntimePermission"accessClassInPackage.org.apache.jasper.runtime.*";// Applications using WebSocket need to be able to access these packagespermission java.lang.RuntimePermission "accessClassInPackage.org.apache.tomcat.websocket";permission java.lang.RuntimePermission "accessClassInPackage.org.apache.tomcat.websocket.server";
};// The Manager application needs access to the following packages to support the
// session display functionality. It also requires the custom Tomcat
// DeployXmlPermission to enable the use of META-INF/context.xml
// These settings support the following configurations:
// - default CATALINA_HOME == CATALINA_BASE
// - CATALINA_HOME != CATALINA_BASE, per instance Manager in CATALINA_BASE
// - CATALINA_HOME != CATALINA_BASE, shared Manager in CATALINA_HOME
grant codeBase "file:${catalina.base}/webapps/manager/-" {permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina";permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.ha.session";permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.manager";permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.manager.util";permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.util";permission org.apache.catalina.security.DeployXmlPermission "manager";
};
grant codeBase "file:${catalina.home}/webapps/manager/-" {permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina";permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.ha.session";permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.manager";permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.manager.util";permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.util";permission org.apache.catalina.security.DeployXmlPermission "manager";
};// The Host Manager application needs the custom Tomcat DeployXmlPermission to
// enable the use of META-INF/context.xml
// These settings support the following configurations:
// - default CATALINA_HOME == CATALINA_BASE
// - CATALINA_HOME != CATALINA_BASE, per instance Host Manager in CATALINA_BASE
// - CATALINA_HOME != CATALINA_BASE, shared Host Manager in CATALINA_HOME
grant codeBase "file:${catalina.base}/webapps/host-manager/-" {permission org.apache.catalina.security.DeployXmlPermission "host-manager";
};
grant codeBase "file:${catalina.home}/webapps/host-manager/-" {permission org.apache.catalina.security.DeployXmlPermission "host-manager";
};// You can assign additional permissions to particular web applications by
// adding additional "grant" entries here, based on the code base for that
// application, /WEB-INF/classes/, or /WEB-INF/lib/ jar files.
//
// Different permissions can be granted to JSP pages, classes loaded from
// the /WEB-INF/classes/ directory, all jar files in the /WEB-INF/lib/
// directory, or even to individual jar files in the /WEB-INF/lib/ directory.
//
// For instance, assume that the standard "examples" application
// included a JDBC driver that needed to establish a network connection to the
// corresponding database and used the scrape taglib to get the weather from
// the NOAA web server. You might create a "grant" entries like this:
//
// The permissions granted to the context root directory apply to JSP pages.
// grant codeBase "file:${catalina.base}/webapps/examples/-" {
// permission java.net.SocketPermission "dbhost.mycompany.com:5432", "connect";
// permission java.net.SocketPermission "*.noaa.gov:80", "connect";
// };
//
// The permissions granted to the context WEB-INF/classes directory
// grant codeBase "file:${catalina.base}/webapps/examples/WEB-INF/classes/-" {
// };
//
// The permission granted to your JDBC driver
// grant codeBase "jar:file:${catalina.base}/webapps/examples/WEB-INF/lib/driver.jar!/-" {
// permission java.net.SocketPermission "dbhost.mycompany.com:5432", "connect";
// };
// The permission granted to the scrape taglib
// grant codeBase "jar:file:${catalina.base}/webapps/examples/WEB-INF/lib/scrape.jar!/-" {
// permission java.net.SocketPermission "*.noaa.gov:80", "connect";
// };// To grant permissions for web applications using packed WAR files, use the
// Tomcat specific WAR url scheme.
//
// The permissions granted to the entire web application
// grant codeBase "war:file:${catalina.base}/webapps/examples.war*/-" {
// };
//
// The permissions granted to a specific JAR
// grant codeBase "war:file:${catalina.base}/webapps/examples.war*/WEB-INF/lib/foo.jar" {
// };
使用SecurityManager启动Tomcat
配置catalina.policy
文件以用于SecurityManager后,可以使用“-security”选项使用SecurityManager启动Tomcat:
$CATALINA_HOME/bin/catalina.sh start -security (Unix)
%CATALINA_HOME%\bin\catalina start -security (Windows)
打包WAR文件的权限
使用打包的WAR文件时,必须使用Tomcat的自定义war URL协议为Web应用程序代码分配权限。
要为整个Web应用程序分配权限,策略文件中的条目将如下所示:
// Example policy file entry
grant codeBase "war:file:${catalina.base}/webapps/examples.war*/-" {...
};
要为Web应用程序中的单个JAR分配权限,策略文件中的条目将如下所示:
// Example policy file entry
grant codeBase "war:file:${catalina.base}/webapps/examples.war*/WEB-INF/lib/foo.jar" {...
};
在Tomcat中配置程序包保护
从Tomcat 5开始,现在可以配置哪个Tomcat内部包受到保护以防止包定义和访问。有关 更多信息,请参阅http://www.oracle.com/technetwork/java/seccodeguide-139067.html。
警告:请注意,删除默认程序包保护可能会打开安全漏洞
默认属性文件
默认$CATALINA_BASE/conf/catalina.properties
文件如下所示:
#
# List of comma-separated packages that start with or equal this string
# will cause a security exception to be thrown when
# passed to checkPackageAccess unless the
# corresponding RuntimePermission ("accessClassInPackage."+package) has
# been granted.
package.access=sun.,org.apache.catalina.,org.apache.coyote.,org.apache.tomcat.,
org.apache.jasper.
#
# List of comma-separated packages that start with or equal this string
# will cause a security exception to be thrown when
# passed to checkPackageDefinition unless the
# corresponding RuntimePermission ("defineClassInPackage."+package) has
# been granted.
#
# by default, no packages are restricted for definition, and none of
# the class loaders supplied with the JDK call checkPackageDefinition.
#
package.definition=sun.,java.,org.apache.catalina.,org.apache.coyote.,
org.apache.tomcat.,org.apache.jasper.
配置catalina.properties
文件以与SecurityManager一起使用后,请记住重新启动Tomcat。
故障排除
如果您的Web应用程序尝试执行缺少必需权限而禁止的操作,则会 在SecurityManager检测到违规时抛出一个 AccessControLException
或一个SecurityException
。调试缺少的权限可能具有挑战性,一个选项是打开执行期间所做的所有安全决策的调试输出。这是通过在启动Tomcat之前设置系统属性来完成的。最简单的方法是通过CATALINA_OPTS
环境变量。执行以下命令:
export CATALINA_OPTS=-Djava.security.debug=all (Unix)
set CATALINA_OPTS=-Djava.security.debug=all (Windows)
在启动Tomcat之前。
警告 - 这将产生许多兆字节 的输出!但是,它可以帮助您通过搜索单词“FAILED”并确定正在检查哪个权限来追踪问题。有关您可以在此处指定的更多选项,请参阅Java安全性文档。
介绍
Tomcat 以与 Java Enterprise Edition应用程序服务器提供的方式兼容的方式为在其下运行的每个Web应用程序提供JNDI InitialContext实现实例 。Java EE标准在文件中提供了一组标准元素来引用/定义资源。/WEB-INF/web.xml
有关为JNDI编程API以及Java Enterprise Edition(Java EE)服务器支持的功能的更多信息,请参阅以下规范,Tomcat为其提供的服务模拟这些功能:
web.xml配置
可以在Web应用程序的Web应用程序部署描述符(/WEB-INF/web.xml
)中使用以下元素来定义资源:
<env-entry>
- 环境条目,单值参数,可用于配置应用程序的运行方式。<resource-ref>
- 资源引用,通常是对象工厂的资源,例如JDBC DataSource
,JavaMail Session
或配置到Tomcat中的自定义对象工厂。<resource-env-ref>
- 资源环境引用,resource-ref
Servlet 2.4 中添加的新变体,可以更轻松地为不需要身份验证信息的资源进行配置。如果Tomcat能够识别用于创建资源的适当资源工厂,并且不需要进一步的配置信息,则Tomcat将使用该信息/WEB-INF/web.xml
来创建资源。
Tomcat为JNDI资源提供了许多无法在web.xml中指定的特定于Tomcat的选项。这些包括closeMethod
在Web应用程序停止时更快地清理JNDI资源,并 singleton
控制是否为每个JNDI查找创建新资源实例。要使用这些配置选项,必须在Web应用程序的<Context>
元素或 元素中 指定资源 。<GlobalNamingResources>
$CATALINA_BASE/conf/server.xml
context.xml配置
如果Tomcat无法识别相应的资源工厂和/或需要其他配置信息,则必须在Tomcat创建资源之前指定其他特定于Tomcat的配置。Tomcat特定资源配置输入<Context>
到可以$CATALINA_BASE/conf/server.xml
在每个Web应用程序上下文XML文件(META-INF/context.xml
)中指定的元素中,或者最好在每个Web应用程序上下文XML文件()中指定。
使用元素中的以下元素执行Tomcat特定资源配置<Context>
:
InitialContext
(相当于<env-entry>
在Web应用程序部署描述符中包含元素)。<resource-ref>
在Web应用程序部署描述符中包含 元素)。java:comp/UserTransaction
。任何数量的这些元素都可以嵌套在 <Context>
元素中,并且只与该特定的Web应用程序相关联。
如果在<Context>
元素中定义了资源 ,则不必定义该资源/WEB-INF/web.xml
。但是,建议保留该条目/WEB-INF/web.xml
以记录Web应用程序的资源要求。
如果为<env-entry>
Web应用程序部署描述符(/WEB-INF/web.xml
)中 包含的元素定义了相同的资源名称,并且在作为Web应用程序<Environment>
元素的一部分的 <Context>
元素中定义了相同的资源名称 ,则只有相应<Environment>
元素允许时, 部署描述符中的值才会优先。 (通过将override
属性设置为“true”)。
全局配置
Tomcat为整个服务器维护一个单独的全局资源命名空间。这些是在元素中配置 的 。您可以使用<ResourceLink>将这些资源公开给Web应用程序, 以将其包含在每个Web应用程序上下文中。 <GlobalNamingResources>
$CATALINA_BASE/conf/server.xml
如果使用<ResourceLink>定义了 资源,则不必定义该资源/WEB-INF/web.xml
。但是,建议保留该条目/WEB-INF/web.xml
以记录Web应用程序的资源要求。
使用资源
在InitialContext
被配置作为网络应用程序最初部署,并且提供给Web应用程序组件(用于只读访问)。所有配置的条目和资源都放在java:comp/env
JNDI命名空间的部分中,因此对资源的典型访问 - 在本例中为JDBC DataSource
- 看起来像这样:
// Obtain our environment naming context
Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");// Look up our data source
DataSource ds = (DataSource)envCtx.lookup("jdbc/EmployeeDB");// Allocate and use a connection from the pool
Connection conn = ds.getConnection();
... use this connection to access the database ...
conn.close();
Tomcat标准资源工厂
Tomcat包含一系列标准资源工厂,可以为您的Web应用程序提供服务,但为您提供配置灵活性(通过 <Context>
元素),而无需修改Web应用程序或部署描述符。下面的每个小节详细说明了标准资源工厂的配置和使用。
有关如何使用Tomcat创建,安装,配置和使用自己的自定义资源工厂类的信息,请参阅添加自定义资源工厂。
注 - 在标准资源工厂中,只有“JDBC数据源”和“用户事务”工厂被强制在其他平台上可用,然后只有在平台实现Java Enterprise Edition(Java EE)规范时才需要它们。所有其他标准资源工厂以及您自己编写的自定义资源工厂都特定于Tomcat,并且不能假定在其他容器上可用。
通用JavaBean资源
0.简介
此资源工厂可用于创建 符合标准JavaBeans命名约定的任何 Java类的对象(即,它具有零参数构造函数,并且具有符合setFoo()命名模式的属性设置器。资源工厂将仅创建lookup()
如果singleton
工厂的属性设置为,则每次为此条目创建适当的bean类的新实例 false
。
使用该设施所需的步骤如下所述。
1.创建JavaBean类
创建JavaBean类,每次查找资源工厂时都会实例化它。对于此示例,假设您创建了一个类com.mycompany.MyBean
,如下所示:
package com.mycompany;public class MyBean {private String foo = "Default Foo";public String getFoo() {return (this.foo);}public void setFoo(String foo) {this.foo = foo;}private int bar = 0;public int getBar() {return (this.bar);}public void setBar(int bar) {this.bar = bar;}}
2.声明您的资源要求
接下来,修改Web应用程序部署描述符(/WEB-INF/web.xml
)以声明JNDI名称,在该名称下将请求此Bean的新实例。最简单的方法是使用一个<resource-env-ref>
元素,如下所示:
<resource-env-ref><description>Object factory for MyBean instances.</description><resource-env-ref-name>bean/MyBeanFactory</resource-env-ref-name><resource-env-ref-type>com.mycompany.MyBean</resource-env-ref-type>
</resource-env-ref>
警告 - 请确保遵守DTD对Web应用程序部署描述符所要求的元素排序!有关详细信息,请参阅 Servlet规范。
3.编写应用程序对此资源的使用
此资源环境引用的典型用法可能如下所示:
Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");writer.println("foo = " + bean.getFoo() + ", bar = " +bean.getBar());
4.配置Tomcat的资源工厂
要配置Tomcat的资源工厂,请将此类元素添加<Context>
到此Web应用程序的 元素中。
<Context ...>...<Resource name="bean/MyBeanFactory" auth="Container"type="com.mycompany.MyBean"factory="org.apache.naming.factory.BeanFactory"bar="23"/>...
</Context>
请注意,资源名称(此处bean/MyBeanFactory
必须与Web应用程序部署描述符中指定的值匹配。我们还初始化bar
属性的值,这将导致setBar(23)
在返回新bean之前调用。因为我们没有初始化 foo
属性(虽然我们可以),bean将包含其构造函数设置的任何默认值。
某些bean具有不能从字符串值自动转换的类型的属性。使用Tomcat BeanFactory设置此类属性将失败并出现NamingException。如果这些bean提供了从字符串值设置属性的方法,则可以将Tomcat BeanFactory配置为使用这些方法。配置使用forceString
属性完成。
假设我们的bean看起来像这样:
package com.mycompany;import java.net.InetAddress;
import java.net.UnknownHostException;public class MyBean2 {private InetAddress local = null;public InetAddress getLocal() {return local;}public void setLocal(InetAddress ip) {local = ip;}public void setLocal(String localHost) {try {local = InetAddress.getByName(localHost);} catch (UnknownHostException ex) {}}private InetAddress remote = null;public InetAddress getRemote() {return remote;}public void setRemote(InetAddress ip) {remote = ip;}public void host(String remoteHost) {try {remote = InetAddress.getByName(remoteHost);} catch (UnknownHostException ex) {}}}
bean有两个属性,都属于类型InetAddress
。第一个属性local
有一个附加的setter,它接受一个字符串参数。默认情况下,Tomcat BeanFactory会尝试使用与属性类型具有相同参数类型的自动检测到的setter,然后抛出NamingException,因为它不准备将给定的字符串属性值转换为InetAddress
。我们可以告诉Tomcat BeanFactory使用其他类似的setter:
<Context ...>...<Resource name="bean/MyBeanFactory" auth="Container"type="com.mycompany.MyBean2"factory="org.apache.naming.factory.BeanFactory"forceString="local"local="localhost"/>...
</Context>
bean属性remote
也可以从字符串设置,但必须使用非标准方法名称host
。要设置local
和remote
使用以下配置:
<Context ...>...<Resource name="bean/MyBeanFactory" auth="Container"type="com.mycompany.MyBean2"factory="org.apache.naming.factory.BeanFactory"forceString="local,remote=host"local="localhost"remote="tomcat.apache.org"/>...
</Context>
可以forceString
通过串联逗号作为分隔符来组合多个属性描述 。每个属性描述都只包含属性名称,在这种情况下BeanFactory调用setter方法。或者它包括name=method
在哪种情况下,name
通过调用方法设置名为property的属性 method
。对于类型String
或原始类型的属性或其相关的原始包装类, forceString
不需要使用。将自动检测正确的setter并应用参数转换。
用户数据库资源
0.简介
UserDatabase资源通常配置为UserDatabase领域使用的全局资源。Tomcat包含一个UserDatabaseFactory,用于创建由XML文件支持的UserDatabase资源 - 通常tomcat-users.xml
设置全局UserDatabase资源所需的步骤如下所述。
1.创建/编辑XML文件
$CATALINA_BASE/conf/tomcat-users.xml
但是,XML文件通常位于 文件系统的任何位置,您可以自由地找到该文件。建议放置XML文件$CATALINA_BASE/conf
。典型的XML看起来像:
<?xml version="1.0" encoding="UTF-8"?>
<tomcat-users><role rolename="tomcat"/><role rolename="role1"/><user username="tomcat" password="tomcat" roles="tomcat"/><user username="both" password="tomcat" roles="tomcat,role1"/><user username="role1" password="tomcat" roles="role1"/>
</tomcat-users>
2.声明你的资源
接下来,修改$CATALINA_BASE/conf/server.xml
以基于XML文件创建UserDatabase资源。它应该看起来像这样:
<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"readonly="false" />
该pathname
属性可以是URL,绝对路径或相对路径。如果相对,则相对于$CATALINA_BASE
。
该readonly
属性是可选的,true
如果未提供,则默认为 。如果XML是可写的,那么它将在Tomcat启动时写入。警告:写入文件时,它将继承Tomcat运行的用户的默认文件权限。确保这些适合维护安装的安全性。
如果在Realm中引用,则默认情况下,UserDatabse将监视 pathname
更改并在观察到上次修改时间的更改时重新加载文件。可以通过将watchSource
属性设置为禁用此功能 false
。
3.配置领域
配置UserDatabase域以使用Realm配置文档中所述的此资源 。
JavaMail会话
0.简介
在许多Web应用程序中,发送电子邮件消息是系统功能的必要部分。在 Java邮件 API使这个过程相对简单,但需要很多配置细节,客户端应用程序必须知道的(包括SMTP主机被用于报文发送的名称)。
Tomcat包含一个标准资源工厂,它将javax.mail.Session
为您创建 会话实例,已配置为连接到SMTP服务器。通过这种方式,应用程序完全不受电子邮件服务器配置环境中的更改的影响 - 它只需要在需要时请求并接收预配置的会话。
下面概述了所需的步骤。
1.声明您的资源要求
您应该做的第一件事是修改Web应用程序部署描述符(/WEB-INF/web.xml
)以声明JNDI名称,您将在该名称下查找预配置的会话。按照惯例,所有这些名称都应该解析为mail
子上下文(相对于作为java:comp/env
所有提供的资源工厂的根的标准命名上下文。典型的web.xml
条目可能如下所示:
<resource-ref><description>Resource reference to a factory for javax.mail.Sessioninstances that may be used for sending electronic mailmessages, preconfigured to connect to the appropriateSMTP server.</description><res-ref-name>mail/Session</res-ref-name><res-type>javax.mail.Session</res-type><res-auth>Container</res-auth>
</resource-ref>
警告 - 请确保遵守DTD对Web应用程序部署描述符所要求的元素排序!有关详细信息,请参阅 Servlet规范。
2.编写应用程序对此资源的使用
此资源引用的典型用法可能如下所示:
Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
Session session = (Session) envCtx.lookup("mail/Session");Message message = new MimeMessage(session);
message.setFrom(new InternetAddress(request.getParameter("from")));
InternetAddress to[] = new InternetAddress[1];
to[0] = new InternetAddress(request.getParameter("to"));
message.setRecipients(Message.RecipientType.TO, to);
message.setSubject(request.getParameter("subject"));
message.setContent(request.getParameter("content"), "text/plain");
Transport.send(message);
请注意,应用程序使用在Web应用程序部署描述符中声明的相同资源引用名称。这与<Context>
在Web应用程序的元素中配置的资源工厂相匹配, 如下所述。
3.配置Tomcat的资源工厂
要配置Tomcat的资源工厂,请将此类元素添加<Context>
到此Web应用程序的 元素中。
<Context ...>...<Resource name="mail/Session" auth="Container"type="javax.mail.Session"mail.smtp.host="localhost"/>...
</Context>
请注意,资源名称(此处mail/Session
)必须与Web应用程序部署描述符中指定的值匹配。自定义mail.smtp.host
参数的值以指向为网络提供SMTP服务的服务器。
其他资源属性和值将转换为属性和值,并javax.mail.Session.getInstance(java.util.Properties)
作为java.util.Properties
集合的一部分传递给它们。除了JavaMail规范的附录A中定义的属性之外,各个提供程序还可以支持其他属性。
如果资源配置与password
属性以及一个mail.smtp.user
或mail.user
属性,那么Tomcat的资源工厂将配置并添加 javax.mail.Authenticator
到邮件会话。
4.安装JavaMail库
下载JavaMail API。
解压缩发行版并将mail.jar放入$ CATALINA_HOME / lib中,以便在初始化邮件会话资源期间Tomcat可以使用它。注意:将此jar放在$ CATALINA_HOME / lib和Web应用程序的lib文件夹中都会导致错误,因此请确保仅将其放在$ CATALINA_HOME / lib位置。
5.重启Tomcat
为了使Tomcat可以看到其他JAR,必须重新启动Tomcat实例。
示例应用
/examples
Tomcat附带的应用程序包含使用此资源工厂的示例。可以通过“JSP Examples”链接访问它。实际发送邮件消息的servlet的源代码是 /WEB-INF/classes/SendMailServlet.java
。
警告 - 默认配置假定端口25上有SMTP服务器列表localhost
。如果不是这种情况,请编辑<Context>
此Web应用程序的 元素,并将参数的参数值修改为mail.smtp.host
网络上SMTP服务器的主机名。
JDBC数据源
0.简介
许多Web应用程序需要通过JDBC驱动程序访问数据库,以支持该应用程序所需的功能。Java EE平台规范要求Java EE Application Server 为此目的提供DataSource实现(即JDBC连接的连接池)。Tomcat提供完全相同的支持,因此使用此服务在Tomcat上开发的基于数据库的应用程序将在任何Java EE服务器上保持不变。
有关JDBC的信息,请参阅以下内容:
javax.sql.DataSource
API)。此包现在称为“JDBC可选包”。注 - Tomcat中的默认数据源支持基于Commons 项目的DBCP 2连接池 。然而,也可以使用实现任何其他连接池,通过编写自己的自定义资源工厂,描述 如下。javax.sql.DataSource
1.安装JDBC驱动程序
使用JDBC数据源 JNDI资源工厂要求您为Tomcat内部类和Web应用程序提供适当的JDBC驱动程序。通过将驱动程序的JAR文件安装到$CATALINA_HOME/lib
目录中可以很容易地实现这一点 ,这使得驱动程序既可用于资源工厂,也可用于应用程序。
2.声明您的资源要求
接下来,修改Web应用程序部署描述符(/WEB-INF/web.xml
)以声明JNDI名称,在该名称下将查找预配置的数据源。按照惯例,所有这些名称都应该解析为jdbc
子上下文(相对于作为java:comp/env
所有提供的资源工厂的根的标准命名上下文。典型的web.xml
条目可能如下所示:
<resource-ref><description>Resource reference to a factory for java.sql.Connectioninstances that may be used for talking to a particulardatabase that is configured in the <Context>configuration for the web application.</description><res-ref-name>jdbc/EmployeeDB</res-ref-name><res-type>javax.sql.DataSource</res-type><res-auth>Container</res-auth>
</resource-ref>
警告 - 请确保遵守DTD对Web应用程序部署描述符所要求的元素排序!有关详细信息,请参阅 Servlet规范。
3.编写应用程序对此资源的使用
此资源引用的典型用法可能如下所示:
Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
DataSource ds = (DataSource)envCtx.lookup("jdbc/EmployeeDB");Connection conn = ds.getConnection();
... use this connection to access the database ...
conn.close();
请注意,应用程序使用在Web应用程序部署描述符中声明的相同资源引用名称。这与<Context>
在Web应用程序的元素中配置的资源工厂相匹配, 如下所述。
4.配置Tomcat的资源工厂
要配置Tomcat的资源工厂,请将类似这样的<Context>
元素添加到Web应用程序的 元素中。
<Context ...>...<Resource name="jdbc/EmployeeDB"auth="Container"type="javax.sql.DataSource"username="dbusername"password="dbpassword"driverClassName="org.hsql.jdbcDriver"url="jdbc:HypersonicSQL:database"maxTotal="8"maxIdle="4"/>...
</Context>
请注意,资源名称(此处jdbc/EmployeeDB
)必须与Web应用程序部署描述符中指定的值匹配。
此示例假定您使用的是HypersonicSQL数据库JDBC驱动程序。自定义driverClassName
和 driverName
参数以匹配实际数据库的JDBC驱动程序和连接URL。
Tomcat的标准数据源资源工厂(org.apache.tomcat.dbcp.dbcp2.BasicDataSourceFactory
)的配置属性如下:
driverName
也被识别。)一些其他属性处理连接验证:
可选的逐出器线程负责通过删除长时间空闲的任何连接来缩小池。推销员不尊重minIdle
。请注意,如果您只希望池根据配置的maxIdle
属性收缩,则无需激活evictor线程。
默认情况下禁用逐出器,可以使用以下属性进行配置:
另一个可选功能是删除废弃的连接。如果应用程序长时间未将其返回池中,则称该连接被放弃。池可以自动关闭此类连接并将其从池中删除。这是泄漏连接的应用程序的解决方法。
默认情况下禁用放弃功能,可以使用以下属性进行配置:
最后,有各种属性可以进一步微调池行为:
NONE
,READ_COMMITTED
, READ_UNCOMMITTED
,REPEATABLE_READ
,SERIALIZABLE
。默认值:无默认设置;
)分隔多个语句。默认值:无声明name=value
,多个属性由分号(;
)分隔。默认值:无属性有关更多详细信息,请参阅Commons DBCP 2文档。
添加自定义资源工厂
如果没有标准资源工厂满足您的需求,您可以编写自己的工厂并将其集成到Tomcat中,然后<Context>
在Web应用程序的元素中配置此工厂的使用 。在下面的示例中,我们将创建一个只知道如何com.mycompany.MyBean
从上面的Generic JavaBean Resources示例创建bean 的工厂。
1.编写资源工厂类
您必须编写一个实现JNDI服务提供程序 javax.naming.spi.ObjectFactory
接口的类。每次Web应用程序调用lookup()
绑定到此工厂的上下文条目时(假设已配置工厂 singleton="false"
),将getObjectInstance()
使用以下参数调用该 方法:
javax.naming.Reference
,它包含此工厂类的类名,以及<Context>
用于创建要返回的对象的配置属性(来自 Web应用程序)。nameCtx
,或者null
未指定名称的名称。name
指定参数的上下文 ,或者null
是否 name
相对于默认初始上下文。要创建一个知道如何生成MyBean
实例的资源工厂,您可以创建一个这样的类:
package com.mycompany;import java.util.Enumeration;
import java.util.Hashtable;
import javax.naming.Context;
import javax.naming.Name;
import javax.naming.NamingException;
import javax.naming.RefAddr;
import javax.naming.Reference;
import javax.naming.spi.ObjectFactory;public class MyBeanFactory implements ObjectFactory {public Object getObjectInstance(Object obj,Name name2, Context nameCtx, Hashtable environment)throws NamingException {// Acquire an instance of our specified bean classMyBean bean = new MyBean();// Customize the bean properties from our attributesReference ref = (Reference) obj;Enumeration addrs = ref.getAll();while (addrs.hasMoreElements()) {RefAddr addr = (RefAddr) addrs.nextElement();String name = addr.getType();String value = (String) addr.getContent();if (name.equals("foo")) {bean.setFoo(value);} else if (name.equals("bar")) {try {bean.setBar(Integer.parseInt(value));} catch (NumberFormatException e) {throw new NamingException("Invalid 'bar' value " + value);}}}// Return the customized instancereturn (bean);}}
在此示例中,我们无条件地创建类的新实例com.mycompany.MyBean
,并根据<ResourceParams>
配置此工厂的元素中包含的参数填充其属性(请参见下文)。您应该注意,factory
应该跳过任何名为的参数- 该参数用于指定工厂类本身的名称(在本例中为 com.mycompany.MyBeanFactory
),而不是正在配置的bean的属性。
有关更多信息ObjectFactory
,请参阅 JNDI服务提供程序接口(SPI)规范。
您需要针对包含目录中所有JAR文件的类路径编译此类$CATALINA_HOME/lib
。完成后,将工厂类(和相应的bean类)解压缩到其下 $CATALINA_HOME/lib
,或放在JAR文件中 $CATALINA_HOME/lib
。这样,Catalina内部资源和Web应用程序都可以看到所需的类文件。
2.声明您的资源要求
接下来,修改Web应用程序部署描述符(/WEB-INF/web.xml
)以声明JNDI名称,在该名称下将请求此Bean的新实例。最简单的方法是使用一个<resource-env-ref>
元素,如下所示:
<resource-env-ref><description>Object factory for MyBean instances.</description><resource-env-ref-name>bean/MyBeanFactory</resource-env-ref-name><resource-env-ref-type>com.mycompany.MyBean</resource-env-ref-type>
</resource-env-ref>
警告 - 请确保遵守DTD对Web应用程序部署描述符所要求的元素排序!有关详细信息,请参阅 Servlet规范。
3.编写应用程序对此资源的使用
此资源环境引用的典型用法可能如下所示:
Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");writer.println("foo = " + bean.getFoo() + ", bar = " +bean.getBar());
4.配置Tomcat的资源工厂
要配置Tomcat的资源工厂,请将此类元素添加<Context>
到此Web应用程序的 元素中。
<Context ...>...<Resource name="bean/MyBeanFactory" auth="Container"type="com.mycompany.MyBean"factory="com.mycompany.MyBeanFactory"singleton="false"bar="23"/>...
</Context>
请注意,资源名称(此处bean/MyBeanFactory
必须与Web应用程序部署描述符中指定的值匹配。我们还初始化bar
属性的值,这将导致setBar(23)
在返回新bean之前调用。因为我们没有初始化 foo
属性(虽然我们可以),bean将包含其构造函数设置的任何默认值。
您还将注意到,从应用程序开发人员的角度来看,资源环境引用的声明以及用于请求新实例的编程与用于Generic JavaBean Resources示例的方法相同 。这说明了使用JNDI资源封装功能的一个优点 - 您可以更改底层实现,而无需使用资源修改应用程序,只要您维护兼容的API即可。
转载来源:https://tomcat.apache.org/tomcat-9.0-doc/index.html
版权声明:本站所有资料均为网友推荐收集整理而来,仅供学习和研究交流使用。
工作时间:8:00-18:00
客服电话
电子邮件
admin@qq.com
扫码二维码
获取最新动态