[修炼apache]FastCGI 指引

scyzxp

FastCGI 指引

    * FastCgiAccessChecker
    * FastCgiAccessCheckerAuthoritative
    * FastCgiAuthenticator
    * FastCgiAuthenticatorAuthoritative
    * FastCgiAuthorizer
    * FastCgiAuthorizerAuthoritative
    * FastCgiConfig
    * FastCgiExternalServer
    * FastCgiIpcDir
    * FastCgiServer
    * FastCgiSuexec
    * 相關資訊

FastCgiAccessChecker

    * 預設值 - Directory
    * 語法 - FastCgiAccessChecker filename [-compat]

FastCgiAccessChecker 指引可用來將 FastCGI 應用程式定義為每一目錄存取的驗證程式。 Apache Access 階段發生於進行使用者鑑別之前，因此，對於是否容許存取所要求的資源的決定，是根據隨要求送出的 HTTP 標題。如果存取驗證決策中涉及動態因素限制，例如，每天時間或網域帳戶是否為最新的，以 FastCGI 為基礎的授權程式就非常有用。

如果 FastCGI 應用程式檔名中沒有對應的靜態或外部伺服器定義，該應用程式就會啟動成為動態的 FastCGI 應用程式。如果檔案名稱開頭不是斜線 (/)，該檔案名稱就會被假設為是 ServerRoot 的相對名稱。

FastCgiAccessChecker 使用於 Directory 或 Location 配置區。

    <Directory htdocs/protected>
    FastCgiAccessChecker fcgi-bin/access-checker
    </Directory>

Mod_fastcgi 會傳送大部分一般可用的所有標準環境變數到 CGI/FastCGI 要求處理程式。在成功回應中 (狀態：200)，由 FastCGI 存取檢查程式所傳回的所有標題，皆當做環境變數傳送到子處理程序 (CGI/FastCGI 呼叫)。在失敗回應中傳回的所有標題，都會傳送到從屬站。FastCGI 規格相容行為是透過 "-compat" 選項取得。

Mod_fastcgi 會將環境變數 "FCGI_APACHE_ROLE" 設定為 "ACCESS_CHECKER"，來表示所執行的授權程式階段 (Apache 專用)。

來自 FastCGI 授權應用程式的自訂失敗回應不被支援。如果要閱讀實例，請參閱 ErrorDocument 指引 (FastCGI 應用程式可提供此文件)。
FastCgiAccessCheckerAuthoritative

    * 環境定義 - Directory
    * 預設值 - FastCgiAccessCheckerAuthoritative On
    * 語法 - FastCgiAccessCheckerAuthoritative On | Off

明確地將 FastCgiAccessCheckerAuthoritative 指引設定為 Off，可在 FastCGI 應用程式無法容許存取時，讓存取檢查跳到較低層次的模組（定義於配置檔和 modules.c 檔案中）。

依預設值，不會跳過控制權，且失敗的存取檢查會產生「禁止」回覆。建議您在停用預設值之前，先仔細考慮清楚。
FastCgiAuthenticator

    * 環境定義 - Directory
    * 語法 - FastCgiAuthenticator filename [-compat]

FastCgiAuthenticator 指引用來將 FastCGI 應用程式定義為每一目錄的驗證程式。驗證程式驗證要求者的方式是將所提供的使用者名稱和密碼，和清單或資料庫中的已知使用者名稱和密碼比對。如果使用者資料庫是在現存的獨立程式中維護，或位於 Web 伺服器以外的機器上，以 FastCGI 為基礎的鑑別程式就非常有用。

如果 FastCGI 應用程式檔名中沒有對應的靜態或外部伺服器定義，該應用程式就會啟動成為動態的 FastCGI 應用程式。如果檔案名稱開頭不是斜線 (/)，該檔案名稱就會被假設為是 ServerRoot 的相對名稱。

FastCgiAuthenticator 使用於 Directory 或 Location 配置區中，且必須包含一個 AuthType 和 AuthName 指引。僅支援 Basic 使用者鑑別類型。這種類型需要有 required 或 FastCgiAuthorizer 指引，才能正確運作。

    <Directory htdocs/protected>
    AuthType Basic
    AuthName ProtectedRealm
    FastCgiAuthenticator fcgi-bin/authenticator
    require valid-user
    </Directory>

Mod_fastcgi 會傳送大部分一般可用的所有標準環境變數到 CGI/FastCGI 要求處理程式。在成功回應中 (狀態：200)，由 FastCGI 鑑別應用程式所傳回的所有標題，皆當做環境變數傳送到子處理程序 (CGI/FastCGI 呼叫)。在失敗回應中傳回的所有標題，都會傳送到從屬站。 FastCGI 規格相容行為是透過 "-compat" 選項取得。

Mod_fastcgi 會將環境變數 "FCGI_APACHE_ROLE" 設定為 "AUTHENTICATOR"，來表示所執行的授權程式階段 (Apache 專用)。

來自 FastCGI 授權應用程式的自訂失敗回應不被支援。如果要閱讀實例，請參閱 ErrorDocument 指引 (FastCGI 應用程式可提供此文件)。

FastCgiAuthenticatorAuthoritative

    * 環境定義 - Directory
    * 預設值 - FastCgiAuthenticatorAuthoritative On
    * 語法 - FastCgiAuthenticatorAuthoritative On | Off

明確地將 FastCgiAuthenticatorAuthoritative 指引設定為 Off，可在 FasCGI 應用程式無法鑑別使用者時，讓鑑別跳到較低層次的模組（定義於配置檔和 modules.c 檔中)。

此指引的常用方法是結合一個受到充分保護的 AuthUserFile，其中含有少數 (和管理相關的) 使用者。

依預設值，不會跳過控制，且不明使用者會產生「需要授權」回覆。要停用預設值之前應考慮清楚。
FastCgiAuthorizer

    * 環境定義 - Directory
    * 語法 - FastCgiAuthorizer 檔名 [-compat]

FastCgiAuthorizer 指引可用來定義 FastCGI 應用程式，作為各個目錄的授權程式。授權程式驗證經過鑑別的使用者是否可以存取所要求的資源。如果存取驗證決策涉及動態因素，如每日時間或使用者是否已付清款項等， FastCGI 型的授權程式就非常有用。

如果 FastCGI 應用程式檔案名稱沒有對應的靜態或外部伺服器定義，應用程式即會啟動成為動態 FastCGI 應用程式。  如果檔案名稱開頭不是斜線 (/)， 檔案名稱即會假設為與 ServerRoot 相對。

FastCgiAuthorizer 使用於 Directory 或 Location 儲存器中，且必須包含 AuthType 和 AuthName 指引。此指引必須搭配一個 authentication 指引，如 FastCgiAuthenticator、AuthUserFile、AuthDBUserFile 或 AuthDBMUserFile，才能正確運作。
.

    <Directory htdocs/protected>
    AuthType Basic
    AuthName ProtectedRealm
    AuthDBMUserFile conf/authentication-database
    FastCgiAuthorizer fcgi-bin/authorizer
    </Directory>

Mod_fastcgi 會傳送大部分一般可用所有標準環境變數到 CGI/FastCGI 要求處理程式。在成功回應中 (狀態：200)，由 FastCGI 鑑別應用程式所傳回的所有標題，都會當做環境變數傳送到子處理程序 (CGI/FastCGI 呼叫)。在失敗回應中傳回的所有標題，都會傳送到從屬站。 FastCGI 規格相容行為是經由 "-compat" 選項取得。

Mod_fastcgi 會將環境變數 "FCGI_APACHE_ROLE" 設定為 "AUTHORIZER"，來表示所執行的授權程式階段 (Apache 專用)。

不支援 FastCGI 授權應用程式的自訂失敗回應。如果要閱讀實例，請參閱 ErrorDocument 指引 (FastCGI 應用程式可提供此文件)。
FastCgiAuthorizerAuthoritative

    * 環境定義 - Directory
    * 預設值 - FastCgiAuthorizerAuthoritative On
    * 語法 - FastCgiAuthorizerAuthoritative On | Off

明確地將 FastCgiAuthenticatorAuthoritative 指引設定為 Off，可在 FasCGI 應用程式無法鑑別使用者時，讓鑑別跳到較低層次的模組（定義於配置檔和 modules.c 檔中)。

此目錄的常用方法是結合一個受到充分保護的 AuthUserFile，其中含有少數 (和管理相關的) 使用者。

依預設值，不會跳過控制，且不明使用者會產生「需要授權」回覆。要停用預設值之前應考慮清楚。
FastCgiConfig

    * 環境定義 - 伺服器配置
    * 語法 - FastCgiConfig 選項 選項 ...

FastCgiConfig 指引定義所有動態 FastCGI 應用程式的預設參數。此指引不會影響靜態或外部應用程式。

動態應用程式會依需求啟動。若需求很大，則啟動其它應用程式案例。隨著需求降低，應用程式案例就逐漸減少。許多選項可支配此程序。

選項可包括下列其中一項 (不區分大小寫)：
appConnTimeout n (0 秒)
    等候和 FastCGI 應用程式完成連線所需的秒數；或 0，表示使用暫停執行的 connect()。如果超過逾時期限，則會產生 SERVER_ERROR 結果。非 0 值表示 select() 用來寫入由非暫停執行的 connect() 傳回的檔案描述子的時間量。在許多平台上，非暫停執行的 connect() 有些麻煩。另請參閱 -idle-timeout，此選項會產生類似的結果，但較具有可攜性。
idle-timeout n (30 秒)
    FastCGI 應用程式可維持非作用中的秒數，在超過此秒數之後，即會中止要求和記載事件（在 error LogLevel）。  非作用中計時器僅在與 FastCGI 應用程式的連線擱置時才會套用。  如果要求被排入應用程式的佇列，但應用程式未於此期限內回應（經由寫入和沖寫），要求即會被中止。如果和應用程式的通信已完成，但和從屬站的通信未完成（回應進入緩衝），則不適用逾時。
autoUpdate none
    此選項會使 mod_fastcgi 在處理每一個要求之前，先檢查磁碟上的應用程式經歷時間。如果應用程式很新，則會通知處理管理系統，然後結束應用程式的所有執行案例。這種功能最好內建於應用程式中（例如，每 100 個要求檢查一次，查詢磁碟上是否有較新的版本，如果有，則結束)。當此選項使用 -restart 時，可能會發生一個尚未解決的問題 (錯誤)。
gainValue n (0.5)
    一個介於 0 和 1 之間的浮點值，在計算目前執行之動態 FastCGI 應用程式的指數遞減連接時間載入因數時，用來做為指數。舊的值以 (1 - gainValue) 來調整，因此，此值愈小，舊的值相對於現行值（由 gainValue 調整）的加權值就愈大。
initial-env name[=value] none
    應用程式的實例產生時，傳入起始環境中的 name-value 組合。如果要傳送來自 Apache 環境的變數，請勿提供 "="（若變數實際上不存在環境中，定義時不會有值)。如果要定義不含值的變數，請提供 "=" ，但不加任何值。此選項可重複使用。
init-start-delay n (1 秒)
    產生此應用程式案例時，最小的間隔秒數。此延遲時間可降低系統在伺服器起始設定時產生的需求。
killInterval n (300 秒)
    killInterval 決定動態應用程式實例結束策略在處理管理系統內的實施頻率。數字小可產生較積極的策略，數字大可產生較消極的策略。
listen-queue-depth n (100)
    此應用程式的全部案例所共用的 listen() 佇列（亦稱為 backlog）深度。接聽佇列較深時，可讓伺服器靈活應付暫時性的載入量變動，而不會拒絕要求；但不會提高通訊量。加入額外的應用程式實例可能可以提高通訊量和效能，視應用程式和主電腦而定。
maxClassProcesses n (10)
    對於任何 FastCGI 應用程式，容許執行的最大動態 FastCGI 應用程式案例數目。
maxProcesses n (50)
    容許隨時執行的動態 FastCGI 應用程式案例最大數量。
minProcesses n (5)
    在任何時間容許執行的動態 FastCGI 應用程式實例下限，這些實例不會被處理管理系統結束（由於沒有需求）。
multiThreshhold n (50)
    介於 0 和 100 之間的一個整數，用來決定是否要終止任何 FastCGI 應用程式實例。如果應用程式目前有一個以上的實例正在執行，此屬性將用來決定是否要終止那些實例。若只剩下一個實例，則改用 singleThreshhold。
pass-header header none
    在要求環境內傳入的 HTTP要求標題名稱。此選項使得 CGI 環境可以使用標題內容（例如，授權）。
priority n (0)
    指定給應用程式案例的處理優先順序 (使用 setpriority())。
processSlack n (5 秒)
    如果目前在執行中的動態 FastCGI 應用程式總數超過 maxProcesses - processSlack，處理管理系統即會啟動結束策略。這可在達到 maxProcesses 之前，結束一些不活動的應用程式實例，在高負荷時提高效能。
restart none
    此選項可讓處理管理系統在失敗時重新啟動動態應用程式 (類似靜態應用程式)。
restart-delay n (5 秒)
    重新產生此應用程式的失敗案例時，最小的間隔秒數。此延遲時間可防止已中斷的應用程式佔用太多系統資源。
singleThreshhold n (0)
    介於 0 和 100 之間的一個整數，決定是否可終止 FastCGI 應用程式的最後一個實例。若處理管理系統計算的應用程式負荷因數低於指定的臨界值，就會終止最後一個實例。指定接近 1 的值，讓您的執行檔長時間在 "idle" 模式下執行。不過，若記憶體或 CPU 時間是重要考量，接近 100 的值更為合適。0 值可防止終止應用程式的最後一個實例，此為預設值。不建議變更預設值（尤其是如果有設定 -appConnTimeout 時，更不可變更）。
startDelay n (3 秒)
    嘗試連接動態 FastCGI 應用程式時，Web 伺服器應等候的秒數。若超過間隔時間，則會通知處理管理系統，希望能夠啟動應用程式的另一個實例。 startDelay 必須小於 appConnTimeout 才有效。
updateInterval n  (300 秒)
    updateInterval 決定多久執行一次統計分析，決定動態 FastCGI 應用程式的命運。
FastCgiExternalServer

    * 環境定義 - 伺服器配置
    * 語法 - FastCgiExternalServer filename -host hostnameport [-appConnTimeout n]
      FastCgiExternalServer filename -socket filename [-appConnTimeout n]

appConnTimeout n (0 秒)
    等候和 FastCGI 應用程式完成連線所需等待的秒數，或 0，表示使用暫停執行的 connect()。如果超過逾時期限，則會產生 SERVER_ERROR 結果。非 0 值表示 select() 用來寫入由非暫停執行的 connect() 傳回的檔案描述子的時間量。在許多平台上，非暫停執行的 connect() 有些麻煩。另請參閱 -idle-timeout; 此選項會產生類似的結果，但較具有可攜性。
idle-timeout n (30 秒)
    FastCGI 應用程式可維持非作用中的秒數，在超過此秒數之後，即會中止要求和記載事件（在 error LogLevel）。  非作用中計時器僅在與 FastCGI 應用程式的連線擱置時才會套用。  如果要求被排入應用程式的佇列，但應用程式未於此期限內回應（經由寫入和沖寫），要求即會被中止。如果和應用程式的通信已完成，但和從屬站的通信未完成（回應進入緩衝），則不適用逾時。
flush none
    接收到應用程式的資料時，強制寫入到從屬站。依預設值，mod_fastcgi 會將資料放入緩衝區內，以便儘快地釋放應用程式。
host hostname:port none
    應用程式與 Web 伺服器通信時使用的主電腦名稱或 IP 位址和 TCP 埠號 (1-65535)。 -socket 與 -host 選項互斥。
Pass-header header none
    在要求環境內傳入的 HTTP 要求標題名稱。此選項使得 CGI 環境可以使用通常無法使用的標題內容（例如，授權）。
socket filename none
    UNIX：應用程式和 Web 伺服器通信時使用的 UNIX 網域 socket 檔名。此檔案名稱相對於 FastCgiIpcDir。 -socket 和 -port 兩個選項互斥。
    Windows NT：應用程式和 Web 伺服器通信時，使用的管線名稱。該名稱相對於 FastCgiIpcDir。-socket 和 -port 兩個選項互斥。
FastCgiIpcDir

    * 環境定義 - 伺服器配置
    * 預設值 - UNIX - FastCgiIpcDir /tmp/fcgi；Windows NT - FastCgiIpcDir \\.\pipe\ModFastCgi\
    * 語法 - UNIX - FastCgiIpcDir directory, Windows NT - FastCgiIpcDir name

適用 UNIX 平台        

UNIX：FastCgiIpcDir 指引指定 directory，作為儲存（和尋找，如果是外部 FastCGI 應用程式）應用程式和 Web 伺服器通信時，所用的 UNIX Socket 檔案的位置。若目錄的開頭不是斜線 (/)，則會假設目錄是和 ServerRoot 相對。如果目錄不存在，則會嘗試以適當的許可權建立目錄。請勿指定一個不在本端檔案系統上的目錄。如果您使用預設目錄（或 /tmp 內的另一個目錄），當您的系統定期地刪除 /tmp 中的檔案時， mod_fastcgi 會中斷執行。
適用 Windows NT        

Windows NT：FastCgiIpcDir 指引指定 name ，作為應用程式與 Web 伺服器通信時，使用的具名管線之根目錄。 name 格式必須是 \\.\pipe\pipename。 pipename 中可以包含反斜線以外的任何字元。
      

FastCgiIpcDir 指引必須放在任何 FastCgiServer 或 FastCgiExternalServer 指引之前 (使用 UNIX socket)。請確定目錄必須可讓 Web 伺服器讀取、寫入及執行（搜尋），任何人都不可以存取此目錄。
FastCgiServer

    * 環境定義 - 伺服器配置
    * 語法 -FastCgiServer 檔名 選項 選項 ...

FastCgiServer 指引將檔名定義為靜態 FastCGI 應用程式。如果檔案名稱開頭不是斜線 (/)，該檔案名稱就會被假設為是與 ServerRoot 相對。

依預設值，「處理管理系統」會使用下列指定的預設配置（在括弧中），啟動應用程式的一個實例。如果某個靜態應用程式實例中止了，mod_fastcgi 即會產生另一個實例來代替，並且記載此事件（在 warn LogLevel）。

選項包括下列其中一個 (不區分大小寫)：
appConnTimeout n (0 秒)
    等待 FastCGI 應用程式連線完成的秒數；或以 0 表示使用暫停執行的 connect()。如果超過逾時值，則會產生 SERVER_ERROR 結果。對於非零值，這表示 select() 用來寫入到由非暫停執行的 connect() 所傳回的檔案描述子的時間量。在許多平台上，非暫停執行的 connect() 有些麻煩。另請參閱 -idle-timeout，該選項產生類似的結果，但更具有可攜性。
idle-timeout n (30 秒)
    FastCGI 應用程式可維持非作用中的秒數，在超過此秒數之後，即會中止要求和記載事件（在 error LogLevel）。  非作用中計時器僅在與 FastCGI 應用程式的連線擱置時才會套用。  如果要求被排入應用程式的佇列，但應用程式未於此期限內回應（經由寫入和沖寫），要求即會被中止。如果和應用程式的通信已完成，但和從屬站的通信未完成（回應進入緩衝），則不適用逾時。
initial-env name[=value] none] none
    傳入 FastCGI 應用程式 initial 環境中的 name-value 組合。如果要傳送 Apache 環境的變數，請勿提供 "=" （若變數實際上不存在環境中，定義時不會有值)。如果要定義不含值的變數，請提供 "=" ，但不加任何值。此選項可重複使用。
init-start-delay n(1 秒)
    產生此應用程式案例時，最小的間隔秒數。此延遲時間可降低系統在伺服器起始設定時產生的需求。
Flush none
    接收到應用程式的資料時，強制寫入到從屬站。依預設值，mod_fastcgi 會將資料放入緩衝區內，以便儘快地釋放應用程式。
Listen-queue-depth n (100)
    此應用程式的全部案例共用的 listen() 佇列（亦稱為 backlog）深度。接聽佇列較深時，可讓伺服器靈活應付暫時性的載入量變動，而不會拒絕要求；此選項不會提高通訊量。加入額外的應用程式實例可以提高通訊量和效能，視應用程式和主電腦而定。
Pass-header header none
    在要求環境內傳入的 HTTP 要求標題名稱。此選項使得 CGI 環境可以使用標題內容（例如，授權）。
processes n (1)
    起始設定伺服器時所產生的應用程式案例數目。
Priority n (0)
    指定給應用程式實例的處理優先順序（使用 setpriority()）。
port n none
    應用程式和 Web 伺服器通信時，所用的 TCP 埠號 (1-65535)。此選項可讓網路上的其它機器也可以存取應用程式。 -socket 和 -port 兩個選項互斥。
Restart-delay n (5 秒)
    重新產生此應用程式的失敗案例時，最小的間隔秒數。此延遲時間可防止已中斷的應用程式佔用太多系統資源。
Socket filename (gen'd)
適用 UNIX 平台        
    UNIX：應用程式在和 Web 伺服器通信時，所用的 UNIX 網域 socket 檔案名稱。該模組會在 FastCgiIpcDir 所指定的目錄中建立 Socket。此選項讓應用程式可被相同機器上的其它應用程式（例如，cgi-fcgi）存取，或透過外部 FastCGI 應用程式定義（FastCgiExternalServer）來存取。若沒有提供 -socket 或 -port 選項，該模組會產生一個 UNIX 網域 socket 檔案名稱。-socket 和 -port 兩個選項互斥。
適用於 Windows NT         Windows NT：應用程式在和 Web 伺服器通信時，應使用的管線名稱。該模組會在由 FastCgiIpcDir 指定的具名管線根目錄之下建立指名的管線。此選項讓應用程式可讓位於相同機器上的其它應用程式（如 cgi-fcgi）存取，或可透過外部 FastCGI 應用程式定義 FastCgiExternalServer 存取。如果沒有提供 -socket 或 -port 選項，該模組會為具名管線產生一個名稱。 -socket 和 -port 兩個選項互斥。
         
FastCgiSuexec

    * 環境定義 - 伺服器配置
    * 預設值 - FastCgiSuexec Off
    * 語法 - FastCgiSuexec On | Off | 檔名

FastCgiSuexec 指引是用來啟用 suexec-wrapper 支援。 FastCgiSuexec 需要在 Apache 啟用 suexec (用於 CGI)。如果要使用 Apache 所用的相同 suexec-wrapper，請將 FastCgiSuexec 設定為 On。如果要使用不同的 suexec-wrapper，請指定 suexec-wrapper 的檔案名稱。若檔名開頭不是斜線 (/)，則會假設檔名和 ServerRoot 相對。

若啟用 FastCgiSuexec ，靜態或外部 FastCGI 應用程式定義的位置非常重要。這些差異是從虛擬伺服器中，定義使用者和群組的 User 和 Group 指引繼承使用者和群組。 User 和 Group 指引應該放在 FastCGI 應用程式定義之前。此功能不會限制 FastCGI 應用程式一定要在其被定義的虛擬伺服器上，應用程式可以服務來自任何虛擬伺服器的要求（由相同使用者和群組所提出）。若接收到對 FastCGI 應用程式的要求，其中沒有正確使用者和群組的相符定義，則會以正確的使用者和群組啟動應用程式的一個動態實例。此動作會導致相同應用程式的多個副本以不同的使用者/群組身份執行。若產生這種問題，請禁止從其它虛擬伺服器瀏覽應用程式，或以相同的 User 和 Group 來配置虛擬伺服器。

關於 suexec 的詳細資訊，請參閱 Apache 文件 (確定您充份瞭解安全性的意義)。