Apache Tomcat Connectors - 參考指南

JkWorkersFile 指定 mod_jk 將找到工作人員定義的位置。請參閱 工作人員文件 以取得詳細說明。

JkWorkersFile     /etc/httpd/conf/workers.properties

JkLogFile 指定 mod_jk 放置其記錄檔的位置。

JkLogFile     /var/log/httpd/mod_jk.log

自 Apache 2.x 的 JK 1.2.3 和 Apache 1.3 的 JK 1.2.16 以來，這也可以用於管道記錄

JkLogFile     "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400"

JkLogLevel 設定記錄層級介於

• 資訊 記錄將包含標準 mod_jk 活動（預設）。
• 警告 記錄將包含非致命錯誤報告。
• 錯誤 記錄還將包含錯誤報告。
• 偵錯 記錄將包含 mod_jk 活動的所有資訊
• 追蹤 記錄將包含 mod_jk 活動的所有追蹤資訊

JkLogLevel    info

資訊 應該是您在正常操作中的預設選項。

JkLogStampFormat 將設定 mod_jk 記錄檔中找到的日期/時間格式。請參閱上方以取得詳細資訊。

JkLogStampFormat "[%Y-%m-%d %H:%M:%S.%Q] "

您可以使用 Apache 標準模組 mod_log_config 記錄 mod_jk 資訊。此模組在 Apache 註解表中設定多個註解。其中大多數僅與負載平衡器工作人員結合使用時才有用。

LogFormat     "%h %l %u %t \"%r\" %>s %b %{JK_WORKER_NAME}n %{JK_LB_FIRST_NAME}n \
               %{JK_LB_FIRST_BUSY}n %{JK_LB_LAST_NAME}n %{JK_LB_LAST_BUSY}n" mod_jk_log
CustomLog     logs/access_log     mod_jk_log

您也可以將請求協定記錄在 mod_jk 記錄檔中，而不是存取記錄檔。這不建議這麼做，而且主要是向後相容性的功能。指令 JkRequestLogFormat 會設定此協定的格式。它會根據每個虛擬主機進行設定和啟用。若要為虛擬主機啟用請求記錄，只要新增 JkRequestLogFormat 設定即可。格式字串的語法類似於 Apache LogFormat 指令，以下是可用的請求記錄格式選項清單

JkRequestLogFormat     "%w %V %T"

指令 JkOptions 讓您可以設定許多轉送選項，這些選項會啟用 (+) 或停用 (-) 下列選項。如果沒有任何前導符號，選項將會啟用。

下列四個選項 +ForwardURIxxx 互斥。必須只使用其中一個，且不允許使用負號前綴。自 1.2.24 版起，預設值為「ForwardURIProxy」。在 1.2.23 版中為「ForwardURICompatUnparsed」，而 1.2.22 版之前則為「ForwardURICompat」。您可以開啟其他兩個選項之一來關閉預設值。除非您有非常充分的理由，否則應將其設為預設值。

所有選項都會從全域伺服器繼承到虛擬主機。支援啟用 (加號選項) 和停用 (減號選項) 的選項會以下列方式繼承
選項(vhost) = 加號選項(全域) - 減號選項(全域) + 加號選項(vhost) - 減號選項(vhost)

使用 JkOptions ForwardURIProxy，轉送的 URI 會在 Apache 內部處理並轉送至 Tomcat 之前，進行部分重新編碼。這將與 mod_rewrite 的本地 URL 處理和 URL 編碼的會話 ID 相容。

JkOptions     +ForwardURIProxy

使用 JkOptions ForwardURICompatUnparsed，轉送的 URI 將不會被解析。它符合規格且安全。它將永遠轉送原始的請求 URI，因此使用 mod_rewrite 改寫 URI，然後轉送改寫後的 URI 將無法運作。

JkOptions     +ForwardURICompatUnparsed

使用 JkOptions ForwardURICompat，轉送的 URI 將由 Apache 解碼。編碼字元將會被解碼，而明確的路徑組成，例如「..」，將會被解析。這較不符合規格，而且如果您使用 JkMount 前綴，則不安全。此選項允許在轉送之前使用 mod_rewrite 改寫 URI。

JkOptions     +ForwardURICompat

使用 JkOptions ForwardURIEscaped，轉送的 URI 將會是 ForwardURICompat 所使用的 URI 編碼形式。明確的路徑組成，例如「..」，將會被解析。這無法與 URL 編碼的會話 ID 搭配使用，但它允許在轉送之前使用 mod_rewrite 改寫 URI。

JkOptions     +ForwardURIEscaped

JkOptions RejectUnsafeURI 將會封鎖在解碼後包含百分比符號「%」或反斜線「\」的所有 URL。

大多數的網路應用程式都不會使用此類 URL。透過使用 RejectUnsafeURI 選項，您可以封鎖多種已知的 URL 編碼攻擊。預設情況下，此選項未設定。

您也可以使用 mod_rewrite 進行此類檢查，它功能更強大，但稍微複雜一些。

JkOptions     +RejectUnsafeURI

JkOptions CollapseSlashesAll 已於 1.2.44 版中棄用，如果使用，將會被忽略。

JkOptions CollapseSlashesUnmount 已於 1.2.44 版中棄用，如果使用，將會被忽略。

JkOptions CollapseSlashesNone 已於 1.2.44 版中棄用，如果使用，將會被忽略。

JkOptions ForwardDirectories 與 Apache 的 DirectoryIndex 指令搭配使用。因此，mod_dir 應可供 Apache 使用，不論是靜態或動態 (DSO)

當 DirectoryIndex 已設定時，Apache 會為指令中指定的每個 local-url 建立子要求，以確定是否有符合的本機檔案 (透過 stat-ing 檔案來完成)。

如果 ForwardDirectories 設為 false (預設值)，而 Apache 找不到任何符合的檔案，Apache 會提供目錄內容 (如果指令 Options 為該目錄指定 Indexes) 或 403 Forbidden 回應 (如果指令 Options 未為該目錄指定 Indexes)。

如果 ForwardDirectories 設為 true，而 Apache 找不到任何符合的檔案，要求會轉送至 Tomcat 以取得解析。這用於 Apache 無法在檔案系統上看到索引檔案的各種情況：Tomcat 在不同的機器上執行、JSP 檔案已預先編譯等。

請注意，本機可見檔案會優先於僅 Tomcat 可見的檔案 (亦即，如果 Apache 可以看到檔案，則會提供該檔案)。如果 Tomcat 通常提供多種類型的檔案，這一點很重要，例如 Velocity 頁面和 JSP 頁面。

JkOptions     +ForwardDirectories

設定 JkOptions ForwardLocalAddress，您要求 mod_jk 傳送 Apache HTTP Server 的本機位址，而非遠端客戶端位址。Tomcat 遠端位址閥門可以使用此功能，只允許來自已設定 Apache 伺服器的連線。

JkOptions     +ForwardLocalAddress

設定 JkOptions ForwardPhysicalAddress，您要求 mod_jk 傳送實體對等 TCP IP 位址作為客戶端位址。預設情況下，mod_jk 使用由網路伺服器提供的邏輯位址。例如，模組 mod_remoteip 會將邏輯 IP 位址設為 X-Forwarded-For 標頭中由代理程式轉送的客戶端 IP。

JkOptions     +ForwardPhysicalAddress

JkOptions FlushPackets，您要求 mod_jk 在收到 Tomcat 傳來的每個 AJP 封包區塊後，清除 Apache 的連線緩衝區。此選項可能會對 Apache 和 Tomcat 造成嚴重的效能損失，因為寫入執行次數比正常情況下所需次數更頻繁 (例如：每個回應結束時)。

JkOptions     +FlushPackets

JkOptions FlushHeader，您要求 mod_jk 在收到 Tomcat 傳來的回應標頭後，清除 Apache 的連線緩衝區。

JkOptions     +FlushHeader

JkOptions DisableReuse，您要求 mod_jk 在使用連線後立即關閉連線。通常，mod_jk 會使用持續連線，並將閒置連線集中起來，以便在必須將新要求傳送至 Tomcat 時重複使用這些連線。

使用此選項可能會對 Apache 和 Tomcat 造成嚴重的效能損失。只有在無法解決的網路問題情況下，才將此選項視為最後的手段。如果 Apache 和 Tomcat 之間的防火牆會在不通知的情況下終止閒置連線，請嘗試將工作者屬性 socket_keepalive 與作業系統中適當的 TCP keepalive 值搭配使用。

JkOptions     +DisableReuse

JkOptions ForwardKeySize，當使用 ajp13 時，您要求 mod_jk 轉發 SSL 金鑰大小，這是 Servlet API 2.3 所需。當 servlet 引擎為 Tomcat 3.2.x 時，不應設定此旗標（預設開啟）。

JkOptions     +ForwardKeySize

JkOptions ForwardSSLCertChain，當使用 ajp13 時，您要求 mod_jk 轉發 SSL 憑證鏈（預設關閉）。Mod_jk 只會將 SSL_CLIENT_CERT 傳遞給 AJP 連接器。對於自簽憑證或由根 CA 憑證直接簽署的憑證，這不是問題。然而，有大量的憑證是由中間 CA 憑證簽署，這是一個重大的問題：servlet 將無法自行驗證用戶端憑證。透過 AJP 連接器將 SSL_CLIENT_CERT_CHAIN 傳遞給 Tomcat，可以修正此錯誤。
此指令僅存在於 1.2.22 版之後。

JkOptions     +ForwardSSLCertChain

指令 JkEnvVar 允許您將環境變數從 Apache 伺服器轉發到 Tomcat 引擎。您可以將預設值新增為指令的第二個參數。如果未明確提供預設值，則僅在執行期間設定變數時才會傳送變數。
變數可以在 Tomcat 端作為請求屬性透過 request.getAttribute(attributeName) 擷取。請注意，透過 JkEnvVar 傳送的變數不會列在 request.getAttributeNames() 中。
變數會從全域伺服器繼承到虛擬主機。

JkEnvVar     SSL_CLIENT_V_START     undefined

如果您已建立自訂或本機版本的 mod_jk.conf-local（如上所述），您可以變更設定，例如工作人員或 URL 前置詞。

JkMount 指令將特定 URL 指定給 Tomcat。一般而言，JkMount 指令的結構為

JkMount [URL prefix] [Worker name]

# send all requests ending in .jsp to worker1
JkMount /*.jsp worker1
# send all requests ending /servlet to worker1
JkMount /*/servlet/ worker1
# send all requests jsp requests to files located in /otherworker will go worker2
JkMount /otherworker/*.jsp worker2

您可以在頂層或 httpd.conf 檔案的 <VirtualHost> 區段中使用 JkMount 指令。

JkUnMount 指令與 JkMount 相反，並封鎖存取特定 URL。目的是能夠從已掛載的內容類型中篩選出特定內容類型。下列範例會掛載 /servlet/* 內容類型，但不會提供屬於該內容類型的所有 .gif 檔案。

# send all requests ending with /servlet to worker1
JkMount /servlet/* worker1
# do not send requests ending with .gif to worker1
JkUnMount /servlet/*.gif worker1

JkUnMount 優先於 JkMount 指令，表示 JK 會先嘗試掛載，然後檢查是否有 JkUnMount 定義的排除。JkUnMount 僅在 JkMount 和 JkUnMount 中的工作人員名稱相同時，才會覆寫 JkMount。

下列範例會封鎖所有 .gif 檔案，即使有 JkMount 可用於這些檔案

# do not send requests ending with .gif to worker1
JkUnMount /*.gif worker1
# The .gif files will not be mounted cause JkUnMount takes
# precedence over JkMount directive
JkMount /servlet/*.gif worker1

從 JK 的 1.2.26 版開始，您可以將 JkUnMount 套用至任何工作人員，方法是在 JkUnMount 中使用星號字元 '*' 作為工作人員名稱。JkUnMount 工作人員名稱中不允許有更複雜的模式。

# Mapping the webapps myapp1 and myapp2:
/myapp1/*=worker1
/myapp2/*=worker2
# Exclude the all subdirectories static for all workers:
!/*/static/*=*
# Exclude some suffixes for all workers:
!*.html=*

JkAutoAlias 指令會自動將 webapp 內容類型目錄別名為 Apache 文件空間。它讓 Apache 能提供靜態內容類型，而 Tomcat 則提供動態內容類型。此指令用於方便，讓您不必為 Tomcat 的 webapp 目錄中的每個應用程式目錄放置 Apache 別名指令。基於安全性考量，強烈建議預設使用 JkMount 將所有請求傳遞給 Tomcat，並使用 JkUnMount 明確排除由 Apache 提供的靜態內容。還應注意，由 Apache 提供的內容會繞過應用程式的 web.xml 中定義的任何安全性限制。此指令僅適用於具有單一路徑元素且沒有版本標記的內容類型的簡單情況。它不支援

• ROOT 情境（例如 .../webapps/ROOT）
• 多層級情境（例如 .../webapps/foo#bar）
• 平行部署（例如 .../webapps/foo##v00.05.12）

# enter the full path to the tomcat webapps directory
JkAutoAlias /opt/tomcat/webapps

以下範例說明如何使用 Tomcat 提供動態情境，並使用 Apache 提供靜態情境。webapps 目錄必須可由 Apache 存取。

# enter the full path to the tomcat webapps directory
JkAutoAlias /opt/tomcat/webapps

# Mount 'examples' directory. It's physical location
# is assumed to be in the /opt/tomcat/webapps/examples
# ajp13w is a worker defined in the workers.properties
JkMount /examples/* ajp13w

# Unmount desired static content from examples webapp.
# This content will be served by the Apache directly.
JkUnMount /*.gif ajp13w

請注意，您可以在 httpd.conf 中的每個虛擬主機中只有一個 JkAutoAlias 指令

JkWorkerProperty 是 JK 1.2.7 版中新增的指令。這是一種用於設定通常在 workers.propeties 檔案中設定的指令的便利方法。該指令的參數是 workers.properties 檔案中的原始行。

# Just like workers.properties but exact line is prefixed
# with JkWorkerProperty

# Minimal jk configuration
JkWorkerProperty worker.list=ajp13w
JkWorkerProperty worker.ajp13w.type=ajp13
JkWorkerProperty worker.ajp13w.host=localhost
JkWorkerProperty worker.ajp13w.port=8009   

JkMountFile 是 JK 1.2.9 版中新增的指令。它用於在執行階段動態更新掛載點。當掛載檔案變更時，JK 會重新載入其內容。

# Load mount points

JkMountFile conf/uriworkermap.properties

如果掛載點 URI 以驚嘆號「!」開頭，它會以與 JkUnMount 相同的方式定義一個排除項。如果掛載點 URI 以減號「-」開頭，掛載點將只會被停用。停用的掛載點可以透過刪除減號並等待 JkMountFile 重新載入來重新啟用。排除項可以透過加上減號為其加上前綴來停用。

# Sample uriworkermap.properties file

/examples/*=ajp13w
# Do not map .gif files
!/*.gif=ajp13w
# Make jsp examples initially disabled  
-/examples/jsp/*=ajp13w

在執行階段，您可以變更這個檔案的內容。例如，移除減號將會啟用先前停用的 URI 對應。您可以在執行階段新增任何數量的反映新部署應用程式的全新項目。Apache 會在 60 秒的間隔內重新載入檔案並更新掛載點。

沒有辦法透過動態重新載入來刪除項目，但您可以停用或排除對應。

除了 mod_jk 特定的指令之外，您也可以使用 SetHandler 和環境變數來控制哪些要求會透過哪些工作人員轉送。這會讓您有更大的彈性，但結果可能比較難理解。如果您同時使用這兩種方式來定義轉送，通常 mod_jk 指令會獲勝。

SetHandler jakarta-servlet 會強制要求由 mod_jk 處理。例如，您可以在 Location 區塊中或在 Apache 2.2 及更新版本中也可以在 RewriteRule 中使用 SetHandler。

為了使用 SetEnvIf 或 RewriteRule 來控制工作人員以取得更複雜的規則，您可以將環境變數 JK_WORKER_NAME 設定為您選擇的目標工作人員名稱。這讓您可以更彈性地決定所選擇的工作人員，包括依賴於 cookie 值。此功能已新增至 mod_jk 的 1.2.19 版。此外，您可能會將規則延伸套件附加到工作人員名稱。延伸套件會以分號「;」與工作人員名稱分隔，使用與 uriworkermap.properties 檔案中相同的語法。在工作人員名稱中支援規則延伸套件的功能已新增至 1.2.33 版。

為了使用 JK_WORKER_NAME 以外的變數，您可以透過 JkWorkerIndicator 指令來設定此變數的名稱。

您也可以透過設定環境變數 no-jk 來定義 mod_jk 轉發的排除項目。

# Automatically map all encoded urls
<Location *;jsessionid=>
  SetHandler jakarta-servlet
  SetEnv JK_WORKER_NAME my_worker
</Location>

# Map all subdirs to workers via naming rule
# and exclude static content.
<Location /apps/>
  SetHandler jakarta-servlet
  SetEnvIf REQUEST_URI ^/apps/([^/]*)/ JK_WORKER_NAME=$1
  SetEnvIf REQUEST_URI ^/apps/([^/]*)/static no-jk
</Location>

環境變數允許根據要求屬性（例如要求 URI、標頭值或 Cookie）覆寫 mod_jk 的預設行為。這可以使用 SetEnvIf 或 RewriteRule 指令來完成。

環境變數 JK_ROUTE 可以設定為明確選擇負載平衡器工作者的成員。其值必須等於成員的路由屬性，或者如果沒有使用該屬性，則等於成員名稱。請注意，這僅在要求中以非標準方式編碼會話 ID 和路由時才需要。預設支援使用 Java Servlet 相容方式編碼 ID 的黏著性。這在版本 1.2.33 中開始提供。

環境變數 JK_REPLY_TIMEOUT 可以設定為動態定義回覆逾時。其值必須以毫秒為單位。這在版本 1.2.27 中開始提供。

環境變數 JK_STICKY_IGNORE 可以設定為停用個別要求的會話黏著性。如果該變數設定為空字串或非零數字，則會停用會話黏著性。將其設定為 0 將重設為工作者組態所定義的行為。這在版本 1.2.33 中開始提供。

當使用基於 Cookie 的會話黏著性時，此功能有助於最佳化負載平衡。在此情況下，只要使用者持續開啟瀏覽器，任何啟動會話的使用者要求都會傳送到同一個 Tomcat 執行個體，即使他離開使用會話的應用程式部分。例如，您可以在使用者要求登入表單時設定此環境變數，以確保此初始會話要求以非黏著性方式進行平衡。

環境變數 JK_STATELESS 可用於改善基於會話的平衡方法 Session 和 Next 的負載平衡。在此情況下，通常任何沒有會話 ID 的要求都會視為新會話。例如，如果在沒有會話 ID 的情況下擷取靜態內容，這可能會造成問題。如果您為要求設定環境變數 JK_STATELESS，則即使要求沒有會話 ID，也不會將其視為新會話。這在版本 1.2.33 中開始提供。

環境變數 JK_IGNORE_CL 可以設定為強制忽略要求的 Content-Length 標頭（如果存在）。然後，mod_jk 會串流要求主體，直到 Web 伺服器指出已讀取完整主體。不會將 Content-Length 標頭傳送到後端。這在版本 1.2.41 中開始提供。

此功能可用於使 mod_jk 與會變更請求主體大小的篩選器相容。其中一個此類篩選器是 mod_deflate，當用於膨脹具有 gzip 編碼主體的請求主體時。在此情況下，mod_jk 預設會轉送截斷的主體，因為它從網路伺服器取得錯誤的主體大小。告知 mod_jk 忽略 Content-Length 標頭將導致串流所有它可以從網路伺服器讀取到後端的請求主體資料。

您應該只針對實際需要它的請求設定 JK_IGNORE_CL 環境變數。不幸的是，mod_jk 無法自動偵測需求。