外掛程式函數 (SAF)

FastCGI 外掛程式提供了下列伺服器應用程式函數 (SAF)：

以下小節說明 FastCGI SAF 的各種參數和「error-reason」字串：

• auth-fastcgi

• responder-fastcgi

• filter-fastcgi

• error-fastcgi

• FastCGI SAF 參數

• error-fastcgi SAF 錯誤原因字串

auth-fastcgi

auth-fastcgi 是一個 PatchCheck 函數。此函數用於將請求轉寄至「Authorizer」FastCGI 應用程式。如果授權成功，將傳送回覆碼 200。否則，會將來自「Authorizer」FastCGI 應用程式的回應傳送回使用者代理程式。

您可以在 http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S6 找到有關 FastCGI 角色的更多資訊。

auth-fastcgi SAF 可接受的參數位於： FastCGI SAF 參數。

以下 obj.conf 程式碼範例說明 auth-fastcgi 的用法：

PathCheck fn="auth-fastcgi" app-path="/usr/bin/perl" app-args="/fastcgi/apps/auth/SimpleAuth.pl" bind-path="localhost:3432"。

responder-fastcgi

responder-fastcgi 是一個 Service 函數。此函數用於將請求轉寄至做為「Responder」的 FastCGI 應用程式。來自 Responder 應用程式的回應將傳送回使用者代理程式。可以在 http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S6 找到有關 FastCGI 角色的更多資訊。

responder-fastcgi SAF 可接受的參數清單位於： FastCGI SAF 參數。

以下 obj.conf 程式碼範例說明 responder-fastcgi 的用法：

Service fn="responder-fastcgi" app-path="/fastcgi-enabled-php-installation/bin/php" bind-path="localhost:3433" app-env="PHP_FCGI_CHILDREN=8" app-env="PHP_FCGI_MAX_REQUEST=500"。

filter-fastcgi

filter-fastcgi 是一個 Service 函數。此函數用於將請求轉寄至「Filter」類型的 FastCGI 應用程式。「Filter」應用程式可接收與 HTTP 請求關聯的資訊，還可以接收儲存在伺服器上的檔案中資料。然後，「Filter」應用程式產生「已篩選」版本的資料流做為回應。此回應將被傳送回使用者代理程式。可以在 http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S6 找到有關 FastCGI 角色的更多資訊。

filter-fastcgi SAF 可接受的參數清單位於： FastCGI SAF 參數。

以下 obj.conf 程式碼範例說明 filter-fastcgi 的用法：

Service fn="filter-fastcgi" app-path="/fastcgi/apps/filter/SimpleFilter" bind-path="localhost:3434" app-env="LD_LIBRARY_PATH=/fastcgi/fcgi-2.4/libfcgi/.libs" min-procs=2

error-fastcgi

error-fastcgi 是 Error 函數。error-fastcgi SAF 可處理 FastCGI 外掛程式特有的錯誤。但是，此函數並不處理 HTTP 錯誤。可將 FastCGI 外掛程式配置為發生錯誤時顯示特定頁面，或將請求重新導向至特定 URL。

error-fastcgi SAF 可接受的參數清單位於： FastCGI SAF 參數。

以下 obj.conf 程式碼片段示範 error-fastcgi 的用法：

Error fn="error-fastcgi" error-reason="Invalid Parameters" error-url="http://www.foo.com/errorPage.html"

請參閱FastCGI SAF 參數，以取得有關 error-fastcgi 參數的資訊。

FastCGI SAF 參數

除非另有明確說明，否則 FastCGI 外掛程式 SAF「auth-fastcgi」、「responder-fastcgi」和「filter-fastcgi」均可接受下列參數：

• bind-path — (選擇性) 可以是 UNIX 網域通訊端名稱、已命名的管道或為 host:port 形式。app-path 參數的說明可解釋 bind-path 參數的用法。

• app-path — (選擇性) 處理請求的 FastCGI 應用程式路徑。此功能取決於 bind-path 參數的值，如下所示：

  1. 如果僅指定 app-path，則外掛程式將建立 FastCGI 應用程式，用以偵聽由外掛程式建立的 UNIX 網域通訊端或已命名的管道。

  2. 如果同時指定 app-path 和 bind-path，則外掛程式將啟動指定的 FastCGI 應用程式程序，並將其連結至指定的 bind-path。

  3. 如果僅指定 bind-path，則會將 FastCGI 應用程序視為遠端執行。因此，外掛程式將不會啟動 FastCGI 應用程式程序。

  4. 如果「app-path」和「bind-path」均未指定，則外掛程式將記錄一則錯誤訊息。

• app-args — (選擇性) 當成引數傳送至 FastCGI 應用程式程序的值。您可使用多個 app-args 參數。使用多個 app-args 參數的格式為 app-args="value" app-args="value" ..。

• app-env — (選擇性) 當成環境變數傳送至 FastCGI 應用程式程序的成對值。您可使用多個「app-env」參數。使用多個 app-env 參數的格式為 app-env="name=value" app-env="name=value"。現有的 Web 伺服器環境變數不會傳送至 FastCGI 程式。因此，您應明確地使用 app-env 設定 FastCGI 程式的環境變數。

  若要編譯 PHP 程式，請確定程式庫檔案已正確配置。

  例如，若您要載入已編譯為 FastCGI 應用程式的 PHP 二進位檔，您必須確定所有的附屬程式庫檔案 (/usr/local/lib 與 /usr/local/mysql/lib) 皆已匯出至 LD_LIBRARY_PATH。

  app-env="LD_LIBRARY_PATH=/usr/local/lib:/usr/local/mysql/lib"

  在 Windows 上為 app-env="Path=c:/php/lib:c:/mysql/lib"

  app-env 也可讓您將其他環境變數匯出至 PHP 應用程式。您可以將 php.ini 檔案位置指定為下列 app-env="PHPRC=<directory path>"。

  使用 PHP 時，您必須為 PHP_FCGI_CHILDREN 與 PHP_FCGI_MAX_REQUESTS 提供較高的值，使其在透過 FastCGI 配置 PHP 時具有較高的優先順序。

• min-procs — (選擇性) 用於指定要建立的 FastCGI 應用程式程序最小整數值。預設為 1。

• max-procs — (選擇性) 用於指定可建立的 FastCGI 應用程式程序最大整數值。此整數值必須等於或大於 min-procs 值。預設為 1。

  ---

  備註 –

  預設值目前為非作業參數。如需有關此問題的更多資訊，請參閱 「Sun Java System Web Server 7.0 Update 3 版本說明」中的「FastCGI 」

  ---

• reuse-connection — (選擇性) 一個布林值，用於確定是否重複使用與 FastCGI 應用程式的連線。False (0、false、no) 代表每次處理請求後會結束與 FastCGI 應用程式的連線。True (1、true、yes) 表示新請求可重複使用現有的連線。預設為 false。另請參閱 connection-timeout。

• connection-timeout — (選擇性) 如果將「reuse-connection」設定為 True，則此值可指定池儲存的連線的逾時值 (以秒為單位)。如果連線閒置長達指定的時間長度，外掛程式將關閉此連線。此參數的預設值為 5 秒。另請參閱 reuse-connection。

• resp-timeout — (選擇性) 代表 FastCGI 伺服器回應逾時的整數值 (以秒為單位)。如果在指定的時間內沒有來自 FastCGI 應用程式的回應，將捨棄此請求。此參數的預設值為 5 分鐘。

• restart-interval — (選擇性) 值為一個整數，代表重新啟動 FastCGI 應用程式的時間間隔 (以分鐘為單位)。此參數的預設值為 60 分鐘 (1 小時)。如果將此參數的值設定為零，將不會強制 FastCGI 應用程式重新啟動。

• req-retry — (選擇性) 值為一個整數，代表 FastCGI 應用程式拒絕請求時，外掛程式應重新傳送請求的次數。此參數的預設值為零。

• listen-queue — (選擇性) 用於指定通訊端的偵聽佇列大小整數值。此參數的預設值為 256。

• rlimit_cpu — 指定 FastCGI 程式可使用的 CPU 時間上限 (以秒為單位)。您只能指定現行 (軟式) 限制。最大 (硬式) 限制不適用於此參數，因此將會忽略。

請注意，chroot、user、group、nice 、chdir、rlimit_as、rlimit_core 與 rlimit_nofile 等參數僅適用於 UNIX 平台。這些參數在 Windows 平台上會被忽略。

• chroot — (僅 UNIX 可選擇) 用於設定 chroot FastCGI 伺服器應用程式程序的根目錄。

• user — (僅 UNIX 可選擇) 指定 FastCGI 應用程式執行時所用之身份的使用者 ID。預設為 Web 伺服器的使用者 ID。

• group — (僅 UNIX 可選擇) FastCGI 應用程式將在指定的群組下執行。預設為 Web 伺服器的群組。

• nice — (僅 UNIX 可選擇) 指定 FastCGI 應用程式程序的 nice/ priority 值。

• chdir — (僅 UNIX 可選擇) 將 chdir 的目錄指定於 chroot 之後，但在執行開始之前。

• rlimit_as — (僅 UNIX 可選擇) 指定最大 CGI 程式位址空間 (以位元組為單位)。您可以提供以逗號分隔的現行 (軟式) 限制與最大 (硬式) 限制。軟式限制必須先列出。如果僅指定一個限制，則兩個限制都會設為此值。

• rlimit_core — (僅 UNIX 可選擇) 指定最大 CGI 程式核心檔案大小。0 值會停用寫入核心。您可以提供以逗號分隔的現行 (軟式) 限制與最大 (硬式) 限制。軟式限制必須先列出。如果僅指定一個限制，則兩個限制都會設為此值。

• rlimit_nofile — (僅 UNIX 可選擇) 為 CGI 程式指定檔案描述元的最大數量。您可以提供以逗號分隔的現行 (軟式) 限制與最大 (硬式) 限制。軟式限制必須先列出。如果僅指定一個限制，則兩個限制都會設為此值。

error-fastcgi 伺服器應用程式功能 (SAF) 接受下列參數：

• error-url — 指定在發生失敗或錯誤情況時，要顯示的頁面、URI 或 URL。此參數的值可以是絕對路徑、文件根的相對路徑、URL 或 URI。

• error-reason — (選擇性) 代表 FastCGI 協定錯誤的字串。發生任何外掛程式錯誤時，此字串可區分要顯示的錯誤 URL。

error-fastcgi SAF 錯誤原因字串

本節提供所有有效「error-reason」字串的清單及這些字串的說明：

• 「配置參數遺失或無效」：未指定 app-path 與 bind-path 時。

• 「Stub 啟動錯誤」： 無法啟動 Fastcgisub 程序。

• 「Stub 連線失敗」： 無法連線至 Fastcgistub。

• 「無權限」： FastCGI 應用程式或 Fastcgisub 沒有執行權限。

• 「Stub 請求處理錯誤」： 無法將請求傳送至 stub、接收到的請求無效，或 stub 沒有針對請求傳送回應等。

• 「設定參數失敗」： 設定 user、group、chroot、nice 等失敗。

• 「使用者和/或群組無效」： 使用者或群組無效。

• 「伺服器程序建立失敗」： FastCGI 應用程式執行失敗或 FastCGI 應用程式無法連結至指定的位址。

• 「Fastcgi 協定錯誤」： FastCGI 應用程式包含具有無效 FastCGI 版本或角色的標頭。

• 「內部錯誤」： 無法開啟要傳送至篩選應用程序的檔案，或任何其他不明的錯誤。