管理員應用程式使用手冊

目錄

簡介

在許多生產環境中,具有能夠部署新的 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-scriptmanager-jmx角色的用戶訪問Manager應用程式(例如用於測試純文本或JMX界面),則必須在終止會話後關閉瀏覽器的所有窗口。如果您不關閉瀏覽器並訪問其他網站,您可能會成為CSRF攻擊的受害者。
  • 建議永遠不要將manager-scriptmanager-jmx角色授予具有manager-gui角色的用戶。

注意 JMX 代理界面實際上是 Tomcat 的低階根級管理界面。如果知道要調用的命令,就可以做很多事情。啟用 manager-jmx 角色時應該要小心。

要啟用對管理員 Web 應用程序的訪問,您必須創建新的用戶名/密碼組合並將其中一個 manager-xxx 角色與之關聯,或者將 manager-xxx 角色添加到某個現有的用戶名/密碼組合中。由於本文大部分描述了使用文本界面,此示例將使用角色名稱 manager-script。用戶名/密碼的配置方式取決於您正在使用的 Realm 實現

  • UserDatabaseRealm 加上 MemoryUserDatabaseMemoryRealmUserDatabaseRealmMemoryUserDatabase 配置在默認的 $CATALINA_BASE/conf/server.xml 中。 MemoryUserDatabaseMemoryRealm 默認讀取一個 XML 格式文件,該文件存儲在 $CATALINA_BASE/conf/tomcat-users.xml,可以使用任何文本編輯器進行編輯。該文件包含一個 XML <user>,每個個體用戶都有一個,可能看起來像這樣
    <user username="craigmcc" password="secret" roles="standard,manager-script" />
    這定義了用於登錄的用戶名和密碼,以及他們所關聯的角色名。您可以將 manager-script 角色添加到一個或多個現有用戶的逗號分隔的 roles 屬性中,並/或者創建具有該分配角色的新用戶。
  • DataSourceRealm — 您的用戶和角色信息存儲在通過 JDBC 訪問的數據庫中。按照您環境的標準程序,將 manager-script 角色添加到一個或多個現有用戶,並/或者創建一個或多個具有此角色的新用戶。
  • JNDIRealm — 您的用戶和角色信息存儲在通過 LDAP 訪問的目錄服務器中。按照您環境的標準程序,將 manager-script 角色添加到一個或多個現有用戶,並/或者創建一個或多個具有此角色的新用戶。

當您第一次嘗試發出下一節中描述的管理員命令時,將被要求使用基本身份驗證進行登錄。您輸入的用戶名和密碼並不重要,只要它們識別出具有角色 manager-script 的有效用戶即可。

除了密碼限制外,可以通過添加 RemoteAddrValveRemoteHostValve 來限制對管理員 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 標記)返回回應,使人類和程式都可以輕鬆閱讀。回應的第一行將以 OKFAIL 開頭,指示請求的命令是否成功。在失敗的情況下,第一行的其餘部分將包含遇到的問題的描述。某些命令包含如下所述的附加信息行。

國際化備註 - 管理員應用程式在其資源包中查找其訊息字串,因此可能已為您的平台翻譯了這些字串。下面的示例顯示訊息的英文版本。

遠端部署新應用程式存檔(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

列出所有當前部署的網路應用程式的內容路徑、當前狀態(runningstopped)以及活動工作階段的數量。啟動 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代理Servlet是一个轻量级代理,用于获取和设置Tomcat内部。 (或通过MBean公开的任何类)它的使用并不十分用户友好,但UI对于集成命令行脚本以监视和更改Tomcat的内部非常有帮助。您可以使用代理执行两件事:获取信息和设置信息。要真正理解JMX代理Servlet,您应该对JMX有一个大致的理解。如果您不知道JMX是什么,那么请准备好感到困惑。

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

您必須提供以下參數

  1. get:完整的 bean 名稱
  2. att:要提取的屬性
  3. 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 個請求參數

  1. set:完整的 bean 名稱
  2. att:您希望更改的屬性
  3. 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 的日誌中看到錯誤輸出時,且您正在將輸出重定向到文件/屬性時使用此屬性。錯誤輸出將不包含在輸出文件/屬性中。如果使用 errorerrorProperty 屬性重定向錯誤,則此屬性將不起作用。
追加 輸出和錯誤文件是否應追加或覆蓋。默認為 false
createemptyfiles 是否在文件為空時創建輸出和錯誤文件。默認為 true
outputproperty 命令的輸出應存儲在其中的屬性的名稱。除非錯誤流被重定向到單獨的文件或流,否則此屬性將包括錯誤輸出。
errorproperty 命令的標準錯誤應存儲在其中的屬性的名稱。

還可以指定幾個其他屬性

屬性 描述 必填
alwaysLog 當您希望在捕獲的輸出中看到的時候,請使用此屬性也出現在 Ant 的日誌中。除非您正在捕獲任務輸出,否則不得使用。默認為 false此屬性將在 Ant 1.6.3 中由 <redirector> 直接支持
failonerror 當您希望避免任何管理器命令處理錯誤終止 Ant 執行時使用此屬性。默認為 true。如果您想捕獲錯誤輸出,則必須將其設置為 false,否則在捕獲到任何內容之前執行將被終止。
此屬性僅對管理器命令執行起作用,任何錯誤或缺少的命令屬性仍將導致 Ant 執行終止。

它們還支持嵌入式 <redirector> 元素,您可以在其中指定其完整的屬性集,但不使用 inputinputstringinputencoding,即使接受,因為它們在此上下文中沒有意義。有關 <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" 屬性,在這種情況下,您將看到每個任務呼叫的輸出附加到文件中。