管理員應用程式使用手冊
目錄
簡介
在許多生產環境中,具有能夠部署新的 Web 應用程序或取消部署現有應用程序的能力是非常有用的,而無需關閉並重新啟動整個容器。此外,您可以要求現有應用程序重新載入自身,即使您尚未在 Tomcat 伺服器配置文件中聲明它為可重新載入
。
為了支援這些功能,Tomcat 包含一個 Web 應用程序(默認安裝在上下文路徑/manager
),支援以下功能
- 從 WAR 文件的上傳內容部署新的 Web 應用程序。
- 從伺服器文件系統部署新的 Web 應用程序,指定上下文路徑。
- 列出當前部署的 Web 應用程序,以及這些 Web 應用程序當前活動的會話。
- 重新載入現有的 Web 應用程序,以反映
/WEB-INF/classes
或/WEB-INF/lib
內容的變更。 - 列出操作系統和 JVM 屬性值。
- 列出可用的全局 JNDI 資源,供準備嵌套在
<Context>
部署描述中的<ResourceLink>
元素的部署工具使用。 - 啟動已停止的應用程序(使其再次可用)。
- 停止現有應用程序(使其不可用),但不取消部署它。
- 取消部署已部署的 Web 應用程序並刪除其文件基目錄(除非它是從文件系統部署的)。
默認的 Tomcat 安裝包含為默認虛擬主機配置的 Manager 應用程序實例。如果創建其他虛擬主機,您可能希望向其中一個或多個主機添加 Manager 應用程序的實例。要將 Manager Web 應用程序Context
的實例添加到新主機,請在$CATALINA_BASE/conf/[enginename]/[hostname]
文件夾中安裝manager.xml
上下文配置文件。這是一個例子
<Context privileged="true" antiResourceLocking="false"
docBase="${catalina.home}/webapps/manager">
<CookieProcessor className="org.apache.tomcat.util.http.Rfc6265CookieProcessor"
sameSiteCookies="strict" />
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1" />
<Manager sessionAttributeValueClassNameFilter="java\.lang\.(?:Boolean|Integer|Long|Number|String)|org\.apache\.catalina\.filters\.CsrfPreventionFilter\$LruCache(?:\$1)?|java\.util\.(?:Linked)?HashMap"/>
</Context>
有三種方式可以使用Manager網絡應用程式。
- 作為一個帶有用戶界面的應用程式,您可以在瀏覽器中使用它。以下是一個示例 URL,您可以將其中的
localhost
替換為您的網站主機名稱:https://127.0.0.1:8080/manager/html
。 - 一個僅使用 HTTP 請求的最小版本,適用於系統管理員設置的腳本使用。命令作為請求 URI 的一部分給出,並且響應以簡單文本的形式給出,可以輕鬆解析和處理。有關更多信息,請參見 支持的 Manager 命令。
- 用於Ant(版本1.4或更高版本)構建工具的方便的任務定義集。有關更多信息,請參見使用 Ant 執行 Manager 命令。
配置管理員應用程式存取權限
下面的描述使用變量名$CATALINA_BASE來引用大多數相對路徑所解析的基本目錄。如果您尚未通過設置CATALINA_BASE目錄來配置Tomcat以進行多個實例,那麼$CATALINA_BASE將設置為$CATALINA_HOME的值,即您安裝Tomcat的目錄。
以默認設置Tomcat的方式出貨,允許互聯網上的任何人執行您的服務器上的Manager應用程式將非常不安全。因此,Manager應用程式的出貨要求任何試圖使用它的人都必須進行身份驗證,使用具有其中一個manager-xxx角色的用戶名和密碼(角色名稱取決於所需的功能)。此外,在默認用戶文件($CATALINA_BASE/conf/tomcat-users.xml
)中沒有用戶名被分配給這些角色。因此,對Manager應用程式的訪問在默認情況下完全被禁用。
您可以在Manager網絡應用程式的web.xml
文件中找到角色名稱。可用角色為
- manager-gui — 訪問HTML界面。
- manager-status — 僅訪問“服務器狀態”頁面。
- manager-script — 訪問此文檔中描述的面向工具的純文本界面以及“服務器狀態”頁面。
- manager-jmx — 訪問JMX代理界面以及“服務器狀態”頁面。
HTML界面受到CSRF(跨站請求偽造)攻擊的保護,但文本和JMX界面無法受到保護。這意味著被允許訪問文本和JMX界面的用戶在使用Web瀏覽器訪問Manager應用程式時必須小心。為了保持CSRF保護
- 如果您使用Web瀏覽器使用具有manager-script或manager-jmx角色的用戶訪問Manager應用程式(例如用於測試純文本或JMX界面),則必須在終止會話後關閉瀏覽器的所有窗口。如果您不關閉瀏覽器並訪問其他網站,您可能會成為CSRF攻擊的受害者。
- 建議永遠不要將manager-script或manager-jmx角色授予具有manager-gui角色的用戶。
注意 JMX 代理界面實際上是 Tomcat 的低階根級管理界面。如果知道要調用的命令,就可以做很多事情。啟用 manager-jmx 角色時應該要小心。
要啟用對管理員 Web 應用程序的訪問,您必須創建新的用戶名/密碼組合並將其中一個 manager-xxx 角色與之關聯,或者將 manager-xxx 角色添加到某個現有的用戶名/密碼組合中。由於本文大部分描述了使用文本界面,此示例將使用角色名稱 manager-script。用戶名/密碼的配置方式取決於您正在使用的 Realm 實現
- UserDatabaseRealm 加上 MemoryUserDatabase 或 MemoryRealm — UserDatabaseRealm 和 MemoryUserDatabase 配置在默認的
$CATALINA_BASE/conf/server.xml
中。 MemoryUserDatabase 和 MemoryRealm 默認讀取一個 XML 格式文件,該文件存儲在$CATALINA_BASE/conf/tomcat-users.xml
,可以使用任何文本編輯器進行編輯。該文件包含一個 XML<user>
,每個個體用戶都有一個,可能看起來像這樣這定義了用於登錄的用戶名和密碼,以及他們所關聯的角色名。您可以將 manager-script 角色添加到一個或多個現有用戶的逗號分隔的<user username="craigmcc" password="secret" roles="standard,manager-script" />
roles
屬性中,並/或者創建具有該分配角色的新用戶。 - DataSourceRealm — 您的用戶和角色信息存儲在通過 JDBC 訪問的數據庫中。按照您環境的標準程序,將 manager-script 角色添加到一個或多個現有用戶,並/或者創建一個或多個具有此角色的新用戶。
- JNDIRealm — 您的用戶和角色信息存儲在通過 LDAP 訪問的目錄服務器中。按照您環境的標準程序,將 manager-script 角色添加到一個或多個現有用戶,並/或者創建一個或多個具有此角色的新用戶。
當您第一次嘗試發出下一節中描述的管理員命令時,將被要求使用基本身份驗證進行登錄。您輸入的用戶名和密碼並不重要,只要它們識別出具有角色 manager-script 的有效用戶即可。
除了密碼限制外,可以通過添加 RemoteAddrValve
或 RemoteHostValve
來限制對管理員 Web 應用程序的訪問 遠程 IP 地址 或主機。有關詳細信息,請參閱 valves documentation。這是一個限制僅限本地主機的示例
<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應用程式知道如何處理的所有命令都在一個單一的請求URI中指定,如下所示
http://{host}:{port}/manager/text/{command}?{parameters}
其中 {host}
和 {port}
代表Tomcat運行的主機名和端口號, {command}
代表您要執行的Manager命令, {parameters}
代表特定於該命令的查詢參數。在下面的示例中,請根據您的安裝適當地自定義主機和端口。
這些命令通常通過HTTP GET請求執行。 /deploy
命令具有一個表單,該表單通過HTTP PUT請求執行。
常見參數
大多數命令接受以下一個或多個查詢參數
- path - 您正在處理的Web應用程式的上下文路徑(包括前導斜槓)。要選擇ROOT Web應用程式,請指定“/”。
注意:無法對Manager應用程式本身執行管理命令。
注意:如果未明確指定path參數,則將使用config參數的標準Context命名規則或(如果config參數不存在)war參數來派生路徑和版本。 - 版本 - 此 Web 應用程式的版本,由平行部署功能使用。如果您在需要路徑的任何地方使用平行部署,則必須除了指定路徑外還要指定版本,而且必須是路徑和版本的組合必須是唯一的,而不僅僅是路徑。
注意:如果未明確指定路徑,則將忽略版本參數。 - war - Web 應用程式存檔 (WAR) 檔案的 URL,或包含 Web 應用程式的目錄的路徑,或包含 Context 配置 ".xml" 檔案的路徑。您可以使用以下任何格式的 URL
- file:/absolute/path/to/a/directory - 包含 Web 應用程式未解壓縮版本的目錄的絕對路徑。此目錄將附加到您指定的上下文路徑,而不會進行任何更改。
- file:/absolute/path/to/a/webapp.war - Web 應用程式存檔 (WAR) 檔案的絕對路徑。這僅對於
/deploy
命令有效,且是該命令接受的唯一可接受格式。 - file:/absolute/path/to/a/context.xml - 包含 Web 應用程式 Context 配置 ".xml" 檔案的絕對路徑,該檔案包含 Context 配置元素。
- directory - 主機應用程式基目錄中 Web 應用程式上下文的目錄名稱。
- webapp.war - 主機應用程式基目錄中位於的 Web 應用程式 WAR 檔案的名稱。
每個命令將以 text/plain
格式(即純 ASCII 文字,無 HTML 標記)返回回應,使人類和程式都可以輕鬆閱讀。回應的第一行將以 OK
或 FAIL
開頭,指示請求的命令是否成功。在失敗的情況下,第一行的其餘部分將包含遇到的問題的描述。某些命令包含如下所述的附加信息行。
國際化備註 - 管理員應用程式在其資源包中查找其訊息字串,因此可能已為您的平台翻譯了這些字串。下面的示例顯示訊息的英文版本。
遠端部署新應用程式存檔(WAR)
https://127.0.0.1:8080/manager/text/deploy?path=/foo
上傳指定為此 HTTP PUT 請求中的請求數據的 Web 應用程式存檔 (WAR) 檔案,將其安裝到對應虛擬主機的 appBase
目錄中,並從指定的路徑派生要添加到 appBase
中的 WAR 檔案的名稱。稍後可以使用 /undeploy
命令卸載應用程式(並刪除相應的 WAR 檔案)。
此命令由HTTP PUT請求執行。
.WAR檔案可以包含特定於Tomcat的部署配置,方法是在/META-INF/context.xml
中包含一個Context配置XML文件。
URL參數包括
update
: 當設置為true時,將首先取消部署任何現有的更新。默認值設置為false。tag
: 指定一個標籤名,這允許將已部署的Web應用與標籤或標籤相關聯。如果Web應用被取消部署,則可以稍後使用標籤需要時重新部署。config
: 以file:/absolute/path/to/a/context.xml格式的URL指向一個Context配置“.xml”文件。這必須是一個Web應用上下文配置“.xml”文件的絕對路徑,其中包含上下文配置元素。
注意 - 這個命令是/undeploy
命令的邏輯相反。
如果安裝和啟動成功,您將收到如下響應
OK - Deployed application at context path /foo
否則,響應將以FAIL
開頭並包含一條錯誤消息。問題的可能原因包括
- 路徑/foo處已存在應用程序
當前運行的所有Web應用程序的上下文路徑必須是唯一的。因此,您必須取消部署使用此上下文路徑的現有Web應用程序,或者選擇新的上下文路徑。
update
參數可以作為URL的參數指定,其值為true
,以避免此錯誤。在這種情況下,將在執行部署之前對現有應用程序進行取消部署。 - 遇到異常
嘗試啟動新Web應用程序時發生異常。檢查Tomcat日誌以獲取詳細信息,但可能的解釋包括解析
/WEB-INF/web.xml
文件時遇到問題,或者在初始化應用程序事件侦听器和过滤器时遇到缺失的类。
從本地路徑部署新應用程式
部署並啟動一個新的Web應用程序,附加到指定的上下文path
(該路徑不能被任何其他Web應用程序使用)。此命令是/undeploy
命令的邏輯相反。
此命令由HTTP GET請求執行。部署命令可以以多種不同的方式使用。
部署先前部署的網路應用程式
https://127.0.0.1:8080/manager/text/deploy?path=/footoo&tag=footag
這可用於部署以前使用tag
屬性部署的Web應用程序。請注意,管理Web應用程序的工作目錄將包含以前部署的WAR文件;刪除它將使部署失敗。
按 URL 部署目錄或 WAR
部署位於Tomcat服務器上的Web應用程序目錄或“.war”文件。如果未指定path
,則路徑和版本將從目錄名稱或WAR文件名稱中派生。 war
參數指定了一個URL(包括file:
方案),用於目錄或Web應用程序存檔(WAR)文件。對WAR文件的URL引用的支持語法在java.net.JarURLConnection
類的Javadocs頁面上描述。僅使用引用整個WAR文件的URL。
在這個例子中,位於 Tomcat 伺服器上目錄 /path/to/foo
中的 Web 應用程式被部署為名為 /footoo
的 Web 應用程式內容。
https://127.0.0.1:8080/manager/text/deploy?path=/footoo&war=file:/path/to/foo
在這個例子中,Tomcat 伺服器上的 ".war" 檔案 /path/to/bar.war
被部署為名為 /bar
的 Web 應用程式內容。請注意,沒有 path
參數,因此上下文路徑預設為 Web 應用程式存檔檔案的名稱,不包含 ".war" 副檔名。
https://127.0.0.1:8080/manager/text/deploy?war=file:/path/to/bar.war
從主機 appBase 部署目錄或 WAR
部署位於您的 Host appBase 目錄中的 Web 應用程式目錄或 ".war" 檔案。路徑和可選版本是從目錄或 war 檔案名稱中衍生出來的。
在這個例子中,位於 Tomcat 伺服器的 Host appBase 目錄中名為 foo
的子目錄中的 Web 應用程式被部署為名為 /foo
的 Web 應用程式內容。請注意,使用的上下文路徑是 Web 應用程式目錄的名稱。
https://127.0.0.1:8080/manager/text/deploy?war=foo
在這個例子中,位於 Tomcat 伺服器的 Host appBase 目錄中的 ".war" 檔案 bar.war
被部署為名為 /bar
的 Web 應用程式內容。
https://127.0.0.1:8080/manager/text/deploy?war=bar.war
使用上下文配置 ".xml" 檔案部署
如果 Host 的 deployXML 標誌設置為 true,您可以使用上下文配置 ".xml" 檔案以及可選的 ".war" 檔案或 Web 應用程式目錄來部署 Web 應用程式。在使用上下文 ".xml" 配置檔案部署 Web 應用程式時,不使用上下文 path
。
上下文配置 ".xml" 檔案可以包含有效的 XML,用於 Web 應用程式上下文,就像它是配置在您的 Tomcat server.xml
配置檔案中一樣。這是一個例子
<Context path="/foobar" docBase="/path/to/application/foobar">
</Context>
當可選的 war
參數設置為 Web 應用程式 ".war" 檔案或目錄的 URL 時,它將覆蓋上下文配置 ".xml" 檔案中配置的任何 docBase。
這是使用上下文配置 ".xml" 檔案部署應用程式的例子。
https://127.0.0.1:8080/manager/text/deploy?config=file:/path/context.xml
這是使用上下文配置 ".xml" 檔案和位於伺服器上的 Web 應用程式 ".war" 檔案來部署應用程式的例子。
https://127.0.0.1:8080/manager/text/deploy
?config=file:/path/context.xml&war=file:/path/bar.war
部署注意事項
如果 Host 配置為 unpackWARs=true,並且您部署一個 war 檔案,該 war 將被解壓縮到 Host appBase 目錄中的一個目錄中。
如果應用程式 war 或目錄安裝在您的 Host appBase 目錄中,並且 Host 配置為 autoDeploy=true,或者上下文路徑必須與目錄名稱或不包含 ".war" 副檔名的 war 檔案名稱匹配。
當不信任的使用者能夠管理網路應用程式時,可以將 Host 的 deployXML 旗標設為 false 以提高安全性。這可以防止不受信任的使用者使用配置 XML 檔案部署網路應用程式,同時也防止他們部署位於其 Host appBase 之外的應用程式目錄或 ".war" 檔案。
部署回應
如果安裝和啟動成功,您將收到如下響應
OK - Deployed application at context path /foo
否則,響應將以FAIL
開頭並包含一條錯誤消息。問題的可能原因包括
- 路徑/foo處已存在應用程序
當前運行的所有Web應用程序的上下文路徑必須是唯一的。因此,您必須取消部署使用此上下文路徑的現有Web應用程序,或者選擇新的上下文路徑。
update
參數可以作為URL的參數指定,其值為true
,以避免此錯誤。在這種情況下,將在執行部署之前對現有應用程序進行取消部署。 - 文件基底不存在或不是可讀取的目錄
由
war
參數指定的 URL 必須識別此伺服器上包含網路應用程式「解開」版本的目錄,或是包含此應用程式的網路應用程式封裝檔案(WAR)的絕對 URL。請更正由war
參數指定的值。 - 遇到異常
嘗試啟動新Web應用程序時發生異常。檢查Tomcat日誌以獲取詳細信息,但可能的解釋包括解析
/WEB-INF/web.xml
文件時遇到問題,或者在初始化應用程序事件侦听器和过滤器时遇到缺失的类。 - 指定了無效的應用程式 URL
您指定的目錄或網路應用程式的 URL 不是有效的。此類 URL 必須以
file:
開頭,並且 WAR 檔案的 URL 必須以 ".war" 結尾。 - 指定了無效的內容路徑
內容路徑必須以斜線字符開頭。要參考 ROOT 網路應用程式,請使用 "/"。
- 內容路徑必須符合目錄或 WAR 檔案名稱
如果應用程式 WAR 或目錄安裝在您的 Host appBase 目錄中,並且 Host 配置了 autoDeploy=true,則內容路徑必須與目錄名稱或沒有 ".war" 擴展名的 WAR 檔案名稱相符。
- 只能安裝 Host 網路應用程式目錄中的網路應用程式
如果 Host 的 deployXML 旗標設為 false,當嘗試在 Host appBase 目錄之外部署網路應用程式目錄或 ".war" 檔案時,將發生此錯誤。
列出目前已部署的應用程式
https://127.0.0.1:8080/manager/text/list
列出所有當前部署的網路應用程式的內容路徑、當前狀態(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
重新載入現有的應用程式
https://127.0.0.1:8080/manager/text/reload?path=/examples
發出現有應用程式關閉並重新載入的訊號。當網路應用程式內容不可重新載入,且您已在 /WEB-INF/classes
目錄中更新了類別或屬性檔案,或者您已在 /WEB-INF/lib
目錄中添加或更新了 JAR 檔案時,這可能會很有用。
如果此命令成功,您將看到像這樣的回應
OK - Reloaded application at context path /examples
否則,響應將以FAIL
開頭並包含一條錯誤消息。問題的可能原因包括
- 遇到異常
重新啟動網路應用程式時遇到異常。請檢查 Tomcat 日誌以獲取詳細資訊。
- 指定了無效的內容路徑
內容路徑必須以斜線字符開頭。要參考 ROOT 網路應用程式,請使用 "/"。
- 路徑 /foo 不存在任何內容
您指定的內容路徑上沒有部署任何應用程式。
- 未指定內容路徑
參數
path
為必填。 - 在路徑為/foo的WAR部署中不支援重新載入。
目前,當網路應用程式直接從WAR文件部署時,不支援應用程式重新載入(以讀取類別或
web.xml
檔案的變更)。僅當網路應用程式從未打包的目錄部署時才有效。如果您使用WAR文件,您應該先undeploy
,然後再deploy
或使用update
參數再次部署應用程式以讀取您的變更。
列出作業系統和 JVM 屬性
https://127.0.0.1:8080/manager/text/serverinfo
顯示有關Tomcat版本、作業系統和JVM屬性的資訊。
如果發生錯誤,響應將以FAIL
開頭,並包含錯誤訊息。問題可能的原因包括
- 遇到異常
在列舉系統屬性時遇到例外情況。檢查Tomcat日誌以獲取詳細資訊。
列出可用的全域 JNDI 資源
https://127.0.0.1:8080/manager/text/resources[?type=xxxxx]
列出可供上下文配置文件中的資源鏈結使用的全域JNDI資源。如果指定了type
請求參數,則其值必須是您感興趣的資源類型的完全合格的Java類別名稱(例如,您將指定javax.sql.DataSource
以獲取所有可用的JDBC資料來源的名稱)。如果不指定type
請求參數,將返回所有類型的資源。
根據是否指定了type
請求參數,正常響應的第一行將是
OK - Listed global resources of all types
或
OK - Listed global resources of type xxxxx
然後是每個資源的一行。每行由冒號字符(“:”)分隔的字段組成,如下所示
- 全域資源名稱 - 此全域JNDI資源的名稱,將在
<ResourceLink>
元素的global
屬性中使用。 - 全域資源類型 - 此全域JNDI資源的完全合格的Java類別名稱。
如果發生錯誤,響應將以FAIL
開頭,並包含錯誤訊息。問題可能的原因包括
- 遇到異常
在列舉全域JNDI資源時遇到例外情況。檢查Tomcat日誌以獲取詳細資訊。
- 沒有可用的全域JNDI資源。
您正在運行的Tomcat伺服器已配置為不使用全域JNDI資源。
工作階段統計
https://127.0.0.1:8080/manager/text/sessions?path=/examples
顯示網路應用程式的默認會話逾時,以及落入其實際逾時時間範圍內的當前活動會話的數量。例如,重新啟動Tomcat,然後執行/examples
網路應用程式中的其中一個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
過期工作階段
https://127.0.0.1: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
參數。
啟動現有的應用程式
https://127.0.0.1:8080/manager/text/start?path=/examples
向停止的應用程式發出信號以重新啟動,並使其再次可用。停止和啟動是有用的,例如,如果您的應用程式所需的資料庫暫時不可用。通常最好停止依賴於此資料庫的 Web 應用程式,而不是讓使用者持續遇到資料庫例外。
如果此命令成功,您將看到像這樣的回應
OK - Started application at context path /examples
否則,響應將以FAIL
開頭並包含一條錯誤消息。問題的可能原因包括
- 遇到異常
啟動 Web 應用程式時遇到例外情況。檢查 Tomcat 日誌以獲取詳細資訊。
- 指定了無效的內容路徑
內容路徑必須以斜線字符開頭。要參考 ROOT 網路應用程式,請使用 "/"。
- 路徑 /foo 不存在任何內容
您指定的內容路徑上沒有部署任何應用程式。
- 未指定內容路徑
參數
path
為必填。
停止現有的應用程式
https://127.0.0.1:8080/manager/text/stop?path=/examples
向現有的應用程式發出信號,使其暫時不可用,但保留已部署。當應用程式停止時,任何進入的請求將看到 HTTP 錯誤 404,並且此應用程式將在應用程式列表命令中顯示為「已停止」。
如果此命令成功,您將看到像這樣的回應
OK - Stopped application at context path /examples
否則,響應將以FAIL
開頭並包含一條錯誤消息。問題的可能原因包括
- 遇到異常
停止 Web 應用程式時遇到例外情況。檢查 Tomcat 日誌以獲取詳細資訊。
- 指定了無效的內容路徑
內容路徑必須以斜線字符開頭。要參考 ROOT 網路應用程式,請使用 "/"。
- 路徑 /foo 不存在任何內容
您指定的內容路徑上沒有部署任何應用程式。
- 未指定內容路徑需要
path
參數。
解除部署現有的應用程式
https://127.0.0.1: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 網路應用程式,請使用 "/"。
- 不存在名為 /foo 的內容。
沒有以您指定的名稱部署的應用程式。
- 未指定內容路徑需要
path
參數。
尋找記憶體洩漏
https://127.0.0.1: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 密碼信息
https://127.0.0.1:8080/manager/text/sslConnectorCiphers
SSL 連接器/加密方式診斷列出了每個連接器當前配置的 SSL/TLS 加密方式。
響應將類似於這樣
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_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
...
連接器 SSL/TLS 憑證鏈信息
https://127.0.0.1:8080/manager/text/sslConnectorCerts
SSL 連接器/證書診斷列出了當前為每個虛擬主機配置的證書鏈。
響應將類似於這樣
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: V3
Subject: CN=localhost, OU=Apache Tomcat PMC, O=The Apache Software Foundation, L=Wakefield, ST=MA, C=US
Signature Algorithm: SHA256withRSA, OID = 1.2.840.113549.1.1.11
...
連接器 SSL/TLS 受信任的憑證信息
https://127.0.0.1:8080/manager/text/sslConnectorTrustedCerts
SSL 連接器/證書診斷列出了當前為每個虛擬主機配置的受信任證書。
響應將類似於這樣
OK - Connector / Trusted Certificate information
Connector[HTTP/1.1-8080]
SSL is not enabled for this connector
Connector[HTTP/1.1-8443]-_default_
[
[
Version: V3
Subject: CN=Apache Tomcat Test CA, OU=Apache Tomcat PMC, O=The Apache Software Foundation, L=Wakefield, ST=MA, C=US
...
重新加載 TLS 配置
https://127.0.0.1:8080/manager/text/sslReload?tlsHostName=name
重新加載 TLS 配置文件(證書和金鑰文件,這不會觸發對 server.xml 的重新解析)。要重新加載所有主機的文件,不要指定tlsHostName
參數。
OK - Reloaded TLS configuration for [_default_]
線程轉儲
https://127.0.0.1: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 ms
java.lang.Thread.State: RUNNABLE
locks java.util.concurrent.ThreadPoolExecutor$Worker@1738ad4
at 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 jakarta.servlet.http.HttpServlet.service(HttpServlet.java:618)
at jakarta.servlet.http.HttpServlet.service(HttpServlet.java:725)
...
VM 資訊
https://127.0.0.1:8080/manager/text/vminfo
撰寫有關 Java 虛擬機的一些診斷信息。
響應將類似於這樣
OK - VM info
2014-12-08 07:27:32.578
Runtime information:
vmName: Java HotSpot(TM) Client VM
vmVersion: 25.25-b02
vmVendor: Oracle Corporation
specName: Java Virtual Machine Specification
specVersion: 1.8
specVendor: Oracle Corporation
managementSpecVersion: 1.2
name: ...
startTime: 1418012458849
uptime: 393855
isBootClassPathSupported: true
OS information:
...
保存配置
https://127.0.0.1:8080/manager/text/save
如果沒有指定任何參數,此命令將當前的伺服器配置保存到 server.xml。如有需要,現有文件將被重命名為備份。
如果指定了path
參數且與已部署 Web 應用程式的路徑匹配,則該 Web 應用程式的配置將保存到當前主機的xmlBase
中的相應命名的 context.xml 文件中。
要使用該命令,必須存在 StoreConfig MBean。通常使用 StoreConfigLifecycleListener 進行配置。
如果命令執行失敗,響應將以FAIL
開頭,並包含錯誤消息。
伺服器狀態
從以下鏈接中,您可以查看有關伺服器的狀態信息。任何一個 manager-xxx 角色都允許訪問此頁面。
https://127.0.0.1:8080/manager/status
https://127.0.0.1:8080/manager/status/all
以 HTML 格式顯示伺服器狀態信息。
https://127.0.0.1:8080/manager/status?XML=true
https://127.0.0.1:8080/manager/status/all?XML=true
以 XML 格式顯示伺服器狀態信息。
https://127.0.0.1:8080/manager/status?JSON=true
https://127.0.0.1:8080/manager/status/all?JSON=true
以 JSON 格式顯示伺服器狀態信息。
首先是伺服器和 JVM 版本號、JVM 提供者、OS 名稱和編號,然後是架構類型。
其次,提供了有关JVM内存使用情况的信息。
然后,有关Tomcat AJP和HTTP连接器的信息。这两者的相同信息都可用。
线程信息:最大线程数、最小和最大空闲线程数、当前线程计数和当前繁忙线程数。
请求信息:最大处理时间和处理时间、请求和错误计数、收到和发送的字节数。
显示阶段、时间、发送字节数、接收字节数、客户端、虚拟主机和请求的表格。表格中列出了所有现有的线程。以下是可能的线程阶段列表:
“解析和准备请求”:正在解析请求标头,或正在进行读取请求正文的必要准备(如果已指定传输编码)。
“服务”:线程正在处理请求并生成响应。此阶段跟随“解析和准备请求”阶段,并在“结束”阶段之前。这个阶段始终至少有一个线程(服务器状态页面)。
“结束”:请求处理结束。仍在输出缓冲区中的响应的任何剩余部分都将发送到客户端。该阶段后跟“保持活动”(如果保持连接活动是适当的)或“就绪”(如果“保持活动”不适用)。
“保持活动”:线程保持连接打开以供客户端发送另一个请求。如果收到另一个请求,则下一个阶段将是“解析和准备请求”。如果在保持活动超时之前未收到请求,则连接将关闭,下一个阶段将是“就绪”。
“就绪”:线程处于休息状态,准备好被使用。
如果您使用/status/all
命令,将提供有关每个部署的Web应用程序的附加信息。
使用 JMX 代理 Servlet
什麼是 JMX 代理 Servlet
JMX 查詢命令
這採取以下形式
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 獲取命令
JMXProxyServlet 還支持一個“get”命令,您可以使用它來獲取特定 MBean 屬性的值。 get
命令的一般形式為
http://webserver/manager/jmxproxy/?get=BEANNAME&att=MYATTRIBUTE&key=MYKEY
您必須提供以下參數
get
:完整的 bean 名稱att
:要提取的屬性key
:(可選)複合數據 MBean 屬性的鍵
如果一切順利,那麼它將顯示 OK,否則將顯示錯誤消息。例如,假設我們希望獲取當前堆內存數據
http://webserver/manager/jmxproxy/?get=java.lang:type=Memory&att=HeapMemoryUsage
或者,如果您只想要“used”鍵
http://webserver/manager/jmxproxy/
?get=java.lang:type=Memory&att=HeapMemoryUsage&key=used
JMX 設置命令
現在您可以查詢 MBean,是時候來操縱 Tomcat 的內部了!set 命令的一般形式是
http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE
因此,您需要提供 3 個請求參數
set
:完整的 bean 名稱att
:您希望更改的屬性val
:新值
如果一切順利,那麼它將顯示 OK,否則將顯示錯誤消息。例如,假設我們希望即時將 ErrorReportValve
的調試值調高到 10。
https://127.0.0.1:8080/manager/jmxproxy/
?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost
&att=debug&val=10
我的結果是(可能會有所不同)
Result: ok
如果我傳入錯誤值,我看到的是這樣。這是我使用的 URL,我嘗試將調試值設置為 'cow'
https://127.0.0.1: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
指令可以在 MBeans 上呼叫方法。指令的一般形式如下:
http://webserver/manager/jmxproxy/
?invoke=BEANNAME&op=METHODNAME&ps=COMMASEPARATEDPARAMETERS
例如,要呼叫findConnectors()
方法的Service,請使用以下方式:
https://127.0.0.1:8080/manager/jmxproxy/
?invoke=Catalina%3Atype%3DService&op=findConnectors&ps=
使用 Ant 執行管理器命令
除了透過HTTP請求執行管理者指令的能力外,Tomcat還包含了一組方便的任務定義,用於Ant(1.4版或更新版本)構建工具。為了使用這些指令,您必須執行以下設定操作:
- 從https://ant.dev.org.tw下載Ant的二進制發行版。您必須使用1.4版或更新版本。
- 將Ant發行版安裝在方便的目錄中(在接下來的指示中稱為ANT_HOME)。
- 將
$ANT_HOME/bin
目錄添加到您的PATH
環境變量中。 - 在Tomcat用戶數據庫中配置至少一個包含
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="https://127.0.0.1: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, and
generated 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
文件的源代碼中包含真實的管理員密碼是一個安全風險。為了避免這種情況,請省略密碼屬性,並從命令行指定它。
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
,即使接受,因為它們在此上下文中沒有意義。有關 <redirector>
元素屬性的詳細信息,請參閱Ant 手冊。
以下是一個示例建構文件摘錄,顯示了如何使用此輸出重定向支持
<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 執行中多次調用任務,即使不打算如此。當您從該任務捕獲輸出時,應該小心,因為這可能導致一些意外情況
- 當在屬性中捕獲時,您將只會找到第一次呼叫的輸出,因為 Ant 屬性是不可變的,一旦設置就無法更改。
- 當在文件中捕獲時,每次運行都會覆蓋它,您只會在其中找到最後一次呼叫的輸出,除非您使用了
append="true"
屬性,在這種情況下,您將看到每個任務呼叫的輸出附加到文件中。