Dispatcher の設定

メモ

Dispatcher のバージョンは AEM とは無関係です。以前のバージョンの AEM のドキュメントに組み込まれている Dispatcher のドキュメントへのリンクをたどると、このページにリダイレクトされる可能性があります。

以下の節では、Dispatcher の様々な設定について説明します。

IPv4 と IPv6 のサポート

AEM と Dispatcher のすべての要素は、IPv4 と IPv6 の両方のネットワークにインストールできます。IPv4 と IPv6 を参照してください。

Dispatcher の設定ファイル

デフォルトでは、Dispatcher の設定は dispatcher.any テキストファイルに格納されますが、インストール時にこのファイルの名前と場所を変更できます。

設定ファイルには、Dispatcher の動作を制御する一連の単一値または複数値プロパティが含まれます。

  • プロパティ名の前にはフォワードスラッシュ(「/」)が付きます。
  • 複数値プロパティは、中括弧(「{ }」)を使用して子アイテムを囲みます。

設定例を次に示します。

# Dispatcher の名前 /name "internet-server" # 各ファームで一連の(ロードバランシングの)レンダラーを設定 /farms { # 最初のファームエントリ(ラベルは重要でなく、便宜上) /website { /clientheaders { # 渡されるヘッダーのリスト } /virtualhosts { # この Web サイトの URL のリスト } /sessionmanagement { # ユーザー認証の設定 } /renders { # ドキュメントをレンダリングする AEM インスタンスのリスト } /filter { # フィルターのリスト } /vanity-urls { # バニティー URL のリスト } /cache { # キャッシュの設定 /rules { # キャッシュ可能なドキュメントのリスト } /invalidate { # 自動無効化されるドキュメントのリスト } } /statistics { /categories { # ロードバランシングでの予測に使用するドキュメントカテゴリ } } /stickyConnectionsFor "/myFolder" /health_check { # インスタンスが 500 を返したときにアクセスするページ } /retryDelay "1" /numberOfRetries "5" /unavailablePenalty "1" /failover "1" } }
        

コードサンプルは、例としてのみ使用することを目的としています。

設定に影響を与える他のファイルを含めることができます。

  • 設定ファイルのサイズが大きい場合、このファイルを管理しやすくするために分割した複数のファイル。
  • 自動生成されたファイル。

例えば、myFarm.any ファイルを /farms の設定に含めるには、次のコードを使用します。

/farms { $include "myFarm.any" }
        

コードサンプルは、例としてのみ使用することを目的としています。

含めるファイルの範囲を指定するには、アスタリスク(「*」)をワイルドカードとして使用します。

例えば、farm_1.anyfarm_5.any のファイルにファーム 1 ~ 5 が設定されている場合、これらのファイルを次のように含めることができます。

/farms { $include "farm_*.any" }
        

コードサンプルは、例としてのみ使用することを目的としています。

環境変数の使用

値を直接記述する代わりに、dispatcher.any ファイルの単一値プロパティに環境変数を使用できます。環境変数の値を含めるには、${variable_name} という形式を使用します。

例えば、dispatcher.any ファイルがキャッシュディレクトリと同じディレクトリに配置されている場合は、/docroot プロパティに次の値を使用できます。

/docroot "${PWD}/cache"
        

コードサンプルは、例としてのみ使用することを目的としています。

もう 1 つの例として、AEM パブリッシュインスタンスのホスト名を格納する RENDER_IP という環境変数を作成した場合は、/renders プロパティの次の設定を使用できます。

/renders {
  /0001 {
    /hostname "${PUBLISH_IP}"
    /port "8443"
  }
}
        

コードサンプルは、例としてのみ使用することを目的としています。

Dispatcher インスタンスの命名 - /name

Dispatcher インスタンスを識別する一意の名前を指定するには、/name プロパティを使用します。/name プロパティは、設定構造の最上位プロパティです。

ファームの定義 - /farms

/farms プロパティは、1 つまたは複数の Dispatcher の動作セットを定義します。各セットは、異なる Web サイトまたは URL に関連付けられます。/farms プロパティには、1 つまたは複数のファームを含めることができます。

  • Dispatcher ですべての Web ページまたは Web サイトを同じ方法で処理する場合は、単一のファームを使用します。
  • Web サイトの異なる領域または異なる Web サイトに異なる Dispatcher 動作が必要な場合は、複数のファームを作成します。

/farms プロパティは、設定構造の最上位プロパティです。ファームを定義するには、/farms プロパティに子プロパティを追加します。Dispatcher インスタンス内でファームを一意に識別するプロパティ名を使用してください。

/farmname プロパティは複数値で、次のような Dispatcher 動作を定義する他のプロパティを含みます。

  • ファームを適用するページの URL。
  • ドキュメントのレンダリングに使用する 1 つまたは複数のサービス URL(一般的には AEM パブリッシュインスタンスの URL)。
  • 複数のドキュメントレンダラーのロードバランシングに使用する統計。
  • キャッシュするファイルおよびその場所など、その他の動作。

値には、任意の英数字(a ~ z、0 ~ 9)を含めることができます。/daycom および /docsdaycom という 2 つのファームのスケルトン定義の例を次に示します。

#name of dispatcher
/name "day sites"

#farms section defines a list of farms or sites
/farms
{
   /daycom
   {
       ...
   }
   /docdaycom
   {
      ...
   }
}
        

コードサンプルは、例としてのみ使用することを目的としています。

メモ

レンダーファームを複数使用する場合、リストは下から順に評価されます。この順序は、Web サイトの仮想ホストを定義する場合に特に重要です。

各ファームプロパティには、以下の子プロパティを含めることができます。

プロパティ名 説明
/homepage
デフォルトのホームページ
(オプション)(IIS のみ)
/clientheaders
通過させるクライアント HTTP 要求のヘッダー。
/virtualhosts このファームの仮想ホスト。
/sessionmanagement
セッション管理および認証のサポート。
/renders レンダリングされたページを提供するサーバー(一般的には AEM パブリッシュインスタンス)。
/filter Dispatcher がアクセスできる URL を定義します。 
/vanity-urls バニティー URL へのアクセスを設定します。
/propagateSyndPost
シンジケーション要求の転送のサポート。
/cache
キャッシュ動作を設定します。
/statistics
ロードバランシング計算用の統計カテゴリの定義。
/stickyConnectionsFor スティッキードキュメントを格納するフォルダー。
/health_check サーバーの可用性を判断するために使用する URL。
/retryDelay 失敗した接続を再試行するまでの遅延。 
/unavailablePenalty ロードバランシング計算用の統計に影響を与えるペナルティ。
/failover 元の要求が失敗した場合に異なるレンダーに要求を再送信します。 

デフォルトページの指定(IIS のみ) - /homepage

注意

このパラメーターは IIS のみで適用され、他の Web サーバーで指定しても効果はありません。

例えば Apache を使用する場合は、mod_rewrite を使用します。mod_rewrite については、Apache Web サイトのドキュメント(Apache 2.2 など)を参照してください。mod_rewrite を使用する場合は、'passthrough|PT' (pass through to next handler) フラグを使用して、内部の request_rec 構造の uri フィールドに filename フィールドの値を設定するよう、書き換えエンジンに指示することをお勧めします。

オプションの /homepage パラメーターでは、解決できないページまたはファイルをクライアントが要求した場合に Dispatcher が返すページを指定します。

一般的に、IIS または AEM が自動リダイレクションターゲットを提供しない URL をユーザーが指定すると、このような状況が発生します。例えば、コンテンツがキャッシュされた後に AEM レンダーインスタンスがシャットダウンされると、コンテンツリダイレクト URL は利用できなくなります。

次の設定サンプルは、そのような状況で index.html ページを表示します。

/homepage "/index.html"
        

コードサンプルは、例としてのみ使用することを目的としています。

/homepage セクションは、/farms セクションの内部に配置します。例を以下に示します。

#name of dispatcher
/name "day sites"

#farms section defines a list of farms or sites
/farms
{
   /daycom
   {
       /homepage "/index.html"
       ...
   }
   /docdaycom
   {
      ...
   }
}
        

コードサンプルは、例としてのみ使用することを目的としています。

通過させる HTTP ヘッダーの指定 - /clientheaders

/clientheaders プロパティでは、Dispatcher がクライアント HTTP 要求からレンダラー(AEM インスタンス)に渡す HTTP ヘッダーのリストを定義します。

デフォルトでは、Dispatcher から AEM インスタンスに標準の HTTP ヘッダーが転送されます。インスタンスによっては、追加のヘッダーを転送したり、特定のヘッダーを削除したりできます。

  • AEM インスタンスが HTTP 要求で予期するヘッダー(カスタムヘッダーなど)を追加します。
  • ヘッダー(Web サーバーに対してのみ重要な認証ヘッダーなど)を削除します。 

 

通過させる一連のヘッダーをカスタマイズした場合は、ヘッダーの完全なリスト(通常はデフォルトで含まれるヘッダーを含む)を指定する必要があります。

例えば、パブリッシュインスタンス向けのページアクティベーション要求を処理する Dispatcher インスタンスには、/clientheaders セクションに PATH ヘッダーが必要です。PATH ヘッダーは、レプリケーションエージェントと Dispatcher 間の通信を可能にします。

次のコードは、/clientheaders の設定例です。

/clientheaders { "referer" "user-agent" "authorization" "from" "content-type" "content-length" "accept-charset" "accept-encoding" "accept-language" "accept" "host" "if-match" "if-none-match" "if-range" "if-unmodified-since" "max-forwards" "proxy-authorization" "proxy-connection" "range" "cookie" "cq-action" "cq-handle" "handle" "action" "cqstats" "PATH" }
        

コードサンプルは、例としてのみ使用することを目的としています。

仮想ホストの識別 - /virtualhosts

/virtualhosts プロパティは、Dispatcher がこのファームに受け入れるすべてのホスト名と URI の組み合わせのリストを定義します。ワイルドカードとしてアスタリスク(「*」)文字を使用できます。/virtualhosts プロパティの値には、次の形式を使用します。

[scheme]host[uri][*]
        

コードサンプルは、例としてのみ使用することを目的としています。

  • scheme:(オプション)http:// または https://
  • host:ホストコンピューターの名前または IP アドレスと、必要な場合はポート番号(http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.23 を参照してください)。
  • uri:(オプション)リソースへのパス。

次の設定例では、myCompany の .com ドメインと .ch ドメイン、さらに mySubDivision のすべてのドメインに対する要求を処理します。

/virtualhosts { "www.myCompany.com" "www.myCompany.ch" "www.mySubDivison.*" }
        

コードサンプルは、例としてのみ使用することを目的としています。

次の設定は、すべての要求を処理します。

/virtualhosts { "*" }
        

コードサンプルは、例としてのみ使用することを目的としています。

仮想ホストの解決

HTTP 要求または HTTPS 要求を受信すると、Dispatcher は要求の hosturi および scheme ヘッダーに最良一致の仮想ホスト値を探します。Dispatcher は、次の順序で virtualhosts プロパティの値を評価します。

  • dispatcher.any ファイル内の一番下のファームから始め、上方向へ進みます。
  • ファームごとに、virtualhosts プロパティの最上位の値から始め、値のリストの下方向へ進みます。

Dispatcher は、以下の方法で最良一致の仮想ホスト値を探します。

  • 要求の hostschemeuri の 3 つすべてに一致する、最初に見つかった仮想ホストを使用します。
  • 要求の schemeuri の両方に一致する scheme 部と uri 部を持つ virtualhosts 値がない場合は、要求の host に一致する、最初に見つかった仮想ホストを使用します。
  • 要求の host に一致する host 部を持つ virtualhosts 値がない場合は、最上位ファームの最上位の仮想ホストを使用します。

したがって、デフォルトの仮想ホストは dispatcher.any ファイルの最上位ファームの virtualhosts プロパティの一番上に配置する必要があります。

仮想ホストの解決の例

以下に示す dispatcher.any ファイルの例では、2 つの Dispatcher ファームを定義し、各ファームは virtualhosts プロパティを定義しています。

/farms { /myProducts { /virtualhosts { "www.mycompany.com" } /renders { /hostname "server1.myCompany.com" /port "80" } } /myCompany { /virtualhosts { "www.mycompany.com/products/*" } /renders { /hostname "server2.myCompany.com" /port "80" } } }
        

コードサンプルは、例としてのみ使用することを目的としています。

以下の表は、この例の場合に、指定された HTTP 要求がどの仮想ホストへと解決されるかを示しています。

要求 URL 解決される仮想ホスト
http://www.mycompany.com/products/gloves.html www.mycompany.com/products/*
http://www.mycompany.com/about.html www.mycompany.com

セキュアセッションの有効化 - /sessionmanagement

注意

この機能を有効にするには、/cache セクションで /allowAuthorized必ず "0" に設定してください。

レンダーファームにアクセスするためのセキュアセッションを作成して、このファーム内のページにユーザーがアクセスする際にログインが必要になるようにします。ログイン後、ユーザーはファーム内のすべてのページにアクセスできます。閉じられたユーザーグループ(CUG)でのこの機能の使用については、閉じられたユーザーグループの作成を参照してください。

/sessionmanagement プロパティは /farms のサブプロパティです。

注意

Web サイトのセクションによってアクセス要件が異なる場合は、複数のファームを定義する必要があります。

/sessionmanagement には、いくつかのサブパラメーターがあります。

/directory(必須)

セッション情報を格納するディレクトリ。指定したディレクトリが存在しない場合は作成されます。

/encode(オプション)

セッション情報のエンコーディング方法。md5 アルゴリズムを使用した暗号化には "md5" を、16 進エンコーディングには "hex" を使用します。セッションデータを暗号化すると、ファイルシステムにアクセスできるユーザーでも、セッション内容を読み取れなくなります。デフォルトは "md5" です。

/header(オプション)

認証情報を格納する HTTP ヘッダーまたは cookie の名前。HTTP ヘッダーに情報を格納する場合は、HTTP:<header-name> を適用します。cookie に情報を格納する場合は、Cookie:<header-name> を適用します。指定しない場合、HTTP:authorization が適用されます。

/timeout(オプション)

最後の使用から、セッションのタイムアウトまでの秒数。指定がない場合は "800" が適用され、ユーザーからの最後の要求から約 13 分でセッションがタイムアウトします。

設定例を次に示します。

/sessionmanagement { /directory "/usr/local/apache/.sessions" /encode "md5" /header "HTTP:authorization" /timeout "800" }
        

コードサンプルは、例としてのみ使用することを目的としています。

ページレンダラーの定義 - /renders

/renders プロパティは、ドキュメントをレンダリングするために Dispatcher が要求を送信する URL を定義します。次の /renders セクションの例では、レンダリングのために単一の AEM インスタンスを識別しています。

/renders { /myRenderer { # レンダラーのホスト名または IP /hostname "aem.myCompany.com" # レンダラーのポート /port "4503" # 接続のタイムアウト(ミリ秒単位)、"0"(デフォルト)は無期限で待機 /timeout "0" } }
        

コードサンプルは、例としてのみ使用することを目的としています。

次の /renders セクションの例では、Dispatcher と同じコンピューター上で動作する AEM インスタンスを識別しています。

/renders { /myRenderer { /hostname "127.0.0.1" /port "4503" } }
        

コードサンプルは、例としてのみ使用することを目的としています。

次の /renders セクションの例では、2 つの AEM インスタンス間で平等にレンダリング要求を分配しています。

/renders { /myFirstRenderer { /hostname "aem.myCompany.com" /port "4503" } /mySecondRenderer { /hostname "127.0.0.1" /port "4503" } }
        

コードサンプルは、例としてのみ使用することを目的としています。

レンダーのオプション

/timeout

AEM インスタンスにアクセスする接続タイムアウトをミリ秒単位で指定します。デフォルトは "0" で、Dispatcher は無制限に待機します。

/receiveTimeout

応答が返るまでに許容される時間をミリ秒単位で指定します。デフォルトは "600000" で、Dispatcher は 10 分間待機します。"0" に設定すると、タイムアウトが完全になくなります。
応答ヘッダーの解析中にタイムアウトに達した場合は、HTTP ステータス 504(Bad Gateway)が返されます。応答本文の読み取り中にタイムアウトに達した場合は、Dispatcher は不完全な応答をクライアントに返しますが、作成されたキャッシュファイルがあれば削除します。

/ipv4

レンダーの IP アドレスを取得するために Dispatcher が getaddrinfo 関数(IPv6 用)を使用するか gethostb name 関数(IPv4 用)を使用するかを指定します。値 0 を指定すると、getaddrinfo が使用されます。値 1 を指定すると、gethostbyname が使用されます。デフォルト値は 0 です。

getaddrinfo 関数は、IP アドレスのリストを返します。Dispatcher は、TCP/IP 接続を確立するまで、そのアドレスのリストを繰り返します。したがって、常に同じ順序で IP アドレスのリストを返す getaddrinfo 関数に応じてレンダーホスト名が複数の IP アドレスおよびホストと関連付けられている場合は、ipv4 プロパティが重要になります。このような状況では、Dispatcher が接続する IP アドレスがランダムになるように、gethostbyname 関数を使用してください。

Amazon Elastic Load Balancing(ELB)は、同じ順序になる可能性がある IP アドレスのリストを使用して、getaddrinfo に応答するサービスです。

コンテンツへのアクセスの設定 - /filter

Dispatcher が受け入れる HTTP 要求を指定するには、/filter セクションを使用します。それ以外のすべての要求は、エラーコード 404(ページが見つかりません)で Web サーバーに返送されます。/filter セクションが存在しない場合は、すべての要求が受け入れられます。

注意:statfile に対する要求は常に拒否されます。

注意

Dispatcher を使用してアクセスを制限する場合の詳しい考慮事項については、セキュリティチェックリストを参照してください。

/filter セクションは、HTTP 要求の要求行部分のパターンに応じてコンテンツへのアクセスを拒否または許可する一連のルールで構成されます。/filter セクションに対しては、ホワイトリスト戦略を使用してください。

  • まず、すべての要素へのアクセスを拒否します。
  • 必要に応じて、コンテンツへのアクセスを許可します。

フィルターの定義

/filter セクションの各アイテムには、要求行の特定の要素または要求行全体と照合するタイプとパターンが含まれます。各フィルターには、次のアイテムを含めることができます。

  • タイプ:/type は、パターンに一致する要求へのアクセスを許可するか、拒否するかを示します。値は、allowまたは deny のどちらかです。
  • 要求行の要素:/method/url/query または /protocol と、HTTP 要求の要求行の特定部分に応じて要求をフィルタリングするためのパターンを含めます。要求行全体ではなく、要求行の要素に対してフィルタリングすることをお勧めします。
  • glob プロパティ:HTTP 要求の要求行全体と照合するには、/glob プロパティを使用します。

/glob プロパティについて詳しくは、glob プロパティのパターンのデザインを参照してください。/glob プロパティでのワイルドカード文字の使用ルールも、要求行の要素を照合するためのパターンに適用されます。

メモ

機能パック NPR-6365 には、フィルター設定とログ機能に関するいくつかの機能強化が導入されています。

これらの機能を利用するには、アドビのサポートチームにお問い合わせください。

HTTP 要求の要求行部分

HTTP/1.1 では、要求行を次のように定義しています。

Method Request-URI HTTP-Version<CRLF>

<CRLF> 文字は、キャリッジリターンとそれに続くラインフィードを表します。次の例は、クライアントが Geometrixx-Outdoors サイトの英語ページを要求したときに受信する要求行です。

GET /content/geometrixx-outdoors/en.html HTTP.1.1<CRLF>

パターンは、要求行の空白文字と <CRLF> 文字を考慮する必要があります。

サンプルフィルター:すべて拒否

次のサンプルのフィルターセクションによって、Dispatcher がすべてのファイルに対する要求を拒否します。すべてのファイルへのアクセスを拒否してから、特定の領域へのアクセスを許可してください。 

/0001 { /glob "*" /type "deny" }
        

コードサンプルは、例としてのみ使用することを目的としています。

明示的に拒否された領域への要求に対して、「404 error code (page not found)」が返されます。

サンプルフィルター:特定の領域へのアクセスを拒否

フィルターを使用して、サンプルの ASP ページの各種要素と、パブリッシュインスタンス内の機密領域へのアクセスを拒否することもできます。次のフィルターは、ASP ページへのアクセスを拒否するものです。

/0002 { /type "deny" /url "*.asp" }
        

コードサンプルは、例としてのみ使用することを目的としています。

サンプルフィルター:POST 要求の有効化

次のサンプルフィルターを使用して、POST メソッドでフォームデータを送信できます。

/filter { /0001 { /glob "*" /type "deny" } /0002 { /type "allow" /method "POST" /url "/content/[.]*.form.html" } }
        

コードサンプルは、例としてのみ使用することを目的としています。

サンプルフィルター:ワークフローコンソールへのアクセスを許可

次の例は、Workflow コンソールへの外部アクセスを拒否するためのフィルターです。

/filter { /0001 { /glob "*" /type "deny" } /0002 { /type "allow" /url "/libs/cq/workflow/content/console*" } }
        

コードサンプルは、例としてのみ使用することを目的としています。

パブリッシュインスタンスで Web アプリケーションコンテキスト(例えば publish)を使用する場合は、このコンテキストをフィルター定義に追加できます。

/0003   { /type "deny"  /url "/publish/libs/cq/workflow/content/console/archive*"  }
        

コードサンプルは、例としてのみ使用することを目的としています。

制限された領域内の単独のページにアクセスする必要がある場合は、そのページへのアクセスを許可できます。例えば、ワークフローコンソール内の「アーカイブ」タブへのアクセスを許可する場合は、次のセクションを追加します。

/0004 { /type "allow" /url "/libs/cq/workflow/content/console/archive*" }
        

コードサンプルは、例としてのみ使用することを目的としています。

メモ

複数のフィルターパターンを 1 つの要求に適用した場合は、最後に適用されたフィルターパターンが有効になります。

サンプルフィルター:正規表現の使用

このフィルターは、ここで単一引用符の間に定義されている正規表現を使用して、非公開のコンテンツディレクトリで拡張子を有効にします。

/005  {  /type "allow" /extension '(css|gif|ico|js|png|swf|jpe?g)' }
        

コードサンプルは、例としてのみ使用することを目的としています。

サンプルフィルター:要求 URL の追加要素のフィルタリング

NPR-6365 に導入された機能強化の 1 つが、要求 URL の追加要素のフィルタリング機能です。導入された新しい要素には、次のものがあります。

  • パス
  • セレクター
  • 拡張子
  • サフィックス

これらは、それぞれ /path/selectors/extension および /suffix という同じ名前のプロパティをフィルタリングルールに追加することによって、設定できます。

それぞれ path、selector および extensions に対するフィルターを使用して、/content パスからのコンテンツの取得をブロックするルールのサンプルを以下に示します。

/006 {
        /type "deny"
        /path "/content"
        /selectors '(feed|rss|pages|languages|blueprint|infinity|tidy)'
        /extension '(json|xml|html)'
        }
        

コードサンプルは、例としてのみ使用することを目的としています。

サンプルの /filter セクション

Dispatcher を設定する際は、できる限り外部アクセスを制限してください。次の例では、外部の訪問者に最小限のアクセス権を付与します。

  • /content
  • デザインなどのその他のコンテンツおよびクライアントライブラリ。次のようなものがあります。
    • /etc/designs/default*
    • /etc/designs/mydesign*

フィルターを作成したら、ページアクセスをテストして、AEM インスタンスがセキュアであることを確認します。

以下の dispatcher.any ファイルの /filter セクションは、Dispatcher 設定ファイルで基礎として使用できます。

このサンプルは、Dispatcher に付属するデフォルトの設定ファイルをベースとしており、実稼動環境での使用例の役割を果たすことを目的としています。先頭に # が付いているアイテムは、非アクティブ化された(コメントアウトされた)アイテムです。これらのアイテムをアクティブ化する(該当する行の # を削除する)と、セキュリティに影響を与える可能性があるので、注意してください。

すべてに対するアクセスを拒否してから、特定の(限られた)要素へのアクセスを許可してください。

  /filter
      {
      # Deny everything first and then allow specific entries
      /0001 { /type "deny" /glob "*" }
      
      # Open consoles
#     /0011 { /type "allow" /url "/admin/*"  }  # allow servlet engine admin
#     /0012 { /type "allow" /url "/crx/*"    }  # allow content repository
#     /0013 { /type "allow" /url "/system/*" }  # allow OSGi console
        
      # Allow non-public content directories
#     /0021 { /type "allow" /url "/apps/*"   }  # allow apps access
#     /0022 { /type "allow" /url "/bin/*"    }
      /0023 { /type "allow" /url "/content*" }  # disable this rule to allow mapped content only
      
#     /0024 { /type "allow" /url "/libs/*"   }
#     /0025 { /type "deny"  /url "/libs/shindig/proxy*" } # if you enable /libs close access to proxy

#     /0026 { /type "allow" /url "/home/*"   }
#     /0027 { /type "allow" /url "/tmp/*"    }
#     /0028 { /type "allow" /url "/var/*"    }

      # Enable extensions in non-public content directories, using a regular expression
      /0041
        {
        /type "allow"
        /extension '(css|gif|ico|js|png|swf|jpe?g)'
        }

      # Enable features 
      /0062 { /type "allow" /url "/libs/cq/personalization/*"  }  # enable personalization

      # Deny content grabbing, on all accessible pages, using regular expressions
      /0081
        {
        /type "deny"
        /selectors '((sys|doc)view|query|[0-9-]+)'
        /extension '(json|xml)'
        }
      # Deny content grabbing for /content
      /0082
        {
        /type "deny"
        /path "/content"
        /selectors '(feed|rss|pages|languages|blueprint|infinity|tidy)'
        /extension '(json|xml|html)'
        }

#     /0087 { /type "allow" /method "GET" /extension 'json' "*.1.json" }  # allow one-level json requests
}
        

コードサンプルは、例としてのみ使用することを目的としています。

メモ

Apache と共に使用する場合は、Dispatcher モジュールの DispatcherUseProcessedURL プロパティに応じてフィルター URL パターンをデザインしてください(「Apache Web サーバー - Dispatcher 用の Apache Web サーバーの設定」を参照)。

メモ

ダイナミックメディアに関するフィルター 0030 および 0031 は、AEM 6.0 以上に適用できます。

アクセスを拡張する場合は、以下の推奨事項について検討します。

  • CQ バージョン 5.4 以前を使用している場合は、/admin への外部アクセスを常に完全に無効にしてください。
  • /libs 内にあるファイルへのアクセスを許可する場合は、注意が必要です。アクセスは、個別に許可する必要があります。
  • 複製の設定が表示されないように、この設定へのアクセスを拒否してください。
    • /etc/replication.xml*
    • /etc/replication.infinity.json*
  • Google Gadgets のリバースプロキシへのアクセスを拒否します。
    • /libs/opensocial/proxy*

インストールによっては、/libs/apps またはその他の場所(使用可能にする必要があります)の下に、追加のリソースが存在する場合があります。外部からアクセスされるリソースを判別するための方法として、access.log ファイルを使用することができます。

注意

コンソールおよびディレクトリへのアクセスによって、実稼動環境でセキュリティのリスクが発生する可能性があります。このようなアクセスに関する正当な理由が明確でない場合は、これらのエントリを非アクティブ化(コメントアウト)のままにしておいてください。

注意

パブリッシュ環境でレポートを使用する場合は、外部の訪問者が /etc/reports にアクセスできないように、Dispatcher を設定してください。

クエリ文字列の制約

Dispatcher バージョン 4.1.5 以降では、/filter セクションを使用してクエリ文字列を制約します。allow フィルター要素を使用して、クエリ文字列を明示的に許可し、一般的な許可を除外することを強くお勧めします。

1 つのエントリに glob、または methodurlqueryversion の組み合わせを含めることができますが、両方を含めることはできません。以下の例では、/etc ノードに解決される URL に対してクエリ文字列 a=* を許可し、その他すべてのクエリ文字列を拒否しています。

/filter {
 /0001 { /type "deny" /method "POST" /url "/etc/*" }
 /0002 { /type "allow" /method "GET" /url "/etc/*" /query "a=*" }
}
        

コードサンプルは、例としてのみ使用することを目的としています。

メモ

ルールに /query が含まれる場合は、クエリ文字列を含む要求だけでなく、指定されたクエリパターンも照合します。

上記の例で、クエリ文字列を持たない /etc への要求も許可する場合は、以下のルールが必要になります。

/filter {
 /0001 { /type "deny" /method “*" /url "/path/*" }
 /0002 { /type "allow" /method "GET" /url "/path/*" }
 /0003 { /type “deny" /method "GET" /url "/path/*" /query "*" }
 /0004 { /type "allow" /method "GET" /url "/path/*" /query "a=*" }
}

Dispatcher のセキュリティのテスト

Dispatcher のフィルターは、AEM パブリッシュインスタンス上の以下のページおよびスクリプトへのアクセスをブロックする必要があります。Web ブラウザーを使用して、サイト訪問者として以下のページを開こうと試み、コード 404 が返されることを確認してください。それ以外の結果が得られた場合は、フィルターを調整してください。

/content/add_valid_page.html?debug=layout に対しては、通常のページレンダリングが表示されます。

  • /admin
  • /system/console
  • /dav/crx.default
  • /crx
  • /bin/crxde/logs
  • /jcr:system/jcr:versionStorage.json
  • /_jcr_system/_jcr_versionStorage.json
  • /libs/wcm/core/content/siteadmin.html
  • /libs/collab/core/content/admin.html
  • /libs/cq/ui/content/dumplibs.html
  • /var/linkchecker.html
  • /etc/linkchecker.html
  • /home/users/a/admin/profile.json
  • /home/users/a/admin/profile.xml
  • /libs/cq/core/content/login.json
  • /content/../libs/foundation/components/text/text.jsp
  • /content/.{.}/libs/foundation/components/text/text.jsp
  • /apps/sling/config/org.apache.felix.webconsole.internal.servlet.OsgiManager.config/jcr%3acontent/jcr%3adata
  • /libs/foundation/components/primary/cq/workflow/components/participants/json.GET.servlet
  • /content.pages.json
  • /content.languages.json
  • /content.blueprint.json
  • /content.-1.json
  • /content.10.json
  • /content.infinity.json
  • /content.tidy.json
  • /content.tidy.-1.blubber.json
  • /content/dam.tidy.-100.json
  • /content/content/geometrixx.sitemap.txt 
  • /content/add_valid_page.query.json?statement=//*
  • /content/add_valid_page.qu%65ry.js%6Fn?statement=//*
  • /content/add_valid_page.query.json?statement=//*[@transportPassword]/(@transportPassword%20|%20@transportUri%20|%20@transportUser)
  • /content/add_valid_path_to_a_page/_jcr_content.json
  • /content/add_valid_path_to_a_page/jcr:content.json
  • /content/add_valid_path_to_a_page/_jcr_content.feed
  • /content/add_valid_path_to_a_page/jcr:content.feed
  • /content/add_valid_path_to_a_page/pagename._jcr_content.feed
  • /content/add_valid_path_to_a_page/pagename.jcr:content.feed
  • /content/add_valid_path_to_a_page/pagename.docview.xml
  • /content/add_valid_path_to_a_page/pagename.docview.json
  • /content/add_valid_path_to_a_page/pagename.sysview.xml
  • /etc.xml
  • /content.feed.xml
  • /content.rss.xml
  • /content.feed.html
  • /content/add_valid_page.html?debug=layout

端末またはコマンドプロンプトで次のコマンドを発行して、匿名での書き込みアクセスが可能かどうかを判断します。ノードにはデータを書き込みできません。

curl -X POST "http://anonymous:anonymous@hostname:port/content/usergenerated/mytestnode"

端末またはコマンドプロンプトで次のコマンドを発行して、Dispatcher キャッシュの無効化を試み、コード 404 の応答を受信することを確認します。

curl -H "CQ-Handle: /content" -H "CQ-Path: /content" http://yourhostname/dispatcher/invalidate.cache

バニティー URL へのアクセスの有効化 - /vanity_urls

CQ または AEM ページ用に設定されているバニティー URL へのアクセスを有効にするように Dispatcher を設定します。

バニティー URL へのアクセスが有効になると、レンダーインスタンス上で実行されているサービスを Dispatcher が定期的に呼び出して、バニティー URL のリストを取得します。Dispatcher がこのリストをローカルファイルに保存します。ページの要求が /filter セクションのフィルターによって拒否されると、Dispatcher はバニティー URL のリストを調べます。拒否された URL がリストにある場合、Dispatcher はバニティー URL へのアクセスを許可します。

バニティー URL へのアクセスを有効にするには、以下の例のような /vanity_urls セクションを /farms セクションに追加します。

 /vanity_urls {
      /url "/libs/granite/dispatcher/content/vanityUrls.html"
      /file "/tmp/vanity_urls"
      /delay 300
 }
        

コードサンプルは、例としてのみ使用することを目的としています。

/vanity_urls セクションには、以下のプロパティが含まれます。

  • /url:レンダーインスタンス上で実行されているバニティー URL サービスへのパス。このプロパティの値は、"/libs/granite/dispatcher/content/vanityUrls.html" である必要があります。
  • /file:Dispatcher がバニティー URL のリストを保存するローカルファイルへのパス。Dispatcher がこのファイルに対する書き込みアクセス権を持っていることを確認してください。
  • /delay:バニティー URL サービスの呼び出し間隔(秒単位)。

 

メモ

使用するレンダーが AEM バージョン 6.2 以前または CQ のいずれかのバージョンのインスタンスである場合は、バニティー URL サービスをインストールするために VanityURLS-Components パッケージをインストールする必要があります(パッケージ共有へのサインインを参照)。

バニティー URL へのアクセスを有効にするには、以下の手順を実行します。

  1. 使用するレンダーサービスが AEM 6.2 インスタンスまたは以前のバージョンの AEM または CQ である場合は、パブリッシュインスタンス上に com.adobe.granite.dispatcher.vanityurl.content パッケージをインストールします。

  2. AEM または CQ ページ向けに設定したバニティー URL ごとに、/filter 設定がその URL を拒否していることを確認します。必要に応じて、この URL を拒否するフィルターを追加します。

  3. /farms の下に /vanity_urls セクションを追加します。

  4. Apache Web サーバーを再起動します。

シンジケーション要求の転送 - /propagateSyndPost

シンジケーション要求は、通常、Dispatcher のみを対象としているので、デフォルトではレンダラー(AEM インスタンスなど)に送信されません。

必要に応じて、シンジケーション要求を Dispatcher に転送するために、/propagateSyndPost プロパティを "1" に設定します。設定する場合、フィルターセクションで POST 要求が拒否されていないことを確認する必要があります。

Dispatcher キャッシュの設定 - /cache

/cache セクションが、Dispatcher によるドキュメントのキャッシュ方法を制御します。次のいくつかのサブプロパティを設定して、キャッシュ戦略を実装します。

 

  • /docroot
  • /statfile
  • /serveStaleOnError
  • /allowAuthorized
  • /rules
  • /statfileslevel 
  • /invalidate
  • /invalidateHandler
  • /allowedClients
  • /ignoreUrlParams
  • /headers

キャッシュセクションの例を次に示します。

/cache { /docroot "/opt/dispatcher/cache" /statfile "/tmp/dispatcher-website.stat" /allowAuthorized "0" /rules { # キャッシュされるファイルのリスト } /invalidate { # 自動無効化されるファイルのリスト } }
        

コードサンプルは、例としてのみ使用することを目的としています。

メモ

権限を区別するキャッシュについては、セキュリティ保護されたコンテンツのキャッシュをお読みください。

キャッシュディレクトリの指定

/docroot プロパティは、キャッシュされたファイルを保存するディレクトリを識別します。

メモ

Dispatcher と Web サーバーが同じファイルを処理できるよう、この値は Web サーバーのドキュメントルートとまったく同じパスの必要があります。
Dispatcher のキャッシュファイルが使用されると、Web サーバーは適切なステータスコードを配信します。そのため、キャッシュファイルを見つけられることが重要になります。

複数のファームを使用する場合は、ファームごとに異なるドキュメントルートを使用する必要があります。

statfile の命名

/statfile プロパティは、statfile として使用するファイルを識別します。Dispatcher は、このファイルを使用して、最も新しいコンテンツ更新時刻を登録します。statfile には、Web サーバー上の任意のファイルを指定できます。

statfile にはコンテンツがありません。コンテンツが更新されると、Dispatcher がタイムスタンプを更新します。デフォルトの statfile 名は .stat で、ドキュメントルートに保存されます。Dispatcher は、statfile へのアクセスをブロックします。

メモ

/statfileslevel が設定されている場合、Dispatcher は /statfile プロパティを無視し、名前として .stat を使用します。

エラー発生時の古くなったドキュメントの返送

/serveStaleOnError プロパティは、レンダーサーバーがエラーを返した場合に Dispatcher が無効になったドキュメントを返すかどうかを制御します。デフォルトでは、statfile にアクセスし、キャッシュされたコンテンツが無効になると、Dispatcher は次回要求時にキャッシュされたコンテンツを削除します。

/serveStaleOnError が "1" に設定されている場合は、レンダーサーバーが成功応答を返さない限り、Dispatcher は無効になったコンテンツをキャッシュから削除しません。AEM からの応答 5xx または接続タイムアウトによって、Dispatcher は期限切れのコンテンツを返し、HTTP ステータス 111(再検証失敗)で応答します。

 

認証使用時のキャッシュ

/allowAuthorized プロパティは、以下のいずれかの認証情報を含む要求をキャッシュするかどうかを制御します。

  • authorization ヘッダー。
  • authorization という cookie。
  • login-token という cookie。

 

 

デフォルトでは、この認証情報を含む要求はキャッシュされません。キャッシュされたドキュメントをクライアントに返す場合、認証は実行されないからです。この設定によって、Dispatcher は、必要な権限を持たないユーザーにキャッシュされたドキュメントを返さなくなります。

ただし、認証済みドキュメントのキャッシュを要件によって承認する場合は、/allowAuthorized を "1" に設定します。

/allowAuthorized "1"

 

メモ

セッション管理(/sessionmanagement プロパティを使用)を有効にするには、/allowAuthorized プロパティを "0" に設定する必要があります。

キャッシュするドキュメントの指定

/rules プロパティは、ドキュメントパスに応じてキャッシュされるドキュメントを制御します。/rules プロパティにかかわらず、Dispatcher は以下の状況にあるドキュメントをキャッシュしません。

  • HTTP メソッドが GET でない場合。
    他の一般的なメソッドとして、フォームデータに対する POST メソッド、HTTP ヘッダーに対する HEAD メソッドがあります。
  • 要求 URI に疑問符(「?」)が含まれている場合。
    疑問符は通常、キャッシュの必要がない、検索結果などの動的ページを指します。
  • ファイル拡張子が不明の場合。
    Web サーバーでドキュメントのタイプ(MIME タイプ)を判別するために、拡張子が必要です。
  • 認証ヘッダー(設定可)が設定されている場合。
  • AEM インスタンスが以下のヘッダーで応答する場合。
    • no-cache
    • no-store
    • must-revalidate

/rules プロパティの各アイテムには、glob パターンとタイプが含まれます。

  • glob パターンは、ドキュメントのパスの照合に使用されます。
  • タイプは、glob パターンに一致するドキュメントをキャッシュするかどうかを示します。値は、allow(ドキュメントをキャッシュする)または deny(ドキュメントを常にレンダリングする)のどちらかです。 

以上のルールで除外されるもの以外にも動的ページがない場合、Dispatcher ですべてのドキュメントをキャッシュできます。この場合、ルールセクションは次のようになります。

/rules { /0000 { /glob "*" /type "allow" } }
        

コードサンプルは、例としてのみ使用することを目的としています。

glob プロパティについて詳しくは、glob プロパティのパターンのデザインを参照してください。

ページ内に動的なセクション(ニュースアプリケーションなど)や、非公開のユーザーグループで使用するセクションがある場合は、以下のように例外を定義できます。

メモ

キャッシュされたページでユーザー権限をチェックできないので、非公開のユーザーグループはキャッシュできません。

/rules { /0000 { /glob "*" /type "allow" } /0001 { /glob "/en/news/*" /type "deny" } /0002 { /glob "*/private/*" /type "deny" } }
        

コードサンプルは、例としてのみ使用することを目的としています。

圧縮(Apache 1.3 のみ)

Apache 1.3 Web サーバーでは、キャッシュされたドキュメントを圧縮することができます。クライアントから要求された場合は、Apache から圧縮形式のドキュメントを返すことができます。

メモ

現在は gzip フォーマットのみがサポートされています。

Apache 1.3 でのみ使用できます。

次のルールによって、すべてのドキュメントが圧縮形式でキャッシュされます。クライアントには、非圧縮形式でも圧縮形式でも返すことができます。

/rules { /rulelabel { /glob "*" /type "allow" /compress "gzip" } }
        

コードサンプルは、例としてのみ使用することを目的としています。

フォルダーレベルでのファイルの無効化

/statfileslevel プロパティを使用して、キャッシュされたファイルをパスに応じて選択的に無効化します。

  • Dispatcher は、ドキュメントルートフォルダーから指定したレベルまでの各フォルダーに .stat ファイルを作成します。ドキュメントルートはレベル 0 です。
  • ファイルが更新されると、Dispatcher は statfileslevel にあるファイルパス上のフォルダーを探し、そのフォルダー下にあるすべてのファイルを無効化します。

すべてのファイルを無効化する代わりに、更新されたファイルと同じパス上にあるファイルのみがキャッシュされます。 

例えば、多言語 Web サイトが /content/myWebsite/xx/topics という構造を使用していて、xx が各言語の 2 文字の識別子を表しているとします。/statfileslevel が 3 の場合(/statfileslevel = "3")、.stat ファイルは以下のフォルダーに作成されます。

  • /content
  • /content/myWebsite
  • /content/myWebsite/xx(各言語フォルダーに .stat ファイルが含まれます)

/content/myWebsite/fr/topics フォルダー内のファイルがアクティベートされると、/content/myWebsite/fr の下の .stat ファイルにアクセスされます。fr フォルダー内のすべてのファイルが無効化されます。

注意:/statfileslevel プロパティの値を指定した場合、/statfile プロパティは無視されます。

キャッシュされたファイルの自動無効化

/invalidate プロパティは、コンテンツが更新されたときに自動的に無効化されるドキュメントを定義します。

自動無効化を使用する場合、Dispatcher はキャッシュされたファイルをコンテンツの更新後に削除しませんが、次回要求されたときにその有効性を確認します。自動無効化されない、キャッシュ内のドキュメントは、コンテンツの更新によって明示的に削除されるまでキャッシュに残ります。

自動無効化は通常、HTML ページに対して使用されます。多くの場合、HTML ページには他のページへのリンクが含まれるので、コンテンツの更新がページに影響を与えるかどうかを判断することが困難です。コンテンツの更新時にすべての関連ページが無効化されるようにするには、すべての HTML ページを自動的に無効化します。以下の設定は、すべての HTML ページを無効化します。

/invalidate { /0000 { /glob "*" /type "deny" } /0001 { /glob "*.html" /type "allow" } }
        

コードサンプルは、例としてのみ使用することを目的としています。

glob プロパティについて詳しくは、glob プロパティのパターンのデザインを参照してください。

この設定によって、/content/geometrixx/en.html ファイルがアクティベートされると、以下のアクティビティが発生します。

  • パターン en.* を持つすべてのファイルが /content/geometrixx/ フォルダーから削除されます。
  • /content/geometrixx/en/jcr_content フォルダーが削除されます。
  • /invalidate 設定に一致するその他すべてのファイルは、即座には削除されません。これらのファイルは、次回の要求が発生すると削除されます。この例では、/content/geometrixx.html は削除されません。/content/geometrixx.html が要求されると、削除されます。

自動生成した PDF や ZIP ファイルをダウンロード用に提供する場合は、これらのファイルも自動的に無効化する必要があります。この場合の設定例を次に示します。

/invalidate { /0000 { /glob "*" /type "deny" } /0001 { /glob "*.html" /type "allow" } /0002 { /glob "*.zip" /type "allow" } /0003 { /glob "*.pdf" /type "allow" } }
        

コードサンプルは、例としてのみ使用することを目的としています。

Adobe Analytics との AEM 統合によって、Web サイトの analytics.sitecatalyst.js ファイルに設定データが提供されます。Dispatcher に付属のサンプルの dispatcher.any ファイルには、このファイル用として次の無効化ルールが含まれています。

{
   /glob "*/analytics.sitecatalyst.js"  /type "allow"
}
        

コードサンプルは、例としてのみ使用することを目的としています。

カスタム無効化スクリプトの使用

/invalidateHandler プロパティを使用して、Dispatcher が無効化要求を受信するたびに呼び出されるスクリプトを定義できます。

このスクリプトは、以下の引数と共に呼び出されます。

  • Handle
    無効化するコンテンツのパス
  • Action
    レプリケーションアクション(Activate、Deactivate)
  • Action Scope
    レプリケーションアクションの範囲(ヘッダー CQ-Action-Scope: ResourceOnly が送信されない限りは空です。詳しくは、「AEM からキャッシュされたページの無効化」を参照してください)。

このスクリプトは、他のアプリケーションに固有のキャッシュの無効化など、多種多様なユースケースを扱ったり、外部化されたページの URL とドキュメントルート内のその場所がコンテンツパスと一致しないケースを扱ったりするのに利用できます。

以下のサンプルスクリプトは、各無効化要求をファイルに記録します。

/invalidateHandler "/opt/dispatcher/scripts/invalidate.sh"
        

コードサンプルは、例としてのみ使用することを目的としています。

サンプルの無効化ハンドラースクリプト
#!/bin/bash

printf "%-15s: %s %s" $1 $2 $3>> /opt/dispatcher/logs/invalidate.log
        

コードサンプルは、例としてのみ使用することを目的としています。

キャッシュをフラッシュできるクライアントの制限

/allowedClients プロパティは、キャッシュのフラッシュを許可する特定のクライアントを定義されます。このグロビングパターンが、IP と照合されます。

以下の例の内容は次のとおりです。

  1. 任意のクライアントへのアクセスを拒否
  2. localhost へのアクセスを明示的に許可
/allowedClients { /0001 { /glob "*.*.*.*" /type "deny" } /0002 { /glob "127.0.0.1" /type "allow" } }
        

コードサンプルは、例としてのみ使用することを目的としています。

glob プロパティについて詳しくは、glob プロパティのパターンのデザインを参照してください。

注意

/allowedClients を定義することをお勧めします。

定義しない場合は、任意のクライアントからキャッシュ消去を呼び出せますが、繰り返しおこなうとサイトのパフォーマンスに深刻な影響を及ぼす場合があります。

URL パラメーターの無視

ignoreUrlParams セクションでは、ページをキャッシュするかキャッシュから提供するかを判断するときにどの URL パラメーターを無視するかを定義します。

  • 要求 URL に含まれるすべてのパラメーターを無視する場合は、ページがキャッシュされます。
  • 要求 URL に含まれる 1 つ以上のパラメーターを無視しない場合は、ページはキャッシュされません。

あるページに対してパラメーターを無視する場合は、そのページが初めて要求されたときにページがキャッシュされます。そのページに対する以降の要求には、要求内のパラメーターの値にかかわらず、キャッシュされたページが返されます。 

無視するパラメーターを指定するには、ignoreUrlParams プロパティに glob ルールを追加します。

  • パラメーターを無視するには、そのパラメーターを許可する glob プロパティを作成します。 
  • ページがキャッシュされないようにするには、そのパラメーターを拒否する glob プロパティを作成します。

次の例では、Dispatcher が "q" パラメーターを無視するので、q パラメーターを含む要求 URL はキャッシュされます。

/ignoreUrlParams
{
    /0001 { /glob "*" /type "deny" }
    /0002 { /glob "q" /type "allow" }
}
        

コードサンプルは、例としてのみ使用することを目的としています。

例の ignoreUrlParams 値を使用すると、q パラメーターは無視されるので、次の HTTP 要求によってページがキャッシュされます。

GET /mypage.html?q=5
        

コードサンプルは、例としてのみ使用することを目的としています。

例の ignoreUrlParams 値を使用すると、p パラメーターは無視されないので、次の HTTP 要求によってページがキャッシュされません。

GET /mypage.html?q=5&p=4

        

コードサンプルは、例としてのみ使用することを目的としています。

glob プロパティについて詳しくは、glob プロパティのパターンのデザインを参照してください。

HTTP 応答ヘッダーのキャッシュ

メモ

この機能は、Dispatcher のバージョン 4.1.11 で利用できます。

/headers プロパティを使用して、Dispatcher がキャッシュする HTTP ヘッダータイプを定義できます。

デフォルト設定から除外されるものを以下に示します。

/cache {
  ...
  /headers {
    "Content-Disposition"
    "Content-Type"
    "X-Content-Type-Options"
    "Last-Modified"
  }
}

        

コードサンプルは、例としてのみ使用することを目的としています。

時間に基づくキャッシュの無効化の設定 - /enableTTL

設定した場合、enableTTL プロパティはバックエンドからの応答ヘッダーを評価し、Cache-Control max-age または Expires 日付が含まれる場合は、有効期限と同じ変更時刻を持つ予備の空のファイルがキャッシュファイルの隣に作成されます。変更時刻以降にキャッシュされたファイルが要求されると、自動的にバックエンドから再要求されます。

次の行を dispatcher.any ファイルに追加することで、この機能を有効にできます。

/enableTTL "1"
        

コードサンプルは、例としてのみ使用することを目的としています。

メモ

この機能は、Dispatcher バージョン 4.1.11 以降で利用できます。

ロードバランシングの設定 - /statistics

/statistics セクションは、Dispatcher が各レンダーの応答性のスコアを付けるファイルのカテゴリを定義します。Dispatcher は、このスコアを使用して、要求を送信するレンダーを決定します。

作成したカテゴリごとに glob パターンを定義します。Dispatcher は、要求されたコンテンツの URI とこれらのパターンを比較して、要求されたコンテンツのカテゴリを決定します。

  • カテゴリの順序によって、URI と比較する順序が決まります。
  • URI と一致する最初のカテゴリパターンがファイルのカテゴリになります。それ以上のカテゴリパターンは評価されません。 

Dispatcher は、最大 8 個の統計カテゴリをサポートします。9 個以上のカテゴリを定義した場合は、最初の 8 個のカテゴリのみが使用されます。

レンダーの選択

レンダリングされたページを要求するたびに、Dispatcher は以下のアルゴリズムを使用してレンダーを選択します。

  1. 要求の renderid cookie にレンダー名が格納されている場合、Dispatcher はそのレンダーを使用します。
  2. 要求に renderid cookie が含まれていない場合、Dispatcher はレンダー統計を比較します。
    1. Dispatcher は、要求 URI のカテゴリを判断します。
    2. Dispatcher は、そのカテゴリで最も応答スコアが低いレンダーを判断して、そのレンダーを選択します。
  3. まだレンダーが選択されていない場合は、リストの先頭のレンダーを使用します。

レンダーのカテゴリのスコアは、以前の応答時間と Dispatcher が以前試みた接続の失敗および成功に基づきます。試行ごとに、要求された URI のカテゴリのスコアが更新されます。

メモ

ロードバランシングを使用しない場合は、このセクションを省略できます。

統計カテゴリの定義

レンダーを選択するための統計を保持するドキュメントのタイプごとにカテゴリを定義します。/statistics セクションには、/categories セクションが含まれます。カテゴリを定義するには、/categories セクションの下に次の形式の行を追加します。

/name { /glob "pattern"}

カテゴリの name は、ファームに対して一意である必要があります。pattern については、「glob プロパティのパターンのデザイン」の節で説明します。

URI のカテゴリを判断するために、Dispatcher は一致が見つかるまで URI と各カテゴリのパターンを比較します。Dispatcher は、リストの先頭のカテゴリから始め、順序に従って比較を続けます。したがって、より具体的なパターンを持つカテゴリを先頭に配置してください。

例えば、Dispatcher のデフォルトの dispatcher.any ファイルには、1 つの HTML カテゴリと 1 つの others カテゴリが定義されています。HTML カテゴリのほうが具体的なので、先頭に配置されています。

/statistics { /categories { /html { /glob "*.html" } /others { /glob "*" } } }
        

コードサンプルは、例としてのみ使用することを目的としています。

以下の例には、検索ページ用のカテゴリも含まれています。

/statistics { /categories { /search { /glob "*search.html" } /html { /glob "*.html" } /others { /glob "*" } } }
        

コードサンプルは、例としてのみ使用することを目的としています。

Dispatcher 統計へのサーバー使用不可能状態の反映

/unavailablePenalty プロパティは、レンダーへの接続が失敗した場合にレンダー統計に適用される時間(0.1 秒単位)を設定します。Dispatcher は、要求された URI に一致する統計カテゴリにこの時間を追加します。

例えば、AEM が実行されていない(したがってリッスンしていない)か、ネットワーク関連の問題が発生したので、指定したホスト名およびポートへの TCP/IP 接続を確立できない場合にペナルティが適用されます。

/unavailablePenalty プロパティは、/farm セクション(/statistics セクションの兄弟)の直接の子です。

/unavailablePenalty プロパティが存在しない場合は、値 "1" が使用されます。

/unavailablePenalty "1"
        

コードサンプルは、例としてのみ使用することを目的としています。

スティッキー接続フォルダーの識別 - /stickyConnectionsFor

/stickyConnectionsFor プロパティは、スティッキードキュメントを格納する 1 つのフォルダーを定義します。このフォルダーには、URL を使用してアクセスします。Dispatcher によって、このフォルダーにある、単一のユーザーからのすべての要求が同一のレンダーインスタンスに送信されます。スティッキー接続は、すべてのドキュメントに必ず一貫したセッションデータが存在することを保証します。このメカニズムは、renderid cookie を利用しています。

次の例は、/products フォルダーへのスティッキー接続を定義しています。

/stickyConnectionsFor "/products"
        

コードサンプルは、例としてのみ使用することを目的としています。

ページが複数のコンテンツノードのコンテンツで組み立てられている場合は、コンテンツへのパスをリストする /paths プロパティを含めます。例えば、/content/image/content/video および /var/files/pdfs のコンテンツを含むページがあるとします。以下の設定を使用すると、ページ上のすべてのコンテンツに対してスティッキー接続が有効になります。

/stickyConnections {
  /paths {
    "/content/image"
    "/content/video"
    "/var/files/pdfs"
  }
}
        

コードサンプルは、例としてのみ使用することを目的としています。

レンダー接続エラーの処理

レンダーサーバーが 500 エラー、すなわち使用不可を返した場合の Dispatcher の動作を設定します。 

ヘルスチェックページの指定

/health_check プロパティを使用して、ステータスコード 500 が発生したときに確認する URL を指定します。このページもステータスコード 500 を返す場合、インスタンスは使用不可能と見なされ、再試行の前に設定可能なタイムペナルティ(/unavailablePenalty)がレンダーに適用されます。

/health_check
  {
  # Page gets contacted when an instance returns a 500
  /url "/health_check.html"
  }

        

コードサンプルは、例としてのみ使用することを目的としています。

ページ再試行遅延の指定

/retryDelay プロパティは、Dispatcher が待機する、ファームレンダーへの接続試行周期(秒単位)を設定します。周期ごとに、Dispatcher が 1 つのレンダーに対して接続を試行する最大回数は、ファーム内のレンダーの数です。

/retryDelay が明示的に定義されていない場合、Dispatcher は値 "1" を使用します。デフォルト値は、ほとんどのケースに適しています。

/retryDelay "1"
        

コードサンプルは、例としてのみ使用することを目的としています。

再試行回数の設定

/numberOfRetries プロパティは、Dispatcher がレンダーに対して実行する。接続試行周期の最大回数を設定します。この再試行回数内で Dispatcher がレンダーに接続できなかった場合、Dispatcher は失敗応答を返します。

周期ごとに、Dispatcher が 1 つのレンダーに対して接続を試行する最大回数は、ファーム内のレンダーの数です。したがって、Dispatcher が接続を試みる最大回数は、(/numberOfRetries)x(レンダー数)になります。

明示的な定義がない場合、"5" がデフォルトの値として使用されます。

/numberOfRetries "5"
        

コードサンプルは、例としてのみ使用することを目的としています。

フェイルオーバーメカニズムの使用

Dispatcher ファーム上でフェイルオーバーメカニズムを有効にして、元の要求の失敗時に異なるレンダーに要求を再送信します。フェイルオーバーを有効にすると、Dispatcher は以下の動作をおこないます。

  • レンダーへの要求が HTTP ステータス 503(UNAVAILABLE)を返した場合、Dispatcher は異なるレンダーに要求を送信します。
  • レンダーへの要求が HTTP ステータス 50x(503 以外)を返した場合、Dispatcher は health_check プロパティに設定されているページへの要求を送信します。
    • ヘルスチェックが 500(INTERNAL_SERVER_ERROR)を返した場合、Dispatcher は元の要求を異なるレンダーに送信します。
    • ヘルスチェックが HTTP ステータス 200 を返した場合、Dispatcher は最初の HTTP 500 エラーをクライアントに返します。 
フェイルオーバーを有効にするには、次の行をファーム(または Web サイト)に追加します。
/failover "1" 
        

コードサンプルは、例としてのみ使用することを目的としています。

メモ

本文を含む HTTP 要求を再試行するには、Dispatcher が Expect: 100-continue 要求ヘッダーをレンダーに送信してから、実際のコンテンツをスプールします。すると、CQSE を含む CQ 5.5 が、100(CONTINUE)またはエラーコードで即座に応答します。その他のサーブレットコンテナも、このメカニズムをサポートする必要があります。

中断エラーの無視 - /ignoreEINTR

注意

このオプションは、通常は必要ありません。このオプションを使用する必要があるのは、次のログメッセージが表示された場合だけです。

    応答の読み込み中にエラーが発生しました:システムコールが中断されました

システムコールの対象が NFS 経由でアクセスするリモートシステム上にある場合、ファイルシステムからのシステムコールはすべて EINTR で中断される可能性があります。これらのシステムコールがタイムアウトするか中断されるかは、基盤となるファイルシステムがローカルマシンにどのようにマウントされたかに基づきます。

インスタンスにそのような設定があり、ログに次のメッセージが含まれる場合は、/ignoreEINTR パラメーターを使用してください。

応答の読み込み中にエラーが発生しました:システムコールが中断されました

内部的に、Dispatcher は次のように表現できるループを使用して、リモートサーバー(AEM)からの応答を読み込みます。

while (response not finished) {
     read more data
}

このようなメッセージは、「read more data」セクションで EINTR が発生した場合に生成されることがあります。原因は、データの受信前にシグナルを受信したことです。

このような中断を無視するには、次のパラメーターを dispatcher.any(の /farms の前)に追加します。

/ignoreEINTR "1"

/ignoreEINTR"1" に設定すると、Dispatcher は応答全体が読み込まれるまでデータの読み込みを続行します。デフォルト値は 0 で、このオプションを無効にします。

glob プロパティのパターンのデザイン

Dispatcher 設定ファイルのいくつかのセクションでは、glob プロパティをクライアント要求の選択条件として使用します。glob プロパティの値は、要求されたリソースのパスやクライアントの IP アドレスなど、Dispatcher が要求の要素と比較するパターンです。例えば、/filter セクションのアイテムは、glob パターンを使用して、Dispatcher が従う、または拒否するページのパスを識別します。

glob の値にワイルドカード文字と英数字を含めて、パターンを定義することができます。ワイルドカード文字に関する説明を次の表に示します。

ワイルドカード文字 説明
*

文字列に含まれる任意の文字の 0 個以上の連続するインスタンスに一致します。一致の最後の文字は、次のどちらかの状況によって判断されます。

  • 文字列内のある文字がパターン内の次の文字に一致し、パターンの文字が以下の性質を持つ。
    • * 以外
    • ? 以外
    • リテラル文字(空白を含む)または文字クラス
  • パターンの終わりに達している。

文字クラス内のこの文字は、リテラルとして解釈されます。

*/geo*

/content/geometrixx ノードと /content/geometrixx-outdoors ノードの下にあるすべてのページに一致します。以下の HTTP 要求は、glob パターンに一致します。

  • "GET /content/geometrixx/en.html"
  • "GET /content/geometrixx-outdoors/en.html"  

*outdoors/*

/content/geometrixx-outdoors ノードの下にあるすべてのページに一致します。例えば、次の HTTP 要求は glob パターンに一致します。

  • "GET /content/geometrixx-outdoors/en.html"
?

任意の 1 文字に一致します。文字クラス外で使用します。

文字クラス内のこの文字は、リテラルとして解釈されます。

*outdoors/??/*

geometrixx-outdoors サイトのすべての言語のページに一致します。例えば、次の HTTP 要求は glob パターンに一致します。

  • "GET /content/geometrixx-outdoors/en/men.html"

次の要求は glob パターンに一致しません。

  • "GET /content/geometrixx-outdoors/en.html" 
[ および ]

文字クラスの最初と最後を定めます。

文字クラスには、1 つまたは複数の文字範囲および単一の文字を含めることができます。

ターゲット文字が文字クラス内または定義されている範囲内のいずれかの文字に一致する場合、一致が発生します。

閉じ角括弧が含まれない場合、パターンによって一致は発生しません。

*[o]men.html*

次の HTTP 要求に一致します。

  • "GET /content/geometrixx-outdoors/en/women.html"

次の HTTP 要求に一致しません。

  • "GET /content/geometrixx-outdoors/en/men.html" 

*[o/]men.html*

次の HTTP 要求に一致します。

  • "GET /content/geometrixx-outdoors/en/women.html" 
  •  "GET /content/geometrixx-outdoors/en/men.html" 

-

文字の範囲を定めます。文字クラス内で使用します。

文字クラス外のこの文字は、リテラルとして解釈されます。

*[m-p]men.html*

次の HTTP 要求に一致します。

  • "GET /content/geometrixx-outdoors/en/women.html"

次の HTTP 要求に一致しません。

  • "GET /content/geometrixx-outdoors/en/men.html"

!

続く文字または文字クラスを打ち消します。文字クラス内の文字および文字範囲の打ち消しにのみ使用してください。ワイルドカード ^ と同等です。

文字クラス外のこの文字は、リテラルとして解釈されます。

*[!o]men.html*

次の HTTP 要求に一致します。

  • "GET /content/geometrixx-outdoors/en/men.html"

次の HTTP 要求に一致しません。

  • "GET /content/geometrixx-outdoors/en/women.html" 

*[!o!/]men.html*

次の HTTP 要求に一致しません。

  • "GET /content/geometrixx-outdoors/en/women.html" または "GET /content/geometrixx-outdoors/en/men. html" 
^

続く文字または文字範囲を打ち消します。文字クラス内の文字および文字範囲の打ち消しにのみ使用してください。ワイルドカード文字 ! と同等です。

文字クラス外のこの文字は、リテラルとして解釈されます。

ワイルドカード文字 ! の例が適用されます。サンプルパターンの文字 ! を文字 ^ で置き換えてください。

ログ

Web サーバー設定で、次の属性を設定できます。

  • Dispatcher ログファイルの場所。
  • ログレベル。

詳しくは、Web サーバーのドキュメント、および使用する Dispatcher インスタンスの readme ファイルを参照してください。

Apache の交替されるログ/パイプ経由のログ

Apache Web サーバーを使用している場合、交替されるログ(パイプ経由のログ)の標準的な機能を使用できます。例えば、次のようにパイプ経由のログを使用できます。

    DispatcherLog "| /usr/apache/bin/rotatelogs logs/dispatcher.log%Y%m%d 604800"

この設定により、ログが自動的に次のように交替されます。

  • Dispatcher ログファイルの拡張子にタイムスタンプ(logs/dispatcher.log%Y%m%d)が付きます。
  • 週単位(60 x 60 x 24 x 7 = 604800 秒)で交替されます。

ログの交替やパイプ経由のログについては、Apache Web サーバーのドキュメント(Apache 2.2 など)を参照してください。

メモ

インストール時のデフォルトのログレベルは高(レベル 3 = デバッグ)なので、Dispatcher ですべてのエラーおよび警告がログに記録されます。このログレベルは、初期の段階では非常に便利です。

ただし、追加のリソースが必要となるので、Dispatcher が現在の要件で円滑に動作している場合は、ログレベルを低くしてください。

トレースログ

Dispatcher の機能強化の中で、機能パック NPR-6365 にはトレースログも導入されています。

トレースログはデバッグログよりレベルが高く、ログに追加情報が表示されます。以下に関するログが追加されます。

  • 転送されたヘッダーの値
  • 特定のアクションに対して適用されるルール

Web サーバーでログレベルを 4 に設定して、トレースログを有効にすることができます。

トレースを有効にしたログの例を以下に示します。

[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[Host] = "localhost:8443"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[User-Agent] = "curl/7.43.0"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[Accept] = "*/*"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[X-Forwarded-SSL-Client-Cert] = "(null)"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[Via] = "1.1 localhost:8443 (dispatcher)"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[X-Forwarded-For] = "::1"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[X-Forwarded-SSL] = "on"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[X-Forwarded-SSL-Cipher] = "DHE-RSA-AES256-SHA"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[X-Forwarded-SSL-Session-ID] = "ba931f5e4925c2dde572d766fdd436375e15a0fd24577b91f4a4d51232a934ae"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[X-Forwarded-Port] = "8443"
[Thu Mar 03 16:05:38 2016] [T] [17183] request.headers[Server-Agent] = "Communique-Dispatcher"
        

コードサンプルは、例としてのみ使用することを目的としています。

ブロックルールに一致するファイルが要求されると、イベントがログに記録されます。

[Thu Mar 03 14:42:45 2016] [T] [11831] 'GET /content.infinity.json HTTP/1.1' was blocked because of /0082
        

コードサンプルは、例としてのみ使用することを目的としています。

基本操作の確認

Web サーバー、Dispatcher および AEM インスタンスの基本の操作とやり取りを確認するには、次の手順を実行します。

  1. loglevel3 に設定します。
  2. Web サーバーを起動します。これに伴い、Dispatcher も起動します。
  3. AEM インスタンスを起動します。
  4. Web サーバーと Dispatcher のログファイルおよびエラーファイルを確認します。
    Web サーバーによっては、次のようなメッセージが表示されます。
           [Thu May 30 05:16:36 2002] [notice] Apache/2.0.50 (Unix) configured
    および
           [Fri Jan 19 17:22:16 2001] [I] [19096] Dispatcher initialized (build XXXX)
  5. Web サーバー経由で Web サイトにアクセスします。コンテンツが要求どおりに表示されていることを確認します。
    例えば、AEM がポート 4502 で、Web サーバーがポート 80 で実行されているローカルインストール上で、以下の両方を使用して Web サイトコンソールにアクセスします。
        http://localhost:4502/libs/wcm/core/content/siteadmin.html
        http://localhost:80/libs/wcm/core/content/siteadmin.html
    結果は同じになるはずです。同じ方法で、他のページへのアクセスも確認します。
  6. キャッシュディレクトリがいっぱいになっていることを確認します。
  7. ページをアクティベートし、キャッシュが正常にフラッシュされるかを確認します。
  8. すべて適切に動作している場合は、loglevel を再び 0 に設定します。

複数の Dispatcher の使用

複雑な設定をおこなう場合は、複数の Dispatcher を使用できます。例えば、次のように使用できます。

  • 1 つ目の Dispatcher を、イントラネット上での Web サイトの公開に使用
  • 2 つ目の Dispatcher を、異なるアドレスと異なるセキュリティ設定で、インターネット上での同じコンテンツの公開に使用

この場合、各要求が経由する Dispatcher は 1 つだけにしてください。別の Dispatcher から渡された要求は処理されません。したがって、どちらの Dispatcher も AEM Web サイトに直接アクセスするようにしてください。

​