Apache HTTP サーバ バージョン 2.0 ドキュメント - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション

Apache HTTP サーバ バージョン 2.0 ドキュメント

リリースノート

  • Apache 2.0 の新機能
  • 1.3 から 2.0 へのアップグレード
  • Apache ライセンス

リファレンスマニュアル

  • コンパイルとインストール
  • 起動
  • 終了と再起動
  • 実行の設定用ディレクティブ
  • ディレクティブ クイックリファレンス
  • モジュール
  • マルチプロセッシングモジュール (MPM)
  • フィルタ
  • ハンドラ
  • サーバとサポートプログラム
  • 用語集

ユーザの手引

  • アドレスとポートのバインド
  • 設定ファイル
  • セクションの設定
  • コンテントネゴシエーション
  • 動的共有オブジェクト (DSO)
  • 環境変数
  • ログファイル
  • URL をファイルシステムにマップする
  • 性能に関する調整
  • セキュリティ情報
  • サーバ全体の設定
  • SSL/TLS による暗号化
  • CGI の Suexec 実行
  • URL Rewriting の手引き
  • バーチャルホスト

How-To / チュートリアル

  • 認証、承認、アクセス制御
  • CGI: 動的コンテンツ
  • .htaccess ファイル
  • Server Side Includes (SSI)
  • ユーザ専用ディレクトリ (public_html)

プラットフォーム固有の情報

  • Microsoft Windows
  • Novell NetWare
  • EBCDIC 版

その他

  • よくある質問 (FAQ)
  • サイトマップ
  • 開発者のためのドキュメント
  • その他

Copyright 1999-2004 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


1.3 から 2.0 へのアップグレード - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

1.3 から 2.0 へのアップグレード

アップグレードを簡単にするために、既存の Apache ユーザに 非常に重要な情報をこの文書にまとめています。これは短い 注意書きとして書かれています。より詳しい情報は 新機能の文書や src/CHANGES ファイルで見つけられると思います。

参照

  • Apache 2.0 新機能の概要

コンパイル時の設定の変更

  • Apache は ビルド処理の設定 に autoconf と libtool を使うようになりました。 このシステムは Apache 1.3 の APACI システムと似ていますが、 まったく同じというわけではありません。
  • 通常のコンパイルするかどうかを選択できるモジュール群に加えて、 Apache 2.0 は リクエスト処理の主な部分を マルチプロセッシング モジュール (MPM) に移動しました。

実行時の設定の変更

  • Apache 1.3 の時にコアサーバにあった多くのディレクティブは MPM に移動しました。サーバに Apache 1.3 とできるだけ同じ振る舞いを させたい場合は、prefork MPM を 選んでください。他の MPM はプロセスの作成やリクエストの処理の 制御に異なったディレクティブを使います。
  • Proxy モジュール は HTTP/1.1 に対応するために再構成されました。重要な変更点としては、 プロキシのアクセス制御が <Directory proxy:> ブロックの 代わりに <Proxy> ブロックに置かれるようになった、というものがあります。
  • モジュールの中には、PATH_INFO (本当のファイル名の後に続く パス情報) の扱いが変わったものがあります。以前はハンドラとして 実装されていたものがフィルタとして実装されるようになったものは PATH_INFO のあるリクエストを受け付けません。INCLUDES や PHP などのフィルタは コアハンドラの上に実装されていますので、PATH_INFO 付きのリクエストを拒否します。 AcceptPathInfo ディレクティブを使ってコアハンドラが PATH_INFO 付きのリクエストを受け付けるようにでき、それによって SSI 等で PATH_INFO を使う機能を復活させることができます。
  • CacheNegotiatedDocs ディレクティブは on もしくは off という引数を 取るようになりました。既に存在している CacheNegotiatedDocs は CacheNegotiatedDocs on に置き換えてください。
  • ErrorDocument ディレクティブはテキストメッセージを 示すために引数の最初に使われていた引用符を使わないようになりました。 代わりに、メッセージを二重引用符で囲むようになっています。 例えば、既存の

    ErrorDocument 403 "Some Message

    は

    ErrorDocument 403 "Some Message"

    に置き換える必要があります。 二番目の引数は、有効な URL やパス名でない限り テキストメッセージとして扱われます。
  • AccessConfig ディレクティブと ResourceConfig ディレクティブは削除されました。 これらのディレクティブは同等の機能を持つ Include で 置き換えることができます。設定ファイルに取り込む代わりに、 上のディレクティブのデフォルト値を使っていた場合は、 httpd.conf に Include conf/access.conf と Include conf/srm.conf を追加する必要があるでしょう。 以前のディレクティブによる順番のように Apache が設定ファイルを 読み込むようにするためには、httpd.conf の最後に srm.conf、access.conf の順にそれぞれ Include ディレクティブを書いてください。
  • BindAddress ディレクティブと Port ディレクティブは削除されました。同等の機能はより柔軟な Listen ディレクティブにより提供されています。
  • Port ディレクティブは Apache-1.3 には自己参照 URL で 使われるポート番号を設定する、という使用法もありました。 これは Apache-2.0 では新しい ServerName 構文によって行ないます。一つのディレクティブでホスト名と 自己参照 URL の両方を設定できるように構文が変更されました。
  • ServerName ディレクティブは削除されました。 リクエストを扱う方法は MPM の選択により決定されるようになりました。 現時点では inetd から起動されるように設計された MPM はありません。
  • AgentLog ディレクティブ、 RefererLog ディレクティブ、 RefererIgnore ディレクティブを提供していた mod_log_agent と mod_log_referer モジュールは削除されました。 Agent ログと refere ログは mod_log_config の CustomLog ディレクティブにより実現可能です。
  • AddModule ディレクティブと ClearModuleList ディレクティブは削除されました。これらのディレクティブは、 モジュールが正しい順番で呼ばれるようにするために使われていました。 Apache 2.0 の新 API はモジュールが明示的に順番を指定できるように なっており、これらのディレクティブは必要なくなりました。
  • FancyIndexing ディレクティブは削除されました。 同じ機能は IndexOptions ディレクティブの FancyIndexing オプションで 実現できます。
  • mod_negotiation による MultiViews コンテントネゴシエーション技術は、 デフォルトのファイルマッチングがより厳密なものに変更されました。 ネゴシエート可能なファイルの場合にのみ選択されます。 以前の挙動は、MultiviewsMatch ディレクティブを使用することで復活できます。
  • (バージョン 2.0.51 から)

    ErrorHeader ディレクティブは不適切な名前 だったために廃止され、その機能は Header ディレクティブに統合されました。 望みの動作を得るためには ErrorHeader の代わりに

    Header always set foo bar

    を使ってください。

その他の変更

  • Apache 1.3 で実験的なモジュールだった mod_auth_digest は 標準モジュールになりました。
  • Apache 1.3 で実験的なモジュールだった mod_mmap_static は mod_file_cache で置き換えられました。
  • Apache の配布は独立した src ディレクトリが なくなるように、完全に再構成されました。その代わりに、 ソースは主ディレクトリに論理的に配置されるようになり、 コンパイルされたサーバのインストールは別ディレクトリへ 行なうようになりました。

サードパーティモジュール

Apache 2.0 のサーバ API には多くの変更が加えられました。 Apache 1.3 用の既存のモジュールは Apache 2.0 では修正なしでは 動きません。詳細は 開発者向け文書 にあります。


Apache 2.0 の新機能の概要 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

Apache 2.0 の新機能の概要

この文書では、Apache HTTP サーババージョン 1.3 と 2.0 の主な違いについて記述しています。

参照

  • 1.3 から 2.0 へのアップグレード

コア機能の拡張

Unix のスレッド
POSIX スレッドをサポートしている Unix システム上では、 Apache はマルチプロセス、マルチスレッドのハイブリッドモードで 実行できるようになりました。これにより 多くの設定においてスケーラビリティが向上します。
新しいビルドシステム
ビルドシステムは autoconf と libtool に基づいたものになるように、 新しく書き直されました。これにより、Apache の configure のシステムは 他のパッケージと似たものになりました。
マルチプロトコルサポート
Apache に複数のプロトコルを扱うための機構が備わりました。 例として mod_echo が書かれています。
Unix 以外のプラットフォームのサポートの改善
Apache 2.0 は BeOS、OS/2、Windows などの Unix 以外の プラットフォームで、より速く、より安定して動作するようになりました。 プラットフォーム特有の マルチプロセッシングモジュール (MPM) と Apache Portable Runtime (APR) の導入により、 ネイティヴの API で実装されるようになり、 バグが多く、性能の悪いことが多い POSIX エミュレーションレイヤの使用を 回避することができました。
新しい Apache API
2.0 ではモジュールの API が大きく変わりました。 1.3 にあったモジュールの順番/優先度の問題の多くは なくなっているはずです。2.0 は優先度の選択をほとんどを自動的に行ない、 モジュールの順番はより柔軟性を高めるためにフック毎に行なわれるように なりました。また、コア Apache サーバにパッチをあてることなく 追加のモジュール機能を提供することができるように新しい関数が 追加されました。
IPv6 サポート
Apache が使用している Apache Portable Runtime library が IPv6 をサポートしているシステムでは Apache は デフォルトで IPv6 のソケットを listen します。さらに、 Listen, NameVirtualHost, VirtualHost の各ディレクティブが IPv6 のアドレスを サポートするようになりました (例えば、 "Listen [fe80::1]:8080")。
フィルタ
Apache のモジュールはサーバから送られてきたり、サーバへ 送るストリームに対して動作するフィルタとして書くことができるように なりました。これにより、例えば CGI スクリプトの出力を mod_include の INCLUDES フィルタを使って Server Side Include のディレクティブを解析する、 というようなことが可能になりました。mod_ext_filter で外部プログラムをフィルタとして動作させることができます。 これは CGI プログラムをハンドラとして動作させるのと よく似た方法でできます。
多言語エラー応答
ブラウザへのエラー応答のメッセージが、SSI の文書を使って 複数の言語で提供されるようになりました。見ための一貫性を保つために 管理者がカスタマイズすることもできます。
設定の簡素化
多くの混乱を招きがちなディレクティブが簡素化されました。 よく混乱を引き起こしていた Port ディレクティブと Bind ディレクティブは なくなりました。Listen ディレクティブのみが IP アドレスのバインドに使われます。 ServerName ディレクティブでは リダイレクトと vhost の認識のためだけにサーバの名前とポート番号を 指定します。
Windows NT のネイティヴ Unicode サポート
Windows NT 上の Apache 2.0 はファイル名の文字エンコード全てに utf-8 を使うようになりました。これらは Unicode ファイルシステムに 直接変換されるので、Windows 2000 と Windows XP を含む、全ての Windows NT 系で多言語サポートが提供されます。 このサポートは、ファイルシステムのアクセス時にローカルの コードページを使う Windows 95, 98, ME には適用されません。
正規表現ライブラリのアップデート
Apache 2.0 は Perl 互換正規表現ライブラリ (PCRE) を含んでいます。 正規表現の評価には、より強力になった Perl 5 構文を使用します。

モジュールの拡張

mod_ssl
Apache 2.0 の新モジュール。このモジュールは OpenSSL が 提供する SSL/TLS 暗号プロトコルへのインタフェースです。
mod_dav
Apache 2.0 の新モジュール。このモジュールはウェブコンテンツを 送り、維持するための規格 HTTP Distributed Authoring and Versioning (DAV) を実装しています。
mod_deflate
Apache 2.0 の新モジュール。送信前に送信内容を圧縮して ネットワーク帯域を節約する、というリクエストをブラウザが 要求できるようにします。
mod_auth_ldap
Apache 2.0.41 の新モジュール。HTTP 基本認証の証明書を保存するのに、 LDAP データベースを使用できるようになります。 関連モジュールの mod_ldap で、 コネクションのプール機能と結果のキャッシュ機能が提供されます。
mod_auth_digest
このモジュールは共有メモリを使うことにより、プロセスをまたいだ セッションのキャッシュをサポートするようになりました。
mod_charset_lite
Apache 2.0 の新モジュール。この実験的なモジュールは キャラクタセットの変換や再符号化を可能にします。
mod_file_cache
Apache 2.0 の新モジュール。このモジュールには、 Apache 1.3 における mod_mmap_static 機能が含まれ、 また、追加のキャッシュ機能が加わっています。
mod_headers
このモジュールは Apache 2.0 で非常に柔軟性が 高くなりました。mod_proxy で使われるリクエストのヘッダを変更できるようになりましたし、 応答ヘッダを条件に応じて設定できるようになりました。
mod_proxy
proxy モジュールは新しいフィルタの機構を利用するためと、 より信頼できる、HTTP/1.1 に準拠した proxy を実装するために 完全に書き直されました。さらに、新しい <Proxy> 設定セクションがproxy されるサイトのより読みやすく (内部的にもより速い) 設定を提供します。オーバーロードされた <Directory "proxy:... > 設定はサポートされていません。このモジュールは proxy_connect, proxy_ftp, proxy_http といった、特定のプロトコルをサポートする モジュールに分割されるようになりました。
mod_negotiation
クライアントが NOT ACCEPTABLE や MULTIPLE CHOICES 応答の 代わりに常に単独の文書を受けとるようにするために、新しいディレクティブ ForceLanguagePriority を使うことができるようになりました。 さらに、より一貫性のある結果を提供するために ネゴシエーションと MultiViews のアルゴリズムが改善され、 文書の内容を含めることのできる、新しい形式のタイプマップが 提供されるようになりました。
mod_autoindex
Autoindex されるディレクトリの内容一覧が、 きれいに表示されるために HTML のテーブルを使うように 設定できるようになりました。また、バージョンによるソーティングなど、 より細かいソーティングの制御ができるようになり、ディレクトリ の内容一覧をワイルドカードにより選別することができるようにもなりました。
mod_include
新しいディレクティブにより、SSI のデフォルトの開始タグと終了タグを 変更できるようになりました。また、エラーと時刻の形式の設定が SSI の 文書中ではなく、主設定ファイル中で行なえるようになりました。 正規表現の解析とグループ化の結果 (Perl の正規表現の構文に 基づいたものになりました) を mod_include の変数 $0 .. $9 により取得できるようになりました。
mod_auth_dbm
AuthDBMType ディレクティブにより、複数の DBM 型のデータベースをサポートする ようになりました。


The Apache License, Version 2.0 - Apache HTTP Server

Apache HTTP Server Version 2.0

Apache > HTTP Server > Documentation > Version 2.0

The Apache License, Version 2.0

Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

  1. Definitions

    "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.

    "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.

    "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.

    "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.

    "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.

    "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.

    "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).

    "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.

    "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."

    "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.

  2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
  3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
  4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
    1. You must give any other recipients of the Work or Derivative Works a copy of this License; and
    2. You must cause any modified files to carry prominent notices stating that You changed the files; and
    3. You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
    4. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.

    You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.

  5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
  6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
  7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
  8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
  9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

APPENDIX: How to apply the Apache License to your work.

To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.

Copyright [yyyy] [name of copyright owner]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


コンパイルとインストール - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

コンパイルとインストール

この文書で扱う範囲は、Unix や Unix に類似したシステムでの Apache のコンパイルとインストールです。 Windows における コンパイルとインストールに関しては「Microsoft Windows で Apache を使う」をご覧下さい。 その他のプラットホームに関しては「プラットホーム」をご覧下さい。

Apache 2.0 の設定とインストールの環境は、Apache 1.3 とは 完全に異なるものになりました。簡単にインストールできるように、 Apache 1.3 では特製スクリプトを使っていました。 Apache 2.0 では他の Open Source プロジェクトと同様の環境に するために libtool と autoconf を使うようになっています。

マイナーバージョンからその次のバージョンにアップグレードする (2.0.50 から 2.0.51 へ等) 場合は、まず アップグレードをご覧下さい。

参照

  • ソースツリーの設定
  • Apacheの起動
  • Apacheの停止と再起動

概要 (せっかちな人向け)

ダウンロード | $ lynx http://httpd.apache.org/download.cgi
展開 $ gzip -d httpd-2_0_NN.tar.gz
$ tar xvf httpd-2_0_NN.tar
設定 | $ ./configure --prefix=PREFIX
コンパイル | $ make
インストール | $ make install
カスタマイズ | $ vi PREFIX/conf/httpd.conf
テスト | $ PREFIX/bin/apachectl start

NN は最新のマイナーバージョンナンバーに、 PREFIX はインストールするサーバでのファイルシステムのパスに、 置き換えてください。PREFIX を指定しなかった場合は、 デフォルトの /usr/local/apache2 になります。

Apache HTTPD のコンパイルとインストールに必要なものをはじめとして、 編集とインストールプロセスでのそれぞれの項は 次に詳しく記述されています。

必要なもの

Apache のビルドには次のものが必要です:

ディスクスペース
ディスクに少なくとも 50 MB の一時的な空き容量があるように 気を付けてください。インストール後は Apache は 10 MB 程度の ディスクスペースを占めます。実際に必要になるディスクスペースは、 設定オプションやサードパーティー製モジュールをどう選択するかによって 大きく変わるでしょう。
ANSI-C コンパイラとビルドシステム
ANSI-C コンパイラをインストールしておいて下さい。お薦めは Free Software Foundation (FSF) による GNU C compiler (GCC) です (バージョン 2.7.2 で大丈夫です)。GCC がない場合は、 少なくとも提供されているコンパイラが ANSI 準拠であることを確認しておいて下さい。 それから、変数 PATH には make といった基本的なビルドツールが含まれている必要があります。
時刻を正確にする
HTTP プロトコルの要素は日時の時刻で表現されています。ですから、 正確な時刻にシンクロさせる機能をシステムに設定することを吟味してみて下さい。 Network Time Protocol (NTP) をベースとした ntpdate や xntpd プログラムが この目的によく用いられます。NTP ソフトウェアや公開 NTP サーバに関する詳細は、Usenet ニュースグループ comp.protocols.time.ntp や NTP ホームページ をご覧下さい。
Perl 5 [オプション]
提供されているスクリプト幾つか、例えば apxs や dbmmanage は Perl で書かれているので、Perl 5 インタプリタが必要になります (5.003 以降)。 "configure"スクリプトでこのようなインタプリタが見つからなくても、 別に不具合はありません。もちろん、Apache 2.0 のコンパイルとインストールはできます。 これらのサポートスクリプトが使えなくなるだけです。 Perl インタプリタを複数インストールしている場合 (ベンダーの Perl 4 と自分で入れた Perl 5 がある場合など) は、 --with-perl オプション (下記参照) を使って ./configure が適切なものを確実に選ぶようにすると良いでしょう。

ダウンロード

Apache は Apache HTTP サーバダウンロードサイトからダウンロードできますし、 同じ場所に幾つかのミラーサイトもリストしています。 UNIX に類似するシステムで Apache を使うユーザは、ソースを ダウンロードしてビルドしたほうが良いでしょう。 ビルドの手順（下記）は簡単ですし、そのおかげでニーズに 見合ったカスタマイズを簡単にできます。 さらに、バイナリのリリースはソースリリースよりも 遅れていることがよくあります。 それでもバイナリをダウンロードしたのであれば、 ディストリビューションの中にある INSSTALL.bindist ファイルの説明に従ってください。

ダウンロード後、ダウンロードしたものが Apache HTTP サーバの完全で改竄されていないバージョンであることを 検証することが重要です。これはダウンロードした tarball の PGP 署名を テストすることによって検証します。 この手順の詳細は ダウンロード ページ にあり、さらに詳しい例は PGP の使用 に記載されています。

展開

Apache HTTPD の tarball からソースファイルを展開して取り出すとは、 単なる圧縮の解除と tar の展開です:

$ gzip -d httpd-2_0_NN.tar.gz
$ tar xvf httpd-2_0_NN.tar

配布用のソースコードがある現在いるディレクトリの下に、 新しいディレクトリが作られます。 サーバをコンパイルする段階に進む前に、そのディレクトリに cd で移動してください。

ソースツリーを設定する

次のステップは、あなたのプラットホームと 個人的な要求に合うように Apache ソースツリーを設定することです。 これは配布ディレクトリのルートディレクトリにある、 configure スクリプトで行ないます。 (Apache ソースツリーの CVS 版をダウンロードした開発者は、次のステップに進む前に autoconf とlibtool をインストールして buildconf を実行する必要があるでしょう。 公式リリースではこの作業は必要ありません。)

デフォルトオプションを使ってソースツリーを全て設定する のであれば、単純に ./configure とタイプしてください。 デフォルトオプションを変更できるように、configure には様々な変数やコマンドラインオプションが用意されています。

最も重要なオプションは、Apache がこの後でインストールされる位置 --prefix です。Apache は、このインストール位置に おいて正常に動作するように設定しなければならないからです。 さらに詳細なファイル位置の制御は追加の 設定オプション でできます。

この時点で、モジュール を有効にしたり 無効にしたりすることで Apache 本体に含まれる 機能 を指定できます。Apache 本体にはデフォルトで、モジュールの Base セットが 含まれます。その他のモジュールは --enable-module オプションで 有効になります。ここで module はモジュールの名前で、 つまりそれはモジュールの名前から mod_ 文字列を取り除いた後に アンダースコアをダッシュで置換した文字列です。 これとは別の方法で --enable-module=shared オプションを使って、モジュールを シェアードオブジェクト (DSO) -- 実行時にロードしたり アンロードしたりできる形式 -- としてコンパイルすることもできます。 同様に、--disable-module オプションで Base モジュールを無効化することもできます。 これらのオプションを使っているときに、もし指定したモジュールが存在しなくても configure は警告を上げることなく、単純にオプションを 無視することに気をつけてください。

上記に加えて、configure スクリプトに、 コンパイラ、ライブラリ、ヘッダファイルの位置を追加情報として渡す 必要がある場合があります。このような場合には、環境変数あるいは コマンドラインオプションで configure に渡します。 詳細に関しては configure マニュアルページ をご覧ください。

ちょっとどんなことができるかを見せましょう。 ここで典型的な例として、/sw/pkg/apache というインストールツリーでコンパイラとフラグを指定して、 さらに二つの追加モジュール mod_rewrite と mod_speling を後で DSO メカニズムでロードするようにコンパイルしてみます:

$ CC="pgcc" CFLAGS="-O2" \
./configure --prefix=/sw/pkg/apache \
--enable-rewrite=shared \
--enable-speling=shared

configure を実行したら、システムの機能を テストしたり、後でサーバをコンパイルするために必要な Makefile を生成したりするのに数分間かかるでしょう。

個々の configure オプションの詳細に関しては configure マニュアルページ をご覧ください。

ビルド

これで Apache の様々なパーツをビルドすることができます。 次のコマンドを単純に実行するだけです:

$ make

基本的な設定をするのに、Pentium III/Linux 2.2 のシステムでおおよそ 3 分程度かかりますが、 あらかじめご了承下さい。 また、時間はハードウェアや有効にしたモジュールの数に 大きく依存するでしょう。

インストール

さて、設定したインストール PREFIX (前述の --prefix オプションを参照) 以下にパッケージをインストールする段階になりました。 次のコマンドを実行してください:

$ make install

アップグレードする場合は、インストールでは設定ファイルや ドキュメントファイルの上書きは行いません。

カスタマイズ

次に PREFIX/conf/ 以下にある 設定ファイルを編集して、 Apache HTTP サーバをカスタマイズします。

$ vi PREFIX/conf/httpd.conf

docs/manual/ の Apache マニュアルをざっと見てください。 または、http://httpd.apache.org/docs-2.0/ にあるマニュアル最新版、設定ディレクティブに当たってみてください。

テスト

次のコマンドを実行して Apache HTTP サーバを開始できます:

$ PREFIX/bin/apachectl start

URL http://localhost/ を通して最初のドキュメントに対する リクエストを発行する事ができるはずです。これで見える ウェブページは DocumentRoot 以下に置かれたもので、通常は PREFIX/htdocs/ でしょう。 サーバを再び停止するには、 次のコマンドを実行します:

$ PREFIX/bin/apachectl stop

アップグレード

アップグレードでまず行なうべきことは、リリースアナウンスと ソースディストリビューションに入っている CHANGES を読んで、 自身のサイトに対して影響を及ぼす変更点を探すことです。 メジャーリリース間の変更をする場合 (例えば 1.3 から 2.0 へ、2.0 から 2.2 へ) は、コンパイル時や実行時の設定に大きな差異があるでしょうから、 手動の調整が必要になるでしょう。モジュールも全て、API の変更に合わせるためにアップグレードが必要になるでしょう。

マイナーバージョンから次のバージョンにアップグレードする場合 (例えば 2.0.55 から 2.0.57 へ) は、もっと簡単です。 make install を実行しても今あるドキュメント、 ログファイル、設定ファイルは上書きされません。 さらに、マイナーバージョン間では configure オプション、 実行時の設定、モジュール API に不整合が起こらないように、 開発者は最大限の努力をしています。 大抵の場合、同一の configure コマンドライン、 同一の設定ファイル、モジュール全てが正常に動作するはずです。 (2.0.41 以降ではそのようになっています。それ以前のバージョンには 不整合が存在します。)

前回のインストール時のソースツリーが残されているのであれば、 アップグレードはさらに簡単です。古いソースツリーのルートに存在する config.nice ファイルには、前回ソースツリーを設定した時の configure コマンドラインが入っています。 次のバージョンにアップグレードする場合は、config.nice ファイルを新しいバージョンのソースツリーにコピーし、 それを編集し必要な変更を行なって、次のように実行します。

$ ./config.nice
$ make
$ make install
$ PREFIX/bin/apachectl stop
$ PREFIX/bin/apachectl start

新しいバージョンを使用する場合は、 実際に運用を始める前に、必ず自分用の環境でテストすべきです。 最終的にアップグレードする前に、非互換性がないかをテストするために、 例えば、異なる --prefix と異なるポート (Listen ディレクティブで設定します) を使用することで、古いバージョンに影響を与えずに新しいバージョンを インストールし、実行できます。


Apache の起動 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

Apache の起動

Windows 上では、Apache は通常は Windows NT, 2000, XP ではサービスとして、Windows 9x, ME ではコンソールアプリケーションとして実行されます。 詳細に関しては、「 サービスとして実行する」と「 コンソールアプリケーションとして実行する」をご覧下さい。

Unixでは、httpd プログラムが、バックグラウンドで常にリクエスト処理を行う デーモンとして実行されます。この文書ではどのように httpd を起動するかについて記述しています。

参照

  • 停止と再起動
  • httpd
  • apachectl

Apache の起動方法

もし、設定ファイル中で指定されている Listen がデフォルトの 80 (もしくは 1024 以下の他のポート) である場合は、Apache を起動するためには root 権限が必要になりますが、 これはこの特権ポートにバインドするためです。 起動して、一度ログファイルを開くといった準備のための 動作を幾つか実行した後は、クライアントからのリクエストに対する listen と応答を実際に行う子プロセスを起動します。 メインの httpd プロセスは root 権限で走り続けますが、 子プロセスはもっと低い権限で走ります。 これは選択したマルチプロセッシングモジュールで制御されます。

推奨の httpd 実行プログラムの起動方法は、 apachectl 制御スクリプトを使用する方法です。このスクリプトは、httpd がオペレーティングシステム上で正常に動作するように必要な環境変数を 適切に設定して、httpd バイナリを起動します。 apachectl はどんなコマンドライン引数も通過させますので、 httpd のどのコマンドラインオプションも apchectl のオプションとして使用できます。 また、apchectl スクリプトを直接編集し、 スクリプト先頭付近の HTTPD 変数を変更することで、 httpd バイナリの正しい位置を指定したり、常に 付加させるコマンドライン引数を指定したりすることができます。

httpd が起動されてまず最初にすることは、 設定ファイル httpd.conf の位置を特定して読み込むことです。 このファイルの位置はコンパイル時に設定されますが、実行時に -f コマンドラインオプションを使って 位置を指定することもできます。例えば次のようにです。

/usr/local/apache2/bin/apachectl -f /usr/local/apache2/conf/httpd.conf

スタートアップが万事上手くいったら、サーバはターミナルから 切り離されて、コマンドプロンプトが即座に戻ってくるでしょう。 これはサーバが起動している状態を示しています。 その後はブラウザでサーバに接続して、 DocumentRoot ディレクトリのテストページやそこからリンクされている ローカルのドキュメントを見ることができるでしょう。

起動時のエラー

Apache は、起動時に致命的な問題に遭遇すると、 終了する前に、コンソールか ErrorLog のどちらかに問題を記述したメッセージを出力します。 最もよくあるエラーメッセージは 「Unable to bind to Port ...」 です。このメッセージは普通は次のどちらかが原因です。

  • root でログインしていない時に、 特権ポートでサーバを起動しようとした。
  • 同じポートに既にバインドされている Apache がもう一つあるときや他のウェブサーバが存在している時に、 サーバを開始しようとした。

より多くの問題解決の方策の説明は、 Apache FAQ をご覧下さい。

ブート時の起動

システムがリブートした後でも サーバが実行され続けるようにしたい場合は、 apachectl を呼び出すものをシステムスタートアップファイル (通常 rc.local や rc.N 内のファイル) に追加しなければなりません。 この方法では Apache を root 権限で起動します。 これをする前に、セキュリティやアクセス制限が 適切に設定されていていることを確認してください。

apachectl スクリプトは通常は、標準的な SysV init スクリプトとして動作するように設計されています。 start, restart, stop といった引数をとって、httpd への適切なシグナルに変換します。 ですから、通常は単に適切な init ディレクトリ内から apachectl へリンクすることができます。しかし、 念のためシステムの要求に合致していることを確認してください。

追加情報

httpd や apachectl 、サーバに含まれていたその他補助プログラムの、 コマンドラインオプションに関する追加情報は、 サーバと補助プログラムページに 記載されています。 Apache 配布に含まれている全モジュール、 それによって提供されるディレクティブ のドキュメントもあります。


停止と再起動 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

停止と再起動

この文書では Unix に類似したシステムでの Apache の停止と再起動について扱っています。 Windows NT, 2000, XP ユーザはサービスとして Apache を実行するで、Windows 9x, MEユーザはコンソールアプリケーションとして Apache を実行するで、 これらのプラットホームでの使用方法をご覧下さい。

参照

  • httpd
  • apachectl

イントロダクション

Apache を停止したり再起動したりするためには、実行されている httpd プロセスにシグナルを送る必要があります。 シグナルを送るには二つの方法があります。 一つ目はプロセスに直接シグナルを送る unix の kill コマンドを使用する方法です。 システムを見ればたくさんの httpd が 実行されているのに気が付くでしょうが、シグナルを送るのは 親プロセスだけで、それ以外の個々のプロセスには シグナルを送らないで下さい。その親プロセスの pid は PidFile に書かれています。これはつまり、親以外のプロセスに シグナルを送る必要すらない、ということです。 親プロセスに送ることができる 3 種類のシグナルがあります: TERM, HUP, USR1 です。これらの説明については続きをご覧下さい。

親プロセスにシグナルを送るには、 次のようなコマンドを発行して下さい:

kill -TERM `cat /usr/local/apache2/logs/httpd.pid`

httpd プロセスにシグナルを送る 2 番目の方法は -k というコマンドライン引数を使用することです。 下で説明されているように、stop, restart, graceful を指定できます。 これらは httpd の引数ですが、 制御用のスクリプト apachectl を 使うことをお薦めします。apachectl はそれらの引数をそのまま httpd に渡します。

httpd にシグナルを送った後、 実行状況を次のコマンドで読むことができます:

tail -f /usr/local/apache2/logs/error_log

ここに挙げた例は、各自の ServerRoot と PidFile の設定に適合するように適宜修正して下さい。

急な停止

シグナル: TERM
apachectl -k stop

TERM あるいは stop シグナルを親プロセスに送ると、即座に子プロセス全てを kill しようとします。 子プロセスを完全に kill し終わるまでに数秒かかるかもしれません。 その後、親プロセス自身が終了します。 処理中のリクエストは全て停止され、もはやリクエストに対する 応答はされません。

緩やかな再起動

シグナル: USR1
apachectl -k graceful

親プロセスは USR1 あるいは graceful シグナルを受け取ると、子プロセスに現在のリクエストの処理の後に終了する (あるいは何もしていなければすぐに終了する) ように助言します。 親プロセスは設定ファイルを再読込して、ログファイルを開き直します。 子プロセスが徐々になくなるに従って、 新しい世代の設定による子プロセスに置き換えていきます。 そして、これらが新たなリクエストに即座に応答し始めます。

特定のプラットホームでは USR1 を緩やかな再起動のために使うことができませんが、代わりのシグナル (例えば WINCH) が使用できるでしょう。 apachectl graceful というコマンドはプラットホームに合ったシグナルを送ります。

このコードは常に MPM のプロセス制御ディレクティブの設定を重視しますので、 クライアントのリクエストを扱うプロセスとスレッドの数を再起動の処理中も 適切な値に維持されます。。また、次のようにして StartServers を守ります: 少なくとも 1 秒後に StartServers 個の新しい子プロセスが 生成されていなければ、その数になるように適宜プロセスを生成します。 この挙動は現在の負荷に対して適切な子プロセスの数と StartServers パラメータでの 希望の数の両方を維持しようとしています。

mod_status を 使用している場合は、USR1 シグナルが送られた際に サーバ統計がゼロに設定されないことに 注意してください。 サーバが新しいリクエストに応答不能な時間を最小にするように (リクエストは OS によってキューに追加されるので絶対に紛失はしません)、 また同時に、希望のチューニングパラメータを守るように コードは書かれています。 このようにするために、世代をまたがった全子プロセスの追跡に使われている スコアボードを維持しなければなりません。

status モジュールは、緩やかな再起動以前から開始して リクエストに応答し続けている子プロセスを特定するために、 G を使うこともします。

現在、USR1 を使うログ移動スクリプトでは、 再起動前の子プロセスがログを書き終わったことを確証する方法が ありません。古いログに対して何かする前に、 USR1 シグナルを送った後いくらか適当な時間待つことを 提案します。例えば、帯域の狭い通信路のユーザのリクエストのほとんどが 10 分以下で完了しているということが分かっていれば、 古いログに何かする前に 15 分待つということです。

再起動時に設定ファイルに誤りがあると、 親プロセスは再起動せずにエラーとともに終了します。 緩やかな再起動の場合は、親プロセスが終了した後でも子プロセスが 実行されたまま放置されたりもします。 (最後のリクエストを処理した後「緩やかに終了」する 子プロセスとなります。) サーバを再起動する際に、これが問題になるかもしれません -- サーバは listen するポートにバインドできないかもしれません。 再起動する前に、設定ファイルの構文を -t コマンドライン引数 (httpd をご覧下さい) を使って検証することができます。 設定ファイルの意味的な内容を構文と同様に検証したい場合は、 非 root ユーザで httpd を起動しようとすればわかります。 もしエラーがなければ、ソケットやログを開こうとして root でないため (もしくは実行中の httpd が既に必要なポートにバインドしているため) に失敗するでしょう。 これ以外の理由で起動に失敗したのであれば、 それは設定ファイルのエラーで、 緩やかな再起動を行う前にその誤りを修正しなければなりません。

急な再起動

シグナル: HUP
apachectl -k restart

HUP あるいは restart シグナルを親プロセスに送ると、 TERM と同様に子プロセスを kill しますが、 親プロセスは終了しません。 設定ファイルを再読込して、ログファイル全てを開き直します。 その後、新しい子プロセスを起動して応答を続けます。

mod_status を使っている場合は、HUP が送られた場合に サーバ統計がゼロに設定されることに注意してください。

再起動時に設定ファイルに誤りがあると、 親プロセスは再起動せずにエラーとともに終了します。 これを避けるには次の方法をご覧下さい。

付録: シグナルと競合状態

Apache 1.2b9 以前は、再起動や停止のシグナルを含む競合状態 (競合状態を簡単に説明すると: タイミンにグよる問題で、 具合の悪い時間帯にちょうど何かが起こると予想外の動作をする ようなことを指します) がありました。 「正しい」機能を持っているアーキテクチャでは、できるだけ このようなことが起こらないようにしています。 しかし、ある種のアーキテクチャでは競合状態は未だ確実に起こりえる ということに注意してください。

ディスク上で ScoreBoardFile を使用しているアーキテクチャでは、 潜在的にスコアボードが壊れる可能性があります。 スコアボードが壊れた場合は、 "bind: Address already in use" (HUP 後) や "long lost child came home!" (USR1 後) といった結果になります。 前者は致命的なエラーですが、 後者はスコアボードスロットを失うだけです。 ですから緩やかな再起動は、たまに確実な再起動 (HUP) も併用して使った方が良いでしょう。 これらの問題を克服するのは非常に難しいのですが、 幸いなことに大部分のアーキテクチャではスコアボードのファイルは必要ありません。 これを使用するアーキテクチャは、 ScoreBoardFile をご覧下さい。

全てのアーキテクチャにおいて、個々の子プロセスで 継続的な HTTP コネクション (KeepAlive) に関する小さな競合状態が起こりえます。 リクエスト行を読んだ後、そしてリクエストヘッダを読む前に 子プロセスは終了するかも知れません。 これに対する修正がありますが 1.2 で修正するには発見が遅すぎました。 理論的には、これは問題ではありません。 なぜなら KeepAlive のクライアントは、ネットワーク遅延や サーバのタイムアウトなどに備えていなければならないからです。 実際にも何か影響があるようには見えません -- テストケースでサーバを 1 秒間に 20 回再起動しても クライアントは壊れた画像や空のドキュメントを受け取ることなく 正常に閲覧できています。


設定ファイル - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

設定ファイル

この文書では、Apache HTTP サーバを設定するのに使用するファイルについて 記述しています。

メインの設定ファイル

関連モジュール 関連ディレクティブ
  • mod_mime
  • <IfDefine>
  • Include
  • TypesConfig

Apache は ディレクティブ を設定ファイルに平文で書くことにより設定します。 メインの設定ファイルは普通は httpd.conf という名前です。 このファイルの位置はコンパイル時に設定されますが、コマンドラインの -f フラグにより上書きできます。 また、他の設定ファイルを Include ディレクティブによって追加でき、ワイルドカードを使用して多数の 設定ファイルを追加することができます。 どんなディレクティブも、これらの設定ファイルどれにでも入れることができます。 Apache は起動時か再起動時のみメイン設定ファイルの変更を認識します。

サーバは MIME ドキュメントタイプを含んでいるファイルも読み込みます。ファイル名は TypesConfig で設定され、デフォルトでは mime.types になっています。

設定ファイルの構文

Apache の設定ファイルは 1 行に 1 つのディレクティブからなります。 バックスラッシュ "\" はディレクティブが次の行に継続していることを 示すために行の最後の文字として使われているかもしれません。 行の最後とバックスラッシュの間に他の文字や空白があってはいけません。

設定ファイルのディレクティブは大文字小文字を区別しませんが、 引数にはしばしば区別するものがあります。ハッシュ文字 "#" で始まる行はコメントと見なされて無視されます。 設定ディレクティブの後の行ではコメントが含まれていてはいけません。ディレクティブの前の空行と空白は無視されますので、 わかりやすくするためにディレクティブをインデントしても構いません。

設定ファイルの構文エラーは、 apachectl configtest かコマンドラインオプション -t を使って調べられます。

モジュール

関連モジュール 関連ディレクティブ
  • mod_so
  • <IfModule>
  • LoadModule

Apache はモジュール化されたサーバです。 コアサーバには最も基本的な機能だけが含まれています。拡張機能は Apache にロードされるモジュールとして利用可能です。デフォルトでは、コンパイル時にモジュールの Base セット (基本セット) が サーバに含まれます。サーバが動的ロードモジュールを使うようにコンパイルされている場合は、 モジュールを別にコンパイルして、いつでも LoadModule ディレクティブを使って追加できます。 そうでない場合は、モジュールの追加や削除をするためには Apache を再コンパイルする必要があります。設定ディレクティブは <IfModule> ブロックに入れることで特定のモジュールが存在するときだけ 設定ファイルに含まれるようにすることができます。

コマンドラインオプション -l を使って現時点で どのモジュールがサーバにコンパイルされているかを知ることができます。

ディレクティブの適用範囲

関連モジュール 関連ディレクティブ
  • <Directory>
  • <DirectoryMatch>
  • <Files>
  • <FilesMatch>
  • <Location>
  • <LocationMatch>
  • <VirtualHost>

メイン設定ファイルにあるディレクティブはサーバ全体に適用されます。 サーバの一部分の設定だけを変更したい場合は <Directory>, <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, <LocationMatch> セクションの中に置くことで適用範囲を決められます。 これらのセクションはその中にあるディレクティブの適用範囲を 特定のファイルシステムの位置や URL に限定します。 非常に細粒度の設定を可能にするために、 セクションを入れ子にすることもできます。

Apache は同時に多くの違うウェブサイトを扱う能力があります。 これは バーチャルホスト と呼ばれています。 特定のウェブサイトにのみ適用されるようにするために、 ディレクティブは <VirtualHost> セクションの中に置くことでも適用範囲を変えることができます。

ほとんどのディレクティブはどのセクションにでも書けますが、 中にはコンテキストによっては意味をなさないものもあります。 例えば、プロセスの作成を制御しているディレクティブはメインサーバの コンテキストにのみ書くことができます。 どのディレクティブをどのセクションに書くことができるかを知るためには ディレクティブの コンテキスト を調べてください。詳しい情報は、 Directory, Location, Files セクションの動作法にあります。

.htaccess ファイル

関連モジュール 関連ディレクティブ
  • AccessFileName
  • AllowOverride

Apache ではウェブツリーの中に置かれた特別なファイルを使って 非中央集権的な設定管理をできます。その特別なファイルは普通は .htaccess という名前で、 AccessFileName ディレクティブでどんな名前にでも指定できます。 .htaccess ファイルに書かれたディレクティブはファイルを置いた ディレクトリとその全てのサブディレクトリに適用されます。 .htaccess ファイルはすべてのリクエストで読み込まれるため、 変更はすぐに反映されます。

どのディレクティブが .htaccess ファイルに書けるかを調べるには、ディレクティブのコンテキスト を調べてください。サーバ管理者はさらにメイン設定ファイルの AllowOverride を設定することでどのディレクティブを .htaccess ファイルに書けるようにするかを制御することができます。

.htaccess ファイルに関する詳しい情報は .htaccess チュートリアル を参照してください。


セクションの設定 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

セクションの設定

設定ファイル中のディレクティブは サーバ全体に適用されたり、特定のディレクトリやファイル、ホスト、URL にのみ 適用されるように制限したりすることができます。この文書は設定用のセクションの コンテナや .htaccess ファイルを使って他の設定ディレクティブの スコープを変更する方法を説明します。

設定用セクションコンテナの種類

関連モジュール 関連ディレクティブ
  • core
  • mod_proxy
  • <Directory>
  • <DirectoryMatch>
  • <Files>
  • <FilesMatch>
  • <IfDefine>
  • <IfModule>
  • <Location>
  • <LocationMatch>
  • <Proxy>
  • <ProxyMatch>
  • <VirtualHost>

コンテナには二つの基本となる種類があります。ほとんどのコンテナは 各リクエストに対して評価されます。その場合、コンテナ中のディレクティブは コンテナにマッチするリクエストにのみ適用されます。 一方、<IfDefine> コンテナと <IfModule> コンテナは サーバの起動時と再起動時にのみ評価されます。起動時に条件が真であれば、 コンテナ中のディレクティブはすべてのリクエストに適用されます。条件が 偽であれば、コンテナ中のディレクティブは無視されます。

<IfDefine> ディレクティブは httpd コマンドラインで適切なパラメータが定義されたときにのみ 適用されるディレクティブを囲います。例えば次の設定では、サーバが httpd -DClosedForNow を使って起動されたときだけすべての リクエストを別のサイトにリダイレクトします:

<IfDefine ClosedForNow>
Redirect / http://otherserver.example.com/
</IfDefine>

<IfModule> は 非常に似ていますが、代わりにサーバ上でモジュールが使用可能な場合にのみ 適用可能なディレクティブを囲います。モジュールはサーバに 静的に組み込まれているか、動的に組み込むようになっていて、設定ファイル中で LoadModule の行がより前の 部分に書かれている必要があります。このディレクティブは特定のモジュールの 存在に関わらず設定ファイルが動作する必要がある場合にのみ使ってください。 常に動作して欲しいディレクティブを囲むために使うべきではありません。 存在しないモジュールに関する有用なエラーメッセージの発生を抑制してしまいますので。

次の例では、mod_mime_magic があるときにのみ MimeMagicFiles ディレクティブが 適用されます。

<IfModule mod_mime_magic.c>
MimeMagicFile conf/magic
</IfModule>

<IfDefine> ディレクティブと <IfModule> ディレクティブは テストの前に "!" を付けることで否定の条件を適用することができます。 また、これらのセクションはより複雑な制限を課すために入れ子にすることができます。

ファイルシステムとウェブ空間

最もよく使われる設定のセクションコンテナはファイルシステムやウェブ空間の 特定の場所の設定を変更するものです。まず、この二つの違いを理解することが 大切です。ファイルシステムはオペレーティングシステムから見たディスクの内容です。 たとえば、デフォルトのインストールでは Apache は Unix ファイルシステムでは /usr/local/apache2 に、Windows ファイルシステムでは "c:/Program Files/Apache Group/Apache2" に存在します。 (Apache では Windows でもパスセパレータとしてスラッシュを使うことに 気をつけてください。) 対照的に、ウェブ空間はあなたのサイトを ウェブサーバから配信されるものとして見たもので、クライアントに見えるものです。 デフォルトの Unix 上の Apache のインストールではウェブ空間の /dir/ というパスはファイルシステムの /usr/local/apache2/htdocs/dir/ というパスに対応します。 ウェブページはデータベースや他の場所から動的に生成することもできますので、 ウェブ空間はファイルシステムに直接マップする必要はありません。

ファイルシステムコンテナ

<Directory> ディレクティブと <Files> ディレクティブ、それと それらの正規表現版はディレクティブをファイルシステムの一部分に対して適用します。 <Directory> セクションの 中のディレクティブは指定されたディレクトリとそのすべてのサブディレクトリに 適用されます。.htaccess ファイルを 使うことでも同じ効果を得ることができます。例えば、次の設定では /var/web/dir1 とすべてのサブディレクトリに対して ディレクトリインデックスを行ないます。

<Directory /var/web/dir1>
Options +Indexes
</Directory>

<Files> セクションの 中にあるディレクティブはどのディレクトリにあるかに関わらず、指定された名前の すべてのファイルに適用されます。ですから例えば以下の設定ディレクティブが 設定ファイルの主セクションに書かれたときには、すべての場所の private.html という名前のファイルへのアクセスを拒否します。

<Files private.html>
Order allow,deny
Deny from all
</Files>

ファイルシステムの特定の場所にあるファイルを指定するために、 <Files> セクションと <Directory> セクションを 組み合わせることができます。例えば、次の設定では /var/web/dir1/private.html, /var/web/dir1/subdir2/private.html, /var/web/dir1/subdir3/private.html など、 /var/web/dir1/ ディレクトリの下にあるすべての private.html へのアクセスを拒否します。

<Directory /var/web/dir1>
<Files private.html>
Order allow,deny
Deny from all
</Files>
</Directory>

ウェブ空間コンテナ

一方、<Location> ディレクティブとその正規表現版はウェブ空間上の内容に対して設定を変更します。 たとえば、次の設定では /private で始まる URL パスへのアクセスを制限します。 具体的には、 http://yoursite.example.com/private, http://yoursite.example.com/private123, http://yoursite.example.com/private/dir/file.html へのリクエストや、 他の同様に /private 文字列で始まるリクエストに 適用されます。

<Location /private>
Order Allow,Deny
Deny from all
</Location>

<Location> ディレクティブはファイルシステムと関係ある必要が全くありません。 たとえば次の例では、どのようにして特定の URL を mod_statusで提供されている Apache 内部ハンドラにマップするかを示しています。ファイルシステムに server-status というファイルが存在する必要はありません。

<Location /server-status>
SetHandler server-status
</Location>

ワイルドカードと正規表現

<Directory>, <Files>, <Location> ディレクティブでは、 C 標準ライブラリの fnmatch のように shell スタイルのワイルドカードキャラクタが使用できます。 "*" 文字は任意の文字列にマッチし、"?" 文字は任意の 1 文字にマッチし、 "[seq]" は seq の任意の文字にマッチします。 "/" 文字はどのワイルドカードでもマッチされません。 明示的に指定する必要があります。

これより柔軟なマッチングが必要な場合は、これらのコンテナに正規表現 (regex) 版である <DirectoryMatch>, <FilesMatch>, <LocationMatch> があり、マッチを選択するのに perl 互換正規表現を使用できます。しかし、次の設定のマージに目を通して、 regex セクションを使用することで、ディレクティブの適用がどのように 変化するか把握しておいてください。

全ユーザディレクトリの設定を変更する、非 regex ワイルドカードセクションは次のようになります。

<Directory /home/*/public_html>
Options Indexes
</Directory>

regex セクションを使用することで、画像ファイルの多くのタイプに対する アクセスを一度に拒否できます。

<FilesMatch \.(?i:gif|jpe?g|png)$>
Order allow,deny
Deny from all
</FilesMatch>

いつ何を使うか

ファイルシステムコンテナとウェブ空間コンテナを使い分けるのは、 実際には非常に簡単です。ファイルシステムに依存する オブジェクトにディレクティブを適応する場合は、必ず <Directory> か <Files> を使用します。ファイルシステムに依存しないオブジェクト (データベースから生成されるウェブページなど) にディレクティブを適用する際には、 <Location> を使用します。

ファイルシステム上のオブジェクトへのアクセスを制限するために、 <Location> を決して使用ないようにしましょう。 同一のファイルシステム位置にマップしている、ウェブ空間位置 (URL) が多数あって、設定した制限を迂回されてしまうかもしれないからです。 例えば次の設定を考えてみましょう。

<Location /dir/>
Order allow,deny
Deny from all
</Location>

http://yoursite.example.com/dir/ へのリクエストでは上手く動作します。しかし大文字小文字を区別しない ファイルシステムを使っていたらどうなるでしょう? http://yoursite.example.com/DIR/ へのリクエストで簡単にアクセス制限を迂回されてしまいます。これに対して <Directory> ディレクティブを使用すると、どのように呼び出されたかに関わらず その場所から提供される内容に適用されます。 (例外はファイルシステムのリンクです。シンボリックリンクを使って、 同一のディレクトリを複数のファイルシステムに設置できます。 <Directory> ディレクティブはパス名をリセットすることなくシンボリックリンクを 辿ります。ですから、高度なセキュリティが要求される場合は、 適切に Options ディレクティブを使用してシンボリックリンクを無効にするべきです。)

大文字小文字を区別するファイルシステムを使用しているから上記のことは 無関係だと思われるかもしれませんが、 同一のファイルシステム位置に複数のウェブ空間位置をマップする方法は、 他にいくらでもあるということを覚えていてください。 ですからできる限りファイルシステムコンテナを使用してください。 しかしながら一つだけ例外があります。 <Location /> セクションはどんな URL にも関わらず適用されるので、完全に安全です。

バーチャルホスト

<VirtualHost> コンテナは特定のホストに適用するディレクティブを格納します。 一台のマシンで複数のホストを異なる設定で提供したいときに有用です。 詳細に関してはバーチャルホストドキュメントを ご覧下さい。

プロクシ

<Proxy> と <ProxyMatch> コンテナは、特定の URL にマッチする mod_proxy プロクシサーバを経由してアクセスしたサイトに対してのみ適用される 設定ディレクティブを格納します。例えば次の設定は、cnn.com ウェブサイトにアクセスするために用いられるプロクシサーバを 制限します。

<Proxy http://cnn.com/*>
Order allow,deny
Deny from all
</Proxy>

どのディレクティブが使えるの?

どのタイプの設定セクションでどのディレクティブが使用できるかは、 ディレクティブの Context を見てください。 <Directory> で使用可能なものは全て、同様に <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, <LocationMatch>, <Proxy>, <ProxyMatch> セクションで使用可能です。しかしながら幾つか例外も存在します。

  • AllowOverride ディレクティブは <Directory> セクションでのみ使用可能です。
  • FollowSymLinks と SymLinksIfOwnerMatch の Options は、 <Directory> セクションか .htaccess ファイルでのみ使用可能です。
  • Options ディレクティブは、 <Files> と <FilesMatch> セクションでは使用できません。

セクションのマージ方法

マージの順番は以下のようになっています:

  1. <Directory> (正規表現無し) と .htaccess を同時に (.htaccess が許可されていれば、それが <Directory> を上書きします)
  2. <DirectoryMatch> (と <Directory ~>
  3. <Files> と <FilesMatch> を同時に
  4. <Location> と <LocationMatch> を同時に

<Directory> 以外は、それぞれのグループは設定ファイルに現れた順番に処理されます。 <Directory> (上のグループ 1) はディレクトリが短いものから長いものへと処理されます。ですから、 例えば <Directory /var/web/dir1> は <Directory /var/web/dir/subdir> の前に処理されます。複数の <Directory> セクションが 同じディレクトリに 適用される場合は、設定ファイル中の順番に従って処理されます。 Include によって挿入された設定は 挿入しているファイルの Include ディレクティブの位置にあったかのように扱われます。

<VirtualHost> セクション中のセクションは バーチャルホストの定義の外側の対応するセクションの 後に適用されます。これによりバーチャルホストが メインのサーバ設定を上書きできるようなります。

後のセクションのディレクティブが前のセクションのものを上書きします。

技術メモ

実際には、名前を変換する段階 (URL をファイル名にマップするために Alias や DocumentRoot が使用されるところ) の直前に <Location>/<LocationMatch> が行なわれます。 これらを適用した結果は変換が終わった後に完全に捨てられます。

例

次はマージの順番を示すための恣意的な例になっています。 リクエスト全てに適用されるとして、本例のディレクティブは A > B > C > D > E の順番に適用されます。

<Location />
E
</Location>

<Files f.html>
D
</Files>

<VirtualHost *>
<Directory /a/b>
B
</Directory>
</VirtualHost>

<DirectoryMatch "^.*b$">
C
</DirectoryMatch>

<Directory /a/b>
A
</Directory>

もっと具体的な、次の例を考えてみましょう。 <Directory> セクションに設置されたアクセス制限に関わらず、 <Location> セクションが最後に評価されて、サーバへのアクセスは制限されません。 言い換えれば、マージの順番は重要で、注意して使用してください!

<Location />
Order deny,allow
Allow from all
</Location>

# Woops! This <Directory> section will have no effect
<Directory />
Order allow,deny
Allow from all
Deny from badguy.example.com
</Directory>


サーバ全体の設定 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

サーバ全体の設定

このドキュメントではcore サーバのディレクティブの中で、 基本動作を設定するためのものを説明します。

サーバ ID

関連モジュール 関連ディレクティブ
  • ServerName
  • ServerAdmin
  • ServerSignature
  • ServerTokens
  • UseCanonicalName

ServerAdmin ディレクティブと ServerTokens ディレクティブは、エラーメッセージなどのサーバが作るドキュメントに、 どのようなサーバの情報を表示するかを制御します。 ServerTokens ディレクティブは、Server HTTP レスポンスヘッダフィールドの値を設定します。

ServerName ディレクティブと UseCanonicalName ディレクティブは、サーバが自分自身を参照する URL を作るときに使われます。 たとえば、クライアントがディレクトリを要求して、 そのディレクトリ名の最後にスラッシュが付いていないような場合には、 ドキュメントの相対的な参照を正しく解決できるようにするために、 Apache は最後のスラッシュを含んだ完全なパスにクライアントを リダイレクトさせる必要があります。

ファイルの位置

関連モジュール 関連ディレクティブ
  • CoreDumpDirectory
  • DocumentRoot
  • ErrorLog
  • LockFile
  • PidFile
  • ScoreBoardFile
  • ServerRoot

これらのディレクティブは Apache が適切な動作をするために必要な各種ファイルの位置を制御します。 パスがスラッシュ (/) で始まっていないときは、ファイルは ServerRoot からの相対パスとして 探されます。root 以外のユーザが書き込み可能なパスにファイルを置く場合は注意が必要です。 詳細は「セキュリティ情報」 を参照してください。

リソースの制限

関連モジュール 関連ディレクティブ
  • LimitRequestBody
  • LimitRequestFields
  • LimitRequestFieldsize
  • LimitRequestLine
  • RLimitCPU
  • RLimitMEM
  • RLimitNPROC
  • ThreadStackSize

LimitRequest* ディレクティブは Apache がクライアントからのリクエスト読み込みで使う リソースを制限するために使われます。これらの値を制限することで、 いくつかのサービス拒否攻撃は影響を和らげることができます。

RLimit* ディレクティブは、Apache の子プロセスから fork されたプロセスが使用するリソースを制限するために使われます。 特に、これは CGI スクリプトと SSI exec コマンドで使われるリソースを制御します。

ThreadStackSize は Netware でのみ、スタックの大きさを制御するために使われます。


ログファイル - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

ログファイル

ウェブサーバを効果的に管理するためには、サーバの活動やパフォーマンス、 今発生しているかもしれない問題に関するフィードバックを得ることが必要です。 Apache HTTP サーバには非常に包括的で柔軟なロギング機能があります。 この文書はロギング機能の設定の仕方と、ログに何が書かれているかを 理解するための方法を説明します。

セキュリティに関する警告

Apache がログファイルを書いているディレクトリに書き込める人は、 ほぼ確実にサーバが起動された uid へのアクセスを手に入れることができます。 そして、それは通常は root ユーザです。 ちゃんと結果を考えることなく、そのディレクトリへの 書き込み権限を与えないでください。詳しくは セキュリティのこつの文書を 読んでください。

加えて、ログファイルにはクライアントからの情報がそのまま、 エスケープされることなく書かれています。ですから、悪意のある クライアントがログファイルに制御文字を挿入することができます。 生のログを扱うときは注意してください。

エラーログ

関連モジュール 関連ディレクティブ
  • ErrorLog
  • LogLevel

ErrorLog ディレクティブにより 名前と場所が決まるサーバのエラーログは、一番重要なログファイルです。 Apache の診断情報はここに送られ、リクエストを処理しているときに 発生したエラーはすべてここに記録されます。サーバを起動したときや、 サーバの動作に問題が起こったときは、一番最初に調べるべき ところです。間違いの詳細や修正方法がそこに書かれていることが よくあります。

エラーログは普通はファイルに書かれます (通常 unix システムでは error_log、Windows と OS/2 では error.log)。 Unix システムではエラーを syslog や パイプでプログラムに送る ことができます。

エラーログの書式は比較的自由度の高いもので、説明的に書かれています。 ただし、いくつかの情報はほとんどのエラーログのエントリにあります。 例えば、代表的なものに次のようなメッセージがあります。

[Wed Oct 11 14:32:52 2000] [error] [client 127.0.0.1] client denied by server configuration: /export/home/live/ap/htdocs/test

ログエントリの最初の項目はメッセージの日付と時刻です。 二つめの項目は報告されているエラーの重要度です。 LogLevel で重要度のレベルを 制限することによりエラーログに送られるエラーの種類を制御することが できます。三つ目の項目はエラーを発生させたクライアントの IP アドレス です。残りはメッセージで、この場合はサーバがクライアントのアクセスを 拒否するように設定されている、ということを示しています。 サーバはリクエストされた文書の (ウェブのパスではなく) ファイルシステムの パスを報告します。

非常に広範囲のメッセージがエラーログに現れます。たいていのものは 上の例のような感じです。エラーログには CGI スクリプトのデバッグ 出力も書かれます。CGI スクリプトが stderr に書いた すべての情報は直接エラーログにコピーされます。

情報を追加したり削除したりしてエラーログをカスタマイズすることは できません。しかし、リクエストに対するエラーログのエントリは、 対応するエントリがアクセスログにあります。 例えば、上の例のエントリはアクセスログのステータスコード 403 の エントリに対応します。アクセスログはカスタマイズ可能ですので、 そちらを使うことによりエラーの状況に関する情報をより多く 手に入れることができます。

テストの最中は、問題が発生しているかどうかを見るために、 常にエラーログを監視するのが役に立つ場合がよくあります。 Unix システムでは、次のものを使うことができます。

tail -f error_log

アクセスログ

関連モジュール 関連ディレクティブ
  • mod_log_config
  • mod_setenvif
  • CustomLog
  • LogFormat
  • SetEnvIf

サーバアクセスログはサーバが処理をしたすべてのリクエストを 記録します。アクセスログの場所と内容は CustomLog ディレクティブにより決まります。ログの内容の選択を簡潔にするために LogFormat ディレクティブを使用することができます。このセクションはアクセスログに 情報を記録するためのサーバの設定方法を説明します。

もちろん、アクセスログに情報を蓄積することはログ管理の 始まりに過ぎません。次の段階は有用な統計を取るためにこの情報を 解析することです。一般的なログ解析はこの文書の範囲外で、 ウェブサーバ自身の仕事というわけでもありません。この話や、 ログ解析を行なうアプリケーションの情報を得るには、 Open Directory や Yahoo を調べてください。

いろんなバージョンの Apache httpd が mod_log_config, mod_log_agent, TransferLog ディレクティブといった、 他のモジュールやディレクティブを使ってアクセスのロギングを 制御してきました。今では、CustomLog がすべての古い ディレクティブの機能を含むようになっています。

アクセスログの書式は非常に柔軟な設定が可能です。 書式は C の printf(1) フォーマット文字列に非常に似た フォーマット文字列 により指定されます。いくつか次の節で例を示します。 フォーマット文字列に使用できる内容の一覧は mod_log_config の文書 を見てください。

Common Log Format

アクセスログのよくある設定に以下のものがあります。

LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common

これは、ニックネーム common を定義し、 ログのフォーマット文字列の一つと関連付けます。フォーマット文字列は パーセントディレクティブからなり、それぞれのパーセントディレクティブは サーバにどの情報をロギングするかを指示します。フォーマット文字列に 文字をそのまま入れることもでき、それらはログの出力に直接コピーされます。 そこに引用文字 (") を書くときは、 フォーマット文字列の最後として解釈 されることを防ぐためにバックスラッシュでエスケープする必要があります。 フォーマット文字列には改行用の "\n"、タブ用の "\t" という特別な制御文字も含めることができます。

CustomLog ディレクティブは 既に定義された ニックネーム を使って新しいログファイルを設定します。 アクセスログのファイル名はスラッシュで始まらない限り、 ServerRoot からの相対パスとして 扱われます。

上の設定は Common Log Format (CLF) と呼ばれる形式で ログエントリを書きます。この標準の形式は異なるウェブサーバの多くが 生成することができ、多くのログ解析プログラムが読みこむことができます。 CLF により生成されたログファイルのエントリは以下のようになります:

127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326

このログエントリのそれぞれの部分の意味は以下で説明します。

127.0.0.1 (%h)
これはサーバへリクエストをしたクライアント (リモートホスト) の IP アドレスです。HostnameLookups が On の場合は、サーバはホスト名を調べて、 IP アドレスが書かれているところに記録します。しかし、この設定は サーバをかなり遅くするので、あまりお勧めできません。 そうではなく、logresolve の ようなログの後処理を行なうプログラムでホスト名を調べるのが良いでしょう。 ここに報告される IP アドレスは必ずしもユーザが使っているマシンの ものであるとは限りません。ユーザとサーバの間にプロキシサーバが あれば、このアドレスは元のマシンのものではなく、プロキシの アドレスになります。
- (%l)
出力中の「ハイフン」は要求された情報が手に入らなかったということを 意味します。この場合、取得できなかった情報はクライアントのマシンの identd により決まる RFC 1413 のクライアントの アイデンティティです。この情報はあまり信用することができず、 しっかりと管理された内部ネットワークを除いては使うべきではありません。 Apache は IdentityCheck が On になっていない限り、この情報を得ようとすらしません。
frank (%u)
これは HTTP 認証による、ドキュメントをリクエストした人の ユーザ ID です。CGI スクリプトには通常同じ値が REMOTE_USER 環境変数として与えられます。リクエストのステータスコード (以下を参照) が 401 であった場合は、ユーザは認証に失敗しているので、 この値は信用できません。ドキュメントがパスワードで保護されていない 場合は、このエントリは前のものと同じように "-" に なります。
[10/Oct/2000:13:55:36 -0700] (%t)
サーバがリクエストの処理を終えた時刻です。書式は:

[day/month/year:hour:minute:second zone]
day = 2*digit
month = 3*letter
year = 4*digit
hour = 2*digit
minute = 2*digit
second = 2*digit
zone = (`+' | `-') 4*digit

ログのフォーマット文字列に %{format}t を 指定することで、別の形式で時刻を表示させることもできます。 このとき、format は C の標準ライブラリの strftime(3) の形式になります。
"GET /apache_pb.gif HTTP/1.0" (\"%r\")
クライアントからのリクエストが二重引用符の中に示されています。 リクエストには多くの有用な情報があります。まず、この場合クライアントが 使ったメソッドは GET です。次に、クライアントは リソース /apache_pb.gif を要求しました。そして、 クライアントはプロトコル HTTP/1.0 を使用しました。 リクエストの各部分を独立にログ収集することもできます。例えば、 フォーマット文字列 "%m %U%q %H" は メソッド、パス、クエリ文字列、プロトコルをログ収集し、 結局 "%r" とまったく同じ出力になります。
200 (%>s)
サーバがクライアントに送り返すステータスコードです。 この情報は、リクエストが成功応答 (2 で始まるコード) であったか、 リダイレクション (3 で始まるコード) であったか、クライアントによる エラー (4 で始まるコード) であったか、サーバのエラー (5 で始まるコード) であったか、を現すので、非常に大切です。ステータスコードの 完全なリストは HTTP 規格 (RFC2616 第 10 節) にあります。
2326 (%b)
この最後のエントリはクライアントに送信されたオブジェクトの、 応答ヘッダを除いたサイズを現します。コンテントがクライアントに送られなかった 場合は、この値は "-" になります。コンテントが無い場合に "0" をログ収集するには、%b ではなく %B を使ってください。

Combined Log Format

もう一つのよく使われる書式は Combined Log Format と呼ばれています。 以下のようにして使うことができます。

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" combined
CustomLog log/access_log combined

この書式の最初の方は Common Log Format とまったく同じで、最後に 二つ追加のエントリがあります。追加のエントリはパーセントディレクティブ %{header}i を使っています。ここで header は HTTP のリクエストヘッダのどれかです。この書式による アクセスログは以下のような感じになります:

127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326 "http://www.example.com/start.html" "Mozilla/4.08 [en] (Win98; I ;Nav)"

追加のエントリは:

"http://www.example.com/start.html" (\"%{Referer}i\")
"Referer" (意図的な綴り間違い) HTTP リクエストヘッダです。 これはクライアントが報告してくる参照元のサイトを表します。 (この場合は、/apache_pb.gif にリンクしているか、 それを含んでいるページです)。
"Mozilla/4.08 [en] (Win98; I ;Nav)" (\"%{User-agent}i\")
User-Agent HTTP リクエストヘッダです。これはクライアントのブラウザが 自分自身のことを報告してくる情報です。

複数のアクセスログ

複数のアクセスログは単に設定ファイルに複数の CustomLog ディレクティブを書くことで作成されます。例えば、以下のディレクティブは 三つのアクセスログを作ります。最初のものは基本的な CLF の情報で、 二つ目と三つ目は referer とブラウザの情報です。最後二つの CustomLog は ReferLog ディレクティブと AgentLog ディレクティブの効果をまねる方法を示しています。

LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common
CustomLog logs/referer_log "%{Referer}i -> %U"
CustomLog logs/agent_log "%{User-agent}i"

この例は LogFormat で ニックネームを定義する必要がない、 ということも示しています。ニックネームの代わりに、 CustomLog ディレクティブに 直接ログの書式を指定することができます。

条件付きログ

クライアントのリクエストの特徴に基づいてアクセスログにエントリの 一部をロギングしない方が便利なことがあります。これは 環境変数 の補助により簡単に実現できます。まず、 リクエストが何らかの条件に合うということを現すために環境変数が 設定される必要があります。これは通常は SetEnvIf により 行なわれます。そして、CustomLog ディレクティブの env= 節を使って環境変数が設定されているリクエストを 含めたり排除したりすることができます。いくつか例を挙げます:

# Mark requests from the loop-back interface
SetEnvIf Remote_Addr "127\.0\.0\.1" dontlog
# Mark requests for the robots.txt file
SetEnvIf Request_URI "^/robots\.txt$" dontlog
# Log what remains
CustomLog logs/access_log common env=!dontlog

他の例として、英語を話す人からのリクエストとそれ以外の人からのリクエストを 分けたい、という場合を考えてみてください。

SetEnvIf Accept-Language "en" english
CustomLog logs/english_log common env=english
CustomLog logs/non_english_log common env=!english

ここまででは条件付きロギングが非常に強力で柔軟であることを示してきましたが、 それがログの内容を制御する唯一の方法というわけではありません。ログファイルは サーバの活動の完全な記録である方がより役に立ちます。単純にログファイルを 後処理して、考慮したくないログを削除する方が簡単であることがよくあります。

ログの交替

普通の負荷のサーバでさえ、ログファイルに保存される情報の量は 膨大になります。アクセスログのファイルは普通 10,000 リクエスト毎に 1 MB 以上増えます。ですから、既存のログを移動したり、削除したりして、 定期的にログを交替させることが必要になります。これはサーバの実行中には 行なえません。というのは、Apache はファイルが open されている間は ずっと古いログファイルに書き続けるからです。 新しいログファイルを open できるように、ログファイルが移動されたり 削除された後に、サーバを再起動する 必要があります。

優雅な 再起動を行なうことで、サーバは既存のコネクションや 処理待ちのコネクションを失うことなく新しいログファイルを open させる ことができます。しかし、これを実現するために、サーバは古いリクエストを 扱っている間は古いログファイルに書き続ける必要があります。 ですから、再起動の後ではログファイルの処理を始める前に、しばらく待たなければ なりません。単にログを交替させて、ディスクの節約のために古いログを 圧縮する普通のシナリオは:

mv access_log access_log.old
mv error_log error_log.old
apachectl graceful
sleep 600
gzip access_log.old error_log.old

ログの交替をするもう一つの方法はパイプ経由のログを使うもので、次の節で説明されています。

パイプ経由のログ

Apache httpd はエラーログとアクセスログをファイルに直接書く代わりに、 パイプを通して別のプログラムに書き出すことができます。 この機能により、主サーバにコードを追加することなく ロギングの柔軟性が非常に高まっています。パイプにログを書くためには、 単にファイル名をパイプ文字 "|" に置き換え、その続きに 標準入力からログのエントリを受けとる実行プログラムの名前を書くだけです。 Apache はパイプ経由のログ用のプロセスをサーバの起動時に実行し、 サーバの実行中にそのプログラムがクラッシュしたときはそれを再び 実行します。(この最後の機能がこの技術が「信頼性のあるパイプ経由のロギング」 と呼ばれている理由です。)

パイプ経由のログ用のプロセスは Apache httpd の親プロセスから起動され、 そのプロセスのユーザ ID を継承します。これは、これは、パイプ経由のログ用の プログラムは普通 root として実行されることを意味します。 ですから、プログラムを簡単で安全に保つことが非常に重要です。

パイプ経由のログの重要な利用法は、サーバの再起動なしでログの交替を することです。Apache HTTP サーバにはこのための rotatelogs と呼ばれる簡単な プログラムが付属しています。たとえば、24 時間毎にログを交替させるには、 以下のものを使うことができます:

CustomLog "|/usr/local/apache/bin/rotatelogs /var/log/access_log 86400" common

パイプの先で呼ばれるコマンド全体が引用符で囲まれていることに注目して ください。この例はアクセスログを使っていますが、エラーログにも同じ技術を 使うことができます。

似ているけれど、よりずっと柔軟な cronolog というログ交替用の プログラムが外部のサイトにあります。

条件付きロギングと同様、パイプ経由のログは非常に強力な 道具ですが、オフラインの後処理のような、より簡単な解決方法があるときは 使わない方が良いでしょう。

バーチャルホスト

多くの バーチャルホスト のあるサーバを実行している ときは、ログファイルの扱い方にいくつかの方法があります。 まず、単独のホストのみのサーバとまったく同じようにログを使うことができます。 ロギングディレクティブを主サーバのコンテキストの <VirtualHost> セクションの外に置くことで、 すべてのログを同じアクセスログとエラーログにログ収集することができます。 この手法では個々のバーチャルホストの統計を簡単にとることはできません。

>CustomLog や ErrorLog ディレクティブが <VirtualHost> の中に 置かれた場合は、そのバーチャル ホストへのすべてのリクエストやエラーがそこで指定されたファイルにのみ ログ収集されます。ロギングディレクティブのないバーチャルホストは 依然としてリクエストが主サーバのログに送られます。この手法は少ない バーチャルホストに対しては非常に有用ですが、ホストの数が非常に多くなると 管理が大変になります。さらに、ファイル記述子の限界の問題を起こすことが あります。

アクセスログには、非常に良い妥協案があります。バーチャルホストの 情報をログのフォーマット文字列に加えることで、すべてのホストへの リクエストを同じログにログ収集して、後でログを個々のファイルに分割することが できます。たとえば、以下のディレクティブを見てください。

LogFormat "%v %l %u %t \"%r\" %>s %b" comonvhost
CustomLog logs/access_log comonvhost

%v がリクエストを扱っているバーチャルホストの名前を ログ収集するために使われています。そして、split-logfile のようなプログラムを 使ってアクセスログを後処理することで、 バーチャルホスト毎のファイルにログを分割することができます。

残念ながら、エラーログには同様の手法はありません。ですから、 すべてのバーチャルホストを同じエラーログの中に混ぜるか、 バーチャルホスト毎にエラーログを使うかを選ばなければなりません。

他のログファイル

関連モジュール 関連ディレクティブ
  • mod_cgi
  • mod_rewrite
  • PidFile
  • RewriteLog
  • RewriteLogLevel
  • ScriptLog
  • ScriptLogBuffer
  • ScriptLogLength

PID ファイル

起動時に、Apache は親 httpd プロセスのプロセス ID を logs/httpd.pid に保存します。この ファイル名は PidFile ディレクティブを使って 変更することができます。プロセス ID は管理者が親プロセスに シグナルを送ることでデーモンを再起動したり終了させたりするときに 使用します。Windows では、代わりに -k コマンドオプションを 使ってください。詳しい情報は 終了と 再起動 のページを見てください。

スクリプトログ

デバッグの補助のために、ScriptLog ディレクティブは CGI スクリプトの入力と出力を記録するようにできます。 これはテスト用にのみ使用して、通常のサーバでは使用しないでください。 詳しい情報は mod_cgi の文書 にあります。

リライトログ

mod_rewrite の強力で 複雑な機能を 使っているときは、ほぼいつもデバッグを簡単にするために RewriteLog の使用が 必要でしょう。このログファイルにはリライトエンジンがリクエストを 書き換える方法の詳細な解析が出力されます。詳しさの度合は RewriteLogLevel で制御できます。


URL からファイルシステム上の位置へのマップ - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

URL からファイルシステム上の位置へのマップ

この文書は Apache がリクエストの URL から送信するファイルの ファイルシステム上の位置を決定する方法を説明します。

関連するモジュールとディレクティブ

関連モジュール 関連ディレクティブ
  • mod_alias
  • mod_proxy
  • mod_rewrite
  • mod_userdir
  • mod_speling
  • mod_vhost_alias
  • Alias
  • AliasMatch
  • CheckSpelling
  • DocumentRoot
  • ErrorDocument
  • Options
  • ProxyPass
  • ProxyPassReverse
  • Redirect
  • RedirectMatch
  • RewriteCond
  • RewriteMatch
  • ScriptAlias
  • ScriptAliasMatch
  • UserDir

DocumentRoot

リクエストに対してどのファイルを送信するかを決定するときの Apache のデフォルトの動作は、リクエストの URL-Path (URL のホスト名と ポート番号の後に続く部分) を取り出して設定ファイルで指定されている DocumentRoot の最後に追加する、というものです。ですから、 DocumentRoot の下のディレクトリやファイルがウェブから見える基本のドキュメントの木構造を なします。

Apache にはサーバが複数のホストへのリクエストを受け取る バーチャルホスト の機能もあります。 この場合、それぞれのバーチャルホストに対して違う DocumentRoot を指定することができます。また、mod_vhost_alias モジュールにより提供されるディレクティブを使って、 送信するためのコンテンツの場所をリクエストされた IP アドレスやホスト名から動的に決めることもできます。

DocumentRoot 外のファイル

ファイルシステム上の、 厳密には DocumentRoot の下にはない部分へのウェブアクセスを許可する必要がある 場合がよくあります。Apache はこのために複数の方法を用意しています。 Unix システムでは、ファイルシステムの他の部分をシンボリックリンクを 使って DocumentRoot の下に持ってくることができます。セキュリティ上の理由により、 Apache は該当するディレクトリの Options の設定に FollowSymLinks か SymLinksIfOwnerMatch が ある場合にのみシンボリックリンクをたどります。

代わりの方法として、Alias ディレクティブを使ってファイルシステムの任意の部分をウェブの空間に マップできます。たとえば、

Alias /docs /var/web

という設定のときは、URL http://www.example.com/docs/dir/file.html には /var/web/dir/file.html が送信されます。 ScriptAlias も、 対象となっているパスが CGI スクリプトとして扱われるという追加の 効果以外は同じように動作します。

もっと柔軟な設定が必要な状況では、 AliasMatch ディレクティブや ScriptAliasMatch ディレクティブ を使って強力な正規表現に基づいたマッチと置換を行なうことができます。 たとえば、

ScriptAliasMatch ^/~([a-zA-Z0-9]+)/cgi-bin/(.+) /home/$1/cgi-bin/$2

は http://example.com/~user/cgi-bin/script.cgi への リクエストを /home/user/cgi-bin/script.cgi というパスへ マップし、このマップの結果としてのファイルを CGI スクリプトとして 扱います。

ユーザディレクトリ

伝統的に Unix システムではユーザ user のホームディレクトリを ~user/ として参照できます。mod_userdir モジュールはこの概念をウェブに拡張して、 それぞれのユーザのホームディレクトリのファイルを 以下のような URL を使ってアクセスできるようにします。

http://www.example.com/~user/file.html

セキュリティの観点から、ウェブからユーザのホームディレクトリへ 直接アクセスできるようにすることは適切ではありません。ですから、 UserDir ディレクティブには ユーザのホームディレクトリの下の、ウェブファイルの 置かれているディレクトリを指定します。デフォルトの設定の Userdir public_html を使うと、上の URL は /home/user/public_html/file.html というようなファイルに マップされます。ここで、/home/user/ は /etc/passwd で指定されているユーザのホームディレクトリです。

Userdir には、 /etc/passwd にホームディレクトリの位置が書かれていない システムでも使うことのできる他の形式もあります。

中にはシンボル "~" (%7e のように符号化されることが多い) を格好が悪いと思って、ユーザのディレクトリを表すために別の文字列の 使用を好む人がいます。mod_userdir はこの機能をサポートしていません。 しかし、ユーザのホームディレクトリが規則的な構成のときは、 AliasMatch を使って望みの 効果を達成することができます。たとえば、 http://www.example.com/upages/user/file.html が /home/user/public_html/file.html にマップされるようにするには、 以下のように AliasMatch ディレクティブを使います:

AliasMatch ^/upages/([a-zA-Z0-9]+)/?(.*) /home/$1/public_html/$2

URL リダイレクション

上の節で説明した設定用のディレクティブは Apache に ファイルシステムの特定の場所からコンテンツを取ってきて クライアントに送り返すようにします。ときには、その代わりに クライアントにリクエストされたコンテンツは別の URL にあることを 知らせて、クライアントが新しい URL へ新しいリクエストを行なうように する方が望ましいことがあります。これはリダイレクションと 呼ばれていて、Redirect ディレクティブにより実装されています。たとえば、 DocumentRoot の下のディレクトリ /foo/ が新しいディレクトリ /bar/ に移動したときは、 以下のようにしてクライアントが新しい場所のコンテンツをリクエストするように 指示することができます:

Redirect permanent /foo/ http://www.example.com/bar/

これは、/foo/ で始まるすべての URL-Path を、 www.example.com サーバの /bar/ が /foo/ に置換されたものにリダイレクトします。 サーバは自分自身のサーバだけでなく、どのサーバにでもクライアントを リダイレクトすることができます。

Apache はより複雑な書き換えの問題のために、 RedirectMatch ディレクティブを 提供しています。たとえば、サイトのホームページを違うサイトにリダイレクト するけれど、他のリクエストはそのまま扱う、というときは以下の設定を 使います:

RedirectMatch permanent ^/$ http://www.example.com/startpage.html

あるいは、一時的にサイトのすべてのページを他のサイトの特定の ページへリダイレクトするときは、以下を使います:

RedirectMatch temp .* http://othersite.example.com/startpage.html

リバースプロキシ

Apache は遠隔地にあるドキュメントをローカルのサーバの URL 空間に 持ってくることもできます。この手法はリバースプロキシと呼ばれています。 ウェブサーバが遠隔地のドキュメントを取得してクライアントに送り返すのが プロキシサーバの動作のように見えるからです。クライアントにはドキュメントが リバースプロキシサーバから送られてきているように見える点が通常の プロキシとは異なります。

次の例では、クライアントが /foo/ ディレクトリの下にある ドキュメントをリクエストすると、サーバが internal.example.com の /bar/ ディレクトリから取得して、さもローカルサーバからの ドキュメントのようにしてクライアントに返します。

ProxyPass /foo/ http://internal.example.com/bar/
ProxyPassReverse /foo/ http://internal.example.com/bar/

ProxyPass ディレクティブは サーバが適切なドキュメントを取得するように設定し、 ProxyPassReverse ディレクティブは internal.example.com からのリダイレクトがローカルサーバの 適切なディレクトリを指すように書き換えます。ただし、ドキュメントの中の リンクは書き換えられない、ということは知っておいてください。 ですから、internal.example.com への絶対パスによるリンクでは、 クライアントがプロキシサーバを抜け出して internal.example.com に 直接リクエストを送る、ということになります。

リライトエンジン

より一層強力な置換が必要なときは、mod_rewrite が提供するリライトエンジンが役に立つでしょう。 このモジュールにより提供されるディレクティブは ブラウザの種類、リクエスト元の IP アドレスなどのリクエストの特徴を 使って送り返すコンテンツの場所を決めます。さらに、mod_rewrite は外部のデータベースファイルやプログラムを使ってリクエストの扱い方を 決めることもできます。リライトエンジンは上で挙げられている三つのマッピング すべてを行なうことができます: 内部のリダイレクト (エイリアス)、 外部のリダイレクト、プロキシです。mod_rewrite を使う多くの実用的な例は URL リライトガイド で説明されています。

File Not Found

必ず、リクエストされた URL に対応するファイルがファイルシステムに 無いという場合が発生します。これが起こるのにはいくつかの理由があります。 場合によっては、ドキュメントを別の場所に移動した結果であることがあります。 この場合は、クライアントにリソースの新しい位置を知らせるために URL リダイレクションを使うのが最善の方法です。 そうすることによって、リソースは新しい位置に移動しているけれども、 古いブックマークやリンクが動作し続けるようにすることができます。

"File Not Found" エラーのもう一つのよくある理由は、 ブラウザへの直接入力や HTML リンクからの偶発的な URL の入力間違いです。 Apache はこの問題を改善するために、mod_speling モジュール (意図的な綴り間違い) (訳注: 正しくは spelling) を提供しています。このモジュールが 使用されているときは、"File Not Found" エラーを横取りして、 似たファイル名のリソースを探します。もし一つだけ見つかった場合は mod_speling はクライアントに正しい位置を知らせるために HTTP リダイレクトを 送ります。もし複数の「近い」ファイルが見つかった場合は、それら 代替となりえるもののリストがクライアントに表示されます。

mod_speling の非常に有用な機能は、大文字小文字を区別せずに ファイル名を比較するものです。これは URL と unix の ファイルシステムが両方とも大文字小文字を区別するものである、 ということをユーザが知らないシステムで役に立ちます。ただし、 時折の URL 訂正程度で済まず、mod_speling をより多く使用すると、サーバに さらなる負荷がかかります。すべての「正しくない」リクエストの後に URL のリダイレクトとクライアントからの新しいリクエストがくることに なりますから。

コンテンツの位置を決めようとするすべての試みが失敗すると、 Apache は、HTTP ステータスコード 404 (file not found) と共に エラーページを返します。このエラーページの外観は ErrorDocument ディレクティブで制御され、 カスタムエラーレスポンス と 国際化サーバエラーレスポンス で 説明されているように、柔軟な設定を行なうことができます。


Security Tips - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Miscellaneous Documentation

Security Tips

Some hints and tips on security issues in setting up a web server. Some of the suggestions will be general, others specific to Apache.

Keep up to Date

The Apache HTTP Server has a good record for security and a developer community highly concerned about security issues. But it is inevitable that some problems -- small or large -- will be discovered in software after it is released. For this reason, it is crucial to keep aware of updates to the software. If you have obtained your version of the HTTP Server directly from Apache, we highly recommend you subscribe to the Apache HTTP Server Announcements List where you can keep informed of new releases and security updates. Similar services are available from most third-party distributors of Apache software.

Of course, most times that a web server is compromised, it is not because of problems in the HTTP Server code. Rather, it comes from problems in add-on code, CGI scripts, or the underlying Operating System. You must therefore stay aware of problems and updates with all the software on your system.

Permissions on ServerRoot Directories

In typical operation, Apache is started by the root user, and it switches to the user defined by the User directive to serve hits. As is the case with any command that root executes, you must take care that it is protected from modification by non-root users. Not only must the files themselves be writeable only by root, but so must the directories, and parents of all directories. For example, if you choose to place ServerRoot in /usr/local/apache then it is suggested that you create that directory as root, with commands like these:

mkdir /usr/local/apache
cd /usr/local/apache
mkdir bin conf logs
chown 0 . bin conf logs
chgrp 0 . bin conf logs
chmod 755 . bin conf logs

It is assumed that /, /usr, and /usr/local are only modifiable by root. When you install the httpd executable, you should ensure that it is similarly protected:

cp httpd /usr/local/apache/bin
chown 0 /usr/local/apache/bin/httpd
chgrp 0 /usr/local/apache/bin/httpd
chmod 511 /usr/local/apache/bin/httpd

You can create an htdocs subdirectory which is modifiable by other users -- since root never executes any files out of there, and shouldn't be creating files in there.

If you allow non-root users to modify any files that root either executes or writes on then you open your system to root compromises. For example, someone could replace the httpd binary so that the next time you start it, it will execute some arbitrary code. If the logs directory is writeable (by a non-root user), someone could replace a log file with a symlink to some other system file, and then root might overwrite that file with arbitrary data. If the log files themselves are writeable (by a non-root user), then someone may be able to overwrite the log itself with bogus data.

Server Side Includes

Server Side Includes (SSI) present a server administrator with several potential security risks.

The first risk is the increased load on the server. All SSI-enabled files have to be parsed by Apache, whether or not there are any SSI directives included within the files. While this load increase is minor, in a shared server environment it can become significant.

SSI files also pose the same risks that are associated with CGI scripts in general. Using the "exec cmd" element, SSI-enabled files can execute any CGI script or program under the permissions of the user and group Apache runs as, as configured in httpd.conf.

There are ways to enhance the security of SSI files while still taking advantage of the benefits they provide.

To isolate the damage a wayward SSI file can cause, a server administrator can enable suexec as described in the CGI in General section

Enabling SSI for files with .html or .htm extensions can be dangerous. This is especially true in a shared, or high traffic, server environment. SSI-enabled files should have a separate extension, such as the conventional .shtml. This helps keep server load at a minimum and allows for easier management of risk.

Another solution is to disable the ability to run scripts and programs from SSI pages. To do this replace Includes with IncludesNOEXEC in the Options directive. Note that users may still use <--#include virtual="..." --> to execute CGI scripts if these scripts are in directories desginated by a ScriptAlias directive.

CGI in General

First of all, you always have to remember that you must trust the writers of the CGI scripts/programs or your ability to spot potential security holes in CGI, whether they were deliberate or accidental. CGI scripts can run essentially arbitrary commands on your system with the permissions of the web server user and can therefore be extremely dangerous if they are not carefully checked.

All the CGI scripts will run as the same user, so they have potential to conflict (accidentally or deliberately) with other scripts e.g. User A hates User B, so he writes a script to trash User B's CGI database. One program which can be used to allow scripts to run as different users is suEXEC which is included with Apache as of 1.2 and is called from special hooks in the Apache server code. Another popular way of doing this is with CGIWrap.

Non Script Aliased CGI

Allowing users to execute CGI scripts in any directory should only be considered if:

  • You trust your users not to write scripts which will deliberately or accidentally expose your system to an attack.
  • You consider security at your site to be so feeble in other areas, as to make one more potential hole irrelevant.
  • You have no users, and nobody ever visits your server.

Script Aliased CGI

Limiting CGI to special directories gives the admin control over what goes into those directories. This is inevitably more secure than non script aliased CGI, but only if users with write access to the directories are trusted or the admin is willing to test each new CGI script/program for potential security holes.

Most sites choose this option over the non script aliased CGI approach.

Other sources of dynamic content

Embedded scripting options which run as part of the server itself, such as mod_php, mod_perl, mod_tcl, and mod_python, run under the identity of the server itself (see the User directive), and therefore scripts executed by these engines potentially can access anything the server user can. Some scripting engines may provide restrictions, but it is better to be safe and assume not.

Protecting System Settings

To run a really tight ship, you'll want to stop users from setting up .htaccess files which can override security features you've configured. Here's one way to do it.

In the server configuration file, put

<Directory />
AllowOverride None
</Directory>

This prevents the use of .htaccess files in all directories apart from those specifically enabled.

Protect Server Files by Default

One aspect of Apache which is occasionally misunderstood is the feature of default access. That is, unless you take steps to change it, if the server can find its way to a file through normal URL mapping rules, it can serve it to clients.

For instance, consider the following example:

# cd /; ln -s / public_html
Accessing http://localhost/~root/

This would allow clients to walk through the entire filesystem. To work around this, add the following block to your server's configuration:

<Directory />
Order Deny,Allow
Deny from all
</Directory>

This will forbid default access to filesystem locations. Add appropriate Directory blocks to allow access only in those areas you wish. For example,

<Directory /usr/users/*/public_html>
Order Deny,Allow
Allow from all
</Directory>
<Directory /usr/local/httpd>
Order Deny,Allow
Allow from all
</Directory>

Pay particular attention to the interactions of Location and Directory directives; for instance, even if <Directory /> denies access, a <Location /> directive might overturn it

Also be wary of playing games with the UserDir directive; setting it to something like "./" would have the same effect, for root, as the first example above. If you are using Apache 1.3 or above, we strongly recommend that you include the following line in your server configuration files:

UserDir disabled root

Watching Your Logs

To keep up-to-date with what is actually going on against your server you have to check the Log Files. Even though the log files only reports what has already happened, they will give you some understanding of what attacks is thrown against the server and allows you to check if the necessary level of security is present.

A couple of examples:

grep -c "/jsp/source.jsp?/jsp/ /jsp/source.jsp??" access_log
grep "client denied" error_log | tail -n 10

The first example will list the number of attacks trying to exploit the Apache Tomcat Source.JSP Malformed Request Information Disclosure Vulnerability, the second example will list the ten last denied clients, for example:

[Thu Jul 11 17:18:39 2002] [error] [client foo.bar.com] client denied by server configuration: /usr/local/apache/htdocs/.htpasswd

As you can see, the log files only report what already has happened, so if the client had been able to access the .htpasswd file you would have seen something similar to:

foo.bar.com - - [12/Jul/2002:01:59:13 +0200] "GET /.htpasswd HTTP/1.1"

in your Access Log. This means you probably commented out the following in your server configuration file:

<Files ~ "^\.ht">
Order allow,deny
Deny from all
<Files>


動的共有オブジェクト (DSO) サポート - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

動的共有オブジェクト (DSO) サポート

Apache HTTP サーバはモジュール化されたプログラムで、 管理者がモジュールを選択することでサーバに組み込む機能を選ぶことができます。 モジュールはサーバがビルドされるときに httpd バイナリに 静的に組み込むことができます。もしくは、httpd バイナリとは 別に存在する動的共有オブジェクト (訳注: Dynamic Shared Object) (DSO) としてコンパイルすることも できます。DSO モジュールはサーバがビルドされるときにコンパイルしたり、 Apache 拡張ツール (apxs) を 使って後でコンパイルして追加したりできます。

この文書は DSO モジュールの使い方と、仕組みについて 説明します。

実装

関連モジュール 関連ディレクティブ
  • mod_so
  • LoadModule

個々の Apache モジュールをロードするための DSO サポートは mod_so.c というモジュールの機能に基づいています。 このモジュール は Apache のコアに静的に組み込まれている必要があります。 それは core.c 以外では DSO にできない唯一の モジュールです。事実上、他のすべての Apache のモジュールは、 インストールの文書で説明されているように、 configure の --enable-module=shared オプションでそれぞれを DSO ビルドにすることにより、DSO モジュールにすることができます。 mod_foo.so のような DSO にモジュールがコンパイルされれば、 httpd.conf ファイル中で mod_so の LoadModule ディレクティブを使うことでサーバの起動や再起動時にこのモジュールを ロードするようにできます。

Apache モジュール用の (特にサードパーティモジュールの) DSO ファイルの 作成を簡単にするために、apxs (APache eXtenSion) という新しいサポートプログラムがあります。 Apache のソースツリーの外で DSO モジュールをビルドするために 使うことができます。発想は単純です: Apache のインストール時の configure、make install のときに Apache の C ヘッダをインストールし、DSO ビルド用のプラットフォーム依存の コンパイラとリンカのフラグを apxs プログラムに追加します。 これにより、ユーザが Apache の配布ソースツリーなしで、さらに DSO サポートのためのプラットフォーム依存のコンパイラやリンカの フラグをいじることなく Apache のモジュールのソースをコンパイル できるようになります。

使用法の概要

Apache 2.0 の DSO 機能の概略を知ることができるための、 短く簡潔な概要です:

  1. 配布されている Apache モジュール、仮に mod_foo.c として、それを DSO mod_foo.so にビルド、インストール:

    $ ./configure --prefix=/path/to/install --enable-foo=shared
    $ make install

  2. サードパーティ Apache モジュール、仮に mod_foo.c として、それを DSO mod_foo.so にビルド、インストール:

    $ ./configure --add-module=module_type:/path/to/3rdparty/mod_foo.c --enable-foo=shared
    $ make install

  3. 共有モジュールの 後々のインストール のために Apache を設定:

    $ ./configure --enable-so
    $ make install

  4. サードパーティ Apache モジュール、仮に mod_foo.c として、それを apxs を使って Apache ソースツリーの外で DSO にビルド、インストール:

    $ cd /path/to/3rdparty
    $ apxs -c mod_foo.c
    $ apxs -i -a -n foo mod_foo.la

どの場合においても、共有モジュールをコンパイルした後で、 httpd.conf で LoadModule ディレクティブを使って Apache がモジュールを使用するように しなければなりません。

背景

最近の Unix 系の OS には 動的共有オブジェクト (DSO) の動的リンク/ロードという気のきいた機構が 存在します。これは、実行時にプログラムのアドレス空間に ロードできるような特別な形式でプログラムをビルドすることを 可能にします。

このロードは二つの方法で行なうことができます: 実行プログラムが 起動されたときに ld.so というシステムプログラム により自動的に行なわれる方法と、実行プログラム中から、システムコール dlopen()/dlsym() による Unix ローダへの プログラムシステムのインタフェースを使って手動で行なう方法とが あります。

最初の方法では DSO は普通は共有ライブラリや DSO ライブラリ と呼ばれていて、DSO の名前は libfoo.so や libfoo.so.1.2 のようになっています。 これらはシステムディレクトリ (通常 /usr/lib) に存在し、 実行プログラムへのリンクはビルド時に -lfoo をリンカに 指定することで確立されます。これによりライブラリへの参照が実行プログラムの ファイルに書き込まれて、起動時に Unix のローダが /usr/lib や、 リンカの -R のようなオプションによりハードコードされたパス、 環境変数 LD_LIBRARY_PATH により設定されたパス、の中から libfoo.so の場所を見つけることができます。それから、 実行プログラム中の (まだ未解決の) シンボルを DSO にあるシンボルで 解決します。

普通は実行プログラム中のシンボルは DSO からは参照されません (DSO は一般的なコードによる再利用可能なライブラリですので)。 ですから、さらなるシンボルの解決は必要ありません。 シンボルは Unix ローダにより完全な解決が行なわれますので、実行ファイル自身は 何もする必要がありません。(実際のところ、静的でない方法でリンクされている すべての実行プログラムに組み込まれている開始用のコードの一部に ld.so を起動するコードが含まれています)。よく使われる ライブラリの動的ロードの利点は明らかです。ライブラリのコードは システムライブラリに libc.so のようにして一度保存するだけでよく、 プログラムのために必要なディスクの領域を節約することができます。

二つめの方法では DSO は普通は共有オブジェクトや DSO ファイルと呼ばれていて、任意の拡張子を付けることができます (ただし、標準的な名前は foo.so です)。 これらのファイルは通常はプログラム専用のディレクトリに置かれ、 これらを使う実行プログラムへのリンクは自動的にはされません。 ですので、実行プログラムは dlopen() を使って 実行時に手動で DSO をプログラムのアドレス空間にロードする必要があります。 この時点では実行プログラムに対して DSO のシンボルの解決は行なわれません。 しかし、その代わりに Unix のローダが DSO の (まだ未解決の) シンボルを 実行プログラムによりエクスポートされたシンボルと既にロードされた DSO ライブラリによりエクスポートされたシンボル (特に、どこにでもある libc.so のすべてのシンボル) で自動的に解決します。 こうすることで、DSO は最初から静的にリンクされていたかのように、 実行プログラムのシンボルを知ることができます。

最後に、DSO の API を利点を生かすために、プログラムは 後でディスパッチテーブルなどでシンボルを使うことができるように、 dlsym() を使っていくつかのシンボルを解決します。 すなわち: 実行プログラムは必要なすべてのシンボルを手動で解決しなければ なりません。この機構の利点はプログラムのオプショナルな部分は 必要になるまでロードする必要がない (だからメモリも消費しない) ことです。必要ならば、基本プログラムの機能を拡張するために これらの部分を動的にロードすることができます。

この DSO 機構は簡単なように見えますが、少なくとも一つ難しい点が あります: プログラムを拡張するために DSO を使っているときに、 DSO が実行プログラムからシンボルを解決する点です (二番目の方法)。 これはなぜでしょうか。それは、DSO のシンボルを実行プログラムの シンボルから「逆解決」するというのはライブラリの設計 (ライブラリはそれを使用するプログラムのことは何も 知らない) に反していて、この機能はすべてのプラットフォームに あるわけではなく、標準化もされていないからです。 実際には実行プログラムのグローバルなシンボルは再エクスポートされることは あまりなく、DSO から使うことができません。リンカにグローバルシンボルすべてを エクスポートするようにさせる方法を見つけることが、実行時にプログラムを 拡張するために DSO を使うときの一番の問題です。

共有ライブラリのアプローチが普通の方法です。DSO 機構はそのために 設計されたものですから。したがって、その方法はオペレーティングシステムが 提供するほとんどすべての種類のライブラリで使われています。 一方、プログラムの拡張のために共有オブジェクトを使用する、という方は あまり使われていません。

1998 年の時点で、実行時に実際に機能拡張のために DSO 機構を使っている ソフトウェアパッケージは少しだけでした: Perl 5 (XS 機構と DnaLoader モジュール によるもの)、Netscape サーバなどです。Apache はすでに モジュールの概念を使って機能拡張をしていて、内部的にディスパッチリストに 基づいた外部モジュールの Apache コア機能へのリンクを行なっていましたので、 バージョン 1.3 から、Apache も DSO 機構を使う仲間になりました。 Apache は実行時に DSO を使ってモジュールをロードするようにすでに 運命付けられていたのです。

利点と欠点

上記の DSO に基づいた機能は以下の利点があります:

  • 実際のサーバプロセスを組み立てるために、 ビルド時に configure のオプションを使う代わりに 実行時に httpd.conf の設定用コマンド LoadModule を使うことができますので、サーバパッケージの柔軟性が高まりました。 たとえば、一つの Apache のインストールから 違う構成のサーバ (標準版と SSL 版、最小構成と拡張版 [mod_perl, PHP3] など) を実行することができます。
  • インストールの後であっても、サーバのパッケージをサードパーティ モジュールで簡単に拡張できるようになりました。これは、Apache コア パッケージと、PHP3, mod_perl, mod_fastcgi など の追加の パッケージを作成できるので、少なくともベンダのパッケージ管理者にとって 大きな利点があります。
  • Apache モジュールの開発が簡単になります。 これは DSO/apxs の組み合わせにより、Apache ソースツリーの 外で作業でき、開発中のモジュールの新しいバージョンを 実行中の Apache サーバに組み込むために apxs -i と apachectl restart を行なうだけで良くなるからです。

DSO には以下の欠点があります:

  • すべてのオペレーティングシステムがプログラムのアドレス空間に コードを動的ロードすることをサポートしているわではないので、 プラットフォームによっては DSO 機構は使えません。
  • Unix のローダがシンボルの解決をする必要ができたので、 そのオーバヘッドによりサーバの起動時間が約 20% 遅くなっています。
  • 位置非依存コード (PIC) (訳注 position independent code) は 相対アドレスのために複雑なアセンブラのトリックが必要なことがあり、 それは必ずしも絶対アドレスと同じくらいの速度がでるわけではありませんので、 プラットフォームによってはサーバの実行速度が約 5% 遅くなります。
  • DSO モジュールはすべてのプラットフォームで他の DSO に基づいた ライブラリに対してリンクできる (ld -lfoo) というわけではありませんので (たとえば、a.out のプラットフォームでは この機能はありませんが、ELF のプラットフォームにはあります)、 すべての種類のモジュールに DSO 機構を使えるわけではありません。 言い換えると、DSO ファイルとしてコンパイルされたモジュールの 使えるシンボルは、 Apache のコアのシンボル、C ライブラリ (libc) と Apache コアが使っている他のすべての静的なライブラリと動的ライブラリの シンボル、PIC による静的なライブラリ (libfoo.a) の シンボルのみに制限されます。その他のコードを使う方法は、 Apache コア自身がすでにそのコードへの参照があるようにするか、 dlopen () を使ってコードを自分自身でロードするかの どちらかしかありません。


コンテントネゴシエーション - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

コンテントネゴシエーション

Apache は HTTP/1.1 の規格に記述されているコンテントネゴシエーションを サポートしています。 ブラウザにより提供されたメディアタイプ、 言語、文字セット、エンコーディングの優先傾向に基づいて、 最適なリソースの表現を選択できます。 また、不完全なネゴシエーション情報を送ってくるブラウザからのリクエストを もっと賢く取り扱えるよう、いくつか機能も実装してあります。

コンテントネゴシエーションは mod_negotiation モジュールによって提供されていて、デフォルトで組み込まれています。

コンテントネゴシエーションについて

リソースは、幾つか異なった表現で利用できる場合があります。 例えば、異なる言語や異なるメディアタイプ、 またはそれらの組み合わせで利用できるかも知れません。 もっとも適した選択をする方法の一つには、インデックスページを ユーザに見せて、ユーザに選んでもらう方法があります。 しかし、サーバが自動的に選ぶことができる場合が多くあります。 これは、ブラウザがリクエスト毎に、 どの表現を嗜好するかという情報を送ることで動作しています。 例えばブラウザは、可能ならフランス語で情報を見たい、 不可能ならその代わりに英語でもよいと、 自分の嗜好を知らせることができます。 ブラウザはリクエストのヘッダで自分の優先傾向を知らせます。 フランス語のみの表現を要求する場合は、ブラウザは次を送ります。

Accept-Language: fr

この優先傾向は、選択可能な表現が存在して、 言語によって様々な表現がある場合にのみ適用される ということに注意してください。

もっと複雑なリクエストの例を挙げましょう。 このブラウザはフランス語と英語を受け付ける、しかしフランス語を好む、 そして様々なメディアタイプを受け付けるが、 プレインテキストや他のタイプよりは HTML を好む、 他のメディアタイプよりは GIF や JPEG を好む、しかし最終手段として 他のメディアタイプも受け付ける、と設定されています。

Accept-Language: fr; q=1.0, en; q=0.5
Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6, image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1

Apache は HTTP/1.1 規格で定義されている 'server driven' コンテントネゴシエーションをサポートしています。 Accept, Accept-Language, Accept-Charset, Accept-Encoding リクエストヘッダを完全にサポートしています。Apache は 'transparent' コンテントネゴシエーションもサポートしていますが、 これは RFC 2295 と RFC 2296 で定義されている試験的な ネゴシエーションプロトコルです。 これらの RFCで定義されている 'feature negotiation' はサポートしていません。

リソースとは URI で特定される概念上のもののことです (RFC 2396)。 Apache のような HTTP サーバは、その名前空間の中での リソースの表現へのアクセスを提供します。 それぞれの表現は 定義されたメディアタイプ、文字セット、エンコーディング等の 付属した、バイト列の形式です。 それぞれのリソースはある時点で 0 個、1 個、それ以上の表現と 関連付けられる可能性があります。複数の表現が利用できる場合は、 リソースはネゴシエーション可能であるとされ、 個々の表現は variant と呼ばれます。 ネゴシエーション可能なリソースの variant が異なる、 その状態を指して、 ネゴシエーションの次元と呼びます。

Apache におけるネゴシエーション

リソースをネゴシエーションするためには、 サーバは variant それぞれについての情報を知っておく必要があります。 これは以下の二つの方法のどちらかで行われます。

  • タイプマップ (すなわち *.var ファイル) を使う方法。 これは variant を明示的に挙げているファイルを指定します。
  • 'Multiviews' を使って、サーバが暗黙の内にファイル名にパターン照合を 行なってその結果から選択する方法。

type-map ファイルを使う

タイプマップは type-map ハンドラ (もしくは、古い Apache の設定と下位互換である MIME タイプ application/x-type-map) に関連付けられたドキュメントです。 この機能を使うためには、あるファイルの拡張子を type-map として定義するようなハンドラを、 設定ファイル中に置く必要があることに注意してください。 これは

AddHandler type-map .var

をサーバ設定ファイル中に書くことが一番良い方法です。

タイプマップファイルは記述するリソースと同じ名前を持っていて、 利用可能な variant それぞれのエントリを持っている必要があります。 そして、このエントリは連続した HTTP のヘッダ行で構成されます。 異なる variant のためのエントリは空行で区切られています。 エントリ中に空行が複数あってはいけません。 習慣的には、マップファイルは全体を結合したもののエントリから始まります (しかしこれは必須ではなく、あったとしても無視されるものです)。 次に例を示します。このファイルはリソース foo を記述しているので、foo.var という名前になります。

URI: foo

URI: foo.en.html
Content-type: text/html
Content-language: en

URI: foo.fr.de.html
Content-type: text/html;charset=iso-8859-2
Content-language: fr, de

たとえ MultiViews を使用するようになっていたとしても、 ファイル名の拡張子よりタイプマップの方が優先権を持つということにも 注意してください。 variant の品質が違うときは、この画像のように (JPEG, GIF, ASCII アートがあります) メディアタイプの "qs" パラメータで指定されます。

URI: foo

URI: foo.jpeg
Content-type: image/jpeg; qs=0.8

URI: foo.gif
Content-type: image/gif; qs=0.5

URI: foo.txt
Content-type: text/plain; qs=0.01

qs 値の範囲は 0.000 から 1.000 です。qs 値が 0.000 の variant は決して 選択されないことに注意してください。'qs' 値のない variant は qs 値 1.0 を 与えられます。qs パラメータはクライアントの能力に関係無く、他の variant と 比較したときの variant の相対的な「品質」を示します。 例えば、写真を表現しようとしているときは JPEG ファイルの方が普通は ASCII ファイルよりも高い品質になります。しかし、リソースが元々 ASCII アートで表現されているときは、ASCII ファイルの 方が JPEG ファイルよりも高い品質になります。このように、qs は 表現されるリソースの性質によって variant 毎に特有の値を取ります。

認識されるヘッダの一覧は mod_negotiation ドキュメントにあります。

Multiviews

MultiViews はディレクトリ毎のオプションで、 httpd.confファイルの <Directory>, <Location>, <Files> セクション中や、(AllowOverride が適切な値に 設定されていると) .htaccess ファイルで Options ディレクティブによって設定することができます。 Options All は MultiViews をセットしないことに注意してください。明示的に その名前を書く必要があります。

MultiViews の効果は以下のようになります: サーバが /some/dir/foo へのリクエストを受け取り、/some/dir で MultiViews が有効であって、 /some/dir/foo が存在しない場合、 サーバはディレクトリを読んで foo.* にあてはまる全てのファイルを探し、 事実上それらのファイルをマップするタイプマップを作ります。 そのとき、メディアタイプとコンテントエンコーディングは、そのファイル名を 直接指定したときと同じものが割り当てられます。 それからクライアントの要求に一番合うものを選びます。

サーバがディレクトリの索引を作ろうとしている場合、 MultiViews は DirectoryIndex ディレクティブで指定されたファイルを探す過程にも 適用されます。設定ファイルに

DirectoryIndex index

が書かれていて、index.html と index.html3 が 両方存在していると、サーバはその中からどちらかを適当に選びます。 もしその両方が存在せずに index.cgi が存在していると、 サーバはそれを実行します。

もしディレクトリを読んでいる際に、 文字セット、コンテントタイプ、言語、エンコーディングを 指定するための mod_mime で認識できる拡張子を持たないファイルが見つかると、結果は MultiViewsMatch ディレクティブの設定に依存します。このディレクティブは ハンドラ、フィルタ、他のファイル拡張子タイプのどれが MultiViews ネゴシエーションで使用できるかを決定します。

ネゴシエーション方法

Apache はリソースの variant の一覧を、タイプマップファイルか ディレクトリ内のファイル名からかで取得した後、 「最適な」 variant を決定するために二つの方法の どちらかを起動します。 Apache のコンテントネゴシエーションの機能を使うために、 どのようにしてこの調停が行われるか詳細を知る必要はありません。 しかしながら、この文書の残りでは関心のある人のために、 使用されている方法について説明しています。

ネゴシエーション方法は二つあります。

  1. 通常は Apache のアルゴリズムを用いた Server driven negotiation が使用されます。Apache のアルゴリズムは後に詳細に説明されています。 このアルゴリズムが使用された場合、Apache はより良い結果になるように、特定の次元において品質の値を 「変える」ことができます。Apache が品質の値を変える方法は後で詳細に説明されています。
  2. RFC 2295 で定義されている機構を用いてブラウザが特に指定した場合、 transparent content negotiation が使用されます。このネゴシエーション方法では、「最適な」 variant の決定をブラウザが完全に制御することができます。 ですから、結果はブラウザが使用しているアルゴリズムに依存します。 Transparent negotiation の処理の過程で、ブラウザは RFC 2296 で 定義されている 'remote variant selection algorithm' を実行するように頼むことができます。

ネゴシエーションの次元

次元 | 説明
メディアタイプ | ブラウザは Accept ヘッダフィールドで優先傾向を指定します。 アイテムそれぞれは、関連した品質数値を持つことができます。 variant の説明も品質数値を持つことができます ("qs" パラメータをご覧下さい)。
言語 | ブラウザは Accept-Language ヘッダフィールドで優先傾向を指定します。 要素それぞれに品質数値を持たせることができます。 variants は 0 か 1 つかそれ以上の言語と 関連づけることができます。
エンコーディング | ブラウザは Accept-Encoding ヘッダフィールドで優先傾向を指定します。 要素それぞれに品質数値を持たせることができます。
文字セット | ブラウザは Accept-Charset ヘッダフィールドで優先傾向を指定します。 要素それぞれに品質数値を持たせることができます。 variant はメディアタイプのパラメータとして文字セットを 指定することもできます。

Apache ネゴシエーションアルゴリズム

ブラウザに返す「最適な」variant を (もしあれば) 選択するように Apache は次のアルゴリズムを使うことができます。 このアルゴリズムを設定により変更することはできません。 次のように動作します:

  1. まずはじめに、ネゴシエーションの次元それぞれについて適切な Accept* ヘッダフィールドを調べ、 variant それぞれに品質を割り当てます。 もしある次元の Accept* ヘッダでその variant が許容できないことが示されていれば、それを削除します。 variant が一つも残っていなければ、ステップ 4 に行きます。
  2. 消去法で「最適な」 variant を選びます。 次のテストが順番に適用されます。 テストで選択されなかった variant は削除されていきます。 テスト後 variant が一つだけ残っていれば、それを最適なものとして ステップ 3 に進みます。 複数 variant が残っていれば、次のテストに進みます。
    1. variant のメディアタイプの品質数値と Accept ヘッダの品質数値との積を計算して、最高値の variant を選びます。
    2. 言語品質数値が最高の variant を選びます。
    3. (もしあれば) Accept-Language ヘッダの言語順か、 (もしあれば) LanguagePriority ディレクティブの言語順で最適な言語の variant を選びます。
    4. 最高「レベル」のメディアパラメータ (text/html メディアタイプのバージョンを与えるために使われます) を持つ variant を選びます。
    5. Accept-Charset ヘッダ行で与えられている最高の文字セット メディアパラメータを持つ variant を選びます。 明示的に除外されていない限り、ISO-8859-1 が許容されるようになっています。 text/* メディアタイプであるけれども 特定の文字セットに明示的に関連づけられているわけではない variant は ISO-8859-1 であると仮定されます。
    6. ISO-8859-1 ではない文字セットメディアパラメータと 関連づけられている variant を選びます。 そのような variant がない場合は、代わりに全ての variant を選びます。
    7. 最適なエンコーディングの variant を選びます。 もし user-agent が許容するエンコーディングがあれば、 その variant のみを選びます。 そうではなく、もしエンコードされたものとそうでない variant が混ざって存在していたらエンコードされていない variant のみを選びます。 variant が全部エンコードされているか variant が全部エンコードされていないという場合は、 全ての variant を選びます。
    8. 内容の最も短い variant を選びます。
    9. 残っている variant の最初のものを選びます。 タイプマップファイルの最初にリストされているか、 variant がディレクトリから最初に読み込まれる時に ASCII順でソートしてファイル名が先頭になったか、のどちらかです。
  3. アルゴリズムを使って一つの「最適な」variant を選びましたので、 それを応答として返します。ネゴシエーションの次元を指定するために HTTP レスポンスヘッダ Vary が設定されます (リソースのキャッシュをする時に、 ブラウザやキャッシュはこの情報を使うことができます)。 以上で終わり。
  4. ここに来たということは、variant が一つも選択されなかった (ブラウザが許容するものがなかったため) ということです。 406 ステータス ("No Acceptable representation" を意味する) が、利用可能な variant のリストのついた HTML ドキュメントとともに返されます。 相違の次元を示す HTTP Vary ヘッダも設定されます。

品質の値を変える

上記の Apache ネゴシエーションアルゴリズムの厳格な解釈で 得られるであろう値から、Apache は品質数値を時々変えます。 これは、このアルゴリズムで完全ではない、あるいは正確でない情報を送る ブラウザ向けによりよい結果を得るために行われます。 かなりポピュラーなブラウザで、もしないと間違った variant を選択する結果になってしまうような Accept ヘッダ情報を送るものもあります。 ブラウザが完全で正しい情報を送っていれば、 この数値変化は適用されません。

メディアタイプとワイルドカード

Accept: リクエストヘッダはメディアタイプの優先傾向を指定します。 これはまた、"image/*" や "*/*" といった「ワイルドカード」メディアタイプを含むことができます。 ここで * は任意の文字列にマッチします。 ですから、次の:

Accept: image/*, */*

を含むリクエストは、"image/" ではじまるタイプ全てが許容できる、 そして他のどんなタイプも許容できる (この場合はじめの "image/*" は冗長になります) ことを示します。 扱うことのできる明示的なタイプに加えて、機械的に ワイルドカードを送るブラウザもあります。例えば:

Accept: text/html, text/plain, image/gif, image/jpeg, */*

こうすることの狙いは、明示的にリストしているタイプが優先されるけれども、 異なる表現が利用可能であればそれでも良い、ということです。 しかしながら、上の基本的なアルゴリズムでは、 */* ワイルドカードは他の全てのタイプと全く同等なので優先されません。 ブラウザは */* にもっと低い品質 (優先) 値を付けてリクエストを送るべきなのです。例えば:

Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01

明示的なタイプには品質数値が付けられていませんので、 デフォルトの 1.0 (最高値) の優先になります。 ワイルドカード */* は低い優先度 0.01 を与えられているので、 明示的にリストされているタイプに合致する variant がない場合にのみ、 他のタイプが返されます。

もし Accept: ヘッダが q 値を全く含んでいなければ、 望みの挙動をするために、 Apache は "*/*" があれば 0.01 の q 値を設定します。 また、"type/*" の形のワイルドカードには 0.02 の q 値を設定します (ですからこれらは "*/*" のマッチよりも優先されます)。 もし Accept: ヘッダ中のメディアタイプのどれかが q 値を含んでいれば、これらの特殊な値は適応されず、 正しい情報を送るブラウザからのリクエストは期待通りに 動作するようになります。

言語ネゴシエーションの例外処理

Apache 2.0 では新たに、言語ネゴシエーションが適合するものを 見つけるのに失敗した時に、優雅にフォールバックできるような ネゴシエーションアルゴリズムが幾つか追加されました。

サーバのページをクライアントがリクエストしたけれども、 ブラウザの送ってきた Accept-Language に合致するページが一つも 見つからなかった場合に、サーバは "No Acceptable Variant" か "Multiple Choices" レスポンスをクライアントに返します。 これらのエラーメッセージを返さないように、 このような場合には Apache が Accept-Language を無視して、 クライアントのリクエストに明示的には合致しないドキュメントを 提供するように設定できます。 ForceLanguagePriority ディレクティブは、これらのエラーの一つか両方をオーバーライドするために 使用できて、 LanguagePriority ディレクティブの内容を使ってサーバの判断を代行するようにできます。

サーバは他に適合するものが見つからなければ、 言語サブセットで適合するものを試そうともします。 例えばクライアントが英国英語である en-GB 言語で ドキュメントをリクエストした場合、サーバは HTTP/1.1 規格では、単に en とマークされているドキュメントを マッチするものとすることは通常は許されていません。 (英国英語は理解できるけど一般的な英語は理解できないという読み手は 考えられないので、Accept-Language ヘッダで en-GB を含んで en を含まないのはほぼ確実に設定の間違いである、 ということに注意してください。 ですが不幸なことに、多くのクライアントではデフォルトで このような設定になっています。) しかしながら、他の言語にはマッチせず、"No Acceptable Variants" エラーを返したり、 LanguagePriority にフォールバックしようとしているときは、 サブセット指定を無視して、en-GB を en にマッチします。 Apache はクライアントの許容言語リストに暗黙に 非常に低い品質値の親言語を加えることになります。 しかし、クライアントが "en-GB; q=0.9, fr; q=0.8" とリクエストして、 サーバが "en" と "fr" と設計されたドキュメントを持っている場合は、 "fr" ドキュメントが返されることに注意してください。 このような処理は、HTTP 1.1 規格との整合性を維持して、 適切に設定されたクライアントともきちんと動作するために 必要です。

より高度なテクニック (Cookie や特殊な URL パス等) においてもユーザの言語選択をサポートするため、 Apache 2.0.47 からは、mod_negotiation が環境変数 prefer-language を認識するようになりました。 この変数が存在して、適切な言語タグが代入されているのであれば、 mod_negotiation は合致する variant を選択しようとします。合致するものが無ければ、 通常のネゴシエーション手順が適用されます。

Example

SetEnvIf Cookie "language=en" prefer-language=en
SetEnvIf Cookie "language=fr" prefer-language=fr

Transparent Content Negotiation の拡張

Apache は transparent content negotiation プロトコル (RFC 2295) を次のように拡張しています。 特定のコンテントエンコーディングのみが利用可能である variant に印を付けるために、新たに {encoding ..} 要素を variant リスト中に使っています。 リスト中のエンコードされた variant を認識し、 Accept-Encoding リクエストヘッダに従って許容される エンコードをもった variant は、どれでも候補 variant として使用するように、 RVSA/1.0 アルゴリズム (RFC 2296) の実装が拡張されました。 RVSA/1.0 の実装では、最適な variant が見つかるまで、 計算した品質数値は小数点以下 5 桁まで丸めません。

リンクと名前の変換に関する注意点

言語ネゴシエーションを使っている場合は、 ファイルが一つ以上の拡張子を持てて、 拡張子の順番は通常は考慮されない (詳細は mod_mime を参照) ので、 幾つかの異なる名前の変換を選べることになります。

典型的なファイルでは、MIME タイプ拡張子 (例えば html) を持っていて、エンコーディング拡張子 (例えば gz) を持っているかもしれなくて、 このファイルに異なる言語 variant を用意していれば、 もちろん言語拡張子 (例えば en) を持っているでしょう。

例:

  • foo.en.html
  • foo.html.en
  • foo.en.html.gz

ファイル名と、それに対して使えるリンクと使えないリンクの例です:

ファイル名 | 使えるリンク | 使えないリンク
foo.html.en | foo foo.html | -
foo.en.html | foo | foo.html
foo.html.en.gz | foo foo.html | foo.gz foo.html.gz
foo.en.html.gz | foo | foo.html foo.html.gz foo.gz
foo.gz.html.en | foo foo.gz foo.gz.html | foo.html
foo.html.gz.en | foo foo.html foo.html.gz | foo.gz

上の表を見て、拡張子なしのリンク (例えば foo) がいつでも使えることに気が付くでしょう。 この利点は、ドキュメントとして応答するファイルの 実際のファイルタイプを隠蔽して、リンクの参照を変更することなく 後からファイルを変更できる、 例えば html から shtml に、あるいは cgi に変更できる点です。

リンクに MIME タイプを使い続けたい (例えば foo.html)時は、言語拡張子は (エンコーディング拡張子もあればそれも含めて) MIME タイプ拡張子の右側になければなりません (例えば foo.html.en)。

キャッシュに関する注意事項

キャッシュが一つの表現を保存しているときは、 リクエスト URL と関連づけられています。 次にその URL がリクエストされた時に、キャッシュは 保存されている表現を使用できます。しかし、 リソースがサーバでネゴシエーション可能であれば、 最初のリクエストでキャッシュされて続くキャッシュヒットでは 間違った応答を返してしまうということになりかねません。 これを防ぐために、Apache はコンテントネゴシエーションの 後に返された応答全てに、HTTP/1.0 クライアントでは キャッシュ不可能の印をつけます。 また、ネゴシエーションされた応答のキャッシュを可能にする HTTP/1.1 プロトコルの機能も Apache はサポートします。

HTTP/1.0 準拠のクライアントからのリクエストに対しては、 (ブラウザであろうとキャッシュであろうと) ネゴシエーションを受けた応答のキャッシュを許すために、 CacheNegotiatedDocs ディレクティブを使用できます。 このディレクティブは、サーバ設定ファイルやバーチャルホストに書くことができ、 引数をとりません。 HTTP/1.1 クライアントからのリクエストには効力を持ちません。

追加情報

コンテントネゴシエーションに関する追加情報は、 Alan J. Flavell さんのLanguage Negotiation Notes をご覧下さい。ですが、 Apache 2.0 での変更点を含むためには更新されていないかもしれない ということに注意してください。


カスタムエラーレスポンス - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

カスタムエラーレスポンス

ウェブマスターが何らかのエラーや問題に対する Apache の反応を設定できるようにする追加機能を提供します。

サーバがエラーや問題を発見した場合の反応を、 カスタマイズして定義することができます。

スクリプトの実行が失敗して "500 Server Error" を発生させたとします。この場合の反応を、より好ましいテキストや、別の URL (内部及び外部) へのリダイレクションに置き換えることができます。

動作

古い動作

NCSA httpd 1.3 は、古くて退屈なエラー/問題メッセージを 返していました。それはしばしばユーザには無意味であり、 またそれを発生させた原因を記録する方法も提供していませんでした。

新しい動作

  1. NCSA のハードコードされたメッセージの代わりに 他のテキストを表示
  2. ローカルの URL にリダイレクト
  3. 外部の URL にリダイレクト

するようにサーバを設定できます。

別の URL にリダイレクトすることは役に立ちますが、 それは説明をしたり、より明確に誤り/問題を記録したりするために 何か情報を伝えられるときに限ります。

これを実現するために、 Apache は新しく CGI のような環境変数を 定義します:

          REDIRECT_HTTP_ACCEPT=*/*, image/gif,
          image/x-xbitmap, image/jpeg
REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX
          A.09.05 9000/712)
REDIRECT_PATH=.:/bin:/usr/local/bin:/etc
REDIRECT_QUERY_STRING=
REDIRECT_REMOTE_ADDR=121.345.78.123
REDIRECT_REMOTE_HOST=ooh.ahhh.com
REDIRECT_SERVER_NAME=crash.bang.edu
REDIRECT_SERVER_PORT=80
REDIRECT_SERVER_SOFTWARE=Apache/0.8.15
REDIRECT_URL=/cgi-bin/buggy.pl

頭に付く REDIRECT_ に注目してください。

少なくとも REDIRECT_URL と REDIRECT_QUERY_STRING は新しい URL (CGI スクリプトか CGI インクルードであると仮定されます) に渡されます。 他の変数は、エラーや問題が起きる前に存在した場合にだけ存在します。 もしあなたの設定した ErrorDocument が 外部リダイレクト (すなわち、http: のような体系名から始まるすべてのもの。たとえ同じホストを指していても) ならば、これらはまったく設定されません。

設定

AllowOverride が適切に設定されていれば、 .htaccess ファイルで ErrorDocument を使用することができます。

ここに、いくつかの例を挙げます。

ErrorDocument 500 /cgi-bin/crash-recover
ErrorDocument 500 "Sorry, our script crashed. Oh dear"
ErrorDocument 500 http://xxx/
ErrorDocument 404 /Lame_excuses/not_found.html
ErrorDocument 401 /Subscription/how_to_subscribe.html

構文

ErrorDocument <3-digit-code> <action>

action (動作) は、

  1. 表示されるべきテキスト。テキストには引用符 (") をつけます。 引用符の後に続くものが何でも表示されます。 注意 : (") は表示されません
  2. リダイレクト先の外部 URL
  3. リダイレクト先のローカル URL

カスタムエラーレスポンスとリダイレクト

スクリプト/SSI に追加の環境変数が利用可能になるように、 リダイレクトされた URL に対する Apache の動作が変更されました。

古い動作

リダイレクトされたスクリプトは標準の CGI 環境変数を利用可能でした。しかし、どこからリダイレクト されたかの情報は提供されていませんでした。

新しい動作

リダイレクトされた先のスクリプトが使用可能なように、 新しいたくさんの環境変数が初期化されます。新しい変数は、それぞれ REDIRECT_ で始まります。 REDIRECT_ で始まる環境変数はリダイレクトされる前に存在していた CGI 環境変数の頭に REDIRECT_ を付けて作成されます。 すなわち、HTTP_USER_AGENT は REDIRECT_HTTP_USER_AGENT になります。 これらの新しい変数に加えて、Apache は、 スクリプトがリダイレクト元のトレースを助けるために REDIRECT_URL と REDIRECT_STATUS を定義します。アクセスログには元の URL とリダイレクトされた URL の両方が記録されます。

ErrorDocument が CGI スクリプトへのローカルリダイレクトを 指定している場合は、それを起動することになったエラーの状態を クライアントまで確実に伝えるために "Status:" ヘッダを含むべきです。例えば、ErrorDocument 用の Perl スクリプトは以下のようなものを含むかもしれません。

...
print "Content-type: text/html\n";
printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
...

スクリプトが 404 Not Found のような 特定のエラーコンディションを扱うためだけに使われる場合は、 代わりに特定のコードとエラーテキストを使用することができます。


バインド - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

バインド

Apache が使用するアドレスとポートの設定をします。

参照

  • バーチャルホスト
  • DNS の問題

概要

関連モジュール 関連ディレクティブ
  • core
  • mpm_common
  • <VirtualHost>
  • Listen

Apache は起動時に、ローカルマシンのあるポートあよびアドレス に対して接続し、リクエストが来るのを待ちます。 デフォルトではマシンのすべてのアドレスに対して listen します。 しかしながら、特定のポートか、特定のアドレスのみか、 またはそれらの組み合わせのいずれかを listen するようにする必要があります。 これは、異なる IP アドレス、ホスト名、ポートに対する Apache の応答方法を決定するバーチャルホスト機能と組み合わせて使われます。

Listen ディレクティブで、特定のポートやアドレス・ポートの組からのみ入ってくる リクエストを受け付けるようにできます。 もしポート番号のみが Listen ディレクティブで指定された場合は、 すべてのインターフェースの与えられたポート番号を listen します。 IP アドレスがポート番号と同時に与えられた場合は、 サーバは与えられたポートとインターフェースを listen します。 複数の Listen ディレクティブを用いて いくつかの listen するアドレスとポートを指定できます。 サーバはリストされたアドレスやポートからのすべてのリクエストに 対して応答します。

たとえば、ポート 80 と 8000 の両方に対しての接続を受け付けるには

Listen 80
Listen 8000

とします。 二つの指定されたインタフェースとポート番号に対しての接続を受け付けるには、

Listen 192.170.2.1:80
Listen 192.170.2.5:8000

とします。 IPv6 アドレスは、角括弧で次の例のように囲まなければいけません。

Listen [fe80::a00:20ff:fea7:ccea]:80

IPv6 の特記事項

多くのプラットホームで IPv6 がサポートされてきていて、 APR はこれらのほとんどで IPv6 をサポートしているので、 Apache は IPv6 ソケットを割り当てて IPv6 経由で送られてきたリクエストを扱うことができます。

IPv6 ソケットが IPv4 と IPv6 コネクションの両方を扱うことができるか どうかは、Apache 管理者にとって厄介な問題です。 IPv4 コネクションを IPv6 ソケットで扱う場合は、 IPv4 マップされた IPv6 アドレスを使用していて、 ほとんどのプラットホームではデフォルトで使用可能ですが、 FreeBSD, NetBSD, OpenBSD では、システム全体としてのポリシーとの整合性から、 デフォルトでは使用不可に設定されています。 これらのデフォルトで使用不可のプラットホームであっても、 特別な設定パラメータで Apache の挙動を変化させることができます。

IPv4 と IPv6 のコネクションを最小限のソケットで扱いたいのであれば、 IPv4 マップの IPv6 アドレスを使用する必要があり、 --enable-v4-mapped configure オプションを指定して、単純に Listen ディレクティブで次のように設定します。

Listen 80

--enable-v4-mapped では、Apache の生成するデフォルトの設定ファイル中の Listen ディレクティブはこの形式を使用しています。 --enable-v4-mapped は、 FreeBSD, NetBSD, OpenBSD 以外の全てのプラットホームでのデフォルトです。 ですから、おそらくお手元の Apache はこの設定でビルドされているでしょう。

プラットフォームや APR が何をサポートするかに関わらず、 IPv4 コネクションのみを扱うようにしたい場合は、 次の例のように全ての Listen ディレクティブで IPv4 アドレスを指定してください。

Listen 0.0.0.0:80
Listen 192.170.2.1:80

IPv4 と IPv6 のコネクションを個別のソケットで扱うようにしたい場合 (つまり IPv4 マップのアドレスを無効にしたい場合) は、--disable-v4-mapped configure オプションを指定して、次のように個別指定の Listen ディレクティブを使用してください。

Listen [::]:80
Listen 0.0.0.0:80

--disable-v4-mapped では、Apache の生成するデフォルトの設定ファイル中の Listen ディレクティブはこの形式を使用しています。 --disable-v4-mapped は、 FreeBSD, NetBSD, OpenBSD プラットホームでのデフォルトです。

バーチャルホストに対してどう働くのか

Listen でバーチャルホストが実装されるわけではありません。 Listen は単にメインサーバにどのアドレスとポートを listen すべきかを 教えるだけです。 <VirtualHost> ディレクティブが使われない場合は、 受け入れたリクエストすべてに対して全く同じ挙動をします。 しかしながら <VirtualHost> を使って、 一つ以上のアドレスやポートに対して異なる挙動をするように 指定することができます。 VirtualHost を実装するには、使用するアドレスとポートを まず初めにサーバに通知しなければなりません。 そして、その指定したアドレスとポートでの このバーチャルホストの挙動を設定するために、 <VirtualHost> セクションを作ります。もし <VirtualHost> が listen していないアドレスとポートに対して 設定されてしまうと、 それにはアクセスできないということに注意してください。


マルチプロセッシングモジュール (MPM) - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

マルチプロセッシングモジュール (MPM)

この文書ではマルチプロセッシングモジュールがどのようなもので、 Apache HTTP サーバでどのように使用されるかについて解説しています。

はじめに

Apache HTTP サーバは異なる幅広い環境、多種多様なプラットホームで 動作するように、パワフルで柔軟性に富んだ設計になっています。 異なるプラットホーム・異なる環境ではしばしば、 異なる機能が必要になったり、 同じ機能でも効率のために異なる実装が必要になったりします。 Apache ではモジュール化された設計により幅広い環境に適応してきました。 この設計のおかげで、管理者は コンパイル時または実行時にどのモジュールをロードするか選ぶことによって、 どの機能をサーバに取り込むか選択することがができます。

Apache 2.0 では、 このモジュール化された設計をサーバの基本機能にまで拡張しました。 サーバには精選されたマルチプロセッシングモジュール (MPM) が付いてきて、これらはマシンのネットワークポートをバインドしたり、 リクエストを受け付けたり、リクエストを扱うよう子プロセスに割り当てたり、 といった役割を持ちます。

モジュール化された設計をサーバのこのレベルまで拡張することで 二つの重要な利点が生まれます:

  • Apache は幅広いオペレーティングシステムを より美しく効率的にサポートできます。 特に Windows 版の Apache は随分効率的になりました。 なぜなら mpm_winnt によって、Apache 1.3 で用いられていた POSIX レイヤの代わりにネイティブのネットワーク機能を 利用できるからです。 特別化された MPM を実装した他のオペレーティングシステムでも、 同様にこの利点は生まれます。
  • サーバは特定のサイト向けに、より上手にカスタマイズできます。 例えば、非常に大きなスケーラビリティを必要とするサイトでは、 worker といったスレッド化された MPM を利用できる一方で、安定性や古いソフトウェアとの互換性を 必要とするサイトでは prefork が利用できます。また、 異なるホストを異なるユーザ ID で動作させる (perchild) といった 特別な機能も提供できます。

ユーザレベルでは、MPM は他の Apache モジュールと同等に見えます。 主な違いは、いつでも唯一の MPM がロードされなければならないという点です。 利用可能な MPM は module インデックスにあります。

MPM を選ぶ

MPM は設定中に選択して、サーバ内部にコンパイルされなければ なりません。 コンパイラは、スレッドが使用されていれば様々な機能を最適化できますが、 そもそもスレッドが使われているということを知る必要があります。 MPM には Unix 上でスレッドを用いるものや、スレッドをまったく 使わないものがあるので、 Apache は、MPM が設定中に選択されて Apache 内部に組み込まれた場合の方が 常により良いパフォーマンスを発揮します。

望みの MPM を実際に選ぶためには、./configure スクリプトで --with-mpm= NAME 引数を用いてください。 NAME は望みの MPM の名前です。

サーバコンパイル後は、どの MPM が選択されたかを ./httpd -l で確かめることができます。 このコマンドは、MPM を含め、サーバにコンパイルで組み込まれたモジュール全てを 列挙します。

MPM デフォルト値

次表に様々な OS 向けのデフォルトの MPM 一覧を掲載しています。 コンパイル時に意図的に他を選択しなければ、自動的にこれらの MPM が選択されます。

BeOS | beos
Netware | mpm_netware
OS/2 | mpmt_os2
Unix | prefork
Windows | mpm_winnt


Apache の環境変数 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

Apache の環境変数

Apache HTTP サーバは環境変数と呼ばれる、名前のついた 変数に情報を記憶する仕組みを提供しています。この情報はログ収集や アクセス制御などのいろいろな操作を制御するために使うことができます。 これらの変数は CGI スクリプトなどの外部プログラムと通信するためにも 使われます。この文書はそれらの変数の操作方法と使用方法をいくつか 紹介します。

これらの変数は環境変数と呼ばれていますが、オペレーティング システムによって制御されている環境変数と同じではありません。 実際は、これらの変数は Apache の内部構造の中に記憶され、操作されています。 それらは、CGI や SSI スクリプトに渡されたときだけ、実際の オペレーティングシステムの環境変数になります。サーバ自身が 実行されているオペレーティングシステムの環境を操作したい場合は、 オペレーティングシステムのシェルが提供している標準の環境変数の 操作方法を使わなければなりません。

環境変数の設定

関連モジュール 関連ディレクティブ
  • mod_env
  • mod_rewrite
  • mod_setenvif
  • mod_unique_id
  • BrowserMatch
  • BrowserMatchNoCase
  • PassEnv
  • RewriteRule
  • SetEnv
  • SetEnvIf
  • SetEnvIfNoCase
  • UnsetEnv

基本的な環境の操作

Apache において環境変数を設定する一番基本的な方法は、 無条件に環境変数を設定する SetEnv ディレクティブを使用することです。 PassEnv ディレクティブにより、Apache が起動されたシェルの 環境変数を渡すこともできます。

リクエスト毎に条件に基づいて設定する

より柔軟性を高めるために、mod_setenvif で提供されているディレクティブを使用することで、リクエストの 特性に基づいて環境変数を設定することができます。例えば、特定のブラウザ (User-Agent) のリクエストや特定の Referer [意図的な綴りです] (訳注: 正しい綴りは referrer ですが、HTTP の仕様では Referer となっています) ヘッダが見つかったときのみ変数を設定することができます。 mod_rewrite の RewriteRule ディレクティブにおいて環境変数を設定する [E=...] オプションを使用することで、 より柔軟な設定を行なうことができます。

一意な識別子

mod_unique_id は、非常に限られた条件の下で 「すべて」のリクエストについて、一意であることが保証されている値を環境変数 UNIQUE_ID に設定します。

標準 CGI 変数

Apache の設定ファイルで設定された環境変数とシェルから渡される 環境変数に加えて、CGI スクリプトと SSI ページには CGI の仕様で要求されている、 リクエストのメタ情報を持った環境変数の組が提供されます。

いくつかの注意

  • 環境を操作するディレクティブを使って標準 CGI 変数を上書きしたり変更したりすることはできません。
  • CGI スクリプトを起動するために suexec が使用されている場合、CGI スクリプトが起動するために、環境変数は安全な環境変数の組に整理されます。 この安全な環境変数の集合は、コンパイル時に suexec.c で定義されます。
  • 移植性のために、環境変数の名前はアルファベット、 数字とアンダースコア (訳注: '_') だけから成ります。 さらに、最初の文字は数字であってはいけません。 この制限に合わない文字は CGI スクリプトと SSI ページに渡されるときにアンダースコアに置換されます。

環境変数の使用

関連モジュール 関連ディレクティブ
  • mod_access
  • mod_cgi
  • mod_ext_filter
  • mod_headers
  • mod_include
  • mod_log_config
  • mod_rewrite
  • Allow
  • CustomLog
  • Deny
  • ExtFilterDefine
  • Header
  • LogFormat
  • RewriteCond
  • RewriteRule

CGI スクリプト

環境変数の主な利用法の一つは、CGI スクリプトに情報を伝えることです。 上で説明されているように、CGI スクリプトに渡される環境変数は Apache の設定により設定される変数に加えて、リクエストの標準のメタ情報を含んでいます。 詳細は CGI チュートリアル を参照してください。

SSI ページ

mod_include の INCLUDES フィルタで処理される server-parsed (SSI) ドキュメントでは、echo 要素を使用すると環境変数が出力されます。 また、ページのある部分がリクエストの性質に応じて変更されるように、 環境変数をフロー制御要素で使うことができます。詳細は SSI チュートリアル を参照してください。

アクセス制御

allow from env= ディレクティブと deny from env= ディレクティブを使用して、サーバへのアクセスを環境変数の値で制御することができます。 SetEnvIf ディレクティブと組み合わせることで、クライアントの特性に基づいて サーバへのアクセス制御を柔軟に行なうことができるようになります。 たとえば、これらのディレクティブを使用して、特定のブラウザ (User-Agent) からのアクセスを拒否することができます。

条件付きログ記録

LogFormat ディレクティブのオプション %e を使用することで、環境変数をアクセスログに記録することができます。さらに、 CustomLog ディレクティブの条件分岐式を使用することで、 環境変数の値によってリクエストをログに記録するかどうかを決めることができます。 SetEnvIf ディレクティブと組み合わせることで、 どのリクエストをログに記録するかを柔軟に制御することが可能になります。たとえば、 gif で終わるファイル名へのリクエストはログに記録しない、 違うサブネットのクライアントからのリクエストだけをログに記録する、 という選択が可能です。

条件付き応答ヘッダ

Header ディレクティブは環境変数の存在や不在によってクライアントへの応答に特定の HTTP ヘッダを付けるかどうかを決めることができます。 これにより、たとえば、クライアントからのリクエスト にあるヘッダがある場合にのみ特定の応答ヘッダを送る、というようなことが できます。

外部フィルタの適用

ExtFilterDefine ディレクティブを使用して mod_ext_filter で設定される外部フィルタは、 disableenv= と enableenv= オプションを使って、環境変数による条件付き適用ができます。

URL の書き換え

RewriteCond ディレクティブで評価文字列として %{ENV:...} 式を指定することで、mod_rewrite の書き換えエンジンが環境変数に基いて条件分岐を行なうことができます。 mod_rewrite が使用可能な変数で ENV: が前についていない変数は、 実際は環境変数ではないということに注意してください。 それらは他のモジュールからは使用できない mod_rewrite 用の特別な変数です。

特別な目的の環境変数

互換性の問題を解決するために、特定のクライアントと通信しているときは Apache の動作を変更できる機構が導入されました。できるだけ柔軟にするために、 これらの機構は環境変数を定義することで呼び出されます。普通は、 BrowserMatch ディレクティブを使いますが、たとえば SetEnv ディレクティブや PassEnv ディレクティブも使用することができます。

downgrade-1.0

これを指定することで、リクエストが HTTP/1.0 より新しいプロトコルの場合でも、HTTP/1.0 として扱われます。

force-no-vary

応答ヘッダがクライアントに送られる前に Vary フィールドを取り除きます。 クライアントの中にはこのフィールドを正しく解釈しないものがあります (クライアントの既知の問題 のページを参照してください)。この変数を設定することでその問題を回避 することができます。この変数を設定すると、force-response-1.0 が設定されたことになります。

force-response-1.0

これが設定されていると、HTTP/1.0 リクエストを発行するクライアントに対しては 常に HTTP/1.0 で応答するようになります。この機能は、 元々は AOL のプロキシの問題のために実装されました。HTTP/1.0 クライアントの中には、 HTTP/1.1 の応答を返されると正しく動作しないものがあるかもしれません。 この機能を使用することで、そのようなクライアントとの間の互換性問題を解決できます。

gzip-only-text/html

これが 1 に設定されると、この変数は text/html 以外のコンテントタイプに対する、mod_deflate 提供の DEFLATE 出力フィルタを無効にします。

no-gzip

セットされると、mod_deflate の DEFLATE フィルタがオフになります。

nokeepalive

これが設定されている場合は、KeepAlive を使用しないようにします。

prefer-language

mod_negotiation の挙動に影響を与えます。 (en, ja, x-klingonといった) 言語タグが格納されていれば、その言語の variant を送信しようとします。 そのような variant がない場合は、 通常のネゴシエーション処理が 適用されます。

redirect-carefully

これはクライアントへのリダイレクトの送信をサーバがより注意深く 行なうようにします。 これは通常、リダイレクトに際してクライアントに 問題があることが分かっている場合に使われます。この機能は元々は マイクロソフトのウェブフォルダのソフトが DAV メソッドによるディレクトリのリソースへのリダイレクトの扱いに 問題がり、それを回避するために実装されました。

suppress-error-charset

Apache 2.0.40 以降で利用可能

クライアントのリクエストに対する応答としてリダイレクトを送信する際、 レスポンスにはリダイレクトが自動的に行なえない (行なわれない) 場合に表示するテキストが含まれます。 通常、このテキストに合致したキャラクタセット、ISO-8859-1 でラベル付けをします。

しかし、リダイレクト先が別の文字セットを使っている場合、 ある問題のあるブラウザのバージョンでは、 リダイレクト先の実際の文字セットの代わりに、 リダイレクト元の文字セットを使ってしまうことがあります。 その結果、例えば変な描画が行なわれたりして、読めなくなったりします。

この環境変数を設定することで、リダイレクションテキストに対する キャラクタセットの指定を除去しますので、それら問題のあるブラウザでも リダイレクト先の文字セットを正しく使うようにできます。

例

おかしな挙動をするクライアントに対してプロトコルの動作を変更する

クライアントに関する既知の問題に対処するために、以下の行を httpd.conf に入れることを推奨しています。

#
# The following directives modify normal HTTP response behavior.
# The first directive disables keepalive for Netscape 2.x and browsers that
# spoof it. There are known problems with these browser implementations.
# The second directive is for Microsoft Internet Explorer 4.0b2
# which has a broken HTTP/1.1 implementation and does not properly
# support keepalive when it is used on 301 or 302 (redirect) responses.
#
BrowserMatch "Mozilla/2" nokeepalive
BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0

#
# The following directive disables HTTP/1.1 responses to browsers which
# are in violation of the HTTP/1.0 spec by not being able to grok a
# basic 1.1 response.
#
BrowserMatch "RealPlayer 4\.0" force-response-1.0
BrowserMatch "Java/1\.0" force-response-1.0
BrowserMatch "JDK/1\.0" force-response-1.0

画像へのリクエストをアクセスログに記録しない

この例では、画像へのリクエストがアクセスログに現れないようにします。 これを変更することで、特定のディレクトリのログ収集をやめたり、 特定のホストからのリクエストのログ収集をやめたりすることが簡単にできます。

SetEnvIf Request_URI \.gif image-request
SetEnvIf Request_URI \.jpg image-request
SetEnvIf Request_URI \.png image-request
CustomLog logs/access_log common env=!image-request

「画像の盗用」を防ぐ

この例は、別のサーバにいる人が、あなたのサーバにある画像を inline 画像として使用することを防ぎます。 これは推奨されている設定ではありませんが、ある限定された状況では有効です。 ここでは、すべての画像は /web/images というディレクトリにあると仮定します。

SetEnvIf Referer "^http://www.example.com/" local_referal
# Allow browsers that do not send Referer info
SetEnvIf Referer "^$" local_referal
<Directory /web/images>
   Order Deny,Allow
   Deny from all
   Allow from env=local_referal
</Directory>

この手法に関する詳しい情報は ApacheToday のチュートリアル「Keeping Your Images from Adorning Other Sites 」を参照してください。


Apache のハンドラの使用 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

Apache のハンドラの使用

Apache のハンドラの使用に関して記述しています。

ハンドラとは

関連モジュール 関連ディレクティブ
  • mod_actions
  • mod_asis
  • mod_cgi
  • mod_imap
  • mod_info
  • mod_mime
  • mod_negotiation
  • mod_status
  • Action
  • AddHandler
  • RemoveHandler
  • SetHandler

「ハンドラ」とは、ファイルが呼ばれたときに実行される動作の Apache における内部表現です。 通常、ファイルはファイル型に基づいた暗黙のハンドラがあります。 普通はすべてのファイルは単にサーバに扱われますが、 ファイルタイプの中には別に「ハンドル」(訳注: 扱う) されるものもあります。

Apache 1.1 では、ハンドラを明示的に使用する機能が追加されました。 ファイルの拡張子や置いている場所に基づいて、 ファイル型と関係なくハンドラを指定することができます。 これはより優雅な解決法という点と、ファイルにタイプとハンドラの両方を関連付けることができるという点で優れています。 (複数の拡張子のあるファイルも参照してください)。

ハンドラはサーバに組み込んだり、モジュールとして含めたり、 Action ディレクティブとして追加したりすることができます。 以下は標準配布に組み込まれているハンドラです。

  • default-handler:default_handelr() を使ってファイルを送ります。 静的なコンテンツを扱うときにデフォルトで使用されるハンドラです。 (core)
  • send-as-is: HTTP ヘッダのあるファイルをそのまま送ります。 (mod_asis)
  • cgi-script: ファイルを CGI スクリプトとして扱います。 (mod_cgi)
  • imap-file: イメージマップのルールファイルとして解析します。 (mod_imap)
  • server-info: サーバの設定情報を取得します。 (mod_info)
  • server-status: サーバの状態報告を取得します。 (mod_status)
  • type-map: コンテントネゴシエーションのためのタイプマップとして解析します。 (mod_negotiation)

例

CGI スクリプトを用いて静的なコンテンツを変更する

以下のディレクティブによって、拡張子が html であるファイルは footer.pl CGI スクリプトを起動するようになります。

Action add-footer /cgi-bin/footer.pl
AddHandler add-footer .html

CGI スクリプトは希望の修正や追加を行なって、元々要求された文書 (環境変数 PATH_TRANSLATED で指されています) を送る責任があります。

HTTP ヘッダのあるファイル

以下のディレクティブは send-as-is ハンドラを使用するように指示します。このハンドラは自分自身の HTTP ヘッダを持っているファイルに使用されます。ここでは、拡張子に関わらず、 /web/htdocs/asis ディレクトリにある全てのファイルは send-as-is ハンドラによって扱われます。

<Directory /web/htdocs/asis>
SetHandler send-as-is
</Directory>

プログラマ向けのメモ

ハンドラの機能を実装するために、利用すると便利かもしれないものが Apache API に追加されました。詳しく言うと、request_rec 構造体に新しいレコードが追加されたということです。

char *handler

もしモジュールがハンドラに関わりたい場合、 やらなければならないことは、リクエストが invoke_handler ステージに達する以前に r->handler を設定することだけです。ハンドラはコンテントタイプの代わりに ハンドラ名を使うようになっていること以外は、以前と同じように実装されています。 必ず要求されているわけではありませんが、メディアタイプ の名前空間を侵さないように、ハンドラの名前にはスラッシュを含まない、 ダッシュ (訳注: "-") で分離された名前を付ける習慣になっています。


フィルタ - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

フィルタ

Apache でのフィルタの使い方について記述しています。

フィルタ

関連モジュール 関連ディレクティブ
  • mod_deflate
  • mod_ext_filter
  • mod_include
  • AddInputFilter
  • AddOutputFilter
  • RemoveInputFilter
  • RemoveOutputFilter
  • ExtFilterDefine
  • ExtFilterOptions
  • SetInputFilter
  • SetOutputFilter

フィルタ とは、サーバが送受信したデータに 適用される処理プロセスのことをいいます。クライアントからサーバに 送られたデータは 入力フィルタ によって、サーバから クライアントに送られるデータは出力フィルタによって 処理されます。複数のフィルタを適用することができ、 その順番を厳密に指定することもできます。

Apache 内部では、チャンク (データのぶつ切り) を行ったり、 バイト範囲の指定されたリクエストを扱ったりといった機能を 行う際に、フィルタが使われています。それに加えて、 実行時の設定ディレクティブで選択が可能なフィルタを モジュールが提供できます。 データに適応されるフィルタのセットは、 SetInputFilter, SetOutputFilter, AddInputFilter, AddOutputFilter, RemoveInputFilter, RemoveOutputFilter ディレクティブで制御できます。

現行の Apache HTTP サーバの配布では、 次のユーザ選択可能なフィルタが提供されています。

INCLUDES
mod_include で Server-Side Include をします。
DEFLATE
mod_deflate を使って、クライアントに送信する前に出力を圧縮します。

また、mod_ext_filter モジュールで 外部プログラムをフィルタとして指定することができます。


suEXEC サポート - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

suEXEC サポート

suEXEC 機能により、Apache ユーザは Web サーバを実行しているユーザ ID とは 異なるユーザ ID で CGI プログラムや SSI プログラムを実行することができます。CGI プログラムまたは SSI プログラムを実行する場合、通常は web サーバと同じユーザで実行されます。

適切に使用すると、この機能によりユーザが個別の CGI や SSI プログラムを開発し実行することで生じるセキュリティ上の危険を、 かなり減らすことができます。しかし、suEXEC の設定が不適切だと、 多くの問題が生じ、あなたのコンピュータに新しいセキュリティホールを 作ってしまう可能性があります。あなたが setuid root されたプログラムと、それらから生じるセキュリティ上の問題の管理に 詳しくないようなら、suEXEC の使用を検討しないように強く推奨します。

始める前に

この文書の先頭に飛ぶ前に、Apache グループとこの文書での仮定を知っておくべきでしょう。

第 1 に、あなたが setuid と setgid 操作が可能な UNIX 由来のオペレーティングシステムを使っていることを想定しています。 これは、すべてのコマンド例にあてはまります。 その他のプラットホームでは、もし suEXEC がサポートされていたとしても設定は異なるかもしれません。

第 2 に、あなたが使用中のコンピュータの セキュリティに関する基本的な概念と、それらの管理について詳しいことを 想定しています。これは、setuid/setgid 操作、あなたのシステム上でのその操作による様々な効果、 セキュリティレベルについてあなたが理解しているということを含みます。

第 3 に、改造されていない suEXEC コードの使用を想定しています。suEXEC のコードは、 多くのベータテスタだけでなく、開発者によっても注意深く精査され テストされています。それらの注意により、簡潔で信頼できる安全な コードの基盤が保証されます。このコードを改変することで、 予期されない問題や新しいセキュリティ上の危険が生じることがあります。 セキュリティプログラミングの詳細に通じていて、 今後の検討のために成果を Apache グループと共有しようと思うのでなければ、suEXEC コードは変えないことを 強く推奨します。

第 4 に、これが最後ですが、suEXEC を Apache のデフォルトインストールには含めないことが Apache グループで決定されています。これは、suEXEC の設定には管理者の詳細にわたる慎重な注意が必要だからです。 suEXEC の様々な設定について検討が終われば、管理者は suEXEC を通常のインストール方法でインストールすることができます。 これらの設定値は、suEXEC 機能の使用中にシステムセキュリティを適切に保つために、 管理者によって慎重に決定され指定されることが必要です。 この詳細な手順により、Apache グループは、suEXEC のインストールについて、注意深く十分に検討してそれを使用することを 決定した場合に限っていただきたいと考えています。

それでも進みますか? よろしい。では、先へ進みましょう!

suEXEC セキュリティモデル

suEXEC の設定とインストールを始める前に、 まず実装しようとしているセキュリティモデルについて論じておきます。 それには、suEXEC の内部で行なわれていること、 システムのセキュリティを保証するために警告されることを よく理解しておいた方がよいでしょう。

suEXEC は、Apache web サーバから呼び出される setuid された "wrapper" プログラムが基本となっています。設計した CGI、または SSI プログラムへの HTTP リクエストがあると、この wrapper が呼び出されます。このようなリクエストがあると、Apache はそのプログラムが実行される際のプログラム名とユーザ ID とグループ ID を指定して suEXEC wrapper を実行します。

それから、wrapper は成功または失敗を決定するため 以下の処理を行ないます。これらの状態のうち一つでも失敗した場合、 プログラムは失敗をログに記録してエラーで終了します。 そうでなければ、後の処理が続けられます。

  1. wrapper を実行しているユーザはこのシステムの正当なユーザか?

    これは、wrapper を実行しているユーザが 本当にシステムの利用者であることを保証するためです。

  2. wrapper が適切な数の引数で呼び出されたか?

    wrapper は適切な数の引数が与えられた場合にのみ実行されます。 適切な引数のフォーマットは Apache Web サーバに解釈されます。 適切な数の引数を受け取らなければ、攻撃をされたか あなたの Apache バイナリの suEXEC の部分が どこかおかしい可能性があります。

  3. この正当なユーザは wrapper の実行を許可されているか?

    このユーザは wrapper 実行を許可されたユーザですか? ただ一人のユーザ (Apache ユーザ) だけが、 このプログラムの実行を許可されます。

  4. 対象の CGI, SSI プログラムが安全でない階層の参照をしているか?

    対象の CGI, SSI プログラムが '/' から始まる、または '..' による参照を行なっていますか? これらは許可されません。 対象のプログラムは suEXEC のドキュメントルート (下記の --with-suexec-docroot=DIR を参照) 内に存在しなければなりません。

  5. 対象となるユーザ名は正当なものか?

    対象となるユーザ名は存在していますか?

  6. 対象となるグループ名は正当なものか?

    対象となるグループ名は存在していますか?

  7. 目的のユーザはスーパーユーザではないか?

    今のところ、suEXEC は root による CGI/SSI プログラムの実行を許可していません。

  8. 対象となるユーザ ID は、最小の ID 番号よりも大きいか?

    最小ユーザ ID 番号は設定時に指定されます。これは、 CGI/SSI プログラム実行を許可されるユーザ ID のとりうる最小値です。これは "system" 用のアカウントを閉め出すのに有効です。

  9. 対象となるグループはスーパーユーザのグループでは ないか?

    今のところ、suEXEC は 'root' グループによる CGI/SSI プログラムの実行を許可していません。

  10. 対象となるグループ ID は最小の ID 番号よりも大きいか?

    最小グループ ID 番号は設定時に指定されます。これは、 CGI/SSI プログラム実行を許可されるグループ ID のとりうる最小値です。 これは "system" 用のグループを閉め出すのに有効です。

  11. wrapper が正常に対象となるユーザとグループになれるか?

    ここで、setuid と setgid の起動によりプログラムは対象となるユーザとグループになります。 グループアクセスリストは、 ユーザが属しているすべてのグループで初期化されます。

  12. CGI/SSI プログラムが置かれているディレクトリに移動 (change directory) できるか?

    ディレクトリが存在しないなら、そのファイルも存在しないかもしれません。 ディレクトリに移動できないのであれば、おそらく存在もしないでしょう。

  13. ディレクトリが Apache のドキュメントツリー内にあるか?

    リクエストがサーバ内のものであれば、 要求されたディレクトリが suEXEC のドキュメントルート配下にありますか? リクエストが UserDir のものであれば、要求されたディレクトリが suEXEC のユーザのドキュメントルート配下にありますか? (suEXEC 設定オプション 参照)

  14. ディレクトリを他のユーザが書き込めるようになって いないか?

    ディレクトリを他ユーザに開放しないようにします。 所有ユーザだけがこのディレクトリの内容を改変できるようにします。

  15. 対象となる CGI/SSI プログラムは存在するか?

    存在しなければ実行できません。

  16. 対象となる CGI/SSI プログラムファイルが他アカウントから 書き込めるようになっていないか?

    所有者以外には CGI/SSI プログラムを変更する権限は与えられません。

  17. 対象となる CGI/SSI プログラムが setuid または setgid されていないか?

    UID/GID を再度変更してのプログラム実行はしません

  18. 対象となるユーザ/グループがプログラムの ユーザ/グループと同じか?

    ユーザがそのファイルの所有者ですか?

  19. 安全な動作を保証するための環境変数クリアが可能か?

    suEXEC は、安全な環境変数のリスト (これらは設定時に作成されます) 内の変数として渡される安全な PATH 変数 (設定時に指定されます) を設定することで、 プロセスの環境変数をクリアします。

  20. 対象となる CGI/SSI プログラムを exec して実行できるか?

    ここで suEXEC が終了し、対象となるプログラムが開始されます。

ここまでが suEXEC の wrapper におけるセキュリティモデルの標準的な動作です。もう少し厳重に CGI/SSI 設計についての新しい制限や規定を取り入れることもできますが、 suEXEC はセキュリティに注意して慎重に少しずつ開発されてきました。

このセキュリティモデルを用いて サーバ設定時にどのように許すことを制限するか、また、suEXEC を適切に設定するとどのようなセキュリティ上の危険を避けられるかに 関するより詳しい情報については、"とかげに注意" (Beware the Jabberwock) の章を参照してください。

suEXEC の設定とインストール

ここから楽しくなります。

suEXEC 設定オプション

--enable-suexec
このオプションは、デフォルトではインストールされず、 有効にはならない suEXEC 機能を有効にします。 suEXEC を使うように APACI に要求するには、--enable-suexec オプションにあわせて少なくとも一つは --with-suexec-xxxxx オプションが指定されなければなりません。
--with-suexec-bin=PATH
セキュリティ上の理由により、suexec バイナリのパスはサーバに ハードコードされている必要があります。デフォルトのパスを 変えたいときはこのオプションを使ってください。例えば、 --with-suexec-bin=/usr/sbin/suexec のように。
--with-suexec-caller=UID
Apache を通常動作させるユーザ名を指定します。 このユーザだけが suexec の実行を許可されたユーザになります。
--with-suexec-userdir=DIR
suEXEC がアクセスを許されるユーザホームディレクトリ配下の サブディレクトリを指定します。 このディレクトリ以下の全実行ファイルは、"安全な"プログラムになるよう、 suEXEC がそのユーザとして実行できるようにします。 "単純な" UserDir ディレクティブを使っている場合 (すなわち "*" を含まないもの)、これと同じ値を設定すべきです。 Userdir ディレクティブがそのユーザのパスワードファイル内の ホームディレクトリと同じ場所を指していなければ、 suEXEC は適切に動作しません。デフォルトは "public_html" です。
各 UserDir が異なった仮想ホストを設定している場合、 それらを全て一つの親ディレクトリに含めて、 その親ディレクトリの名前をここで指定する必要があります。 このように指定されなければ "~userdir" cgi へのリクエストが動作しません。
--with-suexec-docroot=DIR
Apache のドキュメントルートを設定します。これが suEXEC の動作で使用する唯一のディレクトリ階層になります (UserDir の指定は別)。デフォルトでは --datedir に "/htdocs" というサフィックスをつけたものです。 "--datadir=/home/apache" として設定すると、 suEXEC wrapper にとって "/home/apache/htdocs" がドキュメントルートとして使われます。
--with-suexec-uidmin=UID
suEXEC の対象ユーザとして許される UID の最小値を指定します。 大抵のシステムでは 500 か 100 が一般的です。 デフォルト値は 100 です。
--with-suexec-gidmin=GID
suEXEC の対象グループとして許される GID の最小値を指定します。大抵のシステムでは 100 が一般的なので、 デフォルト値としても 100 が使われています。
--with-suexec-logfile=FILE
suEXEC の処理とエラーが記録されるファイル名を指定します。 (監査やデバッグ目的に有用) デフォルトではログファイルは "suexec_log" という名前で、 標準のログファイルディレクトリ (--logfiledir) に置かれます。
--with-suexec-safepath=PATH
CGI 実行ファイルに渡される安全な PATH 環境変数です。 デフォルト値は "/usr/local/bin:/usr/bin:/bin" です。

suEXEC wrapper のコンパイルとインストール
--enable-suexec オプションで suEXEC 機能を有効にすると、 "make" コマンドを実行した時に suexec のバイナリ (Apache 自体も) が自動的に作成されます。
すべての構成要素が作成されると、それらのインストールには make install コマンドが実行できます。バイナリイメージの suexec は --sbindir オプションで指定されたディレクトリにインストールされます。 デフォルトの場所は "/usr/local/apache/sbin/suexec" です。
インストール時には root 権限が必要なので注意してください。wrapper がユーザ ID を設定するために、所有者 root でのセットユーザ ID ビットをそのファイルのモードに設定しなければなりません。

安全なパーミッションを設定する
suEXEC ラッパーは、--with-suexec-caller configure オプションで指定した正しいユーザで起動されていることを確認しますが、 システム上でこのチェックが行なわれる前に、 suEXEC が呼ぶシステムやライブラリが脆弱である可能性は残ります。対抗策として、 一般に良い習慣ともされいますが、 ファイルシステムパーミッションを使って Apache の実行時のグループのみが suEXEC を実行できるように するのが良いでしょう。

たとえば、次のようにサーバが設定されていたとします。

User www
Group webgroup

suexec が "/usr/local/apache2/sbin/suexec" にインストールされていた場合、次のように設定する必要があります。

chgrp webgroup /usr/local/apache2/bin/suexec
chmod 4750 /usr/local/apache2/bin/suexec

これで Apache が実行されるグループのみが suEXEC ラッパーを実行できるということを 確証します。

suEXEC の有効化と無効化

起動時に、Apache は --sbindir オプションで設定されたディレクトリで suexec を探します (デフォルトは "/usr/local/apache/sbin/suexec") 。 適切に設定された suEXEC がみつかると、 エラーログに以下のメッセージが出力されます。

[notice] suEXEC mechanism enabled (wrapper: /path/to/suexec)

サーバ起動時にこのメッセージが出ない場合、 大抵はサーバが想定した場所で wrapper プログラムが見つからなかったか、 setuid root としてインストールされていないかです。

suEXEC の仕組みを使用するのが初めてで、Apache が既に動作中であれば、 Apache を kill して、再起動しなければなりません。HUP シグナルや USR1 シグナルによる単純な再起動では不十分です。

suEXEC を無効にする場合は、suexec ファイルを削除してから Apache を kill して再起動します。

suEXEC の使用

CGI プログラムへのリクエストが suEXEC ラッパーを呼ぶのは、 SuexecUserGroup ディレクティブを 含むバーチャルホストへのリクエストか、mod_userdir により 処理されたリクエストの場合に限ります。

仮想ホスト:
suEXEC wrapper の使い方として、 VirtualHost 設定での SuexecUserGroup ディレクティブを通したものがあります。 このディレクティブをメインサーバのユーザ ID と異なるものにすると、CGI リソースへのすべてのリクエストは、その <VirtualHost> で指定された User と Group として実行されます。<VirtualHost> でこのディレクティブが指定されていない場合、 メインサーバのユーザ ID が想定されます。

ユーザディレクトリ:
mod_userdir により処理されたリクエストは リクエストされたユーザディレクトリのユーザ ID で CGI プログラムを 実行するために suEXEC ラッパーを呼びます。 この機能を動作させるために必要なことは、CGI をそのユーザで実行できること、そのスクリプトが上記のセキュリティ検査をパスできることです。 コンパイル 時のオプション --with-suexec-userdir も参照してください。

suEXEC のデバッグ

suEXEC wrapper は、上記で述べた --with-suexec-logfile オプションで指定されたファイルにログ情報を記録します。 wrapper を適切に設定、インストールできていると思う場合、 どこで迷っているか見ようとするならこのログとサーバの エラーログを見るとよいでしょう。

とかげに注意: 警告と事例

注意! この章は完全ではありません。この章の最新改訂版については、 Apache グループの オンラインドキュメント版を参照してください。

サーバの設定に制限をもうける wrapper について、 いくつか興味深い点があります。suEXEC に関する "バグ" を報告する前にこれらを確認してください。

  • suEXEC の興味深い点
  • 階層構造の制限

    セキュリティと効率の理由から、suEXEC の全てのリクエストは 仮想ホストへのリクエストにおける最上位のドキュメントルート内か、 ユーザディレクトリへのリクエストにおける個々のユーザの最上位の ドキュメントルート内に残らなければなりません。 例えば、四つの仮想ホストを設定している場合、 仮想ホストの suEXEC に有利なように、メインの Apache ドキュメント階層の外側に全ての仮想ホストのドキュメントルートを 構築する必要があります。(例は後日記載)

  • suEXEC の PATH 環境変数

    これを変更するのは危険です。この指定に含まれる各パスが 信頼できる ディレクトリであることを確認してください。 世界からのアクセスにより、誰かがホスト上でトロイの木馬 を実行できるようにはしたくないでしょう。

  • suEXEC コードの改造

    繰り返しますが、何をやろうとしているか把握せずにこれをやると 大きな問題を引き起こしかねません。 可能な限り避けてください。


Apache Performance Tuning - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Miscellaneous Documentation

Apache Performance Tuning

Apache 2.0 is a general-purpose webserver, designed to provide a balance of flexibility, portability, and performance. Although it has not been designed specifically to set benchmark records, Apache 2.0 is capable of high performance in many real-world situations.

Compared to Apache 1.3, release 2.0 contains many additional optimizations to increase throughput and scalability. Most of these improvements are enabled by default. However, there are compile-time and run-time configuration choices that can significantly affect performance. This document describes the options that a server administrator can configure to tune the performance of an Apache 2.0 installation. Some of these configuration options enable the httpd to better take advantage of the capabilities of the hardware and OS, while others allow the administrator to trade functionality for speed.

Hardware and Operating System Issues

The single biggest hardware issue affecting webserver performance is RAM. A webserver should never ever have to swap, as swapping increases the latency of each request beyond a point that users consider "fast enough". This causes users to hit stop and reload, further increasing the load. You can, and should, control the MaxClients setting so that your server does not spawn so many children it starts swapping. This procedure for doing this is simple: determine the size of your average Apache process, by looking at your process list via a tool such as top, and divide this into your total available memory, leaving some room for other processes.

Beyond that the rest is mundane: get a fast enough CPU, a fast enough network card, and fast enough disks, where "fast enough" is something that needs to be determined by experimentation.

Operating system choice is largely a matter of local concerns. But some guidelines that have proven generally useful are:

  • Run the latest stable release and patchlevel of the operating system that you choose. Many OS suppliers have introduced significant performance improvements to their TCP stacks and thread libraries in recent years.

  • If your OS supports a sendfile(2) system call, make sure you install the release and/or patches needed to enable it. (With Linux, for example, this means using Linux 2.4 or later. For early releases of Solaris 8, you may need to apply a patch.) On systems where it is available, sendfile enables Apache 2 to deliver static content faster and with lower CPU utilization.

Run-Time Configuration Issues

Related Modules Related Directives
  • mod_dir
  • mpm_common
  • mod_status
  • AllowOverride
  • DirectoryIndex
  • HostnameLookups
  • EnableMMAP
  • EnableSendfile
  • KeepAliveTimeout
  • MaxSpareServers
  • MinSpareServers
  • Options
  • StartServers

HostnameLookups and other DNS considerations

Prior to Apache 1.3, HostnameLookups defaulted to On. This adds latency to every request because it requires a DNS lookup to complete before the request is finished. In Apache 1.3 this setting defaults to Off. If you need to have addresses in your log files resolved to hostnames, use the logresolve program that comes with Apache, on one of the numerous log reporting packages which are available.

It is recommended that you do this sort of postprocessing of your log files on some machine other than the production web server machine, in order that this activity not adversely affect server performance.

If you use any Allow from domain or Deny from domain directives (i.e., using a hostname, or a domain name, rather than an IP address) then you will pay for a double reverse DNS lookup (a reverse, followed by a forward to make sure that the reverse is not being spoofed). For best performance, therefore, use IP addresses, rather than names, when using these directives, if possible.

Note that it's possible to scope the directives, such as within a <Location /server-status> section. In this case the DNS lookups are only performed on requests matching the criteria. Here's an example which disables lookups except for .html and .cgi files:

HostnameLookups off
<Files ~ "\.(html|cgi)$">
HostnameLookups on
 </Files>

But even still, if you just need DNS names in some CGIs you could consider doing the gethostbyname call in the specific CGIs that need it.

FollowSymLinks and SymLinksIfOwnerMatch

Wherever in your URL-space you do not have an Options FollowSymLinks, or you do have an Options SymLinksIfOwnerMatch Apache will have to issue extra system calls to check up on symlinks. One extra call per filename component. For example, if you had:

DocumentRoot /www/htdocs
<Directory />
Options SymLinksIfOwnerMatch
 </Directory>

and a request is made for the URI /index.html. Then Apache will perform lstat(2) on /www, /www/htdocs, and /www/htdocs/index.html. The results of these lstats are never cached, so they will occur on every single request. If you really desire the symlinks security checking you can do something like this:

DocumentRoot /www/htdocs
<Directory />
Options FollowSymLinks
 </Directory>

<Directory /www/htdocs>
Options -FollowSymLinks +SymLinksIfOwnerMatch
 </Directory>

This at least avoids the extra checks for the DocumentRoot path. Note that you'll need to add similar sections if you have any Alias or RewriteRule paths outside of your document root. For highest performance, and no symlink protection, set FollowSymLinks everywhere, and never set SymLinksIfOwnerMatch.

AllowOverride

Wherever in your URL-space you allow overrides (typically .htaccess files) Apache will attempt to open .htaccess for each filename component. For example,

DocumentRoot /www/htdocs
<Directory />
AllowOverride all
 </Directory>

and a request is made for the URI /index.html. Then Apache will attempt to open /.htaccess, /www/.htaccess, and /www/htdocs/.htaccess. The solutions are similar to the previous case of Options FollowSymLinks. For highest performance use AllowOverride None everywhere in your filesystem.

Negotiation

If at all possible, avoid content-negotiation if you're really interested in every last ounce of performance. In practice the benefits of negotiation outweigh the performance penalties. There's one case where you can speed up the server. Instead of using a wildcard such as:

DirectoryIndex index

Use a complete list of options:

DirectoryIndex index.cgi index.pl index.shtml index.html

where you list the most common choice first.

Also note that explicitly creating a type-map file provides better performance than using MultiViews, as the necessary information can be determined by reading this single file, rather than having to scan the directory for files.

If your site needs content negotiation consider using type-map files, rather than the Options MultiViews directive to accomplish the negotiation. See the Content Negotiation documentation for a full discussion of the methods of negotiation, and instructions for creating type-map files.

Memory-mapping

In situations where Apache 2.0 needs to look at the contents of a file being delivered--for example, when doing server-side-include processing--it normally memory-maps the file if the OS supports some form of mmap(2).

On some platforms, this memory-mapping improves performance. However, there are cases where memory-mapping can hurt the performance or even the stability of the httpd:

  • On some operating systems, mmap does not scale as well as read(2) when the number of CPUs increases. On multiprocessor Solaris servers, for example, Apache 2.0 sometimes delivers server-parsed files faster when mmap is disabled.

  • If you memory-map a file located on an NFS-mounted filesystem and a process on another NFS client machine deletes or truncates the file, your process may get a bus error the next time it tries to access the mapped file content.

For installations where either of these factors applies, you should use EnableMMAP off to disable the memory-mapping of delivered files. (Note: This directive can be overridden on a per-directory basis.)

Sendfile

In situations where Apache 2.0 can ignore the contents of the file to be delivered -- for example, when serving static file content -- it normally uses the kernel sendfile support the file if the OS supports the sendfile(2) operation.

On most platforms, using sendfile improves performance by eliminating separate read and send mechanics. However, there are cases where using sendfile can harm the stability of the httpd:

  • Some platforms may have broken sendfile support that the build system did not detect, especially if the binaries were built on another box and moved to such a machine with broken sendfile support.

  • With an NFS-mounted files, the kernel may be unable to reliably serve the network file through it's own cache.

For installations where either of these factors applies, you should use EnableSendfile off to disable sendfile delivery of file contents. (Note: This directive can be overridden on a per-directory basis.)

Process Creation

Prior to Apache 1.3 the MinSpareServers, MaxSpareServers, and StartServers settings all had drastic effects on benchmark results. In particular, Apache required a "ramp-up" period in order to reach a number of children sufficient to serve the load being applied. After the initial spawning of StartServers children, only one child per second would be created to satisfy the MinSpareServers setting. So a server being accessed by 100 simultaneous clients, using the default StartServers of 5 would take on the order 95 seconds to spawn enough children to handle the load. This works fine in practice on real-life servers, because they aren't restarted frequently. But does really poorly on benchmarks which might only run for ten minutes.

The one-per-second rule was implemented in an effort to avoid swamping the machine with the startup of new children. If the machine is busy spawning children it can't service requests. But it has such a drastic effect on the perceived performance of Apache that it had to be replaced. As of Apache 1.3, the code will relax the one-per-second rule. It will spawn one, wait a second, then spawn two, wait a second, then spawn four, and it will continue exponentially until it is spawning 32 children per second. It will stop whenever it satisfies the MinSpareServers setting.

This appears to be responsive enough that it's almost unnecessary to twiddle the MinSpareServers, MaxSpareServers and StartServers knobs. When more than 4 children are spawned per second, a message will be emitted to the ErrorLog. If you see a lot of these errors then consider tuning these settings. Use the mod_status output as a guide.

Related to process creation is process death induced by the MaxRequestsPerChild setting. By default this is 0, which means that there is no limit to the number of requests handled per child. If your configuration currently has this set to some very low number, such as 30, you may want to bump this up significantly. If you are running SunOS or an old version of Solaris, limit this to 10000 or so because of memory leaks.

When keep-alives are in use, children will be kept busy doing nothing waiting for more requests on the already open connection. The default KeepAliveTimeout of 15 seconds attempts to minimize this effect. The tradeoff here is between network bandwidth and server resources. In no event should you raise this above about 60 seconds, as most of the benefits are lost.

Compile-Time Configuration Issues

Choosing an MPM

Apache 2.x supports pluggable concurrency models, called Multi-Processing Modules (MPMs). When building Apache, you must choose an MPM to use. There are platform-specific MPMs for some platforms: beos, mpm_netware, mpmt_os2, and mpm_winnt. For general Unix-type systems, there are several MPMs from which to choose. The choice of MPM can affect the speed and scalability of the httpd:

  • The worker MPM uses multiple child processes with many threads each. Each thread handles one connection at a time. Worker generally is a good choice for high-traffic servers because it has a smaller memory footprint than the prefork MPM.
  • The prefork MPM uses multiple child processes with one thread each. Each process handles one connection at a time. On many systems, prefork is comparable in speed to worker, but it uses more memory. Prefork's threadless design has advantages over worker in some situations: it can be used with non-thread-safe third-party modules, and it is easier to debug on platforms with poor thread debugging support.

For more information on these and other MPMs, please see the MPM documentation.

Modules

Since memory usage is such an important consideration in performance, you should attempt to eliminate modules that youare not actually using. If you have built the modules as DSOs, eliminating modules is a simple matter of commenting out the associated LoadModule directive for that module. This allows you to experiment with removing modules, and seeing if your site still functions in their absense.

If, on the other hand, you have modules statically linked into your Apache binary, you will need to recompile Apache in order to remove unwanted modules.

An associated question that arises here is, of course, what modules you need, and which ones you don't. The answer here will, of course, vary from one web site to another. However, the minimal list of modules which you can get by with tends to include mod_mime, mod_dir, and mod_log_config. mod_log_config is, of course, optional, as you can run a web site without log files. This is, however, not recommended.

Atomic Operations

Some modules, such as mod_cache and recent development builds of the worker MPM, use APR's atomic API. This API provides atomic operations that can be used for lightweight thread synchronization.

By default, APR implements these operations using the most efficient mechanism available on each target OS/CPU platform. Many modern CPUs, for example, have an instruction that does an atomic compare-and-swap (CAS) operation in hardware. On some platforms, however, APR defaults to a slower, mutex-based implementation of the atomic API in order to ensure compatibility with older CPU models that lack such instructions. If you are building Apache for one of these platforms, and you plan to run only on newer CPUs, you can select a faster atomic implementation at build time by configuring Apache with the --enable-nonportable-atomics option:

./buildconf
./configure --with-mpm=worker --enable-nonportable-atomics=yes

The --enable-nonportable-atomics option is relevant for the following platforms:

  • Solaris on SPARC
    By default, APR uses mutex-based atomics on Solaris/SPARC. If you configure with --enable-nonportable-atomics, however, APR generates code that uses a SPARC v8plus opcode for fast hardware compare-and-swap. If you configure Apache with this option, the atomic operations will be more efficient (allowing for lower CPU utilization and higher concurrency), but the resulting executable will run only on UltraSPARC chips.
  • Linux on x86
    By default, APR uses mutex-based atomics on Linux. If you configure with --enable-nonportable-atomics, however, APR generates code that uses a 486 opcode for fast hardware compare-and-swap. This will result in more efficient atomic operations, but the resulting executable will run only on 486 and later chips (and not on 386).

mod_status and ExtendedStatus On

If you include mod_status and you also set ExtendedStatus On when building and running Apache, then on every request Apache will perform two calls to gettimeofday(2) (or times(2) depending on your operating system), and (pre-1.3) several extra calls to time(2). This is all done so that the status report contains timing indications. For highest performance, set ExtendedStatus off (which is the default).

accept Serialization - multiple sockets

Warning:

This section has not been fully updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

This discusses a shortcoming in the Unix socket API. Suppose your web server uses multiple Listen statements to listen on either multiple ports or multiple addresses. In order to test each socket to see if a connection is ready Apache uses select(2). select(2) indicates that a socket has zero or at least one connection waiting on it. Apache's model includes multiple children, and all the idle ones test for new connections at the same time. A naive implementation looks something like this (these examples do not match the code, they're contrived for pedagogical purposes):

for (;;) {
for (;;) {
fd_set accept_fds;

FD_ZERO (&accept_fds);
for (i = first_socket; i <= last_socket; ++i) {
FD_SET (i, &accept_fds);
 }
rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
if (rc < 1) continue;
new_connection = -1;
for (i = first_socket; i <= last_socket; ++i) {
if (FD_ISSET (i, &accept_fds)) {
new_connection = accept (i, NULL, NULL);
if (new_connection != -1) break;
 }
 }
if (new_connection != -1) break;
 }
process the new_connection;
 }

But this naive implementation has a serious starvation problem. Recall that multiple children execute this loop at the same time, and so multiple children will block at select when they are in between requests. All those blocked children will awaken and return from select when a single request appears on any socket (the number of children which awaken varies depending on the operating system and timing issues). They will all then fall down into the loop and try to accept the connection. But only one will succeed (assuming there's still only one connection ready), the rest will be blocked in accept. This effectively locks those children into serving requests from that one socket and no other sockets, and they'll be stuck there until enough new requests appear on that socket to wake them all up. This starvation problem was first documented in PR#467. There are at least two solutions.

One solution is to make the sockets non-blocking. In this case the accept won't block the children, and they will be allowed to continue immediately. But this wastes CPU time. Suppose you have ten idle children in select, and one connection arrives. Then nine of those children will wake up, try to accept the connection, fail, and loop back into select, accomplishing nothing. Meanwhile none of those children are servicing requests that occurred on other sockets until they get back up to the select again. Overall this solution does not seem very fruitful unless you have as many idle CPUs (in a multiprocessor box) as you have idle children, not a very likely situation.

Another solution, the one used by Apache, is to serialize entry into the inner loop. The loop looks like this (differences highlighted):

for (;;) {
accept_mutex_on ();
for (;;) {
fd_set accept_fds;

FD_ZERO (&accept_fds);
for (i = first_socket; i <= last_socket; ++i) {
FD_SET (i, &accept_fds);
 }
rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
if (rc < 1) continue;
new_connection = -1;
for (i = first_socket; i <= last_socket; ++i) {
if (FD_ISSET (i, &accept_fds)) {
new_connection = accept (i, NULL, NULL);
if (new_connection != -1) break;
 }
 }
if (new_connection != -1) break;
 }
accept_mutex_off ();
process the new_connection;
 }

The functions accept_mutex_on and accept_mutex_off implement a mutual exclusion semaphore. Only one child can have the mutex at any time. There are several choices for implementing these mutexes. The choice is defined in src/conf.h (pre-1.3) or src/include/ap_config.h (1.3 or later). Some architectures do not have any locking choice made, on these architectures it is unsafe to use multiple Listen directives.

The directive AcceptMutex can be used to change the selected mutex implementation at run-time.

AcceptMutex flock

This method uses the flock(2) system call to lock a lock file (located by the LockFile directive).

AcceptMutex fcntl

This method uses the fcntl(2) system call to lock a lock file (located by the LockFile directive).

AcceptMutex sysvsem

(1.3 or later) This method uses SysV-style semaphores to implement the mutex. Unfortunately SysV-style semaphores have some bad side-effects. One is that it's possible Apache will die without cleaning up the semaphore (see the ipcs(8) man page). The other is that the semaphore API allows for a denial of service attack by any CGIs running under the same uid as the webserver (i.e., all CGIs, unless you use something like suexec or cgiwrapper). For these reasons this method is not used on any architecture except IRIX (where the previous two are prohibitively expensive on most IRIX boxes).

AcceptMutex pthread

(1.3 or later) This method uses POSIX mutexes and should work on any architecture implementing the full POSIX threads specification, however appears to only work on Solaris (2.5 or later), and even then only in certain configurations. If you experiment with this you should watch out for your server hanging and not responding. Static content only servers may work just fine.

AcceptMutex posixsem

(2.0 or later) This method uses POSIX semaphores. The semaphore ownership is not recovered if a thread in the process holding the mutex segfaults, resulting in a hang of the web server.

If your system has another method of serialization which isn't in the above list then it may be worthwhile adding code for it to APR.

Another solution that has been considered but never implemented is to partially serialize the loop -- that is, let in a certain number of processes. This would only be of interest on multiprocessor boxes where it's possible multiple children could run simultaneously, and the serialization actually doesn't take advantage of the full bandwidth. This is a possible area of future investigation, but priority remains low because highly parallel web servers are not the norm.

Ideally you should run servers without multiple Listen statements if you want the highest performance. But read on.

accept Serialization - single socket

The above is fine and dandy for multiple socket servers, but what about single socket servers? In theory they shouldn't experience any of these same problems because all children can just block in accept(2) until a connection arrives, and no starvation results. In practice this hides almost the same "spinning" behaviour discussed above in the non-blocking solution. The way that most TCP stacks are implemented, the kernel actually wakes up all processes blocked in accept when a single connection arrives. One of those processes gets the connection and returns to user-space, the rest spin in the kernel and go back to sleep when they discover there's no connection for them. This spinning is hidden from the user-land code, but it's there nonetheless. This can result in the same load-spiking wasteful behaviour that a non-blocking solution to the multiple sockets case can.

For this reason we have found that many architectures behave more "nicely" if we serialize even the single socket case. So this is actually the default in almost all cases. Crude experiments under Linux (2.0.30 on a dual Pentium pro 166 w/128Mb RAM) have shown that the serialization of the single socket case causes less than a 3% decrease in requests per second over unserialized single-socket. But unserialized single-socket showed an extra 100ms latency on each request. This latency is probably a wash on long haul lines, and only an issue on LANs. If you want to override the single socket serialization you can define SINGLE_LISTEN_UNSERIALIZED_ACCEPT and then single-socket servers will not serialize at all.

Lingering Close

As discussed in draft-ietf-http-connection-00.txt section 8, in order for an HTTP server to reliably implement the protocol it needs to shutdown each direction of the communication independently (recall that a TCP connection is bi-directional, each half is independent of the other). This fact is often overlooked by other servers, but is correctly implemented in Apache as of 1.2.

When this feature was added to Apache it caused a flurry of problems on various versions of Unix because of a shortsightedness. The TCP specification does not state that the FIN_WAIT_2 state has a timeout, but it doesn't prohibit it. On systems without the timeout, Apache 1.2 induces many sockets stuck forever in the FIN_WAIT_2 state. In many cases this can be avoided by simply upgrading to the latest TCP/IP patches supplied by the vendor. In cases where the vendor has never released patches (i.e., SunOS4 -- although folks with a source license can patch it themselves) we have decided to disable this feature.

There are two ways of accomplishing this. One is the socket option SO_LINGER. But as fate would have it, this has never been implemented properly in most TCP/IP stacks. Even on those stacks with a proper implementation (i.e., Linux 2.0.31) this method proves to be more expensive (cputime) than the next solution.

For the most part, Apache implements this in a function called lingering_close (in http_main.c). The function looks roughly like this:

void lingering_close (int s)
{
char junk_buffer[2048];

/* shutdown the sending side */
shutdown (s, 1);

signal (SIGALRM, lingering_death);
alarm (30);

for (;;) {
select (s for reading, 2 second timeout);
if (error) break;
if (s is ready for reading) {
if (read (s, junk_buffer, sizeof (junk_buffer)) <= 0) {
break;
 }
/* just toss away whatever is here */
 }
 }

close (s);
 }

This naturally adds some expense at the end of a connection, but it is required for a reliable implementation. As HTTP/1.1 becomes more prevalent, and all connections are persistent, this expense will be amortized over more requests. If you want to play with fire and disable this feature you can define NO_LINGCLOSE, but this is not recommended at all. In particular, as HTTP/1.1 pipelined persistent connections come into use lingering_close is an absolute necessity (and pipelined connections are faster, so you want to support them).

Scoreboard File

Apache's parent and children communicate with each other through something called the scoreboard. Ideally this should be implemented in shared memory. For those operating systems that we either have access to, or have been given detailed ports for, it typically is implemented using shared memory. The rest default to using an on-disk file. The on-disk file is not only slow, but it is unreliable (and less featured). Peruse the src/main/conf.h file for your architecture and look for either USE_MMAP_SCOREBOARD or USE_SHMGET_SCOREBOARD. Defining one of those two (as well as their companions HAVE_MMAP and HAVE_SHMGET respectively) enables the supplied shared memory code. If your system has another type of shared memory, edit the file src/main/http_main.c and add the hooks necessary to use it in Apache. (Send us back a patch too please.)

Historical note: The Linux port of Apache didn't start to use shared memory until version 1.2 of Apache. This oversight resulted in really poor and unreliable behaviour of earlier versions of Apache on Linux.

DYNAMIC_MODULE_LIMIT

If you have no intention of using dynamically loaded modules (you probably don't if you're reading this and tuning your server for every last ounce of performance) then you should add -DDYNAMIC_MODULE_LIMIT=0 when building your server. This will save RAM that's allocated only for supporting dynamically loaded modules.

Appendix: Detailed Analysis of a Trace

Here is a system call trace of Apache 2.0.38 with the worker MPM on Solaris 8. This trace was collected using:

truss -l -p httpd_child_pid.

The -l option tells truss to log the ID of the LWP (lightweight process--Solaris's form of kernel-level thread) that invokes each system call.

Other systems may have different system call tracing utilities such as strace, ktrace, or par. They all produce similar output.

In this trace, a client has requested a 10KB static file from the httpd. Traces of non-static requests or requests with content negotiation look wildly different (and quite ugly in some cases).

/67:    accept(3, 0x00200BEC, 0x00200C0C, 1) (sleeping...)
/67:    accept(3, 0x00200BEC, 0x00200C0C, 1)            = 9

In this trace, the listener thread is running within LWP #67.

Note the lack of accept(2) serialization. On this particular platform, the worker MPM uses an unserialized accept by default unless it is listening on multiple ports.
/65:    lwp_park(0x00000000, 0)                         = 0
/67:    lwp_unpark(65, 1)                               = 0

Upon accepting the connection, the listener thread wakes up a worker thread to do the request processing. In this trace, the worker thread that handles the request is mapped to LWP #65.

/65:    getsockname(9, 0x00200BA4, 0x00200BC4, 1)       = 0

In order to implement virtual hosts, Apache needs to know the local socket address used to accept the connection. It is possible to eliminate this call in many situations (such as when there are no virtual hosts, or when Listen directives are used which do not have wildcard addresses). But no effort has yet been made to do these optimizations.

/65:    brk(0x002170E8)                                 = 0
/65:    brk(0x002190E8)                                 = 0

The brk(2) calls allocate memory from the heap. It is rare to see these in a system call trace, because the httpd uses custom memory allocators (apr_pool and apr_bucket_alloc) for most request processing. In this trace, the httpd has just been started, so it must call malloc(3) to get the blocks of raw memory with which to create the custom memory allocators.

/65:    fcntl(9, F_GETFL, 0x00000000)                   = 2
/65:    fstat64(9, 0xFAF7B818)                          = 0
/65:    getsockopt(9, 65535, 8192, 0xFAF7B918, 0xFAF7B910, 2190656) = 0
/65:    fstat64(9, 0xFAF7B818)                          = 0
/65:    getsockopt(9, 65535, 8192, 0xFAF7B918, 0xFAF7B914, 2190656) = 0
/65:    setsockopt(9, 65535, 8192, 0xFAF7B918, 4, 2190656) = 0
/65:    fcntl(9, F_SETFL, 0x00000082)                   = 0

Next, the worker thread puts the connection to the client (file descriptor 9) in non-blocking mode. The setsockopt(2) and getsockopt(2) calls are a side-effect of how Solaris's libc handles fcntl(2) on sockets.

/65:    read(9, " G E T   / 1 0 k . h t m".., 8000)     = 97

The worker thread reads the request from the client.

/65:    stat("/var/httpd/apache/httpd-8999/htdocs/10k.html", 0xFAF7B978) = 0
/65:    open("/var/httpd/apache/httpd-8999/htdocs/10k.html", O_RDONLY) = 10

This httpd has been configured with Options FollowSymLinks and AllowOverride None. Thus it doesn't need to lstat(2) each directory in the path leading up to the requested file, nor check for .htaccess files. It simply calls stat(2) to verify that the file: 1) exists, and 2) is a regular file, not a directory.

/65:    sendfilev(0, 9, 0x00200F90, 2, 0xFAF7B53C)      = 10269

In this example, the httpd is able to send the HTTP response header and the requested file with a single sendfilev(2) system call. Sendfile semantics vary among operating systems. On some other systems, it is necessary to do a write(2) or writev(2) call to send the headers before calling sendfile(2).

/65:    write(4, " 1 2 7 . 0 . 0 . 1   -  ".., 78)      = 78

This write(2) call records the request in the access log. Note that one thing missing from this trace is a time(2) call. Unlike Apache 1.3, Apache 2.0 uses gettimeofday(3) to look up the time. On some operating systems, like Linux or Solaris, gettimeofday has an optimized implementation that doesn't require as much overhead as a typical system call.

/65:    shutdown(9, 1, 1)                               = 0
/65:    poll(0xFAF7B980, 1, 2000)                       = 1
/65:    read(9, 0xFAF7BC20, 512)                        = 0
/65:    close(9)                                        = 0

The worker thread does a lingering close of the connection.

/65:    close(10)                                       = 0
/65:    lwp_park(0x00000000, 0)         (sleeping...)

Finally the worker thread closes the file that it has just delivered and blocks until the listener assigns it another connection.

/67:    accept(3, 0x001FEB74, 0x001FEB94, 1) (sleeping...)

Meanwhile, the listener thread is able to accept another connection as soon as it has dispatched this connection to a worker thread (subject to some flow-control logic in the worker MPM that throttles the listener if all the available workers are busy). Though it isn't apparent from this trace, the next accept(2) can (and usually does, under high load conditions) occur in parallel with the worker thread's handling of the just-accepted connection.


URL Rewriting Guide - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Miscellaneous Documentation

URL Rewriting Guide

Originally written by
Ralf S. Engelschall <rse@apache.org>
December 1997

This document supplements the mod_rewrite reference documentation. It describes how one can use Apache's mod_rewrite to solve typical URL-based problems with which webmasters are commonony confronted. We give detailed descriptions on how to solve each problem by configuring URL rewriting rulesets.

Introduction to mod_rewrite

The Apache module mod_rewrite is a killer one, i.e. it is a really sophisticated module which provides a powerful way to do URL manipulations. With it you can do nearly all types of URL manipulations you ever dreamed about. The price you have to pay is to accept complexity, because mod_rewrite's major drawback is that it is not easy to understand and use for the beginner. And even Apache experts sometimes discover new aspects where mod_rewrite can help.

In other words: With mod_rewrite you either shoot yourself in the foot the first time and never use it again or love it for the rest of your life because of its power. This paper tries to give you a few initial success events to avoid the first case by presenting already invented solutions to you.

Practical Solutions

Here come a lot of practical solutions I've either invented myself or collected from other people's solutions in the past. Feel free to learn the black magic of URL rewriting from these examples.

ATTENTION: Depending on your server-configuration it can be necessary to slightly change the examples for your situation, e.g. adding the [PT] flag when additionally using mod_alias and mod_userdir, etc. Or rewriting a ruleset to fit in .htaccess context instead of per-server context. Always try to understand what a particular ruleset really does before you use it. It avoid problems.

URL Layout

Canonical URLs

Description:

On some webservers there are more than one URL for a resource. Usually there are canonical URLs (which should be actually used and distributed) and those which are just shortcuts, internal ones, etc. Independent of which URL the user supplied with the request he should finally see the canonical one only.

Solution:

We do an external HTTP redirect for all non-canonical URLs to fix them in the location view of the Browser and for all subsequent requests. In the example ruleset below we replace /~user by the canonical /u/user and fix a missing trailing slash for /u/user.

RewriteRule   ^/~([^/]+)/?(.*)    /u/$1/$2  [R]
RewriteRule   ^/([uge])/([^/]+)$  /$1/$2/   [R]

Canonical Hostnames

Description:
The goal of this rule is to force the use of a particular hostname, in preference to other hostnames which may be used to reach the same site. For example, if you wish to force the use of www.example.com instead of example.com, you might use a variant of the following recipe.
Solution:
# For sites running on a port other than 80
RewriteCond %{HTTP_HOST}   !^fully\.qualified\.domain\.name [NC]
RewriteCond %{HTTP_HOST}   !^$
RewriteCond %{SERVER_PORT} !^80$
RewriteRule ^/(.*)         http://fully.qualified.domain.name:%{SERVER_PORT}/$1 [L,R]

# And for a site running on port 80
RewriteCond %{HTTP_HOST}   !^fully\.qualified\.domain\.name [NC]
RewriteCond %{HTTP_HOST}   !^$
RewriteRule ^/(.*)         http://fully.qualified.domain.name/$1 [L,R]

Moved DocumentRoot

Description:

Usually the DocumentRoot of the webserver directly relates to the URL "/". But often this data is not really of top-level priority, it is perhaps just one entity of a lot of data pools. For instance at our Intranet sites there are /e/www/ (the homepage for WWW), /e/sww/ (the homepage for the Intranet) etc. Now because the data of the DocumentRoot stays at /e/www/ we had to make sure that all inlined images and other stuff inside this data pool work for subsequent requests.

Solution:

We just redirect the URL / to /e/www/. While is seems trivial it is actually trivial with mod_rewrite, only. Because the typical old mechanisms of URL Aliases (as provides by mod_alias and friends) only used prefix matching. With this you cannot do such a redirection because the DocumentRoot is a prefix of all URLs. With mod_rewrite it is really trivial:

RewriteEngine on
RewriteRule   ^/$  /e/www/  [R]

Trailing Slash Problem

Description:

Every webmaster can sing a song about the problem of the trailing slash on URLs referencing directories. If they are missing, the server dumps an error, because if you say /~quux/foo instead of /~quux/foo/ then the server searches for a file named foo. And because this file is a directory it complains. Actually it tries to fix it itself in most of the cases, but sometimes this mechanism need to be emulated by you. For instance after you have done a lot of complicated URL rewritings to CGI scripts etc.

Solution:

The solution to this subtle problem is to let the server add the trailing slash automatically. To do this correctly we have to use an external redirect, so the browser correctly requests subsequent images etc. If we only did a internal rewrite, this would only work for the directory page, but would go wrong when any images are included into this page with relative URLs, because the browser would request an in-lined object. For instance, a request for image.gif in /~quux/foo/index.html would become /~quux/image.gif without the external redirect!

So, to do this trick we write:

RewriteEngine  on
RewriteBase    /~quux/
RewriteRule    ^foo$  foo/  [R]

The crazy and lazy can even do the following in the top-level .htaccess file of their homedir. But notice that this creates some processing overhead.

RewriteEngine  on
RewriteBase    /~quux/
RewriteCond    %{REQUEST_FILENAME}  -d
RewriteRule    ^(.+[^/])$           $1/  [R]

Webcluster through Homogeneous URL Layout

Description:

We want to create a homogeneous and consistent URL layout over all WWW servers on a Intranet webcluster, i.e. all URLs (per definition server local and thus server dependent!) become actually server independent! What we want is to give the WWW namespace a consistent server-independent layout: no URL should have to include any physically correct target server. The cluster itself should drive us automatically to the physical target host.

Solution:

First, the knowledge of the target servers come from (distributed) external maps which contain information where our users, groups and entities stay. The have the form

user1  server_of_user1
user2  server_of_user2
:      :

We put them into files map.xxx-to-host. Second we need to instruct all servers to redirect URLs of the forms

/u/user/anypath
/g/group/anypath
/e/entity/anypath

to

http://physical-host/u/user/anypath
http://physical-host/g/group/anypath
http://physical-host/e/entity/anypath

when the URL is not locally valid to a server. The following ruleset does this for us by the help of the map files (assuming that server0 is a default server which will be used if a user has no entry in the map):

RewriteEngine on

RewriteMap      user-to-host   txt:/path/to/map.user-to-host
RewriteMap     group-to-host   txt:/path/to/map.group-to-host
RewriteMap    entity-to-host   txt:/path/to/map.entity-to-host

RewriteRule   ^/u/([^/]+)/?(.*)   http://${user-to-host:$1|server0}/u/$1/$2
RewriteRule   ^/g/([^/]+)/?(.*)  http://${group-to-host:$1|server0}/g/$1/$2
RewriteRule   ^/e/([^/]+)/?(.*) http://${entity-to-host:$1|server0}/e/$1/$2

RewriteRule   ^/([uge])/([^/]+)/?$          /$1/$2/.www/
RewriteRule   ^/([uge])/([^/]+)/([^.]+.+)   /$1/$2/.www/$3\

Move Homedirs to Different Webserver

Description:

Many webmasters have asked for a solution to the following situation: They wanted to redirect just all homedirs on a webserver to another webserver. They usually need such things when establishing a newer webserver which will replace the old one over time.

Solution:

The solution is trivial with mod_rewrite. On the old webserver we just redirect all /~user/anypath URLs to http://newserver/~user/anypath.

RewriteEngine on
RewriteRule   ^/~(.+)  http://newserver/~$1  [R,L]

Structured Homedirs

Description:

Some sites with thousands of users usually use a structured homedir layout, i.e. each homedir is in a subdirectory which begins for instance with the first character of the username. So, /~foo/anypath is /home/f/foo/.www/anypath while /~bar/anypath is /home/b/bar/.www/anypath.

Solution:

We use the following ruleset to expand the tilde URLs into exactly the above layout.

RewriteEngine on
RewriteRule   ^/~(([a-z])[a-z0-9]+)(.*)  /home/$2/$1/.www$3

Filesystem Reorganization

Description:

This really is a hardcore example: a killer application which heavily uses per-directory RewriteRules to get a smooth look and feel on the Web while its data structure is never touched or adjusted. Background: net.sw is my archive of freely available Unix software packages, which I started to collect in 1992. It is both my hobby and job to to this, because while I'm studying computer science I have also worked for many years as a system and network administrator in my spare time. Every week I need some sort of software so I created a deep hierarchy of directories where I stored the packages:

drwxrwxr-x   2 netsw  users    512 Aug  3 18:39 Audio/
drwxrwxr-x   2 netsw  users    512 Jul  9 14:37 Benchmark/
drwxrwxr-x  12 netsw  users    512 Jul  9 00:34 Crypto/
drwxrwxr-x   5 netsw  users    512 Jul  9 00:41 Database/
drwxrwxr-x   4 netsw  users    512 Jul 30 19:25 Dicts/
drwxrwxr-x  10 netsw  users    512 Jul  9 01:54 Graphic/
drwxrwxr-x   5 netsw  users    512 Jul  9 01:58 Hackers/
drwxrwxr-x   8 netsw  users    512 Jul  9 03:19 InfoSys/
drwxrwxr-x   3 netsw  users    512 Jul  9 03:21 Math/
drwxrwxr-x   3 netsw  users    512 Jul  9 03:24 Misc/
drwxrwxr-x   9 netsw  users    512 Aug  1 16:33 Network/
drwxrwxr-x   2 netsw  users    512 Jul  9 05:53 Office/
drwxrwxr-x   7 netsw  users    512 Jul  9 09:24 SoftEng/
drwxrwxr-x   7 netsw  users    512 Jul  9 12:17 System/
drwxrwxr-x  12 netsw  users    512 Aug  3 20:15 Typesetting/
drwxrwxr-x  10 netsw  users    512 Jul  9 14:08 X11/

In July 1996 I decided to make this archive public to the world via a nice Web interface. "Nice" means that I wanted to offer an interface where you can browse directly through the archive hierarchy. And "nice" means that I didn't wanted to change anything inside this hierarchy - not even by putting some CGI scripts at the top of it. Why? Because the above structure should be later accessible via FTP as well, and I didn't want any Web or CGI stuff to be there.

Solution:

The solution has two parts: The first is a set of CGI scripts which create all the pages at all directory levels on-the-fly. I put them under /e/netsw/.www/ as follows:

-rw-r--r--   1 netsw  users    1318 Aug  1 18:10 .wwwacl
drwxr-xr-x  18 netsw  users     512 Aug  5 15:51 DATA/
-rw-rw-rw-   1 netsw  users  372982 Aug  5 16:35 LOGFILE
-rw-r--r--   1 netsw  users     659 Aug  4 09:27 TODO
-rw-r--r--   1 netsw  users    5697 Aug  1 18:01 netsw-about.html
-rwxr-xr-x   1 netsw  users     579 Aug  2 10:33 netsw-access.pl
-rwxr-xr-x   1 netsw  users    1532 Aug  1 17:35 netsw-changes.cgi
-rwxr-xr-x   1 netsw  users    2866 Aug  5 14:49 netsw-home.cgi
drwxr-xr-x   2 netsw  users     512 Jul  8 23:47 netsw-img/
-rwxr-xr-x   1 netsw  users   24050 Aug  5 15:49 netsw-lsdir.cgi
-rwxr-xr-x   1 netsw  users    1589 Aug  3 18:43 netsw-search.cgi
-rwxr-xr-x   1 netsw  users    1885 Aug  1 17:41 netsw-tree.cgi
-rw-r--r--   1 netsw  users     234 Jul 30 16:35 netsw-unlimit.lst

The DATA/ subdirectory holds the above directory structure, i.e. the real net.sw stuff and gets automatically updated via rdist from time to time. The second part of the problem remains: how to link these two structures together into one smooth-looking URL tree? We want to hide the DATA/ directory from the user while running the appropriate CGI scripts for the various URLs. Here is the solution: first I put the following into the per-directory configuration file in the DocumentRoot of the server to rewrite the announced URL /net.sw/ to the internal path /e/netsw:

RewriteRule  ^net.sw$       net.sw/        [R]
RewriteRule  ^net.sw/(.*)$  e/netsw/$1

The first rule is for requests which miss the trailing slash! The second rule does the real thing. And then comes the killer configuration which stays in the per-directory config file /e/netsw/.www/.wwwacl:

Options       ExecCGI FollowSymLinks Includes MultiViews

RewriteEngine on

#  we are reached via /net.sw/ prefix
RewriteBase   /net.sw/

#  first we rewrite the root dir to
#  the handling cgi script
RewriteRule   ^$                       netsw-home.cgi     [L]
RewriteRule   ^index\.html$            netsw-home.cgi     [L]

#  strip out the subdirs when
#  the browser requests us from perdir pages
RewriteRule   ^.+/(netsw-[^/]+/.+)$    $1                 [L]

#  and now break the rewriting for local files
RewriteRule   ^netsw-home\.cgi.*       -                  [L]
RewriteRule   ^netsw-changes\.cgi.*    -                  [L]
RewriteRule   ^netsw-search\.cgi.*     -                  [L]
RewriteRule   ^netsw-tree\.cgi$        -                  [L]
RewriteRule   ^netsw-about\.html$      -                  [L]
RewriteRule   ^netsw-img/.*$           -                  [L]

#  anything else is a subdir which gets handled
#  by another cgi script
RewriteRule   !^netsw-lsdir\.cgi.*     -                  [C]
RewriteRule   (.*)                     netsw-lsdir.cgi/$1

Some hints for interpretation:

  1. Notice the L (last) flag and no substitution field ('-') in the forth part
  2. Notice the ! (not) character and the C (chain) flag at the first rule in the last part
  3. Notice the catch-all pattern in the last rule

NCSA imagemap to Apache mod_imap

Description:

When switching from the NCSA webserver to the more modern Apache webserver a lot of people want a smooth transition. So they want pages which use their old NCSA imagemap program to work under Apache with the modern mod_imap. The problem is that there are a lot of hyperlinks around which reference the imagemap program via /cgi-bin/imagemap/path/to/page.map. Under Apache this has to read just /path/to/page.map.

Solution:

We use a global rule to remove the prefix on-the-fly for all requests:

RewriteEngine  on
RewriteRule    ^/cgi-bin/imagemap(.*)  $1  [PT]

Search pages in more than one directory

Description:

Sometimes it is necessary to let the webserver search for pages in more than one directory. Here MultiViews or other techniques cannot help.

Solution:

We program a explicit ruleset which searches for the files in the directories.

RewriteEngine on

#   first try to find it in custom/...
#   ...and if found stop and be happy:
RewriteCond         /your/docroot/dir1/%{REQUEST_FILENAME}  -f
RewriteRule  ^(.+)  /your/docroot/dir1/$1  [L]

#   second try to find it in pub/...
#   ...and if found stop and be happy:
RewriteCond         /your/docroot/dir2/%{REQUEST_FILENAME}  -f
RewriteRule  ^(.+)  /your/docroot/dir2/$1  [L]

#   else go on for other Alias or ScriptAlias directives,
#   etc.
RewriteRule   ^(.+)  -  [PT]

Set Environment Variables According To URL Parts

Description:

Perhaps you want to keep status information between requests and use the URL to encode it. But you don't want to use a CGI wrapper for all pages just to strip out this information.

Solution:

We use a rewrite rule to strip out the status information and remember it via an environment variable which can be later dereferenced from within XSSI or CGI. This way a URL /foo/S=java/bar/ gets translated to /foo/bar/ and the environment variable named STATUS is set to the value "java".

RewriteEngine on
RewriteRule   ^(.*)/S=([^/]+)/(.*)    $1/$3 [E=STATUS:$2]

Virtual User Hosts

Description:

Assume that you want to provide www.username.host.domain.com for the homepage of username via just DNS A records to the same machine and without any virtualhosts on this machine.

Solution:

For HTTP/1.0 requests there is no solution, but for HTTP/1.1 requests which contain a Host: HTTP header we can use the following ruleset to rewrite http://www.username.host.com/anypath internally to /home/username/anypath:

RewriteEngine on
RewriteCond   %{HTTP_HOST}                 ^www\.[^.]+\.host\.com$
RewriteRule   ^(.+)                        %{HTTP_HOST}$1          [C]
RewriteRule   ^www\.([^.]+)\.host\.com(.*) /home/$1$2

Redirect Homedirs For Foreigners

Description:

We want to redirect homedir URLs to another webserver www.somewhere.com when the requesting user does not stay in the local domain ourdomain.com. This is sometimes used in virtual host contexts.

Solution:

Just a rewrite condition:

RewriteEngine on
RewriteCond   %{REMOTE_HOST}  !^.+\.ourdomain\.com$
RewriteRule   ^(/~.+)         http://www.somewhere.com/$1 [R,L]

Redirect Failing URLs To Other Webserver

Description:

A typical FAQ about URL rewriting is how to redirect failing requests on webserver A to webserver B. Usually this is done via ErrorDocument CGI-scripts in Perl, but there is also a mod_rewrite solution. But notice that this performs more poorly than using an ErrorDocument CGI-script!

Solution:

The first solution has the best performance but less flexibility, and is less error safe:

RewriteEngine on
RewriteCond   /your/docroot/%{REQUEST_FILENAME} !-f
RewriteRule   ^(.+)                             http://webserverB.dom/$1

The problem here is that this will only work for pages inside the DocumentRoot. While you can add more Conditions (for instance to also handle homedirs, etc.) there is better variant:

RewriteEngine on
RewriteCond   %{REQUEST_URI} !-U
RewriteRule   ^(.+)          http://webserverB.dom/$1

This uses the URL look-ahead feature of mod_rewrite. The result is that this will work for all types of URLs and is a safe way. But it does a performance impact on the webserver, because for every request there is one more internal subrequest. So, if your webserver runs on a powerful CPU, use this one. If it is a slow machine, use the first approach or better a ErrorDocument CGI-script.

Extended Redirection

Description:

Sometimes we need more control (concerning the character escaping mechanism) of URLs on redirects. Usually the Apache kernels URL escape function also escapes anchors, i.e. URLs like "url#anchor". You cannot use this directly on redirects with mod_rewrite because the uri_escape() function of Apache would also escape the hash character. How can we redirect to such a URL?

Solution:

We have to use a kludge by the use of a NPH-CGI script which does the redirect itself. Because here no escaping is done (NPH=non-parseable headers). First we introduce a new URL scheme xredirect: by the following per-server config-line (should be one of the last rewrite rules):

RewriteRule ^xredirect:(.+) /path/to/nph-xredirect.cgi/$1 \
            [T=application/x-httpd-cgi,L]

This forces all URLs prefixed with xredirect: to be piped through the nph-xredirect.cgi program. And this program just looks like:

#!/path/to/perl
##
##  nph-xredirect.cgi -- NPH/CGI script for extended redirects
##  Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.
##

$| = 1;
$url = $ENV{'PATH_INFO'};

print "HTTP/1.0 302 Moved Temporarily\n";
print "Server: $ENV{'SERVER_SOFTWARE'}\n";
print "Location: $url\n";
print "Content-type: text/html\n";
print "\n";
print "<html>\n";
print "<head>\n";
print "<title>302 Moved Temporarily (EXTENDED)</title>\n";
print "</head>\n";
print "<body>\n";
print "<h1>Moved Temporarily (EXTENDED)</h1>\n";
print "The document has moved <a HREF=\"$url\">here</a>.<p>\n";
print "</body>\n";
print "</html>\n";

##EOF##

This provides you with the functionality to do redirects to all URL schemes, i.e. including the one which are not directly accepted by mod_rewrite. For instance you can now also redirect to news:newsgroup via

RewriteRule ^anyurl  xredirect:news:newsgroup
Notice: You have not to put [R] or [R,L] to the above rule because the xredirect: need to be expanded later by our special "pipe through" rule above.

Archive Access Multiplexer

Description:

Do you know the great CPAN (Comprehensive Perl Archive Network) under http://www.perl.com/CPAN? This does a redirect to one of several FTP servers around the world which carry a CPAN mirror and is approximately near the location of the requesting client. Actually this can be called an FTP access multiplexing service. While CPAN runs via CGI scripts, how can a similar approach implemented via mod_rewrite?

Solution:

First we notice that from version 3.0.0 mod_rewrite can also use the "ftp:" scheme on redirects. And second, the location approximation can be done by a RewriteMap over the top-level domain of the client. With a tricky chained ruleset we can use this top-level domain as a key to our multiplexing map.

RewriteEngine on
RewriteMap    multiplex                txt:/path/to/map.cxan
RewriteRule   ^/CxAN/(.*)              %{REMOTE_HOST}::$1                 [C]
RewriteRule   ^.+\.([a-zA-Z]+)::(.*)$  ${multiplex:$1|ftp.default.dom}$2  [R,L]

##
##  map.cxan -- Multiplexing Map for CxAN
##

de        ftp://ftp.cxan.de/CxAN/
uk        ftp://ftp.cxan.uk/CxAN/
com       ftp://ftp.cxan.com/CxAN/
 :
##EOF##

Time-Dependent Rewriting

Description:

When tricks like time-dependent content should happen a lot of webmasters still use CGI scripts which do for instance redirects to specialized pages. How can it be done via mod_rewrite?

Solution:

There are a lot of variables named TIME_xxx for rewrite conditions. In conjunction with the special lexicographic comparison patterns <STRING, >STRING and =STRING we can do time-dependent redirects:

RewriteEngine on
RewriteCond   %{TIME_HOUR}%{TIME_MIN} >0700
RewriteCond   %{TIME_HOUR}%{TIME_MIN} <1900
RewriteRule   ^foo\.html$             foo.day.html
RewriteRule   ^foo\.html$             foo.night.html

This provides the content of foo.day.html under the URL foo.html from 07:00-19:00 and at the remaining time the contents of foo.night.html. Just a nice feature for a homepage...

Backward Compatibility for YYYY to XXXX migration

Description:

How can we make URLs backward compatible (still existing virtually) after migrating document.YYYY to document.XXXX, e.g. after translating a bunch of .html files to .phtml?

Solution:

We just rewrite the name to its basename and test for existence of the new extension. If it exists, we take that name, else we rewrite the URL to its original state.

#   backward compatibility ruleset for
#   rewriting document.html to document.phtml
#   when and only when document.phtml exists
#   but no longer document.html
RewriteEngine on
RewriteBase   /~quux/
#   parse out basename, but remember the fact
RewriteRule   ^(.*)\.html$              $1      [C,E=WasHTML:yes]
#   rewrite to document.phtml if exists
RewriteCond   %{REQUEST_FILENAME}.phtml -f
RewriteRule   ^(.*)$ $1.phtml                   [S=1]
#   else reverse the previous basename cutout
RewriteCond   %{ENV:WasHTML}            ^yes$
RewriteRule   ^(.*)$ $1.html

Content Handling

From Old to New (intern)

Description:

Assume we have recently renamed the page foo.html to bar.html and now want to provide the old URL for backward compatibility. Actually we want that users of the old URL even not recognize that the pages was renamed.

Solution:

We rewrite the old URL to the new one internally via the following rule:

RewriteEngine  on
RewriteBase    /~quux/
RewriteRule    ^foo\.html$  bar.html

From Old to New (extern)

Description:

Assume again that we have recently renamed the page foo.html to bar.html and now want to provide the old URL for backward compatibility. But this time we want that the users of the old URL get hinted to the new one, i.e. their browsers Location field should change, too.

Solution:

We force a HTTP redirect to the new URL which leads to a change of the browsers and thus the users view:

RewriteEngine  on
RewriteBase    /~quux/
RewriteRule    ^foo\.html$  bar.html  [R]

Browser Dependent Content

Description:

At least for important top-level pages it is sometimes necessary to provide the optimum of browser dependent content, i.e. one has to provide a maximum version for the latest Netscape variants, a minimum version for the Lynx browsers and a average feature version for all others.

Solution:

We cannot use content negotiation because the browsers do not provide their type in that form. Instead we have to act on the HTTP header "User-Agent". The following condig does the following: If the HTTP header "User-Agent" begins with "Mozilla/3", the page foo.html is rewritten to foo.NS.html and and the rewriting stops. If the browser is "Lynx" or "Mozilla" of version 1 or 2 the URL becomes foo.20.html. All other browsers receive page foo.32.html. This is done by the following ruleset:

RewriteCond %{HTTP_USER_AGENT}  ^Mozilla/3.*
RewriteRule ^foo\.html$         foo.NS.html          [L]

RewriteCond %{HTTP_USER_AGENT}  ^Lynx/.*         [OR]
RewriteCond %{HTTP_USER_AGENT}  ^Mozilla/[12].*
RewriteRule ^foo\.html$         foo.20.html          [L]

RewriteRule ^foo\.html$         foo.32.html          [L]

Dynamic Mirror

Description:

Assume there are nice webpages on remote hosts we want to bring into our namespace. For FTP servers we would use the mirror program which actually maintains an explicit up-to-date copy of the remote data on the local machine. For a webserver we could use the program webcopy which acts similar via HTTP. But both techniques have one major drawback: The local copy is always just as up-to-date as often we run the program. It would be much better if the mirror is not a static one we have to establish explicitly. Instead we want a dynamic mirror with data which gets updated automatically when there is need (updated data on the remote host).

Solution:

To provide this feature we map the remote webpage or even the complete remote webarea to our namespace by the use of the Proxy Throughput feature (flag [P]):

RewriteEngine  on
RewriteBase    /~quux/
RewriteRule    ^hotsheet/(.*)$  http://www.tstimpreso.com/hotsheet/$1  [P]

RewriteEngine  on
RewriteBase    /~quux/
RewriteRule    ^usa-news\.html$   http://www.quux-corp.com/news/index.html  [P]

Reverse Dynamic Mirror

Description:
...
Solution:
RewriteEngine on
RewriteCond   /mirror/of/remotesite/$1           -U
RewriteRule   ^http://www\.remotesite\.com/(.*)$ /mirror/of/remotesite/$1

Retrieve Missing Data from Intranet

Description:

This is a tricky way of virtually running a corporate (external) Internet webserver (www.quux-corp.dom), while actually keeping and maintaining its data on a (internal) Intranet webserver (www2.quux-corp.dom) which is protected by a firewall. The trick is that on the external webserver we retrieve the requested data on-the-fly from the internal one.

Solution:

First, we have to make sure that our firewall still protects the internal webserver and that only the external webserver is allowed to retrieve data from it. For a packet-filtering firewall we could for instance configure a firewall ruleset like the following:

ALLOW Host www.quux-corp.dom Port >1024 --> Host www2.quux-corp.dom Port 80
DENY  Host *                 Port *     --> Host www2.quux-corp.dom Port 80

Just adjust it to your actual configuration syntax. Now we can establish the mod_rewrite rules which request the missing data in the background through the proxy throughput feature:

RewriteRule ^/~([^/]+)/?(.*)          /home/$1/.www/$2
RewriteCond %{REQUEST_FILENAME}       !-f
RewriteCond %{REQUEST_FILENAME}       !-d
RewriteRule ^/home/([^/]+)/.www/?(.*) http://www2.quux-corp.dom/~$1/pub/$2 [P]

Load Balancing

Description:

Suppose we want to load balance the traffic to www.foo.com over www[0-5].foo.com (a total of 6 servers). How can this be done?

Solution:

There are a lot of possible solutions for this problem. We will discuss first a commonly known DNS-based variant and then the special one with mod_rewrite:

  1. DNS Round-Robin

    The simplest method for load-balancing is to use the DNS round-robin feature of BIND. Here you just configure www[0-9].foo.com as usual in your DNS with A(address) records, e.g.

    www0   IN  A       1.2.3.1
www1   IN  A       1.2.3.2
www2   IN  A       1.2.3.3
www3   IN  A       1.2.3.4
www4   IN  A       1.2.3.5
www5   IN  A       1.2.3.6

    Then you additionally add the following entry:

    www    IN  CNAME   www0.foo.com.
       IN  CNAME   www1.foo.com.
       IN  CNAME   www2.foo.com.
       IN  CNAME   www3.foo.com.
       IN  CNAME   www4.foo.com.
       IN  CNAME   www5.foo.com.
       IN  CNAME   www6.foo.com.

    Notice that this seems wrong, but is actually an intended feature of BIND and can be used in this way. However, now when www.foo.com gets resolved, BIND gives out www0-www6 - but in a slightly permutated/rotated order every time. This way the clients are spread over the various servers. But notice that this not a perfect load balancing scheme, because DNS resolve information gets cached by the other nameservers on the net, so once a client has resolved www.foo.com to a particular wwwN.foo.com, all subsequent requests also go to this particular name wwwN.foo.com. But the final result is ok, because the total sum of the requests are really spread over the various webservers.

  2. DNS Load-Balancing

    A sophisticated DNS-based method for load-balancing is to use the program lbnamed which can be found at http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html. It is a Perl 5 program in conjunction with auxilliary tools which provides a real load-balancing for DNS.

  3. Proxy Throughput Round-Robin

    In this variant we use mod_rewrite and its proxy throughput feature. First we dedicate www0.foo.com to be actually www.foo.com by using a single

    www    IN  CNAME   www0.foo.com.

    entry in the DNS. Then we convert www0.foo.com to a proxy-only server, i.e. we configure this machine so all arriving URLs are just pushed through the internal proxy to one of the 5 other servers (www1-www5). To accomplish this we first establish a ruleset which contacts a load balancing script lb.pl for all URLs.

    RewriteEngine on
RewriteMap    lb      prg:/path/to/lb.pl
RewriteRule   ^/(.+)$ ${lb:$1}           [P,L]

    Then we write lb.pl:

    #!/path/to/perl
##
##  lb.pl -- load balancing script
##

$| = 1;

$name   = "www";     # the hostname base
$first  = 1;         # the first server (not 0 here, because 0 is myself)
$last   = 5;         # the last server in the round-robin
$domain = "foo.dom"; # the domainname

$cnt = 0;
while (<STDIN>) {
    $cnt = (($cnt+1) % ($last+1-$first));
    $server = sprintf("%s%d.%s", $name, $cnt+$first, $domain);
    print "http://$server/$_";
}

##EOF##
    A last notice: Why is this useful? Seems like www0.foo.com still is overloaded? The answer is yes, it is overloaded, but with plain proxy throughput requests, only! All SSI, CGI, ePerl, etc. processing is completely done on the other machines. This is the essential point.
  4. Hardware/TCP Round-Robin

    There is a hardware solution available, too. Cisco has a beast called LocalDirector which does a load balancing at the TCP/IP level. Actually this is some sort of a circuit level gateway in front of a webcluster. If you have enough money and really need a solution with high performance, use this one.

New MIME-type, New Service

Description:

On the net there are a lot of nifty CGI programs. But their usage is usually boring, so a lot of webmaster don't use them. Even Apache's Action handler feature for MIME-types is only appropriate when the CGI programs don't need special URLs (actually PATH_INFO and QUERY_STRINGS) as their input. First, let us configure a new file type with extension .scgi (for secure CGI) which will be processed by the popular cgiwrap program. The problem here is that for instance we use a Homogeneous URL Layout (see above) a file inside the user homedirs has the URL /u/user/foo/bar.scgi. But cgiwrap needs the URL in the form /~user/foo/bar.scgi/. The following rule solves the problem:

RewriteRule ^/[uge]/([^/]+)/\.www/(.+)\.scgi(.*) ...
... /internal/cgi/user/cgiwrap/~$1/$2.scgi$3  [NS,T=application/x-http-cgi]

Or assume we have some more nifty programs: wwwlog (which displays the access.log for a URL subtree and wwwidx (which runs Glimpse on a URL subtree). We have to provide the URL area to these programs so they know on which area they have to act on. But usually this ugly, because they are all the times still requested from that areas, i.e. typically we would run the swwidx program from within /u/user/foo/ via hyperlink to

/internal/cgi/user/swwidx?i=/u/user/foo/

which is ugly. Because we have to hard-code both the location of the area and the location of the CGI inside the hyperlink. When we have to reorganize the area, we spend a lot of time changing the various hyperlinks.

Solution:

The solution here is to provide a special new URL format which automatically leads to the proper CGI invocation. We configure the following:

RewriteRule   ^/([uge])/([^/]+)(/?.*)/\*  /internal/cgi/user/wwwidx?i=/$1/$2$3/
RewriteRule   ^/([uge])/([^/]+)(/?.*):log /internal/cgi/user/wwwlog?f=/$1/$2$3

Now the hyperlink to search at /u/user/foo/ reads only

HREF="*"

which internally gets automatically transformed to

/internal/cgi/user/wwwidx?i=/u/user/foo/

The same approach leads to an invocation for the access log CGI program when the hyperlink :log gets used.

From Static to Dynamic

Description:

How can we transform a static page foo.html into a dynamic variant foo.cgi in a seamless way, i.e. without notice by the browser/user.

Solution:

We just rewrite the URL to the CGI-script and force the correct MIME-type so it gets really run as a CGI-script. This way a request to /~quux/foo.html internally leads to the invocation of /~quux/foo.cgi.

RewriteEngine  on
RewriteBase    /~quux/
RewriteRule    ^foo\.html$  foo.cgi  [T=application/x-httpd-cgi]

On-the-fly Content-Regeneration

Description:

Here comes a really esoteric feature: Dynamically generated but statically served pages, i.e. pages should be delivered as pure static pages (read from the filesystem and just passed through), but they have to be generated dynamically by the webserver if missing. This way you can have CGI-generated pages which are statically served unless one (or a cronjob) removes the static contents. Then the contents gets refreshed.

Solution:
This is done via the following ruleset:
RewriteCond %{REQUEST_FILENAME}   !-s
RewriteRule ^page\.html$          page.cgi   [T=application/x-httpd-cgi,L]

Here a request to page.html leads to a internal run of a corresponding page.cgi if page.html is still missing or has filesize null. The trick here is that page.cgi is a usual CGI script which (additionally to its STDOUT) writes its output to the file page.html. Once it was run, the server sends out the data of page.html. When the webmaster wants to force a refresh the contents, he just removes page.html (usually done by a cronjob).

Document With Autorefresh

Description:

Wouldn't it be nice while creating a complex webpage if the webbrowser would automatically refresh the page every time we write a new version from within our editor? Impossible?

Solution:

No! We just combine the MIME multipart feature, the webserver NPH feature and the URL manipulation power of mod_rewrite. First, we establish a new URL feature: Adding just :refresh to any URL causes this to be refreshed every time it gets updated on the filesystem.

RewriteRule   ^(/[uge]/[^/]+/?.*):refresh  /internal/cgi/apache/nph-refresh?f=$1

Now when we reference the URL

/u/foo/bar/page.html:refresh

this leads to the internal invocation of the URL

/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html

The only missing part is the NPH-CGI script. Although one would usually say "left as an exercise to the reader" ;-) I will provide this, too.

#!/sw/bin/perl
##
##  nph-refresh -- NPH/CGI script for auto refreshing pages
##  Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.
##
$| = 1;

#   split the QUERY_STRING variable
@pairs = split(/&/, $ENV{'QUERY_STRING'});
foreach $pair (@pairs) {
    ($name, $value) = split(/=/, $pair);
    $name =~ tr/A-Z/a-z/;
    $name = 'QS_' . $name;
    $value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
    eval "\$$name = \"$value\"";
}
$QS_s = 1 if ($QS_s eq '');
$QS_n = 3600 if ($QS_n eq '');
if ($QS_f eq '') {
    print "HTTP/1.0 200 OK\n";
    print "Content-type: text/html\n\n";
    print "&lt;b&gt;ERROR&lt;/b&gt;: No file given\n";
    exit(0);
}
if (! -f $QS_f) {
    print "HTTP/1.0 200 OK\n";
    print "Content-type: text/html\n\n";
    print "&lt;b&gt;ERROR&lt;/b&gt;: File $QS_f not found\n";
    exit(0);
}

sub print_http_headers_multipart_begin {
    print "HTTP/1.0 200 OK\n";
    $bound = "ThisRandomString12345";
    print "Content-type: multipart/x-mixed-replace;boundary=$bound\n";
    &print_http_headers_multipart_next;
}

sub print_http_headers_multipart_next {
    print "\n--$bound\n";
}

sub print_http_headers_multipart_end {
    print "\n--$bound--\n";
}

sub displayhtml {
    local($buffer) = @_;
    $len = length($buffer);
    print "Content-type: text/html\n";
    print "Content-length: $len\n\n";
    print $buffer;
}

sub readfile {
    local($file) = @_;
    local(*FP, $size, $buffer, $bytes);
    ($x, $x, $x, $x, $x, $x, $x, $size) = stat($file);
    $size = sprintf("%d", $size);
    open(FP, "&lt;$file");
    $bytes = sysread(FP, $buffer, $size);
    close(FP);
    return $buffer;
}

$buffer = &readfile($QS_f);
&print_http_headers_multipart_begin;
&displayhtml($buffer);

sub mystat {
    local($file) = $_[0];
    local($time);

    ($x, $x, $x, $x, $x, $x, $x, $x, $x, $mtime) = stat($file);
    return $mtime;
}

$mtimeL = &mystat($QS_f);
$mtime = $mtime;
for ($n = 0; $n &lt; $QS_n; $n++) {
    while (1) {
        $mtime = &mystat($QS_f);
        if ($mtime ne $mtimeL) {
            $mtimeL = $mtime;
            sleep(2);
            $buffer = &readfile($QS_f);
            &print_http_headers_multipart_next;
            &displayhtml($buffer);
            sleep(5);
            $mtimeL = &mystat($QS_f);
            last;
        }
        sleep($QS_s);
    }
}

&print_http_headers_multipart_end;

exit(0);

##EOF##

Mass Virtual Hosting

Description:

The <VirtualHost> feature of Apache is nice and works great when you just have a few dozens virtual hosts. But when you are an ISP and have hundreds of virtual hosts to provide this feature is not the best choice.

Solution:

To provide this feature we map the remote webpage or even the complete remote webarea to our namespace by the use of the Proxy Throughput feature (flag [P]):

##
##  vhost.map
##
www.vhost1.dom:80  /path/to/docroot/vhost1
www.vhost2.dom:80  /path/to/docroot/vhost2
     :
www.vhostN.dom:80  /path/to/docroot/vhostN

##
##  httpd.conf
##
    :
#   use the canonical hostname on redirects, etc.
UseCanonicalName on

    :
#   add the virtual host in front of the CLF-format
CustomLog  /path/to/access_log  "%{VHOST}e %h %l %u %t \"%r\" %>s %b"
    :

#   enable the rewriting engine in the main server
RewriteEngine on

#   define two maps: one for fixing the URL and one which defines
#   the available virtual hosts with their corresponding
#   DocumentRoot.
RewriteMap    lowercase    int:tolower
RewriteMap    vhost        txt:/path/to/vhost.map

#   Now do the actual virtual host mapping
#   via a huge and complicated single rule:
#
#   1. make sure we don't map for common locations
RewriteCond   %{REQUEST_URI}  !^/commonurl1/.*
RewriteCond   %{REQUEST_URI}  !^/commonurl2/.*
    :
RewriteCond   %{REQUEST_URI}  !^/commonurlN/.*
#
#   2. make sure we have a Host header, because
#      currently our approach only supports
#      virtual hosting through this header
RewriteCond   %{HTTP_HOST}  !^$
#
#   3. lowercase the hostname
RewriteCond   ${lowercase:%{HTTP_HOST}|NONE}  ^(.+)$
#
#   4. lookup this hostname in vhost.map and
#      remember it only when it is a path
#      (and not "NONE" from above)
RewriteCond   ${vhost:%1}  ^(/.*)$
#
#   5. finally we can map the URL to its docroot location
#      and remember the virtual host for logging puposes
RewriteRule   ^/(.*)$   %1/$1  [E=VHOST:${lowercase:%{HTTP_HOST}}]
    :

Access Restriction

Blocking of Robots

Description:

How can we block a really annoying robot from retrieving pages of a specific webarea? A /robots.txt file containing entries of the "Robot Exclusion Protocol" is typically not enough to get rid of such a robot.

Solution:

We use a ruleset which forbids the URLs of the webarea /~quux/foo/arc/ (perhaps a very deep directory indexed area where the robot traversal would create big server load). We have to make sure that we forbid access only to the particular robot, i.e. just forbidding the host where the robot runs is not enough. This would block users from this host, too. We accomplish this by also matching the User-Agent HTTP header information.

RewriteCond %{HTTP_USER_AGENT}   ^NameOfBadRobot.*
RewriteCond %{REMOTE_ADDR}       ^123\.45\.67\.[8-9]$
RewriteRule ^/~quux/foo/arc/.+   -   [F]

Blocked Inline-Images

Description:

Assume we have under http://www.quux-corp.de/~quux/ some pages with inlined GIF graphics. These graphics are nice, so others directly incorporate them via hyperlinks to their pages. We don't like this practice because it adds useless traffic to our server.

Solution:

While we cannot 100% protect the images from inclusion, we can at least restrict the cases where the browser sends a HTTP Referer header.

RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !^http://www.quux-corp.de/~quux/.*$ [NC]
RewriteRule .*\.gif$        -                                    [F]

RewriteCond %{HTTP_REFERER}         !^$
RewriteCond %{HTTP_REFERER}         !.*/foo-with-gif\.html$
RewriteRule ^inlined-in-foo\.gif$   -                        [F]

Host Deny

Description:

How can we forbid a list of externally configured hosts from using our server?

Solution:

For Apache >= 1.3b6:

RewriteEngine on
RewriteMap    hosts-deny  txt:/path/to/hosts.deny
RewriteCond   ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND [OR]
RewriteCond   ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND
RewriteRule   ^/.*  -  [F]

For Apache <= 1.3b6:

RewriteEngine on
RewriteMap    hosts-deny  txt:/path/to/hosts.deny
RewriteRule   ^/(.*)$ ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND}/$1
RewriteRule   !^NOT-FOUND/.* - [F]
RewriteRule   ^NOT-FOUND/(.*)$ ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND}/$1
RewriteRule   !^NOT-FOUND/.* - [F]
RewriteRule   ^NOT-FOUND/(.*)$ /$1

##
##  hosts.deny
##
##  ATTENTION! This is a map, not a list, even when we treat it as such.
##             mod_rewrite parses it for key/value pairs, so at least a
##             dummy value "-" must be present for each entry.
##

193.102.180.41 -
bsdti1.sdm.de  -
192.76.162.40  -

Proxy Deny

Description:

How can we forbid a certain host or even a user of a special host from using the Apache proxy?

Solution:

We first have to make sure mod_rewrite is below(!) mod_proxy in the Configuration file when compiling the Apache webserver. This way it gets called before mod_proxy. Then we configure the following for a host-dependent deny...

RewriteCond %{REMOTE_HOST} ^badhost\.mydomain\.com$
RewriteRule !^http://[^/.]\.mydomain.com.*  - [F]

...and this one for a user@host-dependent deny:

RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST}  ^badguy@badhost\.mydomain\.com$
RewriteRule !^http://[^/.]\.mydomain.com.*  - [F]

Special Authentication Variant

Description:

Sometimes a very special authentication is needed, for instance a authentication which checks for a set of explicitly configured users. Only these should receive access and without explicit prompting (which would occur when using the Basic Auth via mod_auth).

Solution:

We use a list of rewrite conditions to exclude all except our friends:

RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} !^friend1@client1.quux-corp\.com$
RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} !^friend2@client2.quux-corp\.com$
RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} !^friend3@client3.quux-corp\.com$
RewriteRule ^/~quux/only-for-friends/      -                                 [F]

Referer-based Deflector

Description:

How can we program a flexible URL Deflector which acts on the "Referer" HTTP header and can be configured with as many referring pages as we like?

Solution:

Use the following really tricky ruleset...

RewriteMap  deflector txt:/path/to/deflector.map

RewriteCond %{HTTP_REFERER} !=""
RewriteCond ${deflector:%{HTTP_REFERER}} ^-$
RewriteRule ^.* %{HTTP_REFERER} [R,L]

RewriteCond %{HTTP_REFERER} !=""
RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND
RewriteRule ^.* ${deflector:%{HTTP_REFERER}} [R,L]

... in conjunction with a corresponding rewrite map:

##
##  deflector.map
##

http://www.badguys.com/bad/index.html    -
http://www.badguys.com/bad/index2.html   -
http://www.badguys.com/bad/index3.html   http://somewhere.com/

This automatically redirects the request back to the referring page (when "-" is used as the value in the map) or to a specific URL (when an URL is specified in the map as the second argument).

Other

External Rewriting Engine

Description:

A FAQ: How can we solve the FOO/BAR/QUUX/etc. problem? There seems no solution by the use of mod_rewrite...

Solution:

Use an external RewriteMap, i.e. a program which acts like a RewriteMap. It is run once on startup of Apache receives the requested URLs on STDIN and has to put the resulting (usually rewritten) URL on STDOUT (same order!).

RewriteEngine on
RewriteMap    quux-map       prg:/path/to/map.quux.pl
RewriteRule   ^/~quux/(.*)$  /~quux/${quux-map:$1}

#!/path/to/perl

#   disable buffered I/O which would lead
#   to deadloops for the Apache server
$| = 1;

#   read URLs one per line from stdin and
#   generate substitution URL on stdout
while (<>) {
    s|^foo/|bar/|;
    print $_;
}

This is a demonstration-only example and just rewrites all URLs /~quux/foo/... to /~quux/bar/.... Actually you can program whatever you like. But notice that while such maps can be used also by an average user, only the system administrator can define it.


Apache バーチャルホスト説明書 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

Apache バーチャルホスト説明書

バーチャルホストという用語は、1 台のマシン上で (www.company1.com and www.company2.com のような) 二つ以上のウェブサイトを扱う運用方法のことを指します。 バーチャルホストには、各ウェブサイトに違う IP アドレスがある 「IP ベース」と、それぞれの IP アドレスに 複数の名前がある「名前ベース」とがあります。 複数のサイトが物理的に同じサーバで扱われている、ということはエンドユーザには 明らかではありません。

Apache は、特に手を入れない状態で IP ベースのバーチャルホスト をサポートした最初のサーバの一つです。バージョン 1.1 以降の Apache では、IP ベースとネームベースのバーチャルホストの両方をサポート しています。ネームベースのバーチャルホストは、ホストベースあるいは 非 IP ベースのバーチャルホストと呼ばれることもあります。

以下のページでは、Apache バージョン 1.3 以降でのバーチャルホストのサポートについての詳細を説明します。

参照

  • mod_vhost_alias
  • ネームベースのバーチャルホスト
  • IP ベースのバーチャルホスト
  • バーチャルホストの一般的な設定例
  • ファイル記述子の限界
  • 大量のバーチャルホストの設定
  • バーチャルホストのマッチングについての詳細

バーチャルホストのサポート

  • ネームベースのバーチャルホスト (一つの IP アドレスに複数のウェブサイト)
  • IP ベースのバーチャルホスト (各ウェブサイトに IP アドレス)
  • バーチャルホストの一般的な設定例
  • ファイル記述子の限界 (または、多過ぎるログファイル)
  • 大量のバーチャルホストの設定
  • バーチャルホストのマッチングについての詳細

設定ディレクティブ

  • <VirtualHost>
  • NameVirtualHost
  • ServerName
  • ServerAlias
  • ServerPath

バーチャルホストの設定のデバッグをするには Apache のコマンドラインスイッチ -S が便利です。 つまり、以下のコマンドを入力します:

/usr/local/apache2/bin/httpd -S

このコマンドは Apache が設定ファイルをどう解析したかについて出力します。 IP アドレスとサーバ名を注意深く調べれば、 設定の間違いを見つける助けになるでしょう。 (他のコマンドラインのオプションは httpd プログラムの説明文書を見てください)


名前ベースのバーチャルホスト - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > バーチャルホスト

名前ベースのバーチャルホスト

この文書では名前ベースのバーチャルホストをどんなとき、 どうやって使うかを説明します。

参照

  • ネームベースのバーチャルホスト
  • バーチャルホストのマッチングについての詳細
  • 大量のバーチャルホストの動的な設定
  • バーチャルホストの一般的な設定例
  • ServerPath 設定例

名前ベースと IP ベースのバーチャルホストの比較

IP ベースのバーチャルホストでは、応答する バーチャルホストへのコネクションを決定するために IP アドレスを使用します。ですから、それぞれのホストに個々に IP アドレスが必要になります。これに対して名前ベースのバーチャルホストでは、 クライアントが HTTP ヘッダの一部としてホスト名を告げる、 ということに依存します。この技術で同一 IP アドレスを異なる多数のホストで共有しています。

名前ベースのバーチャルホストは通常単純で、それぞれのホスト名と それに対応する正確な IP アドレスを DNS で設定し、異なる ホスト名を区別するように Apache HTTP サーバを設定するだけです。 さらに、名前ベースのバーチャルホストは不足する IP アドレスの需要を緩和します。したがって、IP ベースのバーチャルホストを 選択すべき特定の理由がなければ名前ベースのバーチャルホストを使うべきです。 IP ベースのバーチャルホストを使用することを考慮する理由として、

  • 名前ベースのバーチャルホストに対応していない古いクライアントがある 名前ベースのバーチャルホストが働くためには、クライアントは HTTP ホストヘッダを送ってこなければなりません。 これは HTTP/1.1 の仕様で要求されていて、すべての現代的な HTTP/1.0 ブラウザでも拡張として実装されています。 とても古いクライアントをサポートしつつ、名前ベースの バーチャルホストを行いたい場合は、この文書の最後の方に 書かれている解決策になるかもしれない方法を見てください。
  • 名前ベースのバーチャルホストは SSL プロトコルの特徴により、 SSL セキュアサーバには使えません。
  • オペレーティングシステムやネットワーク装置のなかには、 別の IP アドレス上でない場合、複数のホストを別扱いできないような 帯域管理の方法を実装しているものがあります。

名前ベースのバーチャルホストを利用する

関連モジュール 関連ディレクティブ
  • core
  • DocumentRoot
  • NameVirtualHost
  • ServerAlias
  • ServerName
  • ServerPath
  • VirtualHost
  • <VirtualHost>

名前ベースのバーチャルホストを使うには、そのホストへの リクエストを受け付けるサーバの IP アドレス (もしかしたらポートも) を指定する必要があります。 これは NameVirtualHost ディレクティブで設定します。通常、NameVirtualHost で * の属性を使ってサーバの全ての IP アドレスを使います。 (例えば SSL の使用などで) 複数のポートを使うことを計画しているのであれば、 引数に *:80 のようにポートも含めるようにしてください。 NameVirtualHost ディレクティブで IP アドレスを書いても、 自動的にサーバがその IP アドレスをリッスンするということはないことに 注意してください。詳細は「Apache の使うアドレスと ポートを設定する」を読んでください。さらに、ここで指定された IP アドレスは全てサーバのネットワークインターフェースと関連付けられて いなければなりません。

次は、扱うホストそれぞれに対して <VirtualHost> ブロックを 作成してください。<VirtualHost> ディレクティブの引数は NameVirtualHost ディレクティブの引数と同じにしてください (すなわち、IP アドレスか、全てのアドレスを意味する *)。それぞれの <VirtualHost> ディレクティブの中には、最低限、どのホストが扱われるかを示す ServerName ディレクティブと、 そのホスト用のコンテンツがファイルシステム上のどこにあるかを示す DocumentRoot ディレクティブを 書く必要があります。

メインホストはなくなります

既にあるウェブサーバにバーチャルホストを追加する場合、 既存のウェブサーバに対しても <VirtualHost> ブロックを作らなければなりません。このバーチャルホストの ServerName と DocumentRoot は、グローバルな ServerName と DocumentRoot と同じものにします。また、このバーチャルホストを設定ファイルの中で 先頭に置いて、デフォルトホストとして動作するようにします。

たとえば、www.domain.tld を動かしていて、 さらにバーチャルホスト www.otherdomain.tld を追加するとしましょう。このバーチャルホストは同一 IP を指しているとします。 そのような場合は、httpd.conf に以下のようなコードを追加するだけです

NameVirtualHost *:80

<VirtualHost *:80>
ServerName www.domain.tld
ServerAlias domain.tld *.domain.tld
DocumentRoot /www/domain
 </VirtualHost>

<VirtualHost *:80>
ServerName www.otherdomain.tld
DocumentRoot /www/otherdomain
 </VirtualHost>

NameVirtualHost 及び VirtualHost のどちらの場合も、 * の部分には明示的に IP アドレスを指定することができます。 例えば、ある IP アドレスでは名前ベースのバーチャルホストを使いたい一方で、 別の IP アドレスでは、他の IP ベースのバーチャルホストや 別組の名前ベースのバーチャルホストを使いたい場合、 そう設定することになるでしょう。

複数の名前でサーバアクセスができるようにしたいことも多いでしょう。 このようなことは、ServerAlias ディレクティブを <VirtualHost> セクションに記述することで実現できます。 例えば上記の <VirtualHost> の例であれば、 次のように一覧に挙げられた名前が、 ユーザが同一のウェブサイトとして目にして使用できるサーバ名である、 と ServerAlias ディレクティブで指定できます。

ServerAlias domain.tld *.domain.tld

domain.tld ドメインへの全てのホストへのリクエストは www.domain.tld のバーチャルホストが処理します。 名前をマッチさせるために、ワイルドカード文字 * や ? を使用することもできます。もちろん思いつきの名前を作って、 ServerName や ServerAlias にその名前を書くといったことはできません。まずは、 これらの名前が サーバに付けられた IP アドレスにマップされるように DNS サーバを適切に設定しなければなりません。

最後に、<VirtualHost> コンテナの中に 他のディレクティブを書くことで、バーチャルホストの設定を細かく調整 することができます。 ほとんどのディレクティブはこれらのコンテナに設置することができて、 変更点はそのバーチャルホストに対してのみ有効になります。 どのディレクティブを書くことができるかは、ディレクティブの コンテキスト を 調べてください。主サーバコンテキスト (<VirtualHost> コンテナの外) の設定用ディレクティブはバーチャルホストでの設定で 上書きされない場合のみ使用されます。

リクエストが来ると、サーバはまず最初に <NameVirtualHost> にマッチする IP アドレスかどうかをチェックします。マッチすれば マッチした IP アドレスの <VirtualHost> のそれぞれのセクションの中から ServerName か ServerAlias に要求されたホスト名があるか探します。 見つかればそのサーバ用の設定を使います。マッチするバーチャルホスト が見つからなければ、マッチした IP アドレスの リストの最初にあるバーチャルホスト が使われます。

結果として、リストの最初のバーチャルホストが デフォルト の バーチャルホストになります。IP アドレスが NameVirtualHost ディレクティブにマッチした場合は、メインのサーバ の DocumentRoot は決して使われません どのバーチャルホストにもマッチしないリクエストに対して、 特別な設定をしたいのであれば、設定ファイル中の最初の <VirtualHost> コンテナにそれを記述してください。

古いブラウザとの互換性

以前述べたように、名前ベースのバーチャルホストが正しく動作する ために必要な情報を送ってこないクライアントが依然として存在しています。 そのようなクライアントに対しては、該当する IP アドレスについて、 一番最初に設定されているバーチャルホスト (プライマリの名前ベースのバーチャルホスト) からページが送り返されます。

どのぐらい古いの ?

「古い」と表現している場合、本当に古いことを意味して使っています。 不幸にして今現在でもこのような古いブラウザに遭遇することがあります。 現在のブラウザは全て、名前ベースのバーチャルホストに必要な Host ヘッダを送ります。

ServerPath ディレクティブで対処が可能です。ちょっと不格好ですけれども。

設定例

NameVirtualHost 111.22.33.44

<VirtualHost 111.22.33.44>
ServerName www.domain.tld
ServerPath /domain
DocumentRoot /web/domain
 </VirtualHost>

この例にはどういう意味があるでしょうか? これは "/domain" で始まる URI へのリクエストはすべて、 バーチャルホスト www.domain.tld で処理される、 という意味です。つまり、すべてのクライアントで http://www.domain.tld/domain/ でアクセスできるページが、 Host: ヘッダを送ってくるクライアントであれば http://www.domain.tld/ としてもアクセスできる、 という意味です。

これが動作するようにするには、 プライマリのバーチャルホストのページに http://www.domain.tld/domain/ へのリンクを設置します。 そして、バーチャルホストのページでは、純粋な相対リンク (例: "file.html" や "../icons/image.gif")、 あるいは /domain/ で始まるリンク (例: "http://www.domain.tld/domain/misc/file.html" や "/domain/misc/file.html") だけを設置します。

これには、幾分かの規律が必要となりますが、 このようなガイドラインを忠実に守ることにより、たいていの場合、 すべてのブラウザで ― 新しいブラウザでも古いものでも ― 作成したページが見えるということを保証します。


Apache IP-based Virtual Host Support - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Virtual Hosts

Apache IP-based Virtual Host Support

See also

  • Name-based Virtual Hosts Support

System requirements

As the term IP-based indicates, the server must have a different IP address for each IP-based virtual host. This can be achieved by the machine having several physical network connections, or by use of virtual interfaces which are supported by most modern operating systems (see system documentation for details, these are frequently called "ip aliases", and the "ifconfig" command is most commonly used to set them up).

How to set up Apache

There are two ways of configuring apache to support multiple hosts. Either by running a separate httpd daemon for each hostname, or by running a single daemon which supports all the virtual hosts.

Use multiple daemons when:

  • There are security partitioning issues, such as company1 does not want anyone at company2 to be able to read their data except via the web. In this case you would need two daemons, each running with different User, Group, Listen, and ServerRoot settings.
  • You can afford the memory and file descriptor requirements of listening to every IP alias on the machine. It's only possible to Listen to the "wildcard" address, or to specific addresses. So if you have a need to listen to a specific address for whatever reason, then you will need to listen to all specific addresses. (Although one httpd could listen to N-1 of the addresses, and another could listen to the remaining address.)

Use a single daemon when:

  • Sharing of the httpd configuration between virtual hosts is acceptable.
  • The machine services a large number of requests, and so the performance loss in running separate daemons may be significant.

Setting up multiple daemons

Create a separate httpd installation for each virtual host. For each installation, use the Listen directive in the configuration file to select which IP address (or virtual host) that daemon services. e.g.

Listen www.smallco.com:80

It is recommended that you use an IP address instead of a hostname (see DNS caveats).

Setting up a single daemon with virtual hosts

For this case, a single httpd will service requests for the main server and all the virtual hosts. The VirtualHost directive in the configuration file is used to set the values of ServerAdmin, ServerName, DocumentRoot, ErrorLog and TransferLog or CustomLog configuration directives to different values for each virtual host. e.g.

<VirtualHost www.smallco.com>
ServerAdmin webmaster@mail.smallco.com
DocumentRoot /groups/smallco/www
ServerName www.smallco.com
ErrorLog /groups/smallco/logs/error_log
TransferLog /groups/smallco/logs/access_log
</VirtualHost>

<VirtualHost www.baygroup.org>
ServerAdmin webmaster@mail.baygroup.org
DocumentRoot /groups/baygroup/www
ServerName www.baygroup.org
ErrorLog /groups/baygroup/logs/error_log
TransferLog /groups/baygroup/logs/access_log
</VirtualHost>

It is recommended that you use an IP address instead of a hostname (see DNS caveats).

Almost any configuration directive can be put in the VirtualHost directive, with the exception of directives that control process creation and a few other directives. To find out if a directive can be used in the VirtualHost directive, check the Context using the directive index.

User and Group may be used inside a VirtualHost directive if the suEXEC wrapper is used.

SECURITY: When specifying where to write log files, be aware of some security risks which are present if anyone other than the user that starts Apache has write access to the directory where they are written. See the security tips document for details.


Dynamically configured mass virtual hosting - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Virtual Hosts

Dynamically configured mass virtual hosting

This document describes how to efficiently serve an arbitrary number of virtual hosts with Apache 1.3.

Motivation

The techniques described here are of interest if your httpd.conf contains many <VirtualHost> sections that are substantially the same, for example:

NameVirtualHost 111.22.33.44
<VirtualHost 111.22.33.44>
ServerName www.customer-1.com
DocumentRoot /www/hosts/www.customer-1.com/docs
ScriptAlias /cgi-bin/ /www/hosts/www.customer-1.com/cgi-bin
 </VirtualHost>
<VirtualHost 111.22.33.44>
ServerName www.customer-2.com
DocumentRoot /www/hosts/www.customer-2.com/docs
ScriptAlias /cgi-bin/ /www/hosts/www.customer-2.com/cgi-bin
 </VirtualHost>
# blah blah blah
<VirtualHost 111.22.33.44>
ServerName www.customer-N.com
DocumentRoot /www/hosts/www.customer-N.com/docs
ScriptAlias /cgi-bin/ /www/hosts/www.customer-N.com/cgi-bin
 </VirtualHost>

The basic idea is to replace all of the static <VirtualHost> configuration with a mechanism that works it out dynamically. This has a number of advantages:

  1. Your configuration file is smaller so Apache starts faster and uses less memory.
  2. Adding virtual hosts is simply a matter of creating the appropriate directories in the filesystem and entries in the DNS - you don't need to reconfigure or restart Apache.

The main disadvantage is that you cannot have a different log file for each virtual host; however if you have very many virtual hosts then doing this is dubious anyway because it eats file descriptors. It is better to log to a pipe or a fifo and arrange for the process at the other end to distribute the logs to the customers (it can also accumulate statistics, etc.).

Overview

A virtual host is defined by two pieces of information: its IP address, and the contents of the Host: header in the HTTP request. The dynamic mass virtual hosting technique is based on automatically inserting this information into the pathname of the file that is used to satisfy the request. This is done most easily using mod_vhost_alias, but if you are using a version of Apache up to 1.3.6 then you must use mod_rewrite. Both of these modules are disabled by default; you must enable one of them when configuring and building Apache if you want to use this technique.

A couple of things need to be `faked' to make the dynamic virtual host look like a normal one. The most important is the server name which is used by Apache to generate self-referential URLs, etc. It is configured with the ServerName directive, and it is available to CGIs via the SERVER_NAME environment variable. The actual value used at run time is controlled by the UseCanonicalName setting. With UseCanonicalName Off the server name comes from the contents of the Host: header in the request. With UseCanonicalName DNS it comes from a reverse DNS lookup of the virtual host's IP address. The former setting is used for name-based dynamic virtual hosting, and the latter is used for IP-based hosting. If Apache cannot work out the server name because there is no Host: header or the DNS lookup fails then the value configured with ServerName is used instead.

The other thing to `fake' is the document root (configured with DocumentRoot and available to CGIs via the DOCUMENT_ROOT environment variable). In a normal configuration this setting is used by the core module when mapping URIs to filenames, but when the server is configured to do dynamic virtual hosting that job is taken over by another module (either mod_vhost_alias or mod_rewrite) which has a different way of doing the mapping. Neither of these modules is responsible for setting the DOCUMENT_ROOT environment variable so if any CGIs or SSI documents make use of it they will get a misleading value.

Simple dynamic virtual hosts

This extract from httpd.conf implements the virtual host arrangement outlined in the Motivation section above, but in a generic fashion using mod_vhost_alias.

# get the server name from the Host: header
UseCanonicalName Off

# this log format can be split per-virtual-host based on the first field
LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
CustomLog logs/access_log vcommon

# include the server name in the filenames used to satisfy requests
VirtualDocumentRoot /www/hosts/%0/docs
VirtualScriptAlias /www/hosts/%0/cgi-bin

This configuration can be changed into an IP-based virtual hosting solution by just turning UseCanonicalName Off into UseCanonicalName DNS. The server name that is inserted into the filename is then derived from the IP address of the virtual host.

A virtually hosted homepages system

This is an adjustment of the above system tailored for an ISP's homepages server. Using a slightly more complicated configuration we can select substrings of the server name to use in the filename so that e.g. the documents for www.user.isp.com are found in /home/user/. It uses a single cgi-bin directory instead of one per virtual host.

# all the preliminary stuff is the same as above, then

# include part of the server name in the filenames
VirtualDocumentRoot /www/hosts/%2/docs

# single cgi-bin directory
ScriptAlias /cgi-bin/ /www/std-cgi/

There are examples of more complicated VirtualDocumentRoot settings in the mod_vhost_alias documentation.

Using more than one virtual hosting system on the same server

With more complicated setups you can use Apache's normal <VirtualHost> directives to control the scope of the various virtual hosting configurations. For example, you could have one IP address for homepages customers and another for commercial customers with the following setup. This can of course be combined with conventional <VirtualHost> configuration sections.

UseCanonicalName Off

LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon

<Directory /www/commercial>
Options FollowSymLinks
AllowOverride All
 </Directory>

<Directory /www/homepages>
Options FollowSymLinks
AllowOverride None
 </Directory>

<VirtualHost 111.22.33.44>
ServerName www.commercial.isp.com

CustomLog logs/access_log.commercial vcommon

VirtualDocumentRoot /www/commercial/%0/docs
VirtualScriptAlias /www/commercial/%0/cgi-bin
 </VirtualHost>

<VirtualHost 111.22.33.45>
ServerName www.homepages.isp.com

CustomLog logs/access_log.homepages vcommon

VirtualDocumentRoot /www/homepages/%0/docs
ScriptAlias /cgi-bin/ /www/std-cgi/
 </VirtualHost>

More efficient IP-based virtual hosting

After the first example I noted that it is easy to turn it into an IP-based virtual hosting setup. Unfortunately that configuration is not very efficient because it requires a DNS lookup for every request. This can be avoided by laying out the filesystem according to the IP addresses themselves rather than the corresponding names and changing the logging similarly. Apache will then usually not need to work out the server name and so incur a DNS lookup.

# get the server name from the reverse DNS of the IP address
UseCanonicalName DNS

# include the IP address in the logs so they may be split
LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon
CustomLog logs/access_log vcommon

# include the IP address in the filenames
VirtualDocumentRootIP /www/hosts/%0/docs
VirtualScriptAliasIP /www/hosts/%0/cgi-bin

Using older versions of Apache

The examples above rely on mod_vhost_alias which appeared after version 1.3.6. If you are using a version of Apache without mod_vhost_alias then you can implement this technique with mod_rewrite as illustrated below, but only for Host:-header-based virtual hosts.

In addition there are some things to beware of with logging. Apache 1.3.6 is the first version to include the %V log format directive; in versions 1.3.0 - 1.3.3 the %v option did what %V does; version 1.3.4 has no equivalent. In all these versions of Apache the UseCanonicalName directive can appear in .htaccess files which means that customers can cause the wrong thing to be logged. Therefore the best thing to do is use the %{Host}i directive which logs the Host: header directly; note that this may include :port on the end which is not the case for %V.

Simple dynamic virtual hosts using mod_rewrite

This extract from httpd.conf does the same thing as the first example. The first half is very similar to the corresponding part above but with some changes for backward compatibility and to make the mod_rewrite part work properly; the second half configures mod_rewrite to do the actual work.

There are a couple of especially tricky bits: By default, mod_rewrite runs before the other URI translation modules (mod_alias etc.) so if they are used then mod_rewrite must be configured to accommodate them. Also, some magic must be performed to do a per-dynamic-virtual-host equivalent of ScriptAlias.

# get the server name from the Host: header
UseCanonicalName Off

# splittable logs
LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon
CustomLog logs/access_log vcommon

<Directory /www/hosts>
# ExecCGI is needed here because we can't force
# CGI execution in the way that ScriptAlias does
Options FollowSymLinks ExecCGI
 </Directory>

# now for the hard bit

RewriteEngine On

# a ServerName derived from a Host: header may be any case at all
RewriteMap lowercase int:tolower

## deal with normal documents first:
# allow Alias /icons/ to work - repeat for other aliases
RewriteCond %{REQUEST_URI} !^/icons/
# allow CGIs to work
RewriteCond %{REQUEST_URI} !^/cgi-bin/
# do the magic
RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1

## and now deal with CGIs - we have to force a MIME type
RewriteCond %{REQUEST_URI} ^/cgi-bin/
RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi]

# that's it!

A homepages system using mod_rewrite

This does the same thing as the second example.

RewriteEngine on

RewriteMap lowercase int:tolower

# allow CGIs to work
RewriteCond %{REQUEST_URI} !^/cgi-bin/

# check the hostname is right so that the RewriteRule works
RewriteCond ${lowercase:%{SERVER_NAME}} ^www\.[a-z-]+\.isp\.com$

# concatenate the virtual host name onto the start of the URI
# the [C] means do the next rewrite on the result of this one
RewriteRule ^(.+) ${lowercase:%{SERVER_NAME}}$1 [C]

# now create the real file name
RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /home/$1/$2

# define the global CGI directory
ScriptAlias /cgi-bin/ /www/std-cgi/

Using a separate virtual host configuration file

This arrangement uses more advanced mod_rewrite features to get the translation from virtual host to document root from a separate configuration file. This provides more flexibility but requires more complicated configuration.

The vhost.map file contains something like this:

www.customer-1.com /www/customers/1
www.customer-2.com /www/customers/2
# ...
www.customer-N.com /www/customers/N

The http.conf contains this:

RewriteEngine on

RewriteMap lowercase int:tolower

# define the map file
RewriteMap vhost txt:/www/conf/vhost.map

# deal with aliases as above
RewriteCond %{REQUEST_URI} !^/icons/
RewriteCond %{REQUEST_URI} !^/cgi-bin/
RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$
# this does the file-based remap
RewriteCond ${vhost:%1} ^(/.*)$
RewriteRule ^/(.*)$ %1/docs/$1

RewriteCond %{REQUEST_URI} ^/cgi-bin/
RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$
RewriteCond ${vhost:%1} ^(/.*)$
RewriteRule ^/(.*)$ %1/cgi-bin/$1


VirtualHost Examples - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Virtual Hosts

VirtualHost Examples

This document attempts to answer the commonly-asked questions about setting up virtual hosts. These scenarios are those involving multiple web sites running on a single server, via name-based or IP-based virtual hosts. A document should be coming soon about running sites on several servers behind a single proxy server.

Running several name-based web sites on a single IP address.

Your server has a single IP address, and multiple aliases (CNAMES) point to this machine in DNS. You want to run a web server for www.example1.com and www.example2.org on this machine.

Note

Creating virtual host configurations on your Apache server does not magically cause DNS entries to be created for those host names. You must have the names in DNS, resolving to your IP address, or nobody else will be able to see your web site. You can put entries in your hosts file for local testing, but that will work only from the machine with those hosts entries.

Server configuration

# Ensure that Apache listens on port 80
Listen 80

# Listen for virtual host requests on all IP addresses
NameVirtualHost *:80

<VirtualHost *:80>
DocumentRoot /www/example1
ServerName www.example1.com

# Other directives here

 </VirtualHost>

<VirtualHost *:80>
DocumentRoot /www/example2
ServerName www.example2.org

# Other directives here

 </VirtualHost>

The asterisks match all addresses, so the main server serves no requests. Due to the fact that www.example1.com is first in the configuration file, it has the highest priority and can be seen as the default or primary server. That means that if a request is received that does not match one of the specified ServerName directives, it will be served by this first VirtualHost.

Note

You can, if you wish, replace * with the actual IP address of the system. In that case, the argument to VirtualHost must match the argument to NameVirtualHost:

NameVirtualHost 172.20.30.40

<VirtualHost 172.20.30.40>
# etc ...

However, it is additionally useful to use * on systems where the IP address is not predictable - for example if you have a dynamic IP address with your ISP, and you are using some variety of dynamic DNS solution. Since * matches any IP address, this configuration would work without changes whenever your IP address changes.

The above configuration is what you will want to use in almost all name-based virtual hosting situations. The only thing that this configuration will not work for, in fact, is when you are serving different content based on differing IP addresses or ports.

Name-based hosts on more than one IP address.

Note

Any of the techniques discussed here can be extended to any number of IP addresses.

The server has two IP addresses. On one (172.20.30.40), we will serve the "main" server, server.domain.com and on the other (172.20.30.50), we will serve two or more virtual hosts.

Server configuration

Listen 80

# This is the "main" server running on 172.20.30.40
ServerName server.domain.com
DocumentRoot /www/mainserver

# This is the other address
NameVirtualHost 172.20.30.50

<VirtualHost 172.20.30.50>
DocumentRoot /www/example1
ServerName www.example1.com

# Other directives here ...

 </VirtualHost>

<VirtualHost 172.20.30.50>
DocumentRoot /www/example2
ServerName www.example2.org

# Other directives here ...

 </VirtualHost>

Any request to an address other than 172.20.30.50 will be served from the main server. A request to 172.20.30.50 with an unknown hostname, or no Host: header, will be served from www.example1.com.

Serving the same content on different IP addresses (such as an internal and external address).

The server machine has two IP addresses (192.168.1.1 and 172.20.30.40). The machine is sitting between an internal (intranet) network and an external (internet) network. Outside of the network, the name server.example.com resolves to the external address (172.20.30.40), but inside the network, that same name resolves to the internal address (192.168.1.1).

The server can be made to respond to internal and external requests with the same content, with just one VirtualHost section.

Server configuration

NameVirtualHost 192.168.1.1
NameVirtualHost 172.20.30.40

<VirtualHost 192.168.1.1 172.20.30.40>
DocumentRoot /www/server1
ServerName server.example.com
ServerAlias server
 </VirtualHost>

Now requests from both networks will be served from the same VirtualHost.

Note:

On the internal network, one can just use the name server rather than the fully qualified host name server.example.com.

Note also that, in the above example, you can replace the list of IP addresses with *, which will cause the server to respond the same on all addresses.

Running different sites on different ports.

You have multiple domains going to the same IP and also want to serve multiple ports. By defining the ports in the "NameVirtualHost" tag, you can allow this to work. If you try using <VirtualHost name:port> without the NameVirtualHost name:port or you try to use the Listen directive, your configuration will not work.

Server configuration

Listen 80
Listen 8080

NameVirtualHost 172.20.30.40:80
NameVirtualHost 172.20.30.40:8080

<VirtualHost 172.20.30.40:80>
ServerName www.example1.com
DocumentRoot /www/domain-80
 </VirtualHost>

<VirtualHost 172.20.30.40:8080>
ServerName www.example1.com
DocumentRoot /www/domain-8080
 </VirtualHost>

<VirtualHost 172.20.30.40:80>
ServerName www.example2.org
DocumentRoot /www/otherdomain-80
 </VirtualHost>

<VirtualHost 172.20.30.40:8080>
ServerName www.example2.org
DocumentRoot /www/otherdomain-8080
 </VirtualHost>

IP-based virtual hosting

The server has two IP addresses (172.20.30.40 and 172.20.30.50) which resolve to the names www.example1.com and www.example2.org respectively.

Server configuration

Listen 80

<VirtualHost 172.20.30.40>
DocumentRoot /www/example1
ServerName www.example1.com
 </VirtualHost>

<VirtualHost 172.20.30.50>
DocumentRoot /www/example2
ServerName www.example2.org
 </VirtualHost>

Requests for any address not specified in one of the <VirtualHost> directives (such as localhost, for example) will go to the main server, if there is one.

Mixed port-based and ip-based virtual hosts

The server machine has two IP addresses (172.20.30.40 and 172.20.30.50) which resolve to the names www.example1.com and www.example2.org respectively. In each case, we want to run hosts on ports 80 and 8080.

Server configuration

Listen 172.20.30.40:80
Listen 172.20.30.40:8080
Listen 172.20.30.50:80
Listen 172.20.30.50:8080

<VirtualHost 172.20.30.40:80>
DocumentRoot /www/example1-80
ServerName www.example1.com
 </VirtualHost>

<VirtualHost 172.20.30.40:8080>
DocumentRoot /www/example1-8080
ServerName www.example1.com
 </VirtualHost>

<VirtualHost 172.20.30.50:80>
DocumentRoot /www/example2-80
ServerName www.example1.org
 </VirtualHost>

<VirtualHost 172.20.30.50:8080>
DocumentRoot /www/example2-8080
ServerName www.example2.org
 </VirtualHost>

Mixed name-based and IP-based vhosts

On some of my addresses, I want to do name-based virtual hosts, and on others, IP-based hosts.

Server configuration

Listen 80

NameVirtualHost 172.20.30.40

<VirtualHost 172.20.30.40>
DocumentRoot /www/example1
ServerName www.example1.com
 </VirtualHost>

<VirtualHost 172.20.30.40>
DocumentRoot /www/example2
ServerName www.example2.org
 </VirtualHost>

<VirtualHost 172.20.30.40>
DocumentRoot /www/example3
ServerName www.example3.net
 </VirtualHost>

# IP-based
<VirtualHost 172.20.30.50>
DocumentRoot /www/example4
ServerName www.example4.edu
 </VirtualHost>

<VirtualHost 172.20.30.60>
DocumentRoot /www/example5
ServerName www.example5.gov
 </VirtualHost>

Using _default_ vhosts

_default_ vhosts for all ports

Catching every request to any unspecified IP address and port, i.e., an address/port combination that is not used for any other virtual host.

Server configuration

<VirtualHost _default_:*>
DocumentRoot /www/default
 </VirtualHost>

Using such a default vhost with a wildcard port effectively prevents any request going to the main server.

A default vhost never serves a request that was sent to an address/port that is used for name-based vhosts. If the request contained an unknown or no Host: header it is always served from the primary name-based vhost (the vhost for that address/port appearing first in the configuration file).

You can use AliasMatch or RewriteRule to rewrite any request to a single information page (or script).

_default_ vhosts for different ports

Same as setup 1, but the server listens on several ports and we want to use a second _default_ vhost for port 80.

Server configuration

<VirtualHost _default_:80>
DocumentRoot /www/default80
# ...
 </VirtualHost>

<VirtualHost _default_:*>
DocumentRoot /www/default
# ...
 </VirtualHost>

The default vhost for port 80 (which must appear before any default vhost with a wildcard port) catches all requests that were sent to an unspecified IP address. The main server is never used to serve a request.

_default_ vhosts for one port

We want to have a default vhost for port 80, but no other default vhosts.

Server configuration

<VirtualHost _default_:80>
DocumentRoot /www/default
...
</VirtualHost>

A request to an unspecified address on port 80 is served from the default vhost any other request to an unspecified address and port is served from the main server.

Migrating a name-based vhost to an IP-based vhost

The name-based vhost with the hostname www.example2.org (from our name-based example, setup 2) should get its own IP address. To avoid problems with name servers or proxies who cached the old IP address for the name-based vhost we want to provide both variants during a migration phase.
The solution is easy, because we can simply add the new IP address (172.20.30.50) to the VirtualHost directive.

Server configuration

Listen 80
ServerName www.example1.com
DocumentRoot /www/example1

NameVirtualHost 172.20.30.40

<VirtualHost 172.20.30.40 172.20.30.50>
DocumentRoot /www/example2
ServerName www.example2.org
# ...
 </VirtualHost>

<VirtualHost 172.20.30.40>
DocumentRoot /www/example3
ServerName www.example3.net
ServerAlias *.example3.net
# ...
 </VirtualHost>

The vhost can now be accessed through the new address (as an IP-based vhost) and through the old address (as a name-based vhost).

Using the ServerPath directive

We have a server with two name-based vhosts. In order to match the correct virtual host a client must send the correct Host: header. Old HTTP/1.0 clients do not send such a header and Apache has no clue what vhost the client tried to reach (and serves the request from the primary vhost). To provide as much backward compatibility as possible we create a primary vhost which returns a single page containing links with an URL prefix to the name-based virtual hosts.

Server configuration

NameVirtualHost 172.20.30.40

<VirtualHost 172.20.30.40>
# primary vhost
DocumentRoot /www/subdomain
RewriteEngine On
RewriteRule ^/.* /www/subdomain/index.html
# ...
 </VirtualHost>

<VirtualHost 172.20.30.40>
DocumentRoot /www/subdomain/sub1
ServerName www.sub1.domain.tld
ServerPath /sub1/
RewriteEngine On
RewriteRule ^(/sub1/.*) /www/subdomain$1
# ...
 </VirtualHost>

<VirtualHost 172.20.30.40>
DocumentRoot /www/subdomain/sub2
ServerName www.sub2.domain.tld
ServerPath /sub2/
RewriteEngine On
RewriteRule ^(/sub2/.*) /www/subdomain$1
# ...
 </VirtualHost>

Due to the ServerPath directive a request to the URL http://www.sub1.domain.tld/sub1/ is always served from the sub1-vhost.
A request to the URL http://www.sub1.domain.tld/ is only served from the sub1-vhost if the client sent a correct Host: header. If no Host: header is sent the client gets the information page from the primary host.
Please note that there is one oddity: A request to http://www.sub2.domain.tld/sub1/ is also served from the sub1-vhost if the client sent no Host: header.
The RewriteRule directives are used to make sure that a client which sent a correct Host: header can use both URL variants, i.e., with or without URL prefix.


An In-Depth Discussion of Virtual Host Matching - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Virtual Hosts

An In-Depth Discussion of Virtual Host Matching

The virtual host code was completely rewritten in Apache 1.3. This document attempts to explain exactly what Apache does when deciding what virtual host to serve a hit from. With the help of the new NameVirtualHost directive virtual host configuration should be a lot easier and safer than with versions prior to 1.3.

If you just want to make it work without understanding how, here are some examples.

Config File Parsing

There is a main_server which consists of all the definitions appearing outside of <VirtualHost> sections. There are virtual servers, called vhosts, which are defined by <VirtualHost> sections.

The directives Listen, ServerName, ServerPath, and ServerAlias can appear anywhere within the definition of a server. However, each appearance overrides the previous appearance (within that server).

The default value of the Listen field for main_server is 80. The main_server has no default ServerPath, or ServerAlias. The default ServerName is deduced from the servers IP address.

The main_server Listen directive has two functions. One function is to determine the default network port Apache will bind to. The second function is to specify the port number which is used in absolute URIs during redirects.

Unlike the main_server, vhost ports do not affect what ports Apache listens for connections on.

Each address appearing in the VirtualHost directive can have an optional port. If the port is unspecified it defaults to the value of the main_server's most recent Listen statement. The special port * indicates a wildcard that matches any port. Collectively the entire set of addresses (including multiple A record results from DNS lookups) are called the vhost's address set.

Unless a NameVirtualHost directive is used for a specific IP address the first vhost with that address is treated as an IP-based vhost. The IP address can also be the wildcard *.

If name-based vhosts should be used a NameVirtualHost directive must appear with the IP address set to be used for the name-based vhosts. In other words, you must specify the IP address that holds the hostname aliases (CNAMEs) for your name-based vhosts via a NameVirtualHost directive in your configuration file.

Multiple NameVirtualHost directives can be used each with a set of VirtualHost directives but only one NameVirtualHost directive should be used for each specific IP:port pair.

The ordering of NameVirtualHost and VirtualHost directives is not important which makes the following two examples identical (only the order of the VirtualHost directives for one address set is important, see below):

NameVirtualHost 111.22.33.44
<VirtualHost 111.22.33.44>
# server A
...
</VirtualHost>
<VirtualHost 111.22.33.44>
# server B
...
</VirtualHost>

NameVirtualHost 111.22.33.55
<VirtualHost 111.22.33.55>
# server C
...
</VirtualHost>
<VirtualHost 111.22.33.55>
# server D
...
</VirtualHost>

<VirtualHost 111.22.33.44>
# server A
</VirtualHost>
<VirtualHost 111.22.33.55>
# server C
...
</VirtualHost>
<VirtualHost 111.22.33.44>
# server B
...
</VirtualHost>
<VirtualHost 111.22.33.55>
# server D
...
</VirtualHost>

NameVirtualHost 111.22.33.44
NameVirtualHost 111.22.33.55

(To aid the readability of your configuration you should prefer the left variant.)

After parsing the VirtualHost directive, the vhost server is given a default Listen equal to the port assigned to the first name in its VirtualHost directive.

The complete list of names in the VirtualHost directive are treated just like a ServerAlias (but are not overridden by any ServerAlias statement) if all names resolve to the same address set. Note that subsequent Listen statements for this vhost will not affect the ports assigned in the address set.

During initialization a list for each IP address is generated and inserted into an hash table. If the IP address is used in a NameVirtualHost directive the list contains all name-based vhosts for the given IP address. If there are no vhosts defined for that address the NameVirtualHost directive is ignored and an error is logged. For an IP-based vhost the list in the hash table is empty.

Due to a fast hashing function the overhead of hashing an IP address during a request is minimal and almost not existent. Additionally the table is optimized for IP addresses which vary in the last octet.

For every vhost various default values are set. In particular:

  1. If a vhost has no ServerAdmin, ResourceConfig, AccessConfig, Timeout, KeepAliveTimeout, KeepAlive, MaxKeepAliveRequests, or SendBufferSize directive then the respective value is inherited from the main_server. (That is, inherited from whatever the final setting of that value is in the main_server.)
  2. The "lookup defaults" that define the default directory permissions for a vhost are merged with those of the main_server. This includes any per-directory configuration information for any module.
  3. The per-server configs for each module from the main_server are merged into the vhost server.

Essentially, the main_server is treated as "defaults" or a "base" on which to build each vhost. But the positioning of these main_server definitions in the config file is largely irrelevant -- the entire config of the main_server has been parsed when this final merging occurs. So even if a main_server definition appears after a vhost definition it might affect the vhost definition.

If the main_server has no ServerName at this point, then the hostname of the machine that httpd is running on is used instead. We will call the main_server address set those IP addresses returned by a DNS lookup on the ServerName of the main_server.

For any undefined ServerName fields, a name-based vhost defaults to the address given first in the VirtualHost statement defining the vhost.

Any vhost that includes the magic _default_ wildcard is given the same ServerName as the main_server.

Virtual Host Matching

The server determines which vhost to use for a request as follows:

Hash table lookup

When the connection is first made by a client, the IP address to which the client connected is looked up in the internal IP hash table.

If the lookup fails (the IP address wasn't found) the request is served from the _default_ vhost if there is such a vhost for the port to which the client sent the request. If there is no matching _default_ vhost the request is served from the main_server.

If the IP address is not found in the hash table then the match against the port number may also result in an entry corresponding to a NameVirtualHost *, which is subsequently handled like other name-based vhosts.

If the lookup succeeded (a corresponding list for the IP address was found) the next step is to decide if we have to deal with an IP-based or a name-base vhost.

IP-based vhost

If the entry we found has an empty name list then we have found an IP-based vhost, no further actions are performed and the request is served from that vhost.

Name-based vhost

If the entry corresponds to a name-based vhost the name list contains one or more vhost structures. This list contains the vhosts in the same order as the VirtualHost directives appear in the config file.

The first vhost on this list (the first vhost in the config file with the specified IP address) has the highest priority and catches any request to an unknown server name or a request without a Host: header field.

If the client provided a Host: header field the list is searched for a matching vhost and the first hit on a ServerName or ServerAlias is taken and the request is served from that vhost. A Host: header field can contain a port number, but Apache always matches against the real port to which the client sent the request.

If the client submitted a HTTP/1.0 request without Host: header field we don't know to what server the client tried to connect and any existing ServerPath is matched against the URI from the request. The first matching path on the list is used and the request is served from that vhost.

If no matching vhost could be found the request is served from the first vhost with a matching port number that is on the list for the IP to which the client connected (as already mentioned before).

Persistent connections

The IP lookup described above is only done once for a particular TCP/IP session while the name lookup is done on every request during a KeepAlive/persistent connection. In other words a client may request pages from different name-based vhosts during a single persistent connection.

Absolute URI

If the URI from the request is an absolute URI, and its hostname and port match the main server or one of the configured virtual hosts and match the address and port to which the client sent the request, then the scheme/hostname/port prefix is stripped off and the remaining relative URI is served by the corresponding main server or virtual host. If it does not match, then the URI remains untouched and the request is taken to be a proxy request.

Observations

  • A name-based vhost can never interfere with an IP-base vhost and vice versa. IP-based vhosts can only be reached through an IP address of its own address set and never through any other address. The same applies to name-based vhosts, they can only be reached through an IP address of the corresponding address set which must be defined with a NameVirtualHost directive.
  • ServerAlias and ServerPath checks are never performed for an IP-based vhost.
  • The order of name-/IP-based, the _default_ vhost and the NameVirtualHost directive within the config file is not important. Only the ordering of name-based vhosts for a specific address set is significant. The one name-based vhosts that comes first in the configuration file has the highest priority for its corresponding address set.
  • For security reasons the port number given in a Host: header field is never used during the matching process. Apache always uses the real port to which the client sent the request.
  • If a ServerPath directive exists which is a prefix of another ServerPath directive that appears later in the configuration file, then the former will always be matched and the latter will never be matched. (That is assuming that no Host: header field was available to disambiguate the two.)
  • If two IP-based vhosts have an address in common, the vhost appearing first in the config file is always matched. Such a thing might happen inadvertently. The server will give a warning in the error logfile when it detects this.
  • A _default_ vhost catches a request only if there is no other vhost with a matching IP address and a matching port number for the request. The request is only caught if the port number to which the client sent the request matches the port number of your _default_ vhost which is your standard Listen by default. A wildcard port can be specified (i.e., _default_:*) to catch requests to any available port. This also applies to NameVirtualHost * vhosts.
  • The main_server is only used to serve a request if the IP address and port number to which the client connected is unspecified and does not match any other vhost (including a _default_ vhost). In other words the main_server only catches a request for an unspecified address/port combination (unless there is a _default_ vhost which matches that port).
  • A _default_ vhost or the main_server is never matched for a request with an unknown or missing Host: header field if the client connected to an address (and port) which is used for name-based vhosts, e.g., in a NameVirtualHost directive.
  • You should never specify DNS names in VirtualHost directives because it will force your server to rely on DNS to boot. Furthermore it poses a security threat if you do not control the DNS for all the domains listed. There's more information available on this and the next two topics.
  • ServerName should always be set for each vhost. Otherwise A DNS lookup is required for each vhost.

Tips

In addition to the tips on the DNS Issues page, here are some further tips:

  • Place all main_server definitions before any VirtualHost definitions. (This is to aid the readability of the configuration -- the post-config merging process makes it non-obvious that definitions mixed in around virtual hosts might affect all virtual hosts.)
  • Group corresponding NameVirtualHost and VirtualHost definitions in your configuration to ensure better readability.
  • Avoid ServerPaths which are prefixes of other ServerPaths. If you cannot avoid this then you have to ensure that the longer (more specific) prefix vhost appears earlier in the configuration file than the shorter (less specific) prefix (i.e., "ServerPath /abc" should appear after "ServerPath /abc/def").


ファイル記述子の限界 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > バーチャルホスト

ファイル記述子の限界

たくさんのバーチャルホストを運用する場合、もし、 各バーチャルホストごとに異なるログファイルが指定してあると、 Apache がファイル記述子 (ファイルハンドルとも呼ばれます) を使い切ってしまうことがあります。Apache が使用するファイル 記述子の数は、各エラーログファイルにつき 1 つ、他のログファイルの ディレクティブにつき 1 つ、さらに内部で使用する 10 から 20、 の合計になります。Unix オペレーティングシステムではプロセスごとに 使用可能なファイル記述子の数を制限しています。たいていの場合は 64 で、 普通は大きな値のハードリミットまで増やすことができます。

Apache は必要に応じて上限を拡大しようと試みますが、 以下のような場合にはうまくいかないかもしれません。

  1. 利用しているシステムで setrlimit() システムコールが提供されていない。
  2. システム上で setrlimit(RLIMIT_NOFILE) が動作しない (たとえば Solaris 2.3 のように)。
  3. 要求されるファイル記述子の数が ハードリミットを超えてしまう。
  4. システムにファイル記述子に関して別の制限が存在してしまっている。 たとえば、stdio ストリームではファイル記述子を 256 以上使えない (Solaris 2)、など。

問題が発生した時に取り得る対処方法は次のとおり:

  • ログファイルの数を減らす。<VirtualHost> セクションでログファイルを指定せず、メインのログファイルにのみ記録する。 (これに関する詳しい情報は以下のログファイルの分割を読んでください。)
  • もし、前述の 1 または 2 の場合であれば、 Apache を起動する前にファイル記述子を増やします。 たとえば次のようなスクリプトを使います。

    #!/bin/sh
    ulimit -S -n 100
    exec httpd

ファイル記述子の問題についての詳細や、 オペレーティングシステムごとの解決方法については「ファイル記述子と Apache」の文書を参照してください。

ログファイルの分割

複数のバーチャルホストのログを同じログファイルに収集しようとしているときには、 各バーチャルホストについて統計的な解析を実行するために後でログファイルを 分割したくなるかもしれません。これは以下のようにして実現できます。

まず、バーチャルホストの情報をログのエントリに追加する必要があります。 これは LogFormat ディレクティブの %v 変数を使うことでできます。 これをログのフォーマット文字列の先頭に追加します:

LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost
CustomLog logs/multiple_vhost_log vhost

これは common log format のログを作成しますが、それぞれの行の先頭に 正規化されたバーチャルホストの名前 (ServerName ディレクティブに書かれているもの) が付加されます。 (ログファイルのカスタマイズの詳細については Custom Log Formats を 読んでください。)

ログファイルを各部分 (バーチャルホスト毎に 1 ファイル) に分けたいときは、 split-logfile を使って行なうことができます。プログラムは Apache 配布の support ディレクトリにあります。

以下のようなコマンドでこのプログラムを実行します:

split-logfile < /logs/multiple_vhost_log

このプログラムはバーチャルホストのログファイルの名前とともに実行され、 ログファイルに現れるそれぞれのバーチャルホスト毎に一つのファイルを作成します。 それぞれのファイルは ホスト名.log という名前になります。


DNS と Apache にまつわる注意事項 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

DNS と Apache にまつわる注意事項

本文書の内容は次の一言に尽きます。「Apache が設定ファイルを読み込むときに DNS を使用する必要がないようにして下さい」。Apache が設定ファイルを 読み込むときに DNS を使用する必要がある場合、信頼性の問題 (起動しないかもしれません) やサービス拒否や盗用アタック (他のユーザからヒットを盗むことを含みます) の問題に直面するかもしれません。

簡単な例

<VirtualHost www.abc.dom>
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>

Apache が正常に機能するには、バーチャルホスト毎に必ず二つの 情報が必要になります。それは、 ServerName と、そのサーバが応答するための IP (最低一つ) です。 上記例では IP アドレスを含んでいませんので、Apache は DNS を使用して www.abc.dom を見つけなければなりません。 何らかの理由で設定ファイルを読み込んでいるときに DNS が利用できなかった場合、 バーチャルホストは設定されません。 そして、そのバーチャルホストに対するヒットには応答がなされません (Apache 1.2 以前では起動すらしません)。

www.abc.dom のアドレスが 10.0.0.1 だとします。では、次の設定について考えてみましょう。

<VirtualHost 10.0.0.1>
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>

現在のリリースでは Apache は DNS 逆引きを使用して このバーチャルホストの ServerName を見つけます。 その逆引きが失敗した場合は部分的にバーチャルホストを無効にします (Apache 1.2 より前では起動すらしません)。 バーチャルホストが名前ベースであれば完全に無効になりますが、 IP ベースであれば概ね動作します。しかしながら、サーバ名を 含む完全な URL を生成しなければならない場合は、正しい URL の生成ができません。

次の例は上記の問題を解決しています。

<VirtualHost 10.0.0.1>
ServerName www.abc.dom
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>

サービス拒否

サービス拒否が起こる場合、(少なくとも) 二つのケースがあります。 Apache 1.2 より前を実行している場合、バーチャルホストのための 上記の二つの DNS 検索のうち一つ失敗すれば起動すらしません。 そしてこの DNS 検索が自分の制御下にすらない場合もありえます。 例えば、abc.dom が顧客のサーバの一つで、 DNS は顧客自身で管理している場合、単に www.abc.dom レコードを削除するだけで、 (1.2 より前の) サーバを起動不能にすることができます。

もう一つのケースは、より気付きにくいものです。 次の設定について考えてみましょう。

<VirtualHost www.abc.dom>
  ServerAdmin webgirl@abc.dom
  DocumentRoot /www/abc
</VirtualHost>

<VirtualHost www.def.dom>
  ServerAdmin webguy@def.dom
  DocumentRoot /www/def
</VirtualHost>

10.0.0.1 を www.abc.dom に、 10.0.0.2 を www.def.dom に割り当てているとします。 また、def.dom は顧客自身の DNS の制御下にあるとします。この設定で、abc.dom に向けられたトラフィック全てを奪うことができる位置に def.dom を設置できています。後は単に www.def.dom が 10.0.0.1 を参照するように 設定するだけです。DNS は顧客側の DNS でコントロールされているので、 www.def.dom レコードが好きな場所を指すように 設定できてしまうのを止めさせることができません。

10.0.0.1 に対するリクエスト (http://www.abc.dom/whatever 形式の URL を入力したユーザからのもの全てを含みます) は、def.dom バーチャルホストで応答されます。 このようなことが何故起こるかもっと良く知るためには、 応答の必要なバーチャルホストへのリクエストに対して、 Apache がどのように整合性を確保するかについて、 深い議論が必要になります。おおざっぱな説明はこちらに記述されています。

「主サーバ」アドレス

Apache 1.1 での 名前ベースのバーチャルホストのサポート 追加の際に、 Apache は httpd の実行されているホストの IP アドレスを知る必要が出てきました。このアドレスを得るために、 (もしあれば) グローバルな ServerName を使用するか、 C 言語の関数 gethostname (コマンドプロンプトで hostname とタイプしたときと同じものを返します) を呼び出すかをします。 その後、得られたアドレスで DNS 検索を行ないます。 現在のところ、この DNS 検索を回避する方法はありません。

DNS サーバがダウンして、この検索ができない事態が起こることを 恐れているのであれば、/etc/hosts にホスト名を記述しておくことができます (マシンが正常に起動するように既に設定されているかもしれません)。 その場合、DNS 参照が失敗した場合にマシンが /etc/hosts を使用するように設定していることを確認してください。 その方法は、どの OS を使用しているかに依存しますが、 /etc/resolv.conf か /etc/nsswitch.conf を編集することで設定できます。

もし他の理由で DNS を利用する必要がない場合は、 HOSTRESORDER 環境変数を「 local 」に設定することでそのようにできます。以上これらの事柄は、どんな OS 、レゾルバライブラリを使用しているかに依存します。また、 mod_env を使用して環境変数を制御しない限り、 CGI にも影響を与えます。man ページや使用している OS の FAQ で調べると良いでしょう。

以上の問題を解決する方法

  • VirtualHost で IP アドレスを使用する。
  • Listen で IP アドレスを使用する。
  • 全てのバーチャルホストが明示的に ServerName を持つようにする。
  • 何も応答しない <VirtualHost _default_:*> サーバを作る。

付録: 将来的な方向性

DNS に関して、現状は全く宜しくありません。Apache 1.2 で、 DNS のイベントが失敗しても少なくとも起動プロセスが続くようにしましたが、 これが最高の解決方法ではないでしょう。アドレスの再割り当てが必要不可避 となっている今日のインターネットにおいては、 設定ファイルの中で明示的な IP アドレスを要求する仕様は、 全く宜しくありません。

盗用のサービスアタックに関して行なうべき事は、 DNS 順引きを行なって得られたアドレスに対する DNS 逆引きを行なって、二つの名前を比較することです。 この二つが一致しなければバーチャルホストは無効になるようにします。 こうするためには逆引き DNS が適切に設定されている必要があります (FTP サーバや TCP ラッパーのおかげで「二重逆引き」DNS は一般的に なっていますので、管理者にはお馴染みものでしょう)。

IP アドレスが使用されていなくて DNS が失敗した場合は、 どうしてもバーチャルホストウェブサーバを信頼性を確保して 起動させることは不可能のようです。 設定の一部を無効にするというような部分的な解決では、 サーバが何をするようにするかにもよりますが、 そのサーバが起動しないより確実に悪い状況になるでしょう。

HTTP/1.1 が開発され、ブラウザやプロキシが Host ヘッダを発行するようになったので、IP ベースのバーチャルホストを 全く使用しなくても済むようになるかもしれません。 この場合、ウェブサーバは設定中に DNS 参照をしなくても済みます。 しかし 1997 年 3 月時点の状況では、 商用レベルのウェブサーバで使用できるほどには、 これらの機能は広く開発が進んでいません。


Frequently Asked Questions - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Frequently Asked Questions

The latest version of this FAQ is always available from the main Apache web site, at <http://httpd.apache.org/docs-2.0/faq/>. In addition, you can view this FAQ all in one page for easy searching and printing.

Since Apache 2.0 is quite new, we don't yet know what the Frequently Asked Questions will be. While this section fills up, you should also consult the Apache 1.3 FAQ to see if your question is answered there.

Topics

Support
What do I do when I have problems?
Error Messages
What does this error message mean?


Support - Frequently Asked Questions - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > FAQ

Support - Frequently Asked Questions

Support

  • "Why can't I ...? Why won't ... work?" What to do in case of problems
  • Whom do I contact for support?

"Why can't I ...? Why won't ... work?" What to do in case of problems

If you are having trouble with your Apache server software, you should take the following steps:

Check the errorlog!
Apache tries to be helpful when it encounters a problem. In many cases, it will provide some details by writing one or messages to the server error log. Sometimes this is enough for you to diagnose & fix the problem yourself (such as file permissions or the like). The default location of the error log is /usr/local/apache2/logs/error_log, but see the ErrorLog directive in your config files for the location on your server.
Check the FAQ!
The latest version of the Apache Frequently-Asked Questions list can always be found at the main Apache web site.
Check the Apache bug database
Most problems that get reported to The Apache Group are recorded in the bug database. Please check the existing reports, open and closed, before adding one. If you find that your issue has already been reported, please don't add a "me, too" report. If the original report isn't closed yet, we suggest that you check it periodically. You might also consider contacting the original submitter, because there may be an email exchange going on about the issue that isn't getting recorded in the database.
Ask in a user support forum

Apache has an active community of users who are willing to share their knowledge. Participating in this community is usually the best and fastest way to get answers to your questions and problems.

Users mailing list

USENET newsgroups:

  • comp.infosystems.www.servers.unix [news] [google]
  • comp.infosystems.www.servers.ms-windows [news] [google]
  • comp.infosystems.www.authoring.cgi [news] [google]
If all else fails, report the problem in the bug database

If you've gone through those steps above that are appropriate and have obtained no relief, then please do let the httpd developers know about the problem by logging a bug report.

If your problem involves the server crashing and generating a core dump, please include a backtrace (if possible). As an example,

# cd ServerRoot
# dbx httpd core
(dbx) where

(Substitute the appropriate locations for your ServerRoot and your httpd and core files. You may have to use gdb instead of dbx.)

Whom do I contact for support?

With several million users and fewer than forty volunteer developers, we cannot provide personal support for Apache. For free support, we suggest participating in a user forum.

Professional, commercial support for Apache is available from a number of companies.


Error Messages - Frequently Asked Questions - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > FAQ

Error Messages - Frequently Asked Questions

Error Messages

  • Invalid argument: core_output_filter: writing data to the network
  • AcceptEx failed
  • Premature end of script headers

Invalid argument: core_output_filter: writing data to the network

Apache uses the sendfile syscall on platforms where it is available in order to speed sending of responses. Unfortunately, on some systems, Apache will detect the presence of sendfile at compile-time, even when it does not work properly. This happens most frequently when using network or other non-standard file-system.

Symptoms of this problem include the above message in the error log and zero-length responses to non-zero-sized files. The problem generally occurs only for static files, since dynamic content usually does not make use of sendfile.

To fix this problem, simply use the EnableSendfile directive to disable sendfile for all or part of your server. Also see the EnableMMAP, which can help with similar problems.

AcceptEx Failed

If you get error messages related to the AcceptEx syscall on win32, see the Win32DisableAcceptEx directive.

Premature end of script headers

Most problems with CGI scripts result in this message written in the error log together with an Internal Server Error delivered to the browser. A guide to helping debug this type of problem is available in the CGI tutorial.


Apache の SSL/TLS 暗号化 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

Apache の SSL/TLS 暗号化

Apache HTTP サーバモジュール mod_ssl が OpenSSL ライブラリへのインターフェースを提供していますが、これは Secure Sockts Layer と Transport Layer Security プロトコルを用いた強力な暗号化を提供します。 このモジュールやこの文書は Ralf S. Engelschall の mod_ssl プロジェクトに基づいています。

Documentation

  • はじめに
  • 互換性
  • How-To
  • よくある質問
  • 用語

mod_ssl

このモジュールで提供されるディレクティブや環境変数に関する 詳しい文書は、mod_ssl リファレンスをご覧下さい。


SSL/TLS 暗号化: はじめに - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > SSL/TLS

SSL/TLS 暗号化: はじめに

標準規格の良い所は、たくさんの規格から選べるということだ。 そして、もし本当にどの規格も気に入らなければ、 一年待つだけで探していた規格が現れる。

-- A. Tanenbaum, "Introduction to Computer Networks"

入門ということで、この章は Web、HTTP、Apache に通じている 読者向けですが、セキュリティ専門家向けではありません。 SSL プロトコルの決定的な手引きであるつもりはありません。 また、組織内の認証管理のための特定のテクニックや、 特許や輸出規制などの重要な法的な問題についても扱いません。 むしろ、更なる研究への出発点として色々な概念、定義、例を並べることで mod_ssl のユーザに基礎知識を提供する事を目的としています。

ここに示された内容は主に、原著者の許可の下 The Open Group Research Institute の Frederick J. Hirsch 氏の記事 Introducing SSL and Certificates using SSLeay を基にしています。 氏の記事は Web Security: A Matter of Trust, World Wide Web Journal, Volume 2, Issue 3, Summer 1997 に掲載されました。 肯定的な意見は Frederick Hirsch 氏 (元記事の著者) へ全ての苦情は Ralf S. Engelschall ( mod_ssl の作者) へお願いします。 [訳注: 訳については Apache ドキュメント翻訳プロジェクト へお願いします。]

暗号化技術

SSL を理解するには、暗号アルゴリズム、 メッセージダイジェスト関数(別名: 一方向関数、ハッシュ関数)、 電子署名などへの理解が必要です。 これらの技術は本が丸ごと必要な題目で (例えば [AC96] を参照)、 プライバシー、信用、認証などの技術の基礎となっています。

暗号アルゴリズム

例えば、アリスが送金のために銀行にメッセージを送りたいとします。 口座番号や送金の金額が含まれるため、 アリスはそのメッセージを秘密にしたいと思います。 解決方法の一つは暗号アルゴリズムを使って、メッセージを 読ませたい人以外は読むことができない暗号化された 形態に変えてしまうことです。 その形態になると、 メッセージは秘密の鍵によってのみ解釈することができます。 鍵なしでは、メッセージは役に立ちません。 良い暗号アルゴリズムは、侵入者が元のテキストを解読することを 非常に難しくするため、努力が割に合わなくさせます。

暗号アルゴリズムには 従来型と公開鍵の二つの種類があります。

従来型暗号
対称暗号としても知られ、 送信者と受信者が鍵を共有することが必要です。 鍵とは、メッセージを暗号化したり復号するのに使われる秘密 の情報のことです。 もし、この鍵が秘密なら、送信者と受信者以外は誰もメッセージを読 むことができません。 もしも、アリスと銀行が秘密の鍵を知っているなら、 彼らはお互いに秘密のメッセージを送ることができるでしょう。 ただし、事前に内密に鍵を選ぶという仕事は問題を含んでいます。
公開鍵暗号
非対称暗号としても知られ、 メッセージを暗号化することのできる二つの鍵 を使用するアルゴリズムを定義することで鍵のやり取りの問題を解決 します。 もし、ある鍵が暗号化に使われたなら、 もう片方の鍵で復号しなければいけません。 この方式によって、一つの鍵を公表して(公開鍵)、 もう片方を秘密にしておく(秘密鍵)だけで、 安全なメッセージを受け取ることができます。

誰もが暗号化されたメッセージを公開鍵によって暗号化 することができますが、秘密鍵の持ち主だけがそれを読むことが できます。 この方法で、銀行の公開鍵を使って暗号化することで、 アリスは秘密のメッセージを送ることができます。 銀行のみが復号することができます。

メッセージダイジェスト

アリスはメッセージを秘密にすることができますが、 誰かが例えば自分に送金するようにメッセージを変更したり、 別のものに置き換えてしまうかもしれないという問題があります。 アリスのメッセージの信用を保証する方法の一つは、 メッセージの簡潔なダイジェストを作って、それも銀行に送るというものです。 メッセージを受け取ると銀行もダイジェストを作成し、 アリスが送ったものと比べます。もし一致したなら、 受け取ったメッセージは無傷だということになります。

このような要約はメッセージダイジェスト、 一方行関数、またはハッシュ関数と呼ばれます。 メッセージダイジェストは長い可変長のメッセージから 短い固定長の表現を作るのに使われます。 ダイジェストアルゴリズムはメッセージから 一意なダイジェストを生成するように作られています。 メッセージダイジェストはダイジェストから元のメッセージを 判定するのがとても難しいようにできています。 また、同じ要約を作成する二つのメッセージを探すのは不可能です。 よって、同じ要約を使ってメッセージを置き換えるという 可能性を排除しています。

アリスへのもう一つの問題は、このダイジェストを安全に送る方法を探すことです。 これができれば、メッセージの信用が保証されます。 一つの方法はこのダイジェストに電子署名を含むことです。

電子署名

アリスが銀行にメッセージを送ったとき、銀行は、 侵入者が彼女になりすまして彼女の口座への取引を申請していないか、 メッセージが本当に彼女からのものか確実に分からなければいけません。 アリスによって作成され、メッセージに含まれた 電子署名がここで役に立ちます。

電子署名はメッセージのダイジェストやその他の情報(処理番号など)を 送信者の秘密鍵で暗号化することで作られます。 誰もが公開鍵を使って署名を復号することができますが、 署名者のみが秘密鍵を知っています。 これは、彼らのみが署名しえたことを意味します。 ダイジェストを電子署名に含むことは、 その署名がそのメッセージのみに有効であることを意味します。 これは、誰もダイジェストを変えて署名をすることができないため、 メッセージの信用も保証します。

侵入者が署名を傍受して後日に再利用するのを防ぐため 電子署名には一意な処理番号が含まれます。 これは、アリスがそんなメッセージは送っていないと言う詐欺 から銀行を守ります。 彼女だけが署名しえたからです。(否認防止)

証明書

アリスは秘密のメッセージを銀行に送り、 署名をして、メッセージの信用を保証することができるおうになりましたが、 通信している相手が本当に銀行なのか確かめなくてはいけません。 これは、彼女が使う公開鍵が銀行の秘密鍵と対になっているものか、 彼女は確かめなくてはいけないということを意味します。 同様に、銀行はメッセージの署名が本当にアリスの署名か確認する必要が あります。

もし両者に身元を証明し、公開鍵を確認し、また信頼された機関が署名 した証明書があれば、両者とも通信相手について正しい相手だと 確信することができます。 そのような信頼された機関は認証局 (Certificate Authority または CA) と呼ばれ、 証明書 (certificate) が認証 (authentication) に使われます。

証明書の内容

証明書は公開鍵と個人、サーバ、その他の主体の実在の身元を 関連付けます。 表1に示されるように証明対象の情報は 身元証明の情報(識別名)と公開鍵が含まれます。 証明書はまた、認証局の身元証明と署名、そして証明書の有効期間を 含みます。 シリアルナンバーなどの認証局の管理上の情報や その他の追加の情報が含まれているかもしれません。

表1: 証明書情報

証明対象 | 識別名、公開鍵
発行者 | 識別名、公開鍵
有効期間 | 開始日、失効日
管理情報 | バージョン、シリアルナンバー
拡張情報 | 基本的な制約、ネットスケープフラッグ、その他

識別名(ディスティングイッシュ・ネーム)は特定の状況における 身分証明を提供するのに使われています。例えば、ある人は 私用と会社とで別々の身分証明を持つかもしれません。 識別名は X.509 標準規格 [X509] で定義されています。 X.509 標準規格は、項目、項目名、そして項目の略称を定義しています。(表 2 参照)

表 2: 識別名情報

識別名項目 | 略称 | 説明 | 例
Common Name (コモンネーム) | CN | 認証される名前 SSL接続するURL | CN=www.example.com
Organization or Company (組織名) | O | 団体の正式英語組織名 | O=Example Japan K.K.
Organizational Unit (部門名) | OU | 部署名など | OU=Customer Service
City/Locality (市区町村) | L | 所在してる市区町村 | L=Sapporo
State/Province (都道府県) | ST | 所在してる都道府県 | ST=Hokkaido
Country(国) | C | 所在している国名の ISO コード 日本の場合 JP | C=JP

認証局はどの項目が省略可能でどれが必須かの方針を定義する かもしれません。項目の内容についても認証局や証明書のユーザからの 要件があるかもしれません。 例えば、ネットスケープのブラウザはサーバの証明書の Common Name (コモンネーム)がサーバのドメイン名の *.example.com というようなワイルドカードのパターンにマッチすること を要求します。

バイナリ形式の証明書は ASN.1 表記法 [X208] [PKCS] で 定義されています。 この表記法は内容をどのように記述するかを定義し、 符号化の規定がこの情報がどのようにバイナリ形式に変換されるかを 定義します。 証明書のバイナリ符号化は Distinguished Encoding Rules (DER) で定義され、それはより一般的な Basic Encoding Rules (BER) に基づいています。 バイナリ形式を扱うことのできない送信では、 バイナリ形式は Base64 符号化 [MIME] で ASCII 形式に変換されることがあります。 このように符号化され、以下の例に示されるように区切り行に 挟まれたものは PEM 符号化されたと言います。 (PEM の名前は "Privacy Enhanced Mail" に由来します)

PEM 符号化された証明書の例 (example.crt)

-----BEGIN CERTIFICATE-----
MIIC7jCCAlegAwIBAgIBATANBgkqhkiG9w0BAQQFADCBqTELMAkGA1UEBhMCWFkx
FTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1UEBxMKU25ha2UgVG93bjEXMBUG
A1UEChMOU25ha2UgT2lsLCBMdGQxHjAcBgNVBAsTFUNlcnRpZmljYXRlIEF1dGhv
cml0eTEVMBMGA1UEAxMMU25ha2UgT2lsIENBMR4wHAYJKoZIhvcNAQkBFg9jYUBz
bmFrZW9pbC5kb20wHhcNOTgxMDIxMDg1ODM2WhcNOTkxMDIxMDg1ODM2WjCBpzEL
MAkGA1UEBhMCWFkxFTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1UEBxMKU25h
a2UgVG93bjEXMBUGA1UEChMOU25ha2UgT2lsLCBMdGQxFzAVBgNVBAsTDldlYnNl
cnZlciBUZWFtMRkwFwYDVQQDExB3d3cuc25ha2VvaWwuZG9tMR8wHQYJKoZIhvcN
AQkBFhB3d3dAc25ha2VvaWwuZG9tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKB
gQDH9Ge/s2zcH+da+rPTx/DPRp3xGjHZ4GG6pCmvADIEtBtKBFAcZ64n+Dy7Np8b
vKR+yy5DGQiijsH1D/j8HlGE+q4TZ8OFk7BNBFazHxFbYI4OKMiCxdKzdif1yfaa
lWoANFlAzlSdbxeGVHoT0K+gT5w3UxwZKv2DLbCTzLZyPwIDAQABoyYwJDAPBgNV
HRMECDAGAQH/AgEAMBEGCWCGSAGG+EIBAQQEAwIAQDANBgkqhkiG9w0BAQQFAAOB
gQAZUIHAL4D09oE6Lv2k56Gp38OBDuILvwLg1v1KL8mQR+KFjghCrtpqaztZqcDt
2q2QoyulCgSzHbEGmi0EsdkPfg6mp0penssIFePYNI+/8u9HT4LuKMJX15hxBam7
dUHzICxBVC1lnHyYGjDuAMhe396lYAn8bCld1/L4NMGBCQ==
-----END CERTIFICATE-----

認証局

まず証明書の申請の情報を確認することで、 認証局は秘密鍵の持ち主の身元を保証します。 例えば、アリスが個人証明書を申請したとすると、 認証局はアリスが証明書の申請が主張する通りの 人物だということを確認しなくてはいけません。

証明書階層構造

認証局は他の認証局への証明書を発行することができます。 未知の証明書を調べる時に、アリスはその証明書の発行者 に自信が持てるまで、発行者の証明書を その上位階層の認証局をたどって調べる必要があります。 「悪質な」証明書の危険性を減らすため、 彼女は限られた連鎖の発行者のみ信頼するように 決めることもできます。

最上位認証局の作成

前に述べたように、全ての証明書について、 最上位の認証局(CA)までそれぞれの発行者が 対象の身元証明の有効性を明らかにする必要があります。 問題は、誰がその最上位の認証機関の証明書を保証するのか、 ということです。 このような場合に限り、証明書は「自己署名」されます。 つまり、証明書の発行者と証明対象が同じということになります。 その結果、自己署名された証明書を信用するには 細心の注意が必要です。 最上位認証局が公開鍵を広く公表することで、 その鍵を信頼するリスクを低くすることができます。 もし、他人がその認証局になりすました時に、それが露見しや すいからです。 多くのブラウザは有名な認証局を信頼するように 設定されています。

Thawte や VeriSign のような多くの会社が認証局として開設しました。 このような会社は以下のサービスを提供します:

  • 証明書申請の確認
  • 証明書申請の処理
  • 証明書の発行と管理

自分で認証局を作ることも可能です。 インターネット環境では危険ですが、 個人やサーバの身元証明が簡単に行える組織の イントラネット内では役に立つかもしれません。

証明書管理

認証局の開設は徹底した管理、技術、運用の体制を必要とする 責任のある仕事です。 認証局は証明書を発行するだけでなく、 管理もしなければなりません。 具体的には、証明書がいつまで有効かを決定し、更新し、 また既に発行されたが失効した証明書のリスト (Certificate Revocation Lists または CRL) を管理しなければいけません。 例えば、アリスが会社から社員として証明書を与えられたとします。 そして、アリスが会社を辞めるときには証明書を取り消さなければ いけないとします。 証明書は次々と人に渡されていくものなので、 証明書そのものから、それが取り消されたか判断することは 不可能です。 よって、証明書の有効性を調べるときには、 認証局に連絡して CRL を照合する必要があります。 普通この過程は自動化されているものではありません。

注意

デフォルトでブラウザに設定されていない認証局を使った場合、 認証局の証明書をブラウザに読み込んで、 ブラウザがその認証局によって署名されたサーバの証明書を 有効化する必要があります。 一度読み込まれると、その認証局によって署名された全ての 証明書を受け入れるため、危険を伴います。

Secure Sockets Layer (SSL)

Secure Sockets Layer プロトコルは信頼性のあるコネクション型の ネットワーク層のプロトコル(例えば、TCP/IP)と アプリケーション層のプロトコル(例えば、HTTP) の間に置くことができます。 SSL は、相互認証によってサーバとクライアント間の安全な通信を、 電子署名によってデータの完全性を、 そして暗号化によってプライバシを提供します。

SSL プロトコルは暗号化、ダイジェスト、電子署名について、 様々なアルゴリズムをサポートするようにできています。 こうすることで、法や輸出の規制を考慮に入れて、サーバに合わせた アルゴリズムを選ぶことができ、また、新しいアルゴリズムを 利用していくことも可能にしています。 アルゴリズムの選択はプロトコルセッション開始時に サーバとクライアント間で取り決められます。

表4: SSL プロトコルのバージョン

バージョン | 出典 | 説明 | ブラウザのサポート
SSL v2.0 | Vendor Standard (Netscape Corp. より) [SSL2] | 実装が現存する初めての SSL プロトコル | - NS Navigator 1.x/2.x - MS IE 3.x - Lynx/2.8+OpenSSL
SSL v3.0 | Expired Internet Draft (Netscape Corp. より) [SSL3] | 特定のセキュリティ攻撃を防ぐための改訂、 非RSA 暗号の追加、証明書階層構造のサポート | - NS Navigator 2.x/3.x/4.x - MS IE 3.x/4.x - Lynx/2.8+OpenSSL
TLS v1.0 | Proposed Internet Standard (IETF より) [TLS1] | MAC レイヤを HMAC へ更新、ブロック暗号の block padding、メッセージ順序の標準化、警告文の充実などのため SSL 3.0 を改訂。 | - Lynx/2.8+OpenSSL

表4に示されるとおり、SSL プロトコルには いくつものバージョンがあります。 表にも書かれているように、SSL 3.0 の利点の一つは 証明書階層構造をサポートすることです。 この機能によって、サーバは自分の証明書に加えて、 発行者の証明書をブラウザに渡すことができます。 証明書階層構造によって、 ブラウザに発行者の証明書が直接登録されていなくても、 階層の中に含まれていれば、 ブラウザはサーバの証明書を有効化することができます。 SSL 3.0 は現在 Internet Engineering Task Force (IETF) によって開発されている Transport Layer Security [TLS] プロトコル標準規格の基礎となっています。

セッションの確立

図1で示されるように、 セッションの確立はクライアントとサーバ間の ハンドシェークシークエンスによって行なわれます。 サーバが証明書を提供するか、クライアントの証明書をリクエストするか というサーバの設定により、このシークエンスは異なるものとなります。 暗号情報の管理のために、追加のハンドシェーク過程が必要になる 場合もありますが、この記事では よくあるシナリオを手短に説明します。 全ての可能性についは、SSL 仕様書を参照してください。

注意

一度 SSL セッションが確立すると、セッションを再利用することで、 セッションを開始するための多くの過程を繰り返すという パフォーマンスの損失を防ぎます。 そのため、サーバは全てのセッションに一意なセッション識別名を 割り当て、サーバにキャッシュし、クライアントは次回から (識別名がサーバのキャッシュで期限切れになるまでは) ハンドシェークなしで接続することができます。

図1: SSL ハンドシェークシークエンス概略

サーバとクライアントで使われる ハンドシェークシークエンスの要素を以下に示します:

  1. データ通信に使われる暗号スイートの取り決め
  2. クライアントとサーバ間でのセッション鍵の確立と共有
  3. オプションとして、クライアントに対するサーバの認証
  4. オプションとして、サーバに対するクライアントの認証

第一ステップの暗号スイート取り決めによって、 サーバとクライアントはそれぞれにあった 暗号スイートを選ぶことができます。 SSL3.0 プロトコルの仕様書は 31 の暗号スイートを定義しています。 暗号スイートは以下のコンポーネントにより定義されています:

  • 鍵の交換手段
  • データ通信の暗号術
  • Message Authentication Code (MAC) 作成のための メッセージダイジェスト

これらの三つの要素は以下のセクションで説明されています。

鍵の交換手段

鍵の交換手段はアプリケーションのデータ通信に使われ、 共有される対称暗号鍵をどのようにがクライアントとサーバで 取り決めるかを定義します。 SSL 2.0 は RSA 鍵交換しか使いませんが、 SSL 3.0 は証明書が使われるときは RSA 鍵交換を使い、 証明書が無く、クライアントとサーバの事前の通信が無い場合は Diffie-Hellman 鍵交換を使う など様々な鍵交換アルゴリズムをサポートします。

鍵の交換方法における一つの選択肢は電子署名です。 電子署名を使うかどうか、また、 どの種類の署名を使うかという選択があります。 秘密鍵で署名することで共有鍵を生成すし、情報交換する時の マン・イン・ザ・ミドル攻撃を防ぐことができます。 [AC96, p516]

データ通信の暗号術

SSL はセッションのメッセージの暗号化に前述した 従来型暗号(対称暗号)を用います。 暗号化しないという選択肢も含め九つの選択肢があります:

  • 暗号化なし
  • ストリーム暗号
    • 40-bit 鍵での RC4
    • 128-bit 鍵での RC4
  • CBC ブロック暗号
    • 40 bit 鍵での RC2
    • 40 bit 鍵での DES
    • 56 bit 鍵での DES
    • 168 bit 鍵での Triple-DES
    • Idea (128 bit 鍵)
    • Fortezza (96 bit 鍵)

ここでの CBC とは暗号ブロック連鎖 (Cipher Block Chaining) の略で、一つ前の暗号化された暗号文の一部が ブロックの暗号化に使われることを意味します。 DES はデータ暗号化標準規格 (Data Encryption Standard) [AC96, ch12] の略で、 DES40 や 3DES_EDE を含むいくつもの種類があります。 Idea は最高なものの一つで、暗号術的には現在ある中で 最も強力なものです。 RC2 は RSA DSI による独占的なアルゴリズムです。 [AC96, ch13]

ダイジェスト関数

ダイジェスト関数の選択はレコードユニットからどのようにダイジェストが生成されるかを決定します。 SSL は以下をサポートします:

  • ダイジェストなし
  • MD5 (128-bit ハッシュ)
  • Secure Hash Algorithm (SHA-1) (160-bit ハッシュ)

メッセージダイジェストは Message Authentication Code (MAC) の生成に使われ、メッセージと共に暗号化され、メッセージの信用を 提供し、リプレイ攻撃を防ぎます。

ハンドシェークシークエンスプロトコル

ハンドシェークシークエンスは三つのプロトコルを使います:

  • SSL ハンドシェークプロトコルは クライアントとサーバ間での SSL セッションの確立に使われます。
  • SSL 暗号仕様変更プロトコルは セッションでの暗号スイートの取り決めに使われます。
  • SSL 警告プロトコルは クライアントサーバ間で SSL エラーを伝達するのに使われます。

三つのプロトコルは、アプリケーションプロトコルデータとともに、 図2に示すとおり SSL レコードプロトコル でカプセル化されます。 カプセル化されたプロトコルはデータを検査しない 下層のプロトコルによってデータとして伝達されます。 カプセル化されたプロトコルは下層のプロトコルに関して一切関知しません。

図2: SSL プロトコルスタック

レコードプロトコルによる SSL コントロールプロトコルのカプセル化は、 アクティブなセッションの二回目の通信があった場合、 コントロールプロトコルが安全であることを意味します。 既にセッションが無い場合は、Null 暗号スイートが使われ、 暗号化は行なわれず、セッションが確立するまでは ダイジェストも無い状態となります。

データ通信

図3に示される SSL レコードプロトコル はクライアントとサーバ間のアプリケーションや SSL コントロールデータの通信に使われます。 このデータはより小さいユニットに分けられたり、 いくつかの高級プロトコルをまとめて一ユニットとして通信が 行なわれることもあります。 データを圧縮し、ダイジェスト署名を添付して、 これらのユニットを暗号化したのち、ベースとなっている 信頼性のあるトランスポートプロトコルを用いるかもしれません。 (注意: 現在メジャーな SLL 実装で圧縮をサポートしているものはありません)

図 3: SSL レコードプロトコル

HTTP 通信の安全化

よくある SSL の使い方はブラウザとウェブサーバ間の HTTP 通信 の安全化です。 これは、従来の安全ではない HTTP の使用を除外するものではありません。 安全化されたものは主に SSH 上の普通の HTTP で、HTTPS と呼ばれます。 大きな違いは、URL スキームに http の代わりに https を用い、サーバが別のポートを使うことです (デフォルトでは443)。 これが主に mod_ssl が Apache ウェブサーバに提供する機能です。

参考文献

[AC96]
Bruce Schneier, Applied Cryptography, 2nd Edition, Wiley, 1996. See http://www.counterpane.com/ for various other materials by Bruce Schneier.
[X208]
ITU-T Recommendation X.208, Specification of Abstract Syntax Notation One (ASN.1), 1988. See for instance http://www.itu.int/rec/recommendation.asp?type=items&lang=e&parent=T-REC-X.208-198811-I.
[X509]
ITU-T Recommendation X.509, The Directory - Authentication Framework. See for instance http://www.itu.int/rec/recommendation.asp?type=folders&lang=e&parent=T-REC-X.509.
[PKCS]
Public Key Cryptography Standards (PKCS), RSA Laboratories Technical Notes, See http://www.rsasecurity.com/rsalabs/pkcs/.
[MIME]
N. Freed, N. Borenstein, Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies, RFC2045. See for instance http://ietf.org/rfc/rfc2045.txt.
[SSL2]
Kipp E.B. Hickman, The SSL Protocol, 1995. See http://www.netscape.com/eng/security/SSL_2.html.
[SSL3]
Alan O. Freier, Philip Karlton, Paul C. Kocher, The SSL Protocol Version 3.0, 1996. See http://www.netscape.com/eng/ssl3/draft302.txt.
[TLS1]
Tim Dierks, Christopher Allen, The TLS Protocol Version 1.0, 1999. See http://ietf.org/rfc/rfc2246.txt.


SSL/TLS Strong Encryption: Compatibility - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > SSL/TLS

SSL/TLS Strong Encryption: Compatibility

All PCs are compatible. But some of them are more compatible than others.

-- Unknown

Here we talk about backward compatibility to other SSL solutions. As you perhaps know, mod_ssl is not the only existing SSL solution for Apache. Actually there are four additional major products available on the market: Ben Laurie's freely available Apache-SSL (from where mod_ssl were originally derived in 1998), Red Hat's commercial Secure Web Server (which is based on mod_ssl), Covalent's commercial Raven SSL Module (also based on mod_ssl) and finally C2Net's commercial product Stronghold (based on a different evolution branch named Sioux up to Stronghold 2.x and based on mod_ssl since Stronghold 3.x).

The idea in mod_ssl is mainly the following: because mod_ssl provides mostly a superset of the functionality of all other solutions we can easily provide backward compatibility for most of the cases. Actually there are three compatibility areas we currently address: configuration directives, environment variables and custom log functions.

Configuration Directives

For backward compatibility to the configuration directives of other SSL solutions we do an on-the-fly mapping: directives which have a direct counterpart in mod_ssl are mapped silently while other directives lead to a warning message in the logfiles. The currently implemented directive mapping is listed in Table 1. Currently full backward compatibility is provided only for Apache-SSL 1.x and mod_ssl 2.0.x. Compatibility to Sioux 1.x and Stronghold 2.x is only partial because of special functionality in these interfaces which mod_ssl (still) doesn't provide.

Table 1: Configuration Directive Mapping

Old Directive | mod_ssl Directive | Comment
Apache-SSL 1.x & mod_ssl 2.0.x compatibility:
SSLEnable | SSLEngine on | compactified
SSLDisable | SSLEngine off | compactified
SSLLogFile file | SSLLog file | compactified
SSLRequiredCiphers spec | SSLCipherSuite spec | renamed
SSLRequireCipher c1 ... | SSLRequire %{SSL_CIPHER} in {"c1", ...} | generalized
SSLBanCipher c1 ... | SSLRequire not (%{SSL_CIPHER} in {"c1", ...}) | generalized
SSLFakeBasicAuth | SSLOptions +FakeBasicAuth | merged
SSLCacheServerPath dir | - | functionality removed
SSLCacheServerPort integer | - | functionality removed
Apache-SSL 1.x compatibility:
SSLExportClientCertificates | SSLOptions +ExportCertData | merged
SSLCacheServerRunDir dir | - | functionality not supported
Sioux 1.x compatibility:
SSL_CertFile file | SSLCertificateFile file | renamed
SSL_KeyFile file | SSLCertificateKeyFile file | renamed
SSL_CipherSuite arg | SSLCipherSuite arg | renamed
SSL_X509VerifyDir arg | SSLCACertificatePath arg | renamed
SSL_Log file | SSLLogFile file | renamed
SSL_Connect flag | SSLEngine flag | renamed
SSL_ClientAuth arg | SSLVerifyClient arg | renamed
SSL_X509VerifyDepth arg | SSLVerifyDepth arg | renamed
SSL_FetchKeyPhraseFrom arg | - | not directly mappable; use SSLPassPhraseDialog
SSL_SessionDir dir | - | not directly mappable; use SSLSessionCache
SSL_Require expr | - | not directly mappable; use SSLRequire
SSL_CertFileType arg | - | functionality not supported
SSL_KeyFileType arg | - | functionality not supported
SSL_X509VerifyPolicy arg | - | functionality not supported
SSL_LogX509Attributes arg | - | functionality not supported
Stronghold 2.x compatibility:
StrongholdAccelerator dir | - | functionality not supported
StrongholdKey dir | - | functionality not supported
StrongholdLicenseFile dir | - | functionality not supported
SSLFlag flag | SSLEngine flag | renamed
SSLSessionLockFile file | SSLMutex file | renamed
SSLCipherList spec | SSLCipherSuite spec | renamed
RequireSSL | SSLRequireSSL | renamed
SSLErrorFile file | - | functionality not supported
SSLRoot dir | - | functionality not supported
SSL_CertificateLogDir dir | - | functionality not supported
AuthCertDir dir | - | functionality not supported
SSL_Group name | - | functionality not supported
SSLProxyMachineCertPath dir | - | functionality not supported
SSLProxyMachineCertFile file | - | functionality not supported
SSLProxyCACertificatePath dir | - | functionality not supported
SSLProxyCACertificateFile file | - | functionality not supported
SSLProxyVerifyDepth number | - | functionality not supported
SSLProxyCipherList spec | - | functionality not supported

Environment Variables

When you use ``SSLOptions +CompatEnvVars'' additional environment variables are generated. They all correspond to existing official mod_ssl variables. The currently implemented variable derivation is listed in Table 2.

Table 2: Environment Variable Derivation

Old Variable | mod_ssl Variable | Comment
SSL_PROTOCOL_VERSION | SSL_PROTOCOL | renamed
SSLEAY_VERSION | SSL_VERSION_LIBRARY | renamed
HTTPS_SECRETKEYSIZE | SSL_CIPHER_USEKEYSIZE | renamed
HTTPS_KEYSIZE | SSL_CIPHER_ALGKEYSIZE | renamed
HTTPS_CIPHER | SSL_CIPHER | renamed
HTTPS_EXPORT | SSL_CIPHER_EXPORT | renamed
SSL_SERVER_KEY_SIZE | SSL_CIPHER_ALGKEYSIZE | renamed
SSL_SERVER_CERTIFICATE | SSL_SERVER_CERT | renamed
SSL_SERVER_CERT_START | SSL_SERVER_V_START | renamed
SSL_SERVER_CERT_END | SSL_SERVER_V_END | renamed
SSL_SERVER_CERT_SERIAL | SSL_SERVER_M_SERIAL | renamed
SSL_SERVER_SIGNATURE_ALGORITHM | SSL_SERVER_A_SIG | renamed
SSL_SERVER_DN | SSL_SERVER_S_DN | renamed
SSL_SERVER_CN | SSL_SERVER_S_DN_CN | renamed
SSL_SERVER_EMAIL | SSL_SERVER_S_DN_Email | renamed
SSL_SERVER_O | SSL_SERVER_S_DN_O | renamed
SSL_SERVER_OU | SSL_SERVER_S_DN_OU | renamed
SSL_SERVER_C | SSL_SERVER_S_DN_C | renamed
SSL_SERVER_SP | SSL_SERVER_S_DN_SP | renamed
SSL_SERVER_L | SSL_SERVER_S_DN_L | renamed
SSL_SERVER_IDN | SSL_SERVER_I_DN | renamed
SSL_SERVER_ICN | SSL_SERVER_I_DN_CN | renamed
SSL_SERVER_IEMAIL | SSL_SERVER_I_DN_Email | renamed
SSL_SERVER_IO | SSL_SERVER_I_DN_O | renamed
SSL_SERVER_IOU | SSL_SERVER_I_DN_OU | renamed
SSL_SERVER_IC | SSL_SERVER_I_DN_C | renamed
SSL_SERVER_ISP | SSL_SERVER_I_DN_SP | renamed
SSL_SERVER_IL | SSL_SERVER_I_DN_L | renamed
SSL_CLIENT_CERTIFICATE | SSL_CLIENT_CERT | renamed
SSL_CLIENT_CERT_START | SSL_CLIENT_V_START | renamed
SSL_CLIENT_CERT_END | SSL_CLIENT_V_END | renamed
SSL_CLIENT_CERT_SERIAL | SSL_CLIENT_M_SERIAL | renamed
SSL_CLIENT_SIGNATURE_ALGORITHM | SSL_CLIENT_A_SIG | renamed
SSL_CLIENT_DN | SSL_CLIENT_S_DN | renamed
SSL_CLIENT_CN | SSL_CLIENT_S_DN_CN | renamed
SSL_CLIENT_EMAIL | SSL_CLIENT_S_DN_Email | renamed
SSL_CLIENT_O | SSL_CLIENT_S_DN_O | renamed
SSL_CLIENT_OU | SSL_CLIENT_S_DN_OU | renamed
SSL_CLIENT_C | SSL_CLIENT_S_DN_C | renamed
SSL_CLIENT_SP | SSL_CLIENT_S_DN_SP | renamed
SSL_CLIENT_L | SSL_CLIENT_S_DN_L | renamed
SSL_CLIENT_IDN | SSL_CLIENT_I_DN | renamed
SSL_CLIENT_ICN | SSL_CLIENT_I_DN_CN | renamed
SSL_CLIENT_IEMAIL | SSL_CLIENT_I_DN_Email | renamed
SSL_CLIENT_IO | SSL_CLIENT_I_DN_O | renamed
SSL_CLIENT_IOU | SSL_CLIENT_I_DN_OU | renamed
SSL_CLIENT_IC | SSL_CLIENT_I_DN_C | renamed
SSL_CLIENT_ISP | SSL_CLIENT_I_DN_SP | renamed
SSL_CLIENT_IL | SSL_CLIENT_I_DN_L | renamed
SSL_EXPORT | SSL_CIPHER_EXPORT | renamed
SSL_KEYSIZE | SSL_CIPHER_ALGKEYSIZE | renamed
SSL_SECKEYSIZE | SSL_CIPHER_USEKEYSIZE | renamed
SSL_SSLEAY_VERSION | SSL_VERSION_LIBRARY | renamed
SSL_STRONG_CRYPTO | - | Not supported by mod_ssl
SSL_SERVER_KEY_EXP | - | Not supported by mod_ssl
SSL_SERVER_KEY_ALGORITHM | - | Not supported by mod_ssl
SSL_SERVER_KEY_SIZE | - | Not supported by mod_ssl
SSL_SERVER_SESSIONDIR | - | Not supported by mod_ssl
SSL_SERVER_CERTIFICATELOGDIR | - | Not supported by mod_ssl
SSL_SERVER_CERTFILE | - | Not supported by mod_ssl
SSL_SERVER_KEYFILE | - | Not supported by mod_ssl
SSL_SERVER_KEYFILETYPE | - | Not supported by mod_ssl
SSL_CLIENT_KEY_EXP | - | Not supported by mod_ssl
SSL_CLIENT_KEY_ALGORITHM | - | Not supported by mod_ssl
SSL_CLIENT_KEY_SIZE | - | Not supported by mod_ssl

Custom Log Functions

When mod_ssl is built into Apache or at least loaded (under DSO situation) additional functions exist for the Custom Log Format of mod_log_config as documented in the Reference Chapter. Beside the ``%{varname}x'' eXtension format function which can be used to expand any variables provided by any module, an additional Cryptography ``%{name}c'' cryptography format function exists for backward compatibility. The currently implemented function calls are listed in Table 3.

Table 3: Custom Log Cryptography Function

Function Call | Description
%...{version}c | SSL protocol version
%...{cipher}c | SSL cipher
%...{subjectdn}c | Client Certificate Subject Distinguished Name
%...{issuerdn}c | Client Certificate Issuer Distinguished Name
%...{errcode}c | Certificate Verification Error (numerical)
%...{errstr}c | Certificate Verification Error (string)


SSL/TLS Strong Encryption: How-To - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > SSL/TLS

SSL/TLS Strong Encryption: How-To

The solution of this problem is trivial and is left as an exercise for the reader.

-- Standard textbook cookie

How to solve particular security constraints for an SSL-aware webserver is not always obvious because of the coherences between SSL, HTTP and Apache's way of processing requests. This chapter gives instructions on how to solve such typical situations. Treat it as a first step to find out the final solution, but always try to understand the stuff before you use it. Nothing is worse than using a security solution without knowing its restrictions and coherences.

Cipher Suites and Enforced Strong Security

  • SSLv2 only server
  • strong encryption only server
  • server gated cryptography
  • stronger per-directory requirements

How can I create a real SSLv2-only server?

The following creates an SSL server which speaks only the SSLv2 protocol and its ciphers.

httpd.conf

SSLProtocol -all +SSLv2
SSLCipherSuite SSLv2:+HIGH:+MEDIUM:+LOW:+EXP

How can I create an SSL server which accepts strong encryption only?

The following enables only the seven strongest ciphers:

httpd.conf

SSLProtocol all
SSLCipherSuite HIGH:MEDIUM

How can I create an SSL server which accepts strong encryption only, but allows export browsers to upgrade to stronger encryption?

This facility is called Server Gated Cryptography (SGC) and details you can find in the README.GlobalID document in the mod_ssl distribution. In short: The server has a Global ID server certificate, signed by a special CA certificate from Verisign which enables strong encryption in export browsers. This works as following: The browser connects with an export cipher, the server sends its Global ID certificate, the browser verifies it and subsequently upgrades the cipher suite before any HTTP communication takes place. The question now is: How can we allow this upgrade, but enforce strong encryption. Or in other words: Browser either have to initially connect with strong encryption or have to upgrade to strong encryption, but are not allowed to keep the export ciphers. The following does the trick:

httpd.conf

# allow all ciphers for the initial handshake,
# so export browsers can upgrade via SGC facility
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL

<Directory /usr/local/apache2/htdocs>
# but finally deny all browsers which haven't upgraded
SSLRequire %{SSL_CIPHER_USEKEYSIZE} >= 128
</Directory>

How can I create an SSL server which accepts all types of ciphers in general, but requires a strong ciphers for access to a particular URL?

Obviously you cannot just use a server-wide SSLCipherSuite which restricts the ciphers to the strong variants. But mod_ssl allows you to reconfigure the cipher suite in per-directory context and automatically forces a renegotiation of the SSL parameters to meet the new configuration. So, the solution is:

# be liberal in general
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL

<Location /strong/area>
# but https://hostname/strong/area/ and below
# requires strong ciphers
SSLCipherSuite HIGH:MEDIUM
</Location>

Client Authentication and Access Control

  • simple certificate-based client authentication
  • selective certificate-based client authentication
  • particular certificate-based client authentication
  • intranet vs. internet authentication

How can I authenticate clients based on certificates when I know all my clients?

When you know your user community (i.e. a closed user group situation), as it's the case for instance in an Intranet, you can use plain certificate authentication. All you have to do is to create client certificates signed by your own CA certificate ca.crt and then verify the clients against this certificate.

httpd.conf

# require a client certificate which has to be directly
# signed by our CA certificate in ca.crt
SSLVerifyClient require
SSLVerifyDepth 1
SSLCACertificateFile conf/ssl.crt/ca.crt

How can I authenticate my clients for a particular URL based on certificates but still allow arbitrary clients to access the remaining parts of the server?

For this we again use the per-directory reconfiguration feature of mod_ssl:

httpd.conf

SSLVerifyClient none
SSLCACertificateFile conf/ssl.crt/ca.crt

<Location /secure/area>
SSLVerifyClient require
SSLVerifyDepth 1
</Location>

How can I authenticate only particular clients for a some URLs based on certificates but still allow arbitrary clients to access the remaining parts of the server?

The key is to check for various ingredients of the client certificate. Usually this means to check the whole or part of the Distinguished Name (DN) of the Subject. For this two methods exists: The mod_auth based variant and the SSLRequire variant. The first method is good when the clients are of totally different type, i.e. when their DNs have no common fields (usually the organisation, etc.). In this case you've to establish a password database containing all clients. The second method is better when your clients are all part of a common hierarchy which is encoded into the DN. Then you can match them more easily.

The first method:

httpd.conf

SSLVerifyClient      none
<Directory /usr/local/apache2/htdocs/secure/area>

SSLVerifyClient      require
SSLVerifyDepth       5
SSLCACertificateFile conf/ssl.crt/ca.crt
SSLCACertificatePath conf/ssl.crt
SSLOptions           +FakeBasicAuth
SSLRequireSSL
AuthName             "Snake Oil Authentication"
AuthType             Basic
AuthUserFile         /usr/local/apache2/conf/httpd.passwd
require              valid-user
</Directory>

httpd.passwd

/C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
/C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
/C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA

The second method:

httpd.conf

SSLVerifyClient      none
<Directory /usr/local/apache2/htdocs/secure/area>

  SSLVerifyClient      require
  SSLVerifyDepth       5
  SSLCACertificateFile conf/ssl.crt/ca.crt
  SSLCACertificatePath conf/ssl.crt
  SSLOptions           +FakeBasicAuth
  SSLRequireSSL
  SSLRequire       %{SSL_CLIENT_S_DN_O}  eq "Snake Oil, Ltd." \
               and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}
</Directory>

How can I require HTTPS with strong ciphers and either basic authentication or client certificates for access to a subarea on the Intranet website for clients coming from the Internet but still allow plain HTTP access for clients on the Intranet?

Let us assume the Intranet can be distinguished through the IP network 192.160.1.0/24 and the subarea on the Intranet website has the URL /subarea. Then configure the following outside your HTTPS virtual host (so it applies to both HTTPS and HTTP):

httpd.conf

SSLCACertificateFile conf/ssl.crt/company-ca.crt

<Directory /usr/local/apache2/htdocs>
#   Outside the subarea only Intranet access is granted
Order                deny,allow
Deny                 from all
Allow                from 192.168.1.0/24
</Directory>

<Directory /usr/local/apache2/htdocs/subarea>
#   Inside the subarea any Intranet access is allowed
#   but from the Internet only HTTPS + Strong-Cipher + Password
#   or the alternative HTTPS + Strong-Cipher + Client-Certificate

#   If HTTPS is used, make sure a strong cipher is used.
#   Additionally allow client certs as alternative to basic auth.
SSLVerifyClient      optional
SSLVerifyDepth       1
SSLOptions           +FakeBasicAuth +StrictRequire
SSLRequire           %{SSL_CIPHER_USEKEYSIZE} >= 128

#   Force clients from the Internet to use HTTPS
RewriteEngine        on
RewriteCond          %{REMOTE_ADDR} !^192\.168\.1\.[0-9]+$
RewriteCond          %{HTTPS} !=on
RewriteRule          .* - [F]

#   Allow Network Access and/or Basic Auth
Satisfy              any

#   Network Access Control
Order                deny,allow
Deny                 from all
Allow                192.168.1.0/24

#   HTTP Basic Authentication
AuthType             basic
AuthName             "Protected Intranet Area"
AuthUserFile         conf/protected.passwd
Require              valid-user
</Directory>


SSL/TLS Strong Encryption: FAQ - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > SSL/TLS

SSL/TLS Strong Encryption: FAQ

The wise man doesn't give the right answers, he poses the right questions.

-- Claude Levi-Strauss

This chapter is a collection of frequently asked questions (FAQ) and corresponding answers following the popular USENET tradition. Most of these questions occurred on the Newsgroup comp.infosystems.www.servers.unix or the mod_ssl Support Mailing List modssl-users@modssl.org. They are collected at this place to avoid answering the same questions over and over.

Please read this chapter at least once when installing mod_ssl or at least search for your problem here before submitting a problem report to the author.

About The Module

  • What is the history of mod_ssl?
  • mod_ssl and Year 2000?
  • mod_ssl and Wassenaar Arrangement?

What is the history of mod_ssl?

The mod_ssl v1 package was initially created in April 1998 by Ralf S. Engelschall via porting Ben Laurie's Apache-SSL 1.17 source patches for Apache 1.2.6 to Apache 1.3b6. Because of conflicts with Ben Laurie's development cycle it then was re-assembled from scratch for Apache 1.3.0 by merging the old mod_ssl 1.x with the newer Apache-SSL 1.18. From this point on mod_ssl lived its own life as mod_ssl v2. The first publicly released version was mod_ssl 2.0.0 from August 10th, 1998. As of this writing (August 1999) the current mod_ssl version is 2.4.0.

After one year of very active development with over 1000 working hours and over 40 releases mod_ssl reached its current state. The result is an already very clean source base implementing a very rich functionality. The code size increased by a factor of 4 to currently a total of over 10.000 lines of ANSI C consisting of approx. 70% code and 30% code documentation. From the original Apache-SSL code currently approx. 5% is remaining only.

After the US export restrictions for cryptographic software were opened, mod_ssl was integrated into the code base of Apache V2 in 2001.

Is mod_ssl Year 2000 compliant?

Yes, mod_ssl is Year 2000 compliant.

Because first mod_ssl internally never stores years as two digits. Instead it always uses the ANSI C & POSIX numerical data type time_t type, which on almost all Unix platforms at the moment is a signed long (usually 32-bits) representing seconds since epoch of January 1st, 1970, 00:00 UTC. This signed value overflows in early January 2038 and not in the year 2000. Second, date and time presentations (for instance the variable ``%{TIME_YEAR}'') are done with full year value instead of abbreviating to two digits.

Additionally according to a Year 2000 statement from the Apache Group, the Apache webserver is Year 2000 compliant, too. But whether OpenSSL or the underlying Operating System (either a Unix or Win32 platform) is Year 2000 compliant is a different question which cannot be answered here.

What about mod_ssl and the Wassenaar Arrangement?

First, let us explain what Wassenaar and its Arrangement on Export Controls for Conventional Arms and Dual-Use Goods and Technologies is: This is a international regime, established 1995, to control trade in conventional arms and dual-use goods and technology. It replaced the previous CoCom regime. 33 countries are signatories: Argentina, Australia, Austria, Belgium, Bulgaria, Canada, Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan, Luxembourg, the Netherlands, New Zealand, Norway, Poland, Portugal, Republic of Korea, Romania, Russian Federation, Slovak Republic, Spain, Sweden, Switzerland, Turkey, Ukraine, the United Kingdom and the United States. For more details look at http://www.wassenaar.org/.

In short: The aim of the Wassenaar Arrangement is to prevent the build up of military capabilities that threaten regional and international security and stability. The Wassenaar Arrangement controls the export of cryptography as a dual-use good, i.e., one that has both military and civilian applications. However, the Wassenaar Arrangement also provides an exemption from export controls for mass-market software and free software.

In the current Wassenaar List of Dual Use Goods and Technologies And Munitions, under GENERAL SOFTWARE NOTE (GSN) it says The Lists do not control "software" which is either: 1. [...] 2. "in the public domain". And under DEFINITIONS OF TERMS USED IN THESE LISTS one can find the definition: In the public domain": This means "technology" or "software" which has been made available without restrictions upon its further dissemination. N.B. Copyright restrictions do not remove "technology" or "software" from being "in the public domain".

So, both mod_ssl and OpenSSL are in the public domain for the purposes of the Wassenaar Agreement and its List of Dual Use Goods and Technologies And Munitions List.

So, mod_ssl and OpenSSL are not affected by the Wassenaar Agreement.

About Installation

  • Core dumps for HTTPS requests?
  • Permission problem on SSLMutex
  • Shared memory and process size?
  • PRNG and not enough entropy?

When I access my website the first time via HTTPS I get a core dump?

There can be a lot of reasons why a core dump can occur, of course. Ranging from buggy third-party modules, over buggy vendor libraries up to a buggy mod_ssl version. But the above situation is often caused by old or broken vendor DBM libraries. To solve it either build mod_ssl with the built-in SDBM library (specify --enable-rule=SSL_SDBM at the APACI command line) or switch from SSLSessionCache dbm: to the newer SSLSessionCache shm:'' variant (after you have rebuilt Apache with MM, of course).

When I startup Apache I get permission errors related to SSLMutex?

When you receive entries like ``mod_ssl: Child could not open SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows) [...] System: Permission denied (errno: 13)'' this is usually caused by to restrictive permissions on the parent directories. Make sure that all parent directories (here /opt, /opt/apache and /opt/apache/logs) have the x-bit set at least for the UID under which Apache's children are running (see the User directive of Apache).

When I use the MM library and the shared memory cache each process grows 1.5MB according to `top' although I specified 512000 as the cache size?

The additional 1MB are caused by the global shared memory pool Apache allocates for all modules and which is not used by mod_ssl for various reasons. So the actually allocated shared memory is always 1MB more than what you specify on SSLSessionCache. But don't be confused by the display of `top': although is indicates that each process grow, this is not reality, of course. Instead the additional memory consumption is shared by all processes, i.e. the 1.5MB are allocated only once per Apache instance and not once per Apache server process.

When I fire up the server, mod_ssl stops with the error "Failed to generate temporary 512 bit RSA private key", why?

Cryptographic software needs a source of unpredictable data to work correctly. Many open source operating systems provide a "randomness device" that serves this purpose (usually named /dev/random). On other systems, applications have to seed the OpenSSL Pseudo Random Number Generator (PRNG) manually with appropriate data before generating keys or performing public key encryption. As of version 0.9.5, the OpenSSL functions that need randomness report an error if the PRNG has not been seeded with at least 128 bits of randomness. So mod_ssl has to provide enough entropy to the PRNG to work correctly. For this one has to use the SSLRandomSeed directives.

About Configuration

  • HTTP and HTTPS with a single server?
  • Where is the HTTPS port?
  • How to test HTTPS manually?
  • Why does my connection hang?
  • Why do I get connection refused?
  • Why are the SSL_XXX variables missing?
  • How to switch with relative hyperlinks?

Is it possible to provide HTTP and HTTPS with a single server?

Yes, HTTP and HTTPS use different server ports, so there is no direct conflict between them. Either run two separate server instances (one binds to port 80, the other to port 443) or even use Apache's elegant virtual hosting facility where you can easily create two virtual servers which Apache dispatches: one responding to port 80 and speaking HTTP and one responding to port 443 speaking HTTPS.

I know that HTTP is on port 80, but where is HTTPS?

You can run HTTPS on any port, but the standards specify port 443, which is where any HTTPS compliant browser will look by default. You can force your browser to look on a different port by specifying it in the URL like this (for port 666): https://secure.server.dom:666/

How can I speak HTTPS manually for testing purposes?

While you usually just use

$ telnet localhost 80
GET / HTTP/1.0

for simple testing the HTTP protocol of Apache, it's not so easy for HTTPS because of the SSL protocol between TCP and HTTP. But with the help of OpenSSL's s_client command you can do a similar check even for HTTPS:

$ openssl s_client -connect localhost:443 -state -debug
GET / HTTP/1.0

Before the actual HTTP response you receive detailed information about the SSL handshake. For a more general command line client which directly understands both the HTTP and HTTPS scheme, can perform GET and POST methods, can use a proxy, supports byte ranges, etc. you should have a look at nifty cURL tool. With it you can directly check if your Apache is running fine on Port 80 and 443 as following:

$ curl http://localhost/
$ curl https://localhost/

Why does the connection hang when I connect to my SSL-aware Apache server?

Because you connected with HTTP to the HTTPS port, i.e. you used an URL of the form ``http://'' instead of ``https://''. This also happens the other way round when you connect via HTTPS to a HTTP port, i.e. when you try to use ``https://'' on a server that doesn't support SSL (on this port). Make sure you are connecting to a virtual server that supports SSL, which is probably the IP associated with your hostname, not localhost (127.0.0.1).

Why do I get ``Connection Refused'' messages when trying to access my freshly installed Apache+mod_ssl server via HTTPS?

There can be various reasons. Some of the common mistakes is that people start Apache with just ``apachectl start'' (or ``httpd'') instead of ``apachectl startssl'' (or ``httpd -DSSL''. Or you're configuration is not correct. At least make sure that your Listen directives match your <VirtualHost> directives. And if all fails, please do yourself a favor and start over with the default configuration mod_ssl provides you.

In my CGI programs and SSI scripts the various documented SSL_XXX variables do not exist. Why?

Just make sure you have ``SSLOptions +StdEnvVars'' enabled for the context of your CGI/SSI requests.

How can I use relative hyperlinks to switch between HTTP and HTTPS?

Usually you have to use fully-qualified hyperlinks because you have to change the URL scheme. But with the help of some URL manipulations through mod_rewrite you can achieve the same effect while you still can use relative URLs:

RewriteEngine on
RewriteRule ^/(.*):SSL$ https://%{SERVER_NAME}/$1 [R,L]
RewriteRule ^/(.*):NOSSL$ http://%{SERVER_NAME}/$1 [R,L]

This rewrite ruleset lets you use hyperlinks of the form <a href="document.html:SSL">

About Certificates

  • What are Keys, CSRs and Certs?
  • Difference on startup?
  • How to create a real cert?
  • How to create my own CA?
  • How to change a pass phrase?
  • How to remove a pass phrase?
  • How to verify a key/cert pair?
  • Bad Certificate Error?
  • Why does a 2048-bit key not work?
  • Why is client auth broken?
  • How to convert from PEM to DER?
  • Verisign and the magic getca program?
  • Global IDs or SGC?
  • Global IDs and Cert Chain?

What are RSA Private Keys, CSRs and Certificates?

The RSA private key file is a digital file that you can use to decrypt messages sent to you. It has a public component which you distribute (via your Certificate file) which allows people to encrypt those messages to you. A Certificate Signing Request (CSR) is a digital file which contains your public key and your name. You send the CSR to a Certifying Authority (CA) to be converted into a real Certificate. A Certificate contains your RSA public key, your name, the name of the CA, and is digitally signed by your CA. Browsers that know the CA can verify the signature on that Certificate, thereby obtaining your RSA public key. That enables them to send messages which only you can decrypt. See the Introduction chapter for a general description of the SSL protocol.

Seems like there is a difference on startup between the original Apache and an SSL-aware Apache?

Yes, in general, starting Apache with a built-in mod_ssl is just like starting an unencumbered Apache, except for the fact that when you have a pass phrase on your SSL private key file. Then a startup dialog pops up asking you to enter the pass phrase.

To type in the pass phrase manually when starting the server can be problematic, for instance when starting the server from the system boot scripts. As an alternative to this situation you can follow the steps below under ``How can I get rid of the pass-phrase dialog at Apache startup time?''.

Ok, I've got my server installed and want to create a real SSL server Certificate for it. How do I do it?

Here is a step-by-step description:

  1. Make sure OpenSSL is really installed and in your PATH. But some commands even work ok when you just run the ``openssl'' program from within the OpenSSL source tree as ``./apps/openssl''.

  2. Create a RSA private key for your Apache server (will be Triple-DES encrypted and PEM formatted):

    $ openssl genrsa -des3 -out server.key 1024

    Please backup this server.key file and remember the pass-phrase you had to enter at a secure location. You can see the details of this RSA private key via the command:

    $ openssl rsa -noout -text -in server.key

    And you could create a decrypted PEM version (not recommended) of this RSA private key via:

    $ openssl rsa -in server.key -out server.key.unsecure

  3. Create a Certificate Signing Request (CSR) with the server RSA private key (output will be PEM formatted):

    $ openssl req -new -key server.key -out server.csr

    Make sure you enter the FQDN ("Fully Qualified Domain Name") of the server when OpenSSL prompts you for the "CommonName", i.e. when you generate a CSR for a website which will be later accessed via https://www.foo.dom/, enter "www.foo.dom" here. You can see the details of this CSR via the command

    $ openssl req -noout -text -in server.csr

  4. You now have to send this Certificate Signing Request (CSR) to a Certifying Authority (CA) for signing. The result is then a real Certificate which can be used for Apache. Here you have two options: First you can let the CSR sign by a commercial CA like Verisign or Thawte. Then you usually have to post the CSR into a web form, pay for the signing and await the signed Certificate you then can store into a server.crt file. For more information about commercial CAs have a look at the following locations:

    1. Verisign
      http://digitalid.verisign.com/server/apacheNotice.htm
    2. Thawte Consulting
      http://www.thawte.com/certs/server/request.html
    3. CertiSign Certificadora Digital Ltda.
      http://www.certisign.com.br
    4. IKS GmbH
      http://www.iks-jena.de/produkte/ca/
    5. Uptime Commerce Ltd.
      http://www.uptimecommerce.com
    6. BelSign NV/SA
      http://www.belsign.be
    Second you can use your own CA and now have to sign the CSR yourself by this CA. Read the next answer in this FAQ on how to sign a CSR with your CA yourself. You can see the details of the received Certificate via the command:

    $ openssl x509 -noout -text -in server.crt
  5. Now you have two files: server.key and server.crt. These now can be used as following inside your Apache's httpd.conf file:
           SSLCertificateFile    /path/to/this/server.crt
       SSLCertificateKeyFile /path/to/this/server.key
    The server.csr file is no longer needed.

How can I create and use my own Certificate Authority (CA)?

The short answer is to use the CA.sh or CA.pl script provided by OpenSSL. The long and manual answer is this:

  1. Create a RSA private key for your CA (will be Triple-DES encrypted and PEM formatted):

    $ openssl genrsa -des3 -out ca.key 1024

    Please backup this ca.key file and remember the pass-phrase you currently entered at a secure location. You can see the details of this RSA private key via the command

    $ openssl rsa -noout -text -in ca.key

    And you can create a decrypted PEM version (not recommended) of this private key via:

    $ openssl rsa -in ca.key -out ca.key.unsecure

  2. Create a self-signed CA Certificate (X509 structure) with the RSA key of the CA (output will be PEM formatted):

    $ openssl req -new -x509 -days 365 -key ca.key -out ca.crt

    You can see the details of this Certificate via the command:

    $ openssl x509 -noout -text -in ca.crt

  3. Prepare a script for signing which is needed because the ``openssl ca'' command has some strange requirements and the default OpenSSL config doesn't allow one easily to use ``openssl ca'' directly. So a script named sign.sh is distributed with the mod_ssl distribution (subdir pkg.contrib/). Use this script for signing.
  4. Now you can use this CA to sign server CSR's in order to create real SSL Certificates for use inside an Apache webserver (assuming you already have a server.csr at hand):

    $ ./sign.sh server.csr

    This signs the server CSR and results in a server.crt file.

How can I change the pass-phrase on my private key file?

You simply have to read it with the old pass-phrase and write it again by specifying the new pass-phrase. You can accomplish this with the following commands:

$ openssl rsa -des3 -in server.key -out server.key.new
$ mv server.key.new server.key

Here you're asked two times for a PEM pass-phrase. At the first prompt enter the old pass-phrase and at the second prompt enter the new pass-phrase.

How can I get rid of the pass-phrase dialog at Apache startup time?

The reason why this dialog pops up at startup and every re-start is that the RSA private key inside your server.key file is stored in encrypted format for security reasons. The pass-phrase is needed to be able to read and parse this file. When you can be sure that your server is secure enough you perform two steps:

  1. Remove the encryption from the RSA private key (while preserving the original file):

    $ cp server.key server.key.org
    $ openssl rsa -in server.key.org -out server.key

  2. Make sure the server.key file is now only readable by root:

    $ chmod 400 server.key

Now server.key will contain an unencrypted copy of the key. If you point your server at this file it will not prompt you for a pass-phrase. HOWEVER, if anyone gets this key they will be able to impersonate you on the net. PLEASE make sure that the permissions on that file are really such that only root or the web server user can read it (preferably get your web server to start as root but run as another server, and have the key readable only by root).

As an alternative approach you can use the ``SSLPassPhraseDialog exec:/path/to/program'' facility. But keep in mind that this is neither more nor less secure, of course.

How do I verify that a private key matches its Certificate?

The private key contains a series of numbers. Two of those numbers form the "public key", the others are part of your "private key". The "public key" bits are also embedded in your Certificate (we get them from your CSR). To check that the public key in your cert matches the public portion of your private key, you need to view the cert and the key and compare the numbers. To view the Certificate and the key run the commands:

$ openssl x509 -noout -text -in server.crt
$ openssl rsa -noout -text -in server.key

The `modulus' and the `public exponent' portions in the key and the Certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach:

$ openssl x509 -noout -modulus -in server.crt | openssl md5
$ openssl rsa -noout -modulus -in server.key | openssl md5

And then compare these really shorter numbers. With overwhelming probability they will differ if the keys are different. BTW, if I want to check to which key or certificate a particular CSR belongs you can compute

$ openssl req -noout -modulus -in server.csr | openssl md5

What does it mean when my connections fail with an "alert bad certificate" error?

Usually when you see errors like OpenSSL: error:14094412: SSL routines:SSL3_READ_BYTES:sslv3 alert bad certificate in the SSL logfile, this means that the browser was unable to handle the server certificate/private-key which perhaps contain a RSA-key not equal to 1024 bits. For instance Netscape Navigator 3.x is one of those browsers.

Why does my 2048-bit private key not work?

The private key sizes for SSL must be either 512 or 1024 for compatibility with certain web browsers. A keysize of 1024 bits is recommended because keys larger than 1024 bits are incompatible with some versions of Netscape Navigator and Microsoft Internet Explorer, and with other browsers that use RSA's BSAFE cryptography toolkit.

Why is client authentication broken after upgrading from SSLeay version 0.8 to 0.9?

The CA certificates under the path you configured with SSLCACertificatePath are found by SSLeay through hash symlinks. These hash values are generated by the `openssl x509 -noout -hash' command. But the algorithm used to calculate the hash for a certificate has changed between SSLeay 0.8 and 0.9. So you have to remove all old hash symlinks and re-create new ones after upgrading. Use the Makefile mod_ssl placed into this directory.

How can I convert a certificate from PEM to DER format?

The default certificate format for SSLeay/OpenSSL is PEM, which actually is Base64 encoded DER with header and footer lines. For some applications (e.g. Microsoft Internet Explorer) you need the certificate in plain DER format. You can convert a PEM file cert.pem into the corresponding DER file cert.der with the following command: $ openssl x509 -in cert.pem -out cert.der -outform DER

I try to install a Verisign certificate. Why can't I find neither the getca nor getverisign programs Verisign mentions?

This is because Verisign has never provided specific instructions for Apache+mod_ssl. Rather they tell you what you should do if you were using C2Net's Stronghold (a commercial Apache based server with SSL support). The only thing you have to do is to save the certificate into a file and give the name of that file to the SSLCertificateFile directive. Remember that you need to give the key file in as well (see SSLCertificateKeyFile directive). For a better CA-related overview on SSL certificate fiddling you can look at Thawte's mod_ssl instructions.

Can I use the Server Gated Cryptography (SGC) facility (aka Verisign Global ID) also with mod_ssl?

Yes, mod_ssl since version 2.1 supports the SGC facility. You don't have to configure anything special for this, just use a Global ID as your server certificate. The step up of the clients are then automatically handled by mod_ssl under run-time. For details please read the README.GlobalID document in the mod_ssl distribution.

After I have installed my new Verisign Global ID server certificate, the browsers complain that they cannot verify the server certificate?

That is because Verisign uses an intermediate CA certificate between the root CA certificate (which is installed in the browsers) and the server certificate (which you installed in the server). You should have received this additional CA certificate from Verisign. If not, complain to them. Then configure this certificate with the SSLCertificateChainFile directive in the server. This makes sure the intermediate CA certificate is send to the browser and this way fills the gap in the certificate chain.

About SSL Protocol

  • Random SSL errors under heavy load?
  • Why has the server a higher load?
  • Why are connections horribly slow?
  • Which ciphers are supported?
  • How to use Anonymous-DH ciphers
  • Why do I get 'no shared ciphers'?
  • HTTPS and name-based vhosts
  • Why is it not possible to use Name-Based Virtual Hosting to identify different SSL virtual hosts?
  • The lock icon in Netscape locks very late
  • Why do I get I/O errors with MSIE clients?
  • Why do I get I/O errors with NS clients?

Why do I get lots of random SSL protocol errors under heavy server load?

There can be a number of reasons for this, but the main one is problems with the SSL session Cache specified by the SSLSessionCache directive. The DBM session cache is most likely the source of the problem, so trying the SHM session cache or no cache at all may help.

Why has my webserver a higher load now that I run SSL there?

Because SSL uses strong cryptographic encryption and this needs a lot of number crunching. And because when you request a webpage via HTTPS even the images are transferred encrypted. So, when you have a lot of HTTPS traffic the load increases.

Often HTTPS connections to my server require up to 30 seconds for establishing the connection, although sometimes it works faster?

Usually this is caused by using a /dev/random device for SSLRandomSeed which is blocking in read(2) calls if not enough entropy is available. Read more about this problem in the reference chapter under SSLRandomSeed.

What SSL Ciphers are supported by mod_ssl?

Usually just all SSL ciphers which are supported by the version of OpenSSL in use (can depend on the way you built OpenSSL). Typically this at least includes the following:

  1. RC4 with MD5
  2. RC4 with MD5 (export version restricted to 40-bit key)
  3. RC2 with MD5
  4. RC2 with MD5 (export version restricted to 40-bit key)
  5. IDEA with MD5
  6. DES with MD5
  7. Triple-DES with MD5

To determine the actual list of supported ciphers you can run the following command:

$ openssl ciphers -v

I want to use Anonymous Diffie-Hellman (ADH) ciphers, but I always get ``no shared cipher'' errors?

In order to use Anonymous Diffie-Hellman (ADH) ciphers, it is not enough to just put ``ADH'' into your SSLCipherSuite. Additionally you have to build OpenSSL with ``-DSSL_ALLOW_ADH''. Because per default OpenSSL does not allow ADH ciphers for security reasons. So if you are actually enabling these ciphers make sure you are informed about the side-effects.

I always just get a 'no shared ciphers' error if I try to connect to my freshly installed server?

Either you have messed up your SSLCipherSuite directive (compare it with the pre-configured example in httpd.conf-dist) or you have chosen the DSA/DH algorithms instead of RSA when you generated your private key and ignored or overlooked the warnings. If you have chosen DSA/DH, then your server no longer speaks RSA-based SSL ciphers (at least not until you also configure an additional RSA-based certificate/key pair). But current browsers like NS or IE only speak RSA ciphers. The result is the "no shared ciphers" error. To fix this, regenerate your server certificate/key pair and this time choose the RSA algorithm.

Why can't I use SSL with name-based/non-IP-based virtual hosts?

The reason is very technical. Actually it's some sort of a chicken and egg problem: The SSL protocol layer stays below the HTTP protocol layer and encapsulates HTTP. When an SSL connection (HTTPS) is established Apache/mod_ssl has to negotiate the SSL protocol parameters with the client. For this mod_ssl has to consult the configuration of the virtual server (for instance it has to look for the cipher suite, the server certificate, etc.). But in order to dispatch to the correct virtual server Apache has to know the Host HTTP header field. For this the HTTP request header has to be read. This cannot be done before the SSL handshake is finished. But the information is already needed at the SSL handshake phase. Bingo!

Why is it not possible to use Name-Based Virtual Hosting to identify different SSL virtual hosts?

Name-Based Virtual Hosting is a very popular method of identifying different virtual hosts. It allows you to use the same IP address and the same port number for many different sites. When people move on to SSL, it seems natural to assume that the same method can be used to have lots of different SSL virtual hosts on the same server.

It comes as rather a shock to learn that it is impossible.

The reason is that the SSL protocol is a separate layer which encapsulates the HTTP protocol. So the problem is that the SSL session is a separate transaction that takes place before the HTTP session even starts. Therefore all the server receives is an SSL request on IP address X and port Y (usually 443). Since the SSL request does not contain any Host: field, the server has no way to decide which SSL virtual host to use. Usually, it will just use the first one it finds that matches the port and IP address.

You can, of course, use Name-Based Virtual Hosting to identify many non-SSL virtual hosts (all on port 80, for example) and then you can have no more than 1 SSL virtual host (on port 443). But if you do this, you must make sure to put the non-SSL port number on the NameVirtualHost directive, e.g.

NameVirtualHost 192.168.1.1:80

Other workaround solutions are:

Use separate IP addresses for different SSL hosts. Use different port numbers for different SSL hosts.

When I use Basic Authentication over HTTPS the lock icon in Netscape browsers still shows the unlocked state when the dialog pops up. Does this mean the username/password is still transmitted unencrypted?

No, the username/password is already transmitted encrypted. The icon in Netscape browsers is just not really synchronized with the SSL/TLS layer (it toggles to the locked state when the first part of the actual webpage data is transferred which is not quite correct) and this way confuses people. The Basic Authentication facility is part of the HTTP layer and this layer is above the SSL/TLS layer in HTTPS. And before any HTTP data communication takes place in HTTPS the SSL/TLS layer has already done the handshake phase and switched to encrypted communication. So, don't get confused by this icon.

When I connect via HTTPS to an Apache+mod_ssl+OpenSSL server with Microsoft Internet Explorer (MSIE) I get various I/O errors. What is the reason?

The first reason is that the SSL implementation in some MSIE versions has some subtle bugs related to the HTTP keep-alive facility and the SSL close notify alerts on socket connection close. Additionally the interaction between SSL and HTTP/1.1 features are problematic with some MSIE versions, too. You've to work-around these problems by forcing Apache+mod_ssl+OpenSSL to not use HTTP/1.1, keep-alive connections or sending the SSL close notify messages to MSIE clients. This can be done by using the following directive in your SSL-aware virtual host section:

SetEnvIf User-Agent ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0

Additionally it is known some MSIE versions have also problems with particular ciphers. Unfortunately one cannot workaround these bugs only for those MSIE particular clients, because the ciphers are already used in the SSL handshake phase. So a MSIE-specific SetEnvIf doesn't work to solve these problems. Instead one has to do more drastic adjustments to the global parameters. But before you decide to do this, make sure your clients really have problems. If not, do not do this, because it affects all(!) your clients, i.e., also your non-MSIE clients.

The next problem is that 56bit export versions of MSIE 5.x browsers have a broken SSLv3 implementation which badly interacts with OpenSSL versions greater than 0.9.4. You can either accept this and force your clients to upgrade their browsers, or you downgrade to OpenSSL 0.9.4 (hmmm), or you can decide to workaround it by accepting the drawback that your workaround will horribly affect also other browsers:

SSLProtocol all -SSLv3

This completely disables the SSLv3 protocol and lets those browsers work. But usually this is an even less acceptable workaround. A more reasonable workaround is to address the problem more closely and disable only the ciphers which cause trouble.

SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP

This also lets the broken MSIE versions work, but only removes the newer 56bit TLS ciphers.

Another problem with MSIE 5.x clients is that they refuse to connect to URLs of the form https://12.34.56.78/ (IP-addresses are used instead of the hostname), if the server is using the Server Gated Cryptography (SGC) facility. This can only be avoided by using the fully qualified domain name (FQDN) of the website in hyperlinks instead, because MSIE 5.x has an error in the way it handles the SGC negotiation.

And finally there are versions of MSIE which seem to require that an SSL session can be reused (a totally non standard-conforming behaviour, of course). Connection with those MSIE versions only work if a SSL session cache is used. So, as a work-around, make sure you are using a session cache (see SSLSessionCache directive).

When I connect via HTTPS to an Apache+mod_ssl server with Netscape Navigator I get I/O errors and the message "Netscape has encountered bad data from the server" What's the reason?

The problem usually is that you had created a new server certificate with the same DN, but you had told your browser to accept forever the old server certificate. Once you clear the entry in your browser for the old certificate, everything usually will work fine. Netscape's SSL implementation is correct, so when you encounter I/O errors with Netscape Navigator it is most of the time caused by the configured certificates.

About Support

  • Resources in case of problems?
  • Support in case of problems?
  • How to write a problem report?
  • I got a core dump, can you help me?
  • How to get a backtrace?

What information resources are available in case of mod_ssl problems?

The following information resources are available. In case of problems you should search here first.

Answers in the User Manual's F.A.Q. List (this)
http://httpd.apache.org/docs-2.0/ssl/ssl_faq.html
First look inside the F.A.Q. (this text), perhaps your problem is such popular that it was already answered a lot of times in the past.
Postings from the modssl-users Support Mailing List http://www.modssl.org/support/
Second search for your problem in one of the existing archives of the modssl-users mailing list. Perhaps your problem popped up at least once for another user, too.

What support contacts are available in case of mod_ssl problems?

The following lists all support possibilities for mod_ssl, in order of preference, i.e. start in this order and do not pick the support possibility you just like most, please.

  1. Write a Problem Report into the Bug Database
    http://www.modssl.org/support/bugdb/
    This is the preferred way of submitting your problem report, because this way it gets filed into the bug database (it cannot be lost) and send to the modssl-users mailing list (others see the current problems and learn from answers).
  2. Write a Problem Report to the modssl-users Support Mailing List
    modssl-users@modssl.org
    This is the second way of submitting your problem report. You have to subscribe to the list first, but then you can easily discuss your problem with both the author and the whole mod_ssl user community.

What information and details should I provide when writing a bug report?

You have to at least always provide the following information:

Apache and OpenSSL version information
The Apache version can be determined by running ``httpd -v''. The OpenSSL version can be determined by running ``openssl version''. Alternatively when you have Lynx installed you can run the command ``lynx -mime_header http://localhost/ | grep Server'' to determine all information in a single step.
The details on how you built and installed Apache+mod_ssl+OpenSSL
For this you can provide a logfile of your terminal session which shows the configuration and install steps. Alternatively you can at least provide the configure command line you used.
In case of core dumps please include a Backtrace
In case your Apache+mod_ssl+OpenSSL should really dump core please attach a stack-frame ``backtrace'' (see the next question on how to get it). Without this information the reason for your core dump cannot be found. So you have to provide the backtrace, please.
A detailed description of your problem
Don't laugh, I'm totally serious. I already got a lot of problem reports where the people not really said what's the actual problem is. So, in your own interest (you want the problem be solved, don't you?) include as much details as possible, please. But start with the essentials first, of course.

I got a core dump, can you help me?

In general no, at least not unless you provide more details about the code location where Apache dumped core. What is usually always required in order to help you is a backtrace (see next question). Without this information it is mostly impossible to find the problem and help you in fixing it.

Ok, I got a core dump but how do I get a backtrace to find out the reason for it?

Follow the following steps:

  1. Make sure you have debugging symbols available in at least Apache. On platforms where you use GCC/GDB you have to build Apache+mod_ssl with ``OPTIM="-g -ggdb3"'' to achieve this. On other platforms at least ``OPTIM="-g"'' is needed.
  2. Startup the server and try to produce the core-dump. For this you perhaps want to use a directive like ``CoreDumpDirectory /tmp'' to make sure that the core-dump file can be written. You then should get a /tmp/core or /tmp/httpd.core file. When you don't get this, try to run your server under an UID != 0 (root), because most "current" kernels do not allow a process to dump core after it has done a setuid() (unless it does an exec()) for security reasons (there can be privileged information left over in memory). Additionally you can run ``/path/to/httpd -X'' manually to force Apache to not fork.
  3. Analyze the core-dump. For this run gdb /path/to/httpd /tmp/httpd.core or a similar command has to run. In GDB you then just have to enter the bt command and, voila, you get the backtrace. For other debuggers consult your local debugger manual. Send this backtrace to the author.


How-To / チュートリアル - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

How-To / チュートリアル

How-To / チュートリアル

認証

認証とは、誰かが自分は誰であるかを名乗っているものを検証する 処理のことです。承認とは、誰かが望みの場所に辿り着けたり、 望みの情報を手に入れたりすることを許可する処理のことです。

参照: 認証、承認、アクセス制御

CGI による動的コンテンツ

CGI (Common Gateway Interface) はウェブサーバが外部のコンテンツ 生成プログラムとどのように相互動作をするかを定義します。 その外部プログラムは通常 CGI プログラムや CGI スクリプトと呼ばれます。 CGI はウェブサイトに動的なコンテンツを追加するための、 一番単純でよく使われている方法です。この文書は Apache ウェブサーバに CGI を設定し、CGI プログラムを書き始めるためのイントロダクションです。

参照: CGI: 動的コンテンツ

.htaccess ファイル

.htaccess ファイルはディレクトリ毎に設定を変更するための 方法を提供します。設定ディレクティブが書かれたファイルが、あるドキュメント ディレクトリに置かれると、ディレクティブはそのディレクトリと すべてのサブディレクトリに適用されます。

参照: .htaccess ファイル

Server Side Includes イントロダクション

SSI (Server Side Includes) は HTML ページ中に書かれるディレクティブで、 ページが送られる時にサーバにより評価されます。これにより、ページ全体を CGI プログラムで生成したり、他の動的な技術を使うことなく、既存の HTML ページに動的に生成された内容を付加することができます。

参照: Server Side Includes (SSI)

ユーザ毎のウェブディレクトリ

複数ユーザの存在するシステムでは、それぞれのユーザは UserDir ディレクティブを使うことによって ホームディレクトリ上にウェブサイトを作成することができます。 URL http://example.com/~username/ を訪れた人は ユーザ "username" のホームディレクトリの、UserDir ディレクティブで指定された サブディレクトリからコンテンツを得ることになります。

参照: ユーザウェブディレクトリ (public_html)


認証、承認、アクセス制御 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > How-To / チュートリアル

認証、承認、アクセス制御

「認証」とは、誰かが自分は誰であるかを主張した場合に、 それを確認するための全過程を指します。「承認」とは、 誰かが行きたい場所に行けるように、あるいは欲しい情報を 得ることができるようにするための全過程を指します。

関連するモジュールとディレクティブ

関連モジュール 関連ディレクティブ
  • mod_auth
  • mod_access
  • Allow
  • AuthGroupFile
  • AuthName
  • AuthType
  • AuthUserFile
  • Deny
  • Options
  • Require

はじめに

もし機密の情報や、ごくごく少数グループの人向けの情報を ウェブサイトに置くのであれば、この文書に書かれている テクニックを使うことで、そのページを見ている人たちが 望みの人たちであることを確実にできるでしょう。

この文書では、多くの人が採用するであろう、 ウェブサイトの一部分を保護する「一般的な」 方法についてカバーしています。

準備

この文書で取り扱われるディレクティブは、 メインサーバ設定ファイル (普通は <Directory> セクション中) か、あるいはディレクトリ毎の設定ファイル (.htaccess ファイル) かで用います。

.htaccess ファイルを用いるのであれば、 これらのファイルに認証用のディレクティブを置けるように サーバの設定をしないといけないでしょう。これは AllowOverride ディレクティブで可能になります。 AllowOverride ディレクティブでは、ディレクトリ毎の設定ファイル中に置くことのできる ディレクティブを、もしあれば、指定します。

認証について話を進めているので、次のような AllowOverride ディレクティブが必要になるでしょう。

AllowOverride AuthConfig

そうでなく、メインサーバ設定ファイルの中に 直接置くのであれば、当然ながらそのファイルへの書き込み 権限を持っていなければならないでしょう。

また、どのファイルがどこに保存されているか知るために、 サーバのディレクトリ構造について少し知っておく 必要があるでしょう。 これはそんなに難しくないので、この文書中で ディレクトリ構造について知っておく必要がある場面では、 明らかになるようにします。

動作させる

では、サーバ上のあるディレクトリをパスワードで保護する 基本手順を示します。

パスワードファイルを作る必要があります。 このファイルは、ウェブからアクセスできる場所に 置くべきではありません。他の人がパスワードファイルを ダウンロードできないようにするためです。例えば、 /usr/local/apache/htdocs でドキュメントを 提供しているのであれば、パスワードファイルは /usr/local/apache/passwd などに置いた方が良いでしょう。

ファイルを作るためには、Apache 付属の htpasswd を使います。このコマンドは Apache をどこにインストールしようとも、 インストールディレクトリの bin ディレクトリ以下に置かれます。ファイルを作るには、次のように タイプしてください。

htpasswd -c /usr/local/apache/passwd/passwords rbowen

htpasswd は、パスワードを要求し、その後 確認のためにもう一度入力するように要求してきます。

# htpasswd -c /usr/local/apache/passwd/passwords rbowen
New password: mypassword
Re-type new password: mypassword
Adding password for user rbowen

もし htpasswd がパスの中に入っていない場合は、 もちろん、実行するためにプログラムまでのフルパスを タイプする必要があります。私のサーバであれば、 /usr/local/apache/bin/htpasswd にプログラムが置かれています。

次に、サーバがパスワードを要求するように設定して、 どのユーザがアクセスを許されているかをサーバに知らせなければ なりません。 httpd.conf を編集するか .htaccess ファイルを使用するかで 設定します。例えば、ディレクトリ /usr/local/apache/htdocs/secret を保護したい場合は、 /usr/local/apache/htdocs/secret/.htaccess か httpd.conf 中の <Directory /usr/local/apache/apache/htdocs/secret> セクションに 配置して、次のディレクティブを使うことができます。

AuthType Basic
AuthName "Restricted Files"
AuthUserFile /usr/local/apache/passwd/passwords
Require user rbowen

個々のディレクティブについて見てみましょう。 AuthType ディレクティブはどういう認証方法でユーザの認証を行うかを 選択します。最も一般的な方法は Basic で、これは mod_auth で実装されています。しかしながら、 これは気を付けるべき重要なポイントなのですが、 Basic 認証はクライアントからブラウザへ、 パスワードを暗号化せずに送ります。ですから、 この方法は特に機密性の高いデータに対しては用いるべきでは ありません。 Apache ではもう一つ別の認証方法: AuthType Digest をサポートしています。 この方法は mod_auth_digest で実装されていて、もっと安全です。 ごくごく最近のクライアントしか Digest 認証をサポートしていないようです。

AuthName ディレクティブでは、認証に使う Realm (訳注: 領域) を設定します。Realm は大きく分けて二つの機能を提供します。 一つ目は、クライアントがパスワードダイアログボックスの 一部としてユーザにこの情報をよく提示する、というものです。 二つ目には、クライアントが与えられた認証領域に対してどのパスワードを 送信すれば良いのかを決定するために使われる、という機能です。

例えば、"Restricted Files" 領域中で 一度認証されれば、同一サーバ上で "Restricted Files" Realm としてマークされたどんな領域でも、クライアントは 自動的に同じパスワードを使おうと試みます。 このおかげで、複数の制限領域に同じ realm を共有させて、 ユーザがパスワードを何度も要求される事態を 防ぐことができます。もちろん、セキュリティ上の理由から、 サーバのホスト名が変わればいつでも必ず、 クライアントは再びパスワードを尋ねる必要があります。

AuthUserFile ディレクティブは htpasswd で作った パスワードファイルへのパスを設定します。 ユーザ数が多い場合は、リクエスト毎のユーザの認証のための プレーンテキストの探索が非常に遅くなることがあります。 Apache ではユーザ情報を高速なデータベースファイルに 保管することもできます。 mod_auth_dbm モジュールが AuthDBMUserFile ディレクティブを提供します。これらのファイルは dbmmanage プログラムで作成したり操作したりできます。 Apache モジュールデータベース中にあるサードパーティー製の モジュールで、その他多くのタイプの認証オプションが 利用可能です。

最後に、Require ディレクティブが、サーバのこの領域にアクセスできるユーザを 指定することによって、プロセスの承認部分を提供します。 次のセクションでは、Require ディレクティブの様々な用法について述べます。

複数の人が入れるようにする

上記のディレクティブは、ただ一人 (具体的にはユーザ名 rbowen の誰か) がディレクトリに 入れるようにします。多くの場合は、複数の人が 入れるようにしたいでしょう。ここで AuthGroupFile の登場です。

もし複数の人が入れるようにしたいのであれば、 グループに属するユーザの一覧の入っている、グループ名のついた グループファイルを作る必要があります。このファイルの 書式はきわめて単純で、お好みのエディタで生成できます。 ファイルの中身は次のようなものです。

GroupName: rbowen dpitts sungo rshersey

一行にスペース区切りで、グループに所属するメンバーの 一覧をならべるだけです。

既に存在するパスワードファイルにユーザを加える場合は、 次のようにタイプしてください。

htpasswd /usr/local/apache/passwd/passwords dpitts

以前と同じ応答が返されますが、新しいファイルを 作るのではなく、既にあるファイルに追加されています。 (新しいパスワードファイルを作るには -c を使います。)

ここで次のようにして .htaccess ファイルを 修正する必要があります。

AuthType Basic
AuthName "By Invitation Only"
AuthUserFile /usr/local/apache/passwd/passwords
AuthGroupFile /usr/local/apache/passwd/groups
Require group GroupName

これで、グループ GroupName にリストされていて、 password ファイルにエントリがある人は、 正しいパスワードをタイプすれば入ることができるでしょう。

もっと特定せずに複数のユーザが入れるようにする、 もう一つの方法があります。グループファイルを作るのではなく、 次のディレクティブを使えばできます。

Require valid-user

require user rbowen 行でなく、上記を使うと、 パスワードファイルにリストされている人であれば誰でも 許可されます。 単にパスワードファイルをグループ毎に分けておくことで、 グループのような振る舞いをさせることもできます。 このアプローチの利点は、Apache は二つではなく、 ただ一つのファイルだけを検査すればよいという点です。 欠点は、たくさんのパスワードファイルを管理して、その中から AuthUserFile ディレクティブに正しいファイルを参照させなければならない点です。

起こりえる問題

Basic 認証が指定されている場合は、 サーバにドキュメントをリクエストする度に ユーザ名とパスワードを検査しなければなりません。 これは同じページ、ページにある全ての画像を リロードする場合であっても該当します (もし画像も保護されたディレクトリから来るのであれば) 。 予想される通り、これは動作を多少遅くします。 遅くなる程度はパスワードファイルの大きさと比例しますが、 これは、ファイルを開いてあなたの名前を発見するまで ユーザ名のリストを読まなければならないからです。 そして、ページがロードされる度にこれを行わなければ なりません。

結論としては、一つのパスワードファイルに置くことのできる ユーザ数には実質的な限界があります。 この限界はサーバマシンの性能に依存して変わりますが、 数百のエントリを越えたあたりから速度低下が見られると予期されています。 その時は他の認証方法を考慮に入れた方が良いでしょう。

もっと巧みに制御できない ?

ユーザ名とパスワードによる認証は認証の一つの方法に過ぎません。 しばしば誰であるかということとは違う何かに基づいて、 入れるようにしたくなることもあるでしょう。 例えばその人がどこから来ているかといったことです。

Allow と Deny ディレクティブを使って、ドキュメントを要求してきたマシンの ホスト名やホストアドレスに基づいて許可不許可を制御できます。 Order ディレクティブはこの二つと連携して動作し、Apache にどの順番でフィルタを適用するかを知らせます。

これらのディレクティブの使い方は次のようになります。

Allow from address

ここで、address は IP アドレス (または IP アドレスの一部)、あるいは完全修飾ドメイン名 (またはドメイン名の一部) です。 必要であれば複数のアドレスやドメイン名を指定できます。

例えば、もし誰かが掲示板を攻撃していて、 その人を閉め出したいのであれば、 次のようにすることができます。

Deny from 205.252.46.165

このアドレスから来る人は、このディレクティブの範囲内の コンテンツを見ることができないません。もし IP アドレスの代わりにマシン名があれば、それを使えます。

Deny from host.example.com

ドメイン全体からのアクセスを防ぎたければ、 単にアドレスやドメイン名の一部を指定することができます。

Deny from 192.101.205
Deny from cyberthugs.com moreidiots.com
Deny from ke

Order を使うことで、 Deny と Allow の組み合わせで 入っても良いグループが本当に確実に限定できているようにできます。

Order deny,allow
Deny from all
Allow from dev.example.com

Allow ディレクティブを単純に列挙するのでは望みの動作をしないでしょう。 なぜなら、全ての人が入れるということに加えて、 指定したホストからの人が入れるようにするからです。 やりたいことは、指定した人たちだけが入れるように することです。

追加情報

これら全てがどのように動作するかについて もっと多くの情報が書かれている mod_auth と mod_access の文書も読むとよいでしょう。


Apache Tutorial: CGI による動的コンテンツ - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > How-To / チュートリアル

Apache Tutorial: CGI による動的コンテンツ

はじめに

関連モジュール 関連ディレクティブ
  • mod_alias
  • mod_cgi
  • AddHandler
  • Options
  • ScriptAlias

CGI (Common Gateway Interface) は、ウェブサーバが コンテンツ生成をする外部プログラムと協調して動作するための方法を 定義しています。そのプログラムはしばしば CGI プログラムや CGI スクリプトと呼ばれます。CGI は、ウェブサイトに動的な コンテンツを置くための最も簡単で一般的な方法です。このドキュメントは、 Apache ウェブサーバで CGI を設定し、 CGI プログラムを書き始めるための入門書となるでしょう。

CGI を許可するように Apache を設定する

CGI プログラムを正しく動作させるには、CGI を許可するように Apache の設定を行う必要があります。 これを行なうための方法がいくつかあります。

ScriptAlias

ScriptAlias ディレクティブを使用して、 CGI プログラム用の特別な別ディレクトリを Apache に設定します。 Apache は、このディレクトリ中の全てのファイルを CGI プログラムであると仮定します。 そして、この特別なリソースがクライアントから要求されると、 そのプログラムの実行を試みます。

ScriptAlias ディレクティブは以下のように使用します:

ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/

デフォルト位置に Apache をインストールしたならば、 この例はデフォルト状態の httpd.conf 設定ファイルに含まれています。 ScriptAlias ディレクティブは、URL の前に付加するディレクトリを定義する Alias ディレクティブとかなり似ています。 Alias と ScriptAlias は通常、DocumentRoot ディレクトリ外のディレクトリのために使用されます。 Alias と ScriptAlias との差は、ScriptAlias が接頭辞で始まるすべての URL は CGI プログラムとみなされるという追加の意味を含んでいることです。 従って、上記の例では、/cgi-bin/ で始まるリソースへのあらゆるリクエストに対して、ディレクトリ /usr/local/apache2/cgi-bin/ から提供し、それらを CGI プログラムとして扱うよう Apache に示します。

例えば、URL http://dev.rcbowen.com/cgi-bin/test.pl が要求された場合、Apache は ファイル /usr/local/apache2/cgi-bin/test.pl を実行し、その出力を返すことを試みます。 もちろん、ファイルが存在し、実行可能であり、決められた方法で出力を返します。 そうでなければ、Apache はエラーメッセージを返します。

ScriptAlias ディレクトリ外の CGI

CGI プログラムは、セキュリティ上の理由から ScriptAlias されたディレクトリに制限されることがしばしばあります。この方法により、 CGI プログラムを使用できるユーザを管理者が厳しく制御することができます。 しかしながら、適切なセキュリティ事前対策がとられるならば、CGI プログラムを任意のディレクトリで実行できないようにする理由はありません。 例えば、ユーザに UserDir ディレクティブで彼らのホームディレクトリ配下にウェブコンテンツを持たせたいとします。 もし、彼らが CGI プログラムを持つことを望んでいても、メインの cgi-bin ディレクトリへのアクセスができない場合、 CGI プログラムを実行することができる他の場所が必要になります。

任意のディレクトリで CGI の実行を許可するには二段階の設定が必要です。 まず、AddHandler や SetHandler ディレクティブによって cgi-script ハンドラが可能になっている必要があります。 次に、Options ディレクティブで ExecCGI が指定されていなければなりません。

CGI の実行を可能にするために Options を明示的に使用する

サーバのメインの設定ファイル中で Options ディレクティブを明示的に使用することで、特定のディレクトリ配下で CGI の実行を許可するように指定することができます:

<Directory /usr/local/apache2/htdocs/somedir>
Options +ExecCGI
 </Directory>

上記ディレクティブは、CGI ファイルの実行を可能にするよう Apache に伝えます。また、どのファイルが CGI ファイルかを サーバに伝える必要があります。次の AddHandler ディレクティブの例では、cgi または pl を拡張子に持つすべてのファイルを CGI プログラムとしてみなすことをサーバに伝えます:

AddHandler cgi-script .cgi .pl

.htaccess files

.htaccess チュートリアル は httpd.conf を変更できない場合にどうやって CGI プログラムを 使えるようにするかを説明しています。

User ディレクトリ

.cgi で終わるすべてのファイルに対して CGI プログラムの 実行を許可するには、以下の設定を使用できます。

<Directory /home/*/public_html>
Options +ExecCGI
AddHandler cgi-script .cgi
 </Directory>

ユーザディレクトリの cgi-bin サブディレクトリの すべてのファイルを CGI プログラムとして指定したい場合には 以下のようなものを使います。

<Directory /home/*/public_html/cgi-bin>
Options ExecCGI
SetHandler cgi-script
 </Directory>

CGI プログラムを書く

「通常の」プログラミングと CGI プログラミングの間には主に二つの違いがあります。

一つは、CGI プログラムのすべての出力には MIME-type ヘッダを付けなければなりません。 これはどのような種類のコンテンツを受け取っているかをクライアントに示す HTTP ヘッダです。ほとんどの場合では、次のように出力します:

Content-type: text/html

もう一つは、出力を HTML か、ブラウザが表示することができる何か他の形式にする必要があります。 大抵の場合は HTML でしょうが、GIF イメージや他の非 HTML コンテンツを出力する CGI プログラムを書くこともあるでしょう。

これら二点以外では、CGI プログラムを書くことは、 あなたが書いている他のプログラムとよく似ているでしょう。

最初の CGI プログラム

次に示すのは、ブラウザに 1 行印字する CGI プログラムの例です。以下を入力し、first.pl というファイルに保存し、それを cgi-bin ディレクトリに置いてください。

#!/usr/bin/perl
print "Content-type: text/html\n\n";
print "Hello, World.";

Perl に精通していなくても、 何が起こるかを理解することはできるでしょう。1 行目は、 /usr/bin/perl で見つけられるインタプリタに このファイルを供給することでこのプログラムが実行されることを Apache に (シェル上で実行しようとしているならば、そのシェルに ) 示します。2 行目は、前述したとおり content-type の定義を印字します。 これには復帰改行の二つの組を後に付加します。 これにより、ヘッダの終りに空行が置かれ、HTTP ヘッダの終りとボディの始まりを示します。3 行目は、"Hello, World." という文字列を印字し、これで終りとなります。

好みのブラウザを開き、アドレス

http://www.example.com/cgi-bin/first.pl

あるいはファイルを置いたロケーションを指定すると、 Hello, World. という 1 行がブラウザウィンドに現れるでしょう。 それはあまりエキサイティングなことではありません。 しかし、これがうまく動けば、 他のどのようなものでも動かすことができるようになります。

しかし、まだ動かない !

ウェブから CGI プログラムへのアクセスを行なったとき、 ブラウザで見る可能性がある四つの基本的なことがあります:

CGI プログラムの出力
素晴らしい ! それはすべてがうまく動いたことを意味します。 出力が正常だけれども、ブラウザが正常に処理してくれない場合は、 正しい Content-Type を CGI プログラム内で セットしたかを確認してください。
CGI プログラムのソースコード、または "POST Method Not Allowed" というメッセージ
これは、CGI プログラムを処理できるよう Apache を適切に設定していなかったことを意味します。「CGI を許可するように Apache を設定する」の章を読み直し、 あなたが何を間違えたかを探してみてください。
メッセージが "Forbidden" で始まっている
これはパーミッションの問題ということを意味します。 Apache のエラーログと、後述の「ファイルのパーミッション」 の章をチェックしてください。
"Internal Server Error" というメッセージ
Apache のエラーログをチェックすると、"Premature end of script headers" というログが記録されていると思います。そして、おそらく CGI プログラムによって生成されたエラーメッセージも記録されているでしょう。 この場合、CGI プログラムが適切な HTTP ヘッダを出力できない原因を知るために、 以下の各章でチェックしてみてください。

ファイルのパーミッション

サーバはあなたの権限で実行されていないのを忘れないように。 つまり、起動するとき、サーバは特権をもたないユーザ - 通常 nobody や www の権限で実行されます。したがって、あなたが所有する ファイルを実行するには別のパーミッションが必要となります。 通常、nobody が実行するのに十分なパーミッションを与える方法は、 ファイルに誰でも実行可能とするパーミッションを与えることです:

chmod a+x first.pl

また、もしあなたのプログラムが他のファイルを読み書きするならば、 それらのファイルは、これが可能となる正しいパーミッション を持っている必要があります。

パス情報と環境

コマンドラインからプログラムを実行するとき、 意識しなくてもシェルに渡される情報があります。 例えば、参照するファイルのためにどこを検索したらよいかを シェルに伝える PATH があります。

プログラムが CGI プログラムとしてウェブサーバによって実行されるとき、 それは同じ PATH ではないかもしれません。 CGI プログラム内で呼び出すあらゆるプログラム (例えば、sendmail のようなもの) は、 フルパスで指定する必要があるでしょう。それにより、CGI プログラムを実行しようとしたとき、 シェルはそのようなプログラムを見つけることができます。

同様なことは、スクリプトのインタプリタ (しばしば perl) へのパスで、CGI プログラムの 1 行目に次のように示されます:

#!/usr/bin/perl

これがインタープリタへの実際のパスであることを確実にしておきます。

プログラムエラー

CGI プログラムが失敗するのは大抵、プログラム自身に問題がある場合です。 一度 CGI の使い方を理解し、前述の二つの誤りを犯していないならば、 まず間違いなくそうでしょう。ブラウザを使ってテストする前に まず確認することは、コマンドラインからプログラムが実行できることです。 例えば、以下を実行してみてください:

cd /usr/local/apache2/cgi-bin
./first.pl

(perl インタプリタは呼ばないでください。 シェルと Apache がスクリプトの最初の行の パス情報 を使って見つけます。)

最初にプログラムから出力されるのは Content-Type を含み、 後に空行の続く HTTP ヘッダでなければなりません。他のものが出力されている 場合は、Apache はこのプログラムをサーバ経由で実行しようとしたときには Premature end of script headers エラーを出力します。詳細は 上記の CGI プログラムを書く を読んでください。

エラーログ

エラーログは友達です。 全てのうまくいかないことは、エラーログにメッセージを生成します。 必ずそれを最初に見るべきです。 もし、あなたがウェブサイトを主催している場所が エラーログの参照を許していないならば、きっと他のサイトで主催するべきです。 エラーログの読み方を学ぶことで、ほとんど全ての問題が迅速に確認され、 迅速に解決されるということが分かるでしょう。

Suexec

suexec サポートプログラムは バーチャルホストやユーザのホームディレクトリの場所に依って CGI プログラムを違うユーザ権限の下で走らせることを可能にします。 Suexec の権限のチェックは非常に厳しく、それを満たさない場合は CGI プログラムが Premature end of script headers エラーで 実行されません。

suexec を使っているかどうかを調べためには apachectl -V を実行して、SUEXEC_BIN の場所を調べてください。 Apache がそこに suexec のバイナリを発見した場合は、suexec が 使用されます。

suexec を完全に理解していない限り、使うべきではありません。 suexec を無効にするには、SUEXEC_BIN から指されている suexec バイナリを削除 (か名前を変更) するだけです。 suexec を読んだ後で、まだそれを 使いたいのであれば、suexec -V を実行して suexec の ログファイルの位置を調べ、そのログファイルを使ってポリシー違反を 見つけてください。

裏で何が起こっているのか?

CGI プログラミングに習熟すると、 裏で起こっていることについて更に理解すること役に立ちます。 ブラウザとサーバがどのように相互通信するかについては特にそうです。 なぜなら、"Hello, World." を印字するプログラムを書くことはおおいに結構ですが、 それは特に有益ではありません。

環境変数

環境変数は、 あなたがコンピュータを使うときに辺りに存在している値です。 それらは、パス (コマンドをタイプしたときに実行する実際のファイルを探し出すところ)、 ユーザ名、端末型などのような便利なものです。 通常、普段使用している環境変数の完全なリストを調べるには、 コマンドプロンプトで env を入力します。

CGI の処理中、サーバとブラウザも環境変数を設定し、 それにより相互に通信することができるようになります。 その環境変数は、ブラウザタイプ (Netscape, IE, Lynx)、サーバタイプ (Apache, IIS, WebSite)、実行されている CGI プログラムの名前などです。

これらの変数は CGI プログラマが使用できます。 そして、それはクライアントとサーバの通信の話の半分です。 必要な変数の完全なリストは http://hoohoo.ncsa.uiuc.edu/cgi/env.html にあります。

以下の単純な Perl CGI プログラムは、渡される全ての環境変数を表示します。同様のプログラムは、 Apache ディストリビューションの cgi-bin ディレクトリに二つ含まれています。 いくつかの変数が必須であり、いくつかは任意であることに注意してください。 そして、公式のリストにはないいくつかの変数が表示されているかもしれません。 さらに、Apache はデフォルトで用意されている基本的なものに あなた自身の環境変数を加えるための、 多くの異なる方法を用意してします。

#!/usr/bin/perl
print "Content-type: text/html\n\n";
foreach $key (keys %ENV) {
print "$key --> $ENV{$key}<br>";
 }

STDIN と STDOUT

サーバとクライアント間のもう一つの通信は、標準入力 (STDIN)と標準出力 (STDOUT) を通じて行なわれます。通常の文脈において、STDIN はキーボードやプログラムが動作するために与えられるファイルを意味し、 STDOUT は通常コンソールまたはスクリーンを意味します。

ウェブフォームから CGI プログラムへPOST したとき、フォームのデータは特別なフォーマットで束ねられ、 STDIN を通して、CGI プログラムに引き渡されます。 プログラムはデータがキーボード もしくはファイルから来ていたかのように処理することができます。

「特別なフォーマット」はとても単純です。フィールド名と値はイコール (=) で結ばれます。そして値の組はアンパサンド (&) で結ばれます。 スペース、アンパサンド、イコールのような面倒な文字は、 それらが動作を駄目にしないようにその文字に相当する 16 進に変換されます。 全データ文字列は、以下のようになります:

name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey

時々、このような文字列が URL に付加されるのを見るでしょう。その場合、サーバは QUERY_STRING という環境変数にその文字列を入れます。それは GET リクエストと呼ばれます。 HTML フォームでは、データを渡すために GET と POST のどちらを使用するかを、FORM タグの METHOD 属性の設定で指定します。

CGI プログラムは、その文字列を役に立つ情報に分割する責任があります。 幸いにも、そのデータ処理を助けるライブラリやモジュールが存在します。 これらは、CGI プログラムの他の面でも同様に役に立ちます。

CGI モジュール/ライブラリ

CGI プログラムを書くとき、面倒な仕事の大部分をしてくれる コードライブラリまたはモジュールを使うことを検討すべきです。 これはエラーを減らし、早い開発につながります。

Perl で CGI プログラムを書いているなら、モジュールは CPAN で提供されています。 この目的のための最も普及しているモジュールは CGI.pm です。 CGI::Lite も検討しましょう。これは、ほとんどのプログラム において必要とするすべての機能の最小セットの実装です。

C で CGI プログラムを書いているなら、いろいろな オプションがあります。これらの内の一つは http://www.boutell.com/cgic/ で提供されている CGIC ライブラリです。

更なる情報

CGI に関する情報はウェブで数多く提供されています。CGI の問題については Usenet の comp.infosystems.www.authoring.cgi で、 他のユーザと論議することができます。HTML Writers Guide の -servers メーリングリストは、あなたの質問に回答してくれる偉大なリソースです。 http://www.hwg.org/lists/hwg-servers/ で更に多くを探し出すことができます。

そしてもちろん、おそらく CGI プログラムの動作に関する詳細の全てが記述されている CGI の仕様を読むべきです。オリジナルバージョンを NCSA で、アップデートされたドラフトを Common Gateway Interface RFC プロジェクトで参照することができます。

CGI の問題について、加わっているメーリングリストまたはニュース グループに質問を送るとき、起こったもの、起こってほしいこと、 実際に起こったことがどう違うか、使用しているサーバ、 CGI プログラムを記述している言語に関する十分な情報と、 可能であれば問題のコードを提供するようにしてください。 そうすることで、問題がより間単に見つかるようになります。

Apache のソースコードにおいて問題を発見したことを確信していない限り、 CGI の問題に関する質問を Apache バグデータベースに送るべきでない ことに注目してください。


Apache チュートリアル: Server Side Includes 入門 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > How-To / チュートリアル

Apache チュートリアル: Server Side Includes 入門

サーバサイドインクルードによって、既存の HTML ドキュメントに動的なコンテンツを追加することができます。

はじめに

関連モジュール 関連ディレクティブ
  • mod_include
  • mod_cgi
  • mod_expires
  • Options
  • XBitHack
  • AddType
  • SetOutputFilter
  • BrowserMatchNoCase

この記事は、通常は単に SSI と呼ばれる Server Side Includes を扱います。この記事においては、サーバでの SSI を許可するための設定と、 現在の HTML ページに動的なコンテンツを加えるためのいくつかの基本的な SSI 技術を紹介します。

記事の後半では、SSI ディレクティブで SSI と共に実行することができる条件文のような 幾分高度な事柄について述べています。

SSI とは ?

SSI (Server Side Includes) は、HTML ページ中に配置されるディレクティブであり、 サーバでページを提供する時に評価されます。SSI は、CGI プログラムやその他の動的な技術で全てのページを提供せずに、 動的に生成されたコンテンツを現在の HTML ページに加えます。

どういう場合に SSI を使い、どういう場合にプログラムで ページを完全に生成するかは、ページのうちどの程度が静的であり、 ページが提供されるたびに再計算する必要がどの程度あるかで通常は決定します。 SSI は現在時刻のような小さい情報を加えるにはうってつけの方法です。 しかし、そのページのほとんどの部分が提供時に生成される場合は、 他の方法を探す必要があります。

SSI を許可するためのサーバの設定

サーバで SSI を許可するには、httpd.conf ファイルまたは .htaccess ファイルに次のディレクティブを指定する必要があります:

Options +Includes

この指定は、ファイルを SSI ディレクティブで解析させることを許可するということを Apache に伝えます。ほとんどの設定ではお互いを上書きできる、複数の Options があることに 注意してください。おそらく、設定が最後に評価されることを 保証されるために、SSI を使用したいディレクトリに Options ディレクティブを適用する必要があるでしょう。

全てのファイルが SSI ディレクティブで解析されるというわけではありません。 どのファイルが解析されるかを Apache に伝える必要があります。 これを行なうには二つ方法があります。 次のディレクティブを使うことで、例えば .shtml のような特別なファイル拡張子を持つファイルを解析するよう Apache に伝えることができます:

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

この方法の欠点は、もし現在のページに SSI ディレクティブを加えたい場合、 それらのディレクティブが実行されるように .shtml 拡張子にするため、そのページの名前と、 そのページへの全てのリンクを変更しなければならないことです。

もう一つの方法は、XBitHack ディレクティブを使用することです:

XBitHack on

XBitHack は、ファイルの実行ビットが立っている場合、 SSI ディレクティブにより解析することを Apache に伝えます。 従って、SSI ディレクティブを現在のページに加えるためには、 ファイル名を変更しなくてもよく、単に chmod を使用してファイルを実行可能にするだけで済みます。

chmod +x pagename.html

行なうべきではないことに関する短いコメント。時々誰かが、全ての .html ファイルを SSI で解析するよう Apache に伝えれば、 わざわざ .shtml というファイル名にする必要がないといって 薦めるのを見ることでしょう。こういう人たちは、おそらく XBitHack について聞いたことがないのでしょう。 この方法について注意することは、たとえ SSI ディレクティブを全く含まない場合でも、Apache がクライアントに 送る全てのファイルを最後まで読み込ませることになります。 この方法はかなり処理を遅くするものであり、良くないアイデアです。

もちろん、Windows ではそのような実行ビットをセット するようなものはありませんのでオプションが少し制限されています。

デフォルトの設定では、Apache は SSI ページについて最終変更時刻や コンテンツの長さを HTTP ヘッダに送りません。 動的なコンテンツであるため、それらの値を計算するのが難しいからです。 このためドキュメントがキャッシュされなくなり、 結果としてクライアントの性能が遅くなったように感じさせることになります。 これを解決する方法が二つあります:

  1. XBitHack Full 設定を使用する。 この設定により、もともと要求されたファイルの時刻を参照し、 読み込まれるファイルの変更時刻を無視して最終変更時刻を決定するよう Apache に伝えます。
  2. mod_expires で提供されているディレクティブを使用して、 ファイルが無効になる時刻を明示します。これにより、 ブラウザとプロキシにキャッシュが有効であることを通知します。

基本的な SSI ディレクティブ

SSI ディレクティブは以下の文法で記述します:

<!--#element attribute=value attribute=value ... -->

HTML のコメントのような書式をしているので、もし SSI を正しく動作可能にしなければ、ブラウザはそれを無視するでしょう。 しかし、HTML ソース中では見えます。もし SSI を正しく設定したなら、 ディレクティブはその結果と置き換えられます。

element はたくさんあるものから一つ指定することができます。 指定できるものの大多数については、次回もう少し詳しく説明します。 ここでは、SSI で行なうことができる例をいくつか示します。

今日の日付

<!--#echo var="DATE_LOCAL" -->

echo 要素は単に変数の値を出力します。 CGI プログラムに利用可能な環境変数の全ての セットを含む多くの標準変数があります。また、set 要素を用いることで、独自の変数を定義することができます。

出力される日付の書式が好きではない場合、その書式を修正するために、 config 要素に timefmt 属性を使用することができます。

<!--#config timefmt="%A %B %d, %Y" -->
Today is <!--#echo var="DATE_LOCAL" -->

ファイルの変更日

This document last modified <!--#flastmod file="index.html" -->

この要素も timefmt フォーマットの設定に従います。

CGI プログラムの結果を取り込む

これは、全ての人のお気に入りである ``ヒットカウンタ'' のような CGI プログラムの結果を出力する SSI のより一般的な使用のうちの一つです。

<!--#include virtual="/cgi-bin/counter.pl" -->

追加の例

以下は、SSI を使用して HTML ドキュメントにおいてできることのいくつかの特別な例です。

いつこのドキュメントは修正されたのか ?

先に、ドキュメントが最後に変更されたのはいつかを ユーザに通知するために SSI を使用することができることを述べました。 しかしながら、実際の方法は、いくぶん問題のままにしておきました。 HTML ドキュメントに配置された次のコードは、ページにそのような タイムスタンプを入れるでしょう。もちろん、上述のように、 SSI を正しく動作可能にしておく必要があります。

<!--#config timefmt="%A %B %d, %Y" -->
This file last modified <!--#flastmod file="ssi.shtml" -->

もちろん、ssi.shtml の部分を実際の当該ファイル名と置き換える必要があります。 もし、あらゆるファイルに張ることができる一般的なコードを探しているなら、 これは不便であるかもしれません。おそらくその場合は、 そうする代わりに変数 LAST_MODIFIED を使用したいと考えるでしょう:

<!--#config timefmt="%D" -->
This file last modified <!--#echo var="LAST_MODIFIED" -->

timefmt 書式についてのより詳細については、お好みの検索サイトに行き、 strftime で検索してみてください。文法は同じです。

標準のフッタを挿入する

もし数ページを超えるページを持つサイトを管理しているならば、 全ページに対して変項を行なうことが本当に苦痛となり得ることが 分かるでしょう。全てのページに渡ってある種の標準的な外観を 維持しようとしているならば特にそうでしょう。

ヘッダやフッタ用の挿入用ファイルを使用することで、 このような更新にかかる負担を減らすことができます。 一つのフッタファイルを作成し、それを include SSI コマンドで各ページに入れるだけで済みます。include 要素は、file 属性または virtual 属性のいずれかを使用してどのファイルを挿入するかを決めることができます。 file 属性は、カレントディレクトリからの相対パスで示された ファイルパスです。 それは / で始まる絶対ファイルパスにはできず、また、そのパスの一部に ../ を含むことができないことを意味します。virtual 属性は、おそらくより便利だと思いますが、提供するドキュメントからの相対 URL で指定すべきです。それは / で始めることができますが、 提供するファイルと同じサーバ上に存在しなくてはなりません。

<!--#include virtual="/footer.html" -->

私は最後の二つを組み合わせて、LAST_MODIFIED ディレクティブをフッタファイルの中に置くことがよくあります。 SSI ディレクティブは、挿入用のファイルに含ませたり、 挿入ファイルのネストをしたりすることができます。すなわち、 挿入用のファイルは他のファイルを再帰的に挿入することができます。

他に何が設定できるのか ?

時刻書式を config で設定できることに加えて、 更に二つ config で設定することができます。

通常、SSI ディレクティブで何かがうまくいかないときは、 次のメッセージが出力されます。

[an error occurred while processing this directive]

このメッセージを他のものにしたい場合、config 要素の errmsg 属性で変更することができます:

<!--#config errmsg="[It appears that you don't know how to use SSI]" -->

おそらく、エンドユーザはこのメッセージを決して見ることはありません。 なぜなら、そのサイトが生きた状態になる前に SSI ディレクティブに関する 全ての問題を解決しているはずだからです。(そうですよね?)

そして、config において sizefmt 属性を使用することで、 返されるファイルサイズの書式を設定することができます。 バイト数には bytes を、適当に Kb や Mb に短縮させるには abbrev を指定することができます。

コマンドの実行

今後数ヶ月のうちに、小さな CGI プログラムと SSI を使用する記事を出したいと考えています。ここではそれとは別に、 exec 要素によって行なうことができることを示します。 SSI にシェル (正確には /bin/sh。Win32 ならば DOS シェル) を使用してコマンドを実行させることができます。 下記の例では、ディレクトリリスト出力を行ないます。

<pre>
<!--#exec cmd="ls" -->
</pre>

Windows 上では、

<pre>
<!--#exec cmd="dir" -->
</pre>

Windows 上では、このディレクティブによっていくつかの奇妙な 書式に気づくでしょう。なぜなら dir の出力が文字列 ``<dir>'' を含み、ブラウザを混乱させるからです。

この機能は非常に危険であり、どんなコードでも exec タグに埋め込まれてしまえば実行することに注意してください。例えば `` ゲストブック '' のように、もし、 ユーザがページの内容を編集できる状況にあるならば、 この機能を確実に抑制してください。Options ディレクティブの IncludesNOEXEC 引数を指定することで、 SSI は許可するけれど exec 機能は許可しないようにすることができます。

高度な SSI テクニック

コンテンツを出力することに加え、Apache SSI は変数を設定し、 そして比較と条件分岐にその変数を使用できる機能を提供しています。

警告

この記事で述べた大部分の機能は、Apache 1.2 以降を使用している場合のみ利用可能です。もちろん、もし Apache 1.2 以降を使用してない場合、直ちにアップグレードする必要があります。 さぁ、今それを行ないなさい。それまで待っています。

変数を設定する

set ディレクティブを使用して、 後で使用するために変数を設定することができます。 これは後の説明で必要になるので、ここでそれについて述べています。 文法は以下のとおりです:

<!--#set var="name" value="Rich" -->

このように単純に文字どおりに設定することに加え、 環境変数や上記の変数 (例えば LAST_MODIFIED のような) を含む他のあらゆる変数を値を設定するのに使用することができます。 変数名の前にドル記号 ($) を使用することで、 それがリテラル文字列ではなくて変数であることを示します。

<!--#set var="modified" value="$LAST_MODIFIED" -->

ドル記号 ($) を文字として変数の値に入れるには、 バックスラッシュによってドル記号をエスケープする必要があります。

<!--#set var="cost" value="\$100" -->

最後になりますが、長い文字列の中に変数を置きたい場合で、 変数名が他の文字とぶつかる可能性があり、 それらの文字について混乱してしまう場合、この混乱を取り除くため、 変数名を中括弧で囲むことができます (これについての良い例を示すのは難しいのですが、 おそらく分かっていただけるでしょう)。

<!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->

条件式

さて、変数を持っていて、 それらの値を設定して比較することができるのですから、 条件を表すためにそれらを使用することができます。これにより SSI はある種の小さなプログラミング言語になっています。 mod_include は条件を表現するために if, elif, else, endif 構造を提供しています。これによって、 一つの実際のページから複数の論理ページを効果的に生成することができます。

条件構造は以下のとおりです:

<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->

test_condition はあらゆる種類の論理的比較をすることができます。 値を比較したり、その値が ``真'' かどうかを評価します (空でないなら与えられた文字列は真です)。 利用可能な比較演算子の全てのリストについては、 mod_include ドキュメンテーションを参照してください。 ここでは、この構造をどう使用するかの例をいくつか示します。

設定ファイルで次の行を記述します:

BrowserMatchNoCase macintosh Mac
BrowserMatchNoCase MSIE InternetExplorer

これはクライアントが Macintosh 上でインターネットエクスプローラが動いている場合、環境変数 ``Mac'' と ``InternetExplorer'' を真と設定します。

次に、SSI が可能になったドキュメントで以下を行ないます:

<!--#if expr="${Mac} && ${InternetExplorer}" -->
Apologetic text goes here
<!--#else -->
Cool JavaScript code goes here
<!--#endif -->

Mac 上の IE に対して何か思うところがあるわけでありません。 他では実行できているいくつかの JavaScript を Mac 上の IE で実行させるのに、先週数時間苦労したというだけのことです。 上の例はその暫定的な対処方法です。

他のどんな変数 (あなたが定義するもの、 または普通の環境変数のいずれか) も、条件文に使用することができます。 Apache は SetEnvIf ディレクティブや他の関連 ディレクティブを使用して環境変数を設定することができます。 この機能により、CGI に頼ることなくかなり複雑な動的なことをさせることができます。

終わりに

SSI は確かに CGI や動的なウェブページを生成する他の技術に代わるものではありません。 しかし、たくさんの余分な作業をせずに、 少量の動的なコンテンツを加えるにはすぐれた方法です。


Apache チュートリアル: .htaccess ファイル - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > How-To / チュートリアル

Apache チュートリアル: .htaccess ファイル

.htaccess ファイルはディレクトリ毎に設定を変更する方法を 提供します。

.htaccess ファイル

関連モジュール 関連ディレクティブ
  • core
  • mod_auth
  • mod_cgi
  • mod_include
  • mod_mime
  • AccessFileName
  • AllowOverride
  • Options
  • AddHandler
  • SetHandler
  • AuthType
  • AuthName
  • AuthUserFile
  • AuthGroupFile
  • Require

.htaccess ファイルとは何か/その使い方

.htaccess ファイル (「分散設定ファイル」) は ディレクトリ毎に設定を変更する方法を提供します。ディレクティブの 書かれたファイルをディレクトリに置くことで、そのディレクトリとその サブディレクトリすべてにディレクティブを適用させることができます。

注:

.htaccess ファイルを別の名前にしたい場合は、 AccessFileName ディレクティブを 使って変更することができます。例えば、そのファイルを .config という名前にしたい場合は、以下の設定をサーバ設定ファイルに入れることが できます:

AccessFileName .config

一般に、.htaccess ファイルの構文は 主設定ファイル と同じです。これらのファイルに書くことのできるディレクティブは AllowOverride ディレクティブにより決まります。 このディレクティブは、.htaccess ファイルに 書かれたディレクティブの中で、、 どのディレクティブが適用されるかをカテゴリー単位で指定します。 .htaccess に書くことのできるディレクティブであれば、 説明文書には「上書き」という項目があり、.htaccess に書くことができるように なるための AllowOverride の値が指定されています。

例えば、AddDefaultCharset ディレクティブの説明を 見ると、.htaccess ファイルでの使用が許可されていることが わかります。 (ディレクティブの概要の所にある「コンテキスト」と書かれている 行を見てください。) 上書きと書かれている行には FileInfo とあります。ですから、.htaccess 中の このディレクティブが有効になるためには、少なくとも AllowOverride FileInfo が設定されている必要があります。

例:

コンテキスト: | サーバ設定ファイル,バーチャルホスト,ディレクトリ,.htaccess
上書き: | FileInfo

あるディレクティブを .htaccess ファイルに書くことができるか どうかわからないときは、そのディレクティブの説明を探して、".htaccess" のための「コンテキスト」の行を調べてください。

いつ .htaccess ファイルを使う(使わない)か。

一般的に、サーバの主設定ファイルにアクセスできない場合を除いて、 .htaccess ファイルの使用は極力避けてください。 世の中には、例えば、ユーザ認証は常に .htaccess ファイルで 行なわなければならない、という誤解が広まっていますが、まったくそんなことは ありません。ユーザ認証の設定はサーバ主設定ファイルに書くことができ、 実際、その方がより良い設定方法です。

.htaccess ファイルはコンテンツ提供者がディレクトリ毎の 設定を行ないたいけれど、サーバシステムの root アクセス権限を持っていない という場合にのみ使うべきものです。サーバ管理者が頻繁に設定変更を行ないたくは ない、というときには個々のユーザが .htaccess ファイルを使って 自分で設定の変更を行なうことを許可した方が良いときもあるでしょう。 これは特に、ISP が複数のユーザのサイトを一つのマシンでホストしていて、 各ユーザが設定の変更をできるようにしたいようなときにあてはまります。

しかし、普通は可能であれば .htaccess ファイルの使用は 避けてください。.htaccess ファイルに書こうと考えるような すべての設定は、サーバの主設定ファイルの <Directory> セクションで同じように行なうことが できます。

.htaccess ファイルの使用を避ける理由は主に二つあります。

一つ目はサーバの性能の問題です。AllowOverride ディレクティブが .htaccess ファイルの設定を許可している場合は、Apache は 各ディレクトリで .htaccess ファイルを探します。 ですから、.htaccess ファイルを許可すると、実際に使用しているか どうかに関わらず、性能の低下を招くことになります! また、.htaccess ファイルは文書がリクエストされる度に読み込まれます。

さらに、Apache は適用すべきディレクティブを集めるために、すべての 上位のディレクトリの .htaccess ファイルを探す必要があることにも 注意してください。(ディレクティブが適用される方法を 参照してください。)ですから、/www/htdocs/example にある ファイルがリクエストされたときは、Apache は以下のファイルを調べます。

/.htaccess
/www/.htaccess
/www/htdocs/.htaccess
/www/htdocs/example/.htaccess

ですから、そのディレクトリのそれぞれのファイルへのアクセスに対して、 上の例のファイルがまったく存在しないときでも、追加のファイルシステムの アクセスが行なわれることになります。(これは、.htaccess が / に対して有効になっているときの場合で、普通はそうなって いないことに注意してください。)

二つ目はセキュリティです。ユーザにサーバの設定を変更することを 許可することになりますので、あなた自身が管理できない変更をされる 恐れがあります。ユーザにこの特権を与えるのが良いのかどうか、十分 検討してください。また、ユーザに与える権限が必要なものよりも少なすぎると、 余分な技術サポート報告を受け取るようになる可能性が高いことにも 注意してください。確実に、ユーザにどの程度の権限を与えたか明確に告げるように してください。AllowOverride に 何を設定したかということと、関連する文書を示すことで、 後々の混乱をぐっと減らすことが できます。

ところで、ディレクティブの書かれた .htaccess を /www/htdocs/example に置くことと、同じディレクティブを 主サーバ設定の Directory セクション <Directory /www/htdocs/example> に書くことは 完全に等価です:

/www/htdocs/example の .htaccess ファイル:

/www/htdocs/example の .htaccess ファイルの 内容

AddType text/example .exm

httpd.conf のセクション file

<Directory /www/htdocs/example>
AddType text/example .exm
 </Directory>

しかし、この設定はサーバ設定ファイルに書いた方がパフォーマンスの 低下が少なくなります。ファイルがリクエストされる度に 読み込まれる代わりに、Apache の起動時に 1 回だけ読み込めば よくなるからです。

AllowOverride ディレクティブの 値を none に設定することで .htaccess ファイル の使用を完全に無効にすることができます。

AllowOverride None

ディレクティブの適用のされ方

.htaccess ファイルの設定ディレクティブは .htaccess ファイルの存在するディレクトリと、そのサブディレクトリすべてに適用されます。 しかし、上の階層のディレクトリにも .htaccess ファイルが 存在するかもしれないことを覚えておくことは大切です。ディレクティブは現れる 順番に適用されます。ですから、あるディレクトリの .htaccess は ディレクトリツリーのより上の階層の .htaccess ファイルの 設定を上書きするかもしれません。そして、その .htaccess も より上の階層で書かれたディレクティブを上書きしたり、主サーバ設定ファイル そのものの設定を上書きしたりしているかもしれません。

例:

ディレクトリ /www/htdocs/example1 に以下の内容の .htaccess ファイルがあります:

Options +ExecCGI

(注: .htaccess ファイルで "Options" ディレクティブが有効になるためには、 "AllowOverride Options" を有効にする必要があります。)

ディレクトリ /www/htdocs/example1/example2 には 以下のような .htaccess ファイルがあります:

Options Includes

二つめの .htaccess により、ディレクトリ /www/htdocs/example1/example2 では CGI の実行は 許可されません。これは、Options Includes のみが 効力を持ち、それがすべての以前の設定を上書きするからです。

認証の例

もし認証の方法を知るためにこの部分に直接来たのであれば、次のことを 知っておくことが重要です。よくある誤解に、パスワード認証を行なうためには .htaccess ファイルを使う必要がある、というものがあります。 これは正しくありません。主サーバ設定ファイルの <Directory> セクションに 認証用のディレクティブを書く方が推奨される方法で、.htaccess ファイルは主サーバ設定ファイルを変更できないときにのみ使用すべきです。 いつ .htaccess ファイルを使うべきで、いつ使うべきではないかに ついては 上を参照してください。

以上のことをふまえた上で、もし .htaccess の使用が まだ必要だと思う場合は、次のようなものが望みのことをしてくれるかも しれません。

ディレクティブが適用されるためには、 "AllowOverride AuthConfig" の設定がなされている 必要があります。

.htaccess ファイルの内容:

AuthType Basic
AuthName "Password Required"
AuthUserFile /www/passwords/password.file
AuthGroupFile /www/passwords/group.file
Require Group admins

これらのディレクティブが有効になるためには、 AllowOverride AuthConfig が有効でなくてはならないことに 注意してください。

認証と承認については 認証チュートリアルを 参照してください。

SSI の例

もう一つの .htaccess ファイルのよくある利用法は 特定のディレクトリで SSI を有効にすることです。これは、望みのディレクトリの .htaccess ファイルに以下の設定ディレクティブを書くことで 達成できます:

Options +Includes
AddType text/html shtml
AddHandler server-parsed shtml

これらのディレクティブが有効になるためには、 AllowOverride Options と AllowOverride FileInfo が有効になっている必要があることに注意してください。

よりまとまった SSI の説明は SSI チュートリアルを 参照してください。

CGI の例

最後に、特定のディレクトリで CGI プログラムの実行を許可したいことが あるでしょう。これは以下の設定で行なうことができます:

Options +ExecCGI
AddHandler cgi-script cgi pl

もしくは、あるディレクトリのすべてのファイルが CGI プログラムと みなされるようにしたいなら、以下の設定で実現することができます:

Options +ExecCGI
SetHandler cgi-script

これらのディレクティブが有効になるためには、 AllowOverride Options と AllowOverride FileInfo が有効である必要があることに注意してください。

CGI プログラムと設定のよりまとまった説明は CGI チュートリアルを参照してください。

問題解決

設定ディレクティブを .htaccess ファイルに書いたけれども、 期待した効果が得られないときには、いくつかの原因が考えられます。

一番よくあることは、設定ディレクティブが考慮されるようには AllowOverride が設定されていない というものです。該当のファイルのスコープに AllowOverride None が設定されていないことを確認してください。これを調べるための良い方法は、 .htaccess ファイルにごみを書いて、リロードすることです。 サーバのエラーが生成されないときは、ほぼ確実に AllowOverride None が設定されている状態になっています。

そうではなく、文書をアクセスしようとしたときにエラーが発生している ときは、Apache のエラーログを調べてください。.htaccess ファイルで 使用されたディレクティブが許可されていない、ということを知らせている 可能性が高いです。または、構文の間違いがあることを述べているかもしれません。 その場合にはまずそれを修正する必要があります。


ユーザ毎のウェブディレクトリ - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > How-To / チュートリアル

ユーザ毎のウェブディレクトリ

複数のユーザのいるシステムでは、UserDir ディレクティブを使って 各ユーザがホームディレクトリにウェブサイトを構築できるように設定することが 可能です。URL http://example.com/~username/ を訪れた人は "username" というユーザの UserDir ディレクティブで指定された サブディレクトリからコンテンツを得ることになります。

参照

  • URL からファイルシステムへのマッピング

ユーザ毎のウェブディレクトリ

関連モジュール 関連ディレクティブ
  • mod_userdir
  • UserDir
  • DirectoryMatch
  • AllowOverride

UserDir を使ってファイルのパスを設定する

UserDir ディレクティブは ユーザ毎のコンテンツが読み込まれるディレクトリを指定します。 このディレクティブはいろいろ違った形式を取ることができます。

スラッシュで始まらないパスが与えられたときは、ユーザのホームディレクトリ からの相対パスとみなされます。次の設定があったときに:

UserDir public_html

URL http://example.com/~rbowen/file.html は パス /home/rbowen/public_html/file.html へ 変換されます。

パスがスラッシュで始まるときは、ディレクトリパスはそのパスに ユーザ名を加えたものからなります。次の設定のとき:

UserDir /var/html

URL http://example.com/~rbowen/file.html は パス /var/html/rbowen/file.html へ変換されます。

アスタリスク (*) を含むパスが指定されたときは、アスタリスクを ユーザ名で置換したものが使用されます。このような設定だと:

UserDir /var/www/*/docs

URL http://example.com/~rbowen/file.html は パス /var/www/rbowen/docs/file.html へ変換されます。

この機能を使用できるユーザを制限する

UserDir のドキュメントに示されている構文を使うことで、 どのユーザがこの機能を使うことができるかを制限することができます:

UserDir enabled
UserDir disabled root jro fish

上の設定は dissabled 文のユーザ以外のすべてのユーザに 対して UserDir の機能を有効にします。同様にして、以下のように 数名のユーザ以外に対してこの機能を無効にすることもできます:

UserDir disabled
UserDir enabled rbowen krietz

他の例は UserDir の説明を参照してください。

ユーザ毎の CGI ディレクトリ

それぞれのユーザに専用の cgi-bin ディレクトリを与えるために、 <Directory> を使ってユーザのホームディレクトリの指定された領域に対して CGI を有効に することができます。

<Directory /home/*/public_html/cgi-bin/>
Options ExecCGI
SetHandler cgi-script
</Directory>

そして、UserDir が public_html に設定されていると仮定すると、 そのディレクトリの CGI プログラム example.cgi は以下の様に呼び出されることができます:

http://example.com/~rbowen/cgi-bin/example.cgi

ユーザによる設定変更を許可

ユーザに彼らのウェブ空間でのサーバの設定の変更を許可する場合、 ユーザは .htaccess ファイルを使って設定を変更する必要があります。 AllowOverride の値を ユーザが変更することを許可したいディレクティブに対して十分なものに 設定していることを確認してください。この機能がどのようにして動作しているか の詳細は .htaccess チュートリアル を読んで ください。


Apache Tutorials - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Miscellaneous Documentation

Apache Tutorials

Warning:

This document has not been fully updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

The following documents give you step-by-step instructions on how to accomplish common tasks with the Apache HTTP server. Many of these documents are located at external sites and are not the work of the Apache Software Foundation. Copyright to documents on external sites is owned by the authors or their assignees. Please consult the official Apache Server documentation to verify what you read on external sites.

Installation & Getting Started

  • Getting Started with Apache 1.3 (ApacheToday)
  • Configuring Your Apache Server Installation (ApacheToday)
  • Getting, Installing, and Running Apache (on Unix) (O'Reilly Network Apache DevCenter)
  • Maximum Apache: Getting Started (CNET Builder.com)
  • How to Build the Apache of Your Dreams (Developer Shed)

Basic Configuration

  • An Amble Through Apache Configuration (O'Reilly Network Apache DevCenter)
  • Using .htaccess Files with Apache (ApacheToday)
  • Setting Up Virtual Hosts (ApacheToday)
  • Maximum Apache: Configure Apache (CNET Builder.com)
  • Getting More Out of Apache (Developer Shed)

Security

  • Security and Apache: An Essential Primer (LinuxPlanet)
  • Using User Authentication (Apacheweek)
  • DBM User Authentication (Apacheweek)
  • An Introduction to Securing Apache (Linux.com)
  • Securing Apache - Access Control (Linux.com)
  • Apache Authentication Part 1 - Part 2 - Part 3 - Part 4 (ApacheToday)
  • mod_access: Restricting Access by Host (ApacheToday)

Logging

  • Log Rhythms (O'Reilly Network Apache DevCenter)
  • Gathering Visitor Information: Customising Your Logfiles (Apacheweek)
  • Apache Guide: Logging Part 1 - Part 2 - Part 3 - Part 4 - Part 5 (ApacheToday)

CGI and SSI

  • Dynamic Content with CGI (ApacheToday)
  • The Idiot's Guide to Solving Perl CGI Problems (CPAN)
  • Executing CGI Scripts as Other Users (LinuxPlanet)
  • CGI Programming FAQ (Web Design Group)
  • Introduction to Server Side Includes Part 1 - Part 2 (ApacheToday)
  • Advanced SSI Techniques (ApacheToday)
  • Setting up CGI and SSI with Apache (CNET Builder.com)

Other Features

  • Content Negotiation Explained (Apacheweek)
  • Using Apache Imagemaps (Apacheweek)
  • Keeping Your Images from Adorning Other Sites (ApacheToday)
  • Language Negotiation Notes (Alan J. Flavell)

If you have a pointer to an accurate and well-written tutorial not included here, please let us know by submitting it to the Apache Bug Database.


Platform Specific Notes - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Platform Specific Notes

Microsoft Windows

Using Apache

This document explains how to install, configure and run Apache 2.0 under Microsoft Windows.

See: Using Apache with Microsoft Windows

Compiling Apache

There are many important points before you begin compiling Apache. This document explain them.

See: Compiling Apache for Microsoft Windows

Other Platforms

Novell NetWare

This document explains how to install, configure and run Apache 2.0 under Novell NetWare 5.1 and above.

See: Using Apache With Novell NetWare

EBCDIC

Version 1.3 of the Apache HTTP Server is the first version which includes a port to a (non-ASCII) mainframe machine which uses the EBCDIC character set as its native codeset.

Warning: This document has not been updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

See: The Apache EBCDIC Port


Using Apache with Microsoft Windows - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Platform Specific Notes

Using Apache with Microsoft Windows

This document explains how to install, configure and run Apache 2.0 under Microsoft Windows. If you find any bugs, or wish to contribute in other ways, please use our bug reporting page.

This document assumes that you are installing a binary distribution of Apache. If you want to compile Apache yourself (possibly to help with development or tracking down bugs), see Compiling Apache for Microsoft Windows.

Because of the current versioning policies on Microsoft Windows operating system families, this document assumes the following:

  • Windows NT: This means all versions of Windows that are based on the Windows NT kernel. Includes Windows NT, Windows 2000, Windows XP and Windows .Net Server 2003.
  • Windows 9x: This means older, consumer-oriented versions of Windows. Includes Windows 95 (also OSR2), Windows 98 and Windows ME.

Operating System Requirements

The primary Windows platform for running Apache 2.0 is Windows NT. The binary installer only works with the x86 family of processors, such as Intel and AMD processors. Running Apache on Windows 9x is not thoroughly tested, and it is never recommended on production systems.

On all operating systems, TCP/IP networking must be installed and working. If running on Windows 95, the Winsock 2 upgrade must be installed. Winsock 2 for Windows 95 can be downloaded from here.

On Windows NT 4.0, installing Service Pack 6 is strongly recommended, as Service Pack 4 created known issues with TCP/IP and Winsock integrity that were resolved in later Service Packs.

Downloading Apache for Windows

Information on the latest versions of Apache can be found on the web site of the Apache web server at http://httpd.apache.org/download.cgi. There you will find the current release, as well as more recent alpha or beta test versions, and a list of HTTP and FTP mirrors from which you can download the Apache web server. Please use a mirror near to you for a fast and reliable download.

For Windows installations you should download the version of Apache for Windows with the .msi extension. This is a single Microsoft Installer file, which contains a ready-to-run version of Apache. There is a separate .zip file, which contains only the source code. You can compile Apache yourself with the Microsoft Visual C++ (Visual Studio) tools.

Installing Apache for Windows

You need Microsoft Installer 1.2 or above for the installation to work. On Windows 9x you can update your Microsoft Installer to version 2.0 here and on Windows NT 4.0 and 2000 the version 2.0 update can be found here. Windows XP does not need this update.

Note that you cannot install two versions of Apache 2.0 on the same computer with the binary installer. You can, however, install a version of the 1.3 series and a version of the 2.0 series on the same computer without problems. If you need to have two different 2.0 versions on the same computer, you have to compile and install Apache from the source.

Run the Apache .msi file you downloaded above. The installation will ask you for these things:

  1. Network Domain. Enter the DNS domain in which your server is or will be registered in. For example, if your server's full DNS name is server.mydomain.net, you would type mydomain.net here.

  2. Server Name. Your server's full DNS name. From the example above, you would type server.mydomain.net here.

  3. Administrator's Email Address. Enter the server administrator's or webmaster's email address here. This address will be displayed along with error messages to the client by default.

  4. For whom to install Apache Select for All Users, on Port 80, as a Service - Recommended if you'd like your new Apache to listen at port 80 for incoming traffic. It will run as a service (that is, Apache will run even if no one is logged in on the server at the moment) Select only for the Current User, on Port 8080, when started Manually if you'd like to install Apache for your personal experimenting or if you already have another WWW server running on port 80.

  5. The installation type. Select Typical for everything except the source code and libraries for module development. With Custom you can specify what to install. A full install will require about 13 megabytes of free disk space. This does not include the size of your web site(s).

  6. Where to install. The default path is C:\Program Files\Apache Group under which a directory called Apache2 will be created by default.

During the installation, Apache will configure the files in the conf subdirectory to reflect the chosen installation directory. However, if any of the configuration files in this directory already exist, they will not be overwritten. Instead, the new copy of the corresponding file will be left with the extension .default. So, for example, if conf\httpd.conf already exists, it will be renamed as conf\httpd.conf.default. After the installation you should manually check to see what new settings are in the .default file, and if necessary, update your existing configuration file.

Also, if you already have a file called htdocs\index.html, it will not be overwritten (and no index.html.default will be installed either). This means it should be safe to install Apache over an existing installation, although you would have to stop the existing running server before doing the installation, and then start the new one after the installation is finished.

After installing Apache, you must edit the configuration files in the conf subdirectory as required. These files will be configured during the installation so that Apache is ready to be run from the directory it was installed into, with the documents server from the subdirectory htdocs. There are lots of other options which you should set before you really start using Apache. However, to get started quickly, the files should work as installed.

Customizing Apache for Windows

Apache is configured by the files in the conf subdirectory. These are the same files used to configure the Unix version, but there are a few different directives for Apache on Windows. See the directive index for all the available directives.

The main differences in Apache for Windows are:

  • Because Apache for Windows is multithreaded, it does not use a separate process for each request, as Apache does on Unix. Instead there are usually only two Apache processes running: a parent process, and a child which handles the requests. Within the child process each request is handled by a separate thread.

    The process management directives are also different:

    MaxRequestsPerChild: Like the Unix directive, this controls how many requests a single child process will serve before exiting. However, unlike on Unix, a single process serves all the requests at once, not just one. If this is set, it is recommended that a very high number is used. The recommended default, MaxRequestsPerChild 0, causes the child process to never exit.

    Warning: The server configuration file is reread when a new child process is started. If you have modified httpd.conf, the new child may not start or you may receive unexpected results.

    ThreadsPerChild: This directive is new. It tells the server how many threads it should use. This is the maximum number of connections the server can handle at once, so be sure to set this number high enough for your site if you get a lot of hits. The recommended default is ThreadsPerChild 50.

  • The directives that accept filenames as arguments must use Windows filenames instead of Unix ones. However, because Apache uses Unix-style names internally, you must use forward slashes, not backslashes. Drive letters can be used; if omitted, the drive with the Apache executable will be assumed.

  • Apache for Windows contains the ability to load modules at runtime, without recompiling the server. If Apache is compiled normally, it will install a number of optional modules in the \Apache2\modules directory. To activate these or other modules, the new LoadModule directive must be used. For example, to activate the status module, use the following (in addition to the status-activating directives in access.conf):

    LoadModule status_module modules/mod_status.so

    Information on creating loadable modules is also available.

  • Apache can also load ISAPI (Internet Server Application Programming Interface) extensions (i.e. internet server applications), such as those used by Microsoft IIS and other Windows servers. More information is available. Note that Apache cannot load ISAPI Filters.

  • When running CGI scripts, the method Apache uses to find the interpreter for the script is configurable using the ScriptInterpreterSource directive.

  • Since it is often difficult to manage files with names like .htaccess in Windows, you may find it useful to change the name of this per-directory configuration file using the AccessFilename directive.

  • Any errors during Apache startup are logged into the Windows event log when running on Windows NT. This mechanism acts as a backup for those situations where Apache cannot even access the normally used error.log file. You can view the Windows event log by using the Event Viewer application on Windows NT 4.0, and the Event Viewer MMC snap-in on newer versions of Windows.

    Note that there is no startup error logging on Windows 9x because no Windows event log exists on those operating systems.

Running Apache as a Service

Apache can be run as a service on Windows NT. There is some highly experimental support for similar behavior on Windows 9x.

You can install Apache as a service automatically during the installation. If you chose to install for all users, the installation will create an Apache service for you. If you specify to install for yourself only, you can manually register Apache as a service after the installation. You have to be a member of the Administrators group for the service installation to succeed.

Apache comes with a utility called the Apache Service Monitor. With it you can see and manage the state of all installed Apache services on any machine on your network. To be able to manage an Apache service with the monitor, you have to first install the service (either automatically via the installation or manually).

You can install Apache as a Windows NT service as follows from the command prompt at the Apache bin subdirectory:

apache -k install

If you need to specify the name of the service you want to install, use the following command. You have to do this if you have several different service installations of Apache on your computer.

apache -k install -n "MyServiceName"

If you need to have specifically named configuration files for different services, you must use this:

apache -k install -n "MyServiceName" -f "c:\files\my.conf"

If you use the first command without any special parameters except -k install, the service will be called Apache2 and the configuration will be assumed to be conf\httpd.conf.

Removing an Apache service is easy. Just use:

apache -k uninstall

The specific Apache service to be uninstalled can be specified by using:

apache -k uninstall -n "MyServiceName"

Normal starting, restarting and shutting down of an Apache service is usually done via the Apache Service Monitor, by using commands like NET START Apache2 and NET STOP Apache2 or via normal Windows service management. Before starting Apache as a service by any means, you should test the service's configuration file by using:

apache -n "MyServiceName" -t

You can control an Apache service by its command line switches, too. To start an installed Apache service you'll use this:

apache -k start

To stop an Apache service via the command line switches, use this:

apache -k stop

or

apache -k shutdown

You can also restart a running service and force it to reread its configuration file by using:

apache -k restart

By default, all Apache services are registered to run as the system user (the LocalSystem account). The LocalSystem account has no privileges to your network via any Windows-secured mechanism, including the file system, named pipes, DCOM, or secure RPC. It has, however, wide privileges locally.

Never grant any network privileges to the LocalSystem account! If you need Apache to be able to access network resources, create a separate account for Apache as noted below.

You may want to create a separate account for running Apache service(s). Especially, if you have to access network resources via Apache, this is strongly recommended.

  1. Create a normal domain user account, and be sure to memorize its password.
  2. Grant the newly-created user a privilege of Log on as a service and Act as part of the operating system. On Windows NT 4.0 these privileges are granted via User Manager for Domains, but on Windows 2000 and XP you probably want to use Group Policy for propagating these settings. You can also manually set these via the Local Security Policy MMC snap-in.
  3. Confirm that the created account is a member of the Users group.
  4. Grant the account read and execute (RX) rights to all document and script folders (htdocs and cgi-bin for example).
  5. Grant the account change (RWXD) rights to the Apache logs directory.
  6. Grant the account read and execute (RX) rights to the Apache.exe binary executable.
It is usually a good practice to grant the user the Apache service runs as read and execute (RX) access to the whole Apache2 directory, except the logs subdirectory, where the user has to have at least change (RWXD) rights.

If you allow the account to log in as a user and as a service, then you can log on with that account and test that the account has the privileges to execute the scripts, read the web pages, and that you can start Apache in a console window. If this works, and you have followed the steps above, Apache should execute as a service with no problems.

Error code 2186 is a good indication that you need to review the "Log On As" configuration for the service, since Apache cannot access a required network resource. Also, pay close attention to the privileges of the user Apache is configured to run as.

When starting Apache as a service you may encounter an error message from the Windows Service Control Manager. For example, if you try to start Apache by using the Services applet in the Windows Control Panel, you may get the following message:

Could not start the Apache2 service on \\COMPUTER
Error 1067; The process terminated unexpectedly.

You will get this generic error if there is any problem with starting the Apache service. In order to see what is really causing the problem you should follow the instructions for Running Apache for Windows from the Command Prompt.

There is some support for Apache on Windows 9x to behave in a similar manner as a service on Windows NT. It is highly experimental. It is not of production-class reliability, and its future is not guaranteed. It can be mostly regarded as a risky thing to play with - proceed with caution!

There are some differences between the two kinds of services you should be aware of:

  • Apache will attempt to start and if successful it will run in the background. If you run the command

    apache -n "MyServiceName" -k start

    via a shortcut on your desktop, for example, then if the service starts successfully, a console window will flash up but it immediately disappears. If Apache detects any errors on startup such as incorrect entries in the httpd.conf configuration file, the console window will remain visible. This will display an error message which will be useful in tracking down the cause of the problem.

  • Windows 9x does not support NET START or NET STOP commands. You must control the Apache service on the command prompt via the -k switches.

  • Apache and Windows 9x offer no support for running Apache as a specific user with network privileges. In fact, Windows 9x offers no security on the local machine, either. This is the simple reason because of which the Apache Software Foundation never endorses use of a Windows 9x -based system as a public Apache server. The primitive support for Windows 9x exists only to assist the user in developing web content and learning the Apache server, and perhaps as an intranet server on a secured, private network.

Once you have confirmed that Apache runs correctly as a console application you can install, control and uninstall the pseudo-service with the same commands as on Windows NT. You can also use the Apache Service Monitor to manage Windows 9x pseudo-services.

Running Apache as a Console Application

Running Apache as a service is usually the recommended way to use it, but it is sometimes easier to work from the command line (on Windows 9x running Apache from the command line is the recommended way due to the lack of reliable service support.)

To run Apache from the command line as a console application, use the following command:

apache

Apache will execute, and will remain running until it is stopped by pressing Control-C.

You can also run Apache via the shortcut Start Apache in Console placed to Start Menu --> Programs --> Apache HTTP Server 2.0.xx --> Control Apache Server during the installation. This will open a console window and start Apache inside it. If you don't have Apache installed as a service, the window will remain visible until you stop Apache by pressing Control-C in the console window where Apache is running in. The server will exit in a few seconds. However, if you do have Apache installed as a service, the shortcut starts the service. If the Apache service is running already, the shortcut doesn't do anything.

You can tell a running Apache to stop by opening another console window and entering:

apache -k shutdown

This should be preferred over pressing Control-C because this lets Apache end any current operations and clean up gracefully.

You can also tell Apache to restart. This forces it to reread the configuration file. Any operations in progress are allowed to complete without interruption. To restart Apache, use:

apache -k restart

Note for people familiar with the Unix version of Apache: these commands provide a Windows equivalent to kill -TERM pid and kill -USR1 pid. The command line option used, -k, was chosen as a reminder of the kill command used on Unix.

If the Apache console window closes immediately or unexpectedly after startup, open the Command Prompt from the Start Menu --> Programs. Change to the folder to which you installed Apache, type the command apache, and read the error message. Then change to the logs folder, and review the error.log file for configuration mistakes. If you accepted the defaults when you installed Apache, the commands would be:

c:
cd "\Program Files\Apache Group\Apache2\bin"
apache

Then wait for Apache to stop, or press Control-C. Then enter the following:

cd ..\logs
more < error.log

When working with Apache it is important to know how it will find the configuration file. You can specify a configuration file on the command line in two ways:

  • -f specifies an absolute or relative path to a particular configuration file:

    apache -f "c:\my server files\anotherconfig.conf"

    or

    apache -f files\anotherconfig.conf

  • -n specifies the installed Apache service whose configuration file is to be used:

    apache -n "MyServiceName"

In both of these cases, the proper ServerRoot should be set in the configuration file.

If you don't specify a configuration file with -f or -n, Apache will use the file name compiled into the server, such as conf\httpd.conf. This built-in path is relative to the installation directory. You can verify the compiled file name from a value labelled as SERVER_CONFIG_FILE when invoking Apache with the -V switch, like this:

apache -V

Apache will then try to determine its ServerRoot by trying the following, in this order:

  1. A ServerRoot directive via the -C command line switch.
  2. The -d switch on the command line.
  3. Current working directory.
  4. A registry entry which was created if you did a binary installation.
  5. The server root compiled into the server. This is /apache by default, you can verify it by using apache -V and looking for a value labelled as HTTPD_ROOT.

During the installation, a version-specific registry key is created in the Windows registry. The location of this key depends on the type of the installation. If you chose to install Apache for all users, the key is located under the HKEY_LOCAL_MACHINE hive, like this (the version numbers will of course vary between different versions of Apache:

HKEY_LOCAL_MACHINE\SOFTWARE\Apache Group\Apache\2.0.43

Correspondingly, if you chose to install Apache for the current user only, the key is located under the HKEY_CURRENT_USER hive, the contents of which are dependent of the user currently logged on:

HKEY_CURRENT_USER\SOFTWARE\Apache Group\Apache\2.0.43

This key is compiled into the server and can enable you to test new versions without affecting the current version. Of course, you must take care not to install the new version in the same directory as another version.

If you did not do a binary install, Apache will in some scenarios complain about the missing registry key. This warning can be ignored if the server was otherwise able to find its configuration file.

The value of this key is the ServerRoot directory which contains the conf subdirectory. When Apache starts it reads the httpd.conf file from that directory. If this file contains a ServerRoot directive which contains a different directory from the one obtained from the registry key above, Apache will forget the registry key and use the directory from the configuration file. If you copy the Apache directory or configuration files to a new location it is vital that you update the ServerRoot directive in the httpd.conf file to reflect the new location.

Testing the Installation

After starting Apache (either in a console window or as a service) it will be listening on port 80 (unless you changed the Listen directive in the configuration files or installed Apache only for the current user). To connect to the server and access the default page, launch a browser and enter this URL:

http://localhost/

Apache should respond with a welcome page and a link to the Apache manual. If nothing happens or you get an error, look in the error.log file in the logs subdirectory. If your host is not connected to the net, or if you have serious problems with your DNS (Domain Name Service) configuration, you may have to use this URL:

http://127.0.0.1/

Once your basic installation is working, you should configure it properly by editing the files in the conf subdirectory. Again, if you change the configuration of the Windows NT service for Apache, first attempt to start it from the command line to make sure that the service starts with no errors.

Because Apache cannot share the same port with another TCP/IP application, you may need to stop, uninstall or reconfigure certain other services before running Apache. These conflicting services include other WWW servers and some firewall implementations.


Compiling Apache for Microsoft Windows - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Platform Specific Notes

Compiling Apache for Microsoft Windows

There are many important points before you begin compiling Apache. See Using Apache with Microsoft Windows before you begin.

Requirements

Compiling Apache requires the following environment to be properly installed:

  • Disk Space

    Make sure you have at least 50 MB of free disk space available. After installation Apache requires approximately 10 MB of disk space, plus space for log and cache files, which can grow rapidly. The actual disk space requirements will vary considerably based on your chosen configuration and any third-party modules or libraries.

  • Microsoft Visual C++ 5.0 or higher.

    Apache can be built using the command line tools, or from within the Visual Studio IDE Workbench. The command line build requires the environment to reflect the PATH, INCLUDE, LIB and other variables that can be configured with the vcvars32 batch file:

    "c:\Program Files\DevStudio\VC\Bin\vcvars32.bat"

  • The Windows Platform SDK.

    Visual C++ 5.0 builds require an updated Microsoft Windows Platform SDK to enable some Apache features. For command line builds, the Platform SDK environment is prepared by the setenv batch file:

    "c:\Program Files\Platform SDK\setenv.bat"

    The Platform SDK files distributed with Visual C++ 6.0 and later are sufficient, so users of later version may skip this requirement.

    Note that the Windows Platform SDK update is required to enable all supported mod_isapi features. Without a recent update, Apache will issue warnings under MSVC++ 5.0 that some mod_isapi features will be disabled. Look for the update at http://msdn.microsoft.com/downloads/sdks/platform/platform.asp.

  • The awk utility (awk, gawk or similar).

    To install Apache within the build system, several files are modified using the awk.exe utility. awk was chosen since it is a very small download (compared with Perl or WSH/VB) and accomplishes the task of generating files. Brian Kernighan's http://cm.bell-labs.com/cm/cs/who/bwk/ site has a compiled native Win32 binary, http://cm.bell-labs.com/cm/cs/who/bwk/awk95.exe which you must save with the name awk.exe rather than awk95.exe.

    Note that Developer Studio IDE will only find awk.exe from the Tools menu Options... Directories tab (the Projects - VC++ Directories pane in Developer Studio 7.0) listing Executable file paths. Add the path for awk.exe to this list, and your system PATH environment variable, as needed.
    Also note that if you are using Cygwin (http://www.cygwin.com/) the awk utility is named gawk.exe and that the file awk.exe is really a symlink to the gawk.exe file. The Windows command shell does not recognize symlinks, and because of that building InstallBin will fail. A workaround is to delete awk.exe from the cygwin installation and rename gawk.exe to awk.exe.

  • [Optional] OpenSSL libraries (for mod_ssl and ab.exe with ssl support)

    Caution: there are significant restrictions and prohibitions on the use and distribution of strong cryptography and patented intellectual property throughout the world. OpenSSL includes strong cryptography controlled by both export regulations and domestic law, as well as intellectual property protected by patent, in the United States and elsewhere. Neither the Apache Software Foundation nor the OpenSSL project can provide legal advise regarding possession, use, or distribution of the code provided by the OpenSSL project. Consult your own legal counsel, you are responsible for your own actions.

    OpenSSL must be installed into a srclib subdirectory named openssl, obtained from http://www.openssl.org/source/, in order to compile mod_ssl or the abs project (ab.exe with SSL support.) To prepare OpenSSL for both release and debug builds of Apache, and disable the patent protected features in 0.9.7, you might use the following build commands:

    perl Configure VC-WIN32
    perl util\mkfiles.pl >MINFO
    perl util\mk1mf.pl dll no-asm no-mdc2 no-rc5 no-idea VC-WIN32 >makefile
    perl util\mk1mf.pl dll debug no-asm no-mdc2 no-rc5 no-idea VC-WIN32 >makefile.dbg
    perl util\mkdef.pl 32 libeay no-asm no-mdc2 no-rc5 no-idea >ms\libeay32.def
    perl util\mkdef.pl 32 ssleay no-asm no-mdc2 no-rc5 no-idea >ms\ssleay32.def
    nmake
    nmake -f makefile.dbg

  • [Optional] zlib sources (for mod_deflate)

    Zlib must be installed into a srclib subdirectory named zlib, however those sources need not be compiled. The build system will compile the compression sources directly into the mod_deflate module. Zlib can be obtained from http://www.gzip.org/zlib/ -- mod_deflate is confirmed to build correctly with version 1.1.4.

Command-Line Build

First, unpack the Apache distribution into an appropriate directory. Open a command-line prompt and cd to that directory.

The master Apache makefile instructions are contained in the Makefile.win file. To compile Apache on Windows NT, simply use one of the following commands to compiled the release or debug build, respectively:

nmake /f Makefile.win _apacher

nmake /f Makefile.win _apached

Either command will compile Apache. The latter will include debugging information in the resulting files, making it easier to find bugs and track down problems.

Developer Studio Workspace IDE Build

Apache can also be compiled using VC++'s Visual Studio development environment. To simplify this process, a Visual Studio workspace, Apache.dsw, is provided. This workspace exposes the entire list of working .dsp projects that are required for the complete Apache binary release. It includes dependencies between the projects to assure that they are built in the appropriate order.

Open the Apache.dsw workspace, and select InstallBin (Release or Debug build, as desired) as the Active Project. InstallBin causes all related project to be built, and then invokes Makefile.win to move the compiled executables and dlls. You may personalize the INSTDIR= choice by changing InstallBin's Settings, General tab, Build command line entry. INSTDIR defaults to the /Apache2 directory. If you only want a test compile (without installing) you may build the BuildBin project instead.

The .dsp project files are distributed in Visual C++ 6.0 format. Visual C++ 5.0 (97) will recognize them. Visual C++ 7.0 (.net) must convert Apache.dsw plus the .dsp files into an Apache.sln plus .msproj files, be sure you reconvert the .msproj file if any of the source .dsp files change! This is really trivial, just open Apache.dsw in the VC++ 7.0 IDE once again.

Visual C++ 7.0 (.net) users should also use the Build menu, Configuration Manager dialog to uncheck both the Debug and Release Solution modules abs, mod_ssl and mod_deflate. These modules are built by invoking nmake or the IDE directly with the BinBuild target to build those modules explicitly, only if the srclib directories openssl and/or zlib exist.

Exported .mak files pose a greater hassle, but they are required for Visual C++ 5.0 users to build mod_ssl, abs (ab with SSL support) and/or mod_deflate. VC++ 7.0 (.net) users also benefit, nmake builds are faster than binenv builds. Build the entire project from within the VC++ 5.0 or 6.0 IDE, then use the Project Menu Export for all makefiles. You must build the projects first in order to create all dynamic auto-generated targets, so that dependencies can be parsed correctly. Run the following command to fix the paths so they will build anywhere:

perl srclib\apr\build\fixwin32mak.pl

You must type this command from the top level directory of the httpd source tree. Every .mak and .dep project file within the current directory and below will be corrected, and the timestamps adjusted to reflect the .dsp.

If you contribute back a patch that revises project files, we must commit project files in Visual Studio 6.0 format. Changes should be simple, with minimal compilation and linkage flags that will be recognized by all VC++ 5.0 through 7.0 environments.

Project Components

The Apache.dsw workspace and makefile.win nmake script both build the .dsp projects of the Apache server in the following sequence:

  1. srclib\apr\apr.dsp
  2. srclib\apr\libapr.dsp
  3. srclib\apr-util\uri\gen_uri_delims.dsp
  4. srclib\apr-util\xml\expat\lib\xml.dsp
  5. srclib\apr-util\aprutil.dsp
  6. srclib\apr-util\libaprutil.dsp
  7. srclib\pcre\dftables.dsp
  8. srclib\pcre\pcre.dsp
  9. srclib\pcre\pcreposix.dsp
  10. server\gen_test_char.dsp
  11. libhttpd.dsp
  12. Apache.dsp

In addition, the modules\ subdirectory tree contains project files for the majority of the modules.

The support\ directory contains project files for additional programs that are not part of the Apache runtime, but are used by the administrator to test Apache and maintain password and log files. Windows-specific support projects are broken out in the support\win32\ directory.

  1. support\ab.dsp
  2. support\htdigest.dsp
  3. support\htpasswd.dsp
  4. support\logresolve.dsp
  5. support\rotatelogs.dsp
  6. support\win32\ApacheMonitor.dsp
  7. support\win32\wintty.dsp

Once Apache has been compiled, it needs to be installed in its server root directory. The default is the \Apache2 directory, of the same drive.

To build and install all the files into the desired folder dir automatically, use one of the following nmake commands:

nmake /f Makefile.win installr INSTDIR=dir

nmake /f Makefile.win installd INSTDIR=dir

The dir argument to INSTDIR gives the installation directory; it can be omitted if Apache is to be installed into \Apache2.

This will install the following:

  • dir\bin\Apache.exe - Apache executable
  • dir\bin\ApacheMonitor.exe - Service monitor taskbar icon utility
  • dir\bin\htdigest.exe - Digest auth password file utility
  • dir\bin\htdbm.exe - SDBM auth database password file utility
  • dir\bin\htpasswd.exe - Basic auth password file utility
  • dir\bin\logresolve.exe - Log file dns name lookup utility
  • dir\bin\rotatelogs.exe - Log file cycling utility
  • dir\bin\wintty.exe - Console window utility
  • dir\bin\libapr.dll - Apache Portable Runtime shared library
  • dir\bin\libaprutil.dll - Apache Utility Runtime shared library
  • dir\bin\libhttpd.dll - Apache Core library
  • dir\modules\mod_*.so - Loadable Apache modules
  • dir\conf - Configuration directory
  • dir\logs - Empty logging directory
  • dir\include - C language header files
  • dir\lib - Link library files

Warning about building Apache from the development tree

Note only the .dsp files are maintained between release builds. The .mak files are NOT regenerated, due to the tremendous waste of reviewer's time. Therefore, you cannot rely on the NMAKE commands above to build revised .dsp project files unless you then export all .mak files yourself from the project. This is unnecessary if you build from within the Microsoft Developer Studio environment.
Also note it is very worthwhile to build the BuildBin target project (or the command line _apacher or _apached target) prior to exporting the make files. Many files are autogenerated in the build process. Only a full build provides all of the dependent files required to build proper dependency trees for correct build behavior.

In order to create distribution .mak files, always review the generated .mak (or .dep) dependencies for Platform SDK or other garbage includes. The DevStudio\SharedIDE\bin\ (VC5) or DevStudio\Common\MSDev98\bin\ (VC6) directory contains the sysincl.dat file, which must list all exceptions. Update this file (including both forward and backslashed paths, such as both sys/time.h and sys\time.h) to include such dependencies. Including local-install paths in a distributed .mak file will cause the build to fail completely. And don't forget to run srclib/apr/build/fixwin32mak.pl in order to fix absolute paths within the .mak files.


Using Apache With Novell NetWare - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Platform Specific Notes

Using Apache With Novell NetWare

This document explains how to install, configure and run Apache 2.0 under Novell NetWare 6.0 and above. If you find any bugs, or wish to contribute in other ways, please use our bug reporting page.

The bug reporting page and dev-httpd mailing list are not provided to answer questions about configuration or running Apache. Before you submit a bug report or request, first consult this document, the Frequently Asked Questions page and the other relevant documentation topics. If you still have a question or problem, post it to the novell.devsup.webserver newsgroup, where many Apache users are more than willing to answer new and obscure questions about using Apache on NetWare.

Most of this document assumes that you are installing Apache from a binary distribution. If you want to compile Apache yourself (possibly to help with development, or to track down bugs), see the section on Compiling Apache for NetWare below.

Requirements

Apache 2.0 is designed to run on NetWare 6.0 service pack 3 and above. If you are running a service pack less than SP3, you must install the latest NetWare Libraries for C (LibC).

NetWare service packs are available here.

Apache 2.0 for NetWare can also be run in a NetWare 5.1 environment as long as the latest service pack or the latest version of the NetWare Libraries for C (LibC) has been installed . WARNING: Apache 2.0 for NetWare has not been targeted for or tested in this environment.

Downloading Apache for NetWare

Information on the latest version of Apache can be found on the Apache web server at http://www.apache.org/. This will list the current release, any more recent alpha or beta-test releases, together with details of mirror web and anonymous ftp sites. Binary builds of the latest releases of Apache 2.0 for NetWare can be downloaded from here.

Installing Apache for NetWare

There is no Apache install program for NetWare currently. If you are building Apache 2.0 for NetWare from source, you will need to copy the files over to the server manually.

Follow these steps to install Apache on NetWare from the binary download (assuming you will install to sys:/apache2):

  • Unzip the binary download file to the root of the SYS: volume (may be installed to any volume)
  • Edit the httpd.conf file setting ServerRoot and ServerName along with any file path values to reflect your correct server settings
  • Add SYS:/APACHE2 to the search path, for example:

    SEARCH ADD SYS:\APACHE2

Follow these steps to install Apache on NetWare manually from your own build source (assuming you will install to sys:/apache2):

  • Create a directory called Apache2 on a NetWare volume
  • Copy APACHE2.NLM, APRLIB.NLM to SYS:/APACHE2
  • Create a directory under SYS:/APACHE2 called BIN
  • Copy HTDIGEST.NLM, HTPASSWD.NLM, HTDBM.NLM, LOGRES.NLM, ROTLOGS.NLM to SYS:/APACHE2/BIN
  • Create a directory under SYS:/APACHE2 called CONF
  • Copy the HTTPD-STD.CONF file to the SYS:/APACHE2/CONF directory and rename to HTTPD.CONF
  • Copy the MIME.TYPES, CHARSET.CONV and MAGIC files to SYS:/APACHE2/CONF directory
  • Copy all files and subdirectories in \HTTPD-2.0\DOCS\ICONS to SYS:/APACHE2/ICONS
  • Copy all files and subdirectories in \HTTPD-2.0\DOCS\MANUAL to SYS:/APACHE2/MANUAL
  • Copy all files and subdirectories in \HTTPD-2.0\DOCS\ERROR to SYS:/APACHE2/ERROR
  • Copy all files and subdirectories in \HTTPD-2.0\DOCS\DOCROOT to SYS:/APACHE2/HTDOCS
  • Create the directory SYS:/APACHE2/LOGS on the server
  • Create the directory SYS:/APACHE2/CGI-BIN on the server
  • Create the directory SYS:/APACHE2/MODULES and copy all nlm modules into the modules directory
  • Edit the HTTPD.CONF file searching for all @@Value@@ markers and replacing them with the appropriate setting
  • Add SYS:/APACHE2 to the search path, for example:

    SEARCH ADD SYS:\APACHE2

Apache may be installed to other volumes besides the default SYS volume.

During the build process, adding the keyword "install" to the makefile command line will automatically produce a complete distribution package under the subdirectory DIST. Install Apache by simply copying the distribution that was produced by the makfiles to the root of a NetWare volume (see: Compiling Apache for NetWare below).

Running Apache for NetWare

To start Apache just type apache at the console. This will load apache in the OS address space. If you prefer to load Apache in a protected address space you may specify the address space with the load statement as follows:

load address space = apache2 apache2

This will load Apache into an address space called apache2. Running multiple instances of Apache concurrently on NetWare is possible by loading each instance into its own protected address space.

After starting Apache, it will be listening to port 80 (unless you changed the Listen directive in the configuration files). To connect to the server and access the default page, launch a browser and enter the server's name or address. This should respond with a welcome page, and a link to the Apache manual. If nothing happens or you get an error, look in the error_log file in the logs directory.

Once your basic installation is working, you should configure it properly by editing the files in the conf directory.

To unload Apache running in the OS address space just type the following at the console:

unload apache2

or

apache2 shutdown

If apache is running in a protected address space specify the address space in the unload statement:

unload address space = apache2 apache2

When working with Apache it is important to know how it will find the configuration files. You can specify a configuration file on the command line in two ways:

  • -f specifies a path to a particular configuration file

apache2 -f "vol:/my server/conf/my.conf"

apache -f test/test.conf

In these cases, the proper ServerRoot should be set in the configuration file.

If you don't specify a configuration file name with -f, Apache will use the file name compiled into the server, usually conf/httpd.conf. Invoking Apache with the -V switch will display this value labeled as SERVER_CONFIG_FILE. Apache will then determine its ServerRoot by trying the following, in this order:

  • A ServerRoot directive via a -C switch.
  • The -d switch on the command line.
  • Current working directory
  • The server root compiled into the server.

The server root compiled into the server is usually sys:/apache2. invoking apache with the -V switch will display this value labeled as HTTPD_ROOT.

Apache 2.0 for NetWare includes a set of command line directives that can be used to modify or display information about the running instance of the web server. These directives are only available while Apache is running. Each of these directives must be preceded by the keyword APACHE2.

RESTART
Instructs Apache to terminate all running worker threads as they become idle, reread the configuration file and restart each worker thread based on the new configuration.
VERSION
Displays version information about the currently running instance of Apache.
MODULES
Displays a list of loaded modules both built-in and external.
DIRECTIVES
Displays a list of all available directives.
SETTINGS
Enables or disables the thread status display on the console. When enabled, the state of each running threads is displayed on the Apache console screen.
SHUTDOWN
Terminates the running instance of the Apache web server.
HELP
Describes each of the runtime directives.

By default these directives are issued against the instance of Apache running in the OS address space. To issue a directive against a specific instance running in a protected address space, include the -p parameter along with the name of the address space. For more information type "apache2 Help" on the command line.

Configuring Apache for NetWare

Apache is configured by reading configuration files usually stored in the conf directory. These are the same as files used to configure the Unix version, but there are a few different directives for Apache on NetWare. See the Apache documentation for all the available directives.

The main differences in Apache for NetWare are:

  • Because Apache for NetWare is multithreaded, it does not use a separate process for each request, as Apache does on some Unix implementations. Instead there are only threads running: a parent thread, and multiple child or worker threads which handle the requests.

    Therefore the "process"-management directives are different:

    MaxRequestsPerChild - Like the Unix directive, this controls how many requests a worker thread will serve before exiting. The recommended default, MaxRequestsPerChild 0, causes the thread to continue servicing request indefinitely. It is recommended on NetWare, unless there is some specific reason, that this directive always remain set to 0.

    StartThreads - This directive tells the server how many threads it should start initially. The recommended default is StartThreads 50.

    MinSpareThreads - This directive instructs the server to spawn additional worker threads if the number of idle threads ever falls below this value. The recommended default is MinSpareThreads 10.

    MaxSpareThreads - This directive instructs the server to begin terminating worker threads if the number of idle threads ever exceeds this value. The recommended default is MaxSpareThreads 100.

    MaxThreads - This directive limits the total number of work threads to a maximum value. The recommended default is ThreadsPerChild 250.

    ThreadStackSize - This directive tells the server what size of stack to use for the individual worker thread. The recommended default is ThreadStackSize 65536.

  • The directives that accept filenames as arguments must use NetWare filenames instead of Unix names. However, because Apache uses Unix-style names internally, forward slashes must be used rather than backslashes. It is recommended that all rooted file paths begin with a volume name. If omitted, Apache will assume the SYS: volume which may not be correct.

  • Apache for NetWare has the ability to load modules at runtime, without recompiling the server. If Apache is compiled normally, it will install a number of optional modules in the \Apache2\modules directory. To activate these, or other modules, the LoadModule directive must be used. For example, to active the status module, use the following:

    LoadModule status_module modules/status.nlm

    Information on creating loadable modules is also available.

Additional NetWare specific directives:

  • CGIMapExtension - This directive maps a CGI file extension to a script interpreter.
  • SecureListen - Enables SSL encryption for a specified port.
  • NWSSLTrustedCerts - Adds trusted certificates that are used to create secure connections to proxied servers.
  • NWSSLUpgradeable - Allow a connection created on the specified address/port to be upgraded to an SSL connection.

Compiling Apache for NetWare

Compiling Apache requires MetroWerks CodeWarrior 6.x or higher. Once Apache has been built, it can be installed to the root of any NetWare volume. The default is the sys:/Apache2 directory.

Before running the server you must fill out the conf directory. Copy the file HTTPD-STD.CONF from the distribution conf directory and rename it to HTTPD.CONF. Edit the HTTPD.CONF file searching for all @@Value@@ markers and replacing them with the appropriate setting. Copy over the conf/magic and conf/mime.types files as well. Alternatively, a complete distribution can be built by including the keyword install when invoking the makefiles.

Requirements:

The following development tools are required to build Apache 2.0 for NetWare:

  • Metrowerks CodeWarrior 6.0 or higher with the NetWare PDK 3.0 or higher.
  • NetWare Libraries for C (LibC)
  • LDAP Libraries for C
  • ZLIB Compression Library source code
  • AWK utility (awk, gawk or similar). AWK can be downloaded from http://developer.novell.com/ndk/apache.htm. The utility must be found in your windows path and must be named awk.exe.
  • To build using the makefiles, you will need GNU make version 3.78.1 (GMake) available at http://developer.novell.com/ndk/apache.htm.

Building Apache using the NetWare makefiles:

  • Set the environment variable NOVELLLIBC to the location of the NetWare Libraries for C SDK, for example:

    Set NOVELLLIBC=c:\novell\ndk\libc

  • Set the environment variable METROWERKS to the location where you installed the Metrowerks CodeWarrior compiler, for example:

    Set METROWERKS=C:\Program Files\Metrowerks\CodeWarrior

    If you installed to the default location C:\Program Files\Metrowerks\CodeWarrior, you don't need to set this.
  • Set the environment variable LDAPSDK to the location where you installed the LDAP Libraries for C, for example:

    Set LDAPSDK=c:\Novell\NDK\cldapsdk\NetWare\libc

  • Set the environment variable ZLIBSDK to the location where you installed the source code for the ZLib Library, for example:

    Set ZLIBSDK=D:\NOVELL\zlib

  • Set the environment variable AP_WORK to the full path of the \httpd-2.0 directory.
  • Set the environment variable APR_WORK to the full path of the \httpd-2.0\srclib\apr directory.
  • Make sure that the path to the AWK utility and the GNU make utility (gmake.exe) have been included in the system's PATH environment variable.
  • Download the source code and unzip to an appropriate directory on your workstation.
  • Change directory to \httpd-2.0\srclib\apr-util\uri and build GENURI.nlm by running "gmake -f nwgnumakefile".
  • Copy the file GENURI.nlm to the SYS: volume of a NetWare server and run using the following command:

    SYS:\genuri > sys:\uri_delims.h

  • Copy the file uri_delims.h to the directory \httpd-2.0\srclib\apr-util\uri on the build machine.
  • Change directory to \httpd-2.0\srclib\apr and build APR by running "gmake -f nwgnumakefile"
  • Change directory to \httpd-2.0\srclib\pcre and build DFTABLES.nlm by running "gmake -f nwgnumakefile"
  • Change directory to \httpd-2.0\server and build GENCHARS.nlm by running "gmake -f nwgnumakefile"
  • Copy the files GENCHARS.nlm and DFTABLES.nlm from their respective directories to the SYS: volume of a NetWare server and run them using the following commands:

    SYS:\genchars > sys:\test_char.h
    SYS:\dftables > sys:\chartables.c

  • Copy the files test_char.h and chartables.c to the directory \httpd-2.0\os\netware on the build machine.
  • Change directory to \httpd-2.0 and build Apache by running "gmake -f nwgnumakefile". You can create a distribution directory by adding an install parameter to the command, for example:

    gmake -f nwgnumakefile install

Additional make options

  • gmake -f nwgnumakefile

    Builds release versions of all of the binaries and copies them to a \release destination directory.

  • gmake -f nwgnumakefile DEBUG=1

    Builds debug versions of all of the binaries and copies them to a \debug destination directory.

  • gmake -f nwgnumakefile install

    Creates a complete Apache distribution with binaries, docs and additional support files in a \dist\Apache2 directory.

  • gmake -f nwgnumakefile installdev

    Same as install but also creates a \lib and \include directory in the destination directory and copies headers and import files.

  • gmake -f nwgnumakefile clean

    Cleans all object files and binaries from the \release or \debug build areas depending on whether DEBUG has been defined.

  • gmake -f nwgnumakefile clobber_all

    Same as clean and also deletes the distribution directory if it exists.


Running a High-Performance Web Server on HPUX - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Platform Specific Notes

Running a High-Performance Web Server on HPUX

Date: Wed, 05 Nov 1997 16:59:34 -0800
From: Rick Jones <raj@cup.hp.com>
Reply-To: raj@cup.hp.com
Organization: Network Performance
Subject: HP-UX tuning tips

Here are some tuning tips for HP-UX to add to the tuning page.

For HP-UX 9.X: Upgrade to 10.20
For HP-UX 10.[00|01|10]: Upgrade to 10.20

For HP-UX 10.20:

Install the latest cumulative ARPA Transport Patch. This will allow you to configure the size of the TCP connection lookup hash table. The default is 256 buckets and must be set to a power of two. This is accomplished with adb against the *disc* image of the kernel. The variable name is tcp_hash_size. Notice that it's critically important that you use "W" to write a 32 bit quantity, not "w" to write a 16 bit value when patching the disc image because the tcp_hash_size variable is a 32 bit quantity.

How to pick the value? Examine the output of ftp://ftp.cup.hp.com/dist/networking/tools/connhist and see how many total TCP connections exist on the system. You probably want that number divided by the hash table size to be reasonably small, say less than 10. Folks can look at HP's SPECweb96 disclosures for some common settings. These can be found at http://www.specbench.org/. If an HP-UX system was performing at 1000 SPECweb96 connections per second, the TIME_WAIT time of 60 seconds would mean 60,000 TCP "connections" being tracked.

Folks can check their listen queue depths with ftp://ftp.cup.hp.com/dist/networking/misc/listenq.

If folks are running Apache on a PA-8000 based system, they should consider "chatr'ing" the Apache executable to have a large page size. This would be "chatr +pi L <BINARY>". The GID of the running executable must have MLOCK privileges. Setprivgrp(1m) should be consulted for assigning MLOCK. The change can be validated by running Glance and examining the memory regions of the server(s) to make sure that they show a non-trivial fraction of the text segment being locked.

If folks are running Apache on MP systems, they might consider writing a small program that uses mpctl() to bind processes to processors. A simple pid % numcpu algorithm is probably sufficient. This might even go into the source code.

If folks are concerned about the number of FIN_WAIT_2 connections, they can use nettune to shrink the value of tcp_keepstart. However, they should be careful there - certainly do not make it less than oh two to four minutes. If tcp_hash_size has been set well, it is probably OK to let the FIN_WAIT_2's take longer to timeout (perhaps even the default two hours) - they will not on average have a big impact on performance.

There are other things that could go into the code base, but that might be left for another email. Feel free to drop me a message if you or others are interested.

sincerely,

rick jones

http://www.cup.hp.com/netperf/NetperfPage.html


The Apache EBCDIC Port - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Platform Specific Notes

The Apache EBCDIC Port

Warning: This document has not been updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

Overview of the Apache EBCDIC Port

Version 1.3 of the Apache HTTP Server is the first version which includes a port to a (non-ASCII) mainframe machine which uses the EBCDIC character set as its native codeset.

(It is the SIEMENS family of mainframes running the BS2000/OSD operating system. This mainframe OS nowadays features a SVR4-derived POSIX subsystem).

The port was started initially to

  • prove the feasibility of porting the Apache HTTP server to this platform
  • find a "worthy and capable" successor for the venerable CERN-3.0 daemon (which was ported a couple of years ago), and to
  • prove that Apache's preforking process model can on this platform easily outperform the accept-fork-serve model used by CERN by a factor of 5 or more.

This document serves as a rationale to describe some of the design decisions of the port to this machine.

Design Goals

One objective of the EBCDIC port was to maintain enough backwards compatibility with the (EBCDIC) CERN server to make the transition to the new server attractive and easy. This required the addition of a configurable method to define whether a HTML document was stored in ASCII (the only format accepted by the old server) or in EBCDIC (the native document format in the POSIX subsystem, and therefore the only realistic format in which the other POSIX tools like grep or sed could operate on the documents). The current solution to this is a "pseudo-MIME-format" which is intercepted and interpreted by the Apache server (see below). Future versions might solve the problem by defining an "ebcdic-handler" for all documents which must be converted.

Technical Solution

Since all Apache input and output is based upon the BUFF data type and its methods, the easiest solution was to add the conversion to the BUFF handling routines. The conversion must be settable at any time, so a BUFF flag was added which defines whether a BUFF object has currently enabled conversion or not. This flag is modified at several points in the HTTP protocol:

  • set before a request is received (because the request and the request header lines are always in ASCII format)
  • set/unset when the request body is received - depending on the content type of the request body (because the request body may contain ASCII text or a binary file)
  • set before a reply header is sent (because the response header lines are always in ASCII format)
  • set/unset when the response body is sent - depending on the content type of the response body (because the response body may contain text or a binary file)

Porting Notes

  1. The relevant changes in the source are #ifdef'ed into two categories:

    #ifdef CHARSET_EBCDIC

    Code which is needed for any EBCDIC based machine. This includes character translations, differences in contiguity of the two character sets, flags which indicate which part of the HTTP protocol has to be converted and which part doesn't etc.

    #ifdef _OSD_POSIX

    Code which is needed for the SIEMENS BS2000/OSD mainframe platform only. This deals with include file differences and socket implementation topics which are only required on the BS2000/OSD platform.

  2. The possibility to translate between ASCII and EBCDIC at the socket level (on BS2000 POSIX, there is a socket option which supports this) was intentionally not chosen, because the byte stream at the HTTP protocol level consists of a mixture of protocol related strings and non-protocol related raw file data. HTTP protocol strings are always encoded in ASCII (the GET request, any Header: lines, the chunking information etc.) whereas the file transfer parts (i.e., GIF images, CGI output etc.) should usually be just "passed through" by the server. This separation between "protocol string" and "raw data" is reflected in the server code by functions like bgets() or rvputs() for strings, and functions like bwrite() for binary data. A global translation of everything would therefore be inadequate.

    (In the case of text files of course, provisions must be made so that EBCDIC documents are always served in ASCII)

  3. This port therefore features a built-in protocol level conversion for the server-internal strings (which the compiler translated to EBCDIC strings) and thus for all server-generated documents. The hard coded ASCII escapes \012 and \015 which are ubiquitous in the server code are an exception: they are already the binary encoding of the ASCII \n and \r and must not be converted to ASCII a second time. This exception is only relevant for server-generated strings; and external EBCDIC documents are not expected to contain ASCII newline characters.

  4. By examining the call hierarchy for the BUFF management routines, I added an "ebcdic/ascii conversion layer" which would be crossed on every puts/write/get/gets, and a conversion flag which allowed enabling/disabling the conversions on-the-fly. Usually, a document crosses this layer twice from its origin source (a file or CGI output) to its destination (the requesting client): file -> Apache, and Apache -> client.

    The server can now read the header lines of a CGI-script output in EBCDIC format, and then find out that the remainder of the script's output is in ASCII (like in the case of the output of a WWW Counter program: the document body contains a GIF image). All header processing is done in the native EBCDIC format; the server then determines, based on the type of document being served, whether the document body (except for the chunking information, of course) is in ASCII already or must be converted from EBCDIC.

  5. For Text documents (MIME types text/plain, text/html etc.), an implicit translation to ASCII can be used, or (if the users prefer to store some documents in raw ASCII form for faster serving, or because the files reside on a NFS-mounted directory tree) can be served without conversion.

    Example:

    to serve files with the suffix .ahtml as a raw ASCII text/html document without implicit conversion (and suffix .ascii as ASCII text/plain), use the directives:

    AddType text/x-ascii-html .ahtml
    AddType text/x-ascii-plain .ascii

    Similarly, any text/foo MIME type can be served as "raw ASCII" by configuring a MIME type "text/x-ascii-foo" for it using AddType.

  6. Non-text documents are always served "binary" without conversion. This seems to be the most sensible choice for, .e.g., GIF/ZIP/AU file types. This of course requires the user to copy them to the mainframe host using the "rcp -b" binary switch.

  7. Server parsed files are always assumed to be in native (i.e., EBCDIC) format as used on the machine, and are converted after processing.

  8. For CGI output, the CGI script determines whether a conversion is needed or not: by setting the appropriate Content-Type, text files can be converted, or GIF output can be passed through unmodified. An example for the latter case is the wwwcount program which we ported as well.

Document Storage Notes

Binary Files

All files with a Content-Type: which does not start with text/ are regarded as binary files by the server and are not subject to any conversion. Examples for binary files are GIF images, gzip-compressed files and the like.

When exchanging binary files between the mainframe host and a Unix machine or Windows PC, be sure to use the ftp "binary" (TYPE I) command, or use the rcp -b command from the mainframe host (the -b switch is not supported in unix rcp's).

Text Documents

The default assumption of the server is that Text Files (i.e., all files whose Content-Type: starts with text/) are stored in the native character set of the host, EBCDIC.

Server Side Included Documents

SSI documents must currently be stored in EBCDIC only. No provision is made to convert it from ASCII before processing.

Apache Modules' Status

Module | Status | Notes
core | + |
mod_access | + |
mod_actions | + |
mod_alias | + |
mod_asis | + |
mod_auth | + |
mod_auth_anon | + |
mod_auth_dbm | ? | with own libdb.a
mod_autoindex | + |
mod_cern_meta | ? |
mod_cgi | + |
mod_digest | + |
mod_dir | + |
mod_so | - | no shared libs
mod_env | + |
mod_example | - | (test bed only)
mod_expires | + |
mod_headers | + |
mod_imap | + |
mod_include | + |
mod_info | + |
mod_log_agent | + |
mod_log_config | + |
mod_log_referer | + |
mod_mime | + |
mod_mime_magic | ? | not ported yet
mod_negotiation | + |
mod_proxy | + |
mod_rewrite | + | untested
mod_setenvif | + |
mod_speling | + |
mod_status | + |
mod_unique_id | + |
mod_userdir | + |
mod_usertrack | ? | untested

Third Party Modules' Status

Module | Status | Notes
mod_jserv | - | JAVA still being ported.
mod_php3 | + | mod_php3 runs fine, with LDAP and GD and FreeType libraries.
mod_put | ? | untested
mod_session | - | untested


Server and Supporting Programs - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Server and Supporting Programs

This page documents all the executable programs included with the Apache HTTP Server.

Index

httpd
Apache hypertext transfer protocol server
apachectl
Apache HTTP server control interface
ab
Apache HTTP server benchmarking tool
apxs
APache eXtenSion tool
configure
Configure the source tree
dbmmanage
Create and update user authentication files in DBM format for basic authentication
htdigest
Create and update user authentication files for digest authentication
htpasswd
Create and update user authentication files for basic authentication
logresolve
Resolve hostnames for IP-addresses in Apache logfiles
rotatelogs
Rotate Apache logs without having to kill the server
suexec
Switch User For Exec
Other Programs
Support tools with no own manual page.


httpd - Apache Hypertext Transfer Protocol Server - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

httpd - Apache Hypertext Transfer Protocol Server

httpd is the Apache HyperText Transfer Protocol (HTTP) server program. It is designed to be run as a standalone daemon process. When used like this it will create a pool of child processes or threads to handle requests.

In general, httpd should not be invoked directly, but rather should be invoked via apachectl on Unix-based systems or as a service on Windows NT, 2000 and XP and as a console application on Windows 9x and ME.

See also

  • Starting Apache
  • Stopping Apache
  • Configuration Files
  • Platform-specific Documentation
  • apachectl

Synopsis

httpd [ -d serverroot ] [ -f config ] [ -C directive ] [ -c directive ] [ -D parameter ] [ -e level ] [ -E file ] [ -k start|restart|graceful|stop ] [ -R directory ] [ -h ] [ -l ] [ -L ] [ -S ] [ -t ] [ -v ] [ -V ] [ -X ]

On Windows systems, the following additional arguments are available:

httpd [ -k install|config|uninstall ] [ -n name ] [ -w ]

Options

-d serverroot
Set the initial value for the ServerRoot directive to serverroot. This can be overridden by the ServerRoot directive in the configuration file. The default is /usr/local/apache2.
-f config
Uses the directives in the file config on startup. If config does not begin with a /, then it is taken to be a path relative to the ServerRoot. The default is conf/httpd.conf.
-k start|restart|graceful|stop
Signals httpd to start, restart, or stop. See Stopping Apache for more information.
-C directive
Process the configuration directive before reading config files.
-c directive
Process the configuration directive after reading config files.
-D parameter
Sets a configuration parameter which can be used with <IfDefine> sections in the configuration files to conditionally skip or process commands at server startup and restart.
-e level
Sets the LogLevel to level during server startup. This is useful for temporarily increasing the verbosity of the error messages to find problems during startup.
-E file
Send error messages during server startup to file.
-R directory
When the server is compiled using the SHARED_CORE rule, this specifies the directory for the shared object files.
-h
Output a short summary of available command line options.
-l
Output a list of modules compiled into the server. This will not list dynamically loaded modules included using the LoadModule directive.
-L
Output a list of directives together with expected arguments and places where the directive is valid.
-S
Show the settings as parsed from the config file (currently only shows the virtualhost settings).
-t
Run syntax tests for configuration files only. The program immediately exits after these syntax parsing tests with either a return code of 0 (Syntax OK) or return code not equal to 0 (Syntax Error). If -D DUMP_VHOSTS is also set, details of the virtual host configuration will be printed.
-v
Print the version of httpd, and then exit.
-V
Print the version and build parameters of httpd, and then exit.
-X
Run httpd in debug mode. Only one worker will be started and the server will not detach from the console.

The following arguments are available only on the Windows platform:

-k install|config|uninstall
Install Apache as a Windows NT service; change startup options for the Apache service; and uninstall the Apache service.
-n name
The name of the Apache service to signal.
-w
Keep the console window open on error so that the error message can be read.


ab - Apache HTTP server benchmarking tool - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

ab - Apache HTTP server benchmarking tool

ab is a tool for benchmarking your Apache Hypertext Transfer Protocol (HTTP) server. It is designed to give you an impression of how your current Apache installation performs. This especially shows you how many requests per second your Apache installation is capable of serving.

See also

  • httpd

Synopsis

ab
    [ -A auth-username:password ]
    [ -c concurrency ]
    [ -C cookie-name=value ]
    [ -d ]
    [ -e csv-file ]
    [ -g gnuplot-file ]
    [ -h ]
    [ -H custom-header ]
    [ -i ]
    [ -k ]
    [ -n requests ]
    [ -p POST-file ]
    [ -P proxy-auth-username:password ]
    [ -q ]
    [ -s ]
    [ -S ]
    [ -t timelimit ]
    [ -T content-type ]
    [ -v verbosity]
    [ -V ]
    [ -w ]
    [ -x <table>-attributes ]
    [ -X proxy[:port] ]
    [ -y <tr>-attributes ]
    [ -z <td>-attributes ]
    [http://]hostname[:port]/path

Options

-A auth-username:password
Supply BASIC Authentication credentials to the server. The username and password are separated by a single : and sent on the wire base64 encoded. The string is sent regardless of whether the server needs it (i.e., has sent an 401 authentication needed).
-c concurrency
Number of multiple requests to perform at a time. Default is one request at a time.
-C cookie-name=value
Add a Cookie: line to the request. The argument is typically in the form of a name=value pair. This field is repeatable.
-d
Do not display the "percentage served within XX [ms] table". (legacy support).
-e csv-file
Write a Comma separated value (CSV) file which contains for each percentage (from 1% to 100%) the time (in milliseconds) it took to serve that percentage of the requests. This is usually more useful than the 'gnuplot' file; as the results are already 'binned'.
-g gnuplot-file
Write all measured values out as a 'gnuplot' or TSV (Tab separate values) file. This file can easily be imported into packages like Gnuplot, IDL, Mathematica, Igor or even Excell. The labels are on the first line of the file.
-h
Display usage information.
-H custom-header
Append extra headers to the request. The argument is typically in the form of a valid header line, containing a colon-separated field-value pair (i.e., "Accept-Encoding: zip/zop;8bit").
-i
Do HEAD requests instead of GET.
-k
Enable the HTTP KeepAlive feature, i.e., perform multiple requests within one HTTP session. Default is no KeepAlive.
-n requests
Number of requests to perform for the benchmarking session. The default is to just perform a single request which usually leads to non-representative benchmarking results.
-p POST-file
File containing data to POST.
-P proxy-auth-username:password
Supply BASIC Authentication credentials to a proxy en-route. The username and password are separated by a single : and sent on the wire base64 encoded. The string is sent regardless of whether the proxy needs it (i.e., has sent an 407 proxy authentication needed).
-q
When processing more than 150 requests, ab outputs a progress count on stderr every 10% or 100 requests or so. The -q flag will suppress these messages.
-s
When compiled in (ab -h will show you) use the SSL protected https rather than the http protocol. This feature is experimental and very rudimentary. You probably do not want to use it.
-S
Do not display the median and standard deviation values, nor display the warning/error messages when the average and median are more than one or two times the standard deviation apart. And default to the min/avg/max values. (legacy support).
-t timelimit
Maximum number of seconds to spend for benchmarking. This implies a -n 50000 internally. Use this to benchmark the server within a fixed total amount of time. Per default there is no timelimit.
-T content-type
Content-type header to use for POST data.
-v verbosity
Set verbosity level - 4 and above prints information on headers, 3 and above prints response codes (404, 200, etc.), 2 and above prints warnings and info.
-V
Display version number and exit.
-w
Print out results in HTML tables. Default table is two columns wide, with a white background.
-x <table>-attributes
String to use as attributes for <table>. Attributes are inserted <table here >.
-X proxy[:port]
Use a proxy server for the requests.
-y <tr>-attributes
String to use as attributes for <tr>.
-z <td>-attributes
String to use as attributes for <td>.

Bugs

There are various statically declared buffers of fixed length. Combined with the lazy parsing of the command line arguments, the response headers from the server and other external inputs, this might bite you.

It does not implement HTTP/1.x fully; only accepts some 'expected' forms of responses. The rather heavy use of strstr(3) shows up top in profile, which might indicate a performance problem; i.e., you would measure the ab performance rather than the server's.


apachectl - Apache HTTP Server Control Interface - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

apachectl - Apache HTTP Server Control Interface

apachectl is a front end to the Apache HyperText Transfer Protocol (HTTP) server. It is designed to help the administrator control the functioning of the Apache httpd daemon.

The apachectl script can operate in two modes. First, it can act as a simple front-end to the httpd command that simply sets any necessary environment variables and then invokes httpd, passing through any command line arguments. Second, apachectl can act as a SysV init script, taking simple one-word arguments like start, restart, and stop, and translating them into appropriate signals to httpd.

If your Apache installation uses non-standard paths, you will need to edit the apachectl script to set the appropriate paths to the httpd binary. You can also specify any necessary httpd command line arguments. See the comments in the script for details.

The apachectl script returns a 0 exit value on success, and >0 if an error occurs. For more details, view the comments in the script.

See also

  • Starting Apache
  • Stopping Apache
  • Configuration Files
  • Platform Docs
  • httpd

Synopsis

When acting in pass-through mode, apachectl can take all the arguments available for the httpd binary.

apachectl [ httpd-argument ]

When acting in SysV init mode, apachectl takes simple, one-word commands, defined below.

apachectl command

Options

Only the SysV init-style options are defined here. Other arguments are defined on the httpd manual page.

start
Start the Apache httpd daemon. Gives an error if it is already running. This is equivalent to apachectl -k start.
stop
Stops the Apache httpd daemon. This is equivalent to apachectl -k stop.
restart
Restarts the Apache httpd daemon. If the daemon is not running, it is started. This command automatically checks the configuration files as in configtest before initiating the restart to make sure the daemon doesn't die. This is equivalent to apachectl -k restart.
fullstatus
Displays a full status report from mod_status. For this to work, you need to have mod_status enabled on your server and a text-based browser such as lynx available on your system. The URL used to access the status report can be set by editing the STATUSURL variable in the script.
status
Displays a brief status report. Similar to the fullstatus option, except that the list of requests currently being served is omitted.
graceful
Gracefully restarts the Apache httpd daemon. If the daemon is not running, it is started. This differs from a normal restart in that currently open connections are not aborted. A side effect is that old log files will not be closed immediately. This means that if used in a log rotation script, a substantial delay may be necessary to ensure that the old log files are closed before processing them. This command automatically checks the configuration files as in configtest before initiating the restart to make sure Apache doesn't die. This is equivalent to apachectl -k graceful.
configtest
Run a configuration file syntax test. It parses the configuration files and either reports Syntax Ok or detailed information about the particular syntax error. This is equivalent to apachectl -t.

The following additional option is available, but deprecated.

startssl
This is equivalent to apachectl -k start -DSSL. We recommend that you use that command explicitly, or you adjust your httpd.conf to remove the <IfDefine> section so that SSL will always be available.


apxs - APache eXtenSion tool - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

apxs - APache eXtenSion tool

apxs is a tool for building and installing extension modules for the Apache HyperText Transfer Protocol (HTTP) server. This is achieved by building a dynamic shared object (DSO) from one or more source or object files which then can be loaded into the Apache server under runtime via the LoadModule directive from mod_so.

So to use this extension mechanism your platform has to support the DSO feature and your Apache httpd binary has to be built with the mod_so module. The apxs tool automatically complains if this is not the case. You can check this yourself by manually running the command

$ httpd -l

The module mod_so should be part of the displayed list. If these requirements are fulfilled you can easily extend your Apache server's functionality by installing your own modules with the DSO mechanism by the help of this apxs tool:

$ apxs -i -a -c mod_foo.c
gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
ld -Bshareable -o mod_foo.so mod_foo.o
cp mod_foo.so /path/to/apache/modules/mod_foo.so
chmod 755 /path/to/apache/modules/mod_foo.so
[activating module `foo' in /path/to/apache/etc/httpd.conf]
$ apachectl restart
/path/to/apache/sbin/apachectl restart: httpd not running, trying to start
[Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
/path/to/apache/sbin/apachectl restart: httpd started
$ _

The arguments files can be any C source file (.c), a object file (.o) or even a library archive (.a). The apxs tool automatically recognizes these extensions and automatically used the C source files for compilation while just using the object and archive files for the linking phase. But when using such pre-compiled objects make sure they are compiled for position independent code (PIC) to be able to use them for a dynamically loaded shared object. For instance with GCC you always just have to use -fpic. For other C compilers consult its manual page or at watch for the flags apxs uses to compile the object files.

For more details about DSO support in Apache read the documentation of mod_so or perhaps even read the src/modules/standard/mod_so.c source file.

See also

  • apachectl
  • httpd

Synopsis

apxs -g [ -S name=value ] -n modname

apxs -q [ -S name=value ] query ...

apxs -c
    [ -S name=value ]
    [ -o dsofile ]
    [ -I incdir ]
    [ -D name=value ]
    [ -L libdir ]
    [ -l libname ]
    [ -Wc,compiler-flags ]
    [ -Wl,linker-flags ]
    files ...

apxs -i
    [ -S name=value ]
    [ -n modname ]
    [ -a ]
    [ -A ]
    dso-file ...

apxs -e
    [ -S name=value ]
    [ -n modname ]
    [ -a ]
    [ -A ]
    dso-file ...

Options

Common Options

-n modname
This explicitly sets the module name for the -i (install) and -g (template generation) option. Use this to explicitly specify the module name. For option -g this is required, for option -i the apxs tool tries to determine the name from the source or (as a fallback) at least by guessing it from the filename.

Query Options

-q
Performs a query for apxs's knowledge about certain settings. The query parameters can be one or more of the following strings: CC, CFLAGS, CFLAGS_SHLIB, INCLUDEDIR, LD_SHLIB, LDFLAGS_SHLIB, LIBEXECDIR, LIBS_SHLIB, SBINDIR, SYSCONFDIR, TARGET.

Use this for manually determining settings. For instance use

INC=-I`apxs -q INCLUDEDIR`

inside your own Makefiles if you need manual access to Apache's C header files.

Configuration Options

-S name=value
This option changes the apxs settings described above.

Template Generation Options

-g
This generates a subdirectory name (see option -n) and there two files: A sample module source file named mod_name.c which can be used as a template for creating your own modules or as a quick start for playing with the apxs mechanism. And a corresponding Makefile for even easier build and installing of this module.

DSO Compilation Options

-c
This indicates the compilation operation. It first compiles the C source files (.c) of files into corresponding object files (.o) and then builds a dynamically shared object in dsofile by linking these object files plus the remaining object files (.o and .a) of files. If no -o option is specified the output file is guessed from the first filename in files and thus usually defaults to mod_name.so.
-o dsofile
Explicitly specifies the filename of the created dynamically shared object. If not specified and the name cannot be guessed from the files list, the fallback name mod_unknown.so is used.
-D name=value
This option is directly passed through to the compilation command(s). Use this to add your own defines to the build process.
-I incdir
This option is directly passed through to the compilation command(s). Use this to add your own include directories to search to the build process.
-L libdir
This option is directly passed through to the linker command. Use this to add your own library directories to search to the build process.
-l libname
This option is directly passed through to the linker command. Use this to add your own libraries to search to the build process.
-Wc,compiler-flags
This option passes compiler-flags as additional flags to the compiler command. Use this to add local compiler-specific options.
-Wl,linker-flags
This option passes linker-flags as additional flags to the linker command. Use this to add local linker-specific options.

DSO Installation and Configuration Options

-i
This indicates the installation operation and installs one or more dynamically shared objects into the server's modules directory.
-a
This activates the module by automatically adding a corresponding LoadModule line to Apache's httpd.conf configuration file, or by enabling it if it already exists.
-A
Same as option -a but the created LoadModule directive is prefixed with a hash sign (#), i.e., the module is just prepared for later activation but initially disabled.
-e
This indicates the editing operation, which can be used with the -a and -A options similarly to the -i operation to edit Apache's httpd.conf configuration file without attempting to install the module.

Examples

Assume you have an Apache module named mod_foo.c available which should extend Apache's server functionality. To accomplish this you first have to compile the C source into a shared object suitable for loading into the Apache server under runtime via the following command:

$ apxs -c mod_foo.c
gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
ld -Bshareable -o mod_foo.so mod_foo.o
$ _

Then you have to update the Apache configuration by making sure a LoadModule directive is present to load this shared object. To simplify this step apxs provides an automatic way to install the shared object in its "modules" directory and updating the httpd.conf file accordingly. This can be achieved by running:

$ apxs -i -a mod_foo.c
cp mod_foo.so /path/to/apache/modules/mod_foo.so
chmod 755 /path/to/apache/modules/mod_foo.so
[activating module `foo' in /path/to/apache/etc/httpd.conf]
$ _

This way a line named

LoadModule foo_module modules/mod_foo.so

is added to the configuration file if still not present. If you want to have this disabled per default use the -A option, i.e.

$ apxs -i -A mod_foo.c

For a quick test of the apxs mechanism you can create a sample Apache module template plus a corresponding Makefile via:

$ apxs -g -n foo
Creating [DIR] foo
Creating [FILE] foo/Makefile
Creating [FILE] foo/mod_foo.c
$ _

Then you can immediately compile this sample module into a shared object and load it into the Apache server:

$ cd foo
$ make all reload
apxs -c mod_foo.c
gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
ld -Bshareable -o mod_foo.so mod_foo.o
apxs -i -a -n "foo" mod_foo.so
cp mod_foo.so /path/to/apache/modules/mod_foo.so
chmod 755 /path/to/apache/modules/mod_foo.so
[activating module `foo' in /path/to/apache/etc/httpd.conf]
apachectl restart
/path/to/apache/sbin/apachectl restart: httpd not running, trying to start
[Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
/path/to/apache/sbin/apachectl restart: httpd started
$ _

You can even use apxs to compile complex modules outside the Apache source tree, like PHP3:

$ cd php3
$ ./configure --with-shared-apache=../apache-1.3
$ apxs -c -o libphp3.so mod_php3.c libmodphp3-so.a
gcc -fpic -DSHARED_MODULE -I/tmp/apache/include -c mod_php3.c
ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a
$ _

because apxs automatically recognized C source files and object files. Only C source files are compiled while remaining object files are used for the linking phase.


configure - Configure the source tree - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

configure - Configure the source tree

The configure script configures the source tree for compiling and installing the Apache HTTP Server on your particular platform. Various options allow the compilation of a server corresponding to your personal requirements.

This script, included in the root directory of the source distribution, is for compilation on Unix and Unix-like systems only. For other platforms, see the platform documentation.

See also

  • Compiling and Installing

Synopsis

You should call the configure script from within the root directory of the distribution.

./configure [OPTION]... [VAR=VALUE]...

To assign environment variables (e.g. CC, CFLAGS ...), specify them as VAR=VALUE. See below for descriptions of some of the useful variables.

Options

  • Configuration options
  • Installation directories
  • System types
  • Optional features
  • Options for support programs

Configuration options

The following options influence the behavior of configure itself.

-C
--config-cache
This is an alias for --cache-file=config.cache
--cache-file=FILE
The test results will be cached in file FILE. This option is disabled by default.
-h
--help [short|recursive]
Output the help and exit. With the argument short only options specific to this package will displayed. The argument recursive displays the short help of all the included packages.
-n
--no-create
The configure script is run normally but does not create output files. This is useful to check the test results before generating makefiles for compilation.
-q
--quiet
Do not print checking ... messages during the configure process.
--srcdir=DIR
Defines directory DIR to be the source file directory. Default is the directory, where configure is located, or the parent directory ...
--silent
Same as --quiet
-V
--version
Display copyright information and exit.

Installation directories

These options define the installation directory. The installation tree depends on the selected layout.

--prefix=PREFIX
Install architecture-independent files in PREFIX. By default the installation directory is set to /usr/local/apache2.
--exec-prefix=EPREFIX
Install architecture-dependent files in EPREFIX. By default the installation directory is set to the PREFIX directory.

By default, make install will install all the files in /usr/local/apache2/bin, /usr/local/apache2/lib etc. You can specify an installation prefix other than /usr/local/apache2 using --prefix, for instance --prefix=$HOME.

Define a directory layout

--enable-layout=LAYOUT
Configure the source code and build scripts to assume an installation tree based on the layout LAYOUT. This allows you to separately specify the locations for each type of file within the Apache HTTP Server installation. The config.layout file contains several example configurations, and you can also create your own custom configuration following the examples. The different layouts in this file are grouped into <Layout FOO>...</Layout> sections and referred to by name as in FOO. The default layout is Apache.

Fine tuning of the installation directories

For better control of the installation directories, use the options below. Please note that the directory defaults are set by autoconf and be overwritten by the corresponding layout setting.

--bindir=DIR
Install user executables in DIR. The user executables are supporting programs like htpasswd, dbmmanage, etc. which are useful for site administrators. By default DIR is set to EPREFIX/bin.
--datadir=DIR
Install read-only architecture-independent data in DIR. By default datadir is set to PREFIX/share. This option is offered by autoconf and currently unused.
--includedir=DIR
Install C header files in DIR. By default includedir is set to EPREFIX/include.
--infodir=DIR
Install info documentation in DIR. By default infodir is set to PREFIX/info. This option is currently unused.
--libdir=DIR
Install object code libraries in DIR. By default libdir is set to EPREFIX/lib.
--libexecdir=DIR
Install the program executables (i.e., shared modules) in DIR. By default libexecdir is set to EPREFIX/libexec.
--localstatedir=DIR
Install modifiable single-machine data in DIR. By default localstatedir is set to PREFIX/var. This option is offered by autoconf and currently unused.
--mandir=DIR
Install the man documentation in DIR. By default mandir is set to EPREFIX/man.
--oldincludedir=DIR
Install C header files for non-gcc in DIR. By default oldincludedir is set to /usr/include. This option is offered by autoconf and currently unused.
--sbindir=DIR
Install the system administrator executables in DIR. Those are server programs like httpd, apachectl, suexec, etc. which are neccessary to run the Apache HTTP Server. By default sbindir is set to EPREFIX/sbin.
--sharedstatedir=DIR
Install modifiable architecture-independent data in DIR. By default sharedstatedir is set to PREFIX/com. This option is offered by autoconf and currently unused.
--sysconfdir=DIR
Install read-only single-machine data like the server configuration files httpd.conf, mime.types, etc. in DIR. By default sysconfdir is set to PREFIX/etc.

System types

These options are used to cross-compile the Apache HTTP Server to run on another system. In normal cases, when building and running the server on the same system, these options are not used.

--build=BUILD
Defines the system type of the system on which the tools are being built. It defaults to the result of the script config.guess.
--host=HOST
Defines the system type of the system on which the server will run. HOST defaults to BUILD.
--target=TARGET
Configure for building compilers for the system type TARGET. It defaults to HOST. This option is offered by autoconf and not necessary for the Apache HTTP Server.

Optional Features

These options are used to fine tune the features your HTTP server will have.

General syntax

Generally you can use the following syntax to enable or disable a feature:

--disable-FEATURE
Do not include FEATURE. This is the same as --enable-FEATURE=no.
--enable-FEATURE[=ARG]
Include FEATURE. The default value for ARG is yes.
--enable-MODULE=shared
The corresponding module will be build as DSO module.
--enable-MODULE=static
By default enabled modules are linked statically. You can force this explicitly.

Note

configure will not complain about --enable-foo even if foo doesn't exist, so you need to type carefully.

Modules enabled by default

Some modules are compiled by default and have to be disabled explicitly. Use the following options to remove discrete modules from the compilation process.

--disable-actions
Disable action triggering on requests, which is provided by mod_actions.
--disable-alias
Disable the mapping of requests to different parts of the filesystem, which is provided by mod_alias.
--disable-asis
Disable support for as-is filetypes, which is provided by mod_asis.
--disable-auth
Disable user-based access control provided by mod_auth. This module provides for HTTP Basic Authentication, where the usernames and passwords are stored in plain text files.
--disable-autoindex
Disable the directory listing functionality provided by mod_autoindex.
--disable-access
Disable host-based access control provided by mod_access.
--disable-cgi
mod_cgi, which provides support for CGI scripts, is enabled by default when using a non-threaded MPM. Use this option to disable CGI support.
--disable-cgid
When using the threaded MPMs worker or perchild support for CGI scripts is provided by mod_cgid by default. To disable CGI support use this option.
--disable-charset-lite
Disable character set translation provided by mod_charset_lite. This module will be installed by default only on EBCDIC systems.
--disable-dir
Disable directory request handling provided by mod_dir.
--disable-env
Enable setting and clearing of environment variables, which is provided by mod_env.
--disable-http
Disable the HTTP protocol handling. The http module is a basic one, enabling the server to function as an HTTP server. It is only useful to disable it if you want to use another protocol module instead. Don't disable this module unless you are really sure what you are doing.
Note: This module will always be linked statically.
--disable-imap
Disable support for server based imagemaps, which provided by mod_imap.
--disable-include
Disable Server Side Includes provided by mod_include.
--disable-log-config
Disable the logging configuration provided by mod_log_config. You won't be able to log requests to the server without this module.
--disable-mime
mod_mime associates the requested filename's extensions with the file's behavior and content (mime-type, language, character set and encoding). Disabling the mapping of file-extensions to MIME is normally not recommended.
--disable-negotiation
Disable content negotiation provided by mod_negotiation.
--disable-setenvif
Disable support for basing environment variables on headers, which is provided by mod_setenvif.
--disable-status
Enable the process/thread monitoring, which is provided by mod_status.
--disable-userdir
Disable the mapping of requests to user-specific directories, which is provided by mod_userdir.

Modules, disabled by default

Some modules are compiled by default and have to be enabled explicitly or by using the keywords most or all (see --enable-mods-shared below for further explanation) to be available. Therefore use the options below.

--enable-auth-anon
Enable anonymous user access provided by mod_auth_anon.
--enable-auth-dbm
mod_auth_dbm provides for HTTP Basic Authentication, where the usernames and passwords are stored in DBM type database files. Use this option to enable the module.
--enable-auth-digest
Enable RFC2617 Digest authentication provided by mod_auth_digest. This module uses plain text files to store the credentials.
--enable-auth-ldap
Enable LDAP based authentication provided by mod_auth_ldap.
--enable-cache
Enable dynamic file caching provided by mod_cache. This experimental module may be interesting for servers with high load or caching proxy servers. At least one storage management module (e.g. mod_disk_cache or mod_mem_cache) is also necessary.
--enable-cern-meta
Enable the CERN-type meta files support provided by mod_cern_meta.
--enable-charset-lite
Enable character set translation provided by mod_charset_lite. This module will be installed by default only on EBCDIC systems. On other systems, you have to enable it.
--enable-dav
Enable the WebDAV protocol handling provided by mod_dav. Support for filesystem resources is provided by the seperate module mod_dav_fs. This module is also automatically enabled with --enable-dav.
Note: mod_dav can only be used together with the http protocol module.
--enable-dav-fs
Enable DAV support for filesystem resources, which is provided by mod_dav_fs. This module is a provider for the mod_dav module, so you should also use --enable-dav.
--enable-deflate
Enable deflate transfer encoding provided by mod_deflate.
--enable-disk-cache
Enable disk caching provided by mod_disk_cache.
--enable-expires
Enable Expires header control provided by mod_expires.
--enable-ext-filter
Enable the external filter support provided by mod_ext_filter.
--enable-file-cache
Enable the file cache provided by mod_file_cache.
--enable-headers
Enable control of HTTP headers provided by mod_headers.
--enable-info
Enable the server information provided by mod_info.
--enable-ldap
Enable LDAP caching and connection pooling services provided by mod_ldap.
--enable-logio
Enable logging of input and output bytes including headers provided by mod_logio.
--enable-mem-cache
Enable memory caching provided by mod_mem_cache.
--enable-mime-magic
Enable automatical determining of MIME types, which is provided by mod_mime_magic.
--enable-isapi
Enable the isapi extension support provided by mod_isapi.
--enable-proxy
Enable the proxy/gateway functionality provided by mod_proxy. The proxying capabilities for CONNECT, FTP and HTTP are provided by the seperate modules mod_proxy_connect, mod_proxy_ftp and mod_proxy_http. These three modules are also automatically enabled with --enable-proxy.
--enable-proxy-connect
Enable proxy support for CONNECT request handling, which is provided by mod_proxy_connect. This module is an extension for the mod_proxy module, so you should also use --enable-proxy.
--enable-proxy-ftp
Enable proxy support for FTP requests, which is provided by mod_proxy_ftp.. This module is an extension for the mod_proxy module, so you should also use --enable-proxy.
--enable-proxy-http
Enable proxy support for HTTP requests, which is provided by mod_proxy_http. This module is an extension for the mod_proxy module, so you should also use --enable-proxy.
--enable-rewrite
Enable rule based URL manipulation provided by mod_rewrite.
--enable-so
Enable DSO capability provided by mod_so. This module will be automatically enabled if you use the --enable-mods-shared option.
--enable-speling
Enable the functionality to correct common URL misspellings, which is provided by mod_spelling.
--enable-ssl
Enable support for SSL/TLS provided by mod_ssl.
--enable-unique-id
Enable the generation of per-request unique ids, which is provided by mod_unique_id.
--enable-usertrack
Enable user-session tracking provided by mod_usertrack.
--enable-vhost-alias
Enable mass virtual hosting provided by mod_vhost_alias.

Modules for developers

The following modules are useful only for developers and testing purposes and are disabled by default. Use the following options to enable them. If you are not sure whether you need one of these modules, omit them.

--enable-bucketeer
Enable the manipulation filter for buckets, which is provided by mod_bucketeer.
--enable-case-filter
Enable the example uppercase conversion output filter support of mod_case_filter.
--enable-case-filter-in
Enable the example uppercase conversion input filter support of mod_case_filter_in.
--enable-echo
Enable the ECHO server provided by mod_echo.
--enable-example
Enable the example and demo module mod_example.
--enable-optional-fn-export
Enable the example for an optional function exporter, which is provided by mod_optional_fn_export.
--enable-optional-fn-import
Enable the example for an optional function importer, which is provided by mod_optional_fn_import.
--enable-optional-hook-export
Enable the example for an optional hook exporter, which is provided by mod_optional_hook_export.
--enable-optional-hook-import
Enable the example optional hook importer, which is provided by mod_optional_hook_import.

MPMs and third-party modules

To add the necessary Multi Processing Module and additional third-party modules use the following options:

--with-module=module-type:module-file

Add a third-party module to the list of statically linked modules. The module source file module-file will be searched in the modules/module-type subdirectory of your Apache HTTP server source tree so it has to be placed there before. If it is not found here configure is considering module-file to be an absolute file path and tries to copy the source file into the module-type subdirectory.

This option is useful to add small external modules consisting of one source file. For more complex modules you should read the vendor's documentation.

Note

If you want to build a DSO module instead of a statically linked use apxs.
--with-mpm=MPM
Choose the process model for your server. You have to select exactly one Multi-Processing Module. Otherwise the default MPM for your operating system will be taken. Possible MPMs are beos, leader, mpmt_os2, perchild, prefork, threadpool and worker.

Cumulative and other options

--enable-maintainer-mode
Turn on debugging and compile time warnings.
--enable-mods-shared=MODULE-LIST

Defines a list of modules to be enabled and build as dynamic shared modules. This mean, these module have to be loaded dynamically by using the LoadModule directive.

MODULE-LIST is a space separated list of modulenames enclosed by quotation marks. The module names are given without the preceding mod_. For example:

--enable-mods-shared='headers rewrite dav'

Additionally you can use the special keywords all and most. For example,

--enable-mods-shared=most

will compile most modules and build them as DSO modules.

--enable-modules=MODULE-LIST
This option behaves similar to --enable-mods-shared, but will link the given modules statically. This mean, these modules will always be present while running httpd. They need not be loaded with LoadModule.
--enable-v4-mapped
Allow IPv6 sockets to handle IPv4 connections.
--with-port=PORT
This defines the port on which httpd will listen. This port number is used when generating the configuration file httpd.conf. The default is 80.
--with-program-name
Define an alternative executable name. The default is httpd.

Optional packages

These options are used to define optional packages.

General syntax

Generally you can use the following syntax to define an optional package:

--with-PACKAGE[=ARG]
Use the package PACKAGE. The default value for ARG isyes.
--without-PACKAGE
Do not use the package PACKAGE. This is the same as --with-PACKAGE=no. This option is provided by autoconf but not very useful for the Apache HTTP Server.

Specific packages

--with-apr=DIR|FILE
The Apache Portable Runtime (APR) is part of the httpd source distribution and will automatically be build together with the HTTP server. If you want to use an already installed APR instead you have to tell configure the path to the apr-config script. You may set the absolute path and name or the directory to the installed APR. apr-config must exists within this directory or the subdirectory bin.
--with-apr-util=DIR|FILE
The Apache Portable Runtime Utilities (APU) are part of the httpd source distribution and will automatically be build together with the HTTP server. If you want to use an already installed APU instead you have to tell configure the path to the apu-config script. You may set the absolute path and name or the directory to the installed APU. apu-config must exists within this directory or the subdirectory bin.
--with-ssl=DIR
If mod_ssl has been enabled configure searches for an installed OpenSSL. You can set the directory path to the SSL/TLS toolkit instead.
--with-z=DIR
configure searches automatically for an installed zlib library if your source configuration requires one (e.g., when mod_deflate is enabled). You can set the directory path to the compression library instead.

Several features of the Apache HTTP Server, including mod_authn_dbm and mod_rewrite's DBM RewriteMap use simple key/value databases for quick lookups of information. SDBM is included in the APU, so this database is always available. If you would like to use other database types, use the following options to enable them:

--with-gdbm[=path]
If no path is specified, configure will search for the include files and libraries of a GNU DBM installation in the usual search paths. An explicit path will cause configure to look in path/lib and path/include for the relevant files. Finally, the path may specify specific include and library paths separated by a colon.
--with-ndbm[=path]
Like --with-gdbm, bur searches for a New DBM installation.
--with-berkeley-db[=path]
Like --with-gdbm, but searches for a Berkeley DB installation.

Note

The DBM options are provided by the APU and passed through to its configuration script. They are useless when using an already installed APU defined by --with-apr-util.

You may use more then one DBM implementation together with your HTTP server. The appropriated DBM type will be configured within the runtime configuration at each time.

Options for support programs

--enable-static-support
Build a statically linked version of the support binaries. This means, a stand-alone executable will be built with all the necessary libraries integrated. Otherwise the support binaries are linked dynamically by default.
--enable-suexec
Use this option to enable suexec, which allows you to set uid and gid for spawned processes. Do not use this option unless you understand all the security implications of running a suid binary on your server. Further options to configure suexec are described below.

It is possible to create a statically linked binary of a single support program by using the following options:

--enable-static-ab
Build a statically linked version of ab.
--enable-static-checkgid
Build a statically linked version of checkgid.
--enable-static-htdbm
Build a statically linked version of htdbm.
--enable-static-htdigest
Build a statically linked version of htdigest.
--enable-static-htpasswd
Build a statically linked version of htpasswd.
--enable-static-logresolve
Build a statically linked version of logresolve.
--enable-static-rotatelogs
Build a statically linked version of rotatelogs.

suexec configuration options

The following options are used to fine tune the behavior of suexec. See Configuring and installing suEXEC for further information.

--with-suexec-bin
This defines the path to suexec binary. Default is --sbindir (see Fine tuning of installation directories).
--with-suexec-caller
This defines the user allowed to call suexec. It should be the same as the user under which httpd normally runs.
--with-suexec-docroot
This defines the directory tree under which suexec access is allowed for executables. Default value is --datadir/htdocs.
--with-suexec-gidmin
Define this as the lowest GID allowed to be a target user for suexec. The default value is 100.
--with-suexec-logfile
This defines the filename of the suexec logfile. By default the logfile is named suexec_log and located in --logfiledir.
--with-suexec-safepath
Define the value of the environment variable PATH to be set for processes started by suexec. Default value is /usr/local/bin:/usr/bin:/bin.
--with-suexec-userdir
This defines the subdirectory under the user's directory that contains all executables for which suexec access is allowed. This setting is necessary when you want to use suexec together with user-specific directories (as provided by mod_userdir). The default is public_html.
--with-suexec-uidmin
Define this as the lowest UID allowed to be a target user for suexec. The default value is 100.
--with-suexec-umask
Set umask for processes started by suexec. It defaults to your system settings.

Environment variables

There are some useful environment variables to override the choices made by configure or to help it to find libraries and programs with nonstandard names or locations.

CC
Define the C compiler command to be used for compilation.
CFLAGS
Set C compiler flags you want to use for compilation.
CPP
Define the C preprocessor command to be used.
CPPFLAGS
Set C/C++ preprocessor flags, e.g. -Iincludedir if you have headers in a nonstandard directory includedir.
LDFLAGS
Set linker flags, e.g. -Llibdir if you have libraries in a nonstandard directory libdir.


dbmmanage - Manage user authentication files in DBM format - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

dbmmanage - Manage user authentication files in DBM format

dbmmanage is used to create and update the DBM format files used to store usernames and password for basic authentication of HTTP users. Resources available from the Apache HTTP server can be restricted to just the users listed in the files created by dbmmanage. This program can only be used when the usernames are stored in a DBM file. To use a flat-file database see htpasswd.

This manual page only lists the command line arguments. For details of the directives necessary to configure user authentication in httpd see the httpd manual, which is part of the Apache distribution or can be found at http://httpd.apache.org/.

See also

  • httpd
  • mod_auth_dbm

Synopsis

dbmmanage [ encoding ] filename add|adduser|check|delete|update username [ encpasswd [ group[,group...] [ comment ] ] ]

dbmmanage filename view [ username ]

dbmmanage filename import

Options

filename
The filename of the DBM format file. Usually without the extension .db, .pag, or .dir.
username
The user for which the operations are performed. The username may not contain a colon (:).
encpasswd
This is the already encrypted password to use for the update and add commands. You may use a hyphen (-) if you want to get prompted for the password, but fill in the fields afterwards. Additionally when using the update command, a period (.) keeps the original password untouched.
group
A group, which the user is member of. A groupname may not contain a colon (:). You may use a hyphen (-) if you don't want to assign the user to a group, but fill in the comment field. Additionally when using the update command, a period (.) keeps the original groups untouched.
comment
This is the place for your opaque comments about the user, like realname, mailaddress or such things. The server will ignore this field.

Encodings

-d
crypt encryption (default, except on Win32, Netware)
-m
MD5 encryption (default on Win32, Netware)
-s
SHA1 encryption
-p
plaintext (not recommended)

Commands

add
Adds an entry for username to filename using the encrypted password encpasswd.
adduser
Asks for a password and then adds an entry for username to filename.
check
Asks for a password and then checks if username is in filename and if it's password matches the specified one.
delete
Deletes the username entry from filename.
import
Reads username:password entries (one per line) from STDIN and adds them to filename. The passwords already have to be crypted.
update
Same as the adduser command, except that it makes sure username already exists in filename.
view
Just displays the contents of the DBM file. If you specify a username, it displays the particular record only.

Bugs

One should be aware that there are a number of different DBM file formats in existence, and with all likelihood, libraries for more than one format may exist on your system. The three primary examples are SDBM, NDBM, the GNU project's GDBM, and Berkeley DB 2. Unfortunately, all these libraries use different file formats, and you must make sure that the file format used by filename is the same format that dbmmanage expects to see. dbmmanage currently has no way of determining what type of DBM file it is looking at. If used against the wrong format, will simply return nothing, or may create a different DBM file with a different name, or at worst, it may corrupt the DBM file if you were attempting to write to it.

dbmmanage has a list of DBM format preferences, defined by the @AnyDBM::ISA array near the beginning of the program. Since we prefer the Berkeley DB 2 file format, the order in which dbmmanage will look for system libraries is Berkeley DB 2, then NDBM, then GDBM and then SDBM. The first library found will be the library dbmmanage will attempt to use for all DBM file transactions. This ordering is slightly different than the standard @AnyDBM::ISA ordering in Perl, as well as the ordering used by the simple dbmopen() call in Perl, so if you use any other utilities to manage your DBM files, they must also follow this preference ordering. Similar care must be taken if using programs in other languages, like C, to access these files.

One can usually use the file program supplied with most Unix systems to see what format a DBM file is in.


htdigest - manage user files for digest authentication - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

htdigest - manage user files for digest authentication

htdigest is used to create and update the flat-files used to store usernames, realm and password for digest authentication of HTTP users. Resources available from the Apache HTTP server can be restricted to just the users listed in the files created by htdigest.

This manual page only lists the command line arguments. For details of the directives necessary to configure digest authentication in httpd see the Apache manual, which is part of the Apache distribution or can be found at http://httpd.apache.org/.

See also

  • httpd
  • mod_auth_digest

Synopsis

htdigest [ -c ] passwdfile realm username

Options

-c
Create the passwdfile. If passwdfile already exists, it is deleted first.
passwdfile
Name of the file to contain the username, realm and password. If -c is given, this file is created if it does not already exist, or deleted and recreated if it does exist.
realm
The realm name to which the user name belongs.
username
The user name to create or update in passwdfile. If username does not exist is this file, an entry is added. If it does exist, the password is changed.


htpasswd - Manage user files for basic authentication - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

htpasswd - Manage user files for basic authentication

htpasswd is used to create and update the flat-files used to store usernames and password for basic authentication of HTTP users. If htpasswd cannot access a file, such as not being able to write to the output file or not being able to read the file in order to update it, it returns an error status and makes no changes.

Resources available from the Apache HTTP server can be restricted to just the users listed in the files created by htpasswd. This program can only manage usernames and passwords stored in a flat-file. It can encrypt and display password information for use in other types of data stores, though. To use a DBM database see dbmmanage.

htpasswd encrypts passwords using either a version of MD5 modified for Apache, or the system's crypt() routine. Files managed by htpasswd may contain both types of passwords; some user records may have MD5-encrypted passwords while others in the same file may have passwords encrypted with crypt().

This manual page only lists the command line arguments. For details of the directives necessary to configure user authentication in httpd see the Apache manual, which is part of the Apache distribution or can be found at http://httpd.apache.org/.

See also

  • httpd
  • The scripts in support/SHA1 which come with the distribution.

Synopsis

htpasswd [ -c ] [ -m ] [ -D ] passwdfile username

htpasswd -b [ -c ] [ -m | -d | -p | -s ] [ -D ] passwdfile username password

htpasswd -n [ -m | -d | -s | -p ] username

htpasswd -nb [ -m | -d | -s | -p ] username password

Options

-b
Use batch mode; i.e., get the password from the command line rather than prompting for it. This option should be used with extreme care, since the password is clearly visible on the command line.
-c
Create the passwdfile. If passwdfile already exists, it is rewritten and truncated. This option cannot be combined with the -n option.
-n
Display the results on standard output rather than updating a file. This is useful for generating password records acceptable to Apache for inclusion in non-text data stores. This option changes the syntax of the command line, since the passwdfile argument (usually the first one) is omitted. It cannot be combined with the -c option.
-m
Use MD5 encryption for passwords. On Windows, Netware and TPF, this is the default.
-d
Use crypt() encryption for passwords. The default on all platforms but Windows, Netware and TPF. Though possibly supported by htpasswd on all platforms, it is not supported by the httpd server on Windows, Netware and TPF.
-s
Use SHA encryption for passwords. Facilitates migration from/to Netscape servers using the LDAP Directory Interchange Format (ldif).
-p
Use plaintext passwords. Though htpasswd will support creation on all platforms, the httpd daemon will only accept plain text passwords on Windows, Netware and TPF.
-D
Delete user. If the username exists in the specified htpasswd file, it will be deleted.
passwdfile
Name of the file to contain the user name and password. If -c is given, this file is created if it does not already exist, or rewritten and truncated if it does exist.
username
The username to create or update in passwdfile. If username does not exist in this file, an entry is added. If it does exist, the password is changed.
password
The plaintext password to be encrypted and stored in the file. Only used with the -b flag.

Exit Status

htpasswd returns a zero status ("true") if the username and password have been successfully added or updated in the passwdfile. htpasswd returns 1 if it encounters some problem accessing files, 2 if there was a syntax problem with the command line, 3 if the password was entered interactively and the verification entry didn't match, 4 if its operation was interrupted, 5 if a value is too long (username, filename, password, or final computed record), 6 if the username contains illegal characters (see the Restrictions section), and 7 if the file is not a valid password file.

Examples

htpasswd /usr/local/etc/apache/.htpasswd-users jsmith

Adds or modifies the password for user jsmith. The user is prompted for the password. If executed on a Windows system, the password will be encrypted using the modified Apache MD5 algorithm; otherwise, the system's crypt() routine will be used. If the file does not exist, htpasswd will do nothing except return an error.

htpasswd -c /home/doe/public_html/.htpasswd jane

Creates a new file and stores a record in it for user jane. The user is prompted for the password. If the file exists and cannot be read, or cannot be written, it is not altered and htpasswd will display a message and return an error status.

htpasswd -mb /usr/web/.htpasswd-all jones Pwd4Steve

Encrypts the password from the command line (Pwd4Steve) using the MD5 algorithm, and stores it in the specified file.

Security Considerations

Web password files such as those managed by htpasswd should not be within the Web server's URI space -- that is, they should not be fetchable with a browser.

The use of the -b option is discouraged, since when it is used the unencrypted password appears on the command line.

Restrictions

On the Windows and MPE platforms, passwords encrypted with htpasswd are limited to no more than 255 characters in length. Longer passwords will be truncated to 255 characters.

The MD5 algorithm used by htpasswd is specific to the Apache software; passwords encrypted using it will not be usable with other Web servers.

Usernames are limited to 255 bytes and may not include the character :.


logresolve - Resolve IP-addresses to hostnames in Apache log files - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

logresolve - Resolve IP-addresses to hostnames in Apache log files

logresolve is a post-processing program to resolve IP-addresses in Apache's access logfiles. To minimize impact on your nameserver, logresolve has its very own internal hash-table cache. This means that each IP number will only be looked up the first time it is found in the log file.

Takes an Apache log file on standard input. The IP addresses must be the first thing on each line and must be seperated from the remainder of the line by a space.

Synopsis

logresolve [ -s filename ] [ -c ] < access_log > access_log.new

Options

-s filename
Specifies a filename to record statistics.
-c
This causes logresolve to apply some DNS checks: after finding the hostname from the IP address, it looks up the IP addresses for the hostname and checks that one of these matches the original address.


rotatelogs - Piped logging program to rotate Apache logs - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

rotatelogs - Piped logging program to rotate Apache logs

rotatelogs is a simple program for use in conjunction with Apache's piped logfile feature. For example:

CustomLog "|bin/rotatelogs /var/logs/logfile 86400" common

This creates the files /var/logs/logfile.nnnn where nnnn is the system time at which the log nominally starts (this time will always be a multiple of the rotation time, so you can synchronize cron scripts with it). At the end of each rotation time (here after 24 hours) a new log is started.

CustomLog "|bin/rotatelogs /var/logs/logfile 5M" common

This configuration will rotate the logfile whenever it reaches a size of 5 megabytes.

ErrorLog "|bin/rotatelogs /var/logs/errorlog.%Y-%m-%d-%H_%M_%S 5M"

This configuration will rotate the error logfile whenever it reaches a size of 5 megabytes, and the suffix to the logfile name will be created of the form errorlog.YYYY-mm-dd-HH_MM_SS.

Synopsis

rotatelogs [ -l ] logfile [ rotationtime [ offset ]] | [ filesizeM ]

Options

-l (2.0.51 and later)
Causes the use of local time rather than GMT as the base for the interval. Note that using -l in an environment which changes the GMT offset (such as for BST or DST) can lead to unpredictable results!
logfile
The path plus basename of the logfile. If logfile includes any '%' characters, it is treated as a format string for strftime(3). Otherwise, the suffix .nnnnnnnnnn is automatically added and is the time in seconds. Both formats compute the start time from the beginning of the current period.
rotationtime
The time between log file rotations in seconds.
offset
The number of minutes offset from UTC. If omitted, zero is assumed and UTC is used. For example, to use local time in the zone UTC -5 hours, specify a value of -300 for this argument.
filesizeM
The maximum file size in megabytes followed by the letter M to specify size rather than time. Use this parameter in place of both rotationtime and offset.

Portability

The following logfile format string substitutions should be supported by all strftime(3) implementations, see the strftime(3) man page for library-specific extensions.

%A | full weekday name (localized)
%a | 3-character weekday name (localized)
%B | full month name (localized)
%b | 3-character month name (localized)
%c | date and time (localized)
%d | 2-digit day of month
%H | 2-digit hour (24 hour clock)
%I | 2-digit hour (12 hour clock)
%j | 3-digit day of year
%M | 2-digit minute
%m | 2-digit month
%p | am/pm of 12 hour clock (localized)
%S | 2-digit second
%U | 2-digit week of year (Sunday first day of week)
%W | 2-digit week of year (Monday first day of week)
%w | 1-digit weekday (Sunday first day of week)
%X | time (localized)
%x | date (localized)
%Y | 4-digit year
%y | 2-digit year
%Z | time zone name
%% | literal `%'


suexec - Switch user before executing external programs - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

suexec - Switch user before executing external programs

suexec is used by the Apache HTTP Server to switch to another user before executing CGI programs. In order to achieve this, it must run as root. Since the HTTP daemon normally doesn't run as root, the suexec executable needs the setuid bit set and must be owned by root. It should never be writable for any other person than root.

For further information about the concepts and and the security model of suexec please refer to the suexec documentation (http://httpd.apache.org/docs-2.0/suexec.html).

Synopsis

suexec -V

Options

-V
If you are root, this option displays the compile options of suexec. For security reasons all configuration options are changeable only at compile time.


Other Programs - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

Other Programs

The following programs are simple support programs included with the Apache HTTP Server which do not have their own manual pages. They are not installed automatically. You can find them after the configuration process in the support/ directory.

log_server_status

This perl script is designed to be run at a frequent interval by something like cron. It connects to the server and downloads the status information. It reformats the information to a single line and logs it to a file. Adjust the variables at the top of the script to specify the location of the resulting logfile.

split-logfile

This perl script will take a combined Web server access log file and break its contents into separate files. It assumes that the first field of each line is the virtual host identity (put there by "%v"), and that the logfiles should be named that + ".log" in the current directory.

The combined log file is read from stdin. Records read will be appended to any existing log files.


Apache Miscellaneous Documentation - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Apache Miscellaneous Documentation

Below is a list of additional documentation pages that apply to the Apache web server development project.

Warning

Some of the documents below have not been fully updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

How to use XSSI and Negotiation for custom ErrorDocuments

Describes a solution which uses XSSI and negotiation to custom-tailor the Apache ErrorDocuments to taste, adding the advantage of returning internationalized versions of the error messages depending on the client's language preferences.

File Descriptor use in Apache

Describes how Apache uses file descriptors and talks about various limits imposed on the number of descriptors available by various operating systems.

FIN_WAIT_2

A description of the causes of Apache processes going into the FIN_WAIT_2 state, and what you can do about it.

Known Client Problems

A list of problems in HTTP clients which can be mitigated by Apache.

Performance Notes - Apache Tuning

Notes about how to (run-time and compile-time) configure Apache for highest performance. Notes explaining why Apache does some things, and why it doesn't do other things (which make it slower/faster).

Security Tips

Some "do"s - and "don't"s - for keeping your Apache web site secure.

URL Rewriting Guide

This document supplements the mod_rewrite reference documentation. It describes how one can use Apache's mod_rewrite to solve typical URL-based problems webmasters are usually confronted with in practice.

Apache Tutorials

A list of external resources which help to accomplish common tasks with the Apache HTTP server.

Relevant Standards

This document acts as a reference page for most of the relevant standards that Apache follows.


International Customized Server Error Messages - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Miscellaneous Documentation

International Customized Server Error Messages

Warning:

This document has not been fully updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

This document describes an easy way to provide your Apache HTTP Server with a set of customized error messages which take advantage of Content Negotiation and mod_include to return error messages generated by the server in the client's native language.

Introduction

By using SSI, all ErrorDocument messages can share a homogenous and consistent style and layout, and maintenance work (changing images, changing links) is kept to a minimum because all layout information can be kept in a single file.

Error documents can be shared across different servers, or even hosts, because all varying information is inserted at the time the error document is returned on behalf of a failed request.

Content Negotiation then selects the appropriate language version of a particular error message text, honoring the language preferences passed in the client's request. (Users usually select their favorite languages in the preferences options menu of today's browsers). When an error document in the client's primary language version is unavailable, the secondary languages are tried or a default (fallback) version is used.

You have full flexibility in designing your error documents to your personal taste (or your company's conventions). For demonstration purposes, we present a simple generic error document scheme. For this hypothetic server, we assume that all error messages...

  • possibly are served by different virtual hosts (different host name, different IP address, or different port) on the server machine,
  • show a predefined company logo in the right top of the message (selectable by virtual host),
  • print the error title first, followed by an explanatory text and (depending on the error context) help on how to resolve the error,
  • have some kind of standardized background image,
  • display an apache logo and a feedback email address at the bottom of the error message.

An example of a "document not found" message for a german client might look like this:

[Needs graphics capability to display]

All links in the document as well as links to the server's administrator mail address, and even the name and port of the serving virtual host are inserted in the error document at "run-time", i.e., when the error actually occurs.

Creating an ErrorDocument directory

For this concept to work as easily as possible, we must take advantage of as much server support as we can get:

  1. By defining the MultiViews Options, we enable the language selection of the most appropriate language alternative (content negotiation).
  2. By setting the LanguagePriority directive we define a set of default fallback languages in the situation where the client's browser did not express any preference at all.
  3. By enabling mod_include (and disallowing execution of cgi scripts for security reasons), we allow the server to include building blocks of the error message, and to substitute the value of certain environment variables into the generated document (dynamic HTML) or even to conditionally include or omit parts of the text.
  4. The AddHandler and AddType directives are useful for automatically SSI-expanding all files with a .shtml suffix to text/html.
  5. By using the Alias directive, we keep the error document directory outside of the document tree because it can be regarded more as a server part than part of the document tree.
  6. The <Directory> block restricts these "special" settings to the error document directory and avoids an impact on any of the settings for the regular document tree.
  7. For each of the error codes to be handled (see RFC2068 for an exact description of each error code, or look at src/main/http_protocol.c if you wish to see apache's standard messages), an ErrorDocument in the aliased /errordocs directory is defined. Note that we only define the basename of the document here because the MultiViews option will select the best candidate based on the language suffixes and the client's preferences. Any error situation with an error code not handled by a custom document will be dealt with by the server in the standard way (i.e., a plain error message in english).
  8. Finally, the AllowOverride directive tells apache that it is not necessary to look for a .htaccess file in the /errordocs directory: a minor speed optimization.

The resulting httpd.conf configuration would then look similar to this:

Note

Note that you can define your own error messages using this method for only part of the document tree, e.g., a /~user/ subtree. In this case, the configuration could as well be put into the .htaccess file at the root of the subtree, and the <Directory> and </Directory> directives -but not the contained directives- must be omitted.

LanguagePriority en fr de
Alias /errordocs /usr/local/apache/errordocs

<Directory /usr/local/apache/errordocs>
AllowOverride none
Options MultiViews IncludesNoExec FollowSymLinks
AddType text/html .shtml
<FilesMatch "\.shtml[.$]">
SetOutputFilter INCLUDES
</FilesMatch>
</Directory>

# "400 Bad Request",
ErrorDocument 400 /errordocs/400
# "401 Authorization Required",
ErrorDocument 401 /errordocs/401
# "403 Forbidden",
ErrorDocument 403 /errordocs/403
# "404 Not Found",
ErrorDocument 404 /errordocs/404
# "500 Internal Server Error",
ErrorDocument 500 /errordocs/500

The directory for the error messages (here: /usr/local/apache/errordocs/) must then be created with the appropriate permissions (readable and executable by the server uid or gid, only writable for the administrator).

Naming the Individual Error Document files

By defining the MultiViews option, the server was told to automatically scan the directory for matching variants (looking at language and content type suffixes) when a requested document was not found. In the configuration, we defined the names for the error documents to be just their error number (without any suffix).

The names of the individual error documents are now determined like this (I'm using 403 as an example, think of it as a placeholder for any of the configured error documents):

  • No file errordocs/403 should exist. Otherwise, it would be found and served (with the DefaultType, usually text/plain), all negotiation would be bypassed.
  • For each language for which we have an internationalized version (note that this need not be the same set of languages for each error code - you can get by with a single language version until you actually have translated versions), a document errordocs/403.shtml.lang is created and filled with the error text in that language (see below).
  • One fallback document called errordocs/403.shtml is created, usually by creating a symlink to the default language variant (see below).

The Common Header and Footer Files

By putting as much layout information in two special "include files", the error documents can be reduced to a bare minimum.

One of these layout files defines the HTML document header and a configurable list of paths to the icons to be shown in the resulting error document. These paths are exported as a set of SSI environment variables and are later evaluated by the "footer" special file. The title of the current error (which is put into the TITLE tag and an H1 header) is simply passed in from the main error document in a variable called title.

By changing this file, the layout of all generated error messages can be changed in a second. (By exploiting the features of SSI, you can easily define different layouts based on the current virtual host, or even based on the client's domain name).

The second layout file describes the footer to be displayed at the bottom of every error message. In this example, it shows an apache logo, the current server time, the server version string and adds a mail reference to the site's webmaster.

For simplicity, the header file is simply called head.shtml because it contains server-parsed content but no language specific information. The footer file exists once for each language translation, plus a symlink for the default language.

for English, French and German versions (default english)

foot.shtml.en,
foot.shtml.fr,
foot.shtml.de,
foot.shtml symlink to
foot.shtml.en

Both files are included into the error document by using the directives <!--#include virtual="head" --> and <!--#include virtual="foot" --> respectively: the rest of the magic occurs in mod_negotiation and in mod_include.

See the listings below to see an actual HTML implementation of the discussed example.

Creating ErrorDocuments in Different Languages

After all this preparation work, little remains to be said about the actual documents. They all share a simple common structure:

<!--#set var="title" value="error description title" -->
<!--#include virtual="head" -->
explanatory error text
<!--#include virtual="foot" -->

In the listings section, you can see an example of a [400 Bad Request] error document. Documents as simple as that certainly cause no problems to translate or expand.

The Fallback Language

Do we need a special handling for languages other than those we have translations for? We did set the LanguagePriority, didn't we?!

Well, the LanguagePriority directive is for the case where the client does not express any language priority at all. But what happens in the situation where the client wants one of the languages we do not have, and none of those we do have?

Without doing anything, the Apache server will usually return a [406 no acceptable variant] error, listing the choices from which the client may select. But we're in an error message already, and important error information might get lost when the client had to choose a language representation first.

So, in this situation it appears to be easier to define a fallback language (by copying or linking, e.g., the english version to a language-less version). Because the negotiation algorithm prefers "more specialized" variants over "more generic" variants, these generic alternatives will only be chosen when the normal negotiation did not succeed.

A simple shell script to do it (execute within the errordocs/ dir):

for f in *.shtml.en
do
ln -s $f `basename $f .en`
done

Customizing Proxy Error Messages

As of Apache-1.3, it is possible to use the ErrorDocument mechanism for proxy error messages as well (previous versions always returned fixed predefined error messages).

Most proxy errors return an error code of [500 Internal Server Error]. To find out whether a particular error document was invoked on behalf of a proxy error or because of some other server error, and what the reason for the failure was, you can check the contents of the new ERROR_NOTES CGI environment variable: if invoked for a proxy error, this variable will contain the actual proxy error message text in HTML form.

The following excerpt demonstrates how to exploit the ERROR_NOTES variable within an error document:

<!--#if expr="$REDIRECT_ERROR_NOTES = ''" -->

<p>
The server encountered an unexpected condition
which prevented it from fulfilling the request.
</p>

<p>
<a href="mailto:<!--#echo var="SERVER_ADMIN" -->"
SUBJECT="Error message [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> for <!--#echo var="REQUEST_URI" -->">
Please forward this error screen to <!--#echo var="SERVER_NAME" -->'s
WebMaster</a>; it includes useful debugging information about
the Request which caused the error.

<pre><!--#printenv --></pre>
</p>

<!--#else -->
<!--#echo var="REDIRECT_ERROR_NOTES" -->
<!--#endif -->

HTML Listing of the Discussed Example

So, to summarize our example, here's the complete listing of the 400.shtml.en document. You will notice that it contains almost nothing but the error text (with conditional additions). Starting with this example, you will find it easy to add more error documents, or to translate the error documents to different languages.

<!--#set var="title" value="Bad Request"-->
<!--#include virtual="head" -->

<p>
Your browser sent a request that this server could not understand:
<blockquote>
<strong><!--#echo var="REQUEST_URI" --></strong>
 </blockquote>

The request could not be understood by the server due to malformed
syntax. The client should not repeat the request without
modifications.
</p>

<p>
<!--#if expr="$HTTP_REFERER != ''" -->
Please inform the owner of
<a href="<!--#echo var="HTTP_REFERER" -->">the referring page</a> about
the malformed link.

<!--#else -->
Please check your request for typing errors and retry.

<!--#endif -->
</p>

<!--#include virtual="foot" -->

Here is the complete head.shtml.en file (the funny line breaks avoid empty lines in the document after SSI processing). Note the configuration section at top. That's where you configure the images and logos as well as the apache documentation directory. Look how this file displays two different logos depending on the content of the virtual host name ($SERVER_NAME), and that an animated apache logo is shown if the browser appears to support it (the latter requires server configuration lines of the form

BrowserMatch "^Mozilla/[2-4]" anigif

for browser types which support animated GIFs).

<!--#if expr="$SERVER_NAME = /.*\.mycompany\.com/" -->
<!--#set var="IMG_CorpLogo" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif" -->
<!--#set var="ALT_CorpLogo" value="Powered by Linux!" -->
<!--#else -->
<!--#set var="IMG_CorpLogo" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/PrivLogo.gif" -->
<!--#set var="ALT_CorpLogo" value="Powered by Linux!" -->
<!--#endif-->

<!--#set var="IMG_BgImage" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/BgImage.gif" -->
<!--#set var="DOC_Apache" value="http://$SERVER_NAME:$SERVER_PORT/Apache/" -->

<!--#if expr="$anigif" -->
<!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_anim.gif" -->
<!--#else-->
<!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_pb.gif" -->
 <!--#endif-->

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>
[<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" -->
</title>
</head>

<body bgcolor="white" background="<!--#echo var="IMG_BgImage" -->">
<h1 align="center">
[<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" -->
<img src="<!--#echo var="IMG_CorpLogo" -->"
  alt="<!--#echo var="ALT_CorpLogo" -->" align="right">
</h1>

<hr /> <!-- ======================================================== -->
<div>

and this is the foot.shtml.en file:

</div>
<hr />

<div align="right">
<small>Local Server time: <!--#echo var="DATE_LOCAL" --></small>
</div>

<div align="center">
<a href="<!--#echo var="DOC_Apache" -->">
<img src="<!--#echo var="IMG_Apache" -->" border="0" align="bottom"
  alt="Powered by <!--#echo var="SERVER_SOFTWARE" -->"></a>
<br />
<small><!--#set var="var" value="Powered by $SERVER_SOFTWARE --
File last modified on $LAST_MODIFIED" -->
<!--#echo var="var" --></small>
</div>

<p>If the indicated error looks like a misconfiguration, please inform
<a href="mailto:<!--#echo var="SERVER_ADMIN" -->"
subject="Feedback about Error message [<!--#echo var="REDIRECT_STATUS" -->]
<!--#echo var="title" -->, req=<!--#echo var="REQUEST_URI" -->">
<!--#echo var="SERVER_NAME" -->'s WebMaster</a>.
</p>
</body>
</html>

If you have tips to contribute, send mail to martin@apache.org


Connections in the FIN_WAIT_2 state and Apache - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Miscellaneous Documentation

Connections in the FIN_WAIT_2 state and Apache

Warning:

This document has not been fully updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

Starting with the Apache 1.2 betas, people are reporting many more connections in the FIN_WAIT_2 state (as reported by netstat) than they saw using older versions. When the server closes a TCP connection, it sends a packet with the FIN bit set to the client, which then responds with a packet with the ACK bit set. The client then sends a packet with the FIN bit set to the server, which responds with an ACK and the connection is closed. The state that the connection is in during the period between when the server gets the ACK from the client and the server gets the FIN from the client is known as FIN_WAIT_2. See the TCP RFC for the technical details of the state transitions.

The FIN_WAIT_2 state is somewhat unusual in that there is no timeout defined in the standard for it. This means that on many operating systems, a connection in the FIN_WAIT_2 state will stay around until the system is rebooted. If the system does not have a timeout and too many FIN_WAIT_2 connections build up, it can fill up the space allocated for storing information about the connections and crash the kernel. The connections in FIN_WAIT_2 do not tie up an httpd process.

Why Does It Happen?

There are numerous reasons for it happening, some of them may not yet be fully clear. What is known follows.

Buggy Clients and Persistent Connections

Several clients have a bug which pops up when dealing with persistent connections (aka keepalives). When the connection is idle and the server closes the connection (based on the KeepAliveTimeout), the client is programmed so that the client does not send back a FIN and ACK to the server. This means that the connection stays in the FIN_WAIT_2 state until one of the following happens:

  • The client opens a new connection to the same or a different site, which causes it to fully close the older connection on that socket.
  • The user exits the client, which on some (most?) clients causes the OS to fully shutdown the connection.
  • The FIN_WAIT_2 times out, on servers that have a timeout for this state.

If you are lucky, this means that the buggy client will fully close the connection and release the resources on your server. However, there are some cases where the socket is never fully closed, such as a dialup client disconnecting from their provider before closing the client. In addition, a client might sit idle for days without making another connection, and thus may hold its end of the socket open for days even though it has no further use for it. This is a bug in the browser or in its operating system's TCP implementation.

The clients on which this problem has been verified to exist:

  • Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE i386)
  • Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE i386)
  • Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m)
  • MSIE 3.01 on the Macintosh
  • MSIE 3.01 on Windows 95

This does not appear to be a problem on:

  • Mozilla/3.01 (Win95; I)

It is expected that many other clients have the same problem. What a client should do is periodically check its open socket(s) to see if they have been closed by the server, and close their side of the connection if the server has closed. This check need only occur once every few seconds, and may even be detected by a OS signal on some systems (e.g., Win95 and NT clients have this capability, but they seem to be ignoring it).

Apache cannot avoid these FIN_WAIT_2 states unless it disables persistent connections for the buggy clients, just like we recommend doing for Navigator 2.x clients due to other bugs. However, non-persistent connections increase the total number of connections needed per client and slow retrieval of an image-laden web page. Since non-persistent connections have their own resource consumptions and a short waiting period after each closure, a busy server may need persistence in order to best serve its clients.

As far as we know, the client-caused FIN_WAIT_2 problem is present for all servers that support persistent connections, including Apache 1.1.x and 1.2.

A necessary bit of code introduced in 1.2

While the above bug is a problem, it is not the whole problem. Some users have observed no FIN_WAIT_2 problems with Apache 1.1.x, but with 1.2b enough connections build up in the FIN_WAIT_2 state to crash their server. The most likely source for additional FIN_WAIT_2 states is a function called lingering_close() which was added between 1.1 and 1.2. This function is necessary for the proper handling of persistent connections and any request which includes content in the message body (e.g., PUTs and POSTs). What it does is read any data sent by the client for a certain time after the server closes the connection. The exact reasons for doing this are somewhat complicated, but involve what happens if the client is making a request at the same time the server sends a response and closes the connection. Without lingering, the client might be forced to reset its TCP input buffer before it has a chance to read the server's response, and thus understand why the connection has closed. See the appendix for more details.

The code in lingering_close() appears to cause problems for a number of factors, including the change in traffic patterns that it causes. The code has been thoroughly reviewed and we are not aware of any bugs in it. It is possible that there is some problem in the BSD TCP stack, aside from the lack of a timeout for the FIN_WAIT_2 state, exposed by the lingering_close code that causes the observed problems.

What Can I Do About it?

There are several possible workarounds to the problem, some of which work better than others.

Add a timeout for FIN_WAIT_2

The obvious workaround is to simply have a timeout for the FIN_WAIT_2 state. This is not specified by the RFC, and could be claimed to be a violation of the RFC, but it is widely recognized as being necessary. The following systems are known to have a timeout:

  • FreeBSD versions starting at 2.0 or possibly earlier.
  • NetBSD version 1.2(?)
  • OpenBSD all versions(?)
  • BSD/OS 2.1, with the K210-027 patch installed.
  • Solaris as of around version 2.2. The timeout can be tuned by using ndd to modify tcp_fin_wait_2_flush_interval, but the default should be appropriate for most servers and improper tuning can have negative impacts.
  • Linux 2.0.x and earlier(?)
  • HP-UX 10.x defaults to terminating connections in the FIN_WAIT_2 state after the normal keepalive timeouts. This does not refer to the persistent connection or HTTP keepalive timeouts, but the SO_LINGER socket option which is enabled by Apache. This parameter can be adjusted by using nettune to modify parameters such as tcp_keepstart and tcp_keepstop. In later revisions, there is an explicit timer for connections in FIN_WAIT_2 that can be modified; contact HP support for details.
  • SGI IRIX can be patched to support a timeout. For IRIX 5.3, 6.2, and 6.3, use patches 1654, 1703 and 1778 respectively. If you have trouble locating these patches, please contact your SGI support channel for help.
  • NCR's MP RAS Unix 2.xx and 3.xx both have FIN_WAIT_2 timeouts. In 2.xx it is non-tunable at 600 seconds, while in 3.xx it defaults to 600 seconds and is calculated based on the tunable "max keep alive probes" (default of 8) multiplied by the "keep alive interval" (default 75 seconds).
  • Sequent's ptx/TCP/IP for DYNIX/ptx has had a FIN_WAIT_2 timeout since around release 4.1 in mid-1994.

The following systems are known to not have a timeout:

  • SunOS 4.x does not and almost certainly never will have one because it as at the very end of its development cycle for Sun. If you have kernel source should be easy to patch.

There is a patch available for adding a timeout to the FIN_WAIT_2 state; it was originally intended for BSD/OS, but should be adaptable to most systems using BSD networking code. You need kernel source code to be able to use it.

Compile without using lingering_close()

It is possible to compile Apache 1.2 without using the lingering_close() function. This will result in that section of code being similar to that which was in 1.1. If you do this, be aware that it can cause problems with PUTs, POSTs and persistent connections, especially if the client uses pipelining. That said, it is no worse than on 1.1, and we understand that keeping your server running is quite important.

To compile without the lingering_close() function, add -DNO_LINGCLOSE to the end of the EXTRA_CFLAGS line in your Configuration file, rerun Configure and rebuild the server.

Use SO_LINGER as an alternative to lingering_close()

On most systems, there is an option called SO_LINGER that can be set with setsockopt(2). It does something very similar to lingering_close(), except that it is broken on many systems so that it causes far more problems than lingering_close. On some systems, it could possibly work better so it may be worth a try if you have no other alternatives.

To try it, add -DUSE_SO_LINGER -DNO_LINGCLOSE to the end of the EXTRA_CFLAGS line in your Configuration file, rerun Configure and rebuild the server.

NOTE

Attempting to use SO_LINGER and lingering_close() at the same time is very likely to do very bad things, so don't.

Increase the amount of memory used for storing connection state

BSD based networking code:
BSD stores network data, such as connection states, in something called an mbuf. When you get so many connections that the kernel does not have enough mbufs to put them all in, your kernel will likely crash. You can reduce the effects of the problem by increasing the number of mbufs that are available; this will not prevent the problem, it will just make the server go longer before crashing.

The exact way to increase them may depend on your OS; look for some reference to the number of "mbufs" or "mbuf clusters". On many systems, this can be done by adding the line NMBCLUSTERS="n", where n is the number of mbuf clusters you want to your kernel config file and rebuilding your kernel.

Disable KeepAlive

If you are unable to do any of the above then you should, as a last resort, disable KeepAlive. Edit your httpd.conf and change "KeepAlive On" to "KeepAlive Off".

Appendix

Below is a message from Roy Fielding, one of the authors of HTTP/1.1.

Why the lingering close functionality is necessary with HTTP

The need for a server to linger on a socket after a close is noted a couple times in the HTTP specs, but not explained. This explanation is based on discussions between myself, Henrik Frystyk, Robert S. Thau, Dave Raggett, and John C. Mallery in the hallways of MIT while I was at W3C.

If a server closes the input side of the connection while the client is sending data (or is planning to send data), then the server's TCP stack will signal an RST (reset) back to the client. Upon receipt of the RST, the client will flush its own incoming TCP buffer back to the un-ACKed packet indicated by the RST packet argument. If the server has sent a message, usually an error response, to the client just before the close, and the client receives the RST packet before its application code has read the error message from its incoming TCP buffer and before the server has received the ACK sent by the client upon receipt of that buffer, then the RST will flush the error message before the client application has a chance to see it. The result is that the client is left thinking that the connection failed for no apparent reason.

There are two conditions under which this is likely to occur:

  1. sending POST or PUT data without proper authorization
  2. sending multiple requests before each response (pipelining) and one of the middle requests resulting in an error or other break-the-connection result.

The solution in all cases is to send the response, close only the write half of the connection (what shutdown is supposed to do), and continue reading on the socket until it is either closed by the client (signifying it has finally read the response) or a timeout occurs. That is what the kernel is supposed to do if SO_LINGER is set. Unfortunately, SO_LINGER has no effect on some systems; on some other systems, it does not have its own timeout and thus the TCP memory segments just pile-up until the next reboot (planned or not).

Please note that simply removing the linger code will not solve the problem -- it only moves it to a different and much harder one to detect.


Known Problems in Clients - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Miscellaneous Documentation

Known Problems in Clients

Warning:

This document has not been fully updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

Over time the Apache Group has discovered or been notified of problems with various clients which we have had to work around, or explain. This document describes these problems and the workarounds available. It's not arranged in any particular order. Some familiarity with the standards is assumed, but not necessary.

For brevity, Navigator will refer to Netscape's Navigator product (which in later versions was renamed "Communicator" and various other names), and MSIE will refer to Microsoft's Internet Explorer product. All trademarks and copyrights belong to their respective companies. We welcome input from the various client authors to correct inconsistencies in this paper, or to provide us with exact version numbers where things are broken/fixed.

For reference, RFC1945 defines HTTP/1.0, and RFC2068 defines HTTP/1.1. Apache as of version 1.2 is an HTTP/1.1 server (with an optional HTTP/1.0 proxy).

Various of these workarounds are triggered by environment variables. The admin typically controls which are set, and for which clients, by using mod_browser. Unless otherwise noted all of these workarounds exist in versions 1.2 and later.

Trailing CRLF on POSTs

This is a legacy issue. The CERN webserver required POST data to have an extra CRLF following it. Thus many clients send an extra CRLF that is not included in the Content-Length of the request. Apache works around this problem by eating any empty lines which appear before a request.

Broken KeepAlive

Various clients have had broken implementations of keepalive (persistent connections). In particular the Windows versions of Navigator 2.0 get very confused when the server times out an idle connection. The workaround is present in the default config files:

BrowserMatch Mozilla/2 nokeepalive

Note that this matches some earlier versions of MSIE, which began the practice of calling themselves Mozilla in their user-agent strings just like Navigator.

MSIE 4.0b2, which claims to support HTTP/1.1, does not properly support keepalive when it is used on 301 or 302 (redirect) responses. Unfortunately Apache's nokeepalive code prior to 1.2.2 would not work with HTTP/1.1 clients. You must apply this patch to version 1.2.1. Then add this to your config:

BrowserMatch "MSIE 4\.0b2;" nokeepalive

Incorrect interpretation of HTTP/1.1 in response

To quote from section 3.1 of RFC1945:

HTTP uses a "<MAJOR>.<MINOR>" numbering scheme to indicate versions of the protocol. The protocol versioning policy is intended to allow the sender to indicate the format of a message and its capacity for understanding further HTTP communication, rather than the features obtained via that communication.

Since Apache is an HTTP/1.1 server, it indicates so as part of its response. Many client authors mistakenly treat this part of the response as an indication of the protocol that the response is in, and then refuse to accept the response.

The first major indication of this problem was with AOL's proxy servers. When Apache 1.2 went into beta it was the first wide-spread HTTP/1.1 server. After some discussion, AOL fixed their proxies. In anticipation of similar problems, the force-response-1.0 environment variable was added to Apache. When present Apache will indicate "HTTP/1.0" in response to an HTTP/1.0 client, but will not in any other way change the response.

The pre-1.1 Java Development Kit (JDK) that is used in many clients (including Navigator 3.x and MSIE 3.x) exhibits this problem. As do some of the early pre-releases of the 1.1 JDK. We think it is fixed in the 1.1 JDK release. In any event the workaround:

BrowserMatch Java/1.0 force-response-1.0
BrowserMatch JDK/1.0 force-response-1.0

RealPlayer 4.0 from Progressive Networks also exhibits this problem. However they have fixed it in version 4.01 of the player, but version 4.01 uses the same User-Agent as version 4.0. The workaround is still:

BrowserMatch "RealPlayer 4.0" force-response-1.0

Requests use HTTP/1.1 but responses must be in HTTP/1.0

MSIE 4.0b2 has this problem. Its Java VM makes requests in HTTP/1.1 format but the responses must be in HTTP/1.0 format (in particular, it does not understand chunked responses). The workaround is to fool Apache into believing the request came in HTTP/1.0 format.

BrowserMatch "MSIE 4\.0b2;" downgrade-1.0 force-response-1.0

This workaround is available in 1.2.2, and in a patch against 1.2.1.

Boundary problems with header parsing

All versions of Navigator from 2.0 through 4.0b2 (and possibly later) have a problem if the trailing CRLF of the response header starts at offset 256, 257 or 258 of the response. A BrowserMatch for this would match on nearly every hit, so the workaround is enabled automatically on all responses. The workaround implemented detects when this condition would occur in a response and adds extra padding to the header to push the trailing CRLF past offset 258 of the response.

Multipart responses and Quoted Boundary Strings

On multipart responses some clients will not accept quotes (") around the boundary string. The MIME standard recommends that such quotes be used. But the clients were probably written based on one of the examples in RFC2068, which does not include quotes. Apache does not include quotes on its boundary strings to workaround this problem.

Byterange Requests

A byterange request is used when the client wishes to retrieve a portion of an object, not necessarily the entire object. There was a very old draft which included these byteranges in the URL. Old clients such as Navigator 2.0b1 and MSIE 3.0 for the MAC exhibit this behaviour, and it will appear in the servers' access logs as (failed) attempts to retrieve a URL with a trailing ";xxx-yyy". Apache does not attempt to implement this at all.

A subsequent draft of this standard defines a header Request-Range, and a response type multipart/x-byteranges. The HTTP/1.1 standard includes this draft with a few fixes, and it defines the header Range and type multipart/byteranges.

Navigator (versions 2 and 3) sends both Range and Request-Range headers (with the same value), but does not accept a multipart/byteranges response. The response must be multipart/x-byteranges. As a workaround, if Apache receives a Request-Range header it considers it "higher priority" than a Range header and in response uses multipart/x-byteranges.

The Adobe Acrobat Reader plugin makes extensive use of byteranges and prior to version 3.01 supports only the multipart/x-byterange response. Unfortunately there is no clue that it is the plugin making the request. If the plugin is used with Navigator, the above workaround works fine. But if the plugin is used with MSIE 3 (on Windows) the workaround won't work because MSIE 3 doesn't give the Range-Request clue that Navigator does. To workaround this, Apache special cases "MSIE 3" in the User-Agent and serves multipart/x-byteranges. Note that the necessity for this with MSIE 3 is actually due to the Acrobat plugin, not due to the browser.

Netscape Communicator appears to not issue the non-standard Request-Range header. When an Acrobat plugin prior to version 3.01 is used with it, it will not properly understand byteranges. The user must upgrade their Acrobat reader to 3.01.

Set-Cookie header is unmergeable

The HTTP specifications say that it is legal to merge headers with duplicate names into one (separated by commas). Some browsers that support Cookies don't like merged headers and prefer that each Set-Cookie header is sent separately. When parsing the headers returned by a CGI, Apache will explicitly avoid merging any Set-Cookie headers.

Expires headers and GIF89A animations

Navigator versions 2 through 4 will erroneously re-request GIF89A animations on each loop of the animation if the first response included an Expires header. This happens regardless of how far in the future the expiry time is set. There is no workaround supplied with Apache, however there are hacks for 1.2 and for 1.3.

POST without Content-Length

In certain situations Navigator 3.01 through 3.03 appear to incorrectly issue a POST without the request body. There is no known workaround. It has been fixed in Navigator 3.04, Netscapes provides some information. There's also some information about the actual problem.

JDK 1.2 betas lose parts of responses.

The http client in the JDK1.2beta2 and beta3 will throw away the first part of the response body when both the headers and the first part of the body are sent in the same network packet AND keep-alive's are being used. If either condition is not met then it works fine.

See also Bug-ID's 4124329 and 4125538 at the java developer connection.

If you are seeing this bug yourself, you can add the following BrowserMatch directive to work around it:

BrowserMatch "Java1\.2beta[23]" nokeepalive

We don't advocate this though since bending over backwards for beta software is usually not a good idea; ideally it gets fixed, new betas or a final release comes out, and no one uses the broken old software anymore. In theory.

Content-Type change is not noticed after reload

Navigator (all versions?) will cache the content-type for an object "forever". Using reload or shift-reload will not cause Navigator to notice a content-type change. The only work-around is for the user to flush their caches (memory and disk). By way of an example, some folks may be using an old mime.types file which does not map .htm to text/html, in this case Apache will default to sending text/plain. If the user requests the page and it is served as text/plain. After the admin fixes the server, the user will have to flush their caches before the object will be shown with the correct text/html type.

MSIE Cookie problem with expiry date in the year 2000

MSIE versions 3.00 and 3.02 (without the Y2K patch) do not handle cookie expiry dates in the year 2000 properly. Years after 2000 and before 2000 work fine. This is fixed in IE4.01 service pack 1, and in the Y2K patch for IE3.02. Users should avoid using expiry dates in the year 2000.

Lynx incorrectly asking for transparent content negotiation

The Lynx browser versions 2.7 and 2.8 send a "negotiate: trans" header in their requests, which is an indication the browser supports transparent content negotiation (TCN). However the browser does not support TCN. As of version 1.3.4, Apache supports TCN, and this causes problems with these versions of Lynx. As a workaround future versions of Apache will ignore this header when sent by the Lynx client.

MSIE 4.0 mishandles Vary response header

MSIE 4.0 does not handle a Vary header properly. The Vary header is generated by mod_rewrite in apache 1.3. The result is an error from MSIE saying it cannot download the requested file. There are more details in PR#4118.

A workaround is to add the following to your server's configuration files:

BrowserMatch "MSIE 4\.0" force-no-vary

(This workaround is only available with releases after 1.3.6 of the Apache Web server.)


Descriptors and Apache - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Miscellaneous Documentation

Descriptors and Apache

Warning:

This document has not been fully updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

A descriptor, also commonly called a file handle is an object that a program uses to read or write an open file, or open network socket, or a variety of other devices. It is represented by an integer, and you may be familiar with stdin, stdout, and stderr which are descriptors 0, 1, and 2 respectively. Apache needs a descriptor for each log file, plus one for each network socket that it listens on, plus a handful of others. Libraries that Apache uses may also require descriptors. Normal programs don't open up many descriptors at all, and so there are some latent problems that you may experience should you start running Apache with many descriptors (i.e., with many virtual hosts).

The operating system enforces a limit on the number of descriptors that a program can have open at a time. There are typically three limits involved here. One is a kernel limitation, depending on your operating system you will either be able to tune the number of descriptors available to higher numbers (this is frequently called FD_SETSIZE). Or you may be stuck with a (relatively) low amount. The second limit is called the hard resource limit, and it is sometimes set by root in an obscure operating system file, but frequently is the same as the kernel limit. The third limit is called the soft resource limit. The soft limit is always less than or equal to the hard limit. For example, the hard limit may be 1024, but the soft limit only 64. Any user can raise their soft limit up to the hard limit. Root can raise the hard limit up to the system maximum limit. The soft limit is the actual limit that is used when enforcing the maximum number of files a process can have open.

To summarize:

#open files <= soft limit <= hard limit <= kernel limit

You control the hard and soft limits using the limit (csh) or ulimit (sh) directives. See the respective man pages for more information. For example you can probably use ulimit -n unlimited to raise your soft limit up to the hard limit. You should include this command in a shell script which starts your webserver.

Unfortunately, it's not always this simple. As mentioned above, you will probably run into some system limitations that will need to be worked around somehow. Work was done in version 1.2.1 to improve the situation somewhat. Here is a partial list of systems and workarounds (assuming you are using 1.2.1 or later).

BSDI 2.0

Under BSDI 2.0 you can build Apache to support more descriptors by adding -DFD_SETSIZE=nnn to EXTRA_CFLAGS (where nnn is the number of descriptors you wish to support, keep it less than the hard limit). But it will run into trouble if more than approximately 240 Listen directives are used. This may be cured by rebuilding your kernel with a higher FD_SETSIZE.

FreeBSD 2.2, BSDI 2.1+

Similar to the BSDI 2.0 case, you should define FD_SETSIZE and rebuild. But the extra Listen limitation doesn't exist.

Linux

By default Linux has a kernel maximum of 256 open descriptors per process. There are several patches available for the 2.0.x series which raise this to 1024 and beyond, and you can find them in the "unofficial patches" section of the Linux Information HQ. None of these patches are perfect, and an entirely different approach is likely to be taken during the 2.1.x development. Applying these patches will raise the FD_SETSIZE used to compile all programs, and unless you rebuild all your libraries you should avoid running any other program with a soft descriptor limit above 256. As of this writing the patches available for increasing the number of descriptors do not take this into account. On a dedicated webserver you probably won't run into trouble.

Solaris through 2.5.1

Solaris has a kernel hard limit of 1024 (may be lower in earlier versions). But it has a limitation that files using the stdio library cannot have a descriptor above 255. Apache uses the stdio library for the ErrorLog directive. When you have more than approximately 110 virtual hosts (with an error log and an access log each) you will need to build Apache with -DHIGH_SLACK_LINE=256 added to EXTRA_CFLAGS. You will be limited to approximately 240 error logs if you do this.

AIX

AIX version 3.2?? appears to have a hard limit of 128 descriptors. End of story. Version 4.1.5 has a hard limit of 2000.

SCO OpenServer

Edit the /etc/conf/cf.d/stune file or use /etc/conf/cf.d/configure choice 7 (User and Group configuration) and modify the NOFILES kernel parameter to a suitably higher value. SCO recommends a number between 60 and 11000, the default is 110. Relink and reboot, and the new number of descriptors will be available.

Compaq Tru64 UNIX/Digital UNIX/OSF

  1. Raise open_max_soft and open_max_hard to 4096 in the proc subsystem. Do a man on sysconfig, sysconfigdb, and sysconfigtab.
  2. Raise max-vnodes to a large number which is greater than the number of apache processes * 4096 (Setting it to 250,000 should be good for most people). Do a man on sysconfig, sysconfigdb, and sysconfigtab.
  3. If you are using Tru64 5.0, 5.0A, or 5.1, define NO_SLACK to work around a bug in the OS. CFLAGS="-DNO_SLACK" ./configure

Others

If you have details on another operating system, please submit it through our Bug Report Page.

In addition to the problems described above there are problems with many libraries that Apache uses. The most common example is the bind DNS resolver library that is used by pretty much every unix, which fails if it ends up with a descriptor above 256. We suspect there are other libraries that similar limitations. So the code as of 1.2.1 takes a defensive stance and tries to save descriptors less than 16 for use while processing each request. This is called the low slack line.

Note that this shouldn't waste descriptors. If you really are pushing the limits and Apache can't get a descriptor above 16 when it wants it, it will settle for one below 16.

In extreme situations you may want to lower the low slack line, but you shouldn't ever need to. For example, lowering it can increase the limits 240 described above under Solaris and BSDI 2.0. But you'll play a delicate balancing game with the descriptors needed to serve a request. Should you want to play this game, the compile time parameter is LOW_SLACK_LINE and there's a tiny bit of documentation in the header file httpd.h.

Finally, if you suspect that all this slack stuff is causing you problems, you can disable it. Add -DNO_SLACK to EXTRA_CFLAGS and rebuild. But please report it to our Bug Report Page so that we can investigate.


Relevant Standards - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Miscellaneous Documentation

Relevant Standards

This page documents all the relevant standards that the Apache HTTP Server follows, along with brief descriptions.

In addition to the information listed below, the following resources should be consulted:

  • http://purl.org/NET/http-errata - HTTP/1.1 Specification Errata
  • http://www.rfc-editor.org/errata.html - RFC Errata
  • http://ftp.ics.uci.edu/pub/ietf/http/#RFC - A pre-compiled list of HTTP related RFCs

Notice

This document is not yet complete.

HTTP Recommendations

Regardless of what modules are compiled and used, Apache as a basic web server complies with the following IETF recommendations:

RFC 1945 (Informational)
The Hypertext Transfer Protocol (HTTP) is an application-level protocol with the lightness and speed necessary for distributed, collaborative, hypermedia information systems. This documents HTTP/1.0.
RFC 2616 (Standards Track)
The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. This documents HTTP/1.1.
RFC 2396 (Standards Track)
A Uniform Resource Identifier (URI) is a compact string of characters for identifying an abstract or physical resource.

HTML Recommendations

Regarding the Hypertext Markup Language, Apache complies with the following IETF and W3C recommendations:

RFC 2854 (Informational)
This document summarizes the history of HTML development, and defines the "text/html" MIME type by pointing to the relevant W3C recommendations.
HTML 4.01 Specification (Errata)
This specification defines the HyperText Markup Language (HTML), the publishing language of the World Wide Web. This specification defines HTML 4.01, which is a subversion of HTML 4.
HTML 3.2 Reference Specification
The HyperText Markup Language (HTML) is a simple markup language used to create hypertext documents that are portable from one platform to another. HTML documents are SGML documents.
XHTML 1.1 - Module-based XHTML (Errata)
This Recommendation defines a new XHTML document type that is based upon the module framework and modules defined in Modularization of XHTML.
XHTML 1.0 The Extensible HyperText Markup Language (Second Edition) (Errata)
This specification defines the Second Edition of XHTML 1.0, a reformulation of HTML 4 as an XML 1.0 application, and three DTDs corresponding to the ones defined by HTML 4.

Authentication

Concerning the different methods of authentication, Apache follows the following IETF recommendations:

RFC 2617 (Draft standard)
"HTTP/1.0", includes the specification for a Basic Access Authentication scheme.

Language/Country Codes

The following links document ISO and other language and country code information:

ISO 639-2
ISO 639 provides two sets of language codes, one as a two-letter code set (639-1) and another as a three-letter code set (this part of ISO 639) for the representation of names of languages.
ISO 3166-1
These pages document the country names (official short names in English) in alphabetical order as given in ISO 3166-1 and the corresponding ISO 3166-1-alpha-2 code elements.
BCP 47 (Best Current Practice), RFC 3066
This document describes a language tag for use in cases where it is desired to indicate the language used in an information object, how to register values for use in this language tag, and a construct for matching such language tags.
RFC 3282 (Standards Track)
This document defines a "Content-language:" header, for use in cases where one desires to indicate the language of something that has RFC 822-like headers, like MIME body parts or Web documents, and an "Accept-Language:" header for use in cases where one wishes to indicate one's preferences with regard to language.


Apache モジュールの解説で使用する用語 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

Apache モジュールの解説で使用する用語

この文書は Apache の各 モジュール を説明するために 使われている用語を説明します。

説明

モジュールの目的の短い説明。

ステータス

これは、そのモジュールが Apache ウェブサーバにどれくらい密接に組み込まれているかを示します。 言い換えれば、モジュールを組み込み、その機能を利用するために、 サーバを再コンパイルする必要があるかもしれないということを示します。 この属性が取り得る値は以下のものです:

MPM
ステータスが "MPM" のモジュールはマルチプロセッシングモジュールです。 他の種類のモジュールとは違って、Apache は常に MPM を一つだけ 使用し続けます。この種類のモジュールは基本的なリクエストの扱いと ディスパッチを行ないます。
Base
ステータスが "Base" のモジュールは、デフォルトでコンパイルされてわざわざ設定から モジュールを削除していない限り、通常は利用可能です。
Extension
ステータスが "Extension" のモジュールは、 デフォルトではコンパイルされず、サーバにも読み込まれません。 そのモジュールとその機能を有効にするには、 サーバをビルドするための設定を変更して、Apache を再コンパイルする必要があります。
Experimental
ステータスが "Experimental" のモジュールは、 Apache 配布物に同梱されていますが、 使用する場合は自己責任で行なう必要があります。 そのモジュールは、ドキュメントも完成に向けて作成中ですし、 サポートされるているとは限りません。
External
ステータスが "External" のモジュールは、基本 Apache 配布に同梱されません ("サードパーティーモジュール")。 そのため、我々に責任はありませんし、 そのモジュールのサポートもしていません。

ソースファイル

これは単純に、 そのモジュールに必要なコードを含むソースファイルの名前を列挙したものです。 これは、<IfModule> ディレクティブで使用される名前でもあります。

モジュール識別子

この文字列は、モジュールの動的読み込みを行なうときに使用する LoadModule ディレクティブにおいて使用されるモジュールの識別子です。 詳しく書くと、ソースファイル内の module タイプの外部変数の名前です。

互換性

あるモジュールが Apache バージョン 2 の配布に含まれていなかった場合、 そのモジュールが導入されたバージョンがここに書かれています。 また、モジュールが特定のプラットフォームにのみ存在するときも 詳細はここに書かれています。


ディレクティブの解説に使われる用語 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

ディレクティブの解説に使われる用語

この文書は各 Apache 設定ディレクティブ を説明するために使われている用語を説明します。

参照

  • 設定ファイル

説明

ディレクティブの目的の簡単な説明。

構文

設定ファイル中のディレクティブの書式を示します。 この構文はディレクティブ特有なので、詳細はディレクティブの説明を 参照してください。一般的に、ディレクティブ名の後には 空白により分割されたいくつかの引数が続きます。 引数が空白を含むときは二重引用符 (訳注: ") で囲まれています。 オプショナルな引数は括弧 (訳注: []) で囲まれています。 引数が複数の値を取り得る場合は、それらの値は垂直の棒 "|" で 分割されています。 変更されないテキストはデフォルトのフォントで表示され、置換の必要な 引数は強調されて表示されます。 引数の数が変わるディレクティブは最後の 引数が繰り返されることを示すために "..." で終わります。

ディレクティブは多くの違う型の引数をとります。いくつか、良く 使われるものを以下で定義します。

URL
http://www.example.com/path/to/file.html のように、 スキーム、ホスト名、パス名(省略可能)を含んでいる完全な Uniform Resource Locator。
URL-path
/path/to/file.html のように、スキームと ホスト名の後に続く url の一部。url-path は ファイルシステムからの視点ではなく、 ウェブからの視点でリソースを表現します。
file-path
/usr/local/apache/htdocs/path/to/file.html のように、 ルートディレクトリから始まるローカルのファイルシステム上のファイルへのパス。 通常、スラッシュで始まらない file-path は ServerRoot からの相対パスとして 扱われます。
directory-path
/usr/local/apache/htdocs/path/to/ のように、 ルートディレクトリから始まるローカルのファイルシステムのディレクトリへの パス。
filename
file.html のように、パス情報の付いていない ファイル名。
regex
Perl 互換の正規表現です。 ディレクティブの定義が regex が何に対してマッチを行なうのかを指定します。
extension
一般的には filename の最後のドットの後の部分です。 しかし、Apache は複数のファイルの拡張子を認識しますので、filename に複数のドットがあると、最初のドットの後の、それぞれのドットで分離された部分が extension (訳注: 拡張子) になります。例えば、filename file.html.en には二つの拡張子があります。.html と .en です。Apache のディレクティブでは、extension はドット付きでも無しでも指定できます。さらに、extension は 大文字小文字を区別しません。
MIME-type
text/html のように、スラッシュで分離された 主フォーマットと副フォーマットによってファイルの形式を 表す方法です。
env-variable
Apache の設定により定義される 環境変数の名前です。これはオペレーティングシステムの 環境変数と同じとは限らないことに注意してください。詳細は 環境変数の説明を参照してください。

デフォルト

ディレクティブにデフォルト値 (すなわち、設定ファイルから 省略されていても、Apache ウェブサーバは特定の値に設定されているかのように 動作します) がある場合はここに記述されます。 デフォルト値の無い場合、ここは "None" と 書かれます。ここで書かれているデフォルトはサーバと共に配布されている デフォルトの httpd.conf 内に書かれているディレクティブの値と 違う可能性があることに注意してください。

コンテキスト

これは、サーバの設定ファイル中のどこでディレクティブが有効なのかを示します。 次に示す値が一つ以上カンマ区切りで列挙されています。

サーバ設定ファイル
これは、サーバ設定ファイル (例えば、httpd.conf, srm.conf, access.conf) 内では使用できますが、 <VirtualHost> や <Directory> の中では 使用できないことを示します。 .htaccessファイルでの使用は許可されていません。
バーチャルホスト
これは、サーバ設定ファイルの <VirtualHost> の中で使用できることを示します。
ディレクトリ
これは、サーバ設定ファイルの <Directory>, <Location>, <Files> コンテナの中で、 Directory, Location, Files セクションの動作方法 で説明されている制限の下で使用できることを示します。
.htaccess
これは、ディレクトリ毎の .htaccess ファイル内で 使用可能であることを示します。 ただ、上書き の設定によっては、処理されないかもしれません。

ディレクティブは指示されたコンテキストでのみ許可されます。 他の場所で使おうとすると、サーバがそのコンテキストを正しく扱えなく なるような設定エラーが発生するか、サーバがまったく動作しなくなる、 すなわち、サーバが起動しなくなるということになります。

ディレクティブの有効な位置は、実際は挙げられているコンテキストの 論理和 (訳注: Boolen OR) になります。言い換えると、 "サーバ設定ファイル、.htaccess" で有効だと 記されているディレクティブは httpd.conf ファイルと .htaccess ファイルとで有効ですが、 <Directory> や <VirtualHost> の中では使用できません。

上書き

このディレクティブの属性は、.htaccess ファイル中に ディレクティブが現れたときに、それの処理を有効にするために どの設定の上書きが必要かを示します。 ディレクティブの コンテキスト が、.htaccess ファイル中では許可していない場合は、 この属性は "適用不可" と書かれます。

上書きは、AllowOverride ディレクティブによって有効にされ、 特定のスコープ(ディレクトリなど)と、 さらに下位のレベルの AllowOverride で修正されない限り、 その配下に対して適用されます。 ディレクティブのドキュメントは取り得る上書きの名前も挙げます。

ステータス

これはディレクティブが Apache ウェブサーバにどれくらいきつく組み込まれているかを 示します。言い換えれば、ディレクティブとその機能を利用するために、 モジュールの数を増やして、サーバを再コンパイルする必要があるかもしれない ということを示します。 この属性が取り得る値は以下のものです:

Core
"Core" のディレクティブは Apache ウェブサーバの基本となるべきものであり、 常に使用可能であることを示します。
MPM
"MPM" のディレクティブはマルチプロセッシングモジュールで提供されています。 この種類のディレクティブはディレクティブの定義のモジュールの行に使っているモジュールの名前が書かれている 場合にのみ使用可能です。
Base
"Base" のディレクティブは デフォルトでサーバに組み込まれている標準モジュールの中の一つでサ ポートされていて、わざわざ設定からモジュールを削除したときを除いて、 通常では使用可能であることを示します。
Extension
"Extension" のディレクティブは、 Apache サーバの配布物に同梱されているモジュールの一つで提供されているものの、 通常ではサーバに組み込まれていないことを示します。 ディレクティブとその機能を有効にするには、サーバビルド用の設定ファイルを 変更して Apache を再コンパイルする必要があります。
Experimental
"Experimental" のディレクティブは、Apache 配布物に 同梱されているものの、試したい場合は自己責任で行なう 必要があるということを示します。ディレクティブは、すべてのドキュメントを 完全にそろわせるために解説されていますが、サポートされているとは限りません。 ディレクティブを提供するモジュールはデフォルトで組み込まれているかも しれませんし、そうでないかもしれません。使用可能かどうかは、 ディレクティブとモジュールの説明をしているページの先頭を調べてください。

モジュール

これは単純にディレクティブが定義されているモジュールの名前を記載します。

互換性

ディレクティブが Apache 2 の配布に組み込まれていなかった場合、 ディレクティブが導入されたバージョンがここに書かれています。 また、ディレクティブが特定のプラットフォームにのみ存在するときも ここに書かれています。


core - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache コア機能

説明: | 常に使用可能な Apache HTTP サーバのコア機能
ステータス: | Core

AcceptPathInfo ディレクティブ

説明: | 後に続くパス名情報を受け付けるリソースの指定
構文: | AcceptPathInfo On|Off|Default
デフォルト: | AcceptPathInfo Default
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core
互換性: | Apache 2.0.30 以降で使用可能

このディレクティブは実際のファイル名 (もしくは存在するディレクトリの 存在しないファイル) の後に続くパス名情報があるリクエストを受け付けるか 拒否するかを制御します。続きのパス名情報はスクリプトには PATH_INFO 環境変数として利用可能になります。

例えば、/test/ が、here.html というファイル 一つのみがあるディレクトリを指しているとします。そうすると、 /test/here.html/more と /test/nothere.html/more へのリクエストは両方とも /more を PATH_INFO とします。

AcceptPathInfo ディレクティブに指定可能な 三つの引数は:

Off
リクエストは存在するパスにそのまま マップされる場合にのみ受け付けられます。ですから、上の例の /test/here.html/more のように、本当のファイル名の 後にパス名情報が続くリクエストには 404 NOT FOUND エラーが返ります。
On
前の方のパスが存在するファイルにマップする場合は リクエストが受け付けられます。上の例の /test/here.html/more は /test/here.html が有効なファイルにマップすれば 受け付けられます。
Default
続きのパス名情報の扱いはリクエストの ハンドラで決まります。 普通のファイルのためのコアハンドラのデフォルトは PATH_INFO を拒否します。 cgi-script や isapi-isa のようにスクリプトを扱うハンドラは 一般的にデフォルトで PATH_INFO を受け付けます。

AcceptPathInfo の主な目的はハンドラの PATH_INFO を 受け付けるか拒否するかの選択を上書きできるようにすることです。 例えば、これは例えば INCLUDES のような フィルタを使って PATH_INFO に 基づいてコンテンツを生成しているときに必要になります。

<Files "mypaths.shtml">
Options +Includes
SetOutputFilter INCLUDES
AcceptPathInfo On
 </Files>

AccessFileName ディレクティブ

説明: | 分散設定ファイルの名前
構文: | AccessFileName filename [filename] ...
デフォルト: | AccessFileName .htaccess
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

リクエストを処理するとき、サーバはディレクトリに 対して分散設定ファイルが有効になっていれば、 そのドキュメントへの パス上にある全てのディレクトリから、ここで指定された名前の一覧の中で 最初に見つかったファイルをそれぞれ設定ファイルとして読み込みます。例えば:

AccessFileName .acl

という設定があると、以下のようにして無効にされていない限り、 ドキュメント /usr/local/web/index.html を返す前に、サーバは /.acl, /usr/.acl, /usr/local/.acl, /usr/local/web/.acl から ディレクティブを読み込みます。

<Directory />
AllowOverride None
 </Directory>

参照

  • AllowOverride
  • 設定ファイル
  • .htaccess ファイル

AddDefaultCharset ディレクティブ

説明: | 明示的に文字セットを指定していない応答に追加される デフォルトの文字セット
構文: | AddDefaultCharset On|Off|charset
デフォルト: | AddDefaultCharset Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core

このディレクティブは、HTTP ヘッダにコンテントタイプパラメータを 持たない応答に追加される文字セットの名前を指定します。 これは、ドキュメント内の META タグで指定されたどのような文字セット も無効にします。 AddDefaultCharset Off という設定により、この機能は無効になります。 AddDefaultCharset On にすれば、ディレクティブの要求通り Apache 内部のデフォルト文字セット iso-8859-1 に設定します。 また、他の charset も指定できます。例えば:

AddDefaultCharset utf-8

AddOutputFilterByType ディレクティブ

説明: | MIME-type に出力フィルタを割り当てる
構文: | AddOutputFilterByType filter[;filter...] MIME-type [MIME-type] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core
互換性: | Apache 2.0.33 以降で使用可能

このディレクティブは応答の MIME-type に応じて出力フィルタを使用するようにします。

次の例は mod_deflate の DEFLATE フィルタを 使っています。text/html と text/plain の すべての出力 (静的なものも動的なものも) をクライアントに送られる前に 圧縮します。

AddOutputFilterByType DEFLATE text/html text/plain

複数のフィルタでコンテンツを処理させたいときは、それぞれの名前をセミコロンで 分ける必要があります。各フィルタに対して AddOutputFilterByType を一つずつ書くこともできます。

次の例は text/html のスクリプトのすべての出力を まず INCLUDES フィルタで処理し、さらに DEFLATE フィルタにかけます。

<Location /cgi-bin/>
Options Includes
AddOutputFilterByType INCLUDES;DEFLATE text/html
 </Location>

注:

AddOutputFilterByType ディレクティブにより 有効にしたフィルタは場合によっては、部分的もしくは完全に適用されないことが あります。例えば、MIME タイプがが決定できないときには DefaultType の設定が同じだったとしても、 DefaultType 設定を使うようになります。

しかし、確実にフィルタが適用されるようにしたいときは、リソースに 明示的にコンテントタイプを割り当てることができます。これには例えば AddType ディレクティブや ForceType ディレクティブを使います。 (nphでない) CGI スクリプトでコンテントタイプを設定するというものでも 大丈夫です。

タイプ毎の出力フィルタはプロキシリクエストには決して適用されません。

参照

  • AddOutputFilter
  • SetOutputFilter
  • フィルタ

AllowEncodedSlashes ディレクティブ

説明: | URL 中の符号化されたパス分離文字が先に伝えられるのを許可するかどうかを 決定する
構文: | AllowEncodedSlashes On|Off
デフォルト: | AllowEncodedSlashes Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core
互換性: | Apache 2.0.46 以降で使用可能

AllowEncodedSlashes ディレクティブは符号化された パス分離文字 (/ は %2F、さらにシステムによっては \ に対応する %5C) が存在する URL の使用を 許可するかどうかを決定します。通常はそのような URL は 404 (Not found) エラー で拒否されます。

AllowEncodedSlashes On による パス分離文字の使用は、PATH_INFO と合わせて 使うときに一番役に立ちます。

Turning AllowEncodedSlashes On is mostly useful when used in conjunction with PATH_INFO.

注

符号化されたスラッシュを許可することは、復号をすることを 意味しません。%2F や (関係するシステムでの) %5C は、他の部分が復号された URL の中でもそのままの形式で 残されます。

参照

  • AcceptPathInfo

AllowOverride ディレクティブ

説明: | .htaccess で許可されるディレクティブの種類
構文: | AllowOverride All|None|directive-type [directive-type] ...
デフォルト: | AllowOverride All
コンテキスト: | ディレクトリ
ステータス: | Core
モジュール: | core

サーバが (AccessFileName によって指定された) .htaccess ファイルを見つけた時、そのファイルの中で 宣言されたどのディレクティブがより前に定義された設定ディレクティブを 上書きできるかを知る必要があります。

<Directory> セクションでのみ使用可能

AllowOverride は正規表現無しの<Directory> セクションでのみ有効で、<Location> や <DirectoryMatch> や <Files> セクションでは無効です。

このディレクティブを None に設定すると、.htaccess ファイルは完全に 無視されます。 この場合、サーバはファイルシステムの .htaccess ファイルを読むことを 試みさえしません。

このディレクティブが All に設定されている時には、 .htaccess という コンテキスト を持つ 全てのディレクティブが利用できます。

directive-type には、以下のディレクティブ群の キーワードのどれかを指定します。

AuthConfig
認証に関するディレクティブの使用を許可する (AuthDBMGroupFile, AuthDBMUserFile, AuthGroupFile, AuthName, AuthType, AuthUserFile, Require など。)。
FileInfo
ドキュメントタイプを制御するためのディレクティブの使用を許可する (DefaultType, ErrorDocument, ForceType, LanguagePriority, SetHandler, SetInputFilter, SetOutputFilter, mod_mime の Add* と Remove* ディレクティブなど。)。
Indexes
ディレクトリインデックスを制御するためのディレクティブの使用を許可する (AddDescription, AddIcon, AddIconByEncoding, AddIconByType, DefaultIcon, DirectoryIndex, FancyIndexing, HeaderName, IndexIgnore, IndexOptions, ReadmeName など。)。
Limit
ホストへのアクセス制御を行うためのディレクティブの使用を許可する (Allow, Deny, Order).
Options
特定のディレクトリにおける機能を指定するためのディレクティブの使用を許可する (Options と XBitHack)。

例:

AllowOverride AuthConfig Indexes

上の例では AuthConfig と Indexes のどちらにも 属さないディレクティブはすべて内部サーバエラーを引き起こします。

参照

  • AccessFileName
  • 設定ファイル
  • .htaccess ファイル

AuthName ディレクティブ

説明: | HTTP 認証の認可領域 (訳注: realm)
構文: | AuthName auth-domain
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Core
モジュール: | core

このディレクティブはディレクトリに対する認可領域 (訳注: realm) の名前を指定します。 認可領域は、利用者がどのユーザ名とパスワードを送信すればよいのかを クライアントに教えるために利用します。 AuthName は一つの引数をとり、 スペースが含まれる場合には、 引用符で括らなければなりません。 このディレクティブは AuthType ディレクティブや Require ディレクティブと、 AuthUserFile や AuthGroupFile などのディレクティブと 一緒に利用する必要があります。

例えば:

AuthName "Top Secret"

ここで AuthName に指定した文字列が、 大部分のブラウザのパスワードダイアログに表示されます。

参照

  • 認証、承認、アクセス制御

AuthType ディレクティブ

説明: | ユーザ認証の種類
構文: | AuthType Basic|Digest
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Core
モジュール: | core

このディレクティブは対象ディレクトリで利用するユーザー認証の種類を選びます。 ただ、現在のところは Basic と Digest しか 実装されていません。 このディレクティブは AuthNameディレクティブや Require ディレクティブと、 AuthUserFile や AuthGroupFile などのディレクティブと 一緒に利用する必要があります。

参照

  • 認証、承認、アクセス制御

CGIMapExtension ディレクティブ

説明: | CGI スクリプトのインタープリタの位置を調べるための手法
構文: | CGIMapExtension cgi-path .extension
デフォルト: | None
コンテキスト: | ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core
互換性: | NetWare のみ

このディレクティブは Apache が CGI スクリプトを実行するための インタープリタを探す方法を制御します。 例えば、CGIMapExtension sys:\foo.nlm .foo と設定すると .foo という拡張子のすべての CGI スクリプトは FOO インタープリタに 渡されます。

ContentDigest ディレクティブ

説明: | Content-MD5 HTTP 応答ヘッダの生成を有効にする
構文: | ContentDigest On|Off
デフォルト: | ContentDigest Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Options
ステータス: | Core
モジュール: | core

このディレクティブは、RFC1864 及び RFC2068 において定義されている Content-MD5 ヘッダーの生成を有効にします。

MD5 は、任意長のデータの「メッセージダイジェスト」(「指紋」 と表現されることもある) を計算するアルゴリズムで、 データの変更があった場合には非常に高い信頼度でメッセージダイジェストに変更が 反映されます。

Content-MD5 ヘッダは、エンドツーエンドで エンティティボディーに含まれるメッセージの完全性チェック (Message Integrity Check - MIC)を提供します。 このヘッダを調べることで、プロキシやクライアントは、 途中経路におけるエンティティボディの予期せぬ変更などを 検出することができます。ヘッダの例:

Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==

リクエスト毎にメッセージダイジェストを計算する (値はキャッシュされません) ことから、 サーバパフォーマンスが低下することについて注意してください。

Content-MD5は、core 機能により処理された ドキュメントを送るときのみ有効であり、 SSI ドキュメントや CGI スクリプトの出力、バイトレンジを指定した 応答の場合にはこのヘッダは付与されません。

DefaultType ディレクティブ

説明: | サーバがコンテントタイプを決定できないときに 送られる MIME コンテントタイプ
構文: | DefaultType MIME-type
デフォルト: | DefaultType text/plain
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core

サーバは、MIME のタイプマップからは決定できない ドキュメントの送信を要求されることがあります。

サーバは、ドキュメントのコンテントタイプをクライアントに通知する必要が ありますので、このようにタイプが未知の場合は DefaultType で指定されたタイプを利用します。 例:

DefaultType image/gif

これは .gif という拡張子がファイル名に含まれていない 多くの GIF 画像が含まれているディレクトリに適しているでしょう。

ForceType ディレクティブと 違って、このディレクティブはデフォルトの MIME タイプを提供するだけで あることに注意してください。ファイル名の拡張子を含め、 メディアタイプを決定できる他の MIME タイプの定義があれば このデフォルトは上書きされます。

<Directory> ディレクティブ

説明: | 指定のファイルシステムのディレクトリとサブディレクトリとのみに 適用されるディレクティブを囲む
構文: | <Directory directory-path> ... </Directory>
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

指定されたディレクトリとそのサブディレクトリにのみ ディレクティブを適用させるためには、 <Directory> と </Directory> を対として、ディレクティブ群を囲います。 その中には、ディレクトリコンテキストで許可された全てのディレクティブを 利用できます。 directive-path は、フルパスもしくは Unix のシェル形式の ワイルドカードを指定します。 ? は任意の 1 文字、* は任意の文字列にマッチします。 シェルにおける指定同様、文字の範囲を [] で指定できます。 ワイルドカードは `/' 文字にはマッチしませんので、 /home/user/public_html には <Directory /*/public_html> はマッチしませんが、 <Directory /home/*/public_html> はマッチします。 例:

<Directory /usr/local/httpd/htdocs>
Options Indexes FollowSymLinks
 </Directory>

directory-path 引数には注意してください: その引数は Apache がファイルをアクセスするために使うファイルシステムのパスに そのままマッチする必要があります。ある <Directory> に 適用されるディレクティブは、別のシンボリックリンクをたどったりして 同じディレクトリを違うパスでアクセスした場合には適用されません。

~ という文字を 付加することで拡張正規表現を利用することもできます。 例えば:

<Directory ~ "^/www/.*/[0-9]{3}">

といった指定の場合、/www/ 以下にある数字 3 文字のディレクトリにマッチします。

もし複数の (正規表現以外の) <Directory>セクションが ドキュメントを含むディレクトリ (やその上位ディレクトリのどれか) とマッチしたならば、 .htaccess ファイルのディレクティブも読み込みつつ、 短いパスから順に適用されます。 例えば、

<Directory />
AllowOverride None
 </Directory>

<Directory /home/>
AllowOverride FileInfo
 </Directory>

と設定し、ドキュメント /home/web/dir/doc.html への アクセスがあった場合には以下のように動作します:

  • AllowOverride None が適用される。 (.htaccess ファイルは無効になる)
  • AllowOverride FileInfo が適用される (/home ディレクトリに対して)。
  • /home/.htaccess, /home/web/.htaccess, /home/web/.htaccess の順にそれらのファイル中の FileInfo ディレクティブが適用される。

正規表現は、通常のセクションがすべて適用されるまで 考慮されません。 その後、全ての正規表現が設定ファイルに現れた順で試されます。 例えば、以下のような場合に

<Directory ~ abc$>
# ... directives here ...
 </Directory>

正規表現のセクションはすべての通常の <Directory> と .htaccess の適用が終わるまで考慮されません。 その後で、正規表現は /home/abc/public_html/abc にマッチし、 対応する <Directory> が適用されます。

Apache のデフォルトでは <Directory /> へのアクセスは Allow from All になっていることに注意してください。 これは、URL からマップされたどのファイルでも Apache は送るということです。 これは以下のようにして変更することが推奨されています。

<Directory />
Order Deny,Allow
Deny from All
 </Directory>

そしてアクセスを可能にしたいディレクトリに対して 個別に設定すればよいでしょう。 このあたりについては、セキュリティに関するコツを 参照してください。

ディレクトリセクションは httpd.conf ファイル書きます。 <Directory> ディレクティブは入れ子にすることができず、 <Limit> や <LimitExcept> セクションの中にも 記述できません。

参照

  • リクエストを受けた際にこれらの異なるセクションが 組み合わされる方法については <Directory>, <Location>, <Files> セクションの動作法

<DirectoryMatch> ディレクティブ

説明: | 正規表現にマッチするファイルシステムのディレクトリと サブディレクトリとのみに適用されるディレクティブを囲む
構文: | <DirectoryMatch regex> ... </DirectoryMatch>
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

<Directory> ディレクティブと同様に、<DirectoryMatch> と </DirectoryMatch> は指定されたディレクトリと そのサブディレクトリにのみ適用されるディレクティブ群を囲います。 しかし、このディレクティブは引数として正規表現をとります。例えば:

<DirectoryMatch "^/www/.*/[0-9]{3}">

は /www/ 以下にある数字 3 文字のディレクトリにマッチします。

参照

  • 通常の <Directory> と正規表現の指定が 適用される順番については <Directory>
  • リクエストを受けた際にこれらの異なるセクションが 組み合わされる方法については <Directory>, <Location>, <Files> セクションの動作法

DocumentRoot ディレクティブ

説明: | ウェブから見えるメインのドキュメントツリーになる ディレクトリ
構文: | DocumentRoot directory-path
デフォルト: | DocumentRoot /usr/local/apache/htdocs
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

このディレクティブは、httpd がファイルを提供するディレクトリを設定します。 Alias のようなディレクティブにマッチしない場合には、 ドキュメントの (訳注:ファイルシステム上の) パスを生成するために、 リクエストされた URL のパス部分をドキュメントルートに付与します。 例:

DocumentRoot /usr/web

この場合、 http://www.my.host.com/index.html へのアクセスがあれば /usr/web/index.html が返されます。

DocumentRoot は最後のスラッシュ無しで 指定する必要があります。

参照

  • URL をファイルシステムの位置に マップする

EnableMMAP ディレクティブ

説明: | 配送中にファイルを読み込むためにメモリマッピングを 使うかどうか
構文: | EnableMMAP On|Off
デフォルト: | EnableMMAP On
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core

このディレクティブは配送中にファイルの内容を読み込む必要があるときに httpd がメモリマッピングを使うかどうかを制御します。デフォルトでは、 例えば、mod_include を使って SSI ファイルを配送 するときのように、ファイルの途中のデータをアクセスする必要があるときには Apache は OS がサポートしていればファイルをメモリにマップします。

このメモリマップは性能の向上を持たらすことがあります。 しかし、環境によっては運用上の問題を防ぐためにメモリマッピングを 使用しないようにした方が良い場合もあります:

  • マルチプロセッサシステムの中にはメモリマッピングをすると httpd の 性能が落ちるものがあります。
  • NFS マウントされた DocumentRoot では、httpd がメモリマップしている間にファイルが削除されたり 短くなったりしたときに起こるセグメンテーションフォールトのために httpd がクラッシュする可能性があります。

これらの問題に当てはまるサーバの設定の場合は、以下のようにして ファイルの配送時のメモリマッピングを使用不可にしてください:

EnableMMAP Off

NFS マウントされたファイルには、問題のあるファイルにのみ明示的に この機能を使用不可にします:

<Directory "/path-to-nfs-files"> EnableMMAP Off </Directory>

EnableSendfile ディレクティブ

説明: | ファイルのクライアントへの配送時にカーネルの sendfile サポートを 使うかどうか
構文: | EnableSendfile On|Off
デフォルト: | EnableSendfile On
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core
互換性: | バージョン 2.0.44 以降で使用可能

このディレクティブはクライアンにファイルの内容を送るときに httpd がカーネルの sendfile サポートを使うかどうかを制御します。デフォルトでは、 例えば静的なファイルの配送のように、リクエストの処理にファイルの 途中のデータのアクセスを必要としないときには、Apache は OS が サポートしていればファイルを読み込むことなく sendfile を使って ファイルの内容を送ります。

sendfile は read と send を別々に行なうことと、バッファの割り当てを 回避します。しかし、プラットフォームやファイルシステムの中には 運用上の問題を避けるためにこの機能を使用不可にした方が良い場合があります:

  • プラットフォームの中にはビルドシステムが検知できなかった、壊れた sendfile のサポートが存在するものがあります。これは特に バイナリが別のマシンでビルドされ、壊れた sendfile のあるマシンに 移動したときに起こります。
  • Linux では、sendfile を用いると、 IPv6 使用時に存在する特定ネットワークカードの TCP-checksum オフロードのバグを踏んでしまいます。
  • ネットワークマウントされた DocumentRoot (例えば NFS や SMB) では、カーネルは自身のキャッシュを使ってネットワークからのファイルを 送ることができないことがあります。

これらの問題に当てはまるサーバの設定の場合は、以下のようにして この機能を使用不可にしてください:

EnableSendfile Off

NFS や SMB マウントされたファイルには、問題のあるファイルにのみ明示的に この機能を使用不可にします:

<Directory "/path-to-nfs-files"> EnableSendfile Off </Directory>

ErrorDocument ディレクティブ

説明: | エラーが発生したときにサーバがクライアントに送るもの
構文: | ErrorDocument error-code document
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core
互換性: | Apache 2.0 ではテキストをクウォートする構文が以前のバージョンから 変わっています。

問題やエラーが発生したときの動作として、 Apache には以下の四つのうち一つの動作を設定することができます。

  1. Apache 標準の簡単なエラーメッセージを表示
  2. 自分で指定したメッセージを表示
  3. 問題やエラーの処理をする為に、自サーバ内の URL-path へリダイレクト
  4. 問題やエラーの処理をする為に、外部の URL へリダイレクト

最初のものがデフォルトの動作で、2 番目から 4 番目は、 ErrorDocumentディレクティブにより、 HTTP のレスポンスコードと、メッセージか URL を指定することで設定します。 Apache が問題もしくはエラーに関する追加情報を提供することがあります。

URL の場合は、ローカルの URL の指定としてスラッシュで始まる (/) パスか、 クライアントが解釈できるフル URL を指定します。
もしくは、ブラウザに表示されるメッセージを指定できます。 例:

ErrorDocument 500 http://foo.example.com/cgi-bin/tester
ErrorDocument 404 /cgi-bin/bad_urls.pl
ErrorDocument 401 /subscription_info.html
ErrorDocument 403 "Sorry can't allow you access today"

加えて、特別な値 default を使って Apache に ハードコードされている簡単なメッセージを指定することができます。 通常は必要ではありませんが、default を使うと 既存の ErrorDocument ディレクティブの設定を 継承するところで、Apache のハードコードされた簡単なメッセージに 戻すことができます。

ErrorDocument 404 /cgi-bin/bad_urls.pl

<Directory /web/docs>
ErrorDocument 404 default
 </Directory>

リモート URL (例えば、頭に http と付与した方法) を ErrorDocument に指定するとき、 たとえ文書が同じサーバにあろうとも、ドキュメントがどこにあるかを通知するために、 Apache はリダイレクトをクライアントに送出するということに、注意してください。 これにはいろいろと関連して起こる問題があります。 中でも最も重要なのは、クライアントは元々のエラーステータスコードを受け取らず、 代わりにリダイレクトのステータスコードを受け取るということです。 これにより、ステータスコードを使って URL が有効であるかどうかを決定しようとする ウェブロボットやその他クライアントを、混乱させるかもしれません。 さらに、ErrorDocument 401 にリモートの URL を指定すると、 クライアントは 401 というステータスコードを受け取らないため、 パスワードをユーザーに入力要求しなければならないことがわかりません。 従って、ErrorDocument 401 というディレクティブを使う場合は、 必ずローカルな文書を参照しなければなりません。

Microsoft Internet Explorer (MSIE) はデフォルトではサーバが生成したエラーメッセージが 「小さすぎる」ときには無視をして自分自身の「やさしい」エラーメッセージで 置換します。サイズのしきい値はエラーの種類によって異なりますが、 一般的にはエラーの文書を 512 バイトよりも多きくすると、MSIE は サーバが生成したエラーを隠さずに表示します。詳しい情報は Microsoft Knowledge Base の記事 Q294807 にあります。

2.0 より前のバージョンでは、対になっていない二重引用符を 先頭に付けることによりメッセージであることを指定していました。

参照

  • カスタマイズ可能な エラー応答のドキュメンテーション

ErrorLog ディレクティブ

説明: | サーバがエラーをログ収集する場所
構文: | ErrorLog file-path|syslog[:facility]
デフォルト: | ErrorLog logs/error_log (Unix) ErrorLog logs/error.log (Windows and OS/2)
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

ErrorLog ディレクティブは、 サーバに生じたさまざまなエラーを 記録する為のファイルの名前を設定します。 file-path が絶対パスでないときは、ServerRoot からの相対パスとみなされます。

例

ErrorLog /var/log/httpd/error_log

file-path がパイプ (|) から始まる場合は、 エラーログを処理するために実行されるコマンドが 指定されていると解釈されます。

例

ErrorLog "|/usr/local/bin/httpd_errors"

ファイル名の変わりに syslog と指定することによって、 システムがサポートしていれば syslogd(8) を利用したロギングが有効になります。 デフォルトでは、local7 ファシリティとなりますが、 syslog:facility といった形で記述することにより、 通常 syslog(1) のドキュメントで説明されているファシリティの一つを使うように することができます。

例

ErrorLog syslog:user

セキュリティ: ログファイルを格納するディレクトリが、サーバを起動したユーザ以外の ユーザによって書き込める場合にセキュリティが破られる可能性があることに 関する詳細は セキュリティに関するコツ を 参照してください。

注

Unix 以外のプラットフォームでファイルのパスを入力するときは、 プラットフォームがバックスラッシュの使用を許していたとしても、 確実にスラッシュのみが使用されるように注意してください。一般的には、 設定ファイル全般でスラッシュのみを使う方が良いでしょう。

参照

  • LogLevel
  • Apache ログファイル

FileETag ディレクティブ

説明: | ETag HTTP 応答ヘッダを作成するために使用される ファイルの属性
構文: | FileETag component ...
デフォルト: | FileETag INode MTime Size
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core

FileETag ディレクティブは ドキュメントがファイルに基づいたものであるときに、 ETag (エンティティタグ) 応答ヘッダフィールドを作成するときに使用する ファイルの属性を設定します。 (ETag の値はネットワークの帯域を節約するための キャッシュの管理で使われます。) Apache 1.3.22 以前では、ETag の値は 常にファイルの inode, サイズ、最終修正時刻 (mtime) から作成 されていました。FileETag ディレクティブにより、これらのどれを使うかを 選ぶことができます。認識されるキーワードは:

INode
ファイルの inode 番号を計算に使います
MTime
ファイルの最終修正時刻を使います
Size
ファイルの中身のバイト数を使います
All
使用可能なすべてのフィールドを使います。 これは

FileETag INode MTime Size

と等価です。
None
ドキュメントがファイルに基づいたものでも、ETag フィールドを 応答に付加しません

INode, MTime, Size キーワードには + や - を前に付けて 指定することもできます。この場合は、より広い範囲から継承された デフォルトの設定に変更を加えるようになります。そのような接頭辞の 無いキーワードを指定すると、即座に継承した設定を無効にします。

あるディレクトリの設定に FileETag INode MTime Size があり、 サブディレクトリの設定に FileETag -INode があるときは、 そのサブディレクトリの設定は (設定が上書きされなければサブディレクトリの サブディレクトリにも継承されます) FileETag MTime Size と同じになります。

<Files> ディレクティブ

説明: | マッチするファイル名に適用されるディレクティブを囲む
構文: | <Files filename> ... </Files>
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core

<Files> ディレクティブは、 その中にあるディレクティブの適用範囲をファイル名で制限します。 <Directory> ディレクティブや <Location> ディレクティブと 同じような機能を持ちます。 これは、</Files> ディレクティブと対に なっていなければなりません。 このセクション中のディレクティブは、ベース名 (ファイル名の最後の部分) が指定されたファイル名にマッチするすべてのオブジェクトに適用されます。 <Files> セクションは <Directory> セクションと .htaccess が読み込まれた後、 <Location> セクションよりは先に 設定ファイルに現れた順に適用されます。 <Files> は、 <Directory> セクション内に ネストさせることができ、 ファイルシステムの一部にのみ限定して適用させることができます。

filename 引数は、ファイル名かワイルドカード文字列 で、ワイルドカードでは ? は一つの文字、* は任意の文字列にマッチします。 ~ という文字を付加することで拡張正規表現を使うこともできます。 例えば、

<Files ~ "\.(gif|jpe?g|png)$">

とすることにより、一般的なインターネットの画像フォーマットにマッチします。 ただし、 <FilesMatch> を使う方が 推奨されています。

ちなみに、<Directory> と <Location> セクションとは異なり、 <Files> は .htaccess ファイル内で利用することができます。 これにより、ユーザがファイル毎にアクセスの制御を行なうことができるように なっています。

参照

  • リクエストを受けた際にこれらの異なるセクションが 組み合わされる方法については <Directory>, <Location>, <Files> セクションの動作法

<FilesMatch> ディレクティブ

説明: | 正規表現にマッチするファイル名に適用される ディレクティブを囲む
構文: | <FilesMatch regex> ... </FilesMatch>
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core

<FilesMatch> ディレクティブは、 <Files> ディレクティブ同様にその中にあるディレクティブの適用範囲をファイル名で制限します。ただし、 このディレクティブには正規表現を指定します。 例えば:

<FilesMatch "\.(gif|jpe?g|png)$">

は一般的なインターネットの画像形式にマッチします。

参照

  • リクエストを受けた際にこれらの異なるセクションが 組み合わされる方法については <Directory>, <Location>, <Files> セクションの動作法

ForceType ディレクティブ

説明: | すべてのマッチするファイルが指定の MIME コンテントタイプで 送られるようにする
構文: | ForceType MIME-type|None
コンテキスト: | ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core
互換性: | Apache 2.0 で core に移動

.htaccess や <Directory> セクション、 <Location> セクション、 <Files> セクションに 書かれた場合、このディレクティブはそこにあるすべてのファイルが MIME-type で指定されたコンテントタイプとして扱われるようにします。たとえば、 GIF ファイルばかりのディレクトリがあって、すべてのファイルを .gif で終わらせたくはないときに、以下のものを使用します:

ForceType image/gif

DefaultType と違って このディレクティブはメディアタイプを決めることができるかもしれない ファイルの拡張子も含め、すべての MIME タイプの関連付けを 上書きすることに注意してください。

None という値を使うことで ForceType の 設定を無効にできます:

# force all files to be image/gif:
<Location /images>
ForceType image/gif
 </Location>

# but normal mime-type associations here:
<Location /images/mixed>
ForceType None
 </Location>

HostnameLookups ディレクティブ

説明: | クライアントの IP アドレスの DNS ルックアップを 有効にする
構文: | HostnameLookups On|Off|Double
デフォルト: | HostnameLookups Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Core
モジュール: | core

このディレクティブは、ホスト名をログ収集できるように DNS ルックアップを有効にします (さらに、CGI/SSI に REMOTE_HOST 変数として渡します)。 Doubleを指定した場合、2 重の逆引きを行ないます。 つまり、逆引きの後に、その結果に対して正引きを行ないます。正引きの 結果の IP アドレスの中にオリジナルのアドレスと一致するものがなければ なりません。("tcpwrappers" の用語では PARANOID と呼ばれています。)

mod_access でホスト名によるアクセス 制御を行なう場合には、 設定の如何によらず 2 重の逆引きが実行されます。 これは、セキュリティを保つために必要です。 HostnameLookups Double を設定しない限り、 他の部分はこの 2 重逆引きの結果を使うことはできません。 例えば、HostnameLookups On と設定してある状態で、 ホスト名によるアクセス制限を行なったオブジェクトへの リクエストを受けたとすると、2 重の逆引きが成功するか否かによらず、 REMOTE_HOST には通常の逆引き結果が渡されます。

ディレクティブのデフォルトは 本当に逆引きを必要としているわけではないサイトの ネットワークトラフィックを低減させるために、Off になっています。 ルックアップによる余計な遅延がなくなるため、 エンドユーザにとっても良いでしょう。 DNS のルックアップには、かなりの時間が必要となる場合が多く、 負荷の高いサイトではこのディレクティブは Off にすべきです。 なお、/support ディレクトリに含まれ、デフォルトでは インストールディレクトリの bin サブディレクトリに インストールされる logresolve ユーティリティにより、 Apache の動作とは別に、ログに残されている IP アドレスからホスト名を ルックアップすることが可能です。

IdentityCheck ディレクティブ

説明: | リモートユーザの RFC1413 によるアイデンティティのロギングを 有効にする
構文: | IdentityCheck On|Off
デフォルト: | IdentityCheck Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Core
モジュール: | core

このディレクティブは、クライアントマシン上で identd やそれに類似したデーモンが動作しているときに、 それぞれの接続に対して RFC 1413 に準処したリモートユーザの 名前のロギングを行なうようにします。 この情報は、アクセスログに収集されます。

ここで得られた情報は簡単なユーザ追跡に使う以外は、 まったく信頼するべきではありません。

すべてのリクエストに対してルックアップが行なわれますので、 深刻な遅延の問題を起こすかもしれないことに注意してください。 (訳注: 例えばクライアント側に) ファイアウォールがあると、 ルックアップが失敗し、各リクエストに 30 秒の遅延が加わることに なる可能性があります。 従って、一般的にはインターネットからアクセス可能なパブリックなサーバで 有益なものではありません。

<IfDefine> ディレクティブ

説明: | 起動時にテストが真であるときのみに処理されるディレクティブを 囲む
構文: | <IfDefine [!]parameter-name> ... </IfDefine>
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core

<IfDefine test>...</IfDefine> セクションは、 ディレクティブを条件付きで指定するために利用します。 <IfDefine> セクションに 含まれるディレクティブは、testが 定義されているときのみ処理されます。 もし test が定義されていなければ、 開始と終了の指定の間のディレクティブは無視されます。

<IfDefine> セクションディレクティブに 指定する test は、 次の二つの形式のうちの一つをとります:

  • parameter-name
  • !parameter-name

前者の場合には、parameter-name と名付けられたパラメータが 定義されていれば開始と終了の間のディレクティブが処理されます。 後者の場合は逆で、parameter-name が指定されていない 場合に処理されます。

parameter-name 引数は、サーバを起動する際に httpd のコマンドラインに -Dparameter- という形で指定すると定義されます。

<IfDefine> セクションは 入れ子にすることができ、複数のパラメータによるテストをするために使用できます。 例:

httpd -DReverseProxy ...

# httpd.conf
<IfDefine ReverseProxy>
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule proxy_module modules/libproxy.so
 </IfDefine>

<IfModule> ディレクティブ

説明: | モジュールの存在するかしないかに応じて処理される ディレクティブを囲む
構文: | <IfModule [!]module-name> ... </IfModule>
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core

<IfModule test>...</IfModule> セクションは、モジュールが存在するときに処理されるディレクティブを 指定するために利用します。 <IfModule> セクションに 含まれるディレクティブは、test で指定するモジュールが組み込まれているときのみ処理されます。 もし test が組み込まれていなければ、開始と終了の間のディレクティブ は無視されます。

<IfModule> セクションディレクティブに 指定する test は、 次の二つの形式のうちの一つをとります。

  • module name
  • !module name

前者の場合は、module name と名付けられたモジュールが Apache に組み込まれていれば (コンパイル済みのものと、LoadModule を利用して 動的に読み込んだものの両方)、 開始と終了の間のディレクティブが処理されます。 後者の場合は逆で、module name が組み込まれていない 場合に処理されます。

module name 引数は、 コンパイルをした時のモジュールのファイル名です。 例えば、 mod_rewrite.c です。 モジュールが複数のソースファイルから構成されている場合は、文字列 STANDARD20_MODULE_STUFF があるファイルの名前を 使ってください。

<IfModule> セクションは 入れ子にすることが可能であり、 複数のモジュールのテストを行なうために使用できます。

特定のモジュールの存在に関わらず動作する 設定ファイルの原本が必要なときにのみこのセクションを使用してください。 通常の動作では、ディレクティブを <IfModule> セクションの中に 入れる必要はありません。

Include ディレクティブ

説明: | サーバ設定ファイル中から他の設定ファイルを取り込む
構文: | Include file-path|directory-path
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Core
モジュール: | core
互換性: | ワイルドカードによるマッチは 2.0.41 以降で使用可能

このディレクティブにより、サーバの設定ファイルから 他の設定ファイルをインクルードすることができます。

複数のファイルをアルファベット順に一度に読み込むために、 シェル形式 (fnmatch) のワイルドカード文字を使うことができます。 さらに、Include にディレクトリを指定した場合は、 ディレクトリとそのサブディレクトリ内の全てのファイルを アルファベット順に読み込んで、設定ファイルとして処理します。 しかし、ディレクトリ全体を読み込むのはお勧めできません。 ふとしたことから httpd が読み込みに失敗するような 一時ファイルをディレクトリに残してしまうようなことがよくあるからです。

指定するファイルパスは絶対パスか、 ServerRoot ディレクトリからの 相対パスか、のどちらかです。

例:

Include /usr/local/apache2/conf/ssl.conf
Include /usr/local/apache2/conf/vhosts/*.conf

ServerRoot からの相対パスの場合は:

Include conf/ssl.conf
Include conf/vhosts/*.conf

apachectl configtest を実行すると、設定をチェックしている時に 読み込まれたファイルのリストが表示されます:

root@host# apachectl configtest
Processing config file: /usr/local/apache2/conf/ssl.conf
Processing config file: /usr/local/apache2/conf/vhosts/vhost1.conf
Processing config file: /usr/local/apache2/conf/vhosts/vhost2.conf
Syntax OK

参照

  • apachectl

KeepAlive ディレクティブ

説明: | HTTP の持続的な接続を有効にする
構文: | KeepAlive On|Off
デフォルト: | KeepAlive On
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

HTTP/1.0 の Keep-Alive 拡張と HTTP/1.1 の持続的接続の機能は、 複数のリクエストが同じ TCP の接続で送られる、長時間持続する HTTP セッションを提供します。たくさんの画像が 含まれる HTML ドキュメントでは場合によっては遅延時間が 50% 短縮される結果も でています。Keep-Alive 接続を有効にするには KeepAlive On と設定します。

HTTP/1.0 に対応したクライアントの際には、 クライアントより特に要求があった場合のみ Keep-Alive 接続となります。 さらに、HTTP/1.0 クライアントでは、コンテンツの容量が先に (訳注: 要求に対して応答を返す前に) わかる場合のみ Keep-Alive 接続を利用できます。 これは、CGI の出力や SSI のページ、 サーバが生成したディレクトリのリストのような動的コンテンツを HTTP/1.0 クライアントに送る場合には Keep-Alive 接続を使えないことを意味します。 HTTP/1.1 に対応したクライアントの際には、 特に指定されない限りはデフォルトとして持続的な接続が行なわれます。 クライアントが要求すれば、コンテンツの容量を判別できないものを 持続的な接続を通して送るために、チャンクエンコーディングが用いられます。

参照

  • MaxKeepAliveRequests

KeepAliveTimeout ディレクティブ

説明: | 持続的な接続で次のリクエストが来るまでサーバが待つ時間
構文: | KeepAliveTimeout seconds
デフォルト: | KeepAliveTimeout 15
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

接続を閉じる前に、Apache が次のリクエストを何秒待つかを指定します。 リクエストを受け付けた後は、Timeout ディレクティブによって 指定されたタイムアウト値が使われます。

KeepAliveTimeout を大きな値に設定すると、 負荷の高いサーバにおいてはパフォーマンスの問題を引き起こす場合があります。 タイムアウトが長ければ長いほど、より多くのサーバプロセスが 活発でないクライアントからの接続の終了を待ち続けることになります。

<Limit> ディレクティブ

説明: | 囲いの中にあるアクセス制御の適用を特定の HTTP メソッドのみに 制限する
構文: | <Limit method [method] ... > ... </Limit>
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core

アクセス制御は、通常全てのアクセスメソッドに対して 影響し、普通はこれが望ましい挙動です。 そうしたことから、大部分の場合にはアクセス制御に関わるディレクティブを <Limit> セクション内に 書くべきではありません。

<Limit> ディレクティブの 目的は、アクセス制御の範囲を 指定された HTTP メソッドに限定するためです。 それ以外のメソッドは、<Limit> で囲われたアクセス制御の 影響を受けません。 以下の例は、POST, PUT, DELETE のメソッドに対してのみアクセスの制御を行ない、 それ以外のメソッドについては制限しません:

<Limit POST PUT DELETE>
Require valid-user
 </Limit>

メソッド名には以下の中から一つ以上を列挙することができます: GET, POST, PUT, DELETE, CONNECT, OPTIONS, PATCH, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK. メソッド名は 大文字小文字を区別します。 GET を指定した場合には HEAD リクエストにも制限がかかります。TRACE メソッドに制限をかけることはできません。

アクセス制御が目的の場合は <Limit> セクションの代わりに <LimitExcept> セクションを使用した方が良いでしょう。 <LimitExcept> セクションでは不特定のメソッドに対しても防御できるからです。

<LimitExcept> ディレクティブ

説明: | 指定されたもの以外の HTTP メソッドにアクセス制御を 制限する
構文: | <LimitExcept method [method] ... > ... </LimitExcept>
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core

<LimitExcept> と </LimitExcept> は、引数に 含まれていない HTTP のアクセスメソッドに適用するためのアクセス制御 ディレクティブを括るために利用します。 つまり、<Limit> セクションの反対の動作をし、 標準のメソッドと標準外や未認識のメソッドの場合の両方を設定できます。 <Limit> のドキュメントも 併せて参照してください。

例:

<LimitExcept POST GET>
Require valid-user
 </LimitExcept>

LimitInternalRecursion ディレクティブ

説明: | 内部リダイレクトと入れ子になったサブリクエストの最大数を決定する
構文: | LimitInternalRecursion number [number]
デフォルト: | LimitInternalRecursion 10
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core
互換性: | Apache 2.0.47 以降で使用可能

内部リダイレクトは例えば Action ディレクティブを 使っているときに起こります。Action ディレクティブは 元々のリクエストを CGI スクリプトに内部リダイレクトを行ないます。 サブリクエストはいくつかの URI に対して、リクエストされたときに 何が起こるかを調べるための Apache の機構です。例えば、mod_dir は DirectoryIndex ディレクティブ がリストするファイルを調べるためにサブリクエストを使います。

LimitInternalRecursion は内部リダイレクトや サブリクエストが無限ループに陥ったときのサーバクラッシュを防ぎます。 普通、そのようなループは設定に失敗したときに発生します。

このディレクティブは、リクエスト毎に評価される、二つの違う限界値を 設定します。最初の number は、起こり得る 内部リクエストの最大値を設定します。二つめの number は サブリクエストが入れ子にできる深さを設定します。number を 一つだけ指定したときは、両方の限界値にその値が設定されます。

例

LimitInternalRecursion 5

LimitRequestBody ディレクティブ

説明: | クライアントから送られる HTTP リクエストのボディの 総量を制限する
構文: | LimitRequestBody bytes
デフォルト: | LimitRequestBody 0
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core

このディレクティブは、リクエストボディに許されるバイト数、bytes を 0 (無制限を意味します) から 2147483647 (2GB) までの数値で指定します。

LimitRequestBody ディレクティブは、 ディレクティブが書かれたコンテキスト (サーバ全体、ディレクトリ、ファイル、ロケーション) 内で 許容する HTTP リクエストメッセージボディのサイズに制限をかけることができます。 クライアントのリクエストがその制限値を越えていれば、 サーバはリクエストを処理せずにエラーを返します。 普通のリクエストメッセージボディのサイズは、リソースの種類や 許可されているメソッドによって大きく変わります。 CGI スクリプトは、よく情報を受信するために メッセージボディを使います。 PUT メソッドの実装は、このディレクティブの値として 少なくともあるリソースに対してサーバが受け付けようとする 表現の大きさほどの値を必要とします。

このディレクティブは、 管理者にクライアントからの異常なリクエストを制御できるようにし、 何らかの形のサービス拒否攻撃 (訳注:DoS) を避けるのに有効です。

ある場所へのファイルアップロードを許可する場合に、 アップロードできるファイルのサイズを 100K に制限したければ、 以下のように指定します:

LimitRequestBody 102400

LimitRequestFields ディレクティブ

説明: | クライアントからの HTTP リクエストのヘッダフィールドの数を 制限する
構文: | LimitRequestFields number
デフォルト: | LimitRequestFields 100
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core

number には、0 (無制限を意味します) から 32767 までの整数を指定します。 デフォルト値は、定数 DEFAULT_LIMIT_REQUEST_FIELDS によりコンパイル時に定義されます (配布時には 100 と指定されています)。

LimitRequestBody ディレクティブは、 サーバ管理者が HTTP リクエスト中において許可するリクエストヘッダフィールド数を 指定します。 サーバはこの値には通常のクライアントからのリクエストに含まれるであろう フィールドの数より大きな値が必要とします。 クライアントにより使われた要求ヘッダーフィールドの数が 20 を超えることはほとんどありませんが、 これは種々のクライアントの実装よって変わり、 詳細なコンテントネゴシエーションをするためのブラウザの設定までにも 影響されることがあります。 オプションの HTTP 拡張はリクエストヘッダフィールドを使って現される場合が 多くあります。

このディレクティブは、 管理者にクライアントからの異常なリクエストを制御できるようにし、 何らかの形のサービス拒否攻撃 (訳注:DoS) を避けるのに有効です。 リクエストのフィールドが多過ぎることを意味するエラー応答が 普通のクライアントに返されるような時はこの値を増やしてください。

例:

LimitRequestFields 50

LimitRequestFieldSize ディレクティブ

説明: | クライアントからの HTTP リクエストのヘッダの サイズを制限する
構文: | LimitRequestFieldsize bytes
デフォルト: | LimitRequestFieldsize 8190
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core

このディレクティブは、HTTP リクエストヘッダ内に含めることのできる バイト数、bytes を 0 からコンパイル時に定義される定数 DEFAULT_LIMIT_REQUEST_FIELDSIZE (配布時には 8192 と指定) で指定された値までの数字で指定します。

LimitRequestFieldSize ディレクティブは、 サーバのコンパイル時に指定したインプットバッファ容量以下に HTTP リクエストヘッダの許容されるサイズを制限することができます。 サーバは、このディレクティブの値として、 通常のクライアントリクエストから送られた個々のヘッダフィールドに 十分足る大きさを必要とします。 普通のリクエストヘッダのサイズは、個々のクライアントにより大きく変わり、 詳細なコンテントネゴシエーションをするためのブラウザの設定までにも 影響されることがあります。

このディレクティブは、 管理者にクライアントからの異常なリクエストを制御できるようにし、 何らかの形のサービス拒否攻撃 (訳注:DoS) を避けるのに有効です。

例:

LimitRequestFieldSize 4094

通常はデフォルトから変更する必要はありません。

LimitRequestLine ディレクティブ

説明: | クライアントからの HTTP リクエスト行のサイズを制限する
構文: | LimitRequestLine bytes
デフォルト: | LimitRequestLine 8190
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core

このディレクティブは、HTTP リクエスト行内で許容されるバイト数 bytes を 0 からコンパイル時の定数 DEFAULT_LIMIT_REQUEST_LINE (配布時には 8190 と指定) で指定された値までの数字で指定します。

LimitRequestLine ディレクティブにより、サーバ管理者は サーバのコンパイル時に指定したインプットバッファ容量以下に クライアントからの HTTP リクエスト行のサイズの制限を行なうことができます。 リクエスト行は、HTTPメソッド、URI、プロトコルバージョンから成っており、 LimitRequestLine はサーバへのリクエストに対して 許容するリクエスト URI の長さを制限することになります。 サーバは、GET リクエストのクエリ部分も含めて、リソースの名前が入るに足る 大きさを必要とします。

このディレクティブは、 管理者にクライアントからの異常なリクエストを制御できるようにし、 何らかの形のサービス拒否攻撃 (訳注:DoS) を避けるのに有効です。

例:

LimitRequestLine 4094

通常はデフォルトから変更する必要はありません。

LimitXMLRequestBody ディレクティブ

説明: | XML 形式のリクエストのボディのサイズを制限する
構文: | LimitXMLRequestBody bytes
デフォルト: | LimitXMLRequestBody 1000000
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core

XML 形式のリクエストのボディの最大値を (バイト単位で) 制限します。 値に 0 を指定するとチェックを無効にします。

例:

LimitXMLRequestBody 0

<Location> ディレクティブ

説明: | 囲んだディレクティブをマッチする URL のみに適用
構文: | <Location URL-path|URL> ... </Location>
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

<Location> ディレクティブは、 URL により中に書かれたディレクティブの適用範囲を制限します。 <Directory> ディレクティブと似ていて、 </Location> ディレクティブで終了する サブセクションを開始します。 <Location> セクションは、 <Directory> セクションと .htaccess の読み込みの後、 <Files> セクションを 適用した後に、設定ファイルに現れた順に処理されます。

<Location> セクションは 完全にファイルシステムと関連せずに動作します。このことから導かれる 結果にはいつくか注意する点があります。最も重要なものは、 ファイルシステムの位置へのアクセス制御に <Location> ディレクティブを使うべきではない ということです。複数の URL がファイルシステムの同じ位置にマップされる 可能がありますので、そのようなアクセス制御は回避されてしまう可能性が あります。

いつ <Location> を使うか

<Location> ディレクティブは ファイルシステム外のコンテンツにディレクティブを適用するときに 使用してください。ファイルシステムに存在するコンテンツに対しては、 <Directory> と <Files> を使ってください。 例外は、<Location /> で、これはサーバ全体に対して 設定を適用する簡単な方法です。

全ての (プロキシ以外の) リクエストに対し、 URL は /path/ という、 接頭辞 http://servername を含まない形でマッチします。 プロキシリクエストの場合には、scheme://servername/path という接頭辞を含む形でマッチし、接頭辞を含めて指定する必要があります。

URL にはワイルドカードを利用することができます。 ? は任意の一文字、* は任意の文字列にマッチします。

~ という文字を追加することで、拡張正規表現を 利用することもできます。 例えば:

<Location ~ "/(extra|special)/data">

は URL に /extra/data か /special/data という文字列が 含まれている場合にマッチします。 <LocationMatch> ディレクティブは <Location> の正規表現 版とまったく同じ動作をします。

<Location> 機能は、SetHandler ディレクティブと 組合わせて利用すると特に便利です。 例えば、foo.com のブラウザからのみステータスの参照を有効にしたければ、 次のようにすれば良いでしょう。

<Location /status>
SetHandler server-status
Order Deny,Allow
Deny from all
Allow from .foo.com
 </Location>

/ (スラッシュ) に関する注

スラッシュ文字は、URL 内に現れる場所に応じて変化する 特別な意味を持っています。 ファイルシステムにおいて利用する場合には複数のスラッシュでも一つの スラッシュとして扱われることが多いですが、 (すなわち、/home///foo は /home/foo と同じいったように) URL においては必ずしもそうなるわけではありません。 <LocationMatch> ディレクティブや正規表現を利用した <Location> ディレクティブで、 複数のスラッシュにマッチさせたいときには、、明示的に記述する 必要があります。

例えば、<LocationMatch ^/abc> は、 /abc というリクエスト URL にマッチしますが、 //abc というリクエスト URL にはマッチしません。 (正規表現でない) <Location> ディレクティブは、 proxy リクエストに対して利用する際には同様の振る舞いをしますが、 (正規表現でない) <Location> を proxy でないリクエストに対して利用する際には、 一つのスラッシュで複数のスラッシュにマッチします。 例えば、<Location /abc/def> と指定し、 /abc//def というリクエストがあれば、 マッチすることになります。

参照

  • リクエストを受けた際にこれらの異なるセクションが 組み合わされる方法については <Directory>, <Location>, <Files> セクションの動作法

<LocationMatch> ディレクティブ

説明: | 囲んだディレクティブを正規表現にマッチする URL のみに 適用
構文: | <LocationMatch regex> ... </LocationMatch>
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

<LocationMatch> ディレクティブは、 <Location> と同じ様に URL により中に書かれたディレクティブの適用範囲を制限します。 但し、引数は普通の文字列ではなく、正規表現となります。例えば、

<LocationMatch "/(extra|special)/data">

は URL に /extra/data か /special/data という文字列が含まれている場合にマッチします。

参照

  • リクエストを受けた際にこれらの異なるセクションが 組み合わされる方法については <Directory>, <Location>, <Files> セクションの動作法

LogLevel ディレクティブ

説明: | ErrorLog の冗長性を制御する
構文: | LogLevel level
デフォルト: | LogLevel warn
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

LogLevel は、エラーログ (ErrorLog ディレクティブを 見てください) へ記録するメッセージの冗長性を調整します。 以下の level を指定でき、順に重要度が下がっていきます。

レベル | 説明 | 例
emerg | 緊急 - システムが利用できない | Child cannot open lock file. Exiting (子プロセスがロックファイルを開けないため終了した)
alert | 直ちに対処が必要 | getpwuid: couldn't determine user name from uid (getpwuid: UID からユーザ名を特定できなかった)
crit | 致命的な状態 | socket: Failed to get a socket, exiting child (socket: ソケットが得られないため、子プロセスを終了させた)
error | エラー | Premature end of script headers (スクリプトのヘッダが足りないままで終わった)
warn | 警告 | child process 1234 did not exit, sending another SIGHUP (子プロセス 1234 が終了しなかった。もう一度 SIGHUP を送る)
notice | 普通だが、重要な情報 | httpd: caught SIGBUS, attempting to dump core in ... (httpd: SIGBUS シグナルを受け、... へコアダンプをした)
info | 追加情報 | "Server seems busy, (you may need to increase StartServers, or Min/MaxSpareServers)..." (「サーバは負荷が高い、 (StartServers や Min/MaxSpareServers の値を増やす必要があるかも)」)
debug | デバッグメッセージ | "Opening config file ..." (設定ファイルを開いている...)

特定のレベルが指定された場合、それより高いレベルの全てのメッセージが 報告されます。 例えば、LogLevel info に指定すると、 notice と warn も報告されます。

なお crit 以上のレベルを指定することが推奨されます。

例:

LogLevel notice

注

ファイルにログを出力する場合、notice レベルのメッセージは抑制されず、すべてログに出力されます。 しかし syslog を使用している場合は、 これは当てはまりません。

MaxKeepAliveRequests ディレクティブ

説明: | 持続的な接続上で許可されるリクエストの数
構文: | MaxKeepAliveRequests number
デフォルト: | MaxKeepAliveRequests 100
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

MaxKeepAliveRequests ディレクティブは、 KeepAlive が有効な場合に、 一回の接続で受け付け可能なリクエストの数を制限します。 0 に設定していれば、受け付けるリクエストは無制限になります。 この設定は、サーバ性能を向上させるために、大きな数値を指定すること勧めます。

例:

MaxKeepAliveRequests 500

NameVirtualHost ディレクティブ

説明: | 名前ベースのバーチャルホストのための IP アドレスを指定
構文: | NameVirtualHost addr[:port]
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core

NameVirtualHost ディレクティブは、 名前ベースのバーチャルホストの設定を行ないたい場合に 必要となるものです。

addr にはホスト名を指定できますが、 常に IP アドレスを指定するのが推奨されます。 例えば、

NameVirtualHost 111.22.33.44

NameVirtualHost ディレクティブは、 名前ベースのバーチャルホストを 利用してリクエストを受け付ける IP アドレスを指定します。 これは、普通は名前ベースのバーチャルホストアドレスです。 ただし、ファイアーウォールや他のプロキシがリクエストを受け付け、 違う IP アドレスのサーバにフォワードするという場合は、 リクエストを提供したいマシン上の物理インターフェースの IP アドレスを指定する必要があります。 複数のアドレスで複数の名前ベースのバーチャルホストを指定する場合は 各アドレスに対してディレクティブを書いてください。

中

「主サーバ」や、どの _default_ サーバも、 NameVirtualHost で指定した IP アドレスへのリクエスト を処理することはありません (なぜか NameVirtualHost を 指定したけどそのアドレスに VirtualHost を定義しなかった場合を除く)。

名前ベースのバーチャルホストにポート番号を指定することも可能です。 例えば

NameVirtualHost 111.22.33.44:8080

IPV6 のアドレスは次の例のように角括弧で囲む必要があります:

NameVirtualHost [fe80::a00:20ff:fea7:ccea]:8080

すべてのインタフェースへのリクエストを受け取るようにするためには、 引数として * を使います。

NameVirtualHost *

<VirtualHost> ディレクティブの引数

<VirtualHost> ディレクティブの引数は NameVirtualHost ディレクティブの引数に正確に 合っている必要があることに注意してください。

NameVirtualHost 1.2.3.4
<VirtualHost 1.2.3.4>
# ...
</VirtualHost>

参照

  • バーチャルホスト説明書

Options ディレクティブ

説明: | ディレクトリに対して使用可能な機能を設定する
構文: | Options [+|-]option [[+|-]option] ...
デフォルト: | Options All
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Options
ステータス: | Core
モジュール: | core

Options ディレクティブは、特定のディレクトリに対して どの機能が使用可能かを制御します。

option を Noneに指定すると、 特別な機能は全て無効になります。 また、以下の示す 1 個以上のものを指定できます。

All
MultiViews を除いた全ての機能が有効となります。 これがデフォルトです。
ExecCGI
mod_cgi による CGI スクリプトの実行を許可します。
FollowSymLinks
サーバが、このディレクトリ内でシンボリックリンクをたどれるようにします。

サーバがシンボリックリンクをたどる場合でも、 <Directory> セクションに マッチさせるための パス名は変更されません。

<Location> 内に このオプションを指定しても無視されることに 注意してください。

Includes
mod_include が提供する SSI を有効にします。
IncludesNOEXEC
SSI は有効になりますが、#exec コマンド と #exec CGI は無効になります。 ただし、#include virtual により、ScriptAlias されたディレクトリで CGI を実行することは可能です。
Indexes
もし、URL がディレクトリにマップするリクエストであって、 且つ DirectoryIndex で指定したファイル (例えば、index.html) が ディレクトリ内に無ければ、mod_autoindex が ディレクトリ内の一覧を整形して返します。
MultiViews
mod_negotiation による コンテントネゴシエーション された "MultiViews" を許可します。
SymLinksIfOwnerMatch
シンボリック先のファイルまたはディレクトリが、 シンボリックリンクの所有ユーザ ID と同じ場合にのみシンボリックリンクを たどれるようにします。

注

<Location> 内にこのオプションを 指定しても無視されます。

通常、ディレクトリに対して複数の Options が 適用可能な場合、 最も近いもの一つのみが適用され、他のものは無視されます。 複数の指定がマージされるわけではありません。(セクションのマージ方法を参照してください。) しかし、すべての Options ディレクティブが + や - 付きで 指定された場合はオプションの値はマージされます。 + を頭につければ現在の設定に加えられ、 - を付ければ現在の設定から削除されます。

例えば、+ や - を利用しない場合は:

<Directory /web/docs>
Options Indexes FollowSymLinks
 </Directory>

<Directory /web/docs/spec>
Options Includes
 </Directory>

/web/docs/spec というディレクトリには、 Includes だけが適用されます。 しかし、2 番目の Options で + や - を利用してみると:

<Directory /web/docs>
Options Indexes FollowSymLinks
 </Directory>

<Directory /web/docs/spec>
Options +Includes -Indexes
 </Directory>

/web/docs/spec というディレクトリには、 FollowSymLinks と Includes が適用されます。

注

-IncludesNOEXEC もしくは -Includes を指定すると、 前の設定がどのようになっていようとも SSI は無効となります。

どのような設定もされていなければ、デフォルトでは All に なります。

Require ディレクティブ

説明: | どの認証済みユーザがリソースをアクセスできるかを選択する
構文: | Require entity-name [entity-name] ...
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Core
モジュール: | core

このディレクティブは、どの認証済みのユーザがディレクトリに アクセスすることができるかを指定します。 以下のような構文になります。

Require user userid [userid] ...
指定されたユーザのみ、ディレクトリへのアクセスを許可します。
Require group group-name [group-name] ...
指定されたグループに属するユーザのみ、ディレクトリへのアクセスを許可します。
Require valid-user
全ての認証されたユーザに、ディレクトリへのアクセスを許可します。

Require は、正しく動作するためには AuthName 及び AuthType ディレクティブや、 (ユーザとグループを指定するために) AuthUserFile 及び AuthGroupFile といったディレクティブと共に 指定する必要があります。 例えば:

AuthType Basic
AuthName "Restricted Directory"
AuthUserFile /web/users
AuthGroupFile /web/groups
Require group admin

このようにして適用されたアクセス制御は、全てのメソッドに 対して行なわれます。 通常は、これが望ましい動作です。 もし、特定のメソッドに対してのみアクセスの制御を適用し、 他のメソッドは制限しない場合には、<Limit> セクション内に Require を 指定してください。

参照

  • Satisfy
  • mod_access

RLimitCPU ディレクティブ

説明: | Apache の子プロセスから起動されたプロセスの CPU 消費量を 制限する
構文: | RLimitCPU seconds|max [seconds|max]
デフォルト: | 未設定。オペレーティングシステムのデフォルトを使用
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core

一つか二つのパラメータをとります。 最初のパラメータは全プロセスに対するリソースのソフトリミットを設定し、 2 番目のパラメータは最大のリソースリミットを設定します。 パラメータには数字か、オペレーティングシステムの最大となる max のどちらかを指定することができます。 最大のリソースリミットを上げるためには、サーバを root で実行するか起動されなければいけません。

ちなみに、この設定は Apache の子プロセス自体ではなく、 リクエストを受け付けた Apache の子プロセスから fork されたプロセスに 適用されます。 これには CGI や SSI から実行されたコマンドが含まれますが、Apache の 親プロセスから fork されたログのパイププロセスなどには適用されません。

CPU リソースのリミットはプロセスあたりの秒数で表わされます。

参照

  • RLimitMEM
  • RLimitNPROC

RLimitMEM ディレクティブ

説明: | Apache の子プロセスから起動されたプロセスのメモリ消費量を 制限する
構文: | RLimitMEM bytes|max [bytes|max]
デフォルト: | 未設定。オペレーティングシステムのデフォルトを使用
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core

一つか二つのパラメータををとります。 最初のパラメータは全プロセスに対するリソースのソフトリミットを設定し、 2 番目のパラメータは最大のリソースリミットを設定します。 パラメータには数字か、オペレーティングシステムの最大となる max のどちらかを指定することができます。 最大のリソースリミットを上げるためには、サーバを root で実行するか起動されなければいけません。

この設定は Apache の子プロセス自体ではなく、 リクエストを受け付けた Apache の子プロセスから fork されたプロセスに 適用されます。 これには CGI や SSI から実行されたコマンドが含まれますが、Apache の 親プロセスから fork されたログのパイププロセスなどには適用されません。

メモリリソースのリミットはプロセスあたりのバイト数で表わされます。

参照

  • RLimitCPU
  • RLimitNPROC

RLimitNPROC ディレクティブ

説明: | Apache の子プロセスから起動されたプロセスが起動するプロセスの 数を制限する
構文: | RLimitNPROC number|max [number|max]
デフォルト: | 未設定。オペレーティングシステムのデフォルトを使用
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core

一つか二つのパラメータをとります。 最初のパラメータは全プロセスに対するリソースのソフトリミットを設定し、 2 番目のパラメータは最大のリソースリミットを設定します。 パラメータには数字か、オペレーティングシステムの最大となる max のどちらかを指定することができます。 最大のリソースリミットを上げるためには、サーバを root で実行するか起動されなければいけません。

この設定は Apache の子プロセス自体ではなく、 リクエストを受け付けた Apache の子プロセスから fork されたプロセスに 適用されます。 これには CGI や SSI から実行されたコマンドが含まれますが、Apache の 親プロセスから fork されたログのパイププロセスなどには適用されません。

プロセスの制限は、ユーザあたりのプロセス数で制御されます。

注

CGI プロセスがウェブサーバのユーザ ID 以外で実行されるので 無ければ、 このディレクティブは、サーバ自身が生成できるプロセスの数を制限することになります。 そのような状況になっているかどうかは、error_log 中の cannot fork というメッセージにより 確認することができます。

参照

  • RLimitMEM
  • RLimitCPU

Satisfy ディレクティブ

説明: | ホストレベルのアクセス制御とユーザ認証との相互作用を指定
構文: | Satisfy Any|All
デフォルト: | Satisfy All
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Core
モジュール: | core
互換性: | バージョン 2.0.51 以降では <Limit> ディレクティブと <LimitExcept> ディレクティブの影響を受ける

Allow と Require の両方が使われているときの アクセスポリシーを設定します。パラメータは All か Any です。このディレクティブはある場所へのアクセスがユーザ名/パスワード とクライアントのホストのアドレスで制限されているときにのみ 役立ちます。デフォルトの動作 (All) はクライアントがアドレスによる アクセス制限を満たし、かつ正しいユーザ名とパスワードを入力することを 要求します。Any では、クライアントはホストの制限を満たすか、 正しいユーザ名とパスワードの入力をするかをすればアクセスを許可されます。 これは、ある場所をパスワードで保護するけれど、特定のアドレスからの クライアントにはパスワードの入力を要求せずにアクセスを許可する、 というようなときに使用できます。

例えば、同じネットワーク上にいる人にはウェブサイトのある部分について 無制限のアクセスを許したいけれど、外のネットワークの人には パスワードを提供させるようにするためには、次のような設定をすることが できます:

Require valid-user
Allow from 192.168.1
Satisfy Any

バージョン 2.0.51 からは <Limit> セクションと <LimitExcept> セクションを使用することで Satisfy ディレクティブが 適用されるメソッドを制限することが できるようになりました。

参照

  • Allow
  • Require

ScriptInterpreterSource ディレクティブ

説明: | CGI スクリプトのインタープリタの位置を調べるための手法
構文: | ScriptInterpreterSource Registry|Registry-Strict|Script
デフォルト: | ScriptInterpreterSource Script
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core
互換性: | Win32 のみ。 オプション Registry-Strict は Apache 2.0 以降で使用可能

このディレクティブは、Apache で CGI スクリプトを 実行する場合に利用するインタープリタを、 どのように探し出すかについて制御するために使用します。 デフォルトの設定は Script です。これはスクリプトの shebang 行 (最初の行で #! から始まるもの) に指されているインタープリタを使用します。Win32 ではその行は 以下の様になります。

#!C:/Perl/bin/perl.exe

もしくは、perl が PATH にある場合は単に:

#!perl

ScriptInterpreterSource Registry を指定すると、 スクリプトファイルの拡張子 (例えば、.pl) を キーとして、Windows のレジストリツリー HKEY_CLASSES_ROOT を検索するようになります。レジストリのサブキー Shell\ExecCGI\Command か、それが存在しない場合は Shell\Open\Command がスクリプトファイルを開くために 使われます。レジストリキーが見つからないときは、Apache は Script オプションが指定されたときの動作に戻ります。

セキュリティ

ScriptInterpreterSource Registry を ScriptAlias されたディレクトリで使うときは 注意してください。Apache はそのディレクトリ中のすべてのファイルを 実行しようとします。Registry という設定は通常は実行されない ファイルに対して望ましくないプログラムの実行が発生する可能性があります。 例えば、ほとんどの Windows システムで、 .htm ファイルのデフォルトの「開く」コマンドは Microsoft Internet Explorer を実行しますので、スクリプトに指定された ディレクトリにある .htm ファイルへのリクエストはサーバの バックグラウンドでブラウザを実行することになります。これは、一分内くらいで システムをクラッシュさるための良い方法です。

Apache 2.0 から導入されたオプション Registry-Strict は Registry と同じことを行ないますが、サブキー Shell\ExecCGI\Command のみを使います。 ExecCGI キーは普通に使われるキーではありません。Windows レジストリに手動で設定する必要がありますので、システムでの偶発的なプログラムの 実行を防ぐことができます。

ServerAdmin ディレクティブ

説明: | サーバがクライアントに送るエラーメッセージに含める電子メールの アドレス
構文: | ServerAdmin email-address
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

ServerAdmin は、クライアントに返すさまざまな エラーメッセージ中に記述する、 電子メールアドレスを設定します。

その際、これのために専用のアドレスを設定するのが良いでしょう。 例えば、

ServerAdmin www-admin@foo.example.com

といったようにします。ユーザはいつもサーバに関する話であるということを 明記してくるわけではありませんので。

ServerAlias ディレクティブ

説明: | リクエストを名前ベースのバーチャルホストにマッチさせているときに 使用されるホストの別名
構文: | ServerAlias hostname [hostname] ...
コンテキスト: | バーチャルホスト
ステータス: | Core
モジュール: | core

ServerAlias ディレクティブは、ネームベースのバーチャルホストにおいて 使用するホストの別名を指定します。

<VirtualHost *>
ServerName server.domain.com
ServerAlias server server2.domain.com server2
# ...
</VirtualHost>

参照

  • Apache バーチャルホスト説明書

ServerName ディレクティブ

説明: | サーバが自分自身を示すときに使うホスト名とポート
構文: | ServerName fully-qualified-domain-name[:port]
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core
互換性: | このディレクティブはバージョン 2.0 ではバージョン 1.3 の Port ディレクティブの機能も含みます。

ServerName ディレクティブは、 サーバが自分自身を示すホスト名とポートを設定します。 これは、リダイレクトする URL を生成する際に利用されます。 例えば、ウェブサーバを動かしているマシンは simple.example.com で、DNS のエイリアス www.example.com もあるときに、 ウェブサーバが後者として認識されて欲しいときは、以下のようにディレクティブを 使います。

ServerName www.example.com:80

ServerName が指定されていないときは、 サーバは IP アドレスから逆引きを行なうことでホスト名を知ろうとします。 ServerName にポートが指定されていないときは、 サーバはリクエストが来ている ポートを使います。最高の信頼性と確実性をもたらすためには、 ServerName を使ってホスト名とポートを明示的に 指定してください。

名前ベースのバーチャルホスト を利用している場合、<VirtualHost> セクション内の ServerName はこのバーチャルホストにマッチするために 何がリクエストの Host: ヘッダに現れる必要があるのかを指定します。

自己参照 URL (例えば mod_dir モジュールによるものなど) が指定されたポートを使うか、クライアントのリクエストのポート番号を使うかを 決定する設定は UseCanonicalName ディレクティブを参照してください。

参照

  • DNS と Apache に関する話
  • Apache バーチャルホスト説明書
  • UseCanonicalName
  • NameVirtualHost
  • ServerAlias

ServerPath ディレクティブ

説明: | 非互換のブラウザが名前ベースのバーチャルホストにアクセスしたときの ための互換用 URL パス名
構文: | ServerPath URL-path
コンテキスト: | バーチャルホスト
ステータス: | Core
モジュール: | core

ServerPath ディレクティブは、ネームベースのバーチャルホストにおいて利用する 互換用 URL パス名を設定します。

参照

  • Apache バーチャルホスト説明書

ServerRoot ディレクティブ

説明: | インストールされたサーバのベースディレクトリ
構文: | ServerRoot directory-path
デフォルト: | ServerRoot /usr/local/apache
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core

ServerRoot ディレクティブは、 サーバが存在するディレクトリを設定します。 通常、conf/ や logs/ といったサブディレクトリが 存在します。 また、他の設定ファイルにおける相対パスは、このディレクトリからとなります。

例

ServerRoot /home/httpd

参照

  • httpd の -d オプション
  • ServerRoot の権限を適切に設定する方法はセキュリティのこつ

ServerSignature ディレクティブ

説明: | サーバが生成するドキュメントのフッタを設定
構文: | ServerSignature On|Off|EMail
デフォルト: | ServerSignature Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core

ServerSignature ディレクティブは、 サーバが生成するドキュメント (エラーメッセージ、mod_proxy における FTP のディレクトリリスト、 mod_info の出力、等々) の最下行に付与するフッタの設定を行ないます。 そのようなフッタ行を有効にしたい理由には、 プロキシが複数連なっている場合に、ユーザはどのサーバが返した エラーメッセージかを知る手段がほとんど無いというものがあります。

デフォルトである Off に設定をすると、フッタ行が抑制されます (そして、Apache-1.2 以前と互換の動作をします)。 On に設定した場合は、単にドキュメントの中に、サーバのバージョン、 稼動中のバーチャルホストの ServerName の書かれた行を追加し、 EMail にした場合はさらに参照されたドキュメントに対する ServerAdmin を指す "mailto:" が追加されます。

バージョン 2.0.44 以降ではこのディレクティブは ServerSignature ディレクティブにより表示される情報も制御します。

参照

  • ServerTokens

ServerTokens ディレクティブ

説明: | Server HTTP 応答ヘッダを設定する
構文: | ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full
デフォルト: | ServerTokens Full
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core

このディレクティブは、クライアントに送り返す Server 応答ヘッダ内に、サーバの一般的な OS 種別や、 コンパイルされて組み込まれているモジュールの情報を 含めるかどうかを指定します。

ServerTokens Prod[uctOnly]
サーバは (例えば): Server: Apache といったように送ります。
ServerTokens Major
Server sends (e.g.): Server: Apache/2
ServerTokens Minor
Server sends (e.g.): Server: Apache/2.0
ServerTokens Min[imal]
サーバは (例えば): Server: Apache/2.0.41 といったように送ります。
ServerTokens OS
サーバは (例えば): Server: Apache/2.0.41 (Unix) といったように送ります。
ServerTokens Full (もしくは未指定)
サーバは (例えば): Server: Apache/2.0.41 (Unix) PHP/4.2.2 MyMod/1.2 といったように送ります。

この設定はサーバ全体に適用され、バーチャルホスト上で有効にしたり 無効にしたりはできません。

バージョン 2.0.44 以降ではこのディレクティブは ServerSignature ディレクティブにより表示される情報も制御します。

参照

  • ServerSignature

SetHandler ディレクティブ

説明: | マッチするファイルがハンドラで処理されるようにする
構文: | SetHandler handler-name|None
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core
互換性: | Apache 2.0 で core に移動

.htaccess や <Directory> セクション、<Location> セクションに書かれた場合、 このディレクティブはそこにあるすべてのファイルが handler-name で指定されたハンドラで扱われることを強制します。例えば、拡張子に関わらず、 ディレクトリ全体がイメージマップファイルとして解析して欲しい場合には、 以下をそのディレクトリの .htaccess ファイルに記述します:

SetHandler imap-file

別の例: URL http://servername/status が指定されたときにサーバが状態報告をするようにしたいときは、以下を httpd.conf に記述します:

<Location /status>
SetHandler server-status
 </Location>

None という値を設定することで、 前の方の SetHandler で定義された設定を無効にすることが できます。

参照

  • AddHandler

SetInputFilter ディレクティブ

説明: | クライアントのリクエストや POST の入力を処理するフィルタを設定する
構文: | SetInputFilter filter[;filter...]
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core

SetInputFilter ディレクティブはクライアントの リクエストや POST の入力をサーバが受け取ったときに処理するフィルタを 設定します。これは AddInputFilter ディレクティブを含め、他の場所で定義されているフィルタの設定に 追加されます。

複数のフィルタを指定するときは、データを処理する順番に セミコロンで区切る必要があります。

参照

  • フィルタ説明書

SetOutputFilter ディレクティブ

説明: | サーバの応答を処理するフィルタを設定する
構文: | SetOutputFilter filter[;filter...]
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core

SetOutputFilter ディレクティブは サーバの応答をクライアントに送り返される前に処理するフィルタを設定します。 これは AddOutputFilter ディレクティブを含め、他の場所で定義されているフィルタの設定に 追加されます。

例えば、以下の設定は /www/data/ ディレクトリのすべての ファイルを SSI で処理します。

<Directory /www/data/>
SetOutputFilter INCLUDES
 </Directory>

複数のフィルタを指定するときは、データを処理する順番に セミコロンで区切る必要があります。

参照

  • フィルタ説明書

TimeOut ディレクティブ

説明: | 各イベントについて、リクエストを失敗させるまでにサーバが 待つ時間を設定
構文: | TimeOut seconds
デフォルト: | TimeOut 300
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core

TimeOut ディレクティブは、現在のところ 以下の三つの待ち時間についての定義を行います:

  1. GET リクエストを受け取るのにかかる総時間
  2. POST や PUTリクエストにおいて、次の TCP パケットが届くまでの待ち時間
  3. レスポンスを返す際、TCP の ACK が帰ってくるまでの時間

将来には別々の設定をすることが可能にできるよう考慮中です。 Apache 1.2 以前はタイマーは 1200 がデフォルトでしたが、 300 に下げられました。300 でもほとんどの場合は十分すぎる値です。 コード中の変な場所にまだパケットを送る際にタイマをリセットしない 場所があるかもしれないので、デフォルトをより小さい値にはしていません。

UseCanonicalName ディレクティブ

説明: | サーバが自分自身の名前とポートを決定する方法を設定する
構文: | UseCanonicalName On|Off|Dns
デフォルト: | UseCanonicalName On
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Core
モジュール: | core

多くの状況で Apache は自己参照 URL、すなわち 同じサーバを指す URL、を作成する必要があります。 UseCanonicalName On を使うと (1.3 より前の すべてのバージョンでも) Apache は ServerName ディレクティブと Port ディレクティブを使ってサーバの正式な名前を作成します。 この名前がすべての自己参照 URL で使われ、CGI の SERVER_NAME と SERVER_PORT にも使われます。

UseCanonicalName Off では Apache は クライアントがホスト名とポートを提供した場合には自己参照 URL を それらを元に作成します (提供されていない場合は上で定義されているように 正式な名前を使います)。 これらの値は名前ベースの バーチャルホストを実装するのに使われているのと同じ値で、 同じクライアントから取得できる値です。CGI 変数 SERVER_NAME と SERVER_PORT もクライアントから与えられた値から 作成されます。

これが有用な場合の例は、イントラネットのサーバで、www の ような短い名前でユーザがマシンに接続しているときです。 ユーザが短い名前を入力して、URL が最後のスラッシュ無しのディレクトリ へのものであるときに、Apache はリクエストを http://www.domain.com/splat/ へリダイレクトすることに 気付くでしょう。認証をするように設定していると、この場合 ユーザは 2 回認証をしなければならなくなります (www に 対して 1 回、www.domain.com に対してもう一回 -- より詳しい情報は この話題の FAQ を参照してください)。 しかし、UseCanonicalName が Off になっていると、 Apache は htttp://www/splat/ にリダイレクトします。

三つ目のオプション UseCanonicalName DNS は、 Host: ヘッダを提供しない古いクライアントをサポートした 大規模な IP ベースのバーチャルホスティングで使用されることを 意図しています。このオプションでは、Apache はクライアントが 接続した IP アドレスに DNS の逆引きを行なって自己参照 URL を 作成します。

警告

CGI が SERVER_NAME に 関する仮定を行なっているときは、このオプションの設定で動作しなく なるかもしれません。クライアントは実質的にはホスト名にとして 何でも望みの値を指定することができます。CGI が SERVER_NAME のみを使って自己参照 URL を作成している 場合はどの設定を行なっても大丈夫なはずです。

参照

  • ServerName
  • Listen

<VirtualHost> ディレクティブ

説明: | 特定のホスト名や IP アドレスのみに適用されるディレクティブを 囲む
構文: | <VirtualHost addr[:port] [addr[:port]] ...> ... </VirtualHost>
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core

<VirtualHost> 及び </VirtualHost> は、 特定のバーチャルホストに対してのみ適用されるディレクティブ群を括る ために使われます。 バーチャルホストコンテキストで許可される全てのディレクティブを指定可能です。 サーバが、指定されたバーチャルホストにあるドキュメントへの リクエストを受け付けた場合、 <VirtualHost> セクションの中にある ディレクティブが適用されます。 Addrは、次のものが利用できます:

  • バーチャルホストの IP アドレス
  • バーチャルホストの IP に対応する完全なドメイン名
  • NameVirtualHost * と共に使われる、 すべての IP アドレスにマッチする文字 *
  • IP ベースのバーチャルホストで他のものにマッチしない IP アドレス のための文字列 _default_

例

<VirtualHost 10.1.2.3>
ServerAdmin webmaster@host.foo.com
DocumentRoot /www/docs/host.foo.com
ServerName host.foo.com
ErrorLog logs/host.foo.com-error_log
TransferLog logs/host.foo.com-access_log
 </VirtualHost>

IPv6 アドレスはオプションのポート番号の指定と区別するために、 角括弧で括って指定する必要があります。次は IPv6 の例です:

<VirtualHost [fe80::a00:20ff:fea7:ccea]>
ServerAdmin webmaster@host.example.com
DocumentRoot /www/docs/host.example.com
ServerName host.example.com
ErrorLog logs/host.example.com-error_log
TransferLog logs/host.example.com-access_log
 </VirtualHost>

各々のバーチャルホストにはそれぞれ違う IP アドレス、ポート番号 もしくはホスト名に対応する必要があり、 1 番目の場合には複数のアドレスで IP パケットを受信できるように サーバマシンを設定しなければなりません。 (もし、マシンが複数のネットワークインターフェースと持たない場合は、 (OSがサポートしていれば) ifconfig alias コマンドにより 達成できます)。

:port といった形式で記述することにより、 マッチさせるポートを変更可能です。 この指定をしない場合には、主サーバ設定における 一番最後に Port で指定されたポートが デフォルトとなります。 :* を指定することにより、 アドレス上の全てのポートにマッチします。(_default_ のときは これを使うことが推奨されています。)

セキュリティに関して: サーバーを起動した以外のユーザがログファイルが保管されるディレクトリに 書き込み可能なときになぜセキュリティが破られる可能性があるかの詳細は セキュリティに関するコツ を 参照してください。

注意点

<VirtualHost> は Apache が Listen する IP アドレスには影響を与えません。 Listen を 使って Apache が正しいアドレスを listen するように設定する必要があります。

IP ベースのバーチャルホストを使っている場合は、特別な名前 _default_ を指定することができます。その場合は そのバーチャルホストは他のバーチャルホストで明示的に挙げられていない すべての IP アドレスにマッチします。_default_ バーチャルホストが無い 場合に IP がバーチャルホストで指定されたものにマッチしないときは、 VirtualHost セクションの外のすべての定義からなる「主」サーバ設定が 使われます。(ただし、NameVirtualHost ディレクティブにマッチする すべての IP アドレスは「主」サーバ設定も _default_ バーチャルホストも 使わないことに注意してください。詳しくは ネームベースのバーチャルホスト を 参照してください。)

:port といった形式で記述することにより、 マッチさせるポートを変更可能です。 この指定をしない場合には、主サーバ設定における 一番最後に Listen で指定された ポートがデフォルトとなります。 :* を指定することにより、 アドレス上の全てのポートにマッチします。(_default_ のときは これを使うことが推奨されています。)

:port といった形式で記述することにより、 マッチさせるポートを変更可能です。 この指定をしない場合には、主サーバ設定における 一番最後に Port で指定されたポートが デフォルトとなります。 :* を指定することにより、 アドレス上の全てのポートにマッチします。(_default_ のときは これを使うことが推奨されています。)

セキュリティ

サーバーを起動した以外のユーザがログファイルが保管されるディレクトリに 書き込み可能なときになぜセキュリティが破られる可能性があるかの詳細は セキュリティに関するコツ を 参照してください。

参照

  • Apache バーチャルホスト説明書
  • DNS と Apache に関する話
  • Apache が使用するアドレスとポートの設定
  • リクエストを受けた際にこれらの異なるセクションが 組み合わされる方法については <Directory>, <Location>, <Files> セクションの動作法


mpm_common - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache MPM 共通ディレクティブ

This translation may be out of date. Check the English version for recent changes.
説明: | 二つ以上のマルチプロセッシングモジュール (MPM) で実装されているディレクティブのコレクション
ステータス: | MPM

CoreDumpDirectory ディレクティブ

説明: | Apache がコアダンプする前に移動を試みるディレクトリ
構文: | CoreDumpDirectory directory
デフォルト: | デフォルトの設定は説明文を読んでください
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, perchild, prefork, mpm_winnt

Apache がコアダンプする前に移動を試みるディレクトリを制御します。 デフォルト値は ServerRoot ディレクトリですが、このディレクトリはサーバの実行されているユーザ権限で 書き込み可能であるべきではないので、通常はコアダンプは書き込まれません。 デバッグのためにコアダンプが必要であれば、 このディレクティブを使って他の位置にコアダンプを書き出すようにできます。

Group ディレクティブ

説明: | リクエストに応答する際に所属するグループ
構文: | Group unix-group
デフォルト: | Group #-1
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | MPM
モジュール: | worker, perchild, prefork

Group ディレクティブで、 リクエストに応答する際に所属しておくグループを設定します。 このディレクティブを使用するためには、スタンドアロン型の サーバは最初に root 権限で起動されている必要があります。 unix-group は次のうちのいずれかです:

グループ名
グループを名前で参照します。
# に続いてグループ番号
グループを番号で参照します。

サーバを実行するために特定の新しいグループを設定することを お薦めします。nobody を使用する管理者もいますが、 これは常に可能であったり望ましい訳ではありません。

Group www-group

注意: サーバ開始を非 root ユーザで行った場合は、 指定されたグループに変わることができなくて、代わりに 起動を行ったユーザの所属するグループとして実行され続けます。

特記事項: このディレクティブを <VirtualHost> で使用することはサポートされなくなりました。Apache 2.0 で suEXEC ラッパーを実現したい場合は、 SuexecUserGroup を使用してください。 セキュリティ: セキュリティ上の注意点に関しては、 User をご覧下さい。

Listen ディレクティブ

説明: | サーバが listen するIP アドレスとポート番号
構文: | Listen [IP-address:]portnumber
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, perchild, prefork, mpm_winnt

Listen ディレクティブは Apache が特定の IP アドレスやポート番号だけを listen するように指定します。 デフォルトでは全ての IP インターフェースのリクエストに応答します。 Listen ディレクティブは現在では必須のディレクティブとなりました。 もし設定ファイルになければ、サーバは起動に失敗します。 これは以前のバージョンの Apache から変更のあった部分です。

Listen ディレクティブでは、特定のポートあるいは アドレスとポートの組み合わせから入ってくるリクエストに対して 応答するように指定します。 もしポート番号だけが指定された場合は、サーバは全インターフェースの 指定されたポート番号に対して listen します。 IP アドレスがポートとともに指定された場合は、 サーバは指定されたポートとインターフェースに対して listen します。

複数のアドレスとポートに対して listen するように、 複数の Listen ディレクティブを使うこともできます。 サーバは列挙されたアドレスとポート全てからのリクエストに対して 応答します。

例えば、サーバが 80 番ポートと 8000 番ポートの両方の コネクションを受け入れる場合は、次のようにします。

Listen 80
Listen 8000

二つの特定のインターフェースとポート番号からのコネクションを 受け入れるようにするには、次のようにします。

Listen 192.170.2.1:80
Listen 192.170.2.5:8000

IPv6 アドレスは角括弧で囲まなければなりません。 例えば次の例のようにです。

Listen [fe80::a00:20ff:fea7:ccea]:80

参照

  • DNS の問題
  • Apache が使用するアドレスとポートの設定

ListenBackLog ディレクティブ

説明: | 保留状態のコネクションのキューの最大長
構文: | ListenBacklog backlog
デフォルト: | ListenBacklog 511
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, perchild, prefork, mpm_winnt

保留状態のコネクションのキューの最大長です。 一般的には調整する必要はありませんし、調整は望ましくありません。 しかし、TCP SYN フラッドアタックの状況下におかれる場合に、 増やした方が望ましいシステムもあります。 listen(2) システムコールのバックログパラメータを ご覧下さい。

この値は OS により、小さな数に抑えられます。 値は OS 毎に異なっています。また多くの OS では、 バックログとして指定されている値ちょうどまで使っているわけではなく、 設定されている値に基づいて (通常は設定値よりも大きな値を) 使っていることに注意してください。

LockFile ディレクティブ

説明: | 受付を直列化するためのロックファイルの位置
構文: | LockFile filename
デフォルト: | LockFile logs/accept.lock
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, perchild, prefork

USE_FCNTL_SERIALIZED_ACCEPT または USE_FLOCK_SERIALIZED_ACCEPT のいずれかを使って Apache をコンパイルした際に使用することになる、 ロックファイルのパスを LockFile は設定します。 このディレクティブは通常はデフォルト値のままにしておくべきです。 これを変更する際の主な理由は、logs ディレクトリが NFS マウントされたものであるという理由です。 ロックファイルはローカルディスクに保存しなければならない からです。 メインサーバプロセスの PID が自動的にファイル名に付加されます。

セキュリティ:

/var/tmp といった、誰でも書き込めるディレクトリにファイルを 置かない方がよいです。なぜなら、サーバが起動時に作成する ロックファイルの作成自体を妨害することによって、 誰でもサービス拒否アタックを引き起こすことができるからです。

MaxClients ディレクティブ

説明: | リクエストに応答するために作成される 子プロセスの最大個数
構文: | MaxClients number
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, prefork

MaxClients ディレクティブは、 応答することのできる同時リクエスト数を設定します。 MaxClients 制限数を越えるコネクションは通常、 ListenBacklog ディレクティブで設定した数までキューに入ります。 他のリクエストの最後まで達して子プロセスが空くと、 次のコネクションに応答します。

スレッドを用いないサーバ (すなわち prefork) では、MaxClients は、リクエストに応答するために起動される 子プロセスの最大数となります。 デフォルト値は 256 で、これを増加させたい場合は、 ServerLimit の値も増加させる必要があります。

スレッドを用いるサーバ (すなわち worker) では、MaxClients は、クライアントに応答できるスレッドの総数を制限します。 デフォルト値は ThreadsPerChild を 16 倍した値になります。MaxClients を 16 プロセス以上必要な値まで増加させたい場合は、 ServerLimit も増加させる必要があります。

MaxMemFree ディレクティブ

説明: | 主メモリアロケータが free() を呼ばずに保持し続けられるメモリの 最大量
構文: | MaxMemFree number
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, prefork, mpm_netware

MaxMemFree ディレクティブは free() を呼ばずに 主アロケータが保持できる空のメモリの最大値をキロバイト単位で設定します。 設定されていないか、零に設定されているときは、無制限になります。

MaxRequestsPerChild ディレクティブ

説明: | 個々の子サーバが稼働中に扱うリクエスト数の上限
構文: | MaxRequestsPerChild number
デフォルト: | MaxRequestsPerChild 10000
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, perchild, prefork, mpm_winnt

MaxRequestsPerChild ディレクティブは、 個々の子サーバプロセスが扱うことのできるリクエストの制限数を 設定します。MaxRequestsPerChild 個のリクエストの後に、子プロセスは終了します。 MaxRequestsPerChild が 0 に設定されている場合は、プロセスは期限切れにより終了することはありません。

MaxRequestsPerChild を非ゼロに制限することには、二つの利点があります:

  • (偶発的な) メモリーリークが起こった場合に プロセスが消費するメモリの総量を制限できる
  • プロセスに有限のライフタイムを設定することで、 サーバ負荷が下がった時にプロセス数を少なくすることができる

注意:

KeepAlive リクエストの場合は、 一つ目のリクエストだけがこの制限に該当します。 実効的には、一つの子プロセスあたりのコネクション数を 制限するように挙動が変化します。

MaxSpareThreads ディレクティブ

説明: | アイドルスレッドの最大数
構文: | MaxSpareThreads number
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | mpm_netware, perchild, worker

アイドルなスレッドの最大数です。異なる MPM ではそれぞれ、 このディレクティブは異なる取り扱われ方をされます。

perchild では、 デフォルトは MaxSpareThreads 10 です。 この MPM はアイドルスレッド数を、それぞれの子プロセスごとに監視します。 子プロセスにアイドルスレッドが多すぎる場合は、 サーバはその子プロセスに含まれるスレッドを終了し始めます。

worker では、 デフォルトは MaxSpareThreads 500 です。 この MPM はアイドルスレッド数をサーバ全体で監視します。 サーバでアイドルスレッド数が多すぎる場合は、 この数字よりも少ない数になるまで子プロセスを終了します。

mpm_netware では、 デフォルトは MaxSpareThreads 100 です。 この MPM はシングルプロセスで実行されますので、 スペアスレッド数もサーバ全体で勘定します。

参照

  • MinSpareThreads
  • StartServers

MaxThreadsPerChild ディレクティブ

説明: | 子プロセス毎のスレッド数の最大数
構文: | MaxThreadsPerChild number
デフォルト: | MaxThreadsPerChild 64
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, perchild

子プロセス毎に含まれるスレッド数の最大値です。 子プロセス毎にスレッド数変化する MPM では、 このディレクティブは、子プロセス内に生成されるスレッド数の 最大値を設定します。デフォルト値よりも大きい値にするのであれば、 コンパイル時に定義された HARD_THREAD_LIMIT を変更して、サーバを再コンパイルする必要があります。

MinSpareThreads ディレクティブ

説明: | リクエストに応答することのできる アイドルスレッド数の最小数
構文: | MinSpareServers number
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | mpm_netware, perchild, worker

リクエストに応答するスレッド数の最小値です。 異なる MPM ではそれぞれ、 このディレクティブは異なる取り扱われ方をします。

perchild では、 デフォルトは MinSpareThreads 5 で、 アイドルスレッド数を子プロセス毎に監視します。 もし子プロセスに十分な数のスレッドがなければ、 サーバはその子プロセスに新しいスレッドを作り始めます。

worker では、 デフォルトは MinSpareThreads 250 で、 アイドルスレッド数をサーバ全体で監視します。 もしサーバに十分な数のアイドルスレッドがなければ、 アイドルスレッド数がこの数よりも大きくなるまで 新しい子プロセスが生成されます。

mpm_netware では、 デフォルトは MinSpareThreads 10 で、 シングルプロセス MPM ですので、サーバ全体で管理されます。

参照

  • MaxSpareThreads
  • StartServers

NumServers ディレクティブ

説明: | 同時に起動している子プロセスの総数
構文: | NumServers number
デフォルト: | NumServers 2
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | perchild

同時に起動している子プロセスの数です。 このディレクティブを使用する MPM は動的に新しい子プロセスを 生成することは行わないので、サイト全体に来るリクエスト全てを 十分扱える程度に大きな数に設定しておく必要があります。

PidFile ディレクティブ

説明: | デーモンのプロセス ID をサーバが記録するためのファイル
構文: | PidFile filename
デフォルト: | PidFile logs/httpd.pid
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, perchild, prefork, mpm_winnt

PidFile ディレクティブで、 デーモンのプロセス ID をサーバが記録するファイルを設定します。 もしファイル名がスラッシュ (/) で始まらない場合は、 ServerRoot からの相対的なものとして扱われます。

例

PidFile /var/run/apache.pid

サーバが ErrorLog や TransferLog を閉じて開き直したり、設定ファイルを 再読込したりさせるために、サーバにシグナルを送ることができると 便利なことがあります。 これは SIGHUP (kill -1) シグナルを PidFile に書かれているプロセス ID に送ることでできます。

PidFile には、ログファイルの設置位置や セキュリティ と全く同じ注意点があります。

ScoreBoardFile ディレクティブ

説明: | 子プロセスと連携するためのデータを保存する ファイルの位置
構文: | ScoreBoardFile file-path
デフォルト: | ScoreBoardFile logs/apache_status
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, perchild, prefork

Apache は親プロセスと子プロセス間の通信にスコアボードを用います。 この通信機能にファイルを必要とするアーキテクチャもあります。 ファイルが指定されていなければ、Apache はまずメモリ上 (匿名共有メモリ) にスコアボードを作ろうとし、それが失敗すると ディスク上にファイル (ファイルベースの共有メモリ) を作ろうとします。 このディレクティブを指定すると、Apache は必ずディスクにファイルを生成します。

例

ScoreBoardFile /var/run/apache_status

ファイルベースの共有メモリは、サードパーティー製のアプリケーションで スコアボードに直接アクセスする必要がある場合に役に立ちます。

ScoreBoardFile を使う場合、 RAM ディスク上に置くとスピードが向上するでしょう。 しかし、ログファイルの設置位置や セキュリティ と同様の注意点があるので、注意してください。

参照

  • Apache の停止と再起動

SendBufferSize ディレクティブ

説明: | TCP バッファサイズ
構文: | SendBufferSize bytes
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, perchild, prefork, mpm_winnt

サーバは TCP バッファサイズを指定されたバイト数に設定します。 高速で高レイテンシな環境で (例 100ms 程度、大陸横断高速通信路など) 古い一般的な OS のデフォルト値を増やすのに非常に便利です。

ServerLimit ディレクティブ

説明: | 設定可能なサーバプロセス数の上限
構文: | ServerLimit number
デフォルト: | ServerLimit 256 (prefork), ServerLimit 16 (worker)
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, prefork

prefork MPM の場合は、このディレクティブは Apache プロセス稼働中における MaxClients に設定可能な上限値を設定することになります (訳注: prefork の場合は同時クライアント数 = サーバプロセス数なので) 。 worker MPM の場合には、このディレクティブは ThreadLimit ディレクティブと組み合わせて、 Apache プロセス稼働中における MaxClients に設定可能な上限値を設定することになります。 再起動中にこのディレクティブを変更しても無視されますが、 MaxClients は再起動中に修正することができます。

このディレクティブを使用する際は特に注意してください。 ServerLimit が必要以上に大きな値に 設定された場合は、余計な未使用共有メモリが割り当てられます。 ServerLimit と MaxClients がシステムの扱える範囲を越えた設定値になっていると、 Apache は起動しないか、起動しても不安定になるでしょう。

prefork MPM では、 MaxClients を 256 よりも大きな値に設定する必要がある時にだけ使用してください。 希望の MaxClients 数とくらべて、必要以上に大きな値を指定することは避けてください。

worker MPM では、 MaxClients と ThreadsPerChild の設定で 16 サーバプロセス以上必要になる場合にのみ使用してください。 希望の MaxClients と ThreadsPerChild とくらべて、必要となるサーバプロセス数以上に大きな値を 設定することは避けてください。

StartServers ディレクティブ

説明: | 起動時に生成される子サーバプロセスの数
構文: | StartServers number
デフォルト: | StartServers 5
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker

StartServers ディレクティブは、 起動時に生成される子サーバプロセスの数を設定します。 プロセス数は負荷に応じて動的に制御されますので、 通常はこの値を調整する理由はあまりないでしょう。

参照

  • MinSpareThreads
  • MaxSpareThreads

StartThreads ディレクティブ

説明: | 起動時に生成されるスレッドの数
構文: | StartThreads number
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | mpm_netware, perchild

起動時に生成されるスレッドの数です。 スレッド数は負荷に応じて動的に制御されますので、 通常はこの値を調整する理由はあまりないでしょう。

perchild でのデフォルトは StartThreads 5 で、このディレクティブは起動時に プロセス毎のスレッド数を追跡します。

mpm_netware でのデフォルトは StartThreads 50 で、 この場合プロセスは一つしかないので、 起動時にリクエストに応答するスレッドの総数となります。

ThreadLimit ディレクティブ

説明: | 設定可能な子プロセス毎のスレッド数の上限を 設定します
構文: | ThreadLimit number
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | mpm_winnt, worker

このディレクティブは Apache プロセス稼働中における ThreadsPerChild に設定可能な上限値を設定します。再起動時にこのディレクティブの値を 変更しても無視されますが、 ThreadsPerChild は再起動中に、このディレクティブで指定された上限値まで 変更することができます。

このディレクティブを使用する際は特に注意してください。 ThreadLimit が ThreadsPerChild よりもずっと大きな値に設定された場合は、 余計な未使用共有メモリが割り当てられてしまいます。 ThreadLimit が ThreadsPerChild の両方がシステムの扱える範囲を超えている場合は、 Apache は起動しないか、起動したとしても不安定になるでしょう。 このディレクティブの値は今使用している Apache の ThreadsPerChild の予想上限値を 超えた値には設定しないでください。

ThreadLimit のデフォルト値は worker のときは 64 で、mpm_winnt のときは 1920 です。

ThreadsPerChild ディレクティブ

説明: | 子プロセスそれぞれに生成されるスレッド数
構文: | ThreadsPerChild number
デフォルト: | ThreadsPerChild 50
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | worker, mpm_winnt

このディレクティブは、それぞれの子プロセスで生成される スレッド数を設定します。 子プロセスは開始時にこれらのスレッドを生成して、 その後は生成しません。mpm_winnt のような、 子プロセスが一つしかないような MPM を利用しているのであれば、 この値はサーバの負荷全体を十分取り扱える程度に、 大きくなければなりません。worker のような、 子プロセスが複数あるような MPM を利用しているのであれば、 サーバの通常負荷を十分扱える程度に、 スレッド総数が多くなければなりません。

User ディレクティブ

説明: | リクエストに応答する際に用いるユーザ ID
構文: | User unix-userid
デフォルト: | User #-1
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | MPM
モジュール: | worker, perchild, prefork

User ディレクティブは サーバがリクエストに応答する際に用いるユーザ ID を設定します。 このディレクティブを使用するためには、スタンドアロン型の サーバは最初に root 権限で起動されている必要があります。 unix-userid は次のどちらかです:

ユーザ名
ユーザを名前で参照します。
# に続いてユーザ番号
ユーザを番号で参照します。

このユーザは、外部に見せるように意図していないファイルに、 アクセス可能になってしまうような権限を持つべきではないですし、 同様に httpd リクエストに対して応答するように意図していない 実行コードを、実行できるような権限を持つべきではないです。 サーバを実行するために特定の新しいユーザとグループを 設定することをお薦めいたします。 nobody ユーザを使用する管理者もいますが、 これが常に望ましいわけではありません。 なぜなら nobody ユーザは、システムで 他の役割を担っているかも知れないからです。

注意: 非 root ユーザでサーバを起動した場合は、 より低い権限のユーザに変わることに失敗して、 代わりに起動を行ったユーザ権限のまま実行され続けるでしょう。 root 権限で開始した場合親プロセスが root 権限で実行され続けますが、これは正常です。

特記事項: このディレクティブを <VirtualHost> で使用することはサポートされなくなりました。 suexec 向けにサーバを設定するのであれば、 SuexecUserGroup を使用してください。

セキュリティ

自分が何をやっているのか正確に把握していない、 そしてその危険性を把握していないのであれば、 User (や Group) を root に設定しないでください。


beos - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM beos

Description: | This Multi-Processing Module is optimized for BeOS.
Status: | MPM
Module?dentifier: | mpm_beos_module
Source?ile: | beos.c

Summary

This Multi-Processing Module (MPM) is the default for BeOS. It uses a single control process which creates threads to handle requests.

See also

  • Setting which addresses and ports Apache uses

MaxRequestsPerThread Directive

Description: | Limit on the number of requests that an individual thread will handle during its life
Syntax: | MaxRequestsPerThread number
Default: | MaxRequestsPerThread 0
Context: | server config
Status: | MPM
Module: | beos

The MaxRequestsPerThread directive sets the limit on the number of requests that an individual server thread will handle. After MaxRequestsPerThread requests, the thread will die. If MaxRequestsPerThread is 0, then the thread will never expire.

Setting MaxRequestsPerThread to a non-zero limit has two beneficial effects:

  • it limits the amount of memory that a thread can consume by (accidental) memory leakage;
  • by giving threads a finite lifetime, it helps reduce the number of threads when the server load reduces.

Note:

For KeepAlive requests, only the first request is counted towards this limit. In effect, it changes the behavior to limit the number of connections per thread.


leader - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM leader

Description: | An experimental variant of the standard worker MPM
Status: | MPM
Module?dentifier: | mpm_leader_module
Source?ile: | leader.c

Summary

Warning

This MPM is experimental, so it may or may not work as expected.

This is an experimental variant of the standard worker MPM. It uses a Leader/Followers design pattern to coordinate work among threads. For more info, see http://deuce.doc.wustl.edu/doc/pspdfs/lf.pdf.

To use the leader MPM, add --with-mpm=leader to the configure script's arguments when building the httpd.

This MPM depends on APR's atomic compare-and-swap operations for thread synchronization. If you are compiling for an x86 target and you don't need to support 386s, or you are compiling for a SPARC and you don't need to run on pre-UltraSPARC chips, add --enable-nonportable-atomics=yes to the configure script's arguments. This will cause APR to implement atomic operations using efficient opcodes not available in older CPUs.


mpm_netware - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM netware

Description: | Multi-Processing Module implementing an exclusively threaded web server optimized for Novell NetWare
Status: | MPM
Module?dentifier: | mpm_netware_module
Source?ile: | mpm_netware.c

Summary

This Multi-Processing Module (MPM) implements an exclusively threaded web server that has been optimized for Novell NetWare.

The main thread is responsible for launching child worker threads which listen for connections and serve them when they arrive. Apache always tries to maintain several spare or idle worker threads, which stand ready to serve incoming requests. In this way, clients do not need to wait for a new child threads to be spawned before their requests can be served.

The StartThreads, MinSpareThreads, MaxSpareThreads, and MaxThreads regulate how the main thread creates worker threads to serve requests. In general, Apache is very self-regulating, so most sites do not need to adjust these directives from their default values. Sites with limited memory may need to decrease MaxThreads to keep the server from thrashing (spawning and terminating idle threads). More information about tuning process creation is provided in the performance hints documentation.

MaxRequestsPerChild controls how frequently the server recycles processes by killing old ones and launching new ones. On the NetWare OS it is highly recommended that this directive remain set to 0. This allows worker threads to continue servicing requests indefinitely.

See also

  • Setting which addresses and ports Apache uses

MaxThreads Directive

Description: | Set the maximum number of worker threads
Syntax: | MaxThreads number
Default: | MaxThreads 2048
Context: | server config
Status: | MPM
Module: | mpm_netware

The MaxThreads directive sets the desired maximum number worker threads allowable. The default value is also the compiled in hard limit. Therefore it can only be lowered, for example:

MaxThreads 512

ThreadStackSize Directive

Description: | Determine the stack size for each thread
Syntax: | ThreadStackSize number
Default: | ThreadStackSize 65536
Context: | server config
Status: | MPM
Module: | mpm_netware

This directive tells the server what stack size to use for each of the running threads. If you ever get a stack overflow you will need to bump this number to a higher setting.


mpmt_os2 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM os2

Description: | Hybrid multi-process, multi-threaded MPM for OS/2
Status: | MPM
Module?dentifier: | mpm_mpmt_os2_module
Source?ile: | mpmt_os2.c

Summary

The Server consists of a main, parent process and a small, static number of child processes.

The parent process's job is to manage the child processes. This involves spawning children as required to ensure there are always StartServers processes accepting connections.

Each child process consists of a a pool of worker threads and a main thread that accepts connections and passes them to the workers via a work queue. The worker thread pool is dynamic, managed by a maintenance thread so that the number of idle threads is kept between MinSpareThreads and MaxSpareThreads.

See also

  • Setting which addresses and ports Apache uses


perchild - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM perchild

Description: | Multi-Processing Module allowing for daemon processes serving requests to be assigned a variety of different userids
Status: | MPM
Module?dentifier: | mpm_perchild_module
Source?ile: | perchild.c

Summary

This module is not functional. Development of this module is not complete and is not currently active. Do not use perchild unless you are a programmer willing to help fix it.

This Multi-Processing Module (MPM) implements a hybrid multi-process, multi-threaded web server. A fixed number of processes create threads to handle requests. Fluctuations in load are handled by increasing or decreasing the number of threads in each process.

See also

  • Setting which addresses and ports Apache uses

How it works

A single control process launches the number of child processes indicated by the NumServers directive at server startup. Each child process creates threads as specified in the StartThreads directive. The individual threads then listen for connections and serve them when they arrive.

Apache always tries to maintain a pool of spare or idle server threads, which stand ready to serve incoming requests. In this way, clients do not need to wait for new threads to be created. For each child process, Apache assesses the number of idle threads and creates or destroys threads to keep this number within the boundaries specified by MinSpareThreads and MaxSpareThreads. Since this process is very self-regulating, it is rarely necessary to modify these directives from their default values. The maximum number of clients that may be served simultaneously is determined by multiplying the number of server processes that will be created (NumServers) by the maximum number of threads created in each process (MaxThreadsPerChild).

While the parent process is usually started as root under Unix in order to bind to port 80, the child processes and threads are launched by Apache as a less-privileged user. The User and Group directives are used to set the privileges of the Apache child processes. The child processes must be able to read all the content that will be served, but should have as few privileges beyond that as possible. In addition, unless suexec is used, these directives also set the privileges which will be inherited by CGI scripts.

MaxRequestsPerChild controls how frequently the server recycles processes by killing old ones and launching new ones.

Working with different user-IDs

The perchild MPM adds the extra ability to specify that particular processes should serve requests under different user-IDs. These user-IDs can then be associated with specific virtual hosts. You have to use one ChildPerUserID directive for every user/group combination you want to be run. Then you can tie particular virtual hosts to that user and group IDs.

The following example runs 7 child processes. Two of them are run under user1/group1. The next four are run under user2/group2 and the remaining process uses the User and Group of the main server:

Global config

NumServers 7
ChildPerUserID user1 group1 2
ChildPerUserID user2 group2 4

Using unbalanced numbers of processes as above is useful, if the particular virtual hosts produce different load. The assignment to the virtual hosts is easily done as in the example below. In conclusion with the example above the following assumes, that server2 has to serve about twice of the hits of server1.

Example

NameVirtualHost *

<VirtualHost *>
ServerName fallbackhost
# no assignment; use fallback
 </VirtualHost>

<VirtualHost *>
ServerName server1
AssignUserID user1 group1
 </VirtualHost>

<VirtualHost *>
ServerName server2
AssignUserID user2 group2
 </VirtualHost>

AssignUserID Directive

Description: | Tie a virtual host to a user and group ID
Syntax: | AssignUserID user-id group-id
Context: | virtual host
Status: | MPM
Module: | perchild

Tie a virtual host to a specific user/group combination. Requests addressed to the virtual host where this directive appears will be served by a process running with the specified user and group ID.

The user and group ID has to be assigned to a number of children in the global server config using the ChildPerUserID directive. See the section above for a configuration example.

ChildPerUserID Directive

Description: | Specify user ID and group ID for a number of child processes
Syntax: | ChildPerUserID user-id group-id num-children
Context: | server config
Status: | MPM
Module: | perchild

Specify a user ID and group ID for a number of child processes. The third argument, num-children, is the number of child processes to start with the specified user and group. It does not represent a specific child number. In order to use this directive, the server must be run initially as root. If you start the server as a non-root user, it will fail to change to the lesser privileged user.

If the total number of child processes, found by totaling all of the third arguments to all ChildPerUserID directives in the config file, is less than NumServers, then all remaining children will inherit the User and Group settings from the main server. See the section above for a configuration example.

Security

Don't set user-id (or group-id) to root unless you know exactly what you are doing, and what the dangers are.

MaxThreadsPerChild Directive

Description: | Maximum number of threads per child process
Syntax: | MaxThreadsPerChild number
Default: | MaxThreadsPerChild 64
Context: | server config
Status: | MPM
Module: | perchild

This directive sets the maximum number of threads that will be created in each child process. To increase this value beyond its default, it is necessary to change the value of the ThreadLimit directive and stop and re-start the server.

NumServers Directive

Description: | Total number of children alive at the same time
Syntax: | NumServers number
Default: | NumServers 2
Context: | server config
Status: | MPM
Module: | perchild

The NumServers directive determines the number of children alive at the same time. This number should be large enough to handle the requests for the entire site. To increase this value beyond the value of 8, it is necessary to change the value of the ServerLimit directive and stop and re-start the server. See the section above for a configuration example.


prefork - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache MPM prefork

説明: | スレッドを使わず、先行して fork を行なうウェブサーバを実装
ステータス: | MPM
モジュール識別子: | mpm_prefork_module
ソースファイル: | prefork.c

概要

このマルチプロセッシングモジュール (MPM) は、 Unix 上での Apache 1.3 のデフォルトの挙動と非常によく似た方法で リクエストを処理する、スレッドを使わず、先行して fork を行なう ウェブサーバを実装しています。 スレッドセーフでないライブラリとの互換性をとるために、 スレッドを避ける必要のあるサイトでは、このモジュールの使用が適切でしょう。 あるリクエストで発生した問題が他のリクエストに影響しないように、 個々のリクエストを単離するのにも、最適な MPM です。

この MPM は非常に自律的なので、この MPM の設定ディレクティブを 調整する必要はほとんどないでしょう。もっとも重要なことは、 MaxClients が、予想される同時リクエスト数を十分扱えるぐらいは大きいけれども、 全プロセスに十分な物理メモリが確実に行き渡る程度には小さい値にする、 ということです。

参照

  • Apache が使用するアドレスとポートの設定

動作方法

一つのコントロールプロセスが、 コネクションに対して listen して、しかるべき時に応答する 子プロセスを起動します。Apache は常に幾つかのスペア かアイドルなサーバプロセスを維持していて、それらは入ってきた リクエストに応答できるように待機しています。 このようにしてクライアントは、リクエストが応答される前に、 新しい子プロセスが fork されるのを待たなくてもよいように なっています。

親プロセスがリクエストに応答するの子プロセスを どのように生成するかは、 StartServers, MinSpareServers, MaxSpareServers, MaxClients で調整します。一般的に、Apache は非常に自律的なので、 大抵のサイトではこれらのディレクティブをデフォルト値から調整する 必要はないでしょう。 同時に 256 を超えるリクエストに応答しないといけないサイトでは、 MaxClients を増やす必要があるでしょう。 一方、メモリの限られているサイトでは、スラッシング (メモリとディスク間で何度もスワップ) が起こるのを防ぐために MaxClients を減らす必要があるでしょう。プロセス生成のチューニングに関する 詳しい情報は、性能に関するヒント にあります。

通常 Unix では親プロセスは 80 番ポートにバインドするために root で起動されますが、子プロセスやスレッドは もっと低い権限のユーザで Apache によって起動されます。 User と Group ディレクティブは Apache の子プロセスの権限を設定するのに用いられます。 子プロセスはクライアントに送るコンテンツ全てを読めないといけませんが、 可能な限り必要最小限の権限のみを持っているようにするべきです。

MaxRequestsPerChild は、古いプロセスを停止して新しいプロセスを起動することによって、 どの程度の頻度でサーバがプロセスをリサイクルするかを制御します。

MaxSpareServers ディレクティブ

説明: | アイドルな子サーバプロセスの最大個数
構文: | MaxSpareServers number
デフォルト: | MaxSpareServers 10
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | prefork

MaxSpareServers ディレクティブは、 アイドルな子サーバプロセスの希望最大個数を設定します。 アイドルプロセスとは、リクエストを扱っていないプロセスです。 MaxSpareServers よりも多い数がアイドルであれば、 親プロセスは超過プロセスを kill します。

非常に混んでいるサイトでのみ、このパラメータをチューニングするべきです。 このパラメータを大きくするということは、大抵の場合は悪い発想です。 MinSpareServers よりも小さい値に設定した場合、MinSpareServers +1 に自動調整されます。

参照

  • MinSpareServers
  • StartServers

MinSpareServers ディレクティブ

説明: | アイドルな子サーバプロセスの最小個数
構文: | MinSpareServers number
デフォルト: | MinSpareServers 5
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | prefork

MaxSpareServers ディレクティブは、 アイドルな子サーバプロセスの希望最小個数を設定します。 アイドルプロセスとは、リクエストを扱っていないプロセスです。 MinSpareServers よりも少ない数がアイドルであれば、 親プロセスは最高で 1 秒につき 1 個の割合で新しい子プロセスを生成します。

非常に混んでいるサイトでのみ、このパラメータをチューニングするべきです。 このパラメータを大きくするということは、大抵の場合は悪い発想です。

参照

  • MaxSpareServers
  • StartServers


threadpool - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM threadpool

Description: | Yet another experimental variant of the standard worker MPM
Status: | MPM
Module?dentifier: | mpm_threadpool_module
Source?ile: | threadpool.c

Summary

Warning

This MPM is a developer playground and highly experimental, so it may or may not work as expected.

This is an experimental variant of the standard worker MPM. Rather than queuing connections like the worker MPM, the threadpool MPM queues idle worker threads and hands each accepted connection to the next available worker.

The threadpool MPM can't match the performance of the worker MPM in benchmark testing. As of 2.0.39, some of the key load-throtting concepts from the threadpool MPM have been incorporated into the worker MPM. The threadpool code is useful primarily as a research platform. For general-purpose use and for any production environments, use worker instead.


mpm_winnt - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache MPM winnt

説明: | Windows NT 向けに最適化されたマルチプロセッシングモジュール
ステータス: | MPM
モジュール識別子: | mpm_winnt_module
ソースファイル: | mpm_winnt.c

概要

このマルチプロセッシングモジュール (MPM) は Windows NT でのデフォルトになります。 一つの制御用プロセスを用い、これが一つの子プロセスを起動し、 そして子プロセスがリクエストを取り扱うためにスレッドを 起動します。

Win32DisableAcceptEx ディレクティブ

説明: | ネットワーク接続の受け付けに accept() をAcceptEx の代わりに使う
構文: | Win32DisableAcceptEx
デフォルト: | AcceptEx() はデフォルトで有効になっています。AcceptEx() を無効にする ためにこのディレクティブを使います。
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | mpm_winnt
互換性: | 2.0.49 バージョン以降で使用可能

AcceptEx() は Microsoft WinSock v2 API で、場合によっては BSD 形式の accept() API よりもよい性能を発揮します。 よく使われている Windows 製品の中で、特にウィルススキャナや VPN パッケージ の中には、バグが原因で AcceptEx() の適切な動作を妨げるものがあります。 以下のようなエラーに遭遇した場合は、このディレクティブを使用して AcceptEx() を使用しないようにしてください。

[error] (730038)An operation was attempted on something that is not a socket.: winnt_accept: AcceptEx failed. Attempting to recover.


worker - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache MPM worker

説明: | マルチスレッドとマルチプロセスのハイブリッド型 ウェブサーバを実装したマルチプロセッシングモジュール
ステータス: | MPM
モジュール識別子: | mpm_worker_module
ソースファイル: | worker.c

概要

このマルチプロセッシングモジュール (MPM) は、マルチスレッドとマルチプロセスのハイブリッド型サーバを 実装しています。リクエストの応答にスレッドを使うと、 プロセスベースのサーバよりも少ないシステム資源で、 多くのリクエストに応答することができます。 さらに、多くのスレッドを持った複数のプロセスを維持することで、 プロセスベースのサーバの持つ安定性を保持しています。

この MPM を制御するのに使われる最も重要なディレクティブは、 ThreadsPerChild と MaxClients です。 ThreadsPerChild は 各子プロセスで用意されるスレッド数を制御して、 MaxClients は 起動されるスレッドの総数の最大値を制限します。

参照

  • Apache の使用するアドレスとポートの設定

動作方法

一つの制御用プロセス (親) が子プロセスを起動します。 子プロセスは ThreadsPerChild ディレクティブで指定された一定数のサーバスレッドと接続を listen するスレッドを一つ作ります。 Listener スレッドは接続が来たときにサーバプロセスに渡します。

Apache はスペアの、つまりアイドルなサーバスレッドの プールを常に維持していて、それらは入ってくるリクエストに 答えられるように待機しています。 このようにして、クライアントはリクエストの応答が得られるようになるために 新しいスレッドやプロセスが生成されるのを 待たなくてもよいようになっています。 起動初期時のプロセス総数は、 StartServers ディレクティブで設定されます。その後の稼働中に、 Apache は全プロセスのアイドルスレッドの合計数を見積もって、 MinSpareThreads と MaxSpareThreads で指定された範囲の中にこの数が収まるように fork したり kill したりします。この操作は非常に自律的なので、 これらのディレクティブをデフォルト値から変更する必要は めったにないでしょう。 同時に応答することのできるクライアント数の最大数 (つまり全プロセス中の総スレッド数の最大値) は MaxClients ディレクティブで決定されます。 活動中の子プロセス数の最大値は MaxClients を ThreadsPerChild で割った ものになります。

活動中の子プロセスの数と子プロセス中のサーバスレッドの数の越えられない 上限を設定するディレクティブが二つあります。これらはサーバを 完全に停止して、再起動することでしか変更することはできません。 ServerLimit は活動中の子プロセスの越えられない上限を設定し、 MaxClients ディレクティブ の値を ThreadsPerChild の値で割った値以上である 必要があります。ThreadLimit は サーバスレッドの越えられない上限で、ThreadsPerChild ディレクティブの 値以上である必要があります。デフォルト以外の値を指定する場合は 他の worker ディレクティブよりも前に書かれている 必要があります。

活動中の子プロセス群に加えて、少なくとも一つのサーバスレッドが 既存のクライアントからの接続を扱っている終了しようとしている 子プロセスがある可能性があります。終了中のプロセスは MaxClients で指定された数まで 存在できますが、実際に期待される数はずっと少なくなります。この 振舞いは各子プロセスを終了させないようにすることで回避できます。 これは以下の様にして実現できます。

  • MaxRequestsPerChild の値を 0 に設定する
  • MaxSpareThreads の値を MaxClients と同じ値にする

worker MPM の典型的なプロセス・スレッド制御の 設定では、次のようになります。

ServerLimit 16
StartServers 2
MaxClients 150
MinSpareThreads 25
MaxSpareThreads 75
ThreadsPerChild 25

通常 Unix では親プロセスは 80 番ポートにバインドするために root で起動されますが、子プロセスやスレッドは もっと低い権限のユーザで Apache によって起動されます。 User と Group ディレクティブは Apache の子プロセスの権限を設定するのに用いられます。 子プロセスはクライアントに送るコンテンツ全てを読めないといけませんが、 可能な限り必要最小限の権限のみを持っているようにするべきです。 さらに、suexec が使用されていない限り、これらのディレクティブは CGI スクリプトで継承される権限も設定します。

MaxRequestsPerChild は、古いプロセスを停止して新しいプロセスを起動することによって、 どの程度の頻度でサーバがプロセスをリサイクルするかを制御します。


mod_access - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_access

説明: | クライアントのホスト名、IP アドレス、その他のクライアント のリクエストの特徴に基づいたアクセス制御機能を提供する
ステータス: | Base
モジュール識別子: | access_module
ソースファイル: | mod_access.c
互換性: | 2.1 より前のバージョンのみで使用可能

概要

mod_access により提供されるディレクティブはサーバの特定の部分への アクセスを制御するために <Directory>, <Files>, <Location> と .htaccess ファイルで使用されます。クライアントのホスト名、IP アドレスや 環境変数として取得された、その他のリクエストの特徴に基づいて アクセス制御を行なうことができます。Allow と Deny ディレクティブは どのようなクライアントにアクセスを 許可する、しないかを指定するために使用されます。一方、 Order ディレクティブは デフォルトのアクセス状態と、 Allow ディレクティブと Deny ディレクティブとのお互いへの影響の仕方を設定します。

ホストによるアクセス制限とパスワードによる認証を同時に 行なうことが可能です。その場合、その二つの制限の関係を指定するために Satisfy ディレクティブを使用します。

一般的には、アクセス制限ディレクティブはすべてのアクセスメソッド (GET, PUT, POST など) に適用されます。そして、ほとんどの場合これが望ましい動作です。 しかし、<Limit> セクションの中にディレクティブを書くことで、 一部のメソッドにのみ制限をかけることもできます。

参照

  • Satisfy
  • Require

Allow ディレクティブ

説明: | サーバのある領域にアクセスできるホストを制御する
構文: | Allow from all|host|env=env-variable [host|env=env-variable] ...
コンテキスト: | ディレクトリ, .htaccess
上書き: | Limit
ステータス: | Base
モジュール: | mod_access

Allow ディレクティブはどのホストが サーバのある領域をアクセスできるかに影響を与えます。 アクセスはホスト名、IP アドレス、IP アドレスの範囲や、 環境変数として取得された、その他のクライアントのリクエストの 特徴によって制御することができます。

このディレクティブの最初の引数は常に from です。 それに続く引数は三つの違った形式があります。Allow from all が指定されていれば、すべてのホストにアクセスを許可し、 アクセス制限は下で説明されているように、 Deny ディレクティブと Order ディレクティブの設定で決まります。 特定のホストやホスト群にのみサーバへのアクセスを許可するためには、 以下のどれかの形式で host を指定することができます:

ドメイン名 (の一部)

例:

Allow from apache.org

この文字列に合うか、これで終わる名前のホストのアクセスが許可されます。 各部分が完全に合うものだけに適用されますので、上の例は foo.apache.org にはマッチしますが、 fooapache.org にはマッチしません。 この設定をすると、Apache は HostnameLookups の設定に関わらず、クライアントの IP アドレスに対して 二重の DNS の逆引きを行ないます。まず IP アドレスに対して DNS の 逆引きを行なってホスト名を得、そのホスト名に対して正引きを 行ない、元の IP アドレスと一致するかを調べます。DNS の正引きと 逆引きが無矛盾かつホスト名が一致するときにのみ アクセスが許可されます。

完全な IP アドレス

例:

Allow from 10.1.2.3

アクセスを許可する IP アドレスです。

IP アドレスの一部

例:

Allow from 10.1

サブネットの制限用の、IP アドレスの最初の一つから三つまでのバイトです。

ネットワーク/ネットマスク の対

例:

Allow from 10.1.0.0/255.255.0.0

ネットワーク a.b.c.d とネットマスク w.x.y.z です。 より細粒度のサブネット制限用です。

ネットワーク/nnn CIDR 指定

例:

Allow from 10.1.0.0/16

ネットマスクが nnn の上位ビットが 1 となっているものからなること以外は前のものと同じです。

注: 最後の三つの例はまったく同じホストに合います。

IPv6 アドレスと IPv6 のサブネットは以下のように指定できます:

Allow from fe80::a00:20ff:fea7:ccea
Allow from fe80::a00:20ff:fea7:ccea/10

Allow ディレクティブの引数の三つ目の形式は、 環境変数 の存在によりアクセスの制御を行なえるようにするものです。 Allow from env=env-variable が指定されていると、環境変数 env-variable が存在した場合にリクエストはアクセスを許可されます。サーバは mod_setenvif のディレクティブにより、クライアントのリクエスト の特徴に基づいて柔軟に環境変数を設定する機能を提供します。 ですから、このディレクティブはクライアントの User-Agent (ブラウザの種類)、Referer や他の HTTP リクエストのヘッダフィールドなどに基づいて アクセス許可をするために使うことができます。

例:

SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in
<Directory /docroot>
Order Deny,Allow
Deny from all
Allow from env=let_me_in
 </Directory>

この場合、user-agent の文字列が KnockKnock/2.0 で始まるブラウザのみがアクセスを許可され、 他のものはアクセスを拒否されます。

Deny ディレクティブ

説明: | サーバがアクセスを拒否するホストを制御する
構文: | Deny from all|host|env=env-variable [host|env=env-variable] ...
コンテキスト: | ディレクトリ, .htaccess
上書き: | Limit
ステータス: | Base
モジュール: | mod_access

このディレクティブはホスト名、IP アドレス、環境変数に基づいてサーバへのアクセスを制限します。 Deny ディレクティブの引数は Allow ディレクティブとまったく同じです。

Order ディレクティブ

説明: | デフォルトのアクセス可能な状態と、Allow と Deny が評価される順番を制御する
構文: | Order ordering
デフォルト: | Order Deny,Allow
コンテキスト: | ディレクトリ, .htaccess
上書き: | Limit
ステータス: | Base
モジュール: | mod_access

Order ディレクティブはデフォルトのアクセスの状態と Allow ディレクティブと Deny ディレクティブが評価される順番を制御します。 Ordering は以下のどれかです。

Deny,Allow
Deny ディレクティブが Allow ディレクティブの前に評価されます。 アクセスはデフォルトで許可されます。Deny ディレクティブに合わないか、Allow ディレクティブに合うクライアントはアクセスを許可されます。
Allow,Deny
Allow ディレクティブが Deny ディレクティブの前に評価されます。 アクセスはデフォルトで拒否されます。Allow ディレクティブに合わないか、Deny ディレクティブに合うクライアントはアクセスを拒否されます。
Mutual-failure
Allow のリストに現れて、 Deny のリストに現れないホストのみがアクセスを許可されます。 この順番付けは Order Allow,Deny と同じ効果を持ち、 その設定の方が好ましいために非推奨となっています。

キーワードはコンマで分離することだけが可能です。 間に空白があってはいけません。どの場合でも、Allow と Deny 文は 全て評価されるということに注意してください。

以下の例では、apache.org ドメインのすべてのホストはアクセスを許可されます。 他のすべてのホストはアクセスを拒否されます。

Order Deny,Allow
Deny from all
Allow from apache.org

次の例では、foo.apache.org サブドメインにあるホスト以外の、 apache.org ドメインのすべてのホストがアクセスを許可されます。 apache.org ドメインでないホストは、デフォルトの状態がアクセス拒否のため、 サーバへのアクセスを拒否されます。

Order Allow,Deny
Allow from apache.org
Deny from foo.apache.org

一方、上の例の Order が Deny,Allow に変わっていれば、すべのホストにアクセスが許可されます。 これは、設定ファイル中の実際の順番に関わらず、 Allow from apache.org が最後に評価されて、 Deny from foo.apache.org を上書きするからです。 apache.org ドメインにないホストも、デフォルトの状態が allow に変化するために、アクセスを許可されます。

Order ディレクティブはデフォルトのアクセスの状態に影響を与えるので、 Allow ディレクティブと Deny ディレクティブが無くても、サーバのアクセスに影響を与えることができます。 たとえば、

<Directory /www>
Order Allow,Deny
 </Directory>

はデフォルトのアクセス状態が deny になるため、 /www ディレクトリへのすべてのアクセスを拒否します。

Order ディレクティブはサーバの設定処理の各段階でだけ アクセスディレクティブの処理の順番を変更します。これは、たとえば、 Order ディレクティブの設定に関わらず、 <Location> セクションの Allow ディレクティブや Deny ディレクティブは、 Directory セクションや .htaccess ファイルの Allow ディレクティブや Deny ディレクティブよりも常に後に評価されるということを意味します。 設定セクションのマージの詳細については、 Directory,Location, Files セクションの動作方法 を参照してください。


mod_actions - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_actions

説明: | メディアタイプやリクエストメソッドに応じて CGI スクリプトを実行する機能を提供
ステータス: | Base
モジュール識別子: | actions_module
ソースファイル: | mod_actions.c

概要

このモジュールには二つのディレクティブがあります。Action ディレクティブは特定のタイプのファイルをリクエストされた場合に CGI スクリプトが実行されるようにします。Script ディレクティブはリクエストで特定のメソッドが使用されたときに CGI スクリプトが実行されるようにします。 これはファイルを処理するスクリプトの実行をずっと簡単にします。

参照

  • mod_cgi
  • CGI による動的コンテンツ
  • Apache のハンドラの使用

Action ディレクティブ

説明: | 特定のハンドラやコンテントタイプに対して CGI を実行するように 設定
構文: | Action action-type cgi-script
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_actions

このディレクティブは action-type がリクエストされたときに cgi-script が実行されるという動作を追加します。cgi-script は ScriptAlias や AddHandler によって CGI スクリプトに設定されたリソースへの URL-path です。 Action-type には handler か MIME コンテントタイプを指定できます。リクエストされたドキュメントの URL とファイルのパスは標準 CGI 環境変数 PATH_INFO と PATH_TRANSLATED を使って伝えられます。

例

# Requests for files of a particular type:
Action image/gif /cgi-bin/images.cgi

# Files of a particular file extension
AddHandler my-file-type .xyz
Action my-file-type /cgi-bin/program.cgi

最初の例では、MIME コンテントタイプが image/gif のファイルへのリクエストは、そのファイルの代わりに指定されたスクリプト /cgi-bin/images.cgi が呼ばれます。

2 番目の例では、拡張子が .xyz のファイルへのリクエストは、 そのファイルの代わりに指定されたスクリプト /cgi-bin/program.cgi が呼ばれます。

参照

  • AddHandler

Script ディレクティブ

説明: | 特定のリクエストメソッドに対して CGI スクリプトを 実行するように設定
構文: | Script method cgi-script
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Base
モジュール: | mod_actions

このディレクティブは method というメソッドを使ってリクエストが行なわれたときに cgi-script を実行するという動作を追加します。 cgi-script は ScriptAlias や AddHandler によって CGI スクリプトに設定されたリソースへの URL-path です。 リクエストされたドキュメントの URL とファイルのパスは標準 CGI 環境変数 PATH_INFO と PATH_TRANSLATED を使って伝えられます。

任意のメソッド名を使用することができます。 メソッド名は大文字小文字を区別します。ですから、 Script PUT と Script put はまったく違った効果になります。

Script コマンドはデフォルトの動作を追加するだけであることに 注意してください。もし CGI スクリプトが呼ばれたり、リクエストされた メソッドを内部で扱うことのできる他のリソースがあれば、それが行なわれます。 GET メソッドの Script は問合せ引数がある場合にのみ (たとえば、foo.html?hi) 呼ばれるということにも注意してください。 そうでない場合は、リクエストは通常通り処理されます。

例

# For <ISINDEX>-style searching
Script GET /cgi-bin/search

# A CGI PUT handler
Script PUT /~bob/put.cgi


mod_alias - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_alias

説明: | ホストファイルシステム上のいろいろな違う場所を ドキュメントツリーにマップする機能と、 URL のリダイレクトを行なう機能を提供する
ステータス: | Base
モジュール識別子: | alias_module
ソースファイル: | mod_alias.c

概要

このモジュールのディレクティブはサーバにリクエストが到着したときに URL の操作や制御をすることを可能にします。Alias ディレクティブと ScriptAlias ディレクティブは URL とファイルシステムのパスをマップするために使用されます。これは DocumentRoot の下にないドキュメントをウェブのドキュメントツリーの一部として 送られるようにします。ScriptAlias ディレクティブにはマップ先のディレクトリが CGI スクリプトのみであることを示すという追加の効果があります。

Redirect ディレクティブは クライアントに違った URL に新しいリクエストを送るように指示します。これは、 リソースが新しい場所に移動したときによく使用されます。

mod_alias は簡単な URL 操作向けに設計されています。 より複雑な操作、クエリーストリングの操作には、mod_rewrite で提供されるツールを使用してください。

参照

  • mod_rewrite
  • URL からファイルシステム上の位置へのマッピング

処理の順番

様々なコンテキスト中での Alias や Redirect は他のディレクティブと 同じように標準の マージ規則 に 従って処理されます。ただし、(例えば <VirtualHost> セクションの中のように) 複数の Alias や Redirect が 同じコンテキスト中に現れた場合は決まった順番で処理されます。

まず、Alias の前にすべての Redirect が処理されます。ですから、Redirect か RedirectMatch にマッチするリクエストには Alias は決して適用されません。次に、Alias と Redirect が設定ファイル中の 順番に適用され、最初にマッチしたものが優先されます。

ですから、二つ以上のディレクティブが同じパスに適用されるときは、 すべてのディレクティブの効果を得るためにはより詳しいパスを先に書く 必要があります。例えば、次の設定は期待通りの動作をします:

Alias /foo/bar /baz
Alias /foo /gaq

しかし、上記の二つのディレクティブの順番が逆になると、 /foo Alias が 常に /foo/bar Alias より先にマッチしますので、後者は 決して適用されることはありません。

Alias ディレクティブ

説明: | URL をファイルシステムの位置にマップする
構文: | Alias URL-path file-path|directory-path
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_alias

Alias ディレクティブはドキュメントを ローカルファイルシステムの DocumentRoot 以外の場所に保管することを可能にします。 URL の (% が復号された) パスが url-path で始まるものは directory-filename で始まるローカルファイルにマップされます。

例

Alias /image /ftp/pub/image

http://myserver/image/foo.gif へのリクエストに対して、サーバは ファイル /ftp/pub/image/foo.gif を返します。

もし url-path の最後に / を書いたなら、サーバがエイリアスを展開するためには、最後の / が必要になることに注意してください。すなわち、Alias /icons/ /usr/local/apache/icons/ というものを使用している場合は、 /icons という url はエイリアスされません。

エイリアスの行き先を含んでいる <Directory> セクションを追加する必要があるかもしれないことに注意してください。 エイリアスの展開は <Directory> セクションを調べる前に行なわれますので、 エイリアスの行き先の <Directory> セクションのみ 効果があります。 (しかし、<Location> セクションはエイリアスが処理される前に実行されますので、 こちらは適用されます。)

特に、Alias を DocumentRoot ディレクトリの外側に配置した場合は、行き先のディレクトリに対する アクセス権限を明示的に制限しなければならないでしょう。

例

Alias /image /ftp/pub/image
<Directory /ftp/pub/image>
Order allow,deny
Allow from all
 </Directory>

AliasMatch ディレクティブ

説明: | 正規表現を使って URL をファイルシステムの位置にマップする
構文: | AliasMatch regex file-path|directory-path
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_alias

このディレクティブは Alias とほとんど同じですが、簡単な先頭からのマッチを行なうのではなく、 標準正規表現を利用します。ここで指定された正規表現と URL のパス が合うかどうかを調べ、合う場合は括弧で括られたマッチを 与えられた文字列で置き換え、それをファイル名として使用します。たとえば、 /icons ディレクトリを使う ためには以下のようなものが使用できます:

AliasMatch ^/icons(.*) /usr/local/apache/icons$1

Redirect ディレクティブ

説明: | クライアントが違う URL を取得するように外部へのリダイレクトを 送る
構文: | Redirect [status] URL-path URL
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_alias

Redirect ディレクティブは古い URL を新しいものへマップします。 新しい URL がクライアントに返されます。そして、 クライアントは新しいアドレスをもう一回取得しようとします。 URL-path (% が復号された) パスで始まるドキュメントへの すべてのリクエストは URL で始まる新しい (% が符号化された) URL へのリダイレクトエラーが返されます。

例

Redirect /service http://foo2.bar.com/service

クライアントは http://myserver/service/foo.txt へのリクエストを行なうと、代わりに http://foo2.bar.com/service/foo.txt をアクセスするように告げられます。

注意

設定ファイル中の順番に関わらず、 Redirect 系のディレクティブは Alias ディレクティブと ScriptAlias ディレクティブよりも優先されます。 また、.htaccess ファイルや <Directory> セクションの中で使われていたとしても、URL-path は相対パスではなく、完全な URL でなければなりません。

もし status 引数が与えられていなければ、リダイレクトは "temporary" (HTTP ステータス 302) になります。これはクライアントに リソースが一時的に移動したということを示します。Status 引数は 他の HTTP のステータスコードを返すために使用することができます:

permanent
永久にリダイレクトをするステータス (301) を返します。 これはリソースが永久に移動したということを意味します。
temp
一時的なリダイレクトステータス (302) を返します。これがデフォルトです。
seeother
"See Other" ステータス (303) を返します。 これはリソースが他のもので置き換えられたことを意味します。
gone
"Gone" ステータス (410) を返します。これはリソースが永久に 削除されたことを意味します。このステータスが使用された場合、 url 引数は省略されなければなりません。

Status の値にステータスコードを数値で与えることで 他のステータスコードも返すことができます。ステータスが 300 と 399 の間にある場合、url 引数は存在していなければいけません。 その他の場合は省略されていなければなりません。ただし、 ステータスは Apache のコードが知っているものである必要があります (http_protocol.c の関数 send_error_response を見てください)。

例:

例

Redirect permanent /one http://example.com/two
Redirect 303 /three http://example.com/other

RedirectMatch ディレクティブ

説明: | 現在の URL への正規表現のマッチにより 外部へのリダイレクトを送る
構文: | RedirectMatch [status] regex URL
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_alias

このディレクティブは Redirect とほとんど同じですが、簡単な先頭からのマッチを行なうのではなく、 標準正規表現を利用します。ここで指定された正規表現と URL-path が合うかどうかを調べ、合う場合は括弧で括られたマッチを 与えられた文字列で置き換え、それをファイル名として使用します。 たとえば、すべての GIF ファイルを別サーバの同様な名前の JPEG ファイルにリダイレクトするには、以下のようなものを使います:

RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg

RedirectPermanent ディレクティブ

説明: | クライアントが違う URL を取得するように外部への永久的な リダイレクトを送る
構文: | RedirectPermanent URL-path URL
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_alias

このディレクティブはクライアントに Redirect が永久的なもの (ステータス 301) であることを知らせます。 Redirect premanent とまったく同じです。

RedirectTemp ディレクティブ

説明: | クライアントが違う URL を取得するように外部への一時的な リダイレクトを送る
構文: | RedirectTemp URL-path URL
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_alias

このディレクティブはクライアントに Redirect が一時的なものである (ステータス 302) ことを知らせます。 Redirect temp とまったく同じです。

ScriptAlias ディレクティブ

説明: | URL をファイルシステムの位置へマップし、マップ先を CGI スクリプトに指定
構文: | ScriptAlias URL-path file-path|directory-path
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_alias

ScriptAlias ディレクティブは、対象ディレクトリに mod_cgi の cgi-script ハンドラで処理される CGI スクリプトがあることを示す以外は Alias ディレクティブと同じ振る舞いをします。 URL の (% が復号された) パスが URL-path で始まるものは ローカルのファイルシステムの フルパスである二番目の引数にマップされます。

例

ScriptAlias /cgi-bin/ /web/cgi-bin/

http://myserver/cgi-bin/foo へのリクエストに対してサーバはスクリプト /web/cgi-bin/foo を実行します。

ScriptAliasMatch ディレクティブ

説明: | URL を正規表現を使ってファイルシステムの位置へマップし、マップ先を CGI スクリプトに指定
構文: | ScriptAliasMatch regex file-path|directory-path
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_alias

このディレクティブは ScriptAlias とほとんど同じですが、簡単な先頭からのマッチを行なうのではなく、 標準正規表現を利用します。ここで指定された正規表現と URL-path が合うかどうかを調べ、合う場合は括弧で括られたマッチを 与えられた文字列で置き換え、それをファイル名として使用します。 たとえば、標準の /cgi-bin を使用するようにするためには、以下のようなものを使います:

ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1


mod_asis - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_asis

説明: | 自分用の HTTP ヘッダの書かれているファイルを送信する
ステータス: | Base
モジュール識別子: | asis_module
ソースファイル: | mod_asis.c

概要

このモジュールはハンドラ send-as-is を提供します。このハンドラは通常の HTTP ヘッダをほとんど追加することなくドキュメントを送信します。

これはサーバからどんな種類のデータを送るときにも使用できます。 Cgi スクリプトや nph スクリプトが無くてもリダイレクトや他の特別な HTTP 応答を送ることができます。

歴史的な理由により、このモジュールは mime タイプ httpd/send-as-is のファイルも処理します。

参照

  • mod_headers
  • mod_cern_meta
  • Apache のハンドラの使用

使用法

サーバ設定ファイルで、ファイルと send-as-is ハンドラを例えば以下のように関連付けてください。

AddHandler send-as-is asis

拡張子が .asis のすべてのファイルの内容は Apache からクライアントへほとんど変更無く送られます。クライアントには HTTP ヘッダが必要ですので、ファイルに書くことを忘れないでください。 Status: ヘッダも必要です。データは 3 桁の HTTP 応答コードと、その後にテキストメッセージが続いたものでなければなりません。

これはクライアントにファイルが移動したことを知らせるために as is (そのまま) で送られるファイルの内容の例です。

Status: 301 Now where did I leave that URL
Location: http://xyz.abc.com/foo/bar.html
Content-type: text/html

<html>
<head>
<title>Lame excuses'R'us</title>
</head>
<body>
<h1>Fred's exceptionally wonderful page has moved to
<a href="http://xyz.abc.com/foo/bar.html">Joe's</a> site.
</h1>
</body>
</html>

注意

注意: サーバはクライアントに返されるデータに常に Date: と Server: ヘッダを追加しますので、 それらがファイルに書かれていてはいけません。 サーバは Last-Modified ヘッダを追加しません。 おそらくはそうすべきでしょうけれど。


mod_auth - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_auth

説明: | テキストファイルを用いたユーザ認証
ステータス: | Base
モジュール識別子: | auth_module
ソースファイル: | mod_auth.c
互換性: | 2.1 より前のバージョンでのみ使用可能

概要

プレインテキストのパスワードファイルとグループファイルを検査して ユーザを探すことで、HTTP 基本認証でアクセス制限できるようにします。 似たような機能で、もっと大きなスケーラビリティを持ったものは、 mod_auth_dbm で提供されています。 また、HTTP ダイジェスト認証は mod_auth_digest で提供されています。

参照

  • Require
  • Satisfy
  • AuthName
  • AuthType

AuthAuthoritative ディレクティブ

説明: | 認証と承認プロセスを、 より低いレベルのモジュールに移行させるかどうかを設定する
構文: | AuthAuthoritative On|Off
デフォルト: | AuthAuthoritative On
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Base
モジュール: | mod_auth

AuthAuthoritative ディレクティブで明示的に Off に設定すると、 与えられた認証ユーザ ID に対してユーザ ID がない またはルールがない場合に、 認証と承認の両方のプロセスが、 より低いレベルのモジュール (Configuration と modules.c ファイルで定義) に移行するようにできます。 ユーザ ID がある、かつまたは、ルールが指定されている場合は、 通常のパスワードとアクセスチェックが適用されて、 認証に失敗すると "Authentication Required" 応答が返されます。

ですから、二つ以上のモジュールのデータベースで同一の ユーザ ID が現われたり、 または、正しい Require ディレクティブが二つ以上のモジュールで現われたりした場合は、 一つ目のモジュールが認定を行って、AuthAuthoritative の設定に関わらず、 アクセスは移行しません。

一般的な使用法は、mod_auth_dbm, mod_auth_msql, mod_auth_anon といったデータベースモジュールの一つと組み合わせることです。 これらのモジュールは多くのユーザ資格検査を提供してくれます。 しかし、少数の (管理者関連の) アクセスは AuthUserFile で良く保護された、より低レベルに移行するようにします。

デフォルトでは、制御は移行しません。そして、未知のユーザ ID や ルールがあっても "Authentication Required" 応答が返されます。 ですから、このディレクティブ設定しないことでシステムの安全を維持できて、また、 NCSA 準拠の挙動を強制できます。

セキュリティ

ユーザが自分自身で作成した .htaccess ファイルで認証できるようにすることの影響を 考慮に入れておいてください。そして、 それが本当に希望の挙動であるかどうかを検討してください。 一般的に言って、mSQL といったデータベースのセキュリティ保護よりも、 単純に一つのファイル .htpasswd のセキュリティを保護する方が容易です。 AuthUserFile と AuthGroupFile は、 ウェブサーバのドキュメントツリーの外側に保管する ようにしてください。保護しようとしているディレクトリ以下には、 置かないで下さい。そうしないと AuthUserFile と AuthGroupFile はダウンロードできてしまいます。

AuthGroupFile ディレクティブ

説明: | 認証に使用するユーザグループの一覧が格納されている、 テキストファイルの名前を設定する
構文: | AuthGroupFile file-path
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Base
モジュール: | mod_auth

AuthGroupFile ディレクティブは、 認証に使用するユーザグループの一覧が格納されている、 テキストファイルの名前を設定します。 file-path はグループファイルへのパスです。 もし絶対パスでなければ、 ServerRoot からの相対パスとして扱われます。

グループファイル各行は、グループ名、コロン、そして スペース区切りでそのメンバーのユーザ名を記述します。

例:

mygroup: bob joe anne

大きなファイルを探索するのは、非常に効率が悪いという点に 注意してください。そのような場合は、 AuthDBMGroupFile の方がずっと良い性能を発揮します。

セキュリティ

AuthGroupFile は、 ウェブサーバのドキュメントツリーの外側に 保管するようにしてください。 保護しようとしているディレクトリ以下には、置かないで下さい。 そうしないと AuthGroupFile は ダウンロードできてしまいます。

AuthUserFile ディレクティブ

説明: | 認証に使用するユーザとパスワードの一覧が格納されている、 テキストファイルの名前を設定する
構文: | AuthUserFile file-path
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Base
モジュール: | mod_auth

AuthUserFile ディレクティブは、 ユーザ認証のためのユーザとパスワードの一覧を格納した テキストファイルの名前を設定します。file-path はユーザファイルへのパスです。 もし絶対パスでなければ (つまり スラッシュで始まらないパスであれば) 、ServerRoot からの相対パスとして扱われます。

ユーザファイルの各行には、ユーザ名、コロン、 暗号化したパスワードを記述します。 同一ユーザ ID が複数回登録された時は、mod_auth は パスワードの検証には最初の登録を使用します。

バイナリ配布の一部としてインストールされるか、 あるいは src/support にある htpasswd ユーティリティで、このパスワードファイルをメインテナンスします。 詳細は man ページをご覧頂くとして、 簡単には:

初期 ID username で、Filename というパスワードファイルを生成します。 次のコマンドを発行するとパスワードが要求されます:

htpasswd -c Filename username

パスワードファイル Filename に、username2 を追加したり修正したりします:

htpasswd Filename username2

(訳注: 非常に多くのユーザを登録すると大きなファイルになりますが) 大きなテキストファイルを検索するのは非常に効率が悪い ということに注意してください。そのような必要のある時は、 AuthDBMUserFile を代わりに使ってください。

セキュリティ

AuthUserFile は、ウェブサーバのドキュメントツリーの外側に保管するようにしてください。 保護しようとしているディレクトリ以下には、置かないで下さい。 そうしないと AuthUserFile は ダウンロードできてしまいます。


mod_auth_anon - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_auth_anon

Description: | Allows "anonymous" user access to authenticated areas
Status: | Extension
Module?dentifier: | auth_anon_module
Source?ile: | mod_auth_anon.c
Compatibility: | Available only in versions prior to 2.1

Summary

This module does access control in a manner similar to anonymous-ftp sites; i.e. have a 'magic' user id 'anonymous' and the email address as a password. These email addresses can be logged.

Combined with other (database) access control methods, this allows for effective user tracking and customization according to a user profile while still keeping the site open for 'unregistered' users. One advantage of using Auth-based user tracking is that, unlike magic-cookies and funny URL pre/postfixes, it is completely browser independent and it allows users to share URLs.

Example

The example below (when combined with the Auth directives of a htpasswd-file based (or GDM, mSQL etc.) base access control system allows users in as 'guests' with the following properties:

  • It insists that the user enters a userID. (Anonymous_NoUserID)
  • It insists that the user enters a password. (Anonymous_MustGiveEmail)
  • The password entered must be a valid email address, ie. contain at least one '@' and a '.'. (Anonymous_VerifyEmail)
  • The userID must be one of anonymous guest www test welcome and comparison is not case sensitive. (Anonymous)
  • And the Email addresses entered in the passwd field are logged to the error log file. (Anonymous_LogEmail)

Excerpt of httpd.conf:

Anonymous_NoUserID off
Anonymous_MustGiveEmail on
Anonymous_VerifyEmail on
Anonymous_LogEmail on
Anonymous anonymous guest www test welcome

AuthName "Use 'anonymous' & Email address for guest entry"
AuthType basic

# An AuthUserFile/AuthDBUserFile/AuthDBMUserFile
# directive must be specified, or use
# Anonymous_Authoritative for public access.
# In the .htaccess for the public directory, add:
<Files *>
Order Deny,Allow
Allow from all

Require valid-user
 </Files>

Anonymous Directive

Description: | Specifies userIDs that are allowed access without password verification
Syntax: | Anonymous user [user] ...
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_anon

A list of one or more 'magic' userIDs which are allowed access without password verification. The userIDs are space separated. It is possible to use the ' and " quotes to allow a space in a userID as well as the \ escape character.

Please note that the comparison is case-IN-sensitive.
I strongly suggest that the magic username 'anonymous' is always one of the allowed userIDs.

Example:

Anonymous anonymous "Not Registered" "I don't know"

This would allow the user to enter without password verification by using the userIDs "anonymous", "AnonyMous", "Not Registered" and "I Don't Know".

Anonymous_Authoritative Directive

Description: | Configures if authorization will fall-through to other methods
Syntax: | Anonymous_Authoritative On|Off
Default: | Anonymous_Authoritative Off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_anon

When set On, there is no fall-through to other authentication methods. So if a userID does not match the values specified in the Anonymous directive, access is denied.

Be sure you know what you are doing when you decide to switch it on. And remember that the order in which the Authentication modules are queried is defined in the modules.c files at compile time.

Anonymous_LogEmail Directive

Description: | Sets whether the password entered will be logged in the error log
Syntax: | Anonymous_LogEmail On|Off
Default: | Anonymous_LogEmail On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_anon

When set On, the default, the 'password' entered (which hopefully contains a sensible email address) is logged in the error log.

Anonymous_MustGiveEmail Directive

Description: | Specifies whether blank passwords are allowed
Syntax: | Anonymous_MustGiveEmail On|Off
Default: | Anonymous_MustGiveEmail On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_anon

Specifies whether the user must specify an email address as the password. This prohibits blank passwords.

Anonymous_NoUserID Directive

Description: | Sets whether the userID field may be empty
Syntax: | Anonymous_NoUserID On|Off
Default: | Anonymous_NoUserID Off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_anon

When set On, users can leave the userID (and perhaps the password field) empty. This can be very convenient for MS-Explorer users who can just hit return or click directly on the OK button; which seems a natural reaction.

Anonymous_VerifyEmail Directive

Description: | Sets whether to check the password field for a correctly formatted email address
Syntax: | Anonymous_VerifyEmail On|Off
Default: | Anonymous_VerifyEmail Off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_anon

When set On the 'password' entered is checked for at least one '@' and a '.' to encourage users to enter valid email addresses (see the above Anonymous_LogEmail).


mod_auth_dbm - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_auth_dbm

Description: | Provides for user authentication using DBM files
Status: | Extension
Module?dentifier: | auth_dbm_module
Source?ile: | mod_auth_dbm.c
Compatibility: | Available only in versions prior to 2.1

Summary

This module provides for HTTP Basic Authentication, where the usernames and passwords are stored in DBM type database files. It is an alternative to the plain text password files provided by mod_auth.

See also

  • AuthName
  • AuthType
  • Require
  • Satisfy

AuthDBMAuthoritative Directive

Description: | Sets whether authentication and authorization will be passwed on to lower level modules
Syntax: | AuthDBMAuthoritative On|Off
Default: | AuthDBMAuthoritative On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_dbm

Setting the AuthDBMAuthoritative directive explicitly to Off allows for both authentication and authorization to be passed on to lower level modules (as defined in the modules.c files) if there is no userID or rule matching the supplied userID. If there is a userID and/or rule specified; the usual password and access checks will be applied and a failure will give an "Authentication Required" reply.

So if a userID appears in the database of more than one module; or if a valid Require directive applies to more than one module; then the first module will verify the credentials; and no access is passed on; regardless of the AuthDBMAuthoritative setting.

A common use for this is in conjunction with one of the basic auth modules; such as mod_auth. Whereas this DBM module supplies the bulk of the user credential checking; a few (administrator) related accesses fall through to a lower level with a well protected .htpasswd file.

By default, control is not passed on and an unknown userID or rule will result in an "Authentication Required" reply. Not setting it thus keeps the system secure and forces an NCSA compliant behaviour.

Security:

Do consider the implications of allowing a user to allow fall-through in his .htaccess file; and verify that this is really what you want; Generally it is easier to just secure a single .htpasswd file, than it is to secure a database which might have more access interfaces.

AuthDBMGroupFile Directive

Description: | Sets the name of the database file containing the list of user groups for authentication
Syntax: | AuthDBMGroupFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_dbm

The AuthDBMGroupFile directive sets the name of a DBM file containing the list of user groups for user authentication. File-path is the absolute path to the group file.

The group file is keyed on the username. The value for a user is a comma-separated list of the groups to which the users belongs. There must be no whitespace within the value, and it must never contain any colons.

Security: make sure that the AuthDBMGroupFile is stored outside the document tree of the web-server; do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthDBMGroupFile unless otherwise protected.

Combining Group and Password DBM files: In some cases it is easier to manage a single database which contains both the password and group details for each user. This simplifies any support programs that need to be written: they now only have to deal with writing to and locking a single DBM file. This can be accomplished by first setting the group and password files to point to the same DBM:

AuthDBMGroupFile /www/userbase
AuthDBMUserFile /www/userbase

The key for the single DBM is the username. The value consists of

Unix Crypt-ed Password:List of Groups[:(ignored)]

The password section contains the encrypted password as before. This is followed by a colon and the comma separated list of groups. Other data may optionally be left in the DBM file after another colon; it is ignored by the authentication module. This is what www.telescope.org uses for its combined password and group database.

AuthDBMType Directive

Description: | Sets the type of database file that is used to store passwords
Syntax: | AuthDBMType default|SDBM|GDBM|NDBM|DB
Default: | AuthDBMType default
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_dbm
Compatibility: | Available in version 2.0.30 and later.

Sets the type of database file that is used to store the passwords. The default database type is determined at compile time. The availability of other types of database files also depends on compile-time settings.

It is crucial that whatever program you use to create your password files is configured to use the same type of database.

AuthDBMUserFile Directive

Description: | Sets thename of a database file containing the list of users and passwords for authentication
Syntax: | AuthDBMUserFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_dbm

The AuthDBMUserFile directive sets the name of a DBM file containing the list of users and passwords for user authentication. File-path is the absolute path to the user file.

The user file is keyed on the username. The value for a user is the encrypted password, optionally followed by a colon and arbitrary data. The colon and the data following it will be ignored by the server.

Security:

Make sure that the AuthDBMUserFile is stored outside the document tree of the web-server; do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthDBMUserFile.

Important compatibility note: The implementation of "dbmopen" in the apache modules reads the string length of the hashed values from the DBM data structures, rather than relying upon the string being NULL-appended. Some applications, such as the Netscape web server, rely upon the string being NULL-appended, so if you are having trouble using DBM files interchangeably between applications this may be a part of the problem.

A perl script called dbmmanage is included with Apache. This program can be used to create and update DBM format password files for use with this module.


mod_auth_digest - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_auth_digest

Description: | User authentication using MD5 Digest Authentication.
Status: | Experimental
Module?dentifier: | auth_digest_module
Source?ile: | mod_auth_digest.c

Summary

This module implements HTTP Digest Authentication. However, it has not been extensively tested and is therefore marked experimental.

See also

  • AuthName
  • AuthType
  • Require
  • Satisfy

Using Digest Authentication

Using MD5 Digest authentication is very simple. Simply set up authentication normally, using AuthType Digest and AuthDigestFile instead of the normal AuthType Basic and AuthUserFile; also, replace any AuthGroupFile with AuthDigestGroupFile. Then add a AuthDigestDomain directive containing at least the root URI(s) for this protection space.

Appropriate user (text) files can be created using the htdigest tool.

Example:

<Location /private/>
AuthType Digest
AuthName "private area"
AuthDigestDomain /private/ http://mirror.my.dom/private2/
AuthDigestFile /web/auth/.digest_pw
Require valid-user
 </Location>

Note

Digest authentication provides a more secure password system than Basic authentication, but only works with supporting browsers. As of November 2002, the major browsers that support digest authentication are Opera, MS Internet Explorer (fails when used with a query string - see "Working with MS Internet Explorer" below for a workaround), Amaya, Mozilla and Netscape since version 7. Since digest authentication is not as widely implemented as basic authentication, you should use it only in controlled environments.

Working with MS Internet Explorer

The Digest authentication implementation in current Internet Explorer implementations has known issues, namely that GET requests with a query string are not RFC compliant. There are a few ways to work around this issue.

The first way is to use POST requests instead of GET requests to pass data to your program. This method is the simplest approach if your application can work with this limitation.

Since version 2.0.51 Apache also provides a workaround in the AuthDigestEnableQueryStringHack environment variable. If AuthDigestEnableQueryStringHack is set for the request, Apache will take steps to work around the MSIE bug and remove the request URI from the digest comparison. Using this method would look similar to the following.

Using Digest Authentication with MSIE:

BrowserMatch "MSIE" AuthDigestEnableQueryStringHack=On

See the BrowserMatch directive for more details on conditionally setting environment variables

AuthDigestAlgorithm Directive

Description: | Selects the algorithm used to calculate the challenge and response hases in digest authentication
Syntax: | AuthDigestAlgorithm MD5|MD5-sess
Default: | AuthDigestAlgorithm MD5
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestAlgorithm directive selects the algorithm used to calculate the challenge and response hashes.

MD5-sess is not correctly implemented yet.

AuthDigestDomain Directive

Description: | URIs that are in the same protection space for digest authentication
Syntax: | AuthDigestDomain URI [URI] ...
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestDomain directive allows you to specify one or more URIs which are in the same protection space (i.e. use the same realm and username/password info). The specified URIs are prefixes, i.e. the client will assume that all URIs "below" these are also protected by the same username/password. The URIs may be either absolute URIs (i.e. inluding a scheme, host, port, etc) or relative URIs.

This directive should always be specified and contain at least the (set of) root URI(s) for this space. Omitting to do so will cause the client to send the Authorization header for every request sent to this server. Apart from increasing the size of the request, it may also have a detrimental effect on performance if AuthDigestNcCheck is on.

The URIs specified can also point to different servers, in which case clients (which understand this) will then share username/password info across multiple servers without prompting the user each time.

AuthDigestFile Directive

Description: | Location of the text file containing the list of users and encoded passwords for digest authentication
Syntax: | AuthDigestFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestFile directive sets the name of a textual file containing the list of users and encoded passwords for digest authentication. File-path is the absolute path to the user file.

The digest file uses a special format. Files in this format can be created using the htdigest utility found in the support/ subdirectory of the Apache distribution.

AuthDigestGroupFile Directive

Description: | Name of the text file containing the list of groups for digest authentication
Syntax: | AuthDigestGroupFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestGroupFile directive sets the name of a textual file containing the list of groups and their members (user names). File-path is the absolute path to the group file.

Each line of the group file contains a groupname followed by a colon, followed by the member usernames separated by spaces. Example:

mygroup: bob joe anne

Note that searching large text files is very inefficient.

Security:

Make sure that the AuthGroupFile is stored outside the document tree of the web-server; do not put it in the directory that it protects. Otherwise, clients may be able to download the AuthGroupFile.

AuthDigestNcCheck Directive

Description: | Enables or disables checking of the nonce-count sent by the server
Syntax: | AuthDigestNcCheck On|Off
Default: | AuthDigestNcCheck Off
Context: | server config
Status: | Experimental
Module: | mod_auth_digest
Not implemented yet.

AuthDigestNonceFormat Directive

Description: | Determines how the nonce is generated
Syntax: | AuthDigestNonceFormat format
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest
Not implemented yet.

AuthDigestNonceLifetime Directive

Description: | How long the server nonce is valid
Syntax: | AuthDigestNonceLifetime seconds
Default: | AuthDigestNonceLifetime 300
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestNonceLifetime directive controls how long the server nonce is valid. When the client contacts the server using an expired nonce the server will send back a 401 with stale=true. If seconds is greater than 0 then it specifies the amount of time for which the nonce is valid; this should probably never be set to less than 10 seconds. If seconds is less than 0 then the nonce never expires.

AuthDigestQop Directive

Description: | Determines the quality-of-protection to use in digest authentication
Syntax: | AuthDigestQop none|auth|auth-int [auth|auth-int]
Default: | AuthDigestQop auth
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestQop directive determines the quality-of-protection to use. auth will only do authentication (username/password); auth-int is authentication plus integrity checking (an MD5 hash of the entity is also computed and checked); none will cause the module to use the old RFC-2069 digest algorithm (which does not include integrity checking). Both auth and auth-int may be specified, in which the case the browser will choose which of these to use. none should only be used if the browser for some reason does not like the challenge it receives otherwise.

auth-int is not implemented yet.

AuthDigestShmemSize Directive

Description: | The amount of shared memory to allocate for keeping track of clients
Syntax: | AuthDigestShmemSize size
Default: | AuthDigestShmemSize 1000
Context: | server config
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestShmemSize directive defines the amount of shared memory, that will be allocated at the server startup for keeping track of clients. Note that the shared memory segment cannot be set less than the space that is neccessary for tracking at least one client. This value is dependant on your system. If you want to find out the exact value, you may simply set AuthDigestShmemSize to the value of 0 and read the error message after trying to start the server.

The size is normally expressed in Bytes, but you may let the number follow a K or an M to express your value as KBytes or MBytes. For example, the following directives are all equivalent:

AuthDigestShmemSize 1048576
AuthDigestShmemSize 1024K
AuthDigestShmemSize 1M


mod_auth_ldap - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_auth_ldap

Description: | Allows an LDAP directory to be used to store the database for HTTP Basic authentication.
Status: | Experimental
Module?dentifier: | auth_ldap_module
Source?ile: | mod_auth_ldap.c
Compatibility: | Available in version 2.0.41 and later

Summary

mod_auth_ldap supports the following features:

  • Known to support the OpenLDAP SDK (both 1.x and 2.x), Novell LDAP SDK and the iPlanet (Netscape) SDK.
  • Complex authorization policies can be implemented by representing the policy with LDAP filters.
  • Support for Microsoft FrontPage allows FrontPage users to control access to their webs, while retaining LDAP for user authentication.
  • Uses extensive caching of LDAP operations via mod_ldap.
  • Support for LDAP over SSL (requires the Netscape SDK) or TLS (requires the OpenLDAP 2.x SDK or Novell LDAP SDK).

See also

  • mod_ldap

Contents

  • Operation
    • The Authentication Phase
    • The Authorization Phase
  • The require Directives
    • require valid-user
    • require user
    • require group
    • require dn
  • Examples
  • Using TLS
  • Using SSL
  • Using Microsoft FrontPage with mod_auth_ldap
    • How It Works
    • Caveats

Operation

There are two phases in granting access to a user. The first phase is authentication, in which mod_auth_ldap verifies that the user's credentials are valid. This also called the search/bind phase. The second phase is authorization, in which mod_auth_ldap determines if the authenticated user is allowed access to the resource in question. This is also known as the compare phase.

The Authentication Phase

During the authentication phase, mod_auth_ldap searches for an entry in the directory that matches the username that the HTTP client passes. If a single unique match is found, then mod_auth_ldap attempts to bind to the directory server using the DN of the entry plus the password provided by the HTTP client. Because it does a search, then a bind, it is often referred to as the search/bind phase. Here are the steps taken during the search/bind phase.

  1. Generate a search filter by combining the attribute and filter provided in the AuthLDAPURL directive with the username passed by the HTTP client.
  2. Search the directory using the generated filter. If the search does not return exactly one entry, deny or decline access.
  3. Fetch the distinguished name of the entry retrieved from the search and attempt to bind to the LDAP server using the DN and the password passed by the HTTP client. If the bind is unsuccessful, deny or decline access.

The following directives are used during the search/bind phase

AuthLDAPURL | Specifies the LDAP server, the base DN, the attribute to use in the search, as well as the extra search filter to use.
AuthLDAPBindDN | An optional DN to bind with during the search phase.
AuthLDAPBindPassword | An optional password to bind with during the search phase.

The Authorization Phase

During the authorization phase, mod_auth_ldap attempts to determine if the user is authorized to access the resource. Many of these checks require mod_auth_ldap to do a compare operation on the LDAP server. This is why this phase is often referred to as the compare phase. mod_auth_ldap accepts the following Require directives to determine if the credentials are acceptable:

  • Grant access if there is a require valid-user directive.
  • Grant access if there is a require user directive, and the username in the directive matches the username passed by the client.
  • Grant access if there is a require dn directive, and the DN in the directive matches the DN fetched from the LDAP directory.
  • Grant access if there is a require group directive, and the DN fetched from the LDAP directory (or the username passed by the client) occurs in the LDAP group.
  • otherwise, deny or decline access

mod_auth_ldap uses the following directives during the compare phase:

AuthLDAPURL | The attribute specified in the URL is used in compare operations for the require user operation.
AuthLDAPCompareDNOnServer | Determines the behavior of the require dn directive.
AuthLDAPGroupAttribute | Determines the attribute to use for comparisons in the require group directive.
AuthLDAPGroupAttributeIsDN | Specifies whether to use the user DN or the username when doing comparisons for the require group directive.

The require Directives

Apache's Require directives are used during the authorization phase to ensure that a user is allowed to access a resource.

require valid-user

If this directive exists, mod_auth_ldap grants access to any user that has successfully authenticated during the search/bind phase.

require user

The require user directive specifies what usernames can access the resource. Once mod_auth_ldap has retrieved a unique DN from the directory, it does an LDAP compare operation using the username specified in the require user to see if that username is part of the just-fetched LDAP entry. Multiple users can be granted access by putting multiple usernames on the line, separated with spaces. If a username has a space in it, then it must be surrounded with double quotes. Multiple users can also be granted access by using multiple require user directives, with one user per line. For example, with a AuthLDAPURL of ldap://ldap/o=Airius?cn (i.e., cn is used for searches), the following require directives could be used to restrict access:

require user "Barbara Jenson"
require user "Fred User"
require user "Joe Manager"

Because of the way that mod_auth_ldap handles this directive, Barbara Jenson could sign on as Barbara Jenson, Babs Jenson or any other cn that she has in her LDAP entry. Only the single require user line is needed to support all values of the attribute in the user's entry.

If the uid attribute was used instead of the cn attribute in the URL above, the above three lines could be condensed to

require user bjenson fuser jmanager

require group

This directive specifies an LDAP group whose members are allowed access. It takes the distinguished name of the LDAP group. Note: Do not surround the group name with quotes. For example, assume that the following entry existed in the LDAP directory:

dn: cn=Administrators, o=Airius
objectClass: groupOfUniqueNames
uniqueMember: cn=Barbara Jenson, o=Airius
uniqueMember: cn=Fred User, o=Airius

The following directive would grant access to both Fred and Barbara:

require group cn=Administrators, o=Airius

Behavior of this directive is modified by the AuthLDAPGroupAttribute and AuthLDAPGroupAttributeIsDN directives.

require dn

The require dn directive allows the administrator to grant access based on distinguished names. It specifies a DN that must match for access to be granted. If the distinguished name that was retrieved from the directory server matches the distinguished name in the require dn, then authorization is granted. Note: do not surround the distinguished name with quotes.

The following directive would grant access to a specific DN:

require dn cn=Barbara Jenson, o=Airius

Behavior of this directive is modified by the AuthLDAPCompareDNOnServer directive.

Examples

  • Grant access to anyone who exists in the LDAP directory, using their UID for searches.

    AuthLDAPURL ldap://ldap1.airius.com:389/ou=People, o=Airius?uid?sub?(objectClass=*)
    require valid-user

  • The next example is the same as above; but with the fields that have useful defaults omitted. Also, note the use of a redundant LDAP server.

    AuthLDAPURL ldap://ldap1.airius.com ldap2.airius.com/ou=People, o=Airius
    require valid-user

  • The next example is similar to the previous one, but is uses the common name instead of the UID. Note that this could be problematical if multiple people in the directory share the same cn, because a search on cn must return exactly one entry. That's why this approach is not recommended: it's a better idea to choose an attribute that is guaranteed unique in your directory, such as uid.

    AuthLDAPURL ldap://ldap.airius.com/ou=People, o=Airius?cn
    require valid-user

  • Grant access to anybody in the Administrators group. The users must authenticate using their UID.

    AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid
    require group cn=Administrators, o=Airius

  • The next example assumes that everyone at Airius who carries an alphanumeric pager will have an LDAP attribute of qpagePagerID. The example will grant access only to people (authenticated via their UID) who have alphanumeric pagers:

    AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(qpagePagerID=*)
    require valid-user

  • The next example demonstrates the power of using filters to accomplish complicated administrative requirements. Without filters, it would have been necessary to create a new LDAP group and ensure that the group's members remain synchronized with the pager users. This becomes trivial with filters. The goal is to grant access to anyone who has a filter, plus grant access to Joe Manager, who doesn't have a pager, but does need to access the same resource:

    AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(|(qpagePagerID=*)(uid=jmanager))
    require valid-user

    This last may look confusing at first, so it helps to evaluate what the search filter will look like based on who connects, as shown below. The text in blue is the part that is filled in using the attribute specified in the URL. The text in red is the part that is filled in using the filter specified in the URL. The text in green is filled in using the information that is retrieved from the HTTP client. If Fred User connects as fuser, the filter would look like

    (&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))

    The above search will only succeed if fuser has a pager. When Joe Manager connects as jmanager, the filter looks like

    (&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))

    The above search will succeed whether jmanager has a pager or not.

Using TLS

To use TLS, see the mod_ldap directives LDAPTrustedCA and LDAPTrustedCAType.

Using SSL

To use SSL, see the mod_ldap directives LDAPTrustedCA and LDAPTrustedCAType.

To specify a secure LDAP server, use ldaps:// in the AuthLDAPURL directive, instead of ldap://.

Using Microsoft FrontPage with mod_auth_ldap

Normally, FrontPage uses FrontPage-web-specific user/group files (i.e., the mod_auth module) to handle all authentication. Unfortunately, it is not possible to just change to LDAP authentication by adding the proper directives, because it will break the Permissions forms in the FrontPage client, which attempt to modify the standard text-based authorization files.

Once a FrontPage web has been created, adding LDAP authentication to it is a matter of adding the following directives to every .htaccess file that gets created in the web

AuthLDAPURL            "the url"
AuthLDAPAuthoritative  off
AuthLDAPFrontPageHack  on

AuthLDAPAuthoritative must be off to allow mod_auth_ldap to decline group authentication so that Apache will fall back to file authentication for checking group membership. This allows the FrontPage-managed group file to be used.

How It Works

FrontPage restricts access to a web by adding the require valid-user directive to the .htaccess files. If AuthLDAPFrontPageHack is not on, the require valid-user directive will succeed for any user who is valid as far as LDAP is concerned. This means that anybody who has an entry in the LDAP directory is considered a valid user, whereas FrontPage considers only those people in the local user file to be valid. The purpose of the hack is to force Apache to consult the local user file (which is managed by FrontPage) - instead of LDAP - when handling the require valid-user directive.

Once directives have been added as specified above, FrontPage users will be able to perform all management operations from the FrontPage client.

Caveats

  • When choosing the LDAP URL, the attribute to use for authentication should be something that will also be valid for putting into a mod_auth user file. The user ID is ideal for this.
  • When adding users via FrontPage, FrontPage administrators should choose usernames that already exist in the LDAP directory (for obvious reasons). Also, the password that the administrator enters into the form is ignored, since Apache will actually be authenticating against the password in the LDAP database, and not against the password in the local user file. This could cause confusion for web administrators.
  • Apache must be compiled with mod_auth in order to use FrontPage support. This is because Apache will still use the mod_auth group file for determine the extent of a user's access to the FrontPage web.
  • The directives must be put in the .htaccess files. Attempting to put them inside <Location> or <Directory> directives won't work. This is because mod_auth_ldap has to be able to grab the AuthUserFile directive that is found in FrontPage .htaccess files so that it knows where to look for the valid user list. If the mod_auth_ldap directives aren't in the same .htaccess file as the FrontPage directives, then the hack won't work, because mod_auth_ldap will never get a chance to process the .htaccess file, and won't be able to find the FrontPage-managed user file.

AuthLDAPAuthoritative Directive

Description: | Prevent other authentication modules from authenticating the user if this one fails
Syntax: | AuthLDAPAuthoritative on|off
Default: | AuthLDAPAuthoritative on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

Set to off if this module should let other authentication modules attempt to authenticate the user, should authentication with this module fail. Control is only passed on to lower modules if there is no DN or rule that matches the supplied user name (as passed by the client).

AuthLDAPBindDN Directive

Description: | Optional DN to use in binding to the LDAP server
Syntax: | AuthLDAPBindDN distinguished-name
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

An optional DN used to bind to the server when searching for entries. If not provided, mod_auth_ldap will use an anonymous bind.

AuthLDAPBindPassword Directive

Description: | Password used in conjuction with the bind DN
Syntax: | AuthLDAPBindPassword password
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

A bind password to use in conjunction with the bind DN. Note that the bind password is probably sensitive data, and should be properly protected. You should only use the AuthLDAPBindDN and AuthLDAPBindPassword if you absolutely need them to search the directory.

AuthLDAPCharsetConfig Directive

Description: | Language to charset conversion configuration file
Syntax: | AuthLDAPCharsetConfig file-path
Context: | server config
Status: | Experimental
Module: | mod_auth_ldap

The AuthLDAPCharsetConfig directive sets the location of the language to charset conversion configuration file. File-path is relative to the ServerRoot. This file specifies the list of language extensions to character sets. Most administrators use the provided charset.conv file, which associates common language extensions to character sets.

The file contains lines in the following format:

Language-Extension charset [Language-String] ...

The case of the extension does not matter. Blank lines, and lines beginning with a hash character (#) are ignored.

AuthLDAPCompareDNOnServer Directive

Description: | Use the LDAP server to compare the DNs
Syntax: | AuthLDAPCompareDNOnServer on|off
Default: | AuthLDAPCompareDNOnServer on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

When set, mod_auth_ldap will use the LDAP server to compare the DNs. This is the only foolproof way to compare DNs. mod_auth_ldap will search the directory for the DN specified with the require dn directive, then, retrieve the DN and compare it with the DN retrieved from the user entry. If this directive is not set, mod_auth_ldap simply does a string comparison. It is possible to get false negatives with this approach, but it is much faster. Note the mod_ldap cache can speed up DN comparison in most situations.

AuthLDAPDereferenceAliases Directive

Description: | When will the module de-reference aliases
Syntax: | AuthLDAPDereferenceAliases never|searching|finding|always
Default: | AuthLDAPDereferenceAliases Always
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

This directive specifies when mod_auth_ldap will de-reference aliases during LDAP operations. The default is always.

AuthLDAPEnabled Directive

Description: | Turn on or off LDAP authentication
Syntax: | AuthLDAPEnabled on|off
Default: | AuthLDAPEnabled on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

Set to off to disable mod_auth_ldap in certain directories. This is useful if you have mod_auth_ldap enabled at or near the top of your tree, but want to disable it completely in certain locations.

AuthLDAPFrontPageHack Directive

Description: | Allow LDAP authentication to work with MS FrontPage
Syntax: | AuthLDAPFrontPageHack on|off
Default: | AuthLDAPFrontPageHack off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

See the section on using Microsoft FrontPage with mod_auth_ldap.

AuthLDAPGroupAttribute Directive

Description: | LDAP attributes used to check for group membership
Syntax: | AuthLDAPGroupAttribute attribute
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

This directive specifies which LDAP attributes are used to check for group membership. Multiple attributes can be used by specifying this directive multiple times. If not specified, then mod_auth_ldap uses the member and uniquemember attributes.

AuthLDAPGroupAttributeIsDN Directive

Description: | Use the DN of the client username when checking for group membership
Syntax: | AuthLDAPGroupAttributeIsDN on|off
Default: | AuthLDAPGroupAttributeIsDN on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

When set on, this directive says to use the distinguished name of the client username when checking for group membership. Otherwise, the username will be used. For example, assume that the client sent the username bjenson, which corresponds to the LDAP DN cn=Babs Jenson, o=Airius. If this directive is set, mod_auth_ldap will check if the group has cn=Babs Jenson, o=Airius as a member. If this directive is not set, then mod_auth_ldap will check if the group has bjenson as a member.

AuthLDAPRemoteUserIsDN Directive

Description: | Use the DN of the client username to set the REMOTE_USER environment variable
Syntax: | AuthLDAPRemoteUserIsDN on|off
Default: | AuthLDAPRemoteUserIsDN off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

If this directive is set to on, the value of the REMOTE_USER environment variable will be set to the full distinguished name of the authenticated user, rather than just the username that was passed by the client. It is turned off by default.

AuthLDAPUrl Directive

Description: | URL specifying the LDAP search parameters
Syntax: | AuthLDAPUrl url
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

An RFC 2255 URL which specifies the LDAP search parameters to use. The syntax of the URL is

ldap://host:port/basedn?attribute?scope?filter

ldap
For regular ldap, use the string ldap. For secure LDAP, use ldaps instead. Secure LDAP is only available if Apache was linked to an LDAP library with SSL support.
host:port

The name/port of the ldap server (defaults to localhost:389 for ldap, and localhost:636 for ldaps). To specify multiple, redundant LDAP servers, just list all servers, separated by spaces. mod_auth_ldap will try connecting to each server in turn, until it makes a successful connection.

Once a connection has been made to a server, that connection remains active for the life of the httpd process, or until the LDAP server goes down.

If the LDAP server goes down and breaks an existing connection, mod_auth_ldap will attempt to re-connect, starting with the primary server, and trying each redundant server in turn. Note that this is different than a true round-robin search.

basedn
The DN of the branch of the directory where all searches should start from. At the very least, this must be the top of your directory tree, but could also specify a subtree in the directory.
attribute
The attribute to search for. Although RFC 2255 allows a comma-separated list of attributes, only the first attribute will be used, no matter how many are provided. If no attributes are provided, the default is to use uid. It's a good idea to choose an attribute that will be unique across all entries in the subtree you will be using.
scope
The scope of the search. Can be either one or sub. Note that a scope of base is also supported by RFC 2255, but is not supported by this module. If the scope is not provided, or if base scope is specified, the default is to use a scope of sub.
filter
A valid LDAP search filter. If not provided, defaults to (objectClass=*), which will search for all objects in the tree. Filters are limited to approximately 8000 characters (the definition of MAX_STRING_LEN in the Apache source code). This should be than sufficient for any application.

When doing searches, the attribute, filter and username passed by the HTTP client are combined to create a search filter that looks like (&(filter)(attribute=username)).

For example, consider an URL of ldap://ldap.airius.com/o=Airius?cn?sub?(posixid=*). When a client attempts to connect using a username of Babs Jenson, the resulting search filter will be (&(posixid=*)(cn=Babs Jenson)).

See above for examples of AuthLDAPURL URLs.


mod_autoindex - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_autoindex

説明: | Unix の ls コマンドや Win32 の dir シェルコマンドに似た ディレクトリインデックスを生成する
ステータス: | Base
モジュール識別子: | autoindex_module
ソースファイル: | mod_autoindex.c

概要

ディレクトリのインデックスは二つの情報源のうちの 一つから生成できます:

  • 普通は index.html と呼ばれる ユーザによって書かれたファイル。 DirectoryIndex ディレクティブでこのファイル名を設定します。 これは mod_dir で制御されます。
  • もしくは、サーバによって生成された一覧。 その他のディレクティブでこの一覧の書式を制御します。 AddIcon, AddIconByEncoding と AddIconByType を使うことで、様々なファイルタイプに対してアイコン一覧を セットします。つまり、リストされたファイル毎に、 ファイルにマッチした一番最初のアイコンが表示されます。 これらは mod_autoindex で制御されます。

望むならば、自動インデックス生成を完全に除去 (あるいは置換) できるように、この二つの機能は分離されています。

自動インデックス生成は Options +Indexes を使うことで有効になります。詳細については、 Options ディレクティブをご覧下さい。

もし FancyIndexingオプションが IndexOptions ディレクティブに与えられているならば、 列の先頭は表示の順番を制御するリンクになります。 先頭のリンクを選択すると、一覧は再生成されて その列の値でソートされます。 同じ先頭を続けて選択すると、交互に昇順と降順とになります。 これらの列の先頭のリンクは、 IndexOptions ディレクティブの SuppressColumnSorting オプションで消すことができます。

"Size" でソートした場合は、用いられるのは 実際のファイルのサイズであって、 表示の値ではないことに注意してください - たとえ両方ともが "1K" と表示されていたとしても、 1010 バイトのファイルは必ず 1011 バイトのファイルよりも前 (昇順の場合) に表示されます。

Autoindex リクエストクエリー引数

Apache 2.0.23 で、 コラムソートのためにクエリー引数を再編成して、 新しいクエリーオプションのグループを導入しました。 出力に対するクライアントのすべての制御を効率的に抹消 できるように、 IndexOptions IgnoreClient が導入されました。

コラムソートのヘッダそれ自体が、 下記のソートクエリーオプションを付加する 自分自身を参照するリンクです。 下記のオプションのどれでも、 ディレクトリリソースへのリクエストに加えることができます。

  • C=N は、ファイル名でソートします。
  • C=M は、更新日時、 ディレクトリ、ファイル名の順でソートします。
  • C=S は、サイズ、 ディレクトリ、ファイル名の順でソートします。
  • C=D は、説明、 ディレクトリ、ファイル名の順でソートします。
  • O=A は、昇順で表をソートします。
  • O=D は、降順で表をソートします。
  • F=0 は、単純な表の書式にします。 (FancyIndex ではありません。)
  • F=1 は、FancyIndex 表示の表の書式にします。
  • F=2 は、表を HTML のテーブルを使った FancyIndex の書式にします。
  • V=0 は、バージョンによるソートを無効にします。
  • V=1 は、バージョンによるソートを有効にします。
  • P=pattern は、与えられた pattern に適合したファイルのみを表示します。

"P (パターンの P)" クエリー引数は、 通常の IndexIgnore ディレクティブが処理された後に検査され、 ファイル名全てが、他の autoindex リスト処理と同様の判定基準下に置かれ続ける ことに注意してください。 mod_autoindex のクエリー引数パーサ (解析) は、 認識不能なオプションにぶつかると即座に停止します。 クエリー引数は上の表に従って 正しい形式になっていなければなりません。

下の単純な例は、これらのクエリーオプションを 表します。これをそのまま切り取って HEADER.html ファイルに保存することもできます。 mod_autoindex が X=Go 入力にぶつかる前に 引数が全て解釈されるように、 未知の引数 "X" はリストの最後に置かれています。

<form action="" method="get">
Show me a <select name="F">
<option value="0"> Plain list</option>
<option value="1" selected="selected"> Fancy list</option>
<option value="2"> Table list</option>
 </select>
Sorted by <select name="C">
<option value="N" selected="selected"> Name</option>
<option value="M"> Date Modified</option>
<option value="S"> Size</option>
<option value="D"> Description</option>
 </select>
<select name="O">
<option value="A" selected="selected"> Ascending</option>
<option value="D"> Descending</option>
 </select>
<select name="V">
<option value="0" selected="selected"> in Normal order</option>
<option value="1"> in Version order</option>
 </select>
Matching <input type="text" name="P" value="*" />
<input type="submit" name="X" value="Go" />
 </form>

AddAlt ディレクティブ

説明: | アイコンの代わりに 表示される、ファイル名で選択された代替テキスト
構文: | AddAlt string file [file] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

AddAlt は、FancyIndexing において、アイコンの代わりに表示する代替テキストを提供します。 file は、説明するファイルのファイル拡張子、 ファイル名の一部、ワイルドカード表現、完全なファイル名の どれかになります。 string に空白がある場合は引用符 (" か ') で囲む必要があります。 この文字列は、クライアントが画像を表示できない場合や 画像のロードを無効にしている場合や アイコンの取得に失敗したときに表示されます。

例

AddAlt "PDF file" *.pdf
AddAlt Compressed *.gz *.zip *.Z

AddAltByEncoding ディレクティブ

説明: | アイコンの代わりに表示される、MIME 符号化方法で選択された 代替テキスト
構文: | AddAltByEncoding string MIME-encoding [MIME-encoding] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

AddAltByEncoding は、 FancyIndexing において、アイコンの代わりに表示する代替文字列を提供します。 MIME-encoding は有効な符号化、例えば x-compress です。 string に空白があるときは、引用符 (" か ') で囲む必要があります。 この文字列は、クライアントが画像を表示できない場合や 画像のロードを無効にしている場合や アイコンの取得に失敗したときに表示されます。

例

AddAltByEncoding gzip x-gzip

AddAltByType ディレクティブ

説明: | アイコンの代わりに 表示される、MIME タイプで選択された代替テキスト
構文: | AddAltByType string MIME-type [MIME-type] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

AddAltByType は、 FancyIndexing において、アイコンの代わりに表示する代替文字列を設定します。 MIME-type は有効なタイプ、例えば text/html です。 string に空白があるときは、引用符 (" か ') で囲む必要があります。 この文字列は、クライアントが画像を表示できない場合や 画像のロードを無効にしている場合や アイコンの取得に失敗したときに表示されます。

例

AddAltByType 'plain text' text/plain

AddDescription ディレクティブ

説明: | ファイルに対して表示する説明
構文: | AddDescription string file [file] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

FancyIndexing において、ファイルに対して表示する説明を設定します。 file は説明するファイルのファイル拡張子、 ファイル名の一部、ワイルドカード表現、完全なファイル名の どれかになります。 string は二重引用符 (") で囲まれます。

例

AddDescription "The planet Mars" /web/pics/mars.gif

通常のデフォルトの説明領域は 23 バイトの幅です。 IndexOptions SuppressIcon オプションで 6 バイト追加、 IndexOptions SuppressSize オプションで 7 バイト追加、 IndexOptions SuppressLastModified オプションで 19 バイト追加されます。 ですから、デフォルトの説明コラムの最大幅は 55 バイトになります。

このコラムの大きさを上書きしたり、 説明が無制限長でもよいようにするための詳細に関しては、 DescriptionWidth という IndexOptions のキーワードをご覧下さい。

警告

AddDescription で定義された説明テキストは、タグや文字列といった HTML マークアップを含むことができます。 もし、説明コラムの幅によってタグ付けされた要素が丸め込まれた (太字の語句の最後が切れるといった) 場合、 出力結果は、ディレクトリ一覧の残りの部分に影響を与えるでしょう。

AddIcon ディレクティブ

説明: | ファイルに表示するアイコンを名前で選択
構文: | AddIcon icon name [name] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

FancyIndexing において、 name で終わるファイルの隣に表示するアイコンを設定します。 icon は、(% でエスケープされた) アイコンへの相対 URL か、他の書式 (alttext, url) です。 ここで alttext は、非グラフィカルブラウザ向けにアイコンに付けられたテキストタグです。

name は、ディレクトリに対応する ^^DIRECTORY^^ か、空白行に対応する ^^BLANKICON^^ (一覧が正しく表示されるために) か、 ファイル拡張子か、ワイルドカード表現か、ファイル名の一部か 完全なファイル名です。

例

AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm
AddIcon /icons/dir.xbm ^^DIRECTORY^^
AddIcon /icons/backup.xbm *~

もし可能なら、 AddIcon より AddIconByType を優先的に使うべきでしょう。

AddIconByEncoding ディレクティブ

説明: | ファイルに表示するアイコンを MIME 符号化方法で選択
構文: | AddIconByEncoding icon MIME-encoding [MIME-encoding] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

FancyIndexing において、ファイルの隣に表示するアイコンを設定します。 icon は、(% でエスケープされた) アイコンへの相対 URL か、他の書式 (alttext, url) です。 ここで alttext は、非グラフィカルブラウザ向けにアイコンに付けられたテキストタグです。

MIME-encoding は、要求されたエンコードに該当する ワイルドカード表現です。

例

AddIconByEncoding /icons/compress.xbm x-compress

AddIconByType ディレクティブ

説明: | ファイルの隣に表示するアイコンを MIME タイプによって選択
構文: | AddIconByType icon MIME-type [MIME-type] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

FancyIndexing において、ファイルの隣に表示するアイコンを設定します。 icon は、(% でエスケープされた) アイコンへの相対 URL か、他の書式 (alttext, url) です。 ここで alttext は、非グラフィカルブラウザ向けにアイコンに付けられたテキストタグです。

MIME-type は、要求されたタイプに該当する ワイルドカード表現です。

例

AddIconByType (IMG,/icons/image.xbm) image/*

DefaultIcon ディレクティブ

説明: | 特定のアイコンが何も設定されていない時に ファイルに表示するアイコン
構文: | DefaultIcon url-path
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

FancyIndexing において、 特定のアイコンがない場合にファイルに表示するアイコンを設定します。 url-path は、(% でエスケープされた) アイコンへの相対 URL です。

例

DefaultIcon /icon/unknown.xbm

HeaderName ディレクティブ

説明: | インデックス一覧の先頭に挿入されるファイルの名前
構文: | HeaderName filename
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

HeaderName ディレクティブは、 インデックス一覧の先頭に挿入するファイルの名前を設定します。 Filename は取り込むファイルの名前です。

例

HeaderName HEADER.html

HeaderName も ReadmeName も両方とも現在は、filename をインデックスされているディレクトリに用いられた URI に対する相対 URI パスとして扱います。 filename がスラッシュで始まる場合は、 DocumentRoot からの相対パスとなります。

例

HeaderName /include/HEADER.html

filename は メジャーコンテントタイプが "text/*" (例えば、text/html, text/plain 等です。) のドキュメントとして解決 されなければなりません。これはつまり、 もし CGI スクリプトの実際のファイルタイプが 次のディレクティブのようにして実際の出力とは異なって text/html としてマークされている場合、 filename は CGI スクリプトを参照するかも知れない、 ということを意味します:

AddType text/html .cgi

Options MultiViews が 有効になっている場合は、 コンテントネゴシエーション が行なわれます。 もし filename が (CGI スクリプトでない) 静的な text/html ドキュメントで解決され、 options Includes か IncludesNOEXEC が有効になっている場合は、 ファイルはサーバーサイドインクルードで処理されます (mod_include ドキュメントを参照して下さい)。

もし HeaderName で指定されたファイルが HTML ドキュメントの開始部分 (<html>, <head>, 等) を含んでいたら、 IndexOptions +SuppressHTMLPreamble を設定して、これらのタグが繰り返されないようにしたいと思うでしょう。

IndexIgnore ディレクティブ

説明: | ディレクトリ一覧を行なう際に無視すべき ファイルリストに追加
構文: | IndexIgnore file [file] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

IndexIgnore ディレクティブは、 ディレクトリの一覧を行う際に無視すべきファイルリストに追加します。 file は、 シェル形式のワイルドカード表現か完全なファイル名です。 IndexIgnore が複数ある場合は、無視するリストに追加が行われ、 置換は行われません。デフォルトではリストには . (カレントディレクトリ) が含まれています。

IndexIgnore README .htaccess *.bak *~

IndexOptions ディレクティブ

説明: | ディレクトリインデックスの様々な設定項目
構文: | IndexOptions [+|-]option [[+|-]option] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

IndexOptions は、ディレクトリインデックスの挙動を指定します。 option は次のどれかです:

DescriptionWidth=[n | *] (2.0.23 以降)
DescriptionWidth キーワードは説明コラムの幅を文字数で指定することができます。
-DescriptionWidth (または非設定) で、 mod_autoindex が最適な幅を計算するようにできます。
DescriptionWidth=n で、コラム幅を n バイトに固定します。
DescriptionWidth=* は、最長の説明に合わせて必要な長さまでコラムを延ばします。
説明を丸め込んだ場合特有の危険については AddDescription セクションをお読み下さい。
FancyIndexing
飾り付きインデックスをオンにします。
FoldersFirst (2.0.23 以降)
このオプションが有効になった場合、サブディレクトリの一覧は 必ず最初に現われて、そのディレクトリの通常のファイルは その後に続きます。 一覧は基本的には、ファイルとディレクトリの二つの部分に分けられて、 それぞれは別々にソートされ、その後サブディレクトリを先にして 表示が行なわれます。例えばソート順が名前の降順になっていて、 FoldersFirst が有効になっている場合は、 サブディレクトリ Zed はサブディレクトリ Beta よりも前にリストされ、通常のファイル Gamma や Alpha よりも前にリストされます。このオプションは FancyIndexing も有効になっているときにのみ、効果があります。
HTMLTable (実験的、 Apache 2.0.23 以降)
この実験的なオプションは FancyIndexing とともに指定することで、 飾りの付いたディレクトリ一覧のためにテーブルを使った単純な表を作ります。 これは古いブラウザを混乱させるかもしれないことに注意してください。 WinNT やその他 utf-8 が有効なプラットホームのように、ファイル名や説明テキストが 右読みになったり左読みになりえる場合は特に必要です。
IconsAreLinks
これは、FancyIndexing において、 アイコンもファイル名へのリンクの一部にします。
IconHeight[=pixels]
このオプションが、IconWidth とともに使われている場合は、 サーバはファイルアイコンのための img タグに height と width 属性を取り込むようになります。 これによって、イメージ全てをロードし終わるまで待たなくても、 ブラウザはページレイアウトをあらかじめ計算することができます。 このオプションに何も値が与えられなければ、Apache ソフトウェアで提供されているアイコンの標準の高さが デフォルトなります。
IconWidth[=pixels]
このオプションが、IconHeight とともに使われている場合は、 サーバはファイルアイコンのための img タグに height と width 属性を取り込むようになります。 これによって、イメージ全てをロードし終わるまで待たなくても、 ブラウザはページレイアウトをあらかじめ計算することができます。 このオプションに何も値が与えられなければ、Apache ソフトウェアで提供されているアイコンの標準の高さが デフォルトなります。
IgnoreCase
このオプションが有効であると、ファイル名は大文字小文字を区別せずにソートされます。 例えばファイル名が昇順でソートされ、IgnoreCase が有効であれば、 Zeta は alfa の後にリストされます (注意: GAMMA は常に gamma の前になります)。
IgnoreClient
このオプションで mod_autoindex は、 クライアントからの全てのクエリー変数を無視するようになります。 これはソート順も含みます。 (つまり SuppressColumnSorting を暗に意味します。)
NameWidth=[n | *]
NameWidth キーワードでファイル名コラムの幅をバイト数で 指定できます。
-NameWidth (または非設定) で、 mod_autoindex が最適な幅を計算するようにできます。
NameWidth=n で、コラム幅を n バイトに固定します。
NameWidth=* は、必要な長さまでコラムを延ばします。
ScanHTMLTitles
FancyIndexing のために、 HTML ドキュメントからタイトルを取り出すことを可能にします。 もしファイルに AddDescription で説明が与えられていなければ、 httpd は title タグの値を読むためにドキュメントを読み始めます。 これは CPU や disk に負荷をかけます。
SuppressColumnSorting
もし指定されていれば、Apache は FancyIndexing で表示されているディレクトリ一覧での コラムの先頭を、ソートのためのリンクにしなくなります。 デフォルトの挙動は、リンクとします。 コラムの先頭を選ぶとコラムの値に従ってディレクトリリストを ソートします。 Apache 2.0.23 以前では、これは同時に ソート文字列のためのクエリー引数の解析も無効にします。 この挙動は Apache 2.0.23 では IndexOptions IgnoreClient で制御されるようになっています。
SuppressDescription
これは FancyIndexing におけるファイルの説明を消去します。 デフォルトでは、説明は定義されておらず、 このオプションを使うと他のために 23 文字の空白を稼ぐことができます。 ファイルの説明に関する情報は、 AddDescription をご覧下さい。また、説明のコラムサイズを制限する DescriptionWidth インデックスオプションもご覧下さい。
SuppressHTMLPreamble
通常、 HeaderName ディレクティブで指定したファイルを ディレクトリが実際に含んでいれば、標準的な HTML プリアンブル (<html>, <head>, 等) の後に、 モジュールはファイルの中身をインクルードします。 SuppressHTMLPreamble オプションは、 この挙動を無効にできて、 モジュールがヘッダーファイルの中身から表示を始めます。 この場合、ヘッダーファイルは正しい HTML 命令を含んでいなければなりません。 ヘッダーファイルが存在しない場合は、プリアンブルは通常通り 生成されます。
SuppressIcon (Apache 2.0.23 以降)
これは FancyIndexing の一覧からアイコンを消去します。 SuppressIcon と SuppressRules と組合わせることによって正しい HTML 3.2 の出力が得られます。 正しい HTML 3.2 出力は、最終規格において img と hr が pre ブロックに入る (FancyIndexing 一覧で書式に使われています) ことを禁止しています。
SuppressLastModified
FancyIndexing 一覧において最終更新日時の表示を消去します。
SuppressRules (Apache 2.0.23 以降)
ディレクトリ一覧において水平区切り線 (hr タグ) を消去します。 SuppressIcon と SuppressRules と組合わせることによって正しい HTML 3.2 の出力が得られます。 正しい HTML 3.2 出力は、最終規格において img と hr が pre ブロックに入る (FancyIndexing 一覧で書式に使われています) ことを禁止しています。
SuppressSize
FancyIndexing 一覧においてファイルサイズの表示を消去します。
TrackModified (Apache 2.0.23 以降)
これは HTTP ヘッダ中に、 リストされたディレクトリの最終更新日や ETag 値を含めます。 これは、オペレーティングシステムやファイルシステムが 適切な stat() の返り値を返す場合にのみ有効です。 いくつかの UNIX システム、OS2 の JFS や Win32 の NTFS ボリュームはそうなっています。 例えば、OS2 と Win32 FAT ボリュームはそうではありません。 この機能が有効になると、クライアントやプロキシは HEAD リクエストを行うことによって、 ファイル一覧の変化を追跡することができるようになります。 いくつかのオペレーティングシステムは、新規ファイルや 移動ファイルは正しく追跡するけれども、 ディレクトリ中のファイルのサイズや日付は追跡ないということに 注意してください。 既に存在するファイルのサイズや日付のスタンプが変化しても、 全ての Unix プラットホームでは、 最終更新日ヘッダーを更新しません。 もしこれが重要であれば、 このオプションを無効のままにしてください。
VersionSort (Apache 2.0a3 以降)
VersionSort キーワードはバージョン番号を含んだファイルが 自然な方法でソートされるようにします。 文字列は通常通りソートされ、 それ以外の、説明や名前中の数となる部分文字列は その数値で比較されます。

例:

foo-1.7
foo-1.7.2
foo-1.7.12
foo-1.8.2
foo-1.8.2a
foo-1.12

番号が 0 から始まる場合は、端数と考えられます

foo-1.001
foo-1.002
foo-1.030
foo-1.04

XHTML (Apache 2.0.49 以降)
XHTML キーワードを指定すると、mod_autoindex は HTML 3.2 の代わりに XHTML 1.0 のコードを出力するようになります。
増減指定できる IndexOptions

Apache 1.3.3 では、 IndexOptions ディレクティブの扱いで幾つかの大きな変化が導入されました。 特に、

  • 一つのディレクトリに対する複数の IndexOptions ディレクティブは、現在では一つにマージされます。 上の例の結果は、

    <Directory /foo> IndexOptions HTMLTable
    IndexOptions SuppressColumnsorting     </Directory>

    と同一になります。

    IndexOptions HTMLTable SuppressColumnsorting

  • 増減構文 (すなわち、'+' や '-' の接頭辞が付くキーワード) の追加。

'+' や '-' 接頭辞の付いたキーワードに出会うとそれは、 その時点での IndexOptions の設定 (これは上流のディレクトリを受け継ぎます) に対して適応されます。 しかしながら、接頭辞の付かないキーワードが処理された場合は、 受け継いだオプション全てとそれまで出会った増減設定全てが 消去されます。次の例を考えてみてください:

IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing
IndexOptions +SuppressSize

中身の効果は IndexOptions FancyIndexing +SuppressSize と同一です。 接頭辞の付かない FancyIndexing でそれ以前の増減キーワードを無効にされて、 その後の累積が始まるからです。

無条件に IndexOptions をあるディレクトリで設定することによって 継承した設定を消去して、+ や - 接頭辞の付かないキーワードで設定してください。

IndexOrderDefault ディレクティブ

説明: | ディレクトリインデックスの標準の順番付けを設定
構文: | IndexOrderDefault Ascending|Descending Name|Date|Size|Description
デフォルト: | IndexOrderDefault Ascending Name
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

IndexOrderDefault ディレクティブは FancyIndexing インデックスオプションと併せて用いれれます。 デフォルトでは、FancyIndexing のディレクトリ一覧はファイル名の昇順で表示されます。 IndexOrderDefault で、初期状態の表示順番を変えることができます。

IndexOrderDefault は二つの引数をとります。一つ目はソートの方向を指示する Ascending か Descending のいずれかです。 二つ目の引数は Name, Date, Size か Description のいずれか一つのキーワードであって、プライマリキーを指定します。 二つ目のキーは常にファイル名の昇順になります。

このディレクティブと SuppressColumnSorting インデックスオプションとを組み合わせることで、 ディレクトリ一覧をある特定の順番でのみ表示するようにできます。 これは、 クライアントが別の順番でディレクトリ一覧をリクエストすることを防ぎます。

ReadmeName ディレクティブ

説明: | インデックス一覧の最後に挿入されるファイルの名前
構文: | ReadmeName filename
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

ReadmeName ディレクティブは、 インデックスの終わりに付け加えられるファイルの名前を設定します。 filename は挿入するファイルの名前で、 一覧の行われている位置から相対的なものとして解釈されます。 filename がスラッシュで始まる場合は、 DocumentRoot からの相対パスとなります。

例

ReadmeName FOOTER.html

例 2

ReadmeName /include/FOOTER.html

より詳細にまでこの挙動について記述している HeaderName もご覧下さい。


mod_cache - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_cache

Description: | Content cache keyed to URIs.
Status: | Experimental
Module?dentifier: | cache_module
Source?ile: | mod_cache.c

Summary

This module is experimental. Documentation is still under development...

mod_cache implements an RFC 2616 compliant HTTP content cache that can be used to cache either local or proxied content. mod_cache requires the services of one or more storage management modules. Two storage management modules are included in the base Apache distribution:

mod_disk_cache
implements a disk based storage manager.
mod_mem_cache
implements a memory based storage manager. mod_mem_cache can be configured to operate in two modes: caching open file descriptors or caching objects in heap storage. mod_mem_cache can be used to cache locally generated content or to cache backend server content for mod_proxy when configured using ProxyPass (aka reverse proxy)

Content is stored in and retrieved from the cache using URI based keys. Content with access protection is not cached.

Related Modules and Directives

Related Modules Related Directives
  • mod_disk_cache
  • mod_mem_cache
  • CacheRoot
  • CacheSize
  • CacheGcInterval
  • CacheDirLevels
  • CacheDirLength
  • CacheExpiryCheck
  • CacheMinFileSize
  • CacheMaxFileSize
  • CacheTimeMargin
  • CacheGcDaily
  • CacheGcUnused
  • CacheGcClean
  • CacheGcMemUsage
  • MCacheSize
  • MCacheMaxObjectCount
  • MCacheMinObjectSize
  • MCacheMaxObjectSize
  • MCacheRemovalAlgorithm
  • MCacheMaxStreamingBuffer

Sample Configuration

Sample httpd.conf

#
# Sample Cache Configuration
#
LoadModule cache_module modules/mod_cache.so

<IfModule mod_cache.c>
#LoadModule disk_cache_module modules/mod_disk_cache.so
<IfModule mod_disk_cache.c>
CacheRoot c:/cacheroot
CacheSize 256
CacheEnable disk /
CacheDirLevels 5
CacheDirLength 3
 </IfModule>

LoadModule mem_cache_module modules/mod_mem_cache.so
<IfModule mod_mem_cache.c>
CacheEnable mem /
MCacheSize 4096
MCacheMaxObjectCount 100
MCacheMinObjectSize 1
MCacheMaxObjectSize 2048
 </IfModule>
 </IfModule>

CacheDefaultExpire Directive

Description: | The default duration to cache a document when no expiry date is specified.
Syntax: | CacheDefaultExpire seconds
Default: | CacheDefaultExpire 3600 (one hour)
Context: | server config, virtual host
Status: | Experimental
Module: | mod_cache

The CacheDefaultExpire directive specifies a default time, in seconds, to cache a document if neither an expiry date nor last-modified date are provided with the document. The value specified with the CacheMaxExpire directive does not override this setting.

CacheDefaultExpire 86400

CacheDisable Directive

Description: | Disable caching of specified URLs
Syntax: | CacheDisable url-string
Context: | server config, virtual host
Status: | Experimental
Module: | mod_cache

The CacheDisable directive instructs mod_cache to not cache urls at or below url-string.

Example

CacheDisable /local_files

CacheEnable Directive

Description: | Enable caching of specified URLs using a specified storage manager
Syntax: | CacheEnable cache_type url-string
Context: | server config, virtual host
Status: | Experimental
Module: | mod_cache

The CacheEnable directive instructs mod_cache to cache urls at or below url-string. The cache storage manager is specified with the cache_type argument. cache_type mem instructs mod_cache to use the memory based storage manager implemented by mod_mem_cache. cache_type disk instructs mod_cache to use the disk based storage manager implemented by mod_disk_cache. cache_type fd instructs mod_cache to use the file descriptor cache implemented by mod_mem_cache.

In the event that the URL space overlaps between different CacheEnable directives (as in the example below), each possible storage manager will be run until the first one that actually processes the request. The order in which the storage managers are run is determined by the order of the CacheEnable directives in the configuration file.

CacheEnable mem /manual
CacheEnable fd /images
CacheEnable disk /

CacheForceCompletion Directive

Description: | Percentage of document served, after which the server will complete caching the file even if the request is cancelled.
Syntax: | CacheForceCompletion Percentage
Default: | CacheForceCompletion 60
Context: | server config, virtual host
Status: | Experimental
Module: | mod_cache

Ordinarily, if a request is cancelled while the response is being cached and delivered to the client the processing of the response will stop and the cache entry will be removed. The CacheForceCompletion directive specifies a threshold beyond which the document will continue to be cached to completion, even if the request is cancelled.

The threshold is a percentage specified as a value between 1 and 100. A value of 0 specifies that the default be used. A value of 100 will only cache documents that are served in their entirety. A value between 60 and 90 is recommended.

CacheForceCompletion 80

Note:

This feature is currently not implemented.

CacheIgnoreCacheControl Directive

Description: | Ignore the fact that the client requested the content not be cached.
Syntax: | CacheIgnoreCacheControl On|Off
Default: | CacheIgnoreCacheControl Off
Context: | server config, virtual host
Status: | Experimental
Module: | mod_cache

Ordinarily, documents with no-cache or no-store header values will not be stored in the cache. The CacheIgnoreCacheControl directive allows this behavior to be overridden. CacheIgnoreCacheControl On tells the server to attempt to cache the document even if it contains no-cache or no-store header values. Documents requiring authorization will never be cached.

CacheIgnoreCacheControl On

CacheIgnoreNoLastMod Directive

Description: | Ignore the fact that a response has no Last Modified header.
Syntax: | CacheIgnoreNoLastMod On|Off
Default: | CacheIgnoreNoLastMod Off
Context: | server config, virtual host
Status: | Experimental
Module: | mod_cache

Ordinarily, documents without a last-modified date are not cached. Under some circumstances the last-modified date is removed (during mod_include processing for example) or not provided at all. The CacheIgnoreNoLastMod directive provides a way to specify that documents without last-modified dates should be considered for caching, even without a last-modified date. If neither a last-modified date nor an expiry date are provided with the document then the value specified by the CacheDefaultExpire directive will be used to generate an expiration date.

CacheIgnoreNoLastMod On

CacheLastModifiedFactor Directive

Description: | The factor used to compute an expiry date based on the LastModified date.
Syntax: | CacheLastModifiedFactor float
Default: | CacheLastModifiedFactor 0.1
Context: | server config, virtual host
Status: | Experimental
Module: | mod_cache

In the event that a document does not provide an expiry date but does provide a last-modified date, an expiry date can be calculated based on the time since the document was last modified. The CacheLastModifiedFactor directive specifies a factor to be used in the generation of this expiry date according to the following formula: expiry-period = time-since-last-modified-date * factor expiry-date = current-date + expiry-period For example, if the document was last modified 10 hours ago, and factor is 0.1 then the expiry-period will be set to 10*0.1 = 1 hour. If the current time was 3:00pm then the computed expiry-date would be 3:00pm + 1hour = 4:00pm. If the expiry-period would be longer than that set by CacheMaxExpire, then the latter takes precedence.

CacheLastModifiedFactor 0.5

CacheMaxExpire Directive

Description: | The maximum time in seconds to cache a document
Syntax: | CacheMaxExpire seconds
Default: | CacheMaxExpire 86400 (one day)
Context: | server config, virtual host
Status: | Experimental
Module: | mod_cache

The CacheMaxExpire directive specifies the maximum number of seconds for which cachable HTTP documents will be retained without checking the origin server. Thus, documents will be out of date at most this number of seconds. This maximum value is enforced even if an expiry date was supplied with the document.

CacheMaxExpire 604800


mod_cern_meta - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_cern_meta

Description: | CERN httpd metafile semantics
Status: | Extension
Module?dentifier: | cern_meta_module
Source?ile: | mod_cern_meta.c

Summary

Emulate the CERN HTTPD Meta file semantics. Meta files are HTTP headers that can be output in addition to the normal range of headers for each file accessed. They appear rather like the Apache .asis files, and are able to provide a crude way of influencing the Expires: header, as well as providing other curiosities. There are many ways to manage meta information, this one was chosen because there is already a large number of CERN users who can exploit this module.

More information on the CERN metafile semantics is available.

See also

  • mod_headers
  • mod_asis

MetaDir Directive

Description: | Name of the directory to find CERN-style meta information files
Syntax: | MetaDir directory
Default: | MetaDir .web
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Extension
Module: | mod_cern_meta

Specifies the name of the directory in which Apache can find meta information files. The directory is usually a 'hidden' subdirectory of the directory that contains the file being accessed. Set to "." to look in the same directory as the file:

MetaDir .

Or, to set it to a subdirectory of the directory containing the files:

MetaDir .meta

MetaFiles Directive

Description: | Activates CERN meta-file processing
Syntax: | MetaFiles on|off
Default: | MetaFiles off
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Extension
Module: | mod_cern_meta

Turns on/off Meta file processing on a per-directory basis.

MetaSuffix Directive

Description: | File name suffix for the file containg CERN-style meta information
Syntax: | MetaSuffix suffix
Default: | MetaSuffix .meta
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Extension
Module: | mod_cern_meta

Specifies the file name suffix for the file containing the meta information. For example, the default values for the two directives will cause a request to DOCUMENT_ROOT/somedir/index.html to look in DOCUMENT_ROOT/somedir/.web/index.html.meta and will use its contents to generate additional MIME header information.

Example:

MetaSuffix .meta


mod_cgi - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_cgi

説明: | CGI スクリプトの実行
ステータス: | Base
モジュール識別子: | cgi_module
ソースファイル: | mod_cgi.c

概要

Mime タイプが application/x-httpd-cgi であるか、ハンドラ cgi-script (Apache 1.1 以降) が指定されているファイルは CGI スクリプトとして扱われ、 サーバにより実行され、その出力がクライアントに返されます。 ファイルは、AddType ディレクティブに指定された 拡張子を名前に含むか、 ScriptAlias ディレクトリに存在することによりこのタイプになります。

サーバが CGI スクリプトを実行するときには、 DOCUMENT_ROOT と呼ばれる変数を環境に追加します。この変数は DocumentRoot の値を保持します。

Apache で CGI スクリプトを使用するためのイントロダクションは、 CGI による動的コンテンツ を参照してください。

Unix でマルチスレッドの MPM を使っている場合は、このモジュールの 代わりに mod_cgid を使う必要があります。 ユーザレベルではこの二つのモジュールは本質的には同一です。

参照

  • AcceptPathInfo
  • Options
  • ScriptAlias
  • AddHandler
  • CGI プログラムを別のユーザ ID で実行する
  • CGI 規格書

CGI 環境変数

サーバは CGI 規格 で決められている CGI 環境変数を設定します。以下のものは、条件付きで設定されます。

PATH_INFO
これは AcceptPathInfo ディレクティブが明示的に off に設定されている場合は設定されません。デフォルトの、 AcceptPathInfo が 指定されていないときの振る舞いでは、mod_cgi はパス情報 (URI のスクリプトのファイル名の後に続く /more/path/info) を 受け付けますが、コアはサーバはパス情報のあるリクエストに 対して 404 NOT FOUND エラーを返します。AcceptPathInfo ディレクティブを 省略すると、mod_cgi へのリクエストに対して On を 設定したのと同じ効果になります。
REMOTE_HOST
HostnameLookups が on (デフォルトでは off です) で、アクセスしているホストのアドレスの DNS の逆引きが実際にホスト名を見つけたときにのみ設定されます。
REMOTE_IDENT
IdentityCheck が on に設定されていて、アクセスしているホストが ident プロトコルをサポートしているときにのみ設定されます。 これは簡単に偽ることができ、クライアントとサーバの間に プロキシがあればまったく役に立たないので、 この変数の値は信用できないということに注意してください。
REMOTE_USER
CGI スクリプトに認証が必要なときにのみ設定されます。

CGI のデバッグ

CGI スクリプトのデバッグは、正しく動作していないスクリプトの出力 (標準出力とエラー) を調べることができないために、難しい状態が続いていました。 これらの Apache 1.2 以降にある ディレクティブはより詳細なエラーのログ収集を提供します。

CGI ログファイルの書式

設定されているときには、CGI エラーログは適切に動作しないすべての CGI をログ収集します。それぞれの正しく動作しない CGI スクリプトは 複数の行にわたる情報がログ収集されます。最初の 2 行は常に以下の書式です:

%% [time] request-line
%% HTTP-status CGI-script-filename

エラーが、CGI スクリプトが実行できないというものである場合は、 ログファイルはさらにもう 2 行書かれます:

%%error
error-message

そうではなく、エラーが正しくないヘッダ情報を返す結果である場合 (スクリプトのバグであることがよくあります)、 以下の情報がログ収集されます:

%request
受け取ったすべての HTTP リクエストヘッダ
(もしあれば) POST や PUT の中身
%response
CGI スクリプトにより出力されたすべてのヘッダ
%stdout
CGI 標準出力
%stderr
CGI 標準エラー

(スクリプトが標準出力や標準エラーに何も出力しなかった場合は、 %stdout や %stderr はありません)。

ScriptLog ディレクティブ

説明: | CGI スクリプトのエラーログファイルの場所
構文: | ScriptLog file-path
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_cgi, mod_cgid

ScriptLog ディレクティブは CGI スクリプトの エラーログファイルを設定します。ScriptLog が 設定されていないときは、 エラーログは作成されません。設定されているときは、CGI のエラーはすべて引数として与えられているファイル名にログされます。 相対パスで指定されているときは、 ServerRootからの相対パスとして 扱われます。

例

ScriptLog logs/cgi_log

このログは子プロセスが実行されているユーザとしてオープンされます。 すなわち、User ディレクティブで指定された ユーザです。これは、スクリプトログが書かれるディレクトリがそのユーザで 書き込み可能か、スクリプトファイルが手動で作成され、そのユーザで 書き込み可能になっている必要があるということです。スクリプトログを アクセスログなどのためのログディレクトリに書かれるようにしたときは、 そのディレクトリを子プロセスを実行しているユーザの権限で 書き込み可能にはしないようにしてください。

スクリプトのログ収集は CGI スクリプトを書くときの デバッグ用の機能として意図されていて、通常のサーバで 常に使用されるようには意図されていないということに注意してください。 速度や効率は最適化されておらず、設計された以外の方法で使用されると セキュリティの問題があるかもしれません。

ScriptLogBuffer ディレクティブ

説明: | スクリプトログに記録される PUT や POST リクエストの内容の上限
構文: | ScriptLogBuffer bytes
デフォルト: | ScriptLogBuffer 1024
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_cgi, mod_cgid

大きな本体を受け取ったときにログファイルがすぐに大きくなりすぎる 問題を避けるために、ファイルにログ収集される PUT と POST の本体の大きさは制限されています。デフォルトでは、1024 バイトまでがログ収集されますが、 このディレクティブはそれを変更することができます。

ScriptLogLength ディレクティブ

説明: | CGI スクリプトのログファイルの大きさの上限
構文: | ScriptLogLength bytes
デフォルト: | ScriptLogLength 10385760
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_cgi, mod_cgid

ScriptLogLength は CGI スクリプトのログファイル の大きさを制限するために使用することができます。ログファイルは CGI のエラー毎に大量の情報 (リクエストのすべてのヘッダ、 すべての出力)をログしますので、すぐに大きなファイルになります。 この大きさの制限がないことによる問題を防ぐために、 このディレクティブを使って CGI のログファイルの 最大のファイルサイズを設定することができます。 ファイルがこの大きさを超えた場合は、それ以上は書き込まれません。


mod_cgid - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_cgid

説明: | 外部 CGI デーモンを使った CGI スクリプトの実行
ステータス: | Base
モジュール識別子: | cgid_module
ソースファイル: | mod_cgid.c
互換性: | Unix のスレッド MPM のみ

概要

最適化が施されていることと、以下で説明されている追加の ScriptSock ディレクティブを除いては、 mod_cgid は mod_cgi と同様の 動作をします。Apache と CGI に関する詳細は mod_cgi の概要を読んでください。

Unix オペレーティングシステムの中には、マルチスレッドのサーバから プロセスを fork するのが非常にコストの高い動作になっているものがあります。 理由は、新しいプロセスが親プロセスのスレッドすべてを複製するからです。 各 CGI 起動時にこのコストがかかるのを防ぐために、mod_cgid は子プロセスを fork して CGI スクリプトを実行するための 外部デーモンを実行します。 主サーバは unix ドメインソケットを使ってこのデーモンと通信します。

コンパイル時にマルチスレッド MPM が選ばれたときは mod_cgi の代わりに必ずこのモジュールが使用されます。 ユーザのレベルではこのモジュールの設定と動作は mod_cgi とまったく同じです。唯一の例外は ScriptSock ディレクティブの 追加で、このディレクティブは CGI デーモンとの通信用のソケットの名前を 指定します。

参照

  • mod_cgi
  • CGI プログラムを違うユーザ ID で実行する

ScriptSock ディレクティブ

説明: | CGI デーモンとの通信に使われるソケットの名前
構文: | ScriptSock file-path
デフォルト: | ScriptSock logs/cgisock
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_cgid

このディレクティブは CGI デーモンとの通信に使われるソケットの 名前を設定します。ソケットは Apache が起動されたユーザ (通常 root) の パーミッションを用いてオープンされます。CGI スクリプトとの通信の セキュリティを保つために、ソケットの存在するディレクトリに 他のユーザが書き込み権限を持っていないようにすることが重要です。

例

ScriptSock /var/run/cgid.sock


mod_charset_lite - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_charset_lite

Description: | Specify character set translation or recoding
Status: | Experimental
Module?dentifier: | charset_lite_module
Source?ile: | mod_charset_lite.c

Summary

This is an experimental module and should be used with care. Experiment with your mod_charset_lite configuration to ensure that it performs the desired function.

mod_charset_lite allows the administrator to specify the source character set of objects as well as the character set they should be translated into before sending to the client. mod_charset_lite does not translate the data itself but instead tells Apache what translation to perform. mod_charset_lite is applicable to EBCDIC and ASCII host environments. In an EBCDIC environment, Apache normally translates text content from the code page of the Apache process locale to ISO-8859-1. mod_charset_lite can be used to specify that a different translation is to be performed. In an ASCII environment, Apache normally performs no translation, so mod_charset_lite is needed in order for any translation to take place.

This module provides a small subset of configuration mechanisms implemented by Russian Apache and its associated mod_charset.

Common Problems

Invalid character set names

The character set name parameters of CharsetSourceEnc and CharsetDefault must be acceptable to the translation mechanism used by APR on the system where mod_charset_lite is deployed. These character set names are not standardized and are usually not the same as the corresponding values used in http headers. Currently, APR can only use iconv(3), so you can easily test your character set names using the iconv(1) program, as follows:

iconv -f charsetsourceenc-value -t charsetdefault-value

Mismatch between character set of content and translation rules

If the translation rules don't make sense for the content, translation can fail in various ways, including:

  • The translation mechanism may return a bad return code, and the connection will be aborted.
  • The translation mechanism may silently place special characters (e.g., question marks) in the output buffer when it cannot translate the input buffer.

CharsetDefault Directive

Description: | Charset to translate into
Syntax: | CharsetDefault charset
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Experimental
Module: | mod_charset_lite

The CharsetDefault directive specifies the charset that content in the associated container should be translated to.

The value of the charset argument must be accepted as a valid character set name by the character set support in APR. Generally, this means that it must be supported by iconv.

Example

<Directory /export/home/trawick/apacheinst/htdocs/convert>
CharsetSourceEnc UTF-16BE
CharsetDefault ISO-8859-1
 </Directory>

CharsetOptions Directive

Description: | Configures charset translation behavior
Syntax: | CharsetOptions option [option] ...
Default: | CharsetOptions DebugLevel=0 NoImplicitAdd
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Experimental
Module: | mod_charset_lite

The CharsetOptions directive configures certain behaviors of mod_charset_lite. Option can be one of

DebugLevel=n
The DebugLevel keyword allows you to specify the level of debug messages generated by mod_charset_lite. By default, no messages are generated. This is equivalent to DebugLevel=0. With higher numbers, more debug messages are generated, and server performance will be degraded. The actual meanings of the numeric values are described with the definitions of the DBGLVL_ constants near the beginning of mod_charset_lite.c.
ImplicitAdd | NoImplicitAdd
The ImplicitAdd keyword specifies that mod_charset_lite should implicitly insert its filter when the configuration specifies that the character set of content should be translated. If the filter chain is explicitly configured using the AddOutputFilter directive, NoImplicitAdd should be specified so that mod_charset_lite doesn't add its filter.

CharsetSourceEnc Directive

Description: | Source charset of files
Syntax: | CharsetSourceEnc charset
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Experimental
Module: | mod_charset_lite

The CharsetSourceEnc directive specifies the source charset of files in the associated container.

The value of the charset argument must be accepted as a valid character set name by the character set support in APR. Generally, this means that it must be supported by iconv.

Example

<Directory /export/home/trawick/apacheinst/htdocs/convert>
CharsetSourceEnc UTF-16BE
CharsetDefault ISO-8859-1
 </Directory>

The character set names in this example work with the iconv translation support in Solaris 8.


mod_dav - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_dav

説明: | 分散オーサリングとバージョン管理 (WebDAV) 機能
ステータス: | Extension
モジュール識別子: | dav_module
ソースファイル: | mod_dav.c

概要

このモジュールはクラス 1 とクラス 2 の WebDAV ('ウェブベースの分散オーサリングとバージョン管理') 機能を Apache に提供します。 この HTTP プロトコルの拡張により、リモートのウェブサーバ上にある リソースやコレクションを 作成、移動、複製、削除できるようになります。

参照

  • DavLockDB
  • LimitXMLRequestBody
  • WebDAV Resources

Enabling WebDAV

mod_dav を有効にするには、httpd.conf ファイル中のコンテナに次を加えます:

Dav On

これは DAV ファイルシステムプロバイダを有効にします。DAV ファイルシステムプロバイダは mod_dav_fs モジュールで実装されています。ですから、このモジュールはコンパイル時に サーバに組み込まれているか、あるいは LoadModule を使用して実行時にロードされている必要があります。

さらに、DAV ロックデータベースの場所が DavLockDB ディレクティブを使って httd.conf ファイルのグローバルセクションに指定されている 必要があります。

DavLockDB /usr/local/apache2/var/DavLock

ロックデータベースファイルのあるディレクトリは Apache が実行されている User と Group に書き込み権限がある必要があります。

<Limit> 節を <Location> ディレクティブ内部に追加して、DAV が有効な場所への アクセスを制限することもできます。DAV クライアントが 一度のリクエストで送信できる最大バイト数を指定したいときは、 LimitXMLRequestBody ディレクティブを使用する必要があります。「通常の」 LimitRequestBody ディレクティブは DAV リクエストに対しては効力を持ちません。

完全な例

DavLockDB /usr/local/apache2/var/DavLock

<Location /foo>
Dav On

AuthType Basic
AuthName DAV
AuthUserFile user.passwd

<LimitExcept GET OPTIONS>
require user admin
 </LimitExcept>
 </Location>

mod_dav は Greg Stein さんの Apache 1.3 用の mod_dav に 由来するものです。そのサイトからより多くの情報を手に入れることができます。

セキュリティの問題

DAV のアクセスメソッドは遠隔クライアントがサーバのファイルを 操作することを可能にしますので、 mod_dav を使用する 前に、サーバが安全であることを特に注意して確認しなければなりません。

サーバ上の DAV が使用可能になっている場所はすべて認証で保護してください。 HTTP 基本認証の使用は推奨できません。少なくとも mod_auth_digest モジュールで提供される HTTP ダイジェスト認証を用いるべきです。WebDAV クライアントのほとんどは この認証方法に対応しています。代わりに、SSL が 有効なコネクションを通した基本認証を使うこともできます。

mod_dav がファイルを操作できるようにするためには、 管理下のディレクトリとファイルとに Apache が実行されている User と Group で書き込み可能である必要があります。 新しく作成されるファイルもこの User と Group に所有される ことになります。この理由から、そのアカウントへのアクセスを制御することは 重要です。DAV リポジトリは Apache 専用のものだとみなされています。 Apache 以外の方法でファイルを修正すること (例えば FTP やファイルシステム 用のツールなどを使って) は許可されていません。

mod_dav はいろいろな種類のサービス拒否攻撃にさらされる かもしれません。LimitXMLRequestBody ディレクティブを使うと 大きな DAV リクエストを解析するときに消費されるメモリの量を制限することが できます。DavDepthInfinity ディレクティブは PROPFIND リクエストが巨大リポジトリで大量のメモリを消費するのを 防ぐことができます。他のサービス拒否攻撃には単純に使用可能なディスク領域を 多くの大きなファイルで埋めてしまうんものがあります。これを直接防ぐ方法は Apache にはありませんので、信用できないユーザに DAV アクセスを提供するのは 避けた方が良いでしょう。

複雑な設定

よくある要求に、mod_dav を使って動的なファイル (PHP スクリプト、CGI スクリプトなど) を操作したいというものがあります。 これの実現は、GET リクエストはスクリプトの内容をダウンロードさせる 代わりに、スクリプトを常に実行させてしまうので難しくなっています。 これを回避する方法には、二つの違う URL を同じコンテンツにマップし、 一つはスクリプトを実行させ、もう一つはダウンロードさせたり、DAV から 操作されたりするように設定するというものがあります。

Alias /phparea /home/gstein/php_files
Alias /php-source /home/gstein/php_files
<Location /php-source> DAV On
ForceType text/plain
 </Location>

この設定により、http://example.com/phparea を PHP スクリプトの 出力をアクセスするために使うことができ、 http://example.com/php-source を DAV クライアントによる が操作のために使うことができます。

Dav ディレクティブ

説明: | WebDAV HTTP メソッドを有効にします
構文: | Dav On|Off|provider-name
デフォルト: | Dav Off
コンテキスト: | ディレクトリ
ステータス: | Extension
モジュール: | mod_dav

与えられたコンテナで WebDAV HTTP メソッドが使えるようにするには 次のようにします。

<Location /foo>
Dav On
 </Location>

On という指定は実際には mod_dav_fs で提供されているデフォルトのプロバイダ、filesystem へのエイリアスになっています。一度あるロケーションで DAV を有効にした後は、そのサブロケーションで無効化することはできない ということに注意してください。完全な設定例は上記のセクション をご覧下さい。

サーバのセキュリティが確保できるまで WebDAV を有効にしないでください。 そうしなければ誰でもそのサーバでファイルを配布することができるように なってしまいます。

DavDepthInfinity ディレクティブ

説明: | PROPFIND, Depth: Infinity リクエストを許可します
構文: | DavDepthInfinity on|off
デフォルト: | DavDepthInfinity off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_dav

'Depth: Infinity' を含んでいる PROPFIND リクエストを処理できるようにするには、 DavDepthInfinity ディレクティブを使います。このタイプのリクエストは denial-of-service アタックとなりうるので、 デフォルトでは許可されていません。

DavMinTimeout ディレクティブ

説明: | サーバが DAV リソースのロックを維持する最小時間です。
構文: | DavMinTimeout seconds
デフォルト: | DavMinTimeout 0
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_dav

クライアントが DAV リソースロックを要求した場合、 ロックがサーバによって自動的に解除されるまでの時間を 同時に指定することができます。この値は単なるリクエストであって、 サーバはこれを無視することもできますし、 任意の値をクライアントに通知することもできます。

クライアントに戻すロックタイムアウトの最小時間を、 秒で、指定するために DavMinTimeout ディレクティブを使います。 マイクロソフトのウェブフォルダのデフォルトでは 120 秒ですが； ネットワークの遅延のせいでクライアントがロックを失うのを減らすために、 DavMinTimeout を使って これをもっと大きな値 (例えば 600 秒) に上書きできます。

例

<Location /MSWord>
DavMinTimeout 600
 </Location>


mod_dav_fs - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_dav_fs

説明: | mod_dav のためのファイルシステムプロバイダ
ステータス: | Extension
モジュール識別子: | dav_fs_module
ソースファイル: | mod_dav_fs.c

概要

このモジュールは mod_dav のサービスを必要とします。mod_dav のサポートモジュールとして動作し、サーバファイルシステム上に 位置するリソースへのアクセスを提供します。このプロバイダの正式な名前は filesystem です。mod_dav バックエンドプロバイダは Dav ディレクティブを使用して起動されます。

例

Dav filesystem

filesystem は mod_dav のデフォルトプロバイダになっていますから、代わりに単に On と指定することもできます。

参照

  • mod_dav

DavLockDB ディレクティブ

説明: | DAV ロックデータベースの位置
構文: | DavLockDB file-path
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_dav_fs

ロックデータベースへのフルパスを、拡張子を除いた形で 指定するには、DavLockDB を使います。パスが絶対パスでなければ、ServerRoot からの相対パスと解釈されます。 mod_dav_fs 実装では、ユーザロックを 追跡するために SDBM データベースを使います。

例

DavLockDB logs/DavLock


mod_deflate - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_deflate

説明: | クライアントへ送られる前にコンテンツを圧縮する
ステータス: | Extension
モジュール識別子: | deflate_module
ソースファイル: | mod_deflate.c

概要

mod_deflate モジュールは DEFLATE 出力フィルタを提供します。これはサーバからの出力を、ネットワークを 通してクライアントに送る前に圧縮することを可能にします。

参照

  • Filters

サンプル設定

下にせっかちな人向けの簡単な設定例を示します。

数タイプのみ圧縮する

AddOutputFilterByType DEFLATE text/html text/plain text/xml

以下の設定はコンテンツをより圧縮しますが、ずっと複雑な設定になります。 設定の隅々までよく理解しないで使わないでください。

画像以外全て圧縮する

<Location />
# Insert filter
SetOutputFilter DEFLATE

# Netscape 4.x has some problems...
BrowserMatch ^Mozilla/4 gzip-only-text/html

# Netscape 4.06-4.08 have some more problems
BrowserMatch ^Mozilla/4\.0[678] no-gzip

# MSIE masquerades as Netscape, but it is fine
# BrowserMatch \bMSIE !no-gzip !gzip-only-text/html

# NOTE: Due to a bug in mod_setenvif up to Apache 2.0.48
# the above regex won't work. You can use the following
# workaround to get the desired effect:
BrowserMatch \bMSI[E] !no-gzip !gzip-only-text/html

# Don't compress images
SetEnvIfNoCase Request_URI \
\.(?:gif|jpe?g|png)$ no-gzip dont-vary
# Make sure proxies don't deliver the wrong content
Header append Vary User-Agent env=!dont-vary
 </Location>

圧縮を有効にする

Output Compression

圧縮機能は DEFLATE フィルタ により実装されています。以下のディレクティブはそのディレクティブのある コンテナ中のドキュメントを圧縮するようにします:

SetOutputFilter DEFLATE

よく使われているブラウザでは、すべてのコンテンツに対する 圧縮を扱えるわけではありません。ですから、gzip-only-text/html ノートを 1 にして、html ファイルに対してのみ 圧縮が働くようにした方がよいかもしれません (以下参照) この値を 1 以外の値に設定した場合は無視されます。

通常、特定のMIMEタイプについてのみ圧縮したいのであれば、 AddOutputFilterByType ディレクティブを使用します。次に Apache のドキュメントの html ファイルのみの圧縮を有効にする例を示します。

<Directory "/your-server-root/manual">
AddOutputFilterByType DEFLATE text/html
 </Directory>

全てのファイルタイプでの圧縮に問題を抱えているブラウザに対しては、 BrowserMatch ディレクティブを使用して、特定のブラウザに no-gzip ノートをセットし、圧縮が行なわれないようにします。 no-gzip と gzip-only-text/html を組み合わせることで上手く対処できます。 この場合、前者が後者をオーバーライドします。 上記の設定例の抜粋を 次に示しますのでご覧下さい。

BrowserMatch ^Mozilla/4 gzip-only-text/html
BrowserMatch ^Mozilla/4\.0[678] no-gzip
BrowserMatch \bMSIE !no-gzip !gzip-only-text/html

まず始めに User-Agent 文字列から Netscape Navigator 4.x であるかどうかを調べます。これらのバージョンでは、 text/html 以外のタイプの圧縮を扱うことができません。 4.06, 4.07, 4.08 は html ファイルの伸張にも問題を抱えています。 ですからこれらに対しては、完全に deflate フィルタをオフにします。

3 番目の BrowserMatch ディレクティブで、推測したユーザーエージェントを修正します。 なぜなら Microsoft Internet Explorer も "Mozilla/4" と特定されますが、 これらは実際には圧縮を扱うことができるからです。 User-Agent ヘッダを "MSIE" (\b は「単語の境界」を意味します) の追加文字で検査して、 これ以前に設定した制限を再び解除します。

注

DEFLATE フィルタは必ず、PHP や SSI といった RESOURCE フィルタの後になります。 DEFLATE フィルタは内部的なサブリクエストを関知しません。

入力の伸張

mod_deflate モジュールは、gzip で圧縮されたリクエスト本体を伸張するフィルタも提供しています。 この機能を有効にするには、SetInputFilter か AddInputFilter を使用して、 DEFLATE フィルタを入力フィルタチェインに組み込みます。 例えば次のようになります。

<Location /dav-area>
SetInputFilter DEFLATE
 </Location>

この設定であれば、Content-Encoding: gzip ヘッダを含むリクエストが来ると、本体は自動的に伸張されます。 gzip リクエスト本体を送信するブラウザはあまりありません。 しかし、例えば WebDAV クライアントの幾つかなど、特別なアプリケーションでリクエストの 圧縮を実際にサポートしているものもあります。

Content-Length に関する注意

リクエスト本体それ自体を評価する場合は、Content-Length ヘッダを信用しないでください。Content-Length ヘッダは、 クライアントから送信されるデータの長さを反映しているのであって、 伸張されたデータストリームのバイトカウントではありません。

Proxy サーバでの扱い

mod_deflate モジュールは Vary: Accept-Encoding HTTP 応答ヘッダを送信して、適切な Accept-Encoding リクエストヘッダを送信するクライアントに対してのみ、 プロクシサーバがキャッシュした応答を送信するように注意を喚起します。 このようにして、圧縮を扱うことのできないクライアントに 圧縮された内容が送られることのないようにします。

もし特別に何かに依存して除外したい場合、例えば User-Agent ヘッダなどに依存している場合、手動で Vary ヘッダを設定して、 追加の制限についてプロクシサーバに注意を行なう必要があります。 例えば User-Agent に依存して DEFLATE を追加する典型的な設定では、次のように追加することになります。

Header append Vary User-Agent

リクエストヘッダ以外の情報 (例えば HTTP バージョン) に依存して圧縮するかどうか決める場合、 Vary ヘッダを * に設定する必要があります。 このようにすると、仕様に準拠したプロクシはキャッシュを全く行なわなくなります。

例

Header set Vary *

DeflateBufferSize ディレクティブ

説明: | zlib が一度に圧縮する塊の大きさ
構文: | DeflateBufferSize value
デフォルト: | DeflateBufferSize 8096
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_deflate

DeflateBufferSize ディレクティブは zlib が一度に圧縮する塊の大きさをバイト単位で指定します。

DeflateCompressionLevel ディレクティブ

説明: | 出力に対して行なう圧縮の程度
構文: | DeflateCompressionLevel value
デフォルト: | Zlib のデフォルト
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_deflate
互換性: | This directive is available since Apache 2.0.45

DeflateCompressionLevel ディレクティブは 圧縮の程度を設定します。大きな値では、より圧縮が行なわれますが、 CPU 資源を消費します。

値は 1 (低圧縮) から 9 (高圧縮) です。

DeflateFilterNote ディレクティブ

説明: | ロギング用に圧縮比をメモに追加
構文: | DeflateFilterNote [type] notename
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_deflate
互換性: | type is available since Apache 2.0.45

DeflateFilterNote ディレクティブは 圧縮比に関するメモがリクエストに付加されることを指定します。 メモ (note) の名前はディレクティブに指定された値です。 メモはアクセスログに 値を記録し、統計を取る目的にも使えます。

例

DeflateFilterNote ratio

LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
CustomLog logs/deflate_log deflate

ログからもっと精密な値を抽出したい場合は、type 引数を使用して、データタイプをログのメモとして残すように指定できます。 type は次のうちの一つです。

Input
フィルタの入力ストリームのバイトカウントをメモに保存する。
Output
フィルタの出力ストリームのバイトカウントをメモに保存する。
Ratio
圧縮率 (出力 / 入力 * 100) をメモに保存する。 type 引数を省略した場合は、これがデフォルトとなります。

まとめると、次のようにログを取ることになるでしょう。

精密なログ採取

DeflateFilterNote Input instream
DeflateFilterNote Output outstream
DeflateFilterNote Ratio ratio

LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
CustomLog logs/deflate_log deflate

参照

  • mod_log_config

DeflateMemLevel ディレクティブ

説明: | zlib が圧縮に使うメモリのレベルを指定
構文: | DeflateMemLevel value
デフォルト: | DeflateMemLevel 9
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_deflate

DeflateMemLevel ディレクティブは zlib が圧縮に使うメモリのレベルを設定します (1 から 9 の間の値)。 (訳注: 2 を底とする対数の値になります。 8 程度が良いでしょう。)

DeflateWindowSize ディレクティブ

説明: | Zlib の圧縮用ウィンドウの大きさ
構文: | DeflateWindowSize value
デフォルト: | DeflateWindowSize 15
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_deflate

DeflateWindowSize ディレクティブは zlib の圧縮用ウィンドウ (訳注: zlib で使用される履歴バッファ) の大きさを指定します (1 から 15 の間の値)。 一般的に大きなウィンドウサイズを使用すると圧縮率が向上します。 (訳注: 2 を底とする対数の値になります。 8 から 15 にするのが良いでしょう。)


mod_dir - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_dir

説明: | 「最後のスラッシュ」のリダイレクトと、ディレクトリの インデックスファイルを扱う機能を提供する
ステータス: | Base
モジュール識別子: | dir_module
ソースファイル: | mod_dir.c

概要

ディレクトリインデックスは、次の二つのうちどちらかが利用されます:

  • 一つ目は、ユーザが作成したファイルを用いるもので、通常 index.html というファイル名を使います。このファイル名は、 DirectoryIndex ディレクティブで 指定することができます。この機能は mod_dir モジュールで提供されます。
  • もう一つの方法は、 サーバによって自動的に生成されるディレクトリリストを用いる場合です。 この機能は、mod_autoindex モジュールにより提供されます。

自動的なインデックス生成機能を削除 (もしくは交換) できるように、この二つの機能は分離されています。

なお http://servername/foo/dirname という URL へのリクエストがあった際に、dirname というディレクトリがあれば、「最後にスラッシュをつけた形」の URL へのリダイレクトを送出します。 ディレクトリへのアクセスはスラッシュで終わっている必要があり、 mod_dir は、http://servername/foo/dirname/ へのリダイレクトを送出することになります。

DirectoryIndex ディレクティブ

説明: | クライアントがディレクトリをリクエストしたときに調べる リソースのリスト
構文: | DirectoryIndex local-url [local-url] ...
デフォルト: | DirectoryIndex index.html
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_dir

クライアントが、ディレクトリ名の最後に「/」 を指定してディレクトリインデックスを要求する場合に探すリソースのリストを DirectoryIndex ディレクティブで設定します。 Local-url は、リクエストされたディレクトリに対応する、サーバ上のドキュメントの (% エンコードされた) URL で、普通はディレクトリ中のファイルの名前です。 複数の URL が設定された場合には、最初に見つかったものを返します。 それらが見つからず、Indexes オプションがセットされている場合、ディレクトリのリストを生成します。

例

DirectoryIndex index.html

http://myserver/docs/ へのアクセスがあり、 http://myserver/docs/index.html が存在すれば、この URL が返されます。 もし存在しなければ、ディレクトリのリストが返されます。

注: ドキュメントが同じディレクトリ内に存在するは必要ありません。

DirectoryIndex index.html index.txt /cgi-bin/index.pl

とした場合、index.html と index.txt のどちらもディレクトリ内に存在しない場合、CGI スクリプト /cgi-bin/index.pl が実行されます。

DirectorySlash ディレクティブ

説明: | パス末尾のスラッシュでリダイレクトするかどうかのオンオフをトグルさせる
構文: | DirectorySlash On|Off
デフォルト: | DirectorySlash On
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_dir
互換性: | 2.0.51 以降

要求のあった URL がディレクトリを指すかどうかを、 mod_dir が調整するべきかどうかを DirectorySlash ディレクティブで設定します。

典型的には、ユーザが末尾のスラッシュ無しでリソースへのリクエストを発行し、 そして、そのリソースがディレクトリを指していた場合、mod_dir は、末尾にスラッシュを付加した上で同じリソースにリダイレクトさせます。 この挙動には幾つか理由があります:

  • ユーザは、最終的にはリソースの別名 URL をリクエストすることになる。
  • mod_autoindex が期待通りに動く。mod_autoindex の生成するリンクはパスを出力しませんので、スラッシュがない場合は間違ったパスを 指してしまうことになります。
  • DirectoryIndex は、 末尾にスラッシュがついているリクエストについてのみ評価される。
  • HTML ページの相対 URL 参照が正しく動作する。

とはいえ、もしこういった効果を望まない、かつ、 上記のような理由が当てはまらない場合は、リダイレクトを次のようにしてオフにできます:

# see security warning below!
<Location /some/path>
DirectorySlash Off
SetHandler some-handler
 </Location>

セキュリティ警告

末尾のスラッシュでのリダイレクトをオフにすると、結果的に情報漏洩を 招くことになるかもしれません。 mod_autoindex が有効 (Options +Indexes) で、 DirectoryIndex が有効なリソース (例えば index.html) を指していて、また、要求のあった URL に特別な ハンドラが設定されていない場合を考えてみてください。 この場合末尾にスラッシュのついているリクエストに対しては index.html ファイルが返されます。しかしスラッシュのないリクエストに対しては、 ディレクトリの内容一覧を返してしまいます。


mod_disk_cache - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_disk_cache

Description: | Content cache storage manager keyed to URIs
Status: | Experimental
Module?dentifier: | disk_cache_module
Source?ile: | mod_disk_cache.c

Summary

This module is experimental. Documentation is still under development...

mod_disk_cache implements a disk based storage manager. It is primarily of use in conjunction with mod_proxy.

Content is stored in and retrieved from the cache using URI based keys. Content with access protection is not cached.

Note:

mod_disk_cache requires the services of mod_cache.

CacheDirLength Directive

Description: | The number of characters in subdirectory names
Syntax: | CacheDirLength length
Default: | CacheDirLength 2
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

The CacheDirLength directive sets the number of characters for each subdirectory name in the cache hierarchy.

The result of CacheDirLevels* CacheDirLength must not be higher than 20.

CacheDirLength 4

CacheDirLevels Directive

Description: | The number of levels of subdirectories in the cache.
Syntax: | CacheDirLevels levels
Default: | CacheDirLevels 3
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

The CacheDirLevels directive sets the number of subdirectory levels in the cache. Cached data will be saved this many directory levels below the CacheRoot directory.

The result of CacheDirLevels* CacheDirLength must not be higher than 20.

CacheDirLevels 5

CacheExpiryCheck Directive

Description: | Indicates if the cache observes Expires dates when seeking files
Syntax: | CacheExpiryCheck On|Off
Default: | CacheExpiryCheck On
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

More detail will be added here, when the function is implemented.

CacheExpiryCheck Off

The CacheExpiryCheck directive is currently not implemented.

CacheGcClean Directive

Description: | The time to retain unchanged cached files that match a URL
Syntax: | CacheGcClean hours url-string
Default: | CacheGcClean ?
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

More detail will be added here, when the function is implemented.

CacheGcClean 12 /daily_scripts

The CacheGcClean directive is currently not implemented.

CacheGcDaily Directive

Description: | The recurring time each day for garbage collection to be run. (24 hour clock)
Syntax: | CacheGcDaily time
Default: | CacheGcDaily ?
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

More detail will be added here, when the function is implemented.

CacheGcDaily 23:59

The CacheGcDaily directive is currently not implemented.

CacheGcInterval Directive

Description: | The interval between garbage collection attempts.
Syntax: | CacheGcInterval hours
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

The CacheGcInterval directive specifies the number of hours to wait between attempts to free up disk space.

More detail will be added here, when the function is implemented.

CacheGcInterval 24

The CacheGcInterval directive is currently not implemented.

CacheGcMemUsage Directive

Description: | The maximum kilobytes of memory used for garbage collection
Syntax: | CacheGcMemUsage KBytes
Default: | CacheGcMemUsage ?
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

More detail will be added here, when the function is implemented.

CacheGcMemUsage 16

The CacheGcMemUsage directive is currently not implemented.

CacheGcUnused Directive

Description: | The time to retain unreferenced cached files that match a URL.
Syntax: | CacheGcUnused hours url-string
Default: | CacheGcUnused ?
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

More detail will be added here, when the function is implemented.

CacheGcUnused 12 /local_images

The CacheGcUnused directive is currently not implemented.

CacheMaxFileSize Directive

Description: | The maximum size (in bytes) of a document to be placed in the cache
Syntax: | CacheMaxFileSize bytes
Default: | CacheMaxFileSize 1000000
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

The CacheMaxFileSize directive sets the maximum size, in bytes, for a document to be considered for storage in the cache.

CacheMaxFileSize 64000

CacheMinFileSize Directive

Description: | The minimum size (in bytes) of a document to be placed in the cache
Syntax: | CacheMinFileSize bytes
Default: | CacheMinFileSize 1
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

The CacheMinFileSize directive sets the minimum size, in bytes, for a document to be considered for storage in the cache.

CacheMinFileSize 64

CacheRoot Directive

Description: | The directory root under which cache files are stored
Syntax: | CacheRoot directory
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

The CacheRoot directive defines the name of the directory on the disk to contain cache files. If the mod_disk_cache module has been loaded or compiled in to the Apache server, this directive must be defined. Failing to provide a value for CacheRoot will result in a configuration file processing error. The CacheDirLevels and CacheDirLength directives define the structure of the directories under the specified root directory.

CacheRoot c:/cacheroot

CacheSize Directive

Description: | The maximum amount of disk space that will be used by the cache in KBytes
Syntax: | CacheSize KBytes
Default: | CacheSize 1000000
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

The CacheSize directive sets the desired disk space usage of the cache, in KBytes (1024-byte units). This directive does not put a hard limit on the size of the cache. The garbage collector will delete files until the usage is at or below the settings. Always use a value that is lower than the available disk space.

CacheSize 5000000

CacheTimeMargin Directive

Description: | The minimum time margin to cache a document
Syntax: | CacheTimeMargin ?
Default: | CacheTimeMargin ?
Context: | server config, virtual host
Status: | Experimental
Module: | mod_disk_cache

More detail will be added here, when the function is implemented.

CacheTimeMargin X

The CacheTimeMargin directive is currently not implemented.


mod_echo - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_echo

説明: | プロトコルモジュールの概要を示すための単純なエコーサーバ
ステータス: | Experimental
モジュール識別子: | echo_module
ソースファイル: | mod_echo.c
互換性: | Apache 2.0 以降

概要

本モジュールはコンセプトを伝えるためのプロトコルモジュールの 実装例となっています。単純なエコーサーバを提供します。 Telnet で接続し、文字列を送信すると、エコーを返します。

ProtocolEcho ディレクティブ

説明: | エコーサーバの有効無効を設定します。
構文: | ProtocolEcho On|Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Experimental
モジュール: | mod_echo
互換性: | Apache 2.0 以降

ProtocolEcho ディレクティブで エコーサーバの有効無効を設定します。

例

ProtocolEcho On


mod_env - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_env

説明: | CGI スクリプト及び SSI ページに渡される環境変数を変更する機能を提供する
ステータス: | Base
モジュール識別子: | env_module
ソースファイル: | mod_env.c

概要

このモジュールにより CGI スクリプトと SSI ページに適用される環境変数を制御することができるようになります。 環境変数は httpd プロセスを起動したシェルから渡されます。また、 設定ファイルで環境変数を設定したり、削除したりすることができます。

参照

  • 環境変数

PassEnv ディレクティブ

説明: | シェルからの環境変数を渡す
構文: | PassEnv env-variable [env-variable] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_env

httpd プロセスを起動したシェルの環境から CGI スクリプトと SSI ページに渡す環境変数を一つ以上指定します。

例

PassEnv LD_LIBRARY_PATH

SetEnv ディレクティブ

説明: | 環境変数を設定する
構文: | SetEnv env-variable value
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_env

環境変数を設定し、それを CGI スクリプトと SSI ページに渡すようにします。

例

SetEnv SPECIAL_PATH /foo/bin

UnsetEnv ディレクティブ

説明: | 環境から変数を取り除く
構文: | UnsetEnv env-variable [env-variable] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_env

CGI スクリプトと SSI ページに渡される環境変数から指定された環境変数を取り除きます。

例

UnsetEnv LD_LIBRARY_PATH


mod_example - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_example

Description: | Illustrates the Apache module API
Status: | Experimental
Module?dentifier: | example_module
Source?ile: | mod_example.c

Summary

This document has not been updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

The files in the src/modules/example directory under the Apache distribution directory tree are provided as an example to those that wish to write modules that use the Apache API.

The main file is mod_example.c, which illustrates all the different callback mechanisms and call syntaxes. By no means does an add-on module need to include routines for all of the callbacks - quite the contrary!

The example module is an actual working module. If you link it into your server, enable the "example-handler" handler for a location, and then browse to that location, you will see a display of some of the tracing the example module did as the various callbacks were made.

Compiling the example module

To include the example module in your server, follow the steps below:

  1. Uncomment the "AddModule modules/example/mod_example" line near the bottom of the src/Configuration file. If there isn't one, add it; it should look like this:

    AddModule modules/example/mod_example.o

  2. Run the src/Configure script ("cd src; ./Configure"). This will build the Makefile for the server itself, and update the src/modules/Makefile for any additional modules you have requested from beneath that subdirectory.
  3. Make the server (run "make" in the src directory).

To add another module of your own:

  1. mkdir src/modules/mymodule
  2. cp src/modules/example/* src/modules/mymodule
  3. Modify the files in the new directory.
  4. Follow steps [1] through [3] above, with appropriate changes.

Using the mod_example Module

To activate the example module, include a block similar to the following in your srm.conf file:

<Location /example-info>
SetHandler example-handler
</Location>

As an alternative, you can put the following into a .htaccess file and then request the file "test.example" from that location:

AddHandler example-handler .example

After reloading/restarting your server, you should be able to browse to this location and see the brief display mentioned earlier.

Example Directive

Description: | Demonstration directive to illustrate the Apache module API
Syntax: | Example
Context: | server config, virtual host, directory, .htaccess
Status: | Experimental
Module: | mod_example

The Example directive just sets a demonstration flag which the example module's content handler displays. It takes no arguments. If you browse to an URL to which the example content-handler applies, you will get a display of the routines within the module and how and in what order they were called to service the document request. The effect of this directive one can observe under the point "Example directive declared here: YES/NO".


mod_expires - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_expires

説明: | ユーザの指定した基準に基づいた Expires と Cache-Control HTTP ヘッダの生成
ステータス: | Extension
モジュール識別子: | expires_module
ソースファイル: | mod_expires.c

概要

このモジュールはサーバ応答の Expires HTTP ヘッダ と Cache-Control ヘッダの max-age ディレクティブの 設定を制御します。元のファイルが作成された時刻または クライアントのアクセス時刻のどちらかに基づいて期限切れ日を 設定することができます。

これらのヘッダはクライアントに文書の 有効性と継続性を指示します。文書がキャッシュされた場合には、 指定時刻に達するまでは、元の場所から取得する代わりに キャッシュされているものを使うことができます。その後は、 キャッシュにあるコピーは期限切れ (expired) で無効であるとされ、 元の場所から新しいものを取得する必要があります。

max-age 以外 (RFC 2616 section 14.9 参照) の Cache-Control のディレクティブを 操作するには Header ディレクティブを 使うことができます。

代替期間指定構文

ExpiresDefault ディレクティブと ExpiresByType ディレクティブは 以下のより読み易い構文を使って定義することができます:

ExpiresDefault "<base> [plus] {<num> <type>}*"
ExpiresByType type/encoding "<base> [plus] {<num> <type>}*"

<base> は以下のどれかです:

  • access
  • now ('access' と等価)
  • modification

plus キーワードは省略可能です。<num> は (atoi() が受け付ける) 整数値、 <type> は以下のどれかです:

  • years
  • months
  • weeks
  • days
  • hours
  • minutes
  • seconds

例えば、以下のディレクティブはどれもデフォルトで文書がアクセスの 1 ヶ月後に 期限が切れるようにするために使えます:

ExpiresDefault "access plus 1 month"
ExpiresDefault "access plus 4 weeks"
ExpiresDefault "access plus 30 days"

期限切れ時刻はいくつか '<num> <type>' 節を追加することでより細かく 制御することができます:

ExpiresByType text/html "access plus 1 month 15 days 2 hours"
ExpiresByType image/gif "modification plus 5 hours 3 minutes"

修正時刻に基づいた設定を使用している場合、Expires ヘッダは ディスクのファイル以外のコンテンツには追加されないことに注意 してください。そのようなコンテンツには修正時刻は存在しないからです。

ExpiresActive ディレクティブ

説明: | Expires ヘッダの生成を有効にする
構文: | ExpiresActive On|Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Extension
モジュール: | mod_expires

このディレクティブは対応するドキュメントの領域で Expires と Cache-Controlヘッダを 有効にするか無効にするかを決めます。 (例えば、.htaccess ファイルではそのディレクトリの 文書のみに適用されるということです。) Off に 設定された場合は対応領域でそれらのヘッダは 生成されません (.htaccess がサーバ設定ファイルの設定を 上書きする、というような下位レベルでの上書きがされていなければ)。 On に設定されていれば、ヘッダは ExpiresByType ディレクティブと ExpiresDefault ディレクティブ の基準に従って文書にヘッダを追加します (各ディレクティブ参照)。

このディレクティブは Expires と Cache-Control ヘッダの存在を 保証するわけではないことに注意してください。基準が満たされて いない場合はヘッダは追加されず、結果としてこのディレクティブが 指定されていなかったかのようにさえ見えることになります。

ExpiresByType ディレクティブ

説明: | MIME タイプによって設定される Expires ヘッダの値
構文: | ExpiresByType MIME-type <code>seconds
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Extension
モジュール: | mod_expires

このディレクティブは指定されたタイプのドキュメント (例えば text/html) に対して生成される Expires ヘッダと Cache-Control ヘッダの max-age ディレクティブの値を定義します。 二つ目の引数は期限切れの日時を生成するための基準時刻に追加される 秒数を設定します。Cache-Control: max-age は期限切れの時刻からリクエスト時刻を引いたものを秒で 表すことで生成されます。

基準時刻はファイルの最終修正時刻か、クライアントのドキュメントへの アクセス時刻です。どちらを使うべきかは <code> によって指定します。M は基準時刻として ファイルの最終修正時刻をという意味で、A はクライアントの アクセス時刻を使うという意味になります。

効果には微妙な違いがあります。M が使用された場合は、 すべてのキャッシュにある現在のドキュメントキャッシュは同時に期限が 切れます。これは同じ URL に毎週常に置かれる報せのようなものには 非常に有効です。A が使用された場合は、期限切れの 時間は各クライアントよって異なります。これはあまり変更されない 画像ファイルなど、特に関連するドキュメント群がすべて同じ画像を 参照するとき (すなわち画像が比較的短い期間内に繰り返し アクセスされるとき) に有効です。

例:

# enable expirations
ExpiresActive On
# expire GIF images after a month in the client's cache
ExpiresByType image/gif A2592000
# HTML documents are good for a week from the
# time they were changed
ExpiresByType text/html M604800

このディレクティブは ExpiresActive On が指定されている ときのみ有効であることに注意してください。これは、 指定された MIME タイプに対してのみ ExpiresDefault ディレクティブで 設定された期限切れ期日を上書きします。

この文書の前の方で説明されている代替構文を 使って期限切れ期日の計算方法を指定することもできます。

ExpiresDefault ディレクティブ

説明: | 期限切れ期日を計算するデフォルトアルゴリズム
構文: | ExpiresDefault <code>seconds
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Extension
モジュール: | mod_expires

このディレクティブは対応する範囲のすべてのドキュメントに対して デフォルトの期限切れ期日の計算アルゴリズムを設定します。ExpiresByType ディレクティブによって タイプ毎に上書きすることができます。引数の構文はそのディレクティブの 説明を参照してください。また、代替構文も 参照してください。


mod_ext_filter - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_ext_filter

Description: | Pass the response body through an external program before delivery to the client
Status: | Extension
Module?dentifier: | ext_filter_module
Source?ile: | mod_ext_filter.c

Summary

mod_ext_filter presents a simple and familiar programming model for filters. With this module, a program which reads from stdin and writes to stdout (i.e., a Unix-style filter command) can be a filter for Apache. This filtering mechanism is much slower than using a filter which is specially written for the Apache API and runs inside of the Apache server process, but it does have the following benefits:

  • the programming model is much simpler
  • any programming/scripting language can be used, provided that it allows the program to read from standard input and write to standard output
  • existing programs can be used unmodified as Apache filters

Even when the performance characteristics are not suitable for production use, mod_ext_filter can be used as a prototype environment for filters.

See also

  • Filters

Examples

Generating HTML from some other type of response

# mod_ext_filter directive to define a filter
# to HTML-ize text/c files using the external
# program /usr/bin/enscript, with the type of
# the result set to text/html
ExtFilterDefine c-to-html mode=output \
intype=text/c outtype=text/html \
cmd="/usr/bin/enscript --color -W html -Ec -o - -"
<Directory "/export/home/trawick/apacheinst/htdocs/c">
# core directive to cause the new filter to
# be run on output
SetOutputFilter c-to-html

# mod_mime directive to set the type of .c
# files to text/c
AddType text/c .c

# mod_ext_filter directive to set the debug
# level just high enough to see a log message
# per request showing the configuration in force
ExtFilterOptions DebugLevel=1
 </Directory>

Implementing a content encoding filter

Note: this gzip example is just for the purposes of illustration. Please refer to mod_deflate for a practical implementation.

# mod_ext_filter directive to define the external filter
ExtFilterDefine gzip mode=output cmd=/bin/gzip

<Location /gzipped>
# core directive to cause the gzip filter to be
# run on output
SetOutputFilter gzip

# mod_header directive to add
# "Content-Encoding: gzip" header field
Header set Content-Encoding gzip
 </Location>

Slowing down the server

# mod_ext_filter directive to define a filter
# which runs everything through cat; cat doesn't
# modify anything; it just introduces extra pathlength
# and consumes more resources
ExtFilterDefine slowdown mode=output cmd=/bin/cat \
preservescontentlength
<Location />
# core directive to cause the slowdown filter to
# be run several times on output
#
SetOutputFilter slowdown;slowdown;slowdown
 </Location>

Using sed to replace text in the response

# mod_ext_filter directive to define a filter which
# replaces text in the response
#
ExtFilterDefine fixtext mode=output intype=text/html \
cmd="/bin/sed s/verdana/arial/g"
<Location />
# core directive to cause the fixtext filter to
# be run on output
SetOutputFilter fixtext
 </Location>

Tracing another filter

# Trace the data read and written by mod_deflate
# for a particular client (IP 192.168.1.31)
# experiencing compression problems.
# This filter will trace what goes into mod_deflate.
ExtFilterDefine tracebefore \
cmd="/bin/tracefilter.pl /tmp/tracebefore" \
EnableEnv=trace_this_client
# This filter will trace what goes after mod_deflate.
# Note that without the ftype parameter, the default
# filter type of AP_FTYPE_RESOURCE would cause the
# filter to be placed *before* mod_deflate in the filter
# chain. Giving it a numeric value slightly higher than
# AP_FTYPE_CONTENT_SET will ensure that it is placed
# after mod_deflate.
ExtFilterDefine traceafter \
cmd="/bin/tracefilter.pl /tmp/traceafter" \
EnableEnv=trace_this_client ftype=21
<Directory /usr/local/docs>
SetEnvIf Remote_Addr 192.168.1.31 trace_this_client
SetOutputFilter tracebefore;deflate;traceafter
 </Directory>

Here is the filter which traces the data:

#!/usr/local/bin/perl -w
use strict;

open(SAVE, ">$ARGV[0]")
or die "can't open $ARGV[0]: $?";
while (<STDIN>) {
print SAVE $_;
print $_;
 }

close(SAVE);

ExtFilterDefine Directive

Description: | Define an external filter
Syntax: | ExtFilterDefine filtername parameters
Context: | server config
Status: | Extension
Module: | mod_ext_filter

The ExtFilterDefine directive defines the characteristics of an external filter, including the program to run and its arguments.

filtername specifies the name of the filter being defined. This name can then be used in SetOutputFilter directives. It must be unique among all registered filters. At the present time, no error is reported by the register-filter API, so a problem with duplicate names isn't reported to the user.

Subsequent parameters can appear in any order and define the external command to run and certain other characteristics. The only required parameter is cmd=. These parameters are:

cmd=cmdline
The cmd= keyword allows you to specify the external command to run. If there are arguments after the program name, the command line should be surrounded in quotation marks (e.g., cmd="/bin/mypgm arg1 arg2". Normal shell quoting is not necessary since the program is run directly, bypassing the shell. Program arguments are blank-delimited. A backslash can be used to escape blanks which should be part of a program argument. Any backslashes which are part of the argument must be escaped with backslash themselves. In addition to the standard CGI environment variables, DOCUMENT_URI, DOCUMENT_PATH_INFO, and QUERY_STRING_UNESCAPED will also be set for the program.
mode=mode
mode should be output for now (the default). In the future, mode=input will be used to specify a filter for request bodies.
intype=imt
This parameter specifies the internet media type (i.e., MIME type) of documents which should be filtered. By default, all documents are filtered. If intype= is specified, the filter will be disabled for documents of other types.
outtype=imt
This parameter specifies the internet media type (i.e., MIME type) of filtered documents. It is useful when the filter changes the internet media type as part of the filtering operation. By default, the internet media type is unchanged.
PreservesContentLength
The PreservesContentLength keyword specifies that the filter preserves the content length. This is not the default, as most filters change the content length. In the event that the filter doesn't modify the length, this keyword should be specified.
ftype=filtertype
This parameter specifies the numeric value for filter type that the filter should be registered as. The default value, AP_FTYPE_RESOURCE, is sufficient in most cases. If the filter needs to operate at a different point in the filter chain than resource filters, then this parameter will be necessary. See the AP_FTYPE_foo definitions in util_filter.h for appropriate values.
disableenv=env
This parameter specifies the name of an environment variable which, if set, will disable the filter.
enableenv=env
This parameter specifies the name of an environment variable which must be set, or the filter will be disabled.

ExtFilterOptions Directive

Description: | Configure mod_ext_filter options
Syntax: | ExtFilterOptions option [option] ...
Default: | ExtFilterOptions DebugLevel=0 NoLogStderr
Context: | directory
Status: | Extension
Module: | mod_ext_filter

The ExtFilterOptions directive specifies special processing options for mod_ext_filter. Option can be one of

DebugLevel=n
The DebugLevel keyword allows you to specify the level of debug messages generated by mod_ext_filter. By default, no debug messages are generated. This is equivalent to DebugLevel=0. With higher numbers, more debug messages are generated, and server performance will be degraded. The actual meanings of the numeric values are described with the definitions of the DBGLVL_ constants near the beginning of mod_ext_filter.c.

Note: The core directive LogLevel should be used to cause debug messages to be stored in the Apache error log.

LogStderr | NoLogStderr
The LogStderr keyword specifies that messages written to standard error by the external filter program will be saved in the Apache error log. NoLogStderr disables this feature.

Example

ExtFilterOptions LogStderr DebugLevel=0

Messages written to the filter's standard error will be stored in the Apache error log. No debug messages will be generated by mod_ext_filter.


mod_file_cache - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_file_cache

Description: | Caches a static list of files in memory
Status: | Experimental
Module?dentifier: | file_cache_module
Source?ile: | mod_file_cache.c

Summary

This module should be used with care. You can easily create a broken site using mod_file_cache, so read this document carefully.

Caching frequently requested files that change very infrequently is a technique for reducing server load. mod_file_cache provides two techniques for caching frequently requested static files. Through configuration directives, you can direct mod_file_cache to either open then mmap() a file, or to pre-open a file and save the file's open file handle. Both techniques reduce server load when processing requests for these files by doing part of the work (specifically, the file I/O) for serving the file when the server is started rather than during each request.

Notice: You cannot use this for speeding up CGI programs or other files which are served by special content handlers. It can only be used for regular files which are usually served by the Apache core content handler.

This module is an extension of and borrows heavily from the mod_mmap_static module in Apache 1.3.

Using mod_file_cache

mod_file_cache caches a list of statically configured files via MMapFile or CacheFile directives in the main server configuration.

Not all platforms support both directives. For example, Apache on Windows does not currently support the MMapStatic directive, while other platforms, like AIX, support both. You will receive an error message in the server error log if you attempt to use an unsupported directive. If given an unsupported directive, the server will start but the file will not be cached. On platforms that support both directives, you should experiment with both to see which works best for you.

MMapFile Directive

The MMapFile directive of mod_file_cache maps a list of statically configured files into memory through the system call mmap(). This system call is available on most modern Unix derivates, but not on all. There are sometimes system-specific limits on the size and number of files that can be mmap()ed, experimentation is probably the easiest way to find out.

This mmap()ing is done once at server start or restart, only. So whenever one of the mapped files changes on the filesystem you have to restart the server (see the Stopping and Restarting documentation). To reiterate that point: if the files are modified in place without restarting the server you may end up serving requests that are completely bogus. You should update files by unlinking the old copy and putting a new copy in place. Most tools such as rdist and mv do this. The reason why this modules doesn't take care of changes to the files is that this check would need an extra stat() every time which is a waste and against the intent of I/O reduction.

CacheFile Directive

The CacheFile directive of mod_file_cache opens an active handle or file descriptor to the file (or files) listed in the configuration directive and places these open file handles in the cache. When the file is requested, the server retrieves the handle from the cache and passes it to the sendfile() (or TransmitFile() on Windows), socket API.

This file handle caching is done once at server start or restart, only. So whenever one of the cached files changes on the filesystem you have to restart the server (see the Stopping and Restarting documentation). To reiterate that point: if the files are modified in place without restarting the server you may end up serving requests that are completely bogus. You should update files by unlinking the old copy and putting a new copy in place. Most tools such as rdist and mv do this.

Note

Don't bother asking for a directive which recursively caches all the files in a directory. Try this instead... See the Include directive, and consider this command:

find /www/htdocs -type f -print \
| sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf

CacheFile Directive

Description: | Cache a list of file handles at startup time
Syntax: | CacheFile file-path [file-path] ...
Context: | server config
Status: | Experimental
Module: | mod_file_cache

The CacheFile directive opens handles to one or more files (given as whitespace separated arguments) and places these handles into the cache at server startup time. Handles to cached files are automatically closed on a server shutdown. When the files have changed on the filesystem, the server should be restarted to to re-cache them.

Be careful with the file-path arguments: They have to literally match the filesystem path Apache's URL-to-filename translation handlers create. We cannot compare inodes or other stuff to match paths through symbolic links etc. because that again would cost extra stat() system calls which is not acceptable. This module may or may not work with filenames rewritten by mod_alias or mod_rewrite.

Example

CacheFile /usr/local/apache/htdocs/index.html

MMapFile Directive

Description: | Map a list of files into memory at startup time
Syntax: | MMapFile file-path [file-path] ...
Context: | server config
Status: | Experimental
Module: | mod_file_cache

The MMapFile directive maps one or more files (given as whitespace separated arguments) into memory at server startup time. They are automatically unmapped on a server shutdown. When the files have changed on the filesystem at least a HUP or USR1 signal should be send to the server to re-mmap() them.

Be careful with the file-path arguments: They have to literally match the filesystem path Apache's URL-to-filename translation handlers create. We cannot compare inodes or other stuff to match paths through symbolic links etc. because that again would cost extra stat() system calls which is not acceptable. This module may or may not work with filenames rewritten by mod_alias or mod_rewrite.

Example

MMapFile /usr/local/apache/htdocs/index.html


mod_headers - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_headers

Description: | Customization of HTTP request and response headers
Status: | Extension
Module?dentifier: | headers_module
Source?ile: | mod_headers.c
Compatibility: | RequestHeader is available only in Apache 2.0

Summary

This module provides directives to control and modify HTTP request and response headers. Headers can be merged, replaced or removed.

Order of Processing

The directives provided by mod_headers can occur almost anywhere within the server configuration. They are valid in the main server config and virtual host sections, inside <Directory>, <Location> and <Files> sections, and within .htaccess files.

The directives are processed in the following order:

  1. main server
  2. virtual host
  3. <Directory> sections and .htaccess
  4. <Files>
  5. <Location>

Order is important. These two headers have a different effect if reversed:

RequestHeader append MirrorID "mirror 12"
RequestHeader unset MirrorID

This way round, the MirrorID header is not set. If reversed, the MirrorID header is set to "mirror 12".

Examples

  1. Copy all request headers that begin with "TS" to the response headers:

    Header echo ^TS

  2. Add a header, MyHeader, to the response including a timestamp for when the request was received and how long it took to begin serving the request. This header can be used by the client to intuit load on the server or in isolating bottlenecks between the client and the server.

    Header add MyHeader "%D %t"

    results in this header being added to the response:

    MyHeader: D=3775428 t=991424704447256

  3. Say hello to Joe

    Header add MyHeader "Hello Joe. It took %D microseconds \
    for Apache to serve this request."

    results in this header being added to the response:

    MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.

  4. Conditionally send MyHeader on the response if and only if header "MyRequestHeader" is present on the request. This is useful for constructing headers in response to some client stimulus. Note that this example requires the services of the mod_setenvif module.

    SetEnvIf MyRequestHeader value HAVE_MyRequestHeader
    Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader

    If the header MyRequestHeader: value is present on the HTTP request, the response will contain the following header:

    MyHeader: D=3775428 t=991424704447256 mytext

Header Directive

Description: | Configure HTTP response headers
Syntax: | Header [condition] set|append|add|unset|echo header [value] [env=[!]variable]
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_headers
Compatibility: | Condition is available in version 2.0.51 and later

This directive can replace, merge or remove HTTP response headers. The header is modified just after the content handler and output filters are run, allowing outgoing headers to be modified.

The optional condition can be either onsuccess or always. It determines, which internal header table should be operated on. onsuccess stands for 2xx status codes and always for all status codes (including 2xx). Especially if you want to unset headers set by certain modules, you should try out, which table is affected.

The action it performs is determined by the second argument. This can be one of the following values:

set
The response header is set, replacing any previous header with this name. The value may be a format string.
append
The response header is appended to any existing header of the same name. When a new value is merged onto an existing header it is separated from the existing header with a comma. This is the HTTP standard way of giving a header multiple values.
add
The response header is added to the existing set of headers, even if this header already exists. This can result in two (or more) headers having the same name. This can lead to unforeseen consequences, and in general "append" should be used instead.
unset
The response header of this name is removed, if it exists. If there are multiple headers of the same name, all will be removed.
echo
Request headers with this name are echoed back in the response headers. header may be a regular expression.

This argument is followed by a header name, which can include the final colon, but it is not required. Case is ignored for set, append, add and unset. The header name for echo is case sensitive and may be a regular expression.

For add, append and set a value is specified as the third argument. If value contains spaces, it should be surrounded by doublequotes. value may be a character string, a string containing format specifiers or a combination of both. The following format specifiers are supported in value:

%t | The time the request was received in Universal Coordinated Time since the epoch (Jan. 1, 1970) measured in microseconds. The value is preceded by t=.
%D | The time from when the request was received to the time the headers are sent on the wire. This is a measure of the duration of the request. The value is preceded by D=.
%{FOOBAR}e | The contents of the environment variable FOOBAR.

When the Header directive is used with the add, append, or set argument, a fourth argument may be used to specify conditions under which the action will be taken. If the environment variable specified in the env=... argument exists (or if the environment variable does not exist and env=!... is specified) then the action specified by the Header directive will take effect. Otherwise, the directive will have no effect on the request.

The Header directives are processed just before the response is sent to the network. These means that it is possible to set and/or override most headers, except for those headers added by the header filter.

RequestHeader Directive

Description: | Configure HTTP request headers
Syntax: | RequestHeader set|append|add|unset header [value]
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_headers

This directive can replace, merge or remove HTTP request headers. The header is modified just before the content handler is run, allowing incoming headers to be modified. The action it performs is determined by the first argument. This can be one of the following values:

set
The request header is set, replacing any previous header with this name
append
The request header is appended to any existing header of the same name. When a new value is merged onto an existing header it is separated from the existing header with a comma. This is the HTTP standard way of giving a header multiple values.
add
The request header is added to the existing set of headers, even if this header already exists. This can result in two (or more) headers having the same name. This can lead to unforeseen consequences, and in general append should be used instead.
unset
The request header of this name is removed, if it exists. If there are multiple headers of the same name, all will be removed.

This argument is followed by a header name, which can include the final colon, but it is not required. Case is ignored. For add, append and set a value is given as the third argument. If value contains spaces, it should be surrounded by double quotes. For unset, no value should be given.

The RequestHeader directive is processed just before the request is run by its handler in the fixup phase. This should allow headers generated by the browser, or by Apache input filters to be overridden or modified.


mod_imap - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_imap

Description: | Server-side imagemap processing
Status: | Base
Module?dentifier: | imap_module
Source?ile: | mod_imap.c

Summary

This module processes .map files, thereby replacing the functionality of the imagemap CGI program. Any directory or document type configured to use the handler imap-file (using either AddHandler or SetHandler) will be processed by this module.

The following directive will activate files ending with .map as imagemap files:

AddHandler imap-file map

Note that the following is still supported:

AddType application/x-httpd-imap map

However, we are trying to phase out "magic MIME types" so we are deprecating this method.

New Features

The imagemap module adds some new features that were not possible with previously distributed imagemap programs.

  • URL references relative to the Referer: information.
  • Default <base> assignment through a new map directive base.
  • No need for imagemap.conf file.
  • Point references.
  • Configurable generation of imagemap menus.

Imagemap File

The lines in the imagemap files can have one of several formats:

directive value [x,y ...]
directive value "Menu text" [x,y ...]
directive value x,y ... "Menu text"

The directive is one of base, default, poly, circle, rect, or point. The value is an absolute or relative URL, or one of the special values listed below. The coordinates are x,y pairs separated by whitespace. The quoted text is used as the text of the link if a imagemap menu is generated. Lines beginning with '#' are comments.

Imagemap File Directives

There are six directives allowed in the imagemap file. The directives can come in any order, but are processed in the order they are found in the imagemap file.

base Directive

Has the effect of <base href="value"> . The non-absolute URLs of the map-file are taken relative to this value. The base directive overrides ImapBase as set in a .htaccess file or in the server configuration files. In the absence of an ImapBase configuration directive, base defaults to http://server_name/.

base_uri is synonymous with base. Note that a trailing slash on the URL is significant.

default Directive
The action taken if the coordinates given do not fit any of the poly, circle or rect directives, and there are no point directives. Defaults to nocontent in the absence of an ImapDefault configuration setting, causing a status code of 204 No Content to be returned. The client should keep the same page displayed.
poly Directive
Takes three to one-hundred points, and is obeyed if the user selected coordinates fall within the polygon defined by these points.
circle
Takes the center coordinates of a circle and a point on the circle. Is obeyed if the user selected point is with the circle.
rect Directive
Takes the coordinates of two opposing corners of a rectangle. Obeyed if the point selected is within this rectangle.
point Directive
Takes a single point. The point directive closest to the user selected point is obeyed if no other directives are satisfied. Note that default will not be followed if a point directive is present and valid coordinates are given.

Values

The values for each of the directives can any of the following:

a URL

The URL can be relative or absolute URL. Relative URLs can contain '..' syntax and will be resolved relative to the base value.

base itself will not resolved according to the current value. A statement base mailto: will work properly, though.

map
Equivalent to the URL of the imagemap file itself. No coordinates are sent with this, so a menu will be generated unless ImapMenu is set to none.
menu
Synonymous with map.
referer
Equivalent to the URL of the referring document. Defaults to http://servername/ if no Referer: header was present.
nocontent
Sends a status code of 204 No Content, telling the client to keep the same page displayed. Valid for all but base.
error
Fails with a 500 Server Error. Valid for all but base, but sort of silly for anything but default.

Coordinates

0,0 200,200
A coordinate consists of an x and a y value separated by a comma. The coordinates are separated from each other by whitespace. To accommodate the way Lynx handles imagemaps, should a user select the coordinate 0,0, it is as if no coordinate had been selected.

Quoted Text

"Menu Text"

After the value or after the coordinates, the line optionally may contain text within double quotes. This string is used as the text for the link if a menu is generated:

<a href="http://foo.com/">Menu text</a>

If no quoted text is present, the name of the link will be used as the text:

<a href="http://foo.com/">http://foo.com</a>

If you want to use double quotes within this text, you have to write them as &quot;.

Example Mapfile

#Comments are printed in a 'formatted' or 'semiformatted' menu.
#And can contain html tags. <hr>
base referer
poly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0
rect .. 0,0 77,27 "the directory of the referer"
circle http://www.inetnebr.com/lincoln/feedback/ 195,0 305,27
rect another_file "in same directory as referer" 306,0 419,27
point http://www.zyzzyva.com/ 100,100
point http://www.tripod.com/ 200,200
rect mailto:nate@tripod.com 100,150 200,0 "Bugs?"

Referencing your mapfile

HTML example

<a href="/maps/imagemap1.map">
<img ismap src="/images/imagemap1.gif">
 </a>

XHTML example

<a href="/maps/imagemap1.map">
<img ismap="ismap" src="/images/imagemap1.gif" />
 </a>

ImapBase Directive

Description: | Default base for imagemap files
Syntax: | ImapBase map|referer|URL
Default: | ImapBase http://servername/
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Base
Module: | mod_imap

The ImapBase directive sets the default base used in the imagemap files. Its value is overridden by a base directive within the imagemap file. If not present, the base defaults to http://servername/.

See also

  • UseCanonicalName

ImapDefault Directive

Description: | Default action when an imagemap is called with coordinates that are not explicitly mapped
Syntax: | ImapDefault error|nocontent|map|referer|URL
Default: | ImapDefault nocontent
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Base
Module: | mod_imap

The ImapDefault directive sets the default default used in the imagemap files. Its value is overridden by a default directive within the imagemap file. If not present, the default action is nocontent, which means that a 204 No Content is sent to the client. In this case, the client should continue to display the original page.

ImapMenu Directive

Description: | Action if no coordinates are given when calling an imagemap
Syntax: | ImapMenu none|formatted|semiformatted|unformatted
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Base
Module: | mod_imap

The ImapMenu directive determines the action taken if an imagemap file is called without valid coordinates.

none
If ImapMenu is none, no menu is generated, and the default action is performed.
formatted
A formatted menu is the simplest menu. Comments in the imagemap file are ignored. A level one header is printed, then an hrule, then the links each on a separate line. The menu has a consistent, plain look close to that of a directory listing.
semiformatted
In the semiformatted menu, comments are printed where they occur in the imagemap file. Blank lines are turned into HTML breaks. No header or hrule is printed, but otherwise the menu is the same as a formatted menu.
unformatted
Comments are printed, blank lines are ignored. Nothing is printed that does not appear in the imagemap file. All breaks and headers must be included as comments in the imagemap file. This gives you the most flexibility over the appearance of your menus, but requires you to treat your map files as HTML instead of plaintext.


mod_include - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_include

説明: | サーバがパースする html ドキュメント (Server Side Includes)
ステータス: | Base
モジュール識別子: | include_module
ソースファイル: | mod_include.c
互換性: | Apache 2.0 から出力フィルタとして実装されました。

概要

このモジュールはファイルがクライアントに送られる前に処理するフィルタを 提供します。処理の内容は要素と呼ばれる特別な形式の SGML コメントにより 制御されます。これらの要素は条件分岐や、他のファイルや プログラムの出力の取り込み、環境変数の設定や表示を行なうことが できます。

参照

  • Options
  • AcceptPathInfo
  • 国際化されたカスタムサーバエラーメッセージ
  • フィルタ
  • SSI チュートリアル

Server-Side Includes を有効にする

Server Side Includes は INCLUDES フィルタ により実装されています。 Server-side include のディレクティブを含むドキュメントの拡張子が .shtml の場合、以下のディレクティブでは Apache がそれらを パースして、その結果できるドキュメントに text/html の MIME タイプを割り当てます:

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

以下のディレクティブは shtml ファイルのあるディレクトリで指定されている 必要があります (通常は <Directory> セクションで指定しますが、 AllowOverride Options が設定されていると、.htaccess ファイルに書くこともできます):

Options +Includes

互換性を保つために、server-parsed ハンドラ も INCLUDES フィルタを 有効にします。MIME タイプ text/x-server-parsed-html や text/x-server-parsed-html3 のドキュメントに対しても Apache は INCLUDES フィルタを有効にします (出力されるものは MIME タイプ text/html になります)。

詳しい情報は Tutorial on Server Side Includes.

サーバサイドインクルード (SSI) での PATH_INFO

SSI で処理されるファイルはデフォルトでは PATH_INFO (後続のパス名情報) 付きのリクエストを受け入れなくなりました。AcceptPathInfo ディレクティブで PATH_INFO 付きのリクエストを受け入れるようにサーバを 設定できます。

基本要素

ドキュメントは、SGML のコメントとして特別なコマンドが埋め込まれた HTML ドキュメントとしてパースされます。コマンドの構文は次のように なっています:

<!--#element attribute=value attribute=value ... -->

値 (訳注: value) は二重引用符で囲むのが一般的ですが、 シングルクオート (') とバッククオート (`) も使用できます。 多くのコマンドは属性-値 (訳注: attribute-value) の組を一つだけ指定できます。 コメントの終わり (-->) の前には、SSI の句の一部だと解釈されないようにするために空白を 入れてください。最初の <!--# はまとめて一つの 句で、空白をふくんではいけないこと注意してください。

要素 (訳注: element) を以下の表に示します。

要素 | 説明
config | configure output formats
echo | print variables
exec | execute external programs
fsize | print size of a file
flastmod | print last modification time of a file
include | include a file
printenv | print all available variables
set | set a value of a variable

SSI 要素は mod_include 以外のモジュールで 定義されることもあります。実際、 exec 要素は mod_cgi で提供されていて、このモジュールが ロードされる場合にのみ利用可能となります。

config 要素

次のコマンドは解析の様々な側面を制御します。属性は次の通りです。

errmsg
この値が、ドキュメントの解析中にエラーが発生した時に クライアントに送信されるメッセージになります。これは SSIErrorMsg ディレクティブを上書きします。
sizefmt
この値は、ファイルのサイズを表示する際に使用する フォーマットを設定します。値は バイトカウントの bytesか、Kb や Mb を優先的に使用する abbrec (例えば 1024 バイトは "1K" と表示されます) です。
timefmt
この値は strftime(3) ライブラリルーチンが 日時をプリントする際に用いられます。

echo 要素

このコマンドは以下で定義されている include 変数 を表示します。変数が設定されていない場合は SSIUndefinedEcho ディレクティブで 決定される結果となります。日付はその時点での timefmt に従って 表示されます。属性は次の通りです。

var
値は表示する変数の名前です。
encoding

変数を出力する前に、変数中の特別文字をどのようにエンコードするかを 指定します。none に設定されていると、エンコードは行なわれません。 url に設定されていると、URL エンコード (%-エンコードとも 呼ばれています。これはリンク等の URL の使用に適切です) が 行なわれます。echo 要素の開始時は、デフォルトは entity に設定されています。これはエンティティエンコード (段落やテキストなどのブロックレベルの HTML エレメントのコンテキストに 適しています) を行ないます。これは encoding 属性 を加えることで変更できます。変更は次の encoding 属性か、 要素の終了まで効力を持ちます。

encoding 属性はエンコードの変更をしたい var の前に ある必要があることに注意してください。 また、ISO-8859-1 エンコーディングで 定義されている特別な文字だけがエンコードされます。 別の文字のエンコーディングの場合は、このエンコーディングは 望みの結果にならないかもしれません。

クロスサイトスクリプティングの問題を避けるために、 常にユーザからのデータをエンコードすべきです。

exec 要素

exec コマンドは指定されたシェルコマンドや CGI スクリプトを 実行します。mod_cgi がサーバに組み込まれているいなければ なりません。Option IncludesNOEXEC はこのコマンドを無効にします。 使用可能な属性は次の通りです。

cgi

値は (%-エンコードされた) URL を指定します。パスが スラッシュ (/) で始まらないときは、ドキュメントからの 相対パスとして扱われます。このパスで参照されているドキュメントは サーバが CGI スクリプトとして扱っていなくても CGI スクリプトとして 起動されます。ただし、スクリプトのあるディレクトリでは (ScriptAlias や Option ExecCGI によって) CGI スクリプトの使用が許可されている必要があります。

CGI スクリプトには、クライアントからの元々のリクエストの PATH_INFO とクエリー文字列 (QUERY_STRING) が渡されます。 これらは URL パスとして特定できないものです。 スクリプトは標準 CGI 環境に加えて、include 変数を 使用することができます。

例

<!--#exec cgi="/cgi-bin/example.cgi" -->

スクリプトが、出力の代わりに Location: ヘッダを返すと、 HTML のアンカー (訳注：リンク) に変換されます。

exec cgi よりも、 include virtual の方を使うようにしてください。特に、CGI への追加の引数を クエリー文字列を使って渡すことは exec cgi は できませんが、include virtual は以下のようにして 可能です。

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

cmd

サーバは指定された文字列を /bin/sh を使って 実行します。コマンドは通常の CGI 変数に加えて include 変数も使うことができます。

ほとんどの場合、#include virtual を使う方が #exec cgi や #exec cmd を使うよりも良いです。前者 (#include virtual) は標準の Apache のサブリクエスト機構を使ってファイルやスクリプトの 出力を取り込みます。 こちらの方がよくテストされメンテナンスされた方法です。

さらに、Win32 のようないくつかのプラットフォームや、suexec を使っている unix では、 exec ディレクティブのコマンドに 引数を渡したり、コマンドに空白を入れることはできません。 ですから、以下のものは unix の suexec でない設定では動作しますが、 Win32 や suexec を使っている unix では期待した結果にはなりません:

<!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->

fsize 要素

このコマンドは指定されたファイルの大きさを sizefmt の 書式指定に基づいて出力します。属性は次の通りです。

file
値は解析されているドキュメントの存在するディレクトリからの 相対パスです。
virtual
値は (% エンコードされた) URL-path です。スラッシュ (/) で 始まらないときはドキュメントからの相対パスとして扱われます。 CGI の出力のサイズはプリントされません。CGI スクリプト自体のサイズがプリントされることに注意してください。

flastmod 要素

このコマンドは指定されたファイルの最終修正時刻を timefmt 書式指定に従って表示します。 指定可能な属性は fsize コマンドと同じです。

include 要素

このコマンドは別の文書やファイルのテキストを解析しているファイルに 挿入します。挿入されるファイルはアクセス制御の管理下にあります。 解析しているファイルの存在するディレクトリに Option IncludesNOEXEC が設定されている場合、text MIME タイプ (text/plain, text/html 等) のドキュメントのみインクルードが行なわれます。 その他の場合は、クエリー文字列も含め、コマンドで指定された 完全な URL を使って普通に CGI スクリプトが呼び出されます。

属性が文書の位置を指定します。include コマンドに与えられたそれぞれの 属性に対して挿入作業が行なわれます。有効な属性は次の通りです。

file
値は解析されているドキュメントの存在するディレクトリからの 相対パスです。 ../ を含んでいたり、絶対パスを指定したりはできません。 ですから、ドキュメントルートの外にあるファイルや、ディレクトリ構造で 上位にあるファイルを挿入することはできません。 常にこの属性よりは、virtual 属性を使うようにしてください。
virtual

値は解析されているドキュメントからの (% エンコードされた) URL です。URL にはスキームやホスト名を含めることはできません。パスと、 もしあればクエリー文字列を指定できるだけです。スラッシュ (/) から 始まらない場合は、ドキュメントからの相対パスとして扱われます。

URL は属性から作られ、その URL をクライアントがアクセスしたときに 出力される内容が解析後の出力に含められます。ですから、挿入される ファイルは入れ子構造にすることができます。

指定された URL が CGI プログラムであった場合は、 プログラムが実行され、その出力が解析しているファイル中の ディレクティブがあった位置に挿入されます。CGI の url に クエリー URL を入れることもできます。

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

HTML ドキュメントに CGI プログラムの出力を含める方法としては、 include virtual の方が exec cgi よりも 好ましい方法です。

printenv 要素

これは、存在するすべての変数とその値を表示します。Apache 1.3.12 から、 特別な文字は出力される前にエンティティエンコード (詳細は echo 要素を参照) されるようになりました。属性はありません。

例

<!--#printenv -->

set 要素

これは変数の値を設定します。属性は次の通りです。

var
設定する変数の名前。
value
変数に設定する値。

例

<!--#set var="category" value="help" -->

Include 変数

標準 CGI 環境の変数に加えて、echo コマンドや、 if や elif, それにドキュメントから呼び出される すべてのプログラムから使用できる変数があります。

DATE_GMT
グリニッジ標準時による現在時刻。
DATE_LOCAL
ローカルの標準時による現在時刻。
DOCUMENT_NAME
ユーザがリクエストした (ディレクトリを除いた) ファイル名。
DOCUMENT_URI
ユーザがリクエストした (% エンコードされた) URL-path。 挿入ファイルが入れ子になっている場合は、解析されている ドキュメントの URL ではないことに注意してください。
LAST_MODIFIED
ユーザがリクエストしたドキュメントの最終修正時刻。
QUERY_STRING_UNESCAPED
クエリー文字列がある場合、この変数には (%-デコードされた) クエリー文字列が代入されていて、shell で使用できるように エスケープされています (& といった特殊文字にはバックスラッシュが直前に置かれます)。

変数置換

変数置換はたいていの場合 SSI ディレクティブの引数として妥当な場所にある 引用符で囲まれた文字列中で行なわれます。これに該当するものには、 config, exec, flastmod, fsize, include, echo, set の 各ディレクティブと、条件分岐用のオペレータへの引数があります。 ドル記号はバックスラッシュを使うことで使うことができます:

<!--#if expr="$a = \$test" -->

変数名としてみなされる文字列の中で変数への参照を置換する必要があるときは、 シェルでの変数置換のように、中括弧で括ることで区別することができます:

<!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->

この例では、REMOTE_HOST が "X" で REQUEST_METHOD が "Y" のときに変数 Zed を "X_Y" に設定します。

以下の例では、DOCUMENT_URI が /foo/file.html のときに "in foo" を、/bar/file.html のときに "in bar" を、 どちらでもないときには "in neither" を表示します。

<!--#if expr='"$DOCUMENT_URI" = "/foo/file.html"' -->
in foo
 <!--#elif expr='"$DOCUMENT_URI" = "/bar/file.html"' -->
in bar
 <!--#else -->
in neither
 <!--#endif -->

フロー制御要素

基本的なフローコントロール要素は次の通りです。

<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->

if 要素はプログラミング言語の if 文と同じように動作します。条件が評価され、結果が真であれば次の elif か else か endif 要素までの文字列が出力に挿入されます。

elif や else 文は test_condition が偽のときにテキストを出力に挿入するために使われます。 これらの要素はあってもなくても構いません。

endif 要素は if 要素を終了させます。この要素は必須です。

test_condition は以下のどれかです:

string
string が空でない場合に真です
string1 = string2
string1 == string2
string1 != string2

string1 と string2 を比較します。 string2 が /string/ という形式であれば、正規表現として比較されます。正規表現は PCRE エンジンで実装されていて、 perl 5 と同じ構文を使用します。 == は単に = の別名で、まったく同じ動作を します。

正のマッチング (= または ==) の場合は、 正規表現でグループ分けされたパーツをキャプチャすることができます。 キャプチャされた部分は特殊変数 $1 .. $9 に格納されます。

例

<!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
<!--#set var="session" value="$1" -->
 <!--#endif -->

string1 < string2
string1 <= string2
string1 > string2
string1 >= string2
string1 と string2 を比較します。 文字列として比較される (strcmp(3) を使用) ことに注意してください。ですから、文字列 "100" は "20" よりも小さいことになります。
( test_condition )
test_condition が真のとき、真
! test_condition
test_condition が偽のとき、真
test_condition1 && test_condition2
test_condition1 かつ test_condition2 が真のとき、真
test_condition1 || test_condition2
test_condition1 または test_condition2 が真のとき、真

"=" と "!=" の方が "&&" より きつく束縛します。"!" の束縛が一番きつくなっています。 ですから以下の二つは等価です:

<!--#if expr="$a = test1 && $b = test2" -->
<!--#if expr="($a = test1) && ($b = test2)" -->

真偽値オペレータ && と || は同じ優先度です。 これらのオペレータで一方により強い優先度をつけたい場合には、 括弧を使う必要があります。

変数やオペレータとして認識されないものはすべて文字列として 扱われます。文字列は引用符で囲むこともできます: 'string' のように。引用符で囲まれていない文字列には空白 (スペースとタブ) を含めることはできません。それらは変数などの句を分離するために 使われているからです。複数の文字列が続いているときは、 空白を間に入れて一つにくっつけられます。ですから、

string1    string2 は string1 string2 になります。

また、

'string1    string2' は string1    string2 になります。

SSIEndTag ディレクティブ

説明: | include 要素を終了させる文字列
構文: | SSIEndTag tag
デフォルト: | SSIEndTag "-->"
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_include
互換性: | 2.0.30 以降で利用可能

このディレクティブは mod_include が探す、 include 要素の終了を示す文字列を変更します。

例

SSIEndTag "%>"

参照

  • SSIStartTag

SSIErrorMsg ディレクティブ

説明: | SSI のエラーがあったときに表示されるエラーメッセージ
構文: | SSIErrorMsg message
デフォルト: | SSIErrorMsg "[an error occurred while processing this directive]"
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Base
モジュール: | mod_include
互換性: | バージョン 2.0.30 以降で使用可能

SSIErrorMsg ディレクティブは mod_include がエラーが起こったときに表示するメッセージを変更します。プロダクションサーバでは メッセージがユーザに表示されないようにするために デフォルトエラーメッセージを "<!-- Error -->" に変えるというようなことを考えるかもしれません。

このディレクティブは <!--#config errmsg=message --> 要素と同じ効果になります。

例

SSIErrorMsg "<!-- Error -->"

SSIStartTag ディレクティブ

説明: | include 要素を開始する文字列
構文: | SSIStartTag tag
デフォルト: | SSIStartTag "<!--#"
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_include
互換性: | バージョン 2.0.30 以降で使用可能

このディレクティブは mod_include が探す、include 要素の開始を示す文字列を変更します。

二つのサーバで (もしかすると別々の段階で) ファイルの出力を解析していて、 それぞれに違うコマンドを処理させたい、 というようなときにこのオプションを使います。

例

SSIStartTag "<%"
SSIEndTag "%>"

上の例のように対応する SSIEndTag を併せて使うと、 下に示す例のように SSI ディレクティブを使えます:

違う開始と終了のタグを使った SSI ディレクティブ

<%printenv %>

参照

  • SSIEndTag

SSITimeFormat ディレクティブ

説明: | 日付けを現す文字列の書式を設定する
構文: | SSITimeFormat formatstring
デフォルト: | SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Base
モジュール: | mod_include
互換性: | 2.0.30 以降で使用可能

このディレクティブは DATE 環境変数を echo して日付を現す文字列が 表示されるときの書式を変更します。formatstring は C 標準ライブラリの strftime(3) と同じ形式です。

このディレクティブは <!--#config timefmt=formatstring --> 要素と同じ効果になります。

例

SSITimeFormat "%R, %B %d, %Y"

上のディレクティブでは、日付は "22:26, June 14, 2002" という 形式で表示されます。

SSIUndefinedEcho ディレクティブ

説明: | 未定義の変数が echo されたときに表示される文字列
構文: | SSIUndefinedEcho string
デフォルト: | SSIUndefinedEcho "(none)"
コンテキスト: | サーバ設定ファイル, バーチャルホスト
上書き: | All
ステータス: | Base
モジュール: | mod_include
互換性: | 2.0.34 以降で利用可能

このディレクティブは変数が定義されていないにも関わらず "echo" されたときに mod_include が表示する文字列を変更します。

例

SSIUndefinedEcho "<!-- undef -->"

XBitHack ディレクティブ

説明: | 実行ビットが設定されたファイルの SSI ディレクティブを 解析する
構文: | XBitHack on|off|full
デフォルト: | XBitHack off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Options
ステータス: | Base
モジュール: | mod_include

XBitHack ディレクティブは通常の HTML ドキュメントの解析を制御します。このディレクティブは MIME タイプ text/html と関連付けられているファイルにのみ影響します。 XBitHack は以下の値をとることができます。

off
実行可能ファイルに対して特別な扱いをしません。
on
ユーザの実行ビットが設定されている text/html ファイルは全てサーバで解析する html ドキュメントとして扱われます。
full
on と同様ですが、グループ実行ビットもテストします。 もしそれが設定されていれば、返されるファイルの Last-modified の 日付をファイルの最終修正時刻にします。それが設定されていないときは、 last-modified の日付は送られません。このビットを設定すると、 クライアントやプロキシがリクエストをキャッシュできるようになります。
注意 他の CGI を #include するかもしれないものや、各アクセスに対して違う出力を生成する (もしくは後のリクエストで変わるかもしれないもの) すべての SSI スクリプトに対してグループ実行ビットが 設定されていないことを確認できない場合は、full は使わない方が良い でしょう。


mod_info - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_info

This translation may be out of date. Check the English version for recent changes.
説明: | サーバの設定の包括的な概観を提供する
ステータス: | Extension
モジュール識別子: | info_module
ソースファイル: | mod_info.c

概要

mod_info を設定するには、以下を httpd.conf ファイルに加えます。

<Location /server-info>
SetHandler server-info
</Location>

サーバ設定の情報へのアクセスを制限するために、 <Location> ディレクティブの中に <Limit> 節を入れるとよいかもしれません。

一旦設定すると、http://your.host.dom/server-info をアクセスすることでサーバの情報を得られるようになります。

このモジュールは実行時に設定ファイルを読み込みます。 サーバの設定ファイルが最後にサーバに読み込まれた後に変更されている 場合には、表示されている内容は実行されているサーバの設定を反映して いないかもしれないことに注意してください。 また、設定ファイルはサーバが実行されているユーザの権限で 読み込み許可が与えられている必要があります (User ディレクティブを参照してください)。 でなければ、ディレクティブの設定は表示されません。

mod_info がサーバに組み込まれている場合は、ディレクトリ毎のファイル (例えば、.htaccess) を含むすべての設定ファイルで ハンドラを使用可能であるということにも注意してください。 これは、あなたのサイトではセキュリティに関連した問題があるかもしれません。

特に、このモジュールはシステムパス、ユーザ名/パスワード、 データベース名など、他の Apache モジュールの設定ディレクティブから セキュリティ上微妙な情報を漏らす可能性があります。 このモジュールの動作方法のせいで、情報の流出を防ぐ方法はありません。 ですから、このモジュールはちゃんとアクセスが制御された環境で、 注意して使ってください。

AddModuleInfo ディレクティブ

説明: | server-info ハンドラにより表示されるモジュールの情報に 追加の情報を付け加える
構文: | AddModuleInfo module-name string
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_info
互換性: | Apache 1.3 以降

これは、string の内容がモジュール module-name の追加情報 として HTML として解釈され、表示されるようにします。例:

AddModuleInfo mod_authn_file.c 'See <a \
href="http://www.apache.org/docs-2.0/mod/mod_authn_file.html">\
http://www.apache.org/docs-2.0/mod/mod_authn_file.html</a>'


mod_isapi - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_isapi

Description: | ISAPI Extensions within Apache for Windows
Status: | Base
Module?dentifier: | isapi_module
Source?ile: | mod_isapi.c
Compatibility: | Win32 only

Summary

This module implements the Internet Server extension API. It allows Internet Server extensions (e.g. ISAPI .dll modules) to be served by Apache for Windows, subject to the noted restrictions.

ISAPI extension modules (.dll files) are written by third parties. The Apache Group does not author these modules, so we provide no support for them. Please contact the ISAPI's author directly if you are experiencing problems running their ISAPI extension. Please do not post such problems to Apache's lists or bug reporting pages.

Usage

In the server configuration file, use the AddHandler directive to associate ISAPI files with the isapi-isa handler, and map it to them with their file extensions. To enable any .dll file to be processed as an ISAPI extension, edit the httpd.conf file and add the following line:

AddHandler isapi-isa .dll

There is no capability within the Apache server to leave a requested module loaded. However, you may preload and keep a specific module loaded by using the following syntax in your httpd.conf:

ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll

Whether or not you have preloaded an ISAPI extension, all ISAPI extensions are governed by the same permissions and restrictions as CGI scripts. That is, Options ExecCGI must be set for the directory that contains the ISAPI .dll file.

Review the Additional Notes and the Programmer's Journal for additional details and clarification of the specific ISAPI support offered by mod_isapi.

Additional Notes

Apache's ISAPI implementation conforms to all of the ISAPI 2.0 specification, except for some "Microsoft-specific" extensions dealing with asynchronous I/O. Apache's I/O model does not allow asynchronous reading and writing in a manner that the ISAPI could access. If an ISA tries to access unsupported features, including async I/O, a message is placed in the error log to help with debugging. Since these messages can become a flood, the directive ISAPILogNotSupported Off exists to quiet this noise.

Some servers, like Microsoft IIS, load the ISAPI extension into the server and keep it loaded until memory usage is too high, or unless configuration options are specified. Apache currently loads and unloads the ISAPI extension each time it is requested, unless the ISAPICacheFile directive is specified. This is inefficient, but Apache's memory model makes this the most effective method. Many ISAPI modules are subtly incompatible with the Apache server, and unloading these modules helps to ensure the stability of the server.

Also, remember that while Apache supports ISAPI Extensions, it does not support ISAPI Filters. Support for filters may be added at a later date, but no support is planned at this time.

Programmer's Journal

If you are programming Apache 2.0 mod_isapi modules, you must limit your calls to ServerSupportFunction to the following directives:

HSE_REQ_SEND_URL_REDIRECT_RESP
Redirect the user to another location.
This must be a fully qualified URL (e.g. http://server/location).
HSE_REQ_SEND_URL
Redirect the user to another location.
This cannot be a fully qualified URL, you are not allowed to pass the protocol or a server name (e.g. simply /location).
This redirection is handled by the server, not the browser.

Warning

In their recent documentation, Microsoft appears to have abandoned the distinction between the two HSE_REQ_SEND_URL functions. Apache continues to treat them as two distinct functions with different requirements and behaviors.

HSE_REQ_SEND_RESPONSE_HEADER
Apache accepts a response body following the header if it follows the blank line (two consecutive newlines) in the headers string argument. This body cannot contain NULLs, since the headers argument is NULL terminated.
HSE_REQ_DONE_WITH_SESSION
Apache considers this a no-op, since the session will be finished when the ISAPI returns from processing.
HSE_REQ_MAP_URL_TO_PATH
Apache will translate a virtual name to a physical name.
HSE_APPEND_LOG_PARAMETER
This logged message may be captured in any of the following logs:
  • in the \"%{isapi-parameter}n\" component in a CustomLog directive
  • in the %q log component with the ISAPIAppendLogToQuery On directive
  • in the error log with the ISAPIAppendLogToErrors On directive

The first option, the %{isapi-parameter}n component, is always available and preferred.

HSE_REQ_IS_KEEP_CONN
Will return the negotiated Keep-Alive status.
HSE_REQ_SEND_RESPONSE_HEADER_EX
Will behave as documented, although the fKeepConn flag is ignored.
HSE_REQ_IS_CONNECTED
Will report false if the request has been aborted.

Apache returns FALSE to any unsupported call to ServerSupportFunction, and sets the GetLastError value to ERROR_INVALID_PARAMETER.

ReadClient retrieves the request body exceeding the initial buffer (defined by ISAPIReadAheadBuffer). Based on the ISAPIReadAheadBuffer setting (number of bytes to buffer prior to calling the ISAPI handler) shorter requests are sent complete to the extension when it is invoked. If the request is longer, the ISAPI extension must use ReadClient to retrieve the remaining request body.

WriteClient is supported, but only with the HSE_IO_SYNC flag or no option flag (value of 0). Any other WriteClient request will be rejected with a return value of FALSE, and a GetLastError value of ERROR_INVALID_PARAMETER.

GetServerVariable is supported, although extended server variables do not exist (as defined by other servers.) All the usual Apache CGI environment variables are available from GetServerVariable, as well as the ALL_HTTP and ALL_RAW values.

Apache 2.0 mod_isapi supports additional features introduced in later versions of the ISAPI specification, as well as limited emulation of async I/O and the TransmitFile semantics. Apache also supports preloading ISAPI .dlls for performance, neither of which were not available under Apache 1.3 mod_isapi.

ISAPIAppendLogToErrors Directive

Description: | Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the error log
Syntax: | ISAPIAppendLogToErrors on|off
Default: | ISAPIAppendLogToErrors off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the server error log.

ISAPIAppendLogToQuery Directive

Description: | Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the query field
Syntax: | ISAPIAppendLogToQuery on|off
Default: | ISAPIAppendLogToQuery on
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the query field (appended to the CustomLog %q component).

ISAPICacheFile Directive

Description: | ISAPI .dll files to be loaded at startup
Syntax: | ISAPICacheFile file-path [file-path] ...
Context: | server config, virtual host
Status: | Base
Module: | mod_isapi

Specifies a space-separated list of file names to be loaded when the Apache server is launched, and remain loaded until the server is shut down. This directive may be repeated for every ISAPI .dll file desired. The full path name of each file should be specified. If the path name is not absolute, it will be treated relative to ServerRoot.

ISAPIFakeAsync Directive

Description: | Fake asynchronous support for ISAPI callbacks
Syntax: | ISAPIFakeAsync on|off
Default: | ISAPIFakeAsync off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

While set to on, asynchronous support for ISAPI callbacks is simulated.

ISAPILogNotSupported Directive

Description: | Log unsupported feature requests from ISAPI extensions
Syntax: | ISAPILogNotSupported on|off
Default: | ISAPILogNotSupported off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

Logs all requests for unsupported features from ISAPI extensions in the server error log. This may help administrators to track down problems. Once set to on and all desired ISAPI modules are functioning, it should be set back to off.

ISAPIReadAheadBuffer Directive

Description: | Size of the Read Ahead Buffer sent to ISAPI extensions
Syntax: | ISAPIReadAheadBuffer size
Default: | ISAPIReadAheadBuffer 49152
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

Defines the maximum size of the Read Ahead Buffer sent to ISAPI extensions when they are initially invoked. All remaining data must be retrieved using the ReadClient callback; some ISAPI extensions may not support the ReadClient function. Refer questions to the ISAPI extension's author.


mod_ldap - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_ldap

Description: | LDAP connection pooling and result caching services for use by other LDAP modules
Status: | Experimental
Module?dentifier: | ldap_module
Source?ile: | util_ldap.c
Compatibility: | Available in version 2.0.41 and later

Summary

This module was created to improve the performance of websites relying on backend connections to LDAP servers. In addition to the functions provided by the standard LDAP libraries, this module adds an LDAP connection pool and an LDAP shared memory cache.

To enable this module, LDAP support must be compiled into apr-util. This is achieved by adding the --with-ldap flag to the ./configure script when building Apache.

SSL support requires that mod_ldap be linked with one of the following LDAP SDKs: OpenLDAP SDK (both 1.x and 2.x), Novell LDAP SDK or the iPlanet(Netscape) SDK.

Example Configuration

The following is an example configuration that uses mod_ldap to increase the performance of HTTP Basic authentication provided by mod_auth_ldap.

# Enable the LDAP connection pool and shared
# memory cache. Enable the LDAP cache status
# handler. Requires that mod_ldap and mod_auth_ldap
# be loaded. Change the "yourdomain.example.com" to
# match your domain.

LDAPSharedCacheSize 200000
LDAPCacheEntries 1024
LDAPCacheTTL 600
LDAPOpCacheEntries 1024
LDAPOpCacheTTL 600

<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
AuthLDAPEnabled on
AuthLDAPURL ldap://127.0.0.1/dc=example,dc=com?uid?one
AuthLDAPAuthoritative on
require valid-user
 </Location>

LDAP Connection Pool

LDAP connections are pooled from request to request. This allows the LDAP server to remain connected and bound ready for the next request, without the need to unbind/connect/rebind. The performance advantages are similar to the effect of HTTP keepalives.

On a busy server it is possible that many requests will try and access the same LDAP server connection simultaneously. Where an LDAP connection is in use, Apache will create a new connection alongside the original one. This ensures that the connection pool does not become a bottleneck.

There is no need to manually enable connection pooling in the Apache configuration. Any module using this module for access to LDAP services will share the connection pool.

LDAP Cache

For improved performance, mod_ldap uses an aggressive caching strategy to minimize the number of times that the LDAP server must be contacted. Caching can easily double or triple the throughput of Apache when it is serving pages protected with mod_auth_ldap. In addition, the load on the LDAP server will be significantly decreased.

mod_ldap supports two types of LDAP caching during the search/bind phase with a search/bind cache and during the compare phase with two operation caches. Each LDAP URL that is used by the server has its own set of these three caches.

The Search/Bind Cache

The process of doing a search and then a bind is the most time-consuming aspect of LDAP operation, especially if the directory is large. The search/bind cache is used to cache all searches that resulted in successful binds. Negative results (i.e., unsuccessful searches, or searches that did not result in a successful bind) are not cached. The rationale behind this decision is that connections with invalid credentials are only a tiny percentage of the total number of connections, so by not caching invalid credentials, the size of the cache is reduced.

mod_ldap stores the username, the DN retrieved, the password used to bind, and the time of the bind in the cache. Whenever a new connection is initiated with the same username, mod_ldap compares the password of the new connection with the password in the cache. If the passwords match, and if the cached entry is not too old, mod_ldap bypasses the search/bind phase.

The search and bind cache is controlled with the LDAPCacheEntries and LDAPCacheTTL directives.

Operation Caches

During attribute and distinguished name comparison functions, mod_ldap uses two operation caches to cache the compare operations. The first compare cache is used to cache the results of compares done to test for LDAP group membership. The second compare cache is used to cache the results of comparisons done between distinguished names.

The behavior of both of these caches is controlled with the LDAPOpCacheEntries and LDAPOpCacheTTL directives.

Monitoring the Cache

mod_ldap has a content handler that allows administrators to monitor the cache performance. The name of the content handler is ldap-status, so the following directives could be used to access the mod_ldap cache information:

<Location /server/cache-info>
SetHandler ldap-status
 </Location>

By fetching the URL http://servername/cache-info, the administrator can get a status report of every cache that is used by mod_ldap cache. Note that if Apache does not support shared memory, then each httpd instance has its own cache, so reloading the URL will result in different information each time, depending on which httpd instance processes the request.

Using SSL

The ability to create an SSL connections to an LDAP server is defined by the directives LDAPTrustedCA and LDAPTrustedCAType. These directives specify the certificate file or database and the certificate type. Whenever the LDAP url includes ldaps://, mod_ldap will establish a secure connection to the LDAP server.

# Establish an SSL LDAP connection. Requires that
# mod_ldap and mod_auth_ldap be loaded. Change the
# "yourdomain.example.com" to match your domain.

LDAPTrustedCA /certs/certfile.der
LDAPTrustedCAType DER_FILE

<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
AuthLDAPEnabled on
AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one
AuthLDAPAuthoritative on
require valid-user
 </Location>

If mod_ldap is linked against the Netscape/iPlanet LDAP SDK, it will not talk to any SSL server unless that server has a certificate signed by a known Certificate Authority. As part of the configuration mod_ldap needs to be told where it can find a database containing the known CAs. This database is in the same format as Netscape Communicator's cert7.db database. The easiest way to get this file is to start up a fresh copy of Netscape, and grab the resulting $HOME/.netscape/cert7.db file.

LDAPCacheEntries Directive

Description: | Maximum number of entries in the primary LDAP cache
Syntax: | LDAPCacheEntries number
Default: | LDAPCacheEntries 1024
Context: | server config
Status: | Experimental
Module: | mod_ldap

Specifies the maximum size of the primary LDAP cache. This cache contains successful search/binds. Set it to 0 to turn off search/bind caching. The default size is 1024 cached searches.

LDAPCacheTTL Directive

Description: | Time that cached items remain valid
Syntax: | LDAPCacheTTL seconds
Default: | LDAPCacheTTL 600
Context: | server config
Status: | Experimental
Module: | mod_ldap

Specifies the time (in seconds) that an item in the search/bind cache remains valid. The default is 600 seconds (10 minutes).

LDAPOpCacheEntries Directive

Description: | Number of entries used to cache LDAP compare operations
Syntax: | LDAPOpCacheEntries number
Default: | LDAPOpCacheEntries 1024
Context: | server config
Status: | Experimental
Module: | mod_ldap

This specifies the number of entries mod_ldap will use to cache LDAP compare operations. The default is 1024 entries. Setting it to 0 disables operation caching.

LDAPOpCacheTTL Directive

Description: | Time that entries in the operation cache remain valid
Syntax: | LDAPOpCacheTTL seconds
Default: | LDAPOpCacheTTL 600
Context: | server config
Status: | Experimental
Module: | mod_ldap

Specifies the time (in seconds) that entries in the operation cache remain valid. The default is 600 seconds.

LDAPSharedCacheFile Directive

Description: | Sets the shared memory cache file
Syntax: | LDAPSharedCacheFile directory-path/filename
Context: | server config
Status: | Experimental
Module: | mod_ldap

Specifies the directory path and file name of the shared memory cache file. If not set, anonymous shared memory will be used if the platform supports it.

LDAPSharedCacheSize Directive

Description: | Size in bytes of the shared-memory cache
Syntax: | LDAPSharedCacheSize bytes
Default: | LDAPSharedCacheSize 102400
Context: | server config
Status: | Experimental
Module: | mod_ldap

Specifies the number of bytes to allocate for the shared memory cache. The default is 100kb. If set to 0, shared memory caching will not be used.

LDAPTrustedCA Directive

Description: | Sets the file containing the trusted Certificate Authority certificate or database
Syntax: | LDAPTrustedCA directory-path/filename
Context: | server config
Status: | Experimental
Module: | mod_ldap

It specifies the directory path and file name of the trusted CA mod_ldap should use when establishing an SSL connection to an LDAP server. If using the Netscape/iPlanet Directory SDK, the file name should be cert7.db.

LDAPTrustedCAType Directive

Description: | Specifies the type of the Certificate Authority file
Syntax: | LDAPTrustedCAType type
Context: | server config
Status: | Experimental
Module: | mod_ldap

The following types are supported:
DER_FILE - file in binary DER format
BASE64_FILE - file in Base64 format
CERT7_DB_PATH - Netscape certificate database file ")


mod_log_config - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_log_config

説明: | サーバへのリクエストのロギング
ステータス: | Base
モジュール識別子: | log_config_module
ソースファイル: | mod_log_config.c

概要

このモジュールはクライアントのリクエストを柔軟にログ収集する機能を 提供します。ログはカスタマイズ可能な書式で書かれ、ファイルに直接 書いたり、外部プログラムに渡したりすることができます。個々のリクエストを 特徴に応じてログに書いたり書かなかったりできるように、条件による ログ収集も提供されています。

このモジュールは三つのディレクティブ提供します: ログファイルを作成するための TransferLog, 新しい書式を 定義する LogFormat, ログファイルと 書式を一度に定義する CustomLog です。 各リクエストが複数回ログ収集されるようにするために TransferLog ディレクティブと CustomLog ディレクティブは複数回使用することができます。

参照

  • Apache ログファイル

カスタムログ書式

LogFormat ディレクティブと CustomLog ディレクティブの書式を指定する引数は文字列です。この文字列を使ってそれぞれの リクエストがログファイルにログ収集されます。その文字列には ログファイルにそのまま 書かれる文字列や、それぞれ改行とタブを現す C 言語 形式の制御文字 "\n" と "\t" とを含めることができます。そのまま出力させたい引用符とバックスラッシュは バックスラッシュでエスケープする必要があります。

リクエストの特徴そのものは "%" ディレクティブを書式の文字列に書くことで ログ収集されます。"%" ディレクティブはログファイル中では以下のような 値で置換されます:

フォーマット文字列 | 説明
%% パーセント記号 (Apache 2.0.44 以降)
%...a | リモート IP アドレス
%...A | ローカル IP アドレス
%...B | HTTP ヘッダ以外の送られたバイト数
%...b | HTTP ヘッダ以外の送られたバイト数。CLF 書式。 すなわち、1 バイトも送られなかったときは 0 ではなく、 '-' になる
%...{Foobar}C | サーバに送られたリクエスト中のクッキー Foobar の値
%...D | リクエストを処理するのにかかった時間、ミリ秒単位
%...{FOOBAR}e | 環境変数 FOOBAR の内容
%...f | ファイル名
%...h | リモートホスト
%...H | リクエストプロトコル
%...{Foobar}i | サーバに送られたリクエストの Foobar: ヘッダの内容
%...l | (identd からもし提供されていれば) リモートログ名。 これは IdentityCheck ディレクティブが On に設定されていない限り、 - になります。
%...m | リクエストメソッド
%...{Foobar}n | 他のモジュールからのメモ Foobar の内容
%...{Foobar}o | 応答の Foobar: ヘッダの内容
%...p | リクエストを扱っているサーバの正式なポート
%...P | リクエストを扱った子プロセスのプロセス ID
%...{format}P | リクエストを扱ったワーカーのプロセス ID かスレッド ID。 format として有効な値は pid と tid (Apache 2.0.46 以降)
%...q | 問い合せ文字列 (存在する場合は前に ? が追加される。 そうでない場合は空文字列)
%...r | リクエストの最初の行
%...s | ステータス。内部でリダイレクトされたリクエストは、元々の リクエストのステータス --- 最後のステータスは %...>s
%...t | 時刻。CLF の時刻の書式 (標準の英語の書式)
%...{format}t | format で与えられた書式による時刻。format は strftime (3) の 書式である必要がある。(地域化されている可能性がある)
%...T | リクエストを扱うのにかかった時間、秒単位
%...u | リモートユーザ (認証によるもの。ステータス (%s) が 401 のときは意味がないものである可能性がある)
%...U | リクエストされた URL パス。クエリ文字列は含まない
%...v | リクエストを扱っているサーバの正式な ServerName
%...V | UseCanonicalName の設定によるサーバ名
%...X 応答が完了したときの接続ステータス:
X = | 応答が完了する前に接続が異常終了
+ = | 応答が送られた後に接続を持続することが可能
- = | 応答が送られた後に接続が切られる

(このディレクティブは Apache 1.3 の後期のバージョンでは %...c に割り当てられて いましたが、これは歴史的に ssl が使用している %...{var}c 構文と衝突していました。)

%...I | リクエストとヘッダを含む、受け取ったバイト数。 0 にはならない。 これを使用するためには mod_logio が必要
%...O | ヘッダを含む、送信したバイト数。0 にはならない。 これを使用するためには mod_logio が必要

"..." は何もないか (例えば、 "%h %u %r %s %b" のように)、 その項目を含めるかどうかの条件 (もし条件に合わなかったときは その項目は "-" になります) にすることができます。条件の形式は HTTP ステータスコードのリストで、前に "!" を付けることもできます。 ですから、"%400,501{User-agent}i" は 400 エラーと 501 エラー (Bad Request と Not Implemented) のときのみ User-agent: をログ収集します。 "%!200,304,302{Referer}i" は普通のステータスを返さなかった すべてのリクエストで Referer: をログ収集します。

修飾子 "<" と ">" は内部リダイレクトされたリクエストのログに 元のリクエストか最終的なリクエストのどちらを使用するかを 指定するために使います。デフォルトでは、% ディレクティブの %s, %U, %T, %D, %r は元のリクエストを、他は最終的なリクエストを 使用します。例えば、リクエストの最終ステータスを記録するには %>s を、内部的に認証されていないリソースへリダイレクトされた リクエストで元のリクエストで認証されたユーザを記録するためには %<u を使うことができます。

httpd 2.0 の 1.3.25 より前のバージョンでは、 %...r, %...i, %...o の文字列は エスケープされていなかったことに 注意してください。これは主に Common Log Format からの要求によるものです。 これは、クライアントがログに制御文字を挿入することができるということで、 生のログファイルを扱うときには非常に注意が必要でした。

セキュリティ上の理由により 2.0.46 より印字不可能な文字と 他の特別な文字は、ほとんど \xhh という 文字列でエスケープされるようになりました。ここで、hh は そのままのバイトの値の 16 進での値です。この規則の例外には、 バックスラッシュを使ってエスケープされる " と \ と、 C 形式の表記法が使われる空白文字 (\n, \t など) が あります。

よく使われるフォーマット文字列は:

Common Log Format (CLF)
"%h %l %u %t \"%r\" %>s %b"
バーチャルホスト付き Common Log Format
"%v %h %l %u %t \"%r\" %>s %b"
NCSA extended/combined ログ書式
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
Referer ログ書式
"%{Referer}i -> %U"
Agent (ブラウザ) ログ書式
"%{User-agent}i"

%v と %p にはそれぞれ、 リクエストを扱っているサーバの正規化された ServerName と Listen が使われるということに注意してください。 これは UseCanonicalName の 設定に関わらず、常にそうなります。そうしないとどの ホストが実際にリクエストを扱ったのかを知るために、 ログ解析プログラムがバーチャルホストのマッチングをとるアルゴリズム全体を 再実装しなければならなくなるからです。

セキュリティに関して

ログファイルが保存されているディレクトリがサーバを起動した以外のユーザで 書き込み可能なときにセキュリティの問題が発生する理由の詳細はセキュリティのこつ を参照してください。

CookieLog ディレクティブ

説明: | クッキングのロギングのためのファイル名を設定する
構文: | CookieLog filename
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_log_config
互換性: | このディレクティブは非推奨

CookieLog ディレクティブはクッキーのロギングのためのファイル名を 設定します。filename は ServerRoot からの相対パスです。このディレクティブは mod_cookies との互換性のためだけに 存在し、使用は推奨されていません。

CustomLog ディレクティブ

説明: | ログファイルの名前と書式を設定する
構文: | CustomLog file|pipe format|nickname [env=[!]environment-variable]
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_log_config

CustomLog ディレクティブはサーバへのリクエストを ログ収集するために使われます。ログの書式が指定され、 環境変数を使ってロギングが条件に応じて行なわれるようにすることもできます。

ログが書かれる場所を指定する最初の引数は以下の二つの形式の値を とることができます:

file
ServerRoot からの相対パスで表されるファイル名。
pipe
パイプ文字 "|" と、その後に標準入力からログの 情報を受けとるプログラムへのパスが続いたもの。

セキュリティ

もしプログラムが使用された場合、 httpd が起動されたユーザとして実行されます。これはサーバが root によって起動された場合は root になります。プログラムが 安全であるように留意してください。

注

Unix でないプラットフォームでファイルのパスを入力しているときは、 使用しているプラットフォームがバックスラッシュの使用を許可していた として、通常のスラッシュだけを使うように気をつけてください。 一般的に、設定ファイル中では常に普通のスラッシュのみを使うようにする 方が良いです。

二つめの引数はログファイルに何が書かれるかを指定します。 前にある LogFormat ディレクティブにより 定義された nickname か、ログの書式 のところで説明されている、明示的な format 文字列の どちらかを指定することができます。

例えば、以下の二つのディレクティブ群は全く同じ効果をもたらします:

# CustomLog with format nickname
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common

# CustomLog with explicit format string
CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"

三つ目の引数は省略可能で、サーバの環境にある変数があるかないかに 応じてリクエストをログ収集するかどうかを制御するために使うことができます。 指定された環境変数がリクエストに対して 設定されていた場合 ('env=!name' 文が使われたときは 設定されていない場合)、リクエストがログ収集されます。

環境変数は mod_setenvif モジュールと mod_rewrite モジュールの両方もしくは 片方を用いてリクエストごとに設定することができます。 例えば、サーバにあるすべての GIF 画像へのリクエストを別のログファイル には記録したいけれど、メインログには記録したくない、というときは 以下のものを使うことができます:

SetEnvIf Request_URI \.gif$ gif-image
CustomLog gif-requests.log common env=gif-image
CustomLog nongif-requests.log common env=!gif-image

LogFormat ディレクティブ

説明: | ログファイルで使用する書式を設定する
構文: | LogFormat format|nickname [nickname]
デフォルト: | LogFormat "%h %l %u %t \"%r\" %>s %b"
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_log_config

このディレクティブはアクセスログファイルの書式を指定します。

LogFormat ディレクティブは二つの形式のどちらかを とることができます。最初の形式では一つの引数のみが指定され、 続く TransferLog で指定されたログで使われるログの書式を設定します。この単独の引数では 上のカスタムログ書式で説明されているように format を明示的に指定することができます。 もしくは、下で説明されているように前に LogFormat ディレクティブで定義されたログの書式を nicknameを使って 参照することもできます。

LogFormat ディレクティブの二つめの形式は format に nickname を与えます。 フォーマット文字列全体を再び書くかわりに、 この nickname を続きの LogFormat ディレクティブや CustomLog ディレクティブで使うことができます。 Nickname を定義する LogFormat ディレクティブは 他には何もしません -- すなわち、ニックネームを定義 するだけで、実際に書式を適用してデフォルトにするということは行ないません。 ですから、これは続く TransferLog ディレクティブには影響を与えません。 さらに、LogFormat ディレクティブは既存の nickname を 使って別の nickname を定義することはできません。Nickname には パーセント記号 (%) が含まれていてはいけないことにも注意 してください。

例

LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common

TransferLog ディレクティブ

説明: | ログファイルの位置を指定
構文: | TransferLog file|pipe
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_log_config

このディレクティブは、ログ書式を直接指定できないことと、 条件付きロギングが無いことを除くと、CustomLog と全く同じ引数と効果があります。 直接ログ書式を指定する代わりに、ログの書式はそこまでで一番最後に指定された ニックネームを定義しない LogFormat ディレクティブ で定義されたものを使います。 もし他の書式が全く指定されていないときは Common Log Format が使われます。

例

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog logs/access_log


mod_log_forensic - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_log_forensic

Description: | Forensic Logging of the requests made to the server
Status: | Extension
Module?dentifier: | log_forensic_module
Source?ile: | mod_log_forensic.c
Compatibility: | Available in version 2.0.50 and later

Summary

This module provides for forensic logging of client requests. Logging is done before and after processing a request, so the forensic log contains two log lines for each request. The forensic logger is very strict, which means:

  • The format is fixed. You cannot modify the logging format at runtime.
  • If it cannot write its data, the child process exits immediately and may dump core (depending on your CoreDumpDirectory configuration).

The check_forensic script, which can be found in the distribution's support directory, may be helpful in evaluating the forensic log output.

This module was backported from version 2.1 which uses a more powerful APR version in order to generate the forensic IDs. If you want to run mod_log_forensic in version 2.0, you need to include mod_unique_id as well.

See also

  • Apache Log Files
  • mod_log_config

Forensic Log Format

Each request is logged two times. The first time before it's processed further (that is, after receiving the headers). The second log entry is written after the request processing at the same time where normal logging occurs.

In order to identify each request, a unique request ID is assigned. This forensic ID can be cross logged in the normal transfer log using the %{forensic-id}n format string. If you're using mod_unique_id, its generated ID will be used.

The first line logs the forensic ID, the request line and all received headers, separated by pipe characters (|). A sample line looks like the following (all on one line):

+yQtJf8CoAB4AAFNXBIEAAAAA|GET /manual/de/images/down.gif HTTP/1.1|Host:localhost%3a8080|User-Agent:Mozilla/5.0 (X11; U; Linux i686; en-US; rv%3a1.6) Gecko/20040216 Firefox/0.8|Accept:image/png, etc...

The plus character at the beginning indicates that this is first log line of this request. The second line just contains a minus character and the ID again:

-yQtJf8CoAB4AAFNXBIEAAAAA

The check_forensic script takes as its argument the name of the logfile. It looks for those +/- ID pairs and complains if a request was not completed.

Security Considerations

See the security tips document for details on why your security could be compromised if the directory where logfiles are stored is writable by anyone other than the user that starts the server.

ForensicLog Directive

Description: | Sets filename of the forensic log
Syntax: | ForensicLog filename|pipe
Context: | server config, virtual host
Status: | Extension
Module: | mod_log_forensic

The ForensicLog directive is used to log requests to the server for forensic analysis. Each log entry is assigned a unique ID which can be associated with the request using the normal CustomLog directive. mod_log_forensic takes the unique ID from mod_unique_id, so you need to load this module as well. (This requirement will not be necessary in version 2.1 and later, because of a more powerful APR version.) The ID token is attached to the request under the name forensic-id, which can be added to the transfer log using the %{forensic-id}n format string.

The argument, which specifies the location to which the logs will be written, can take one of the following two types of values:

filename
A filename, relative to the ServerRoot.
pipe
The pipe character "|", followed by the path to a program to receive the log information on its standard input. The program name can be specified relative to the ServerRoot directive.

Security:

If a program is used, then it will be run as the user who started httpd. This will be root if the server was started by root; be sure that the program is secure or switches to a less privileged user.

Note

When entering a file path on non-Unix platforms, care should be taken to make sure that only forward slashed are used even though the platform may allow the use of back slashes. In general it is a good idea to always use forward slashes throughout the configuration files.


mod_logio - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_logio

説明: | リクエスト毎に入力バイト数と出力バイト数とをロギング
ステータス: | Extension
モジュール識別子: | logio_module
ソースファイル: | mod_logio.c

概要

このモジュールはリクエストごとに受け取ったバイト数と 送信したバイト数のロギングを行なう機能を提供します。 記録される数字はリクエストのヘッダとレスポンスの本体を 反映した、実際にネットワークで受け取ったバイト値です。 入力では SSL/TLS の前に、出力では SSL/TLS の後に数えるので、 数字は暗号による変化も正しく反映したものになります。

このモジュールの使用には mod_log_config モジュールが 必要です。

参照

  • mod_log_config
  • Apache ログファイル

カスタムログ書式

このモジュールは新しいロギング用ディレクティブを加えます。 リクエスト自身の特徴はフォーマット文字列に、以下の様に置換される "%" ディレクティブを 入れることでログ収集されます:

フォーマット文字列 | 説明
%...I | リクエストとヘッダを含む、受け取ったバイト数。 0 にはならない。
%...O | ヘッダを含む、送信したバイト数。0 にはならない。

通常、この機能は以下の様に使用されます:

結合 I/O ログ書式:
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\" %I %O"


mod_mem_cache - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_mem_cache

Description: | Content cache keyed to URIs
Status: | Experimental
Module?dentifier: | mem_cache_module
Source?ile: | mod_mem_cache.c

Summary

This module is experimental. Documentation is still under development...

This module requires the service of mod_cache. It acts as a support module for mod_cache and provides a memory based storage manager. mod_mem_cache can be configured to operate in two modes: caching open file descriptors or caching objects in heap storage. mod_mem_cache is most useful when used to cache locally generated content or to cache backend server content for mod_proxy configured for ProxyPass (aka reverse proxy).

Content is stored in and retrieved from the cache using URI based keys. Content with access protection is not cached.

See also

  • mod_cache
  • mod_disk_cache

MCacheMaxObjectCount Directive

Description: | The maximum number of objects allowed to be placed in the cache
Syntax: | MCacheMaxObjectCount value
Default: | MCacheMaxObjectCount 1009
Context: | server config
Status: | Experimental
Module: | mod_mem_cache

The MCacheMaxObjectCount directive sets the maximum number of objects to be cached. The value is used to create the open hash table. If a new object needs to be inserted in the cache and the maximum number of objects has been reached, an object will be removed to allow the new object to be cached. The object to be removed is selected using the algorithm specified by MCacheRemovalAlgorithm.

Example

MCacheMaxObjectCount 13001

MCacheMaxObjectSize Directive

Description: | The maximum size (in bytes) of a document allowed in the cache
Syntax: | MCacheMaxObjectSize bytes
Default: | MCacheMaxObjectSize 10000
Context: | server config
Status: | Experimental
Module: | mod_mem_cache

The MCacheMaxObjectSize directive sets the maximum allowable size, in bytes, of a document for it to be considered cacheable.

Example

MCacheMaxObjectSize 6400000

Note

The value of MCacheMaxObjectSize must be greater than the value specified by the MCacheMinObjectSize directive.

MCacheMaxStreamingBuffer Directive

Description: | Maximum amount of a streamed response to buffer in memory before declaring the response uncacheable
Syntax: | MCacheMaxStreamingBuffer size_in_bytes
Default: | MCacheMaxStreamingBuffer the smaller of 100000 or MCacheMaxObjectSize
Context: | server config
Status: | Experimental
Module: | mod_mem_cache

The MCacheMaxStreamingBuffer directive specifies the maximum number of bytes of a streamed response to buffer before deciding that the response is too big to cache. A streamed response is one in which the entire content is not immediately available and in which the Content-Length may not be known. Sources of streaming responses include proxied responses and the output of CGI scripts. By default, a streamed response will not be cached unless it has a Content-Length header. The reason for this is to avoid using a large amount of memory to buffer a partial response that might end up being too large to fit in the cache. The MCacheMaxStreamingBuffer directive allows buffering of streamed responses that don't contain a Content-Length up to the specified maximum amount of space. If the maximum buffer space is reached, the buffered content is discarded and the attempt to cache is abandoned.

Note:

Using a nonzero value for MCacheMaxStreamingBuffer will not delay the transmission of the response to the client. As soon as mod_mem_cache copies a block of streamed content into a buffer, it sends the block on to the next output filter for delivery to the client.

# Enable caching of streamed responses up to 64KB:
MCacheMaxStreamingBuffer 65536

MCacheMinObjectSize Directive

Description: | The minimum size (in bytes) of a document to be allowed in the cache
Syntax: | MCacheMinObjectSize bytes
Default: | MCacheMinObjectSize 0
Context: | server config
Status: | Experimental
Module: | mod_mem_cache

The MCacheMinObjectSize directive sets the minimum size in bytes of a document for it to be considered cacheable.

Example

MCacheMinObjectSize 10000

MCacheRemovalAlgorithm Directive

Description: | The algorithm used to select documents for removal from the cache
Syntax: | MCacheRemovalAlgorithm LRU|GDSF
Default: | MCacheRemovalAlgorithm GDSF
Context: | server config
Status: | Experimental
Module: | mod_mem_cache

The MCacheRemovalAlgorithm directive specifies the algorithm used to select documents for removal from the cache. Two choices are available:

LRU (Least Recently Used)
LRU removes the documents that have not been accessed for the longest time.
GDSF (GreadyDual-Size)
GDSF assigns a priority to cached documents based on the cost of a cache miss and the size of the document. Documents with the lowest priority are removed first.

Example

MCacheRemovalAlgorithm GDSF
MCacheRemovalAlgorithm LRU

MCacheSize Directive

Description: | The maximum amount of memory used by the cache in KBytes
Syntax: | MCacheSize KBytes
Default: | MCacheSize 100
Context: | server config
Status: | Experimental
Module: | mod_mem_cache

The MCacheSize directive sets the maximum amount of memory to be used by the cache, in KBytes (1024-byte units). If a new object needs to be inserted in the cache and the size of the object is greater than the remaining memory, objects will be removed until the new object can be cached. The object to be removed is selected using the algorithm specified by MCacheRemovalAlgorithm.

Example

MCacheSize 700000

Note

The MCacheSize value must be greater than the value specified by the MCacheMaxObjectSize directive.


mod_mime - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_mime

説明: | リクエストされたファイルの拡張子とファイルの振る舞い (ハンドラとフィルタ)、内容 (MIME タイプ、言語、文字セット、エンコーディング) とを関連付ける
ステータス: | ベース
モジュール識別子: | mime_module
ソースファイル: | mod_mime.c

概要

このモジュールは拡張子を使っていろいろな「メタ情報」をファイルに 関連付けるために使用されます。この情報はドキュメントのファイル名と MIME タイプ、言語、文字セット、エンコーディングとを関連付けます。 この情報はブラウザに送られますし、複数のファイルの中からユーザの好みの ものが選ばれるように、コンテントネゴシエーションでも使われます。 コンテントネゴシエーション に関する詳しい情報は mod_negotiation をご覧下さい。

AddCharset ディレクティブ、 AddEncoding ディレクティブ、 AddHandler ディレクティブ、 AddLanguage ディレクティブ、 AddType ディレクティブはすべて、 ファイルの拡張子をメタ情報にマップするために使用されます。 それぞれ、ドキュメントの文字セット (訳注: charset)、content-encoding, content-language, MIME タイプ (content-type) を設定します。 TypesConfig ディレクティブは拡張子を MIME タイプにマップするファイルを指定するために使用されます。

さらに、mod_mime はコンテンツを作成、処理する ハンドラ と フィルタ を設定することができます。AddHandler ディレクティブ、AddOutputFilter ディレクティブ、AddInputFilter ディレクティブは ドキュメントを扱うモジュールやスクリプトを制御します。 MultiviewsMatch ディレクティブは これらのディレクティブが指定したファイルの拡張子を mod_negotiation が Multiviews のマッチをとるときに 考慮するようにできます。

mod_mime はメタ情報をファイル名と関連付けますが、 core サーバにはあるコンテナ (たとえば, <Location>, <Directory>, <Files>) の中のすべてのファイルを特定の メタ情報と関連付けるディレクティブがあります。これらのディレクティブには ForceType, SetHandler, SetInputFilter, SetOutputFilter があります。 コアのディレクティブは mod_mime により定義された ファイル名の拡張子のマッピングすべてを上書きします。

ファイルのメタ情報を変えても Last-Modified ヘッダの値は変わらないことに注意してください。ですから、 それらを変更した場合は、クライアントやプロキシで以前にキャッシュされた コピーがそのときのヘッダとともに使われる可能性があります。 メタ情報 (言語、コンテントタイプ、文字セット、エンコーディング) を 変更したときは、すべての訪問者が正しいコンテントヘッダを 受け取るように、影響を受けるファイルに 'touch' コマンドを実行する (最終更新日を更新する) 必要があるかもしれません。

参照

  • MimeMagicFile
  • AddDefaultCharset
  • ForceType
  • DefaultType
  • SetHandler
  • SetInputFilter
  • SetOutputFilter

複数の拡張子のあるファイル

ファイルは複数の拡張子を持つことができ、拡張子の順番は通常は関係ありません。例えば、ファイル welcome.html.fr がコンテントタイプは text/html に、言語はフランス語にマップされる場合、welcome.fr.html もまったく同じ情報にマップされます。 同じメタ情報にマップされる拡張子が複数あるときには、言語と コンテントエンコーディングを除いて、 右側にあるものが使用されます。たとえば、.gif が MIME タイプ image/gif にマップされ、.html が MIME タイプ text/html にマップされる場合は、ファイル welcome.gif.html は MIME タイプ text/html に関連付けられます。

リソースに複数の言語やエンコーディングを関連付けること ができるため、 言語とコンテントエンコーディングは前のものに追加されていきます。 たとえば、ファイル welcome.html.en.de は Content-Language: en, de と Content-Type: text/html として送信されます。

複数の拡張子のあるファイルが MIME タイプとハンドラの両方に関連付けられているときは注意する必要があります。 その場合、普通はリクエストがハンドラに関連付けられた モジュールによって扱われることになります。たとえば、拡張子 .imap が (mod_imap の) imap-file にマップされていて、.html が MIME タイプ text/html にマップされているときは、ファイル world.imap.html は imap-file ハンドラと text/html MIME タイプに関連付けられます。ファイルが処理されるときは imap-file ハンドラが使用されますので、そのファイルは mod_imap のイメージマップファイルとして扱われることになります。

コンテントエンコーディング

特定の MIME タイプのファイルはインターネットでの転送を簡単にするために、 さらに符号化することができます。これは通常は gzip の ような圧縮のことを指しますが、pgp のような暗号化や、 バイナリファイルを ASCII (テキスト) 形式で送るために考案された UUencoding のことを指すこともあります。

HTTP/1.1 RFC 14.11 節では次のように記述されています。

Content-Encoding エンティティヘッダフィールドはメディアタイプの 修飾子として使われます。それが存在していれば、値はエンティティボディに どの追加の符号化が適用されたかを示し、Content-Type ヘッダフィールドに 書かれているメディアタイプを得るためにどの復号機構を適用すべきか、も 示していることになります。Content-Encoding は主に、元のメディアタイプの 同一性を失うことなくドキュメントを圧縮することを可能にするために 使用されます。

複数のファイル拡張子 (複数の拡張子については 上の節 を参照) 使うことで、 ファイルのタイプやエンコーディングを指定することが できます。

たとえば、Microsoft Word のドキュメントがあり、サイズを小さくするために pkzip されているとします。.doc 拡張子が Microsoft Word の ファイルタイプと関連付けられていて、.zip 拡張子が pkzip ファイルエンコーディングと関連付けられていると、ファイル Resume.doc.zip は pkzip された Word ドキュメントである ということがわかります。

クライアントのブラウザにエンコーディング方法を知らせるために、 Apache はリソースと共に Content-Encoding ヘッダを 送ります。

Content-encoding: pkzip

文字セットと言語

ファイルタイプとファイルエンコーディングの他に重要な情報は ドキュメントの書かれている言語と、どの文字セットでファイルが表示 されるべきか、というものです。たとえば、ドキュメントはベトナムの アルファベットやキリル文字で書かれていて、そのように表示される 必要があるかもしれません。この情報もまた、HTTP ヘッダで 送信されます。

文字セット、言語、エンコーディング、mime タイプはすべて コンテントネゴシエーション (mod_negotiation 参照) の最中に、複数の文字セット、言語、エンコーディング、MIME タイプからなる 代替物があるときにどのドキュメントをクライアントに送るのかを 決定するときに使われます。AddCharset, AddEncoding, AddLanguage, AddType の各ディレクティブで作成された 拡張子の関連付け (と MimeMagicFile でリストされている 拡張子) がこの選択に参加します。AddHandler, AddInputFilter, AddOutputFilter の 各ディレクティブでのみ関連付けられている拡張子は MultiviewsMatch ディレクティブを 使うことでマッチの 処理に含めることも外すこともできます。

Charset

さらに情報を伝えるために、Apache は文書の言語を Content-Language ヘッダで送ることもあります。 また、情報を正しく表示するために使用すべき文字セットを示すために Conten-Type ヘッダに情報を追加することもあります。

Content-Language: en, fr
Content-Type: text/plain; charset=ISO-8859-1

言語の指定は二文字の短縮形で行なわれます。charset が 使用すべき文字セットの名前です。

AddCharset ディレクティブ

説明: | ファイル名の拡張子を指定された文字セットにマップする
構文: | AddCharset charset extension [extension] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime

AddCharset ディレクティブは、 与えられた拡張子を指定された charset にマップします。charset は、拡張子 extension を含んでいるファイル名の MIME charset パラメータです。新しいマッピングは既にある他のマッピングに追加され、同じ拡張子 extension のためのマッピングを上書きします。

例

AddLanguage ja .ja
AddCharset EUC-JP .euc
AddCharset ISO-2022-JP .jis
AddCharset SHIFT_JIS .sjis

この場合、ドキュメント xxxx.ja.jis は charset が ISO-2022-JP の日本語のドキュメントとして扱われます (xxxx.jis.ja も同様)。AddCharset ディレクティブは、ドキュメントが適切に解釈され表示されるように、 ドキュメントの charset の情報をクライアントに教えるために役に立ちます。 また、サーバがクライアントの charset の優先度に基づいて複数のドキュメントの中からドキュメントを選ぶコンテントネゴシエーションのためにも役に立ちます。

引数 extensionは大文字小文字を区別せず、 最初のドットはあってもなくても構いません。

参照

  • mod_negotiation
  • AddDefaultCharset

AddEncoding ディレクティブ

説明: | ファイル名の拡張子を指定されたエンコーディング にマップする
構文: | AddEncoding MIME-enc extension [extension] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime

AddEncoding ディレクティブは、 与えられた拡張子を指定されたエンコーディングにマップします。 MIME-enc は、拡張子 extension を含んだドキュメントに使用する MIME エンコーディングです。 この新しいマッピングは既にある他のマッピングに追加され、 同じ拡張子 extension のためのマッピングを上書きします。

例

AddEncoding x-gzip .gz
AddEncoding x-compress .Z

これは、拡張子 .gz を含むファイル名が x-gzip エンコーディングを使ってエンコードされていることと、拡張子 .Z を含むファイル名が x-compress でエンコードされていることを指定します。

古いクライアントは x-zip と x-compress が返ってくることを期待しますが、標準規格ではそれぞれ gzip と compress と等価であることになっています。Apache は、コンテントエンコーディングの比較をするときには、先頭にある x- を無視します。Apache がエンコーディング付きで応答を返すときは、クライアントが要求した形式 (すなわち、x-foo や foo) を使用します。要するに、この二つのエンコーディングの場合は常に x-gzip と x-compress を使うべきである、ということです。deflate のようなより新しいエンコーディングでは、x- なしで指定してください。

引数 extension は大文字小文字を区別せず、 最初のドットはあってもなくても構いません。

AddHandler ディレクティブ

説明: | ファイル名の拡張子を指定されたハンドラにマップする
構文: | AddHandler handler-name extension [extension] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime

拡張子 extension が名前にあるファイルは指定された handler-name に扱われます。 この新しいマッピングは既にある他のマッピングに追加され、 同じ拡張子 extension のためのマッピングを上書きします。たとえば、拡張子 ".cgi" で終わるファイルを CGI スクリプトとして扱いたいときは、以下の設定をします。

AddHandler cgi-script .cgi

これを httpd.conf ファイルに記述することで、拡張子 ".cgi" のファイルは CGI プログラムとして扱われます。

引数 extension は大文字小文字を区別せず、 最初のドットはあってもなくても構いません。

参照

  • SetHandler

AddInputFilter ディレクティブ

説明: | ファイルの拡張子をクライアントのリクエストを処理する フィルタにマップする
構文: | AddInputFilter filter[;filter...] extension [extension] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime
互換性: | 2.0.26 以降で使用可能

AddInputFilter はファイルの拡張子 extension をクライアントのリクエストや POST がサーバに来たときに 処理をするフィルタにマップします。 これは、SetInputFilter ディレクティブも 含め、他の場所で定義されているフィルタに加えられます。 このマッピングはすでにあるものより優先されてマージされ、 同じ extension に対する既存のマッピングを上書きします。

複数のフィルタを指定するときは、データを処理する順番にセミコロンで 繋いで書く必要があります。フィルタと extension との 両方の引数は大文字小文字を区別せず、拡張子の最初のドットは あってもなくても構いません。

参照

  • RemoveInputFilter
  • SetInputFilter

AddLanguage ディレクティブ

説明: | ファイル名を指定された言語にマップ
構文: | AddLanguage MIME-lang extension [extension] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime

AddLanguage ディレクティブは、与えられた拡張子を指定された content language にマップします。MIME-lang は、拡張子 extension を含んでいるファイル名の MIME における言語です。 この新しいマッピングは既にあるマッピングに追加され、同じ拡張子 extension のためのマッピングを上書きします。

例

AddEncoding x-compress .Z
AddLanguage en .en
AddLanguage fr .fr

この場合、xxxx.en.Z ドキュメントは compress された英語のドキュメントとして扱われます (xxxx.Z.en も同様)。content language はクライアントに通知されますが、 ブラウザがこの情報を使うことはおそらくありません。 AddLanguage ディレクティブは、サーバがクライアントの言語の優先度に基づいて複数の ドキュメントの中からドキュメントを選ぶコンテントネゴシエーションのためにより役に立ちます。

複数の言語が同じ拡張子に割り当てられているときは、 最後のものが使用されます。すなわち、次のような場合、

AddLanguage en .en
AddLanguage en-gb .en
AddLanguage en-us .en

拡張子 .en のあるドキュメントは en-us として扱われます。

引数 extension は大文字小文字を区別せず、 最初のドットはあってもなくても構いません。

参照

  • mod_negotiation

AddOutputFilter ディレクティブ

説明: | ファイル名の拡張子をサーバからの応答を処理するフィルタに マップする
構文: | AddOutputFilter filter[;filter...] extension [extension] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime
互換性: | 2.0.26 以降で使用可能

AddOutputFilter ディレクティブは 拡張子 extension をサーバの応答がクライアントに送られる 前に処理するフィルタを定義します。 これは SetOutputFilter ディレクティブと AddOutputFilterByType ディレクティブ を含め、他の場所で定義されているフィルタに加えられます。 この新しいマッピングは既にあるマッピングに追加され、同じ拡張子 extension のためのマッピングを上書きします。

例えば、以下の設定はすべての .shtml ファイルを SSI で処理し、 その出力を mod_deflate を使って圧縮します。

AddOutputFilter INCLUDES;DEFLATE shtml

複数のフィルタを指定するときは、データを処理する順番にセミコロンで 繋いで書く必要があります。filter と extension の 両引数は大文字小文字を区別せず、拡張子の最初のドットは あってもなくても構いません。

参照

  • RemoveOutputFilter
  • SetOutputFilter

AddType ディレクティブ

説明: | ファイル名の拡張子を指定されたコンテントタイプにマップ
構文: | AddType MIME-type extension [extension] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime

AddType ディレクティブは、 与えられた拡張子を指定されたコンテントタイプにマップします。 MIME-type は拡張子 extension を含んだドキュメントに使用する MIME タイプです。 この新しいマッピングは既にあるマッピングに追加され、同じ拡張子 extension のためのマッピングを上書きします。 このディレクティブは MIME タイプファイル (TypesConfig ディレクティブを参照) に無いマッピングを追加するために使用することができます。

例

AddType image/gif .gif

新しい MIME タイプは、TypesConfig ファイルを変更するのではなく、AddType ディレクティブを使って追加することが推奨されています。

引数 extension は大文字小文字を区別せず、 最初のドットはあってもなくても構いません。

参照

  • DefaultType
  • ForceType

DefaultLanguage ディレクティブ

説明: | あるスコープのすべてのファイルを指定された言語に 設定する
構文: | DefaultLanguage MIME-lang
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime

DefaultLanguage ディレクティブは、Apache がディレクティブのスコープ (例えば、その時点の <Directory> の範囲) にある、明示的な言語拡張子 (AddLanguage で設定される .fr や .de) のない全てのファイルを、指定された MIME-lang 言語であるとみなすようにします。 これにより、すべてのファイル名を変えることなく、 ディレクトリがオランダ語のコンテントを含んでいる、 というようなことを指定することができます。 拡張子を使用して言語を指定する方法と違い、 DefaultLanguage は一つの言語しか指定できないことに注意してください。

DefaultLanguage ディレクティブが有効でなく、ファイルに AddLanguage で設定された言語の拡張子がないときは、 ファイルには言語属性がないとみなされます。

例

DefaultLanguage en

参照

  • mod_negotiation

ModMimeUsePathInfo ディレクティブ

説明: | path_info コンポーネントをファイル名の一部として扱うように mod_mime に通知する
構文: | ModMimeUsePathInfo On|Off
デフォルト: | ModMimeUsePathInfo Off
コンテキスト: | ディレクトリ
ステータス: | ベース
モジュール: | mod_mime
互換性: | Apache 2.0.41 以降

ModMimeUsePathInfo ディレクティブは、 mod_mime の持つディレクティブを リクエストに適用させるために、ファイル名と path_info URL コンポーネントを結合させるために使用します。 デフォルトでは「 Off 」で、path_info コンポーネントは無視されます。

このディレクティブは、バーチャルファイルシステムを使用している際に 推奨されるディレクティブです。

例

ModMimeUsePathInfo On

/bar が存在して (foo.shtml は存在しない) ModMimeUsePathInfo が On であるとして、 /bar/foo.shtml に対するリクエストを発行した場合、 mod_mime は入ってきたリクエストを /bar/foo.shtml として扱い、 AddOutputFileter INCLUDES .shtml のようなディレクティブは INCLUDES フィルタをリクエストに付加させます。 ModMimeUsePathInfo が設定されなければ、 INCLUDES フィルタは付加されません。

参照

  • AcceptPathInfo

MultiviewsMatch ディレクティブ

説明: | MultiViews でのマッチングの検索に含ませる ファイルのタイプを指定する
構文: | MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers [Handlers|Filters]
デフォルト: | MultiviewsMatch NegotiatedOnly
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime
互換性: | 2.0.26 以降で使用可能

MultiviewsMatch を使用することで、 mod_negotiation の Multiviews に 3 種類の異なる挙動をさせることができます。 Multiviews を使用すると、ファイル (例 index.html) に対するリクエストに対して、ネゴシエーションする拡張子がベースに付いたもの (index.html.en, index.html.fr や index.html.gz) をマッチさせることができます。

NegotiatedOnly オプションでは、ベース名に続く拡張子全てが コンテントネゴシエーションで mod_mime が認識する拡張子 (例 文字セット、コンテントタイプ、言語やエンコーディング) に関連付けられていなければなりません。これは副作用の最も少ない 最も的確な実装で、デフォルトになっています。

ハンドラとフィルタの両方もしくは片方と関連付けられた拡張子を含めるには、 MultiviewsMatch ディレクティブに Handlers, Filters またはその両方のオプションをセットします。 もし他の条件が同じであれば、最も小さいファイルが送信されます。 例えば、500 文字の index.html.cgi と 1000 バイトの index.html.pl であれば、.cgi のファイルが優先されます。.asis ファイルを利用しているユーザは、 .asis ファイルが asis-handler に関連付けられているときには、 ハンドラオプションの使用を好むでしょう。

最後に、mod_mime が認識しない拡張子であろうとも、 どんな拡張子でもマッチさせる Any が使用できます。 この挙動は Apache 1.3 のときと同じもので、予期しない動作、例えば .old や .bak ファイルといったウェブマスタが送信を意図していない ファイルを送信する、といった動作を行なう可能性があります。

例えば次の設定では、ハンドラやフィルタが Multiviews に参加することが できますし、未知のファイルは除外することができます。

MultiviewsMatch Handlers Filters

参照

  • Options
  • mod_negotiation

RemoveCharset ディレクティブ

説明: | ファイルの拡張子に関連付けられたすべての文字セット を解除する
構文: | RemoveCharset extension [extension] ...
コンテキスト: | バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime
互換性: | 2.0.24 以降で使用可能

RemoveCharset ディレクティブ は与えられた拡張子に関連付けられた文字セットを取り消します。 これにより、サブディレクトリにある .htaccess ファイルが親ディレクトリやサーバの設定ファイル から継承した関連付けを取り消すことができます。例えば:

extension は大文字小文字を区別しません。 また、最初のドットはあってもなくても構いません。

例

RemoveCharset .html .shtml

RemoveEncoding ディレクティブ

説明: | ファイルの拡張子に関連付けられたすべてのコンテントエンコーディング を解除する
構文: | RemoveEncoding extension [extension] ...
コンテキスト: | バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime

RemoveEncoding ディレクティブは、 与えられた拡張子に関連付けられたエンコーディングを取り消します。 これにより、サブディレクトリにある .htaccess ファイルが親ディレクトリやサーバの設定ファイルから継承した関連付けを 取り消すことができます。

/foo/.htaccess:

AddEncoding x-gzip .gz
AddType text/plain .asc
<Files *.gz.asc>
RemoveEncoding .gz
 </Files>

これは、foo.gz は gzip でエンコードされていることを指定しますが、foo.gz.asc はエンコードされていないプレーンテキストの ファイルであるということを指定します。

注意

RemoveEncoding は AddEncoding ディレクティブの後で処理されますので、 同じディレクトリの設定中に両方が現れると、 後者の効果が打ち消される可能性があります。

extension は大文字小文字を区別しません。 また、最初のドットはあってもなくても構いません。

RemoveHandler ディレクティブ

説明: | ファイルの拡張子に関連付けられたすべてのハンドラを 解除する
構文: | RemoveHandler extension [extension] ...
コンテキスト: | バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime

RemoveHandler ディレクティブ は与えられた拡張子に関連付けられたハンドラを取り消します。 これにより、サブディレクトリにある .htaccess ファイルが親ディレクトリやサーバの設定ファイル から継承した関連付けを取り消すことができます。たとえば:

/foo/.htaccess:

AddHandler server-parsed .html

/foo/bar/.htaccess:

RemoveHandler .html

これは、/foo/bar ディレクトリの .html ファイルは SSI (mod_include モジュール参照) ではなく、 普通のファイルとして扱われるようにする効果があります。

extension は大文字小文字を区別しません。 また、最初のドットはあってもなくても構いません。

RemoveInputFilter ディレクティブ

説明: | ファイル拡張子に関連付けられた入力フィルタを解除する
構文: | RemoveInputFilter extension [extension] ...
コンテキスト: | バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime
互換性: | 2.0.26 以降で使用可能

RemoveInputFilter ディレクティブは 指定されたファイル拡張子に関連付けられた入力フィルタを解除します。 これを利用することで、親ディレクトリやサーバ設定ファイルから 継承した関連付けを サブディレクトリ内において .htaccess ファイルで取り消すことができます。

extension 引数は大文字小文字を区別しません。また、 最初のドットはあってもなくても構いません。

参照

  • AddInputFilter
  • SetInputFilter

RemoveLanguage ディレクティブ

説明: | ファイル拡張子に関連付けられた言語を解除する
構文: | RemoveLanguage extension [extension] ...
コンテキスト: | バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime
互換性: | 2.0.24 以降で使用可能

RemoveLanguage ディレクティブは 指定されたファイル拡張子に関連付けられた言語を解除します。 これを利用することで、親ディレクトリやサーバ設定ファイルから 継承した関連付けを サブディレクトリ内において .htaccess ファイルで取り消すことができます。

extension 引数は大文字小文字を区別しません。また、 最初のドットはついてもつかなくても構いません。

RemoveOutputFilter ディレクティブ

説明: | ファイル拡張子に関連付けられた出力フィルタを解除する
構文: | RemoveOutputFilter extension [extension] ...
コンテキスト: | バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime
互換性: | 2.0.26 以降でのみ使用可能

RemoveOutputFilter ディレクティブは 指定されたファイル拡張子に関連付けられた出力フィルタを解除します。 これを利用することで、親ディレクトリやサーバ設定ファイルから 継承した関連付けを サブディレクトリ内において .htaccess ファイルで取り消すことができます。

extension は大文字小文字を区別しません。 また、最初のドットはあってもなくても構いません。

例

RemoveOutputFilter shtml

参照

  • AddOutputFilter

RemoveType ディレクティブ

説明: | ファイルの拡張子と関連付けられたコンテントタイプを 解除する
構文: | RemoveType extension [extension] ...
コンテキスト: | バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | ベース
モジュール: | mod_mime

RemoveType ディレクティブは与えられた拡張子の MIME タイプの関連付けを取り消します。これにより、 サブディレクトリにある .htaccess ファイルが親ディレクトリやサーバの設定ファイルから継承した 関連付けを取り消すことができます。たとえば:

/foo/.htaccess:

RemoveType .cgi

これは /foo/ ディレクトリ以下の .cgi ファイルの特別な扱いを取り消します。ファイルは DefaultType として扱われます。

注意

RemoveType ディレクティブは AddType ディレクティブの後に処理されますので、 両方が同じディレクトリの設定中に現れた場合、 後者の効果が打ち消される可能性があります。

extension は大文字小文字を区別しません。 また、最初のドットはあってもなくても構いません。

TypesConfig ディレクティブ

説明: | mime.types ファイルの位置
構文: | TypesConfig file-path
デフォルト: | TypesConfig conf/mime.types
コンテキスト: | サーバ設定ファイル
ステータス: | ベース
モジュール: | mod_mime

TypesConfig ディレクティブは、MIME タイプ設定ファイルの位置を設定します。filename は ServerRoot からの相対パスです。 このファイルはファイルの拡張子からコンテントタイプへの デフォルトのマッピングを設定します。 ほとんどの管理者は、よく使われるファイル名の拡張子を IANA に登録されたコンテントタイプに関連付けている、 Apache の mime.types ファイルを使います。 現在の一覧は http://www.isi.edu/in-notes/iana/assignments/media-types/media-types で管理されています。これは、主要なメディアタイプの定義を提供して、 必要ところを AddType で 上書きする、という方法で httpd.conf を簡略にします。 mime.types はサーバをアップグレードしたときに 置き換えられるかもしれないので、そのファイルを直接 編集しないでください。

ファイルは、AddType ディレクティブの引数と同じ形式の行で構成されます。

MIME-type [extension] ...

拡張子の大文字小文字は区別されません。空行やハッシュ (`#') で始まる行は無視されます。

(1) IANA に既に登録されている、あるいは (2) 広く受け入れられていてプラットホーム間でファイル拡張子に衝突がない、 という場合でなければ、配布中の mime.types ファイルに新たなものを登録するように Apache HTTP Server Project にリクエストしないでください。 category/x-subtype のリクエストは自動的に却下されますし、 言語や文字セットの名前空間で既に使用されていて、衝突の可能性のある 2 文字の拡張子も却下されます。

参照

  • mod_mime_magic


mod_mime_magic - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_mime_magic

Description: | Determines the MIME type of a file by looking at a few bytes of its contents
Status: | Extension
Module?dentifier: | mime_magic_module
Source?ile: | mod_mime_magic.c

Summary

This module determines the MIME type of files in the same way the Unix file(1) command works: it looks at the first few bytes of the file. It is intended as a "second line of defense" for cases that mod_mime can't resolve.

This module is derived from a free version of the file(1) command for Unix, which uses "magic numbers" and other hints from a file's contents to figure out what the contents are. This module is active only if the magic file is specified by the MimeMagicFile directive.

Format of the Magic File

The contents of the file are plain ASCII text in 4-5 columns. Blank lines are allowed but ignored. Commented lines use a hash mark (#). The remaining lines are parsed for the following columns:

Column | Description
1 byte number to begin checking from
">" indicates a dependency upon the previous non-">" line
2

type of data to match

byte | single character
short | machine-order 16-bit integer
long | machine-order 32-bit integer
string | arbitrary-length string
date | long integer date (seconds since Unix epoch/1970)
beshort | big-endian 16-bit integer
belong | big-endian 32-bit integer
bedate | big-endian 32-bit integer date
leshort | little-endian 16-bit integer
lelong | little-endian 32-bit integer
ledate | little-endian 32-bit integer date
3 | contents of data to match
4 | MIME type if matched
5 | MIME encoding if matched (optional)

For example, the following magic file lines would recognize some audio formats:

# Sun/NeXT audio data
0      string      .snd
>12    belong      1       audio/basic
>12    belong      2       audio/basic
>12    belong      3       audio/basic
>12    belong      4       audio/basic
>12    belong      5       audio/basic
>12    belong      6       audio/basic
>12    belong      7       audio/basic
>12    belong     23       audio/x-adpcm

Or these would recognize the difference between *.doc files containing Microsoft Word or FrameMaker documents. (These are incompatible file formats which use the same file suffix.)

# Frame
0  string  \<MakerFile        application/x-frame
0  string  \<MIFFile          application/x-frame
0  string  \<MakerDictionary  application/x-frame
0  string  \<MakerScreenFon   application/x-frame
0  string  \<MML              application/x-frame
0  string  \<Book             application/x-frame
0  string  \<Maker            application/x-frame

# MS-Word
0  string  \376\067\0\043            application/msword
0  string  \320\317\021\340\241\261  application/msword
0  string  \333\245-\0\0\0           application/msword

An optional MIME encoding can be included as a fifth column. For example, this can recognize gzipped files and set the encoding for them.

# gzip (GNU zip, not to be confused with
#       [Info-ZIP/PKWARE] zip archiver)

0  string  \037\213  application/octet-stream  x-gzip

Performance Issues

This module is not for every system. If your system is barely keeping up with its load or if you're performing a web server benchmark, you may not want to enable this because the processing is not free.

However, an effort was made to improve the performance of the original file(1) code to make it fit in a busy web server. It was designed for a server where there are thousands of users who publish their own documents. This is probably very common on intranets. Many times, it's helpful if the server can make more intelligent decisions about a file's contents than the file name allows ...even if just to reduce the "why doesn't my page work" calls when users improperly name their own files. You have to decide if the extra work suits your environment.

Notes

The following notes apply to the mod_mime_magic module and are included here for compliance with contributors' copyright restrictions that require their acknowledgment.

mod_mime_magic: MIME type lookup via file magic numbers
Copyright (c) 1996-1997 Cisco Systems, Inc.

This software was submitted by Cisco Systems to the Apache Group in July 1997. Future revisions and derivatives of this source code must acknowledge Cisco Systems as the original contributor of this module. All other licensing and usage conditions are those of the Apache Group.

Some of this code is derived from the free version of the file command originally posted to comp.sources.unix. Copyright info for that program is included below as required.

- Copyright (c) Ian F. Darwin, 1987. Written by Ian F. Darwin.

This software is not subject to any license of the American Telephone and Telegraph Company or of the Regents of the University of California.

Permission is granted to anyone to use this software for any purpose on any computer system, and to alter it and redistribute it freely, subject to the following restrictions:

  1. The author is not responsible for the consequences of use of this software, no matter how awful, even if they arise from flaws in it.
  2. The origin of this software must not be misrepresented, either by explicit claim or by omission. Since few users ever read sources, credits must appear in the documentation.
  3. Altered versions must be plainly marked as such, and must not be misrepresented as being the original software. Since few users ever read sources, credits must appear in the documentation.
  4. This notice may not be removed or altered.

For compliance with Mr Darwin's terms: this has been very significantly modified from the free "file" command.

  • all-in-one file for compilation convenience when moving from one version of Apache to the next.
  • Memory allocation is done through the Apache API's pool structure.
  • All functions have had necessary Apache API request or server structures passed to them where necessary to call other Apache API routines. (i.e., usually for logging, files, or memory allocation in itself or a called function.)
  • struct magic has been converted from an array to a single-ended linked list because it only grows one record at a time, it's only accessed sequentially, and the Apache API has no equivalent of realloc().
  • Functions have been changed to get their parameters from the server configuration instead of globals. (It should be reentrant now but has not been tested in a threaded environment.)
  • Places where it used to print results to stdout now saves them in a list where they're used to set the MIME type in the Apache request record.
  • Command-line flags have been removed since they will never be used here.

MimeMagicFile Directive

Description: | Enable MIME-type determination based on file contents using the specified magic file
Syntax: | MimeMagicFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_mime_magic

The MimeMagicFile directive can be used to enable this module, the default file is distributed at conf/magic. Non-rooted paths are relative to the ServerRoot. Virtual hosts will use the same file as the main server unless a more specific setting is used, in which case the more specific setting overrides the main server's file.

Example

MimeMagicFile conf/magic


mod_negotiation - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_negotiation

説明: | コンテントネゴシエーション 機能を提供する
ステータス: | Base
モジュール識別子: | negotiation_module
ソースファイル: | mod_negotiation.c

概要

コンテントネゴシエーション、より正確にはコンテンツの選択機能は、 複数用意されているドキュメントから、クライアントの能力に一番合った ドキュメントを選択する機能です。この実装は二つあります。

  • タイプマップ (type-map ハンドラで扱われるファイル)。これは variants を含んでいるファイルを明示的に指定します。
  • MultiViews の探索 (MultiViews Option で有効になります)。 サーバが暗黙の内にファイル名のパターンマッチを行ない、 その結果から選択します。

参照

  • Options
  • mod_mime
  • コンテントネゴシエーション
  • 環境変数

タイプマップ

タイプマップは RFC 822 のメールヘッダに類似した書式です。 ドキュメントの記述が空行で分離されて書かれていて、ハッシュ文字 ('#') で始まる行はコメントとして扱われます。 ドキュメントの説明は複数のヘッダレコードから構成されます。 レコードは、続きの行が空白で始まっていると複数の行にまたがります。 最初の空白が消去されて、前の行とつなげて 1 行として扱われます。 ヘッダレコードはキーワード名の後に値が続くという形式で、 キーワード名は常にコロンで終わります。空白はヘッダ名と値の間、 値のトークンの間に入れることができます。 使用可能なヘッダは以下のとおりです:

Content-Encoding:
ファイルのエンコーディング。Apache は AddEncoding ディレクティブ で定義されたエンコーディングだけを認識します。通常 compress されたファイルのための x-compress と gzip されたファイルのための x-gzip を含みます。 エンコーディングの比較をするときは、接頭辞 x- は無視されます。
Content-Language:
インターネット標準の言語タグ (RFC 1766) で定義されている言語の種類。例えば、en は英語を表します。 複数の言語が格納される場合はコンマで区切られます。
Content-Length:
ファイルの長さ (バイト数)。 このヘッダがない場合、ファイルの実際の長さが使用されます。
Content-Type:
ドキュメントの MIME メディアタイプ、オプショナルなパラメータ付き。パラメータの構文は name=value で、メディアタイプや他のパラメータとはセミコロンで分離されます。 共通のパラメータは以下のとおり:
level
メディアタイプのバージョンを示す整数。 text/html では 2 がデフォルトで、その他の場合は 0 がデフォルトです。
qs
クライアントの能力に関係なく、variant を他と比較したときの相対的な「品質」で、0.0 から 1.0 の範囲の浮動点小数。 例えば、写真を表現しようとしているときは普通は JPEG ファイルの方が ASCII ファイルよりも高い品質になります。 しかし、リソースが ASCII アートで表現されているときは、ASCII ファイルの方が JPEG ファイルよりも高い品質になります。このように、qs はリソース毎に特有の値を取ります。

例

Content-Type: image/jpeg; qs=0.8

URI:
(指定のメディアタイプ、コンテントエンコーディングの) variant の ファイルの uri. これは、マップファイルからの相対 URL として 解釈されます。同じサーバに存在しなければならず、クライアントが 直接リクエストしたときにアクセスを許可されるものでなければなりません。
Body:
Apache 2.0 で新設されたこの Body ヘッダを使って、 リソースの実際の内容をタイプマップファイルに書くことができます。 このヘッダは本文の内容の区切りとなる文字列で始まる必要があります。 タイプマップファイルの続く行は、区切り文字列が見つかるまで、 リソースの本文になります。

Example:

Body:----xyz----
<html>
<body>
<p>Content of the page.</p>
</body>
</html>
----xyz----

MultiViews

MultiViews 探索は、Multiviews Options ディレクティブにより有効になります。 サーバが /some/dir/foo へのリクエストを受け取り、/some/dir/foo が存在 しない場合、サーバはディレクトリを読んで、 foo.* にあてはまる全てのファイルを探し、 事実上それらのファイルをマップするタイプマップを作ります。 そのとき、メディアタイプとコンテントエンコーディングは、 そのファイル名を直接指定したときと同じものが割り当てられます。 それからクライアントの要求に一番合うものを選び、 そのドキュメントを返します。

ファイルを選択する際に、関連するコンテントネゴシエーションの メタ情報を持たないファイルについて、判定を行うかどうかを MultiViewsMatch ディレクティブで設定します。

CacheNegotiatedDocs ディレクティブ

説明: | コンテントネゴシエーションされたドキュメントをプロキシサーバが キャッシュできるようにする
構文: | CacheNegotiatedDocs On|Off
デフォルト: | CacheNegotiatedDocs Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_negotiation
互換性: | バージョン 2.0で構文が変わりました

このディレクティブが設定されていると、コンテントネゴシエーション をした結果のドキュメントのキャッシュを許可します。 これは、プロキシの後ろにいるクライアントが能力に一番合った ドキュメントではなく、 キャッシュをより効果的にするものを得る可能性があるということです。

このディレクティブは HTTP/1.0 ブラウザからのリクエスト のみに適用されます。HTTP/1.1 は、 交渉されたドキュメントのキャッシュに対してずっとよい制御が可能なので、 このディレクティブは HTTP/1.1 のリクエストには影響しません。

2.0 より前のバージョンでは、 CacheNegotiatedDocs は引数を取らず、 ディレクティブが存在することで on の動作をしていました。

ForceLanguagePriority ディレクティブ

説明: | 要求に合う単独のドキュメントが見つからなかったときに行なうことを指定
構文: | ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]
デフォルト: | ForceLanguagePriority Prefer
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_negotiation
互換性: | バージョン 2.0.30 以降で使用可能

ForceLanguagePriority ディレクティブは 要求に合うドキュメントを一つだけ返すことができないときに、 LanguagePriority ディレクティブを使ってネゴシエーションの結果を返します。

ForceLanguagePriority Prefer は、同等の選択肢が いくつかあるときに、HTTP の 300 (MULTIPLE CHOICES) を返す代わりに、 LanguagePriority を使って一つだけドキュメントを返すように します。以下のディレクティブが指定されていて、ユーザの Accept-Language ヘッダでは en と de の品質が共に .500 (同じくらい許容) であるときは、 最初にマッチする variant の en が送られます。

LanguagePriority en fr de
ForceLanguagePriority Prefer

ForceLanguagePriority Fallback では、HTTP 406 (NOT ACCEPTABLE) を送信する代わりに、 LanguagePriority が正しい結果を送ります。 以下のディレクティブが指定されていて、ユーザの Accept-Language が es 言語のみを許可していて、さらにそのような variant がないときには、 以下の LanguagePriority のリストの最初の variant が送れれます。

LanguagePriority en fr de
ForceLanguagePriority Fallback

Prefer と Fallback の両方のオプションを 同時に指定することができます。 ですから、複数の variant があるときは LanguagePriority の最初の variant が送られ、クライアントの許容言語に合う vaiant がないときは 存在するドキュメントで最初のものが送られる、という様にすることができます。

参照

  • AddLanguage

LanguagePriority ディレクティブ

説明: | クライアントが優先度を示さなかったときの言語の variant の優先度を 指定
構文: | LanguagePriority MIME-lang [MIME-lang] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_negotiation

LanguagePriority は、MultiViews リクエストを扱うときに、クライアントが優先順位を提供していない場合の 言語の優先順位を設定します。MIME-lang のリストが優先度の降順に並びます。

Example:

LanguagePriority en fr de

foo.html がリクエストされ、foo.html.fr と foo.html.de が両方存在し、 ブラウザが言語の優先順位を提供してない場合は foo.html.fr が返されます。

このディレクティブは他の方法で「最善」 の言語が決定できないときか、ForceLanguagePriority ディレクティブが None 以外のときにのみ効果があることに注意してください。 一般的には、サーバ側ではなくクライアント側で好みの言語を決定します。

参照

  • AddLanguage


mod_nw_ssl - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_nw_ssl

Description: | Enable SSL encryption for NetWare
Status: | Base
Module?dentifier: | nwssl_module
Source?ile: | mod_nw_ssl.c
Compatibility: | NetWare only

Summary

This module enables SSL encryption for a specified port. It takes advantage of the SSL encryption functionality that is built into the NetWare operating system.

NWSSLTrustedCerts Directive

Description: | List of additional client certificates
Syntax: | NWSSLTrustedCerts filename [filename] ...
Context: | server config
Status: | Base
Module: | mod_nw_ssl

Specifies a list of client certificate files (DER format) that are used when creating a proxied SSL connection. Each client certificate used by a server must be listed separately in its own .der file.

NWSSLUpgradeable Directive

Description: | Allows a connection to be upgraded to an SSL connection upon request
Syntax: | NWSSLUpgradeable [IP-address:]portnumber
Context: | server config
Status: | Base
Module: | mod_nw_ssl

Allow a connection that was created on the specified address and/or port to be upgraded to an SSL connection upon request from the client. The address and/or port must have already be defined previously with a Listen directive.

SecureListen Directive

Description: | Enables SSL encryption for the specified port
Syntax: | SecureListen [IP-address:]portnumber Certificate-Name [MUTUAL]
Context: | server config
Status: | Base
Module: | mod_nw_ssl

Specifies the port and the eDirectory based certificate name that will be used to enable SSL encryption. An optional third parameter also enables mutual authentication.


mod_proxy - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_proxy

Description: | HTTP/1.1 proxy/gateway server
Status: | Extension
Module?dentifier: | proxy_module
Source?ile: | mod_proxy.c

Summary

Warning

Do not enable proxying with ProxyRequests until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

This module implements a proxy/gateway for Apache. It implements proxying capability for FTP, CONNECT (for SSL), HTTP/0.9, HTTP/1.0, and HTTP/1.1. The module can be configured to connect to other proxy modules for these and other protocols.

Apache's proxy features are divided into several modules in addition to mod_proxy: mod_proxy_http, mod_proxy_ftp and mod_proxy_connect. Thus, if you want to use one or more of the particular proxy functions, load mod_proxy and the appropriate module(s) into the server (either statically at compile-time or dynamically via the LoadModule directive).

In addition, extended features are provided by other modules. Caching is provided by mod_cache and related modules. The ability to contact remote servers using the SSL/TLS protocol is provided by the SSLProxy* directives of mod_ssl. These additional modules will need to be loaded and configured to take advantage of these features.

See also

  • mod_cache
  • mod_proxy_http
  • mod_proxy_ftp
  • mod_proxy_connect
  • mod_ssl

Forward and Reverse Proxies

Apache can be configured in both a forward and reverse proxy mode.

An ordinary forward proxy is an intermediate server that sits between the client and the origin server. In order to get content from the origin server, the client sends a request to the proxy naming the origin server as the target and the proxy then requests the content from the origin server and returns it to the client. The client must be specially configured to use the forward proxy to access other sites.

A typical usage of a forward proxy is to provide Internet access to internal clients that are otherwise restricted by a firewall. The forward proxy can also use caching (as provided by mod_cache) to reduce network usage.

The forward proxy is activated using the ProxyRequests directive. Because forward proxys allow clients to access arbitrary sites through your server and to hide their true origin, it is essential that you secure your server so that only authorized clients can access the proxy before activating a forward proxy.

A reverse proxy, by contrast, appears to the client just like an ordinary web server. No special configuration on the client is necessary. The client makes ordinary requests for content in the name-space of the reverse proxy. The reverse proxy then decides where to send those requests, and returns the content as if it was itself the origin.

A typical usage of a reverse proxy is to provide Internet users access to a server that is behind a firewall. Reverse proxies can also be used to balance load among several back-end servers, or to provide caching for a slower back-end server. In addition, reverse proxies can be used simply to bring several servers into the same URL space.

A reverse proxy is activated using the ProxyPass directive or the [P] flag to the RewriteRule directive. It is not necessary to turn ProxyRequests on in order to configure a reverse proxy.

Basic Examples

The examples below are only a very basic idea to help you get started. Please read the documentation on the individual directives.

In addition, if you wish to have caching enabled, consult the documentation from mod_cache.

Forward Proxy

ProxyRequests On
ProxyVia On

<Proxy *>
Order deny,allow
Deny from all
Allow from internal.example.com
 </Proxy>

Reverse Proxy

ProxyRequests Off

<Proxy *>
Order deny,allow
Allow from all
 </Proxy>

ProxyPass /foo http://foo.example.com/bar
ProxyPassReverse /foo http://foo.example.com/bar

Controlling access to your proxy

You can control who can access your proxy via the <Proxy> control block as in the following example:

<Proxy *>
Order Deny,Allow
Deny from all
Allow from 192.168.0
 </Proxy>

For more information on access control directives, see mod_access.

Strictly limiting access is essential if you are using a forward proxy (using the ProxyRequests directive). Otherwise, your server can be used by any client to access arbitrary hosts while hiding his or her true identity. This is dangerous both for your network and for the Internet at large. When using a reverse proxy (using the ProxyPass directive with ProxyRequests Off), access control is less critical because clients can only contact the hosts that you have specifically configured.

FTP Proxy

Why doesn't file type xxx download via FTP?

You probably don't have that particular file type defined as application/octet-stream in your proxy's mime.types configuration file. A useful line can be

application/octet-stream   bin dms lha lzh exe class tgz taz

How can I force an FTP ASCII download of File xxx?

In the rare situation where you must download a specific file using the FTP ASCII transfer method (while the default transfer is in binary mode), you can override mod_proxy's default by suffixing the request with ;type=a to force an ASCII transfer. (FTP Directory listings are always executed in ASCII mode, however.)

How can I access FTP files outside of my home directory?

An FTP URI is interpreted relative to the home directory of the user who is logging in. Alas, to reach higher directory levels you cannot use /../, as the dots are interpreted by the browser and not actually sent to the FTP server. To address this problem, the so called Squid %2f hack was implemented in the Apache FTP proxy; it is a solution which is also used by other popular proxy servers like the Squid Proxy Cache. By prepending /%2f to the path of your request, you can make such a proxy change the FTP starting directory to / (instead of the home directory). For example, to retrieve the file /etc/motd, you would use the URL:

ftp://user@host/%2f/etc/motd

How can I hide the FTP cleartext password in my browser's URL line?

To log in to an FTP server by username and password, Apache uses different strategies. In absense of a user name and password in the URL altogether, Apache sends an anonymous login to the FTP server, i.e.,

user: anonymous
password: apache_proxy@

This works for all popular FTP servers which are configured for anonymous access.

For a personal login with a specific username, you can embed the user name into the URL, like in:

ftp://username@host/myfile

If the FTP server asks for a password when given this username (which it should), then Apache will reply with a 401 (Authorization required) response, which causes the Browser to pop up the username/password dialog. Upon entering the password, the connection attempt is retried, and if successful, the requested resource is presented. The advantage of this procedure is that your browser does not display the password in cleartext (which it would if you had used

ftp://username:password@host/myfile

in the first place).

Note

The password which is transmitted in such a way is not encrypted on its way. It travels between your browser and the Apache proxy server in a base64-encoded cleartext string, and between the Apache proxy and the FTP server as plaintext. You should therefore think twice before accessing your FTP server via HTTP (or before accessing your personal files via FTP at all!) When using unsecure channels, an eavesdropper might intercept your password on its way.

Slow Startup

If you're using the ProxyBlock directive, hostnames' IP addresses are looked up and cached during startup for later match test. This may take a few seconds (or more) depending on the speed with which the hostname lookups occur.

Intranet Proxy

An Apache proxy server situated in an intranet needs to forward external requests through the company's firewall (for this, configure the ProxyRemote directive to forward the respective scheme to the firewall proxy). However, when it has to access resources within the intranet, it can bypass the firewall when accessing hosts. The NoProxy directive is useful for specifying which hosts belong to the intranet and should be accessed directly.

Users within an intranet tend to omit the local domain name from their WWW requests, thus requesting "http://somehost/" instead of http://somehost.example.com/. Some commercial proxy servers let them get away with this and simply serve the request, implying a configured local domain. When the ProxyDomain directive is used and the server is configured for proxy service, Apache can return a redirect response and send the client to the correct, fully qualified, server address. This is the preferred method since the user's bookmark files will then contain fully qualified hosts.

Protocol Adjustments

For circumstances where you have a application server which doesn't implement keepalives or HTTP/1.1 properly, there are 2 environment variables which when set send a HTTP/1.0 with no keepalive. These are set via the SetEnv directive.

These are the force-proxy-request-1.0 and proxy-nokeepalive notes.

<Location /buggyappserver/>
ProxyPass http://buggyappserver:7001/foo/
SetEnv force-proxy-request-1.0 1
SetEnv proxy-nokeepalive 1
 </Location>

AllowCONNECT Directive

Description: | Ports that are allowed to CONNECT through the proxy
Syntax: | AllowCONNECT port [port] ...
Default: | AllowCONNECT 443 563
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The AllowCONNECT directive specifies a list of port numbers to which the proxy CONNECT method may connect. Today's browsers use this method when a https connection is requested and proxy tunneling over HTTP is in effect.

By default, only the default https port (443) and the default snews port (563) are enabled. Use the AllowCONNECT directive to override this default and allow connections to the listed ports only.

Note that you'll need to have mod_proxy_connect present in the server in order to get the support for the CONNECT at all.

NoProxy Directive

Description: | Hosts, domains, or networks that will be connected to directly
Syntax: | NoProxy host [host] ...
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This directive is only useful for Apache proxy servers within intranets. The NoProxy directive specifies a list of subnets, IP addresses, hosts and/or domains, separated by spaces. A request to a host which matches one or more of these is always served directly, without forwarding to the configured ProxyRemote proxy server(s).

Example

ProxyRemote * http://firewall.mycompany.com:81
NoProxy .mycompany.com 192.168.112.0/21

The host arguments to the NoProxy directive are one of the following type list:

Domain

A Domain is a partially qualified DNS domain name, preceded by a period. It represents a list of hosts which logically belong to the same DNS domain or zone (i.e., the suffixes of the hostnames are all ending in Domain).

Examples

.com .apache.org.

To distinguish Domains from Hostnames (both syntactically and semantically; a DNS domain can have a DNS A record, too!), Domains are always written with a leading period.

Note

Domain name comparisons are done without regard to the case, and Domains are always assumed to be anchored in the root of the DNS tree, therefore two domains .MyDomain.com and .mydomain.com. (note the trailing period) are considered equal. Since a domain comparison does not involve a DNS lookup, it is much more efficient than subnet comparison.

SubNet

A SubNet is a partially qualified internet address in numeric (dotted quad) form, optionally followed by a slash and the netmask, specified as the number of significant bits in the SubNet. It is used to represent a subnet of hosts which can be reached over a common network interface. In the absence of the explicit net mask it is assumed that omitted (or zero valued) trailing digits specify the mask. (In this case, the netmask can only be multiples of 8 bits wide.) Examples:

192.168 or 192.168.0.0
the subnet 192.168.0.0 with an implied netmask of 16 valid bits (sometimes used in the netmask form 255.255.0.0)
192.168.112.0/21
the subnet 192.168.112.0/21 with a netmask of 21 valid bits (also used in the form 255.255.248.0)

As a degenerate case, a SubNet with 32 valid bits is the equivalent to an IPAddr, while a SubNet with zero valid bits (e.g., 0.0.0.0/0) is the same as the constant _Default_, matching any IP address.

IPAddr

A IPAddr represents a fully qualified internet address in numeric (dotted quad) form. Usually, this address represents a host, but there need not necessarily be a DNS domain name connected with the address.

Example

192.168.123.7

Note

An IPAddr does not need to be resolved by the DNS system, so it can result in more effective apache performance.

Hostname

A Hostname is a fully qualified DNS domain name which can be resolved to one or more IPAddrs via the DNS domain name service. It represents a logical host (in contrast to Domains, see above) and must be resolvable to at least one IPAddr (or often to a list of hosts with different IPAddrs).

Examples

prep.ai.mit.edu
www.apache.org

Note

In many situations, it is more effective to specify an IPAddr in place of a Hostname since a DNS lookup can be avoided. Name resolution in Apache can take a remarkable deal of time when the connection to the name server uses a slow PPP link.

Hostname comparisons are done without regard to the case, and Hostnames are always assumed to be anchored in the root of the DNS tree, therefore two hosts WWW.MyDomain.com and www.mydomain.com. (note the trailing period) are considered equal.

See also

  • DNS Issues

<Proxy> Directive

Description: | Container for directives applied to proxied resources
Syntax: | <Proxy wildcard-url> ...</Proxy>
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

Directives placed in <Proxy> sections apply only to matching proxied content. Shell-style wildcards are allowed.

For example, the following will allow only hosts in yournetwork.example.com to access content via your proxy server:

<Proxy *>
Order Deny,Allow
Deny from all
Allow from yournetwork.example.com
 </Proxy>

The following example will process all files in the foo directory of example.com through the INCLUDES filter when they are sent through the proxy server:

<Proxy http://example.com/foo/*>
SetOutputFilter INCLUDES
 </Proxy>

ProxyBadHeader Directive

Description: | Determines how to handle bad header lines in a response
Syntax: | ProxyBadHeader IsError|Ignore|StartBody
Default: | ProxyBadHeader IsError
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | available in Apache 2.0.44 and later

The ProxyBadHeader directive determines the behaviour of mod_proxy if it receives syntactically invalid header lines (i.e. containing no colon). The following arguments are possible:

IsError
Abort the request and end up with a 502 (Bad Gateway) response. This is the default behaviour.
Ignore
Treat bad header lines as if they weren't sent.
StartBody
When receiving the first bad header line, finish reading the headers and treat the remainder as body. This helps to work around buggy backend servers which forget to insert an empty line between the headers and the body.

ProxyBlock Directive

Description: | Words, hosts, or domains that are banned from being proxied
Syntax: | ProxyBlock *|word|host|domain [word|host|domain] ...
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyBlock directive specifies a list of words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and FTP document requests to sites whose names contain matched words, hosts or domains are blocked by the proxy server. The proxy module will also attempt to determine IP addresses of list items which may be hostnames during startup, and cache them for match test as well. That may slow down the startup time of the server.

Example

ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu

rocky.wotsamattau.edu would also be matched if referenced by IP address.

Note that wotsamattau would also be sufficient to match wotsamattau.edu.

Note also that

ProxyBlock *

blocks connections to all sites.

ProxyDomain Directive

Description: | Default domain name for proxied requests
Syntax: | ProxyDomain Domain
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This directive is only useful for Apache proxy servers within intranets. The ProxyDomain directive specifies the default domain which the apache proxy server will belong to. If a request to a host without a domain name is encountered, a redirection response to the same host with the configured Domain appended will be generated.

Example

ProxyRemote * http://firewall.mycompany.com:81
NoProxy .mycompany.com 192.168.112.0/21
ProxyDomain .mycompany.com

ProxyErrorOverride Directive

Description: | Override error pages for proxied content
Syntax: | ProxyErrorOverride On|Off
Default: | ProxyErrorOverride Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | Available in version 2.0 and later

This directive is useful for reverse-proxy setups, where you want to have a common look and feel on the error pages seen by the end user. This also allows for included files (via mod_include's SSI) to get the error code and act accordingly (default behavior would display the error page of the proxied server, turning this on shows the SSI Error message).

ProxyIOBufferSize Directive

Description: | Determine size of internal data throughput buffer
Syntax: | ProxyIOBufferSize bytes
Default: | ProxyIOBufferSize 8192
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyIOBufferSize directive adjusts the size of the internal buffer, which is used as a scratchpad for the data between input and output. The size must be less or equal 8192.

In almost every case there's no reason to change that value.

<ProxyMatch> Directive

Description: | Container for directives applied to regular-expression-matched proxied resources
Syntax: | <ProxyMatch regex> ...</ProxyMatch>
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The <ProxyMatch> directive is identical to the <Proxy> directive, except it matches URLs using regular expressions.

ProxyMaxForwards Directive

Description: | Maximium number of proxies that a request can be forwarded through
Syntax: | ProxyMaxForwards number
Default: | ProxyMaxForwards 10
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | Available in Apache 2.0 and later

The ProxyMaxForwards directive specifies the maximum number of proxies through which a request may pass, if there's no Max-Forwards header supplied with the request. This is set to prevent infinite proxy loops, or a DoS attack.

Example

ProxyMaxForwards 15

ProxyPass Directive

Description: | Maps remote servers into the local server URL-space
Syntax: | ProxyPass [path] !|url
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy

This directive allows remote servers to be mapped into the space of the local server; the local server does not act as a proxy in the conventional sense, but appears to be a mirror of the remote server. path is the name of a local virtual path; url is a partial URL for the remote server and cannot include a query string.

Suppose the local server has address http://example.com/; then

ProxyPass /mirror/foo/ http://backend.example.com/

will cause a local request for http://example.com/mirror/foo/bar to be internally converted into a proxy request to http://backend.example.com/bar.

The ! directive is useful in situations where you don't want to reverse-proxy a subdirectory, e.g.

ProxyPass /mirror/foo/i !
ProxyPass /mirror/foo http://backend.example.com

will proxy all requests to /mirror/foo to backend.example.com except requests made to /mirror/foo/i.

Note

Order is important. you need to put the exclusions before the general proxypass directive.

When used inside a <Location> section, the first argument is omitted and the local directory is obtained from the <Location>.

The ProxyRequests directive should usually be set off when using ProxyPass.

If you require a more flexible reverse-proxy configuration, see the RewriteRule directive with the [P] flag.

ProxyPassReverse Directive

Description: | Adjusts the URL in HTTP response headers sent from a reverse proxied server
Syntax: | ProxyPassReverse [path] url
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy

This directive lets Apache adjust the URL in the Location, Content-Location and URI headers on HTTP redirect responses. This is essential when Apache is used as a reverse proxy to avoid by-passing the reverse proxy because of HTTP redirects on the backend servers which stay behind the reverse proxy.

Only the HTTP response headers specifically mentioned above will be rewritten. Apache will not rewrite other response headers, nor will it rewrite URL references inside HTML pages. This means that if the proxied content contains absolute URL references, they will by-pass the proxy. A third-party module that will look inside the HTML and rewrite URL references is Nick Kew's mod_proxy_html.

path is the name of a local virtual path. url is a partial URL for the remote server - the same way they are used for the ProxyPass directive.

For example, suppose the local server has address http://example.com/; then

ProxyPass /mirror/foo/ http://backend.example.com/
ProxyPassReverse /mirror/foo/ http://backend.example.com/

will not only cause a local request for the http://example.com/mirror/foo/bar to be internally converted into a proxy request to http://backend.example.com/bar (the functionality ProxyPass provides here). It also takes care of redirects the server backend.example.com sends: when http://backend.example.com/bar is redirected by him to http://backend.example.com/quux Apache adjusts this to http://example.com/mirror/foo/quux before forwarding the HTTP redirect response to the client. Note that the hostname used for constructing the URL is chosen in respect to the setting of the UseCanonicalName directive.

Note that this ProxyPassReverse directive can also be used in conjunction with the proxy pass-through feature (RewriteRule ... [P]) from mod_rewrite because its doesn't depend on a corresponding ProxyPass directive.

When used inside a <Location> section, the first argument is omitted and the local directory is obtained from the <Location>.

ProxyPreserveHost Directive

Description: | Use incoming Host HTTP request header for proxy request
Syntax: | ProxyPreserveHost On|Off
Default: | ProxyPreserveHost Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | Available in Apache 2.0.31 and later.

When enabled, this option will pass the Host: line from the incoming request to the proxied host, instead of the hostname specified in the proxypass line.

This option should normally be turned Off. It is mostly useful in special configurations like proxied mass name-based virtual hosting, where the original Host header needs to be evaluated by the backend server.

ProxyReceiveBufferSize Directive

Description: | Network buffer size for proxied HTTP and FTP connections
Syntax: | ProxyReceiveBufferSize bytes
Default: | ProxyReceiveBufferSize 0
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyReceiveBufferSize directive specifies an explicit (TCP/IP) network buffer size for proxied HTTP and FTP connections, for increased throughput. It has to be greater than 512 or set to 0 to indicate that the system's default buffer size should be used.

Example

ProxyReceiveBufferSize 2048

ProxyRemote Directive

Description: | Remote proxy used to handle certain requests
Syntax: | ProxyRemote match remote-server
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This defines remote proxies to this proxy. match is either the name of a URL-scheme that the remote server supports, or a partial URL for which the remote server should be used, or * to indicate the server should be contacted for all requests. remote-server is a partial URL for the remote server. Syntax:

remote-server = scheme://hostname[:port]

scheme is effectively the protocol that should be used to communicate with the remote server; only http is supported by this module.

Example

ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000
ProxyRemote * http://cleversite.com
ProxyRemote ftp http://ftpproxy.mydomain.com:8080

In the last example, the proxy will forward FTP requests, encapsulated as yet another HTTP proxy request, to another proxy which can handle them.

This option also supports reverse proxy configuration - a backend webserver can be embedded within a virtualhost URL space even if that server is hidden by another forward proxy.

ProxyRemoteMatch Directive

Description: | Remote proxy used to handle requests matched by regular expressions
Syntax: | ProxyRemoteMatch regex remote-server
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyRemoteMatch is identical to the ProxyRemote directive, except the first argument is a regular expression match against the requested URL.

ProxyRequests Directive

Description: | Enables forward (standard) proxy requests
Syntax: | ProxyRequests On|Off
Default: | ProxyRequests Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This allows or prevents Apache from functioning as a forward proxy server. (Setting ProxyRequests to Off does not disable use of the ProxyPass directive.)

In a typical reverse proxy configuration, this option should be set to Off.

In order to get the functionality of proxying HTTP or FTP sites, you need also mod_proxy_http or mod_proxy_ftp (or both) present in the server.

Warning

Do not enable proxying with ProxyRequests until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

ProxyTimeout Directive

Description: | Network timeout for proxied requests
Syntax: | ProxyTimeout seconds
Default: | ProxyTimeout 300
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | Available in Apache 2.0.31 and later

This directive allows a user to specifiy a timeout on proxy requests. This is useful when you have a slow/buggy appserver which hangs, and you would rather just return a timeout and fail gracefully instead of waiting however long it takes the server to return.

ProxyVia Directive

Description: | Information provided in the Via HTTP response header for proxied requests
Syntax: | ProxyVia On|Off|Full|Block
Default: | ProxyVia Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This directive controls the use of the Via: HTTP header by the proxy. Its intended use is to control the flow of of proxy requests along a chain of proxy servers. See RFC 2616 (HTTP/1.1), section 14.45 for an explanation of Via: header lines.

  • If set to Off, which is the default, no special processing is performed. If a request or reply contains a Via: header, it is passed through unchanged.
  • If set to On, each request and reply will get a Via: header line added for the current host.
  • If set to Full, each generated Via: header line will additionally have the Apache server version shown as a Via: comment field.
  • If set to Block, every proxy request will have all its Via: header lines removed. No new Via: header will be generated.


mod_proxy_connect - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_proxy_connect

Description: | mod_proxy extension for CONNECT request handling
Status: | Extension
Module?dentifier: | proxy_connect_module
Source?ile: | proxy_connect.c

Summary

This module requires the service of mod_proxy. It provides support for the CONNECT HTTP method. This method is mainly used to tunnel SSL requests through proxy servers.

Thus, in order to get the ability of handling CONNECT requests, mod_proxy and mod_proxy_connect have to be present in the server.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • AllowCONNECT
  • mod_proxy


mod_proxy_ftp - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_proxy_ftp

Description: | FTP support module for mod_proxy
Status: | Extension
Module?dentifier: | proxy_ftp_module
Source?ile: | proxy_ftp.c

Summary

This module requires the service of mod_proxy. It provides support for the proxying FTP sites.

Thus, in order to get the ability of handling FTP proxy requests, mod_proxy and mod_proxy_ftp have to be present in the server.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • mod_proxy


mod_proxy_http - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_proxy_http

Description: | HTTP support module for mod_proxy
Status: | Extension
Module?dentifier: | proxy_http_module
Source?ile: | proxy_http.c

Summary

This module requires the service of mod_proxy. It provides the features used for proxying HTTP requests. mod_proxy_http supports HTTP/0.9, HTTP/1.0 and HTTP/1.1. It does not provide any caching abilities. If you want to set up a caching proxy, you might want to use the additional service of the mod_cache module.

Thus, in order to get the ability of handling HTTP proxy requests, mod_proxy and mod_proxy_http have to be present in the server.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • mod_proxy
  • mod_proxy_connect


mod_rewrite - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_rewrite

Description: | Provides a rule-based rewriting engine to rewrite requested URLs on the fly
Status: | Extension
Module?dentifier: | rewrite_module
Source?ile: | mod_rewrite.c
Compatibility: | Available in Apache 1.3 and later

Summary

``The great thing about mod_rewrite is it gives you all the configurability and flexibility of Sendmail. The downside to mod_rewrite is that it gives you all the configurability and flexibility of Sendmail.''

-- Brian Behlendorf
Apache Group

`` Despite the tons of examples and docs, mod_rewrite is voodoo. Damned cool voodoo, but still voodoo. ''

-- Brian Moore
bem@news.cmc.net

Welcome to mod_rewrite, the Swiss Army Knife of URL manipulation!

This module uses a rule-based rewriting engine (based on a regular-expression parser) to rewrite requested URLs on the fly. It supports an unlimited number of rules and an unlimited number of attached rule conditions for each rule to provide a really flexible and powerful URL manipulation mechanism. The URL manipulations can depend on various tests, for instance server variables, environment variables, HTTP headers, time stamps and even external database lookups in various formats can be used to achieve a really granular URL matching.

This module operates on the full URLs (including the path-info part) both in per-server context (httpd.conf) and per-directory context (.htaccess) and can even generate query-string parts on result. The rewritten result can lead to internal sub-processing, external request redirection or even to an internal proxy throughput.

But all this functionality and flexibility has its drawback: complexity. So don't expect to understand this entire module in just one day.

This module was invented and originally written in April 1996 and gifted exclusively to the The Apache Group in July 1997 by

Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com

Internal Processing

The internal processing of this module is very complex but needs to be explained once even to the average user to avoid common mistakes and to let you exploit its full functionality.

API Phases

First you have to understand that when Apache processes a HTTP request it does this in phases. A hook for each of these phases is provided by the Apache API. Mod_rewrite uses two of these hooks: the URL-to-filename translation hook which is used after the HTTP request has been read but before any authorization starts and the Fixup hook which is triggered after the authorization phases and after the per-directory config files (.htaccess) have been read, but before the content handler is activated.

So, after a request comes in and Apache has determined the corresponding server (or virtual server) the rewriting engine starts processing of all mod_rewrite directives from the per-server configuration in the URL-to-filename phase. A few steps later when the final data directories are found, the per-directory configuration directives of mod_rewrite are triggered in the Fixup phase. In both situations mod_rewrite rewrites URLs either to new URLs or to filenames, although there is no obvious distinction between them. This is a usage of the API which was not intended to be this way when the API was designed, but as of Apache 1.x this is the only way mod_rewrite can operate. To make this point more clear remember the following two points:

  1. Although mod_rewrite rewrites URLs to URLs, URLs to filenames and even filenames to filenames, the API currently provides only a URL-to-filename hook. In Apache 2.0 the two missing hooks will be added to make the processing more clear. But this point has no drawbacks for the user, it is just a fact which should be remembered: Apache does more in the URL-to-filename hook than the API intends for it.
  2. Unbelievably mod_rewrite provides URL manipulations in per-directory context, i.e., within .htaccess files, although these are reached a very long time after the URLs have been translated to filenames. It has to be this way because .htaccess files live in the filesystem, so processing has already reached this stage. In other words: According to the API phases at this time it is too late for any URL manipulations. To overcome this chicken and egg problem mod_rewrite uses a trick: When you manipulate a URL/filename in per-directory context mod_rewrite first rewrites the filename back to its corresponding URL (which is usually impossible, but see the RewriteBase directive below for the trick to achieve this) and then initiates a new internal sub-request with the new URL. This restarts processing of the API phases.

    Again mod_rewrite tries hard to make this complicated step totally transparent to the user, but you should remember here: While URL manipulations in per-server context are really fast and efficient, per-directory rewrites are slow and inefficient due to this chicken and egg problem. But on the other hand this is the only way mod_rewrite can provide (locally restricted) URL manipulations to the average user.

Don't forget these two points!

Ruleset Processing

Now when mod_rewrite is triggered in these two API phases, it reads the configured rulesets from its configuration structure (which itself was either created on startup for per-server context or during the directory walk of the Apache kernel for per-directory context). Then the URL rewriting engine is started with the contained ruleset (one or more rules together with their conditions). The operation of the URL rewriting engine itself is exactly the same for both configuration contexts. Only the final result processing is different.

The order of rules in the ruleset is important because the rewriting engine processes them in a special (and not very obvious) order. The rule is this: The rewriting engine loops through the ruleset rule by rule (RewriteRule directives) and when a particular rule matches it optionally loops through existing corresponding conditions (RewriteCond directives). For historical reasons the conditions are given first, and so the control flow is a little bit long-winded. See Figure 1 for more details.

[Needs graphics capability to display]
Figure 1:The control flow through the rewriting ruleset

As you can see, first the URL is matched against the Pattern of each rule. When it fails mod_rewrite immediately stops processing this rule and continues with the next rule. If the Pattern matches, mod_rewrite looks for corresponding rule conditions. If none are present, it just substitutes the URL with a new value which is constructed from the string Substitution and goes on with its rule-looping. But if conditions exist, it starts an inner loop for processing them in the order that they are listed. For conditions the logic is different: we don't match a pattern against the current URL. Instead we first create a string TestString by expanding variables, back-references, map lookups, etc. and then we try to match CondPattern against it. If the pattern doesn't match, the complete set of conditions and the corresponding rule fails. If the pattern matches, then the next condition is processed until no more conditions are available. If all conditions match, processing is continued with the substitution of the URL with Substitution.

Quoting Special Characters

As of Apache 1.3.20, special characters in TestString and Substitution strings can be escaped (that is, treated as normal characters without their usual special meaning) by prefixing them with a slosh ('\') character. In other words, you can include an actual dollar-sign character in a Substitution string by using '\$'; this keeps mod_rewrite from trying to treat it as a backreference.

Regex Back-Reference Availability

One important thing here has to be remembered: Whenever you use parentheses in Pattern or in one of the CondPattern, back-references are internally created which can be used with the strings $N and %N (see below). These are available for creating the strings Substitution and TestString. Figure 2 shows to which locations the back-references are transfered for expansion.

[Needs graphics capability to display]
Figure 2: The back-reference flow through a rule.

We know this was a crash course on mod_rewrite's internal processing. But you will benefit from this knowledge when reading the following documentation of the available directives.

Environment Variables

This module keeps track of two additional (non-standard) CGI/SSI environment variables named SCRIPT_URL and SCRIPT_URI. These contain the logical Web-view to the current resource, while the standard CGI/SSI variables SCRIPT_NAME and SCRIPT_FILENAME contain the physical System-view.

Notice: These variables hold the URI/URL as they were initially requested, i.e., before any rewriting. This is important because the rewriting process is primarily used to rewrite logical URLs to physical pathnames.

Example

SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
SCRIPT_FILENAME=/u/rse/.www/index.html
SCRIPT_URL=/u/rse/
SCRIPT_URI=http://en1.engelschall.com/u/rse/

Practical Solutions

We also have an URL Rewriting Guide available, which provides a collection of practical solutions for URL-based problems. There you can find real-life rulesets and additional information about mod_rewrite.

RewriteBase Directive

Description: | Sets the base URL for per-directory rewrites
Syntax: | RewriteBase URL-path
Default: | See usage for information.
Context: | directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteBase directive explicitly sets the base URL for per-directory rewrites. As you will see below, RewriteRule can be used in per-directory config files (.htaccess). There it will act locally, i.e., the local directory prefix is stripped at this stage of processing and your rewriting rules act only on the remainder. At the end it is automatically added back to the path. The default setting is; RewriteBase physical-directory-path

When a substitution occurs for a new URL, this module has to re-inject the URL into the server processing. To be able to do this it needs to know what the corresponding URL-prefix or URL-base is. By default this prefix is the corresponding filepath itself. But at most websites URLs are NOT directly related to physical filename paths, so this assumption will usually be wrong! There you have to use the RewriteBase directive to specify the correct URL-prefix.

If your webserver's URLs are not directly related to physical file paths, you have to use RewriteBase in every .htaccess files where you want to use RewriteRule directives.

For example, assume the following per-directory config file:

#
#  /abc/def/.htaccess -- per-dir config file for directory /abc/def
#  Remember: /abc/def is the physical path of /xyz, i.e., the server
#            has a 'Alias /xyz /abc/def' directive e.g.
#

RewriteEngine On

#  let the server know that we were reached via /xyz and not
#  via the physical path prefix /abc/def
RewriteBase   /xyz

#  now the rewriting rules
RewriteRule   ^oldstuff\.html$  newstuff.html

In the above example, a request to /xyz/oldstuff.html gets correctly rewritten to the physical file /abc/def/newstuff.html.

For Apache Hackers

The following list gives detailed information about the internal processing steps:

Request:
  /xyz/oldstuff.html

Internal Processing:
  /xyz/oldstuff.html     -> /abc/def/oldstuff.html  (per-server Alias)
  /abc/def/oldstuff.html -> /abc/def/newstuff.html  (per-dir    RewriteRule)
  /abc/def/newstuff.html -> /xyz/newstuff.html      (per-dir    RewriteBase)
  /xyz/newstuff.html     -> /abc/def/newstuff.html  (per-server Alias)

Result:
  /abc/def/newstuff.html

This seems very complicated but is the correct Apache internal processing, because the per-directory rewriting comes too late in the process. So, when it occurs the (rewritten) request has to be re-injected into the Apache kernel! BUT: While this seems like a serious overhead, it really isn't, because this re-injection happens fully internally to the Apache server and the same procedure is used by many other operations inside Apache. So, you can be sure the design and implementation is correct.

RewriteCond Directive

Description: | Defines a condition under which rewriting will take place
Syntax: | RewriteCond TestString CondPattern
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteCond directive defines a rule condition. Precede a RewriteRule directive with one or more RewriteCond directives. The following rewriting rule is only used if its pattern matches the current state of the URI and if these additional conditions apply too.

TestString is a string which can contains the following expanded constructs in addition to plain text:

  • RewriteRule backreferences: These are backreferences of the form

    $N

    (0 <= N <= 9) which provide access to the grouped parts (parenthesis!) of the pattern from the corresponding RewriteRule directive (the one following the current bunch of RewriteCond directives).
  • RewriteCond backreferences: These are backreferences of the form

    %N

    (1 <= N <= 9) which provide access to the grouped parts (parentheses!) of the pattern from the last matched RewriteCond directive in the current bunch of conditions.
  • RewriteMap expansions: These are expansions of the form

    ${mapname:key|default}

    See the documentation for RewriteMap for more details.
  • Server-Variables: These are variables of the form

    %{ NAME_OF_VARIABLE }

    where NAME_OF_VARIABLE can be a string taken from the following list:
    HTTP headers: connection & request:
    HTTP_USER_AGENT
    HTTP_REFERER
    HTTP_COOKIE
    HTTP_FORWARDED
    HTTP_HOST
    HTTP_PROXY_CONNECTION
    HTTP_ACCEPT
             REMOTE_ADDR
    REMOTE_HOST
    REMOTE_USER
    REMOTE_IDENT
    REQUEST_METHOD
    SCRIPT_FILENAME
    PATH_INFO
    QUERY_STRING
    AUTH_TYPE
    server internals: system stuff: specials:
    DOCUMENT_ROOT
    SERVER_ADMIN
    SERVER_NAME
    SERVER_ADDR
    SERVER_PORT
    SERVER_PROTOCOL
    SERVER_SOFTWARE
             TIME_YEAR
    TIME_MON
    TIME_DAY
    TIME_HOUR
    TIME_MIN
    TIME_SEC
    TIME_WDAY
    TIME
             API_VERSION
    THE_REQUEST
    REQUEST_URI
    REQUEST_FILENAME
    IS_SUBREQ
    HTTPS

    These variables all correspond to the similarly named HTTP MIME-headers, C variables of the Apache server or struct tm fields of the Unix system. Most are documented elsewhere in the Manual or in the CGI specification. Those that are special to mod_rewrite include:

    IS_SUBREQ
    Will contain the text "true" if the request currently being processed is a sub-request, "false" otherwise. Sub-requests may be generated by modules that need to resolve additional files or URIs in order to complete their tasks.
    API_VERSION
    This is the version of the Apache module API (the internal interface between server and module) in the current httpd build, as defined in include/ap_mmn.h. The module API version corresponds to the version of Apache in use (in the release version of Apache 1.3.14, for instance, it is 19990320:10), but is mainly of interest to module authors.
    THE_REQUEST
    The full HTTP request line sent by the browser to the server (e.g., "GET /index.html HTTP/1.1"). This does not include any additional headers sent by the browser.
    REQUEST_URI
    The resource requested in the HTTP request line. (In the example above, this would be "/index.html".)
    REQUEST_FILENAME
    The full local filesystem path to the file or script matching the request.
    HTTPS
    Will contain the text "on" if the connection is using SSL/TLS, or "off" otherwise. (This variable can be safely used regardless of whether mod_ssl is loaded).

Special Notes:

  1. The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same value, i.e., the value of the filename field of the internal request_rec structure of the Apache server. The first name is just the commonly known CGI variable name while the second is the consistent counterpart to REQUEST_URI (which contains the value of the uri field of request_rec).
  2. There is the special format: %{ENV:variable} where variable can be any environment variable. This is looked-up via internal Apache structures and (if not found there) via getenv() from the Apache server process.
  3. There is the special format: %{SSL:variable} where variable is the name of an SSL environment variable; this can be used whether or not mod_ssl is loaded, but will always expand to the empty string if it is not. Example: %{SSL:SSL_CIPHER_USEKEYSIZE} may expand to 128.
  4. There is the special format: %{HTTP:header} where header can be any HTTP MIME-header name. This is looked-up from the HTTP request. Example: %{HTTP:Proxy-Connection} is the value of the HTTP header ``Proxy-Connection:''.
  5. There is the special format %{LA-U:variable} for look-aheads which perform an internal (URL-based) sub-request to determine the final value of variable. Use this when you want to use a variable for rewriting which is actually set later in an API phase and thus is not available at the current stage. For instance when you want to rewrite according to the REMOTE_USER variable from within the per-server context (httpd.conf file) you have to use %{LA-U:REMOTE_USER} because this variable is set by the authorization phases which come after the URL translation phase where mod_rewrite operates. On the other hand, because mod_rewrite implements its per-directory context (.htaccess file) via the Fixup phase of the API and because the authorization phases come before this phase, you just can use %{REMOTE_USER} there.
  6. There is the special format: %{LA-F:variable} which performs an internal (filename-based) sub-request to determine the final value of variable. Most of the time this is the same as LA-U above.

CondPattern is the condition pattern, i.e., a regular expression which is applied to the current instance of the TestString, i.e., TestString is evaluated and then matched against CondPattern.

Remember: CondPattern is a perl compatible regular expression with some additions:

  1. You can prefix the pattern string with a '!' character (exclamation mark) to specify a non-matching pattern.
  2. There are some special variants of CondPatterns. Instead of real regular expression strings you can also use one of the following:
    • '<CondPattern' (is lexically lower)
      Treats the CondPattern as a plain string and compares it lexically to TestString. True if TestString is lexically lower than CondPattern.
    • '>CondPattern' (is lexically greater)
      Treats the CondPattern as a plain string and compares it lexically to TestString. True if TestString is lexically greater than CondPattern.
    • '=CondPattern' (is lexically equal)
      Treats the CondPattern as a plain string and compares it lexically to TestString. True if TestString is lexically equal to CondPattern, i.e the two strings are exactly equal (character by character). If CondPattern is just "" (two quotation marks) this compares TestString to the empty string.
    • '-d' (is directory)
      Treats the TestString as a pathname and tests if it exists and is a directory.
    • '-f' (is regular file)
      Treats the TestString as a pathname and tests if it exists and is a regular file.
    • '-s' (is regular file with size)
      Treats the TestString as a pathname and tests if it exists and is a regular file with size greater than zero.
    • '-l' (is symbolic link)
      Treats the TestString as a pathname and tests if it exists and is a symbolic link.
    • '-F' (is existing file via subrequest)
      Checks if TestString is a valid file and accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to determine the check, so use it with care because it decreases your servers performance!
    • '-U' (is existing URL via subrequest)
      Checks if TestString is a valid URL and accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to determine the check, so use it with care because it decreases your server's performance!

    Notice

    All of these tests can also be prefixed by an exclamation mark ('!') to negate their meaning.

Additionally you can set special flags for CondPattern by appending

[flags]

as the third argument to the RewriteCond directive. Flags is a comma-separated list of the following flags:

  • 'nocase|NC' (no case)
    This makes the test case-insensitive, i.e., there is no difference between 'A-Z' and 'a-z' both in the expanded TestString and the CondPattern. This flag is effective only for comparisons between TestString and CondPattern. It has no effect on filesystem and subrequest checks.
  • 'ornext|OR' (or next condition)
    Use this to combine rule conditions with a local OR instead of the implicit AND. Typical example:
    RewriteCond %{REMOTE_HOST}  ^host1.*  [OR]
RewriteCond %{REMOTE_HOST}  ^host2.*  [OR]
RewriteCond %{REMOTE_HOST}  ^host3.*
RewriteRule ...some special stuff for any of these hosts...
    Without this flag you would have to write the cond/rule three times.

Example:

To rewrite the Homepage of a site according to the ``User-Agent:'' header of the request, you can use the following:

RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
RewriteRule  ^/$                 /homepage.max.html  [L]

RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
RewriteRule  ^/$                 /homepage.min.html  [L]

RewriteRule  ^/$                 /homepage.std.html  [L]

Interpretation: If you use Netscape Navigator as your browser (which identifies itself as 'Mozilla'), then you get the max homepage, which includes Frames, etc. If you use the Lynx browser (which is Terminal-based), then you get the min homepage, which contains no images, no tables, etc. If you use any other browser you get the standard homepage.

RewriteEngine Directive

Description: | Enables or disables runtime rewriting engine
Syntax: | RewriteEngine on|off
Default: | RewriteEngine off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteEngine directive enables or disables the runtime rewriting engine. If it is set to off this module does no runtime processing at all. It does not even update the SCRIPT_URx environment variables.

Use this directive to disable the module instead of commenting out all the RewriteRule directives!

Note that, by default, rewrite configurations are not inherited. This means that you need to have a RewriteEngine on directive for each virtual host in which you wish to use it.

RewriteLock Directive

Description: | Sets the name of the lock file used for RewriteMap synchronization
Syntax: | RewriteLock file-path
Context: | server config
Status: | Extension
Module: | mod_rewrite

This directive sets the filename for a synchronization lockfile which mod_rewrite needs to communicate with RewriteMap programs. Set this lockfile to a local path (not on a NFS-mounted device) when you want to use a rewriting map-program. It is not required for other types of rewriting maps.

RewriteLog Directive

Description: | Sets the name of the file used for logging rewrite engine processing
Syntax: | RewriteLog file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_rewrite

The RewriteLog directive sets the name of the file to which the server logs any rewriting actions it performs. If the name does not begin with a slash ('/') then it is assumed to be relative to the Server Root. The directive should occur only once per server config.

To disable the logging of rewriting actions it is not recommended to set Filename to /dev/null, because although the rewriting engine does not then output to a logfile it still creates the logfile output internally. This will slow down the server with no advantage to the administrator! To disable logging either remove or comment out the RewriteLog directive or use RewriteLogLevel 0!

Security

See the Apache Security Tips document for details on why your security could be compromised if the directory where logfiles are stored is writable by anyone other than the user that starts the server.

Example

RewriteLog "/usr/local/var/apache/logs/rewrite.log"

RewriteLogLevel Directive

Description: | Sets the verbosity of the log file used by the rewrite engine
Syntax: | RewriteLogLevel Level
Default: | RewriteLogLevel 0
Context: | server config, virtual host
Status: | Extension
Module: | mod_rewrite

The RewriteLogLevel directive sets the verbosity level of the rewriting logfile. The default level 0 means no logging, while 9 or more means that practically all actions are logged.

To disable the logging of rewriting actions simply set Level to 0. This disables all rewrite action logs.

Using a high value for Level will slow down your Apache server dramatically! Use the rewriting logfile at a Level greater than 2 only for debugging!

Example

RewriteLogLevel 3

RewriteMap Directive

Description: | Defines a mapping function for key-lookup
Syntax: | RewriteMap MapName MapType:MapSource
Context: | server config, virtual host
Status: | Extension
Module: | mod_rewrite
Compatibility: | The choice of different dbm types is available in Apache 2.0.41 and later

The RewriteMap directive defines a Rewriting Map which can be used inside rule substitution strings by the mapping-functions to insert/substitute fields through a key lookup. The source of this lookup can be of various types.

The MapName is the name of the map and will be used to specify a mapping-function for the substitution strings of a rewriting rule via one of the following constructs:

${ MapName : LookupKey }
${ MapName : LookupKey | DefaultValue }

When such a construct occurs the map MapName is consulted and the key LookupKey is looked-up. If the key is found, the map-function construct is substituted by SubstValue. If the key is not found then it is substituted by DefaultValue or by the empty string if no DefaultValue was specified.

The following combinations for MapType and MapSource can be used:

  • Standard Plain Text
    MapType: txt, MapSource: Unix filesystem path to valid regular file

    This is the standard rewriting map feature where the MapSource is a plain ASCII file containing either blank lines, comment lines (starting with a '#' character) or pairs like the following - one per line.

    MatchingKey SubstValue

    Example

    ##
##  map.txt -- rewriting map
##

Ralf.S.Engelschall    rse   # Bastard Operator From Hell
Mr.Joe.Average        joe   # Mr. Average

    RewriteMap real-to-user txt:/path/to/file/map.txt

  • Randomized Plain Text
    MapType: rnd, MapSource: Unix filesystem path to valid regular file

    This is identical to the Standard Plain Text variant above but with a special post-processing feature: After looking up a value it is parsed according to contained ``|'' characters which have the meaning of ``or''. In other words they indicate a set of alternatives from which the actual returned value is chosen randomly. Although this sounds crazy and useless, it was actually designed for load balancing in a reverse proxy situation where the looked up values are server names. Example:

    ##
##  map.txt -- rewriting map
##

static   www1|www2|www3|www4
dynamic  www5|www6

    RewriteMap servers rnd:/path/to/file/map.txt

  • Hash File
    MapType: dbm[=type], MapSource: Unix filesystem path to valid regular file

    Here the source is a binary format DBM file containing the same contents as a Plain Text format file, but in a special representation which is optimized for really fast lookups. The type can be sdbm, gdbm, ndbm, or db depending on compile-time settings. If the type is ommitted, the compile-time default will be chosen. You can create such a file with any DBM tool or with the following Perl script. Be sure to adjust it to create the appropriate type of DBM. The example creates an NDBM file.

    #!/path/to/bin/perl
##
##  txt2dbm -- convert txt map to dbm format
##

use NDBM_File;
use Fcntl;

($txtmap, $dbmmap) = @ARGV;

open(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n";
tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644)
  or die "Couldn't create $dbmmap!\n";

while (<TXT>) {
  next if (/^\s*#/ or /^\s*$/);
  $DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/);
}

untie %DB;
close(TXT);

    $ txt2dbm map.txt map.db

  • Internal Function
    MapType: int, MapSource: Internal Apache function

    Here the source is an internal Apache function. Currently you cannot create your own, but the following functions already exists:

    • toupper:
      Converts the looked up key to all upper case.
    • tolower:
      Converts the looked up key to all lower case.
    • escape:
      Translates special characters in the looked up key to hex-encodings.
    • unescape:
      Translates hex-encodings in the looked up key back to special characters.
  • External Rewriting Program
    MapType: prg, MapSource: Unix filesystem path to valid regular file

    Here the source is a program, not a map file. To create it you can use the language of your choice, but the result has to be a executable (i.e., either object-code or a script with the magic cookie trick '#!/path/to/interpreter' as the first line).

    This program is started once at startup of the Apache servers and then communicates with the rewriting engine over its stdin and stdout file-handles. For each map-function lookup it will receive the key to lookup as a newline-terminated string on stdin. It then has to give back the looked-up value as a newline-terminated string on stdout or the four-character string ``NULL'' if it fails (i.e., there is no corresponding value for the given key). A trivial program which will implement a 1:1 map (i.e., key == value) could be:

    #!/usr/bin/perl
$| = 1;
while (<STDIN>) {
    # ...put here any transformations or lookups...
    print $_;
}

    But be very careful:

    1. ``Keep it simple, stupid'' (KISS), because if this program hangs it will hang the Apache server when the rule occurs.
    2. Avoid one common mistake: never do buffered I/O on stdout! This will cause a deadloop! Hence the ``$|=1'' in the above example...
    3. Use the RewriteLock directive to define a lockfile mod_rewrite can use to synchronize the communication to the program. By default no such synchronization takes place.

The RewriteMap directive can occur more than once. For each mapping-function use one RewriteMap directive to declare its rewriting mapfile. While you cannot declare a map in per-directory context it is of course possible to use this map in per-directory context.

Note

For plain text and DBM format files the looked-up keys are cached in-core until the mtime of the mapfile changes or the server does a restart. This way you can have map-functions in rules which are used for every request. This is no problem, because the external lookup only happens once!

RewriteOptions Directive

Description: | Sets some special options for the rewrite engine
Syntax: | RewriteOptions Options
Default: | RewriteOptions MaxRedirects=10
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite
Compatibility: | MaxRedirects is available in Apache 2.0.45 and later

The RewriteOptions directive sets some special options for the current per-server or per-directory configuration. The Option strings can be one of the following:

inherit
This forces the current configuration to inherit the configuration of the parent. In per-virtual-server context this means that the maps, conditions and rules of the main server are inherited. In per-directory context this means that conditions and rules of the parent directory's .htaccess configuration are inherited.
MaxRedirects=number
In order to prevent endless loops of internal redirects issued by per-directory RewriteRules, mod_rewrite aborts the request after reaching a maximum number of such redirects and responds with an 500 Internal Server Error. If you really need more internal redirects than 10 per request, you may increase the default to the desired value.

RewriteRule Directive

Description: | Defines rules for the rewriting engine
Syntax: | RewriteRule Pattern Substitution
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite
Compatibility: | The cookie-flag is available in Apache 2.0.40 and later.

The RewriteRule directive is the real rewriting workhorse. The directive can occur more than once. Each directive then defines one single rewriting rule. The definition order of these rules is important, because this order is used when applying the rules at run-time.

Pattern is a perl compatible regular expression which gets applied to the current URL. Here ``current'' means the value of the URL when this rule gets applied. This may not be the originally requested URL, because any number of rules may already have matched and made alterations to it.

Some hints about the syntax of regular expressions:

Text:
  .           Any single character
  [chars]     Character class: One  of chars
  [^chars]    Character class: None of chars
  text1|text2 Alternative: text1 or text2

Quantifiers:
  ?           0 or 1 of the preceding text
  *           0 or N of the preceding text (N > 0)
  +           1 or N of the preceding text (N > 1)

Grouping:
  (text)      Grouping of text
              (either to set the borders of an alternative or
              for making backreferences where the Nth group can
              be used on the RHS of a RewriteRule with $N)

Anchors:
  ^           Start of line anchor
  $           End   of line anchor

Escaping:
  \char       escape that particular char
              (for instance to specify the chars ".[]()" etc.)

For more information about regular expressions have a look at the perl regular expression manpage ("perldoc perlre"). If you are interested in more detailed information about regular expressions and their variants (POSIX regex etc.) have a look at the following dedicated book on this topic:

Mastering Regular Expressions
Jeffrey E.F. Friedl
Nutshell Handbook Series
O'Reilly & Associates, Inc. 1997
ISBN 1-56592-257-3

Additionally in mod_rewrite the NOT character ('!') is a possible pattern prefix. This gives you the ability to negate a pattern; to say, for instance: ``if the current URL does NOT match this pattern''. This can be used for exceptional cases, where it is easier to match the negative pattern, or as a last default rule.

Notice

When using the NOT character to negate a pattern you cannot have grouped wildcard parts in the pattern. This is impossible because when the pattern does NOT match, there are no contents for the groups. In consequence, if negated patterns are used, you cannot use $N in the substitution string!

Substitution of a rewriting rule is the string which is substituted for (or replaces) the original URL for which Pattern matched. Beside plain text you can use

  1. back-references $N to the RewriteRule pattern
  2. back-references %N to the last matched RewriteCond pattern
  3. server-variables as in rule condition test-strings (%{VARNAME})
  4. mapping-function calls (${mapname:key|default})

Back-references are $N (N=0..9) identifiers which will be replaced by the contents of the Nth group of the matched Pattern. The server-variables are the same as for the TestString of a RewriteCond directive. The mapping-functions come from the RewriteMap directive and are explained there. These three types of variables are expanded in the order of the above list.

As already mentioned above, all the rewriting rules are applied to the Substitution (in the order of definition in the config file). The URL is completely replaced by the Substitution and the rewriting process goes on until there are no more rules unless explicitly terminated by a L flag - see below.

There is a special substitution string named '-' which means: NO substitution! Sounds silly? No, it is useful to provide rewriting rules which only match some URLs but do no substitution, e.g., in conjunction with the C (chain) flag to be able to have more than one pattern to be applied before a substitution occurs.

Query String

The Pattern will not match against the query string. Instead, you must use a RewriteCond with the %{QUERY_STRING} variable. You can, however, create URLs in the substitution string containing a query string part. Just use a question mark inside the substitution string to indicate that the following stuff should be re-injected into the query string. When you want to erase an existing query string, end the substitution string with just the question mark. To combine a new query string with an old one, use the [QSA] flag (see below).

Substitution of Absolute URLs

There is a special feature: When you prefix a substitution field with http://thishost[:thisport] then mod_rewrite automatically strips it out. This auto-reduction on implicit external redirect URLs is a useful and important feature when used in combination with a mapping-function which generates the hostname part. Have a look at the first example in the example section below to understand this.

Remember: An unconditional external redirect to your own server will not work with the prefix http://thishost because of this feature. To achieve such a self-redirect, you have to use the R-flag (see below).

Additionally you can set special flags for Substitution by appending

[flags]

as the third argument to the RewriteRule directive. Flags is a comma-separated list of the following flags:

  • 'redirect|R [=code]' (force redirect)
    Prefix Substitution with http://thishost[:thisport]/ (which makes the new URL a URI) to force a external redirection. If no code is given a HTTP response of 302 (MOVED TEMPORARILY) is used. If you want to use other response codes in the range 300-400 just specify them as a number or use one of the following symbolic names: temp (default), permanent, seeother. Use it for rules which should canonicalize the URL and give it back to the client, e.g., translate ``/~'' into ``/u/'' or always append a slash to /u/user, etc.

    Note: When you use this flag, make sure that the substitution field is a valid URL! If not, you are redirecting to an invalid location! And remember that this flag itself only prefixes the URL with http://thishost[:thisport]/, rewriting continues. Usually you also want to stop and do the redirection immediately. To stop the rewriting you also have to provide the 'L' flag.

  • 'forbidden|F' (force URL to be forbidden)
    This forces the current URL to be forbidden, i.e., it immediately sends back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with appropriate RewriteConds to conditionally block some URLs.
  • 'gone|G' (force URL to be gone)
    This forces the current URL to be gone, i.e., it immediately sends back a HTTP response of 410 (GONE). Use this flag to mark pages which no longer exist as gone.
  • 'proxy|P' (force proxy)
    This flag forces the substitution part to be internally forced as a proxy request and immediately (i.e., rewriting rule processing stops here) put through the proxy module. You have to make sure that the substitution string is a valid URI (e.g., typically starting with http://hostname) which can be handled by the Apache proxy module. If not you get an error from the proxy module. Use this flag to achieve a more powerful implementation of the ProxyPass directive, to map some remote stuff into the namespace of the local server.

    Notice: To use this functionality make sure you have the proxy module compiled into your Apache server program. If you don't know please check whether mod_proxy.c is part of the ``httpd -l'' output. If yes, this functionality is available to mod_rewrite. If not, then you first have to rebuild the ``httpd'' program with mod_proxy enabled.

  • 'last|L' (last rule)
    Stop the rewriting process here and don't apply any more rewriting rules. This corresponds to the Perl last command or the break command from the C language. Use this flag to prevent the currently rewritten URL from being rewritten further by following rules. For example, use it to rewrite the root-path URL ('/') to a real one, e.g., '/e/www/'.
  • 'next|N' (next round)
    Re-run the rewriting process (starting again with the first rewriting rule). Here the URL to match is again not the original URL but the URL from the last rewriting rule. This corresponds to the Perl next command or the continue command from the C language. Use this flag to restart the rewriting process, i.e., to immediately go to the top of the loop.
    But be careful not to create an infinite loop!
  • 'chain|C' (chained with next rule)
    This flag chains the current rule with the next rule (which itself can be chained with the following rule, etc.). This has the following effect: if a rule matches, then processing continues as usual, i.e., the flag has no effect. If the rule does not match, then all following chained rules are skipped. For instance, use it to remove the ``.www'' part inside a per-directory rule set when you let an external redirect happen (where the ``.www'' part should not to occur!).
  • 'type|T=MIME-type' (force MIME type)
    Force the MIME-type of the target file to be MIME-type. For instance, this can be used to simulate the mod_alias directive ScriptAlias which internally forces all files inside the mapped directory to have a MIME type of ``application/x-httpd-cgi''.
  • 'nosubreq|NS' (used only if no internal sub-request)
    This flag forces the rewriting engine to skip a rewriting rule if the current request is an internal sub-request. For instance, sub-requests occur internally in Apache when mod_include tries to find out information about possible directory default files (index.xxx). On sub-requests it is not always useful and even sometimes causes a failure to if the complete set of rules are applied. Use this flag to exclude some rules.

    Use the following rule for your decision: whenever you prefix some URLs with CGI-scripts to force them to be processed by the CGI-script, the chance is high that you will run into problems (or even overhead) on sub-requests. In these cases, use this flag.

  • 'nocase|NC' (no case)
    This makes the Pattern case-insensitive, i.e., there is no difference between 'A-Z' and 'a-z' when Pattern is matched against the current URL.
  • 'qsappend|QSA' (query string append)
    This flag forces the rewriting engine to append a query string part in the substitution string to the existing one instead of replacing it. Use this when you want to add more data to the query string via a rewrite rule.
  • 'noescape|NE' (no URI escaping of output)
    This flag keeps mod_rewrite from applying the usual URI escaping rules to the result of a rewrite. Ordinarily, special characters (such as '%', '$', ';', and so on) will be escaped into their hexcode equivalents ('%25', '%24', and '%3B', respectively); this flag prevents this from being done. This allows percent symbols to appear in the output, as in

    RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]

    which would turn '/foo/zed' into a safe request for '/bar?arg=P1=zed'.
  • 'passthrough|PT' (pass through to next handler)
    This flag forces the rewriting engine to set the uri field of the internal request_rec structure to the value of the filename field. This flag is just a hack to be able to post-process the output of RewriteRule directives by Alias, ScriptAlias, Redirect, etc. directives from other URI-to-filename translators. A trivial example to show the semantics: If you want to rewrite /abc to /def via the rewriting engine of mod_rewrite and then /def to /ghi with mod_alias:

    RewriteRule ^/abc(.*) /def$1 [PT]
    Alias /def /ghi

    If you omit the PT flag then mod_rewrite will do its job fine, i.e., it rewrites uri=/abc/... to filename=/def/... as a full API-compliant URI-to-filename translator should do. Then mod_alias comes and tries to do a URI-to-filename transition which will not work.

    Note: You have to use this flag if you want to intermix directives of different modules which contain URL-to-filename translators. The typical example is the use of mod_alias and mod_rewrite..

  • 'skip|S=num' (skip next rule(s))
    This flag forces the rewriting engine to skip the next num rules in sequence when the current rule matches. Use this to make pseudo if-then-else constructs: The last rule of the then-clause becomes skip=N where N is the number of rules in the else-clause. (This is not the same as the 'chain|C' flag!)
  • 'env|E=VAR:VAL' (set environment variable)
    This forces an environment variable named VAR to be set to the value VAL, where VAL can contain regexp backreferences $N and %N which will be expanded. You can use this flag more than once to set more than one variable. The variables can be later dereferenced in many situations, but usually from within XSSI (via <!--#echo var="VAR"-->) or CGI (e.g. $ENV{'VAR'}). Additionally you can dereference it in a following RewriteCond pattern via %{ENV:VAR}. Use this to strip but remember information from URLs.
  • 'cookie|CO=NAME:VAL:domain[:lifetime[:path]]' (set cookie)
    This sets a cookie on the client's browser. The cookie's name is specified by NAME and the value is VAL. The domain field is the domain of the cookie, such as '.apache.org',the optional lifetime is the lifetime of the cookie in minutes, and the optional path is the path of the cookie

Note

Never forget that Pattern is applied to a complete URL in per-server configuration files. But in per-directory configuration files, the per-directory prefix (which always is the same for a specific directory!) is automatically removed for the pattern matching and automatically added after the substitution has been done. This feature is essential for many sorts of rewriting, because without this prefix stripping you have to match the parent directory which is not always possible.

There is one exception: If a substitution string starts with ``http://'' then the directory prefix will not be added and an external redirect or proxy throughput (if flag P is used!) is forced!

Note

To enable the rewriting engine for per-directory configuration files you need to set ``RewriteEngine On'' in these files and ``Options FollowSymLinks'' must be enabled. If your administrator has disabled override of FollowSymLinks for a user's directory, then you cannot use the rewriting engine. This restriction is needed for security reasons.

Here are all possible substitution combinations and their meanings:

Inside per-server configuration (httpd.conf)
for request ``GET /somepath/pathinfo'':

Given Rule                                      Resulting Substitution
----------------------------------------------  ----------------------------------
^/somepath(.*) otherpath$1                      not supported, because invalid!

^/somepath(.*) otherpath$1  [R]                 not supported, because invalid!

^/somepath(.*) otherpath$1  [P]                 not supported, because invalid!
----------------------------------------------  ----------------------------------
^/somepath(.*) /otherpath$1                     /otherpath/pathinfo

^/somepath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
                                                via external redirection

^/somepath(.*) /otherpath$1 [P]                 not supported, because silly!
----------------------------------------------  ----------------------------------
^/somepath(.*) http://thishost/otherpath$1      /otherpath/pathinfo

^/somepath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
                                                via external redirection

^/somepath(.*) http://thishost/otherpath$1 [P]  not supported, because silly!
----------------------------------------------  ----------------------------------
^/somepath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
                                                via external redirection

^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
                                                via external redirection
                                                (the [R] flag is redundant)

^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
                                                via internal proxy

Inside per-directory configuration for /somepath
(i.e., file .htaccess in dir /physical/path/to/somepath containing RewriteBase /somepath)
for request ``GET /somepath/localpath/pathinfo'':

Given Rule                                      Resulting Substitution
----------------------------------------------  ----------------------------------
^localpath(.*) otherpath$1                      /somepath/otherpath/pathinfo

^localpath(.*) otherpath$1  [R]                 http://thishost/somepath/otherpath/pathinfo
                                                via external redirection

^localpath(.*) otherpath$1  [P]                 not supported, because silly!
----------------------------------------------  ----------------------------------
^localpath(.*) /otherpath$1                     /otherpath/pathinfo

^localpath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
                                                via external redirection

^localpath(.*) /otherpath$1 [P]                 not supported, because silly!
----------------------------------------------  ----------------------------------
^localpath(.*) http://thishost/otherpath$1      /otherpath/pathinfo

^localpath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
                                                via external redirection

^localpath(.*) http://thishost/otherpath$1 [P]  not supported, because silly!
----------------------------------------------  ----------------------------------
^localpath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
                                                via external redirection

^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
                                                via external redirection
                                                (the [R] flag is redundant)

^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
                                                via internal proxy

Example:

We want to rewrite URLs of the form

/ Language /~ Realname /.../ File

into

/u/ Username /.../ File . Language

We take the rewrite mapfile from above and save it under /path/to/file/map.txt. Then we only have to add the following lines to the Apache server configuration file:

RewriteLog   /path/to/file/rewrite.log
RewriteMap   real-to-user               txt:/path/to/file/map.txt
RewriteRule  ^/([^/]+)/~([^/]+)/(.*)$   /u/${real-to-user:$2|nobody}/$3.$1


mod_setenvif - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_setenvif

説明: | リクエストの特徴に基づいた環境変数の設定を可能にする
ステータス: | Base
モジュール識別子: | setenvif_module
ソースファイル: | mod_setenvif.c

概要

mod_setenvif モジュールは、リクエストのある側面が指定された正規表現 に合うかどうかによって環境変数を設定する機能を提供します。 これらの環境変数を使用して、サーバの他の部分がどのような動作をするかを 決定することができます。

このモジュールが提供するディレクティブは、 設定ファイルに現れる順番に適用されます。 それを使って、次の例のようにより複雑な設定をすることができます。 これは、ブラウザが mozilla ではあるけれど、MSIE ではないときに netscape を設定します。

BrowserMatch ^Mozilla netscape
BrowserMatch MSIE !netscape

参照

  • Apache の環境変数

BrowserMatch ディレクティブ

説明: | HTTP User-Agent に基づいて環境変数を設定する
構文: | BrowserMatch regex [!]env-variable[=value] [[!]env-variable[=value]] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_setenvif

BrowserMatch は SetEnvIf ディレクティブの 特例で、User-Agent HTTP リクエストヘッダに基づいて 環境変数を設定します。以下の 2 行の効果は同じになります:

BrowserMatchNoCase Robot is_a_robot
SetEnvIfNoCase User-Agent Robot is_a_robot

その他の例:

BrowserMatch ^Mozilla forms jpeg=yes browser=netscape
BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
BrowserMatch MSIE !javascript

BrowserMatchNoCase ディレクティブ

説明: | HTTP User-Agent に基づいて大文字小文字を区別せずに 環境変数を設定する
構文: | BrowserMatchNoCase regex [!]env-variable[=value] [[!]env-variable[=value]] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_setenvif
互換性: | Apache 1.2 以降 (Apache 1.2 ではこのディレクティブはもう用いられていない mod_browser モジュールにありました)

BrowserMatchNoCase ディレクティブは 意味的には BrowserMatch ディレクティブと 同じです。ただし、このディレクティブは大文字小文字を区別しない マッチングを行ないます。例えば:

BrowserMatchNoCase mac platform=macintosh
BrowserMatchNoCase win platform=windows

BrowserMatch ディレクティブと BrowserMatchNoCase ディレクティブは SetEnvIf ディレクティブと SetEnvIfNoCase ディレクティブの 特例です。以下の 2 行の効果は同じです:

BrowserMatchNoCase Robot is_a_robot
SetEnvIfNoCase User-Agent Robot is_a_robot

SetEnvIf ディレクティブ

説明: | リクエストの属性に基づいて環境変数を設定する
構文: | SetEnvIf attribute regex [!]env-variable[=value] [[!]env-variable[=value]] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_setenvif

SetEnvIf ディレクティブは、リクエストの属性に基づいて環境変数を定義します。 最初の引数で指定できる attribute は以下の三つのどれかです:

  1. HTTP リクエストヘッダフィールド (詳しい情報は RFC 2616 を 参照してください)。例えば、Host, User-Agent, Referer, Accept-Language です。リクエストヘッダの集合を現すために 正規表現を使うこともできます。
  2. 以下のリクエストの一部分のどれか:
    • Remote_Host - リクエストを行なっているクライアントのホスト名 (もしあれば)
    • Remote_Addr - リクエストを行なっているクライアントの IP アドレス
    • Server_Addr - リクエストを受け取ったサーバの IP アドレス (2.0.43 以降のみ)
    • Request_Method - 使用されているメソッド名 (GET, POST など)
    • Request_Protocol - リクエストが行なわれたプロトコルの名前とバージョン (例えば、"HTTP/0.9", "HTTP/1.1" など。)
    • Request_URI - URL のスキームとホストの後の部分
  3. リクエストと関連付けられる環境変数のリスト。これにより SetEnvIf ディレクティブが以前のマッチの結果を 使うことができるようになります。この方法のテストでは前の部分にある SetEnvIf[NoCase] の結果のみを使用可能です。「前」とは、 より広い範囲に対して定義されている (サーバ全体のように) か、現在のディレクティブの 範囲でより前の部分で定義されているか、ということです。 環境変数である可能性は、リクエストの特性に対するマッチが存在せず、 attribute に正規表現が使われなかったときにのみ考慮されます。

二つ目の引数 (regex) は Perl 互換の正規表現です。 これは POSIX.2 の egrep 形式の正規表現と似ています。regex が attribute にマッチする場合は、残りの引数が評価されます。

残りの引数は設定する変数の名前で、設定される値を指定することもできます。 これは、

  1. varname
  2. !varname
  3. varname=value

のどれかの形式になります。

最初の形式では、値は "1" に設定されます。 二つ目はもし値が定義されていればそれを取り除きます。 三つ目は変数を value の与えられた値に設定します。 2.0.51 以降では、regex 内に $1..$9 が存在すればそれを認識し、regex の対応する丸括弧で囲まれた部分で 置換します。

例:

SetEnvIf Request_URI "\.gif$" object_is_image=gif
SetEnvIf Request_URI "\.jpg$" object_is_image=jpg
SetEnvIf Request_URI "\.xbm$" object_is_image=xbm
:
SetEnvIf Referer www\.mydomain\.com intra_site_referral
:
SetEnvIf object_is_image xbm XBIT_PROCESSING=1
:
SetEnvIf ^TS* ^[a-z].* HAVE_TS

初めの三つはリクエストが画像であるときに環境変数 object_is_image を設定します。四つ目は 参照元のページがウェブサイト www.mydomain.com にあるときに intra_site_referral を設定します。

最後の例は、リクエストに "TS" で始まり、値が集合 [a-z] のどれかで 始まるヘッダがあるときに HAVE_TS を設定します。

参照

  • 他の例は、Apache の環境変数

SetEnvIfNoCase ディレクティブ

説明: | リクエストの属性に基づいて大文字小文字を区別せずに環境変数を設定する
構文: | SetEnvIfNoCase attribute regex [!]env-variable[=value] [[!]env-variable[=value]] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_setenvif
互換性: | Apache 1.3 以降

SetEnvIfNoCase は意味的には SetEnvIf ディレクティブと 同じです。違いは、正規表現のマッチングが大文字小文字を区別しないで 行なわれることです。例えば:

SetEnvIfNoCase Host Apache\.Org site=apache

これは HTTP リクエストヘッダにフィールド Host: が あり、その値が Apache.Org や apache.org、 その他の大文字小文字の組み合わせであったときに site 環境変数を "apache" に設定します。


mod_so - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_so

説明: | 起動時や再起動時に実行コードとモジュールをサーバにロードする
ステータス: | Extension
モジュール識別子: | so_module
ソースファイル: | mod_so.c
互換性: | このモジュールは Window では (常に含まれている) Base モジュールです

概要

いくつかのオペレーティングシステムでは、サーバの再コンパイルをする代わりに、 このモジュールを使用して 動的共有オブジェクト (DSO) 機構により、実行時に Apache にモジュールを読み込ませることが できます。

Unix 上では、読み込まれるコードは通常は共有オブジェクトファイル (普通 .so という拡張子が付いています) からです。 Windows 上ではこのモジュールの拡張子は .so か .dll です。

警告

Apache 1.3 のモジュールを直接 Apache 2.0 で使うことはできません ― モジュールは Apache 2.0 用に動的にロードされるか、 直接組み込まれるために修正されなければなりません。

Windows 用のロード可能なモジュールを作成する

注

Apache 1.3.15 と 2.0 とで Windows のモジュール名の形式は変更されました ― モジュールは mod_foo.so という名前になりました。

まだ mod_so で ApacheModuleFoo.dll という名前のモジュールも ロードされますが、新しい名前の付け方を使う方が好まれます。モジュールを 2.0 用に移植しているのであれば、2.0 の習慣に合うように名前を 修正してください。

Apache のモジュール API は UNIX と Windows 間では変更されていません。 多くのモジュールは全く変更なし、もしくは簡単な変更により Windows で実行できるようになります。ただし、それ以外の Windows には無い Unix アーキテクチャーの機能に依存したモジュールは動作しません。

モジュールが実際に動作するときは、 二つの方法のどちらかでサーバに追加することができます。まず、Unix と同様にサーバにコンパイルして組み込むことができます。Windows 用の Apache は Unix 用の Apache にある Configure プログラムがありませんので、モジュールのソースファイルを ApacheCore プロジェクトファイルに追加し、シンボルを os\win32\modules.c ファイルに追加する必要があります。

二つ目はモジュールを DLL としてコンパイルする方法です。 DLL は共有ライブラリで、実行時に LoadModule ディレクティブによりサーバに読み込むことができます。これらのモジュール DLL はそのまま配布することが可能で、サーバを再コンパイルすることなく、Windows 用の Apache のすべてのインストールで実行することができます。

モジュール DLL を作成するためには、 モジュールの作成に小さな変更を行なう必要があります。 つまり、モジュールのレコード (これは後で作成されます。 以下を参照してください) が DLL からエクスポートされなければなりません。 これを行なうには、AP_MODULE_DECLARE_DATA (Apache のヘッダファイルで定義されています) をモジュールのモジュールレコード 定義の部分に追加してください。たとえば、モジュールに

module foo_module;

があるとすると、それを次のもので置き換えてください。

module AP_MODULE_DECLARE_DATA foo_module;

Unix 上でもこのモジュールを 変更無しで使い続けられるように、このマクロは Windows 上でのみ効力を持ちます。.DEF ファイルの方を良く知っているという場合は、 代わりにそれを使ってモジュールレコードを エクスポートすることもできます。

さあ、あなたのモジュールの DLL を作成しましょう。これを、 libhttpd.lib 共有ライブラリがコンパイルされたときに作成された ibhttpd.lib エクスポートライブラリとリンクしてください。この時に、 Apache のヘッダファイルが正しい位置にあるように、 コンパイラの設定を変える必要があるかもしれません。 このライブラリはサーバルートの modules ディレクトリにあります。 ビルド環境が正しく設定されるように、既存のモジュール用の .dsp を 取ってくるのが一番良いでしょう。もしくは、あなたの .dsp と コンパイラとリンクのオプションを比較する、というものでも良いです。

これで DLL 版のモジュールが作成されているはずです。 サーバルートの modules ディレクトリにモジュールを置いて、 LoadModule ディレクティブを使って読み込んでください。

LoadFile ディレクティブ

説明: | 指定されたオブジェクトファイルやライブラリをリンクする
構文: | LoadFile filename [filename] ...
コンテキスト: | サーバ設定ファイル
ステータス: | Extension
モジュール: | mod_so

LoadFile ディレクティブは、サーバが起動されたときや再起動されたときに、 指定されたオブジェクトファイルやライブラリをリンクします。 これはモジュールが動作するために必要になるかもしれない追加の コードを読み込むために使用されます。Filename は絶対パスか、ServerRoot からの相対パスです。

例:

LoadFile libexec/libxmlparse.so

LoadModule ディレクティブ

説明: | オブジェクトファイルやライブラリをリンクし、使用モジュールの リストに追加する
構文: | LoadModule module filename
コンテキスト: | サーバ設定ファイル
ステータス: | Extension
モジュール: | mod_so

LoadModule ディレクティブは filename というオブジェクトファイルおよびライブラリをリンクし、module という名前のモジュールの構造をアクティブなモジュールのリストに追加します。 Module はファイル中の module 型の外部変数の名前で、モジュールのドキュメントに モジュール識別子として書かれているものです。例 :

LoadModule status_module modules/mod_status.so

これは ServerRoot の modules サブディレクトリから指定された名前の モジュールをロードします。


mod_speling - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_speling

説明: | ユーザが入力したであろう間違った URL を、 大文字小文字の区別を無視することと一つ以下の綴り間違いを許容することで 修正を試みる
ステータス: | Extension
モジュール識別子: | speling_module
ソースファイル: | mod_speling.c

概要

リクエストの綴りが間違っていたり、 大文字小文字が違っていたりするために、Apache のコアサーバが ドキュメントへのリクエストへの応答を正しく提供できないことがあります。 このモジュールは、他のすべてのモジュールがあきらめた後であったとしても、 リクエストに合うドキュメントを見つけようとすることによりこの問題の 解決を試みます。このモジュールはリクエストされたディレクトリにある それぞれのドキュメントの名前と、リクエストされたドキュメントの名前とを 大文字小文字の区別を無視し、一文字までの 綴りの間違い (文字の挿入/省略/隣合う文字の置換、間違った文字) を許可して比較することにより、目的を達成しようとします。 この方法でリクエストに合うドキュメントの一覧が作成されます。

ディレクトリをスキャンした後に、

  • 適切なドキュメントが見つからなかった場合、 Apache はいつもと同じように処理をし、 「ドキュメントが見つからない」というエラーを返します。
  • リクエストに「ほとんど」合うドキュメントが一つだけ見つかった場合、 それがリダイレクト応答として返されます。
  • よく似たドキュメントが複数見つかった場合、 そのリストがクライアントに返され、 クライアントが正しい候補を選択できるようにします。

CheckSpelling ディレクティブ

説明: | spelling モジュールを使用するようにする
構文: | CheckSpelling on|off
デフォルト: | CheckSpelling Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Options
ステータス: | Extension
モジュール: | mod_speling
互換性: | CheckSpelling は Apache 1.1 では別配布のモジュールで、 大文字小文字の間違いのみの機能でした。Apache 1.3 で Apache の配布に 含まれるようになりました。Apache 1.3.2 より前では CheckSpelling ディレクティブは「サーバ」と「バーチャルホスト」コンテキストでのみ 使用可能でした

このディレクティブは綴り用のモジュールを使用するかどうかを 決めます。使用時には、以下のことを覚えておいてください

  • 同時にたくさんの綴りの訂正を行なわなければならないときは、 そのために行なわれるディレクトリのスキャンがサーバの性能に 影響を与えます。
  • ドキュメントの中に綴りの「訂正」により 意図せず合ってしまうような重要なファイルがないようにしてください。
  • モジュールはユーザ名の綴りの間違い (http://my.host/~apahce/ のように) を訂正することはできません。 訂正できるのはファイル名とディレクトリ名だけです。
  • 綴りの訂正は存在するファイルに厳密に適用されますので、 <Location /status> はネゴシエーションの結果のファイル "/stats.html" として間違って扱われるかもしれません。


mod_ssl - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_ssl

Description: | Strong cryptography using the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols
Status: | Extension
Module?dentifier: | ssl_module
Source?ile: | mod_ssl.c

Summary

This module provides SSL v2/v3 and TLS v1 support for the Apache HTTP Server. It was contributed by Ralf S. Engeschall based on his mod_ssl project and originally derived from work by Ben Laurie.

This module relies on OpenSSL to provide the cryptography engine.

Further details, discussion, and examples are provided in the SSL documentation.

Environment Variables

This module provides a lot of SSL information as additional environment variables to the SSI and CGI namespace. The generated variables are listed in the table below. For backward compatibility the information can be made available under different names, too. Look in the Compatibility chapter for details on the compatibility variables.

Variable Name: | Value Type: | Description:
HTTPS | flag | HTTPS is being used.
SSL_PROTOCOL | string | The SSL protocol version (SSLv2, SSLv3, TLSv1)
SSL_SESSION_ID | string | The hex-encoded SSL session id
SSL_CIPHER | string | The cipher specification name
SSL_CIPHER_EXPORT | string | true if cipher is an export cipher
SSL_CIPHER_USEKEYSIZE | number | Number of cipher bits (actually used)
SSL_CIPHER_ALGKEYSIZE | number | Number of cipher bits (possible)
SSL_VERSION_INTERFACE | string | The mod_ssl program version
SSL_VERSION_LIBRARY | string | The OpenSSL program version
SSL_CLIENT_M_VERSION | string | The version of the client certificate
SSL_CLIENT_M_SERIAL | string | The serial of the client certificate
SSL_CLIENT_S_DN | string | Subject DN in client's certificate
SSL_CLIENT_S_DN_x509 | string | Component of client's Subject DN
SSL_CLIENT_I_DN | string | Issuer DN of client's certificate
SSL_CLIENT_I_DN_x509 | string | Component of client's Issuer DN
SSL_CLIENT_V_START | string | Validity of client's certificate (start time)
SSL_CLIENT_V_END | string | Validity of client's certificate (end time)
SSL_CLIENT_A_SIG | string | Algorithm used for the signature of client's certificate
SSL_CLIENT_A_KEY | string | Algorithm used for the public key of client's certificate
SSL_CLIENT_CERT | string | PEM-encoded client certificate
SSL_CLIENT_CERT_CHAIN n | string | PEM-encoded certificates in client certificate chain
SSL_CLIENT_VERIFY | string | NONE, SUCCESS, GENEROUS or FAILED:reason
SSL_SERVER_M_VERSION | string | The version of the server certificate
SSL_SERVER_M_SERIAL | string | The serial of the server certificate
SSL_SERVER_S_DN | string | Subject DN in server's certificate
SSL_SERVER_S_DN_x509 | string | Component of server's Subject DN
SSL_SERVER_I_DN | string | Issuer DN of server's certificate
SSL_SERVER_I_DN_x509 | string | Component of server's Issuer DN
SSL_SERVER_V_START | string | Validity of server's certificate (start time)
SSL_SERVER_V_END | string | Validity of server's certificate (end time)
SSL_SERVER_A_SIG | string | Algorithm used for the signature of server's certificate
SSL_SERVER_A_KEY | string | Algorithm used for the public key of server's certificate
SSL_SERVER_CERT | string | PEM-encoded server certificate

[ where x509 is a component of a X.509 DN: C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email ]

Custom Log Formats

When mod_ssl is built into Apache or at least loaded (under DSO situation) additional functions exist for the Custom Log Format of mod_log_config. First there is an additional ``%{varname}x'' eXtension format function which can be used to expand any variables provided by any module, especially those provided by mod_ssl which can you find in the above table.

For backward compatibility there is additionally a special ``%{name}c'' cryptography format function provided. Information about this function is provided in the Compatibility chapter.

Example:

CustomLog logs/ssl_request_log \ "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

SSLCACertificateFile Directive

Description: | File of concatenated PEM-encoded CA Certificates for Client Auth
Syntax: | SSLCACertificateFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose clients you deal with. These are used for Client Authentication. Such a file is simply the concatenation of the various PEM-encoded Certificate files, in order of preference. This can be used alternatively and/or additionally to SSLCACertificatePath.

Example

SSLCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt

SSLCACertificatePath Directive

Description: | Directory of PEM-encoded CA Certificates for Client Auth
Syntax: | SSLCACertificatePath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the Certificates of Certification Authorities (CAs) whose clients you deal with. These are used to verify the client certificate on Client Authentication.

The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you can't just place the Certificate files there: you also have to create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.

Example

SSLCACertificatePath /usr/local/apache2/conf/ssl.crt/

SSLCARevocationFile Directive

Description: | File of concatenated PEM-encoded CA CRLs for Client Auth
Syntax: | SSLCARevocationFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you can assemble the Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose clients you deal with. These are used for Client Authentication. Such a file is simply the concatenation of the various PEM-encoded CRL files, in order of preference. This can be used alternatively and/or additionally to SSLCARevocationPath.

Example

SSLCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-client.crl

SSLCARevocationPath Directive

Description: | Directory of PEM-encoded CA CRLs for Client Auth
Syntax: | SSLCARevocationPath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the Certificate Revocation Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. These are used to revoke the client certificate on Client Authentication.

The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you have not only to place the CRL files there. Additionally you have to create symbolic links named hash-value.rN. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.

Example

SSLCARevocationPath /usr/local/apache2/conf/ssl.crl/

SSLCertificateChainFile Directive

Description: | File of PEM-encoded Server CA Certificates
Syntax: | SSLCertificateChainFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the optional all-in-one file where you can assemble the certificates of Certification Authorities (CA) which form the certificate chain of the server certificate. This starts with the issuing CA certificate of of the server certificate and can range up to the root CA certificate. Such a file is simply the concatenation of the various PEM-encoded CA Certificate files, usually in certificate chain order.

This should be used alternatively and/or additionally to SSLCACertificatePath for explicitly constructing the server certificate chain which is sent to the browser in addition to the server certificate. It is especially useful to avoid conflicts with CA certificates when using client authentication. Because although placing a CA certificate of the server certificate chain into SSLCACertificatePath has the same effect for the certificate chain construction, it has the side-effect that client certificates issued by this same CA certificate are also accepted on client authentication. That's usually not one expect.

But be careful: Providing the certificate chain works only if you are using a single (either RSA or DSA) based server certificate. If you are using a coupled RSA+DSA certificate pair, this will work only if actually both certificates use the same certificate chain. Else the browsers will be confused in this situation.

Example

SSLCertificateChainFile /usr/local/apache2/conf/ssl.crt/ca.crt

SSLCertificateFile Directive

Description: | Server PEM-encoded X.509 Certificate file
Syntax: | SSLCertificateFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive points to the PEM-encoded Certificate file for the server and optionally also to the corresponding RSA or DSA Private Key file for it (contained in the same file). If the contained Private Key is encrypted the Pass Phrase dialog is forced at startup time. This directive can be used up to two times (referencing different filenames) when both a RSA and a DSA based server certificate is used in parallel.

Example

SSLCertificateFile /usr/local/apache2/conf/ssl.crt/server.crt

SSLCertificateKeyFile Directive

Description: | Server PEM-encoded Private Key file
Syntax: | SSLCertificateKeyFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive points to the PEM-encoded Private Key file for the server. If the Private Key is not combined with the Certificate in the SSLCertificateFile, use this additional directive to point to the file with the stand-alone Private Key. When SSLCertificateFile is used and the file contains both the Certificate and the Private Key this directive need not be used. But we strongly discourage this practice. Instead we recommend you to separate the Certificate and the Private Key. If the contained Private Key is encrypted, the Pass Phrase dialog is forced at startup time. This directive can be used up to two times (referencing different filenames) when both a RSA and a DSA based private key is used in parallel.

Example

SSLCertificateKeyFile /usr/local/apache2/conf/ssl.key/server.key

SSLCipherSuite Directive

Description: | Cipher Suite available for negotiation in SSL handshake
Syntax: | SSLCipherSuite cipher-spec
Default: | SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This complex directive uses a colon-separated cipher-spec string consisting of OpenSSL cipher specifications to configure the Cipher Suite the client is permitted to negotiate in the SSL handshake phase. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotation with the reconfigured Cipher Suite after the HTTP request was read but before the HTTP response is sent.

An SSL cipher specification in cipher-spec is composed of 4 major attributes plus a few extra minor ones:

  • Key Exchange Algorithm:
    RSA or Diffie-Hellman variants.
  • Authentication Algorithm:
    RSA, Diffie-Hellman, DSS or none.
  • Cipher/Encryption Algorithm:
    DES, Triple-DES, RC4, RC2, IDEA or none.
  • MAC Digest Algorithm:
    MD5, SHA or SHA1.

An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1 cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use, one can either specify all the Ciphers, one at a time, or use aliases to specify the preference and order for the ciphers (see Table 1).

Tag | Description
Key Exchange Algorithm:
kRSA | RSA key exchange
kDHr | Diffie-Hellman key exchange with RSA key
kDHd | Diffie-Hellman key exchange with DSA key
kEDH | Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)
Authentication Algorithm:
aNULL | No authentication
aRSA | RSA authentication
aDSS | DSS authentication
aDH | Diffie-Hellman authentication
Cipher Encoding Algorithm:
eNULL | No encoding
DES | DES encoding
3DES | Triple-DES encoding
RC4 | RC4 encoding
RC2 | RC2 encoding
IDEA | IDEA encoding
MAC Digest Algorithm:
MD5 | MD5 hash function
SHA1 | SHA1 hash function
SHA | SHA hash function
Aliases:
SSLv2 | all SSL version 2.0 ciphers
SSLv3 | all SSL version 3.0 ciphers
TLSv1 | all TLS version 1.0 ciphers
EXP | all export ciphers
EXPORT40 | all 40-bit export ciphers only
EXPORT56 | all 56-bit export ciphers only
LOW | all low strength ciphers (no export, single DES)
MEDIUM | all ciphers with 128 bit encryption
HIGH | all ciphers using Triple-DES
RSA | all ciphers using RSA key exchange
DH | all ciphers using Diffie-Hellman key exchange
EDH | all ciphers using Ephemeral Diffie-Hellman key exchange
ADH | all ciphers using Anonymous Diffie-Hellman key exchange
DSS | all ciphers using DSS authentication
NULL | all ciphers using no encryption

Now where this becomes interesting is that these can be put together to specify the order and ciphers you wish to use. To speed this up there are also aliases (SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM, HIGH) for certain groups of ciphers. These tags can be joined together with prefixes to form the cipher-spec. Available prefixes are:

  • none: add cipher to list
  • +: add ciphers to list and pull them to current location in list
  • -: remove cipher from list (can be added later again)
  • !: kill cipher from list completely (can not be added later again)

A simpler way to look at all of this is to use the ``openssl ciphers -v'' command which provides a nice way to successively create the correct cipher-spec string. The default cipher-spec string is ``ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'' which means the following: first, remove from consideration any ciphers that do not authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next, use ciphers using RC4 and RSA. Next include the high, medium and then the low security ciphers. Finally pull all SSLv2 and export ciphers to the end of the list.

$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'
NULL-SHA                SSLv3 Kx=RSA      Au=RSA  Enc=None      Mac=SHA1
NULL-MD5                SSLv3 Kx=RSA      Au=RSA  Enc=None      Mac=MD5
EDH-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
...                     ...               ...     ...           ...
EXP-RC4-MD5             SSLv3 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
EXP-RC2-CBC-MD5         SSLv2 Kx=RSA(512) Au=RSA  Enc=RC2(40)   Mac=MD5  export
EXP-RC4-MD5             SSLv2 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export

The complete list of particular RSA & DH ciphers for SSL is given in Table 2.

Example

SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW

Cipher-Tag | Protocol | Key Ex. | Auth. | Enc. | MAC | Type
RSA Ciphers:
DES-CBC3-SHA | SSLv3 | RSA | RSA | 3DES(168) | SHA1 |
DES-CBC3-MD5 | SSLv2 | RSA | RSA | 3DES(168) | MD5 |
IDEA-CBC-SHA | SSLv3 | RSA | RSA | IDEA(128) | SHA1 |
RC4-SHA | SSLv3 | RSA | RSA | RC4(128) | SHA1 |
RC4-MD5 | SSLv3 | RSA | RSA | RC4(128) | MD5 |
IDEA-CBC-MD5 | SSLv2 | RSA | RSA | IDEA(128) | MD5 |
RC2-CBC-MD5 | SSLv2 | RSA | RSA | RC2(128) | MD5 |
RC4-MD5 | SSLv2 | RSA | RSA | RC4(128) | MD5 |
DES-CBC-SHA | SSLv3 | RSA | RSA | DES(56) | SHA1 |
RC4-64-MD5 | SSLv2 | RSA | RSA | RC4(64) | MD5 |
DES-CBC-MD5 | SSLv2 | RSA | RSA | DES(56) | MD5 |
EXP-DES-CBC-SHA | SSLv3 | RSA(512) | RSA | DES(40) | SHA1 | export
EXP-RC2-CBC-MD5 | SSLv3 | RSA(512) | RSA | RC2(40) | MD5 | export
EXP-RC4-MD5 | SSLv3 | RSA(512) | RSA | RC4(40) | MD5 | export
EXP-RC2-CBC-MD5 | SSLv2 | RSA(512) | RSA | RC2(40) | MD5 | export
EXP-RC4-MD5 | SSLv2 | RSA(512) | RSA | RC4(40) | MD5 | export
NULL-SHA | SSLv3 | RSA | RSA | None | SHA1 |
NULL-MD5 | SSLv3 | RSA | RSA | None | MD5 |
Diffie-Hellman Ciphers:
ADH-DES-CBC3-SHA | SSLv3 | DH | None | 3DES(168) | SHA1 |
ADH-DES-CBC-SHA | SSLv3 | DH | None | DES(56) | SHA1 |
ADH-RC4-MD5 | SSLv3 | DH | None | RC4(128) | MD5 |
EDH-RSA-DES-CBC3-SHA | SSLv3 | DH | RSA | 3DES(168) | SHA1 |
EDH-DSS-DES-CBC3-SHA | SSLv3 | DH | DSS | 3DES(168) | SHA1 |
EDH-RSA-DES-CBC-SHA | SSLv3 | DH | RSA | DES(56) | SHA1 |
EDH-DSS-DES-CBC-SHA | SSLv3 | DH | DSS | DES(56) | SHA1 |
EXP-EDH-RSA-DES-CBC-SHA | SSLv3 | DH(512) | RSA | DES(40) | SHA1 | export
EXP-EDH-DSS-DES-CBC-SHA | SSLv3 | DH(512) | DSS | DES(40) | SHA1 | export
EXP-ADH-DES-CBC-SHA | SSLv3 | DH(512) | None | DES(40) | SHA1 | export
EXP-ADH-RC4-MD5 | SSLv3 | DH(512) | None | RC4(40) | MD5 | export

SSLEngine Directive

Description: | SSL Engine Operation Switch
Syntax: | SSLEngine on|off
Default: | SSLEngine off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive toggles the usage of the SSL/TLS Protocol Engine. This is usually used inside a <VirtualHost> section to enable SSL/TLS for a particular virtual host. By default the SSL/TLS Protocol Engine is disabled for both the main server and all configured virtual hosts.

Example

<VirtualHost _default_:443>
SSLEngine on
...
</VirtualHost>

SSLMutex Directive

Description: | Semaphore for internal mutual exclusion of operations
Syntax: | SSLMutex type
Default: | SSLMutex none
Context: | server config
Status: | Extension
Module: | mod_ssl

This configures the SSL engine's semaphore (aka. lock) which is used for mutual exclusion of operations which have to be done in a synchronized way between the pre-forked Apache server processes. This directive can only be used in the global server context because it's only useful to have one global mutex. This directive is designed to closely match the AcceptMutex directive

The following Mutex types are available:

  • none | no

    This is the default where no Mutex is used at all. Use it at your own risk. But because currently the Mutex is mainly used for synchronizing write access to the SSL Session Cache you can live without it as long as you accept a sometimes garbled Session Cache. So it's not recommended to leave this the default. Instead configure a real Mutex.

  • posixsem

    This is an elegant Mutex variant where a Posix Semaphore is used when possible. It is only available when the underlying platform and APR supports it.

  • sysvsem

    This is a somewhat elegant Mutex variant where a SystemV IPC Semaphore is used when possible. It is possible to "leak" SysV semaphores if processes crash before the semaphore is removed. It is only available when the underlying platform and APR supports it.

  • sem

    This directive tells the SSL Module to pick the "best" semaphore implementation available to it, choosing between Posix and SystemV IPC, in that order. It is only available when the underlying platform and APR supports at least one of the 2.

  • pthread

    This directive tells the SSL Module to use Posix thread mutexes. It is only available if the underlying platform and APR supports it.

  • fcntl:/path/to/mutex

    This is a portable Mutex variant where a physical (lock-)file and the fcntl() fucntion are used as the Mutex. Always use a local disk filesystem for /path/to/mutex and never a file residing on a NFS- or AFS-filesystem. It is only available when the underlying platform and APR supports it. Note: Internally, the Process ID (PID) of the Apache parent process is automatically appended to /path/to/mutex to make it unique, so you don't have to worry about conflicts yourself. Notice that this type of mutex is not available under the Win32 environment. There you have to use the semaphore mutex.

  • flock:/path/to/mutex

    This is similar to the fcntl:/path/to/mutex method with the exception that the flock() function is used to provide file locking. It is only available when the underlying platform and APR supports it.

  • file:/path/to/mutex

    This directive tells the SSL Module to pick the "best" file locking implementation available to it, choosing between fcntl and flock, in that order. It is only available when the underlying platform and APR supports at least one of the 2.

  • default | yes

    This directive tells the SSL Module to pick the default locking implementation as determined by the platform and APR.

Example

SSLMutex file:/usr/local/apache/logs/ssl_mutex

SSLOptions Directive

Description: | Configure various SSL engine run-time options
Syntax: | SSLOptions [+|-]option ...
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Extension
Module: | mod_ssl

This directive can be used to control various run-time options on a per-directory basis. Normally, if multiple SSLOptions could apply to a directory, then the most specific one is taken completely; the options are not merged. However if all the options on the SSLOptions directive are preceded by a plus (+) or minus (-) symbol, the options are merged. Any options preceded by a + are added to the options currently in force, and any options preceded by a - are removed from the options currently in force.

The available options are:

  • StdEnvVars

    When this option is enabled, the standard set of SSL related CGI/SSI environment variables are created. This per default is disabled for performance reasons, because the information extraction step is a rather expensive operation. So one usually enables this option for CGI and SSI requests only.

  • CompatEnvVars

    When this option is enabled, additional CGI/SSI environment variables are created for backward compatibility to other Apache SSL solutions. Look in the Compatibility chapter for details on the particular variables generated.

  • ExportCertData

    When this option is enabled, additional CGI/SSI environment variables are created: SSL_SERVER_CERT, SSL_CLIENT_CERT and SSL_CLIENT_CERT_CHAIN n (with n = 0,1,2,..). These contain the PEM-encoded X.509 Certificates of server and client for the current HTTPS connection and can be used by CGI scripts for deeper Certificate checking. Additionally all other certificates of the client certificate chain are provided, too. This bloats up the environment a little bit which is why you have to use this option to enable it on demand.

  • FakeBasicAuth

    When this option is enabled, the Subject Distinguished Name (DN) of the Client X509 Certificate is translated into a HTTP Basic Authorization username. This means that the standard Apache authentication methods can be used for access control. The user name is just the Subject of the Client's X509 Certificate (can be determined by running OpenSSL's openssl x509 command: openssl x509 -noout -subject -in certificate.crt). Note that no password is obtained from the user. Every entry in the user file needs this password: ``xxj31ZMTZzkVA'', which is the DES-encrypted version of the word `password''. Those who live under MD5-based encryption (for instance under FreeBSD or BSD/OS, etc.) should use the following MD5 hash of the same word: ``$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/''.

  • StrictRequire

    This forces forbidden access when SSLRequireSSL or SSLRequire successfully decided that access should be forbidden. Usually the default is that in the case where a ``Satisfy any'' directive is used, and other access restrictions are passed, denial of access due to SSLRequireSSL or SSLRequire is overridden (because that's how the Apache Satisfy mechanism should work.) But for strict access restriction you can use SSLRequireSSL and/or SSLRequire in combination with an ``SSLOptions +StrictRequire''. Then an additional ``Satisfy Any'' has no chance once mod_ssl has decided to deny access.

  • OptRenegotiate

    This enables optimized SSL connection renegotiation handling when SSL directives are used in per-directory context. By default a strict scheme is enabled where every per-directory reconfiguration of SSL parameters causes a full SSL renegotiation handshake. When this option is used mod_ssl tries to avoid unnecessary handshakes by doing more granular (but still safe) parameter checks. Nevertheless these granular checks sometimes maybe not what the user expects, so enable this on a per-directory basis only, please.

Example

SSLOptions +FakeBasicAuth -StrictRequire
<Files ~ "\.(cgi|shtml)$">
SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData
<Files>

SSLPassPhraseDialog Directive

Description: | Type of pass phrase dialog for encrypted private keys
Syntax: | SSLPassPhraseDialog type
Default: | SSLPassPhraseDialog builtin
Context: | server config
Status: | Extension
Module: | mod_ssl

When Apache starts up it has to read the various Certificate (see SSLCertificateFile) and Private Key (see SSLCertificateKeyFile) files of the SSL-enabled virtual servers. Because for security reasons the Private Key files are usually encrypted, mod_ssl needs to query the administrator for a Pass Phrase in order to decrypt those files. This query can be done in two ways which can be configured by type:

  • builtin

    This is the default where an interactive terminal dialog occurs at startup time just before Apache detaches from the terminal. Here the administrator has to manually enter the Pass Phrase for each encrypted Private Key file. Because a lot of SSL-enabled virtual hosts can be configured, the following reuse-scheme is used to minimize the dialog: When a Private Key file is encrypted, all known Pass Phrases (at the beginning there are none, of course) are tried. If one of those known Pass Phrases succeeds no dialog pops up for this particular Private Key file. If none succeeded, another Pass Phrase is queried on the terminal and remembered for the next round (where it perhaps can be reused).

    This scheme allows mod_ssl to be maximally flexible (because for N encrypted Private Key files you can use N different Pass Phrases - but then you have to enter all of them, of course) while minimizing the terminal dialog (i.e. when you use a single Pass Phrase for all N Private Key files this Pass Phrase is queried only once).

  • exec:/path/to/program

    Here an external program is configured which is called at startup for each encrypted Private Key file. It is called with two arguments (the first is of the form ``servername:portnumber'', the second is either ``RSA'' or ``DSA''), which indicate for which server and algorithm it has to print the corresponding Pass Phrase to stdout. The intent is that this external program first runs security checks to make sure that the system is not compromised by an attacker, and only when these checks were passed successfully it provides the Pass Phrase.

    Both these security checks, and the way the Pass Phrase is determined, can be as complex as you like. Mod_ssl just defines the interface: an executable program which provides the Pass Phrase on stdout. Nothing more or less! So, if you're really paranoid about security, here is your interface. Anything else has to be left as an exercise to the administrator, because local security requirements are so different.

    The reuse-algorithm above is used here, too. In other words: The external program is called only once per unique Pass Phrase.

Example:

SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter

SSLProtocol Directive

Description: | Configure usable SSL protocol flavors
Syntax: | SSLProtocol [+|-]protocol ...
Default: | SSLProtocol all
Context: | server config, virtual host
Override: | Options
Status: | Extension
Module: | mod_ssl

This directive can be used to control the SSL protocol flavors mod_ssl should use when establishing its server environment. Clients then can only connect with one of the provided protocols.

The available (case-insensitive) protocols are:

  • SSLv2

    This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the original SSL protocol as designed by Netscape Corporation.

  • SSLv3

    This is the Secure Sockets Layer (SSL) protocol, version 3.0. It is the successor to SSLv2 and the currently (as of February 1999) de-facto standardized SSL protocol from Netscape Corporation. It's supported by almost all popular browsers.

  • TLSv1

    This is the Transport Layer Security (TLS) protocol, version 1.0. It is the successor to SSLv3 and currently (as of February 1999) still under construction by the Internet Engineering Task Force (IETF). It's still not supported by any popular browsers.

  • All

    This is a shortcut for ``+SSLv2 +SSLv3 +TLSv1'' and a convinient way for enabling all protocols except one when used in combination with the minus sign on a protocol as the example above shows.

Example

# enable SSLv3 and TLSv1, but not SSLv2
SSLProtocol all -SSLv2

SSLProxyCACertificateFile Directive

Description: | File of concatenated PEM-encoded CA Certificates for Remote Server Auth
Syntax: | SSLProxyCACertificateFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose remote servers you deal with. These are used for Remote Server Authentication. Such a file is simply the concatenation of the various PEM-encoded Certificate files, in order of preference. This can be used alternatively and/or additionally to SSLProxyCACertificatePath.

Example

SSLProxyCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-remote-server.crt

SSLProxyCACertificatePath Directive

Description: | Directory of PEM-encoded CA Certificates for Remote Server Auth
Syntax: | SSLProxyCACertificatePath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the Certificates of Certification Authorities (CAs) whose remote servers you deal with. These are used to verify the remote server certificate on Remote Server Authentication.

The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you can't just place the Certificate files there: you also have to create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.

Example

SSLProxyCACertificatePath /usr/local/apache2/conf/ssl.crt/

SSLProxyCARevocationFile Directive

Description: | File of concatenated PEM-encoded CA CRLs for Remote Server Auth
Syntax: | SSLProxyCARevocationFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you can assemble the Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose remote servers you deal with. These are used for Remote Server Authentication. Such a file is simply the concatenation of the various PEM-encoded CRL files, in order of preference. This can be used alternatively and/or additionally to SSLProxyCARevocationPath.

Example

SSLProxyCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-remote-server.crl

SSLProxyCARevocationPath Directive

Description: | Directory of PEM-encoded CA CRLs for Remote Server Auth
Syntax: | SSLProxyCARevocationPath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the Certificate Revocation Lists (CRL) of Certification Authorities (CAs) whose remote servers you deal with. These are used to revoke the remote server certificate on Remote Server Authentication.

The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you have not only to place the CRL files there. Additionally you have to create symbolic links named hash-value.rN. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.

Example

SSLProxyCARevocationPath /usr/local/apache2/conf/ssl.crl/

SSLProxyCipherSuite Directive

Description: | Cipher Suite available for negotiation in SSL proxy handshake
Syntax: | SSLProxyCipherSuite cipher-spec
Default: | SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

Equivalent to SSLCipherSuite, but for the proxy connection. Please refer to SSLCipherSuite for additional information.

SSLProxyEngine Directive

Description: | SSL Proxy Engine Operation Switch
Syntax: | SSLProxyEngine on|off
Default: | SSLProxyEngine off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive toggles the usage of the SSL/TLS Protocol Engine for proxy. This is usually used inside a <VirtualHost> section to enable SSL/TLS for proxy usage in a particular virtual host. By default the SSL/TLS Protocol Engine is disabled for proxy image both for the main server and all configured virtual hosts.

Example

<VirtualHost _default_:443>
SSLProxyEngine on
...
</VirtualHost>

SSLProxyMachineCertificateFile Directive

Description: | File of concatenated PEM-encoded client certificates and keys to be used by the proxy
Syntax: | SSLProxyMachineCertificateFile filename
Context: | server config
Override: | Not applicable
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you keep the certificates and keys used for authentication of the proxy server to remote servers.

This referenced file is simply the concatenation of the various PEM-encoded certificate files, in order of preference. Use this directive alternatively or additionally to SSLProxyMachineCertificatePath.

Currently there is no support for encrypted private keys

Example:

SSLProxyMachineCertificateFile /usr/local/apache2/conf/ssl.crt/proxy.pem

SSLProxyMachineCertificatePath Directive

Description: | Directory of PEM-encoded client certificates and keys to be used by the proxy
Syntax: | SSLProxyMachineCertificatePath directory
Context: | server config
Override: | Not applicable
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the certificates and keys used for authentication of the proxy server to remote servers.

The files in this directory must be PEM-encoded and are accessed through hash filenames. Additionally, you must create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.

Currently there is no support for encrypted private keys

Example:

SSLProxyMachineCertificatePath /usr/local/apache2/conf/proxy.crt/

SSLProxyProtocol Directive

Description: | Configure usable SSL protocol flavors for proxy usage
Syntax: | SSLProxyProtocol [+|-]protocol ...
Default: | SSLProxyProtocol all
Context: | server config, virtual host
Override: | Options
Status: | Extension
Module: | mod_ssl

This directive can be used to control the SSL protocol flavors mod_ssl should use when establishing its server environment for proxy . It will only connect to servers using one of the provided protocols.

Please refer to SSLProtocol for additional information.

SSLProxyVerify Directive

Description: | Type of remote server Certificate verification
Syntax: | SSLProxyVerify level
Default: | SSLProxyVerify none
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive sets the Certificate verification level for the remote server Authentication. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the remote server authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotation with the reconfigured remote server verification level after the HTTP request was read but before the HTTP response is sent.

The following levels are available for level:

  • none: no remote server Certificate is required at all
  • optional: the remote server may present a valid Certificate
  • require: the remote server has to present a valid Certificate
  • optional_no_ca: the remote server may present a valid Certificate
    but it need not to be (successfully) verifiable.

In practice only levels none and require are really interesting, because level optional doesn't work with all servers and level optional_no_ca is actually against the idea of authentication (but can be used to establish SSL test pages, etc.)

Example

SSLProxyVerify require

SSLProxyVerifyDepth Directive

Description: | Maximum depth of CA Certificates in Remote Server Certificate verification
Syntax: | SSLProxyVerifyDepth number
Default: | SSLProxyVerifyDepth 1
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive sets how deeply mod_ssl should verify before deciding that the remote server does not have a valid certificate. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotation with the reconfigured remote server verification depth after the HTTP request was read but before the HTTP response is sent.

The depth actually is the maximum number of intermediate certificate issuers, i.e. the number of CA certificates which are max allowed to be followed while verifying the remote server certificate. A depth of 0 means that self-signed remote server certificates are accepted only, the default depth of 1 means the remote server certificate can be self-signed or has to be signed by a CA which is directly known to the server (i.e. the CA's certificate is under SSLProxyCACertificatePath), etc.

Example

SSLProxyVerifyDepth 10

SSLRandomSeed Directive

Description: | Pseudo Random Number Generator (PRNG) seeding source
Syntax: | SSLRandomSeed context source [bytes]
Context: | server config
Status: | Extension
Module: | mod_ssl

This configures one or more sources for seeding the Pseudo Random Number Generator (PRNG) in OpenSSL at startup time (context is startup) and/or just before a new SSL connection is established (context is connect). This directive can only be used in the global server context because the PRNG is a global facility.

The following source variants are available:

  • builtin

    This is the always available builtin seeding source. It's usage consumes minimum CPU cycles under runtime and hence can be always used without drawbacks. The source used for seeding the PRNG contains of the current time, the current process id and (when applicable) a randomly choosen 1KB extract of the inter-process scoreboard structure of Apache. The drawback is that this is not really a strong source and at startup time (where the scoreboard is still not available) this source just produces a few bytes of entropy. So you should always, at least for the startup, use an additional seeding source.

  • file:/path/to/source

    This variant uses an external file /path/to/source as the source for seeding the PRNG. When bytes is specified, only the first bytes number of bytes of the file form the entropy (and bytes is given to /path/to/source as the first argument). When bytes is not specified the whole file forms the entropy (and 0 is given to /path/to/source as the first argument). Use this especially at startup time, for instance with an available /dev/random and/or /dev/urandom devices (which usually exist on modern Unix derivates like FreeBSD and Linux).

    But be careful: Usually /dev/random provides only as much entropy data as it actually has, i.e. when you request 512 bytes of entropy, but the device currently has only 100 bytes available two things can happen: On some platforms you receive only the 100 bytes while on other platforms the read blocks until enough bytes are available (which can take a long time). Here using an existing /dev/urandom is better, because it never blocks and actually gives the amount of requested data. The drawback is just that the quality of the received data may not be the best.

    On some platforms like FreeBSD one can even control how the entropy is actually generated, i.e. by which system interrupts. More details one can find under rndcontrol(8) on those platforms. Alternatively, when your system lacks such a random device, you can use tool like EGD (Entropy Gathering Daemon) and run it's client program with the exec:/path/to/program/ variant (see below) or use egd:/path/to/egd-socket (see below).

  • exec:/path/to/program

    This variant uses an external executable /path/to/program as the source for seeding the PRNG. When bytes is specified, only the first bytes number of bytes of its stdout contents form the entropy. When bytes is not specified, the entirety of the data produced on stdout form the entropy. Use this only at startup time when you need a very strong seeding with the help of an external program (for instance as in the example above with the truerand utility you can find in the mod_ssl distribution which is based on the AT&T truerand library). Using this in the connection context slows down the server too dramatically, of course. So usually you should avoid using external programs in that context.

  • egd:/path/to/egd-socket (Unix only)

    This variant uses the Unix domain socket of the external Entropy Gathering Daemon (EGD) (see http://www.lothar.com/tech /crypto/) to seed the PRNG. Use this if no random device exists on your platform.

Example

SSLRandomSeed startup builtin
SSLRandomSeed startup file:/dev/random
SSLRandomSeed startup file:/dev/urandom 1024
SSLRandomSeed startup exec:/usr/local/bin/truerand 16
SSLRandomSeed connect builtin
SSLRandomSeed connect file:/dev/random
SSLRandomSeed connect file:/dev/urandom 1024

SSLRequire Directive

Description: | Allow access only when an arbitrarily complex boolean expression is true
Syntax: | SSLRequire expression
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive specifies a general access requirement which has to be fulfilled in order to allow access. It's a very powerful directive because the requirement specification is an arbitrarily complex boolean expression containing any number of access checks.

The expression must match the following syntax (given as a BNF grammar notation):

expr     ::= "true" | "false"
           | "!" expr
           | expr "&&" expr
           | expr "||" expr
           | "(" expr ")"
           | comp

comp     ::= word "==" word | word "eq" word
           | word "!=" word | word "ne" word
           | word "<"  word | word "lt" word
           | word "<=" word | word "le" word
           | word ">"  word | word "gt" word
           | word ">=" word | word "ge" word
           | word "in" "{" wordlist "}"
           | word "=~" regex
           | word "!~" regex

wordlist ::= word
           | wordlist "," word

word     ::= digit
           | cstring
           | variable
           | function

digit    ::= [0-9]+
cstring  ::= "..."
variable ::= "%{" varname "}"
function ::= funcname "(" funcargs ")"

while for varname any variable from Table 3 can be used. Finally for funcname the following functions are available:

  • file(filename)

    This function takes one string argument and expands to the contents of the file. This is especially useful for matching this contents against a regular expression, etc.

Notice that expression is first parsed into an internal machine representation and then evaluated in a second step. Actually, in Global and Per-Server Class context expression is parsed at startup time and at runtime only the machine representation is executed. For Per-Directory context this is different: here expression has to be parsed and immediately executed for every request.

Example

SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \
and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \
and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \
and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \
and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \
or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/

Standard CGI/1.0 and Apache variables:

HTTP_USER_AGENT        PATH_INFO             AUTH_TYPE
HTTP_REFERER           QUERY_STRING          SERVER_SOFTWARE
HTTP_COOKIE            REMOTE_HOST           API_VERSION
HTTP_FORWARDED         REMOTE_IDENT          TIME_YEAR
HTTP_HOST              IS_SUBREQ             TIME_MON
HTTP_PROXY_CONNECTION  DOCUMENT_ROOT         TIME_DAY
HTTP_ACCEPT            SERVER_ADMIN          TIME_HOUR
HTTP:headername        SERVER_NAME           TIME_MIN
THE_REQUEST            SERVER_PORT           TIME_SEC
REQUEST_METHOD         SERVER_PROTOCOL       TIME_WDAY
REQUEST_SCHEME         REMOTE_ADDR           TIME
REQUEST_URI            REMOTE_USER           ENV:variablename
REQUEST_FILENAME

SSL-related variables:

HTTPS                  SSL_CLIENT_M_VERSION   SSL_SERVER_M_VERSION
                       SSL_CLIENT_M_SERIAL    SSL_SERVER_M_SERIAL
SSL_PROTOCOL           SSL_CLIENT_V_START     SSL_SERVER_V_START
SSL_SESSION_ID         SSL_CLIENT_V_END       SSL_SERVER_V_END
SSL_CIPHER             SSL_CLIENT_S_DN        SSL_SERVER_S_DN
SSL_CIPHER_EXPORT      SSL_CLIENT_S_DN_C      SSL_SERVER_S_DN_C
SSL_CIPHER_ALGKEYSIZE  SSL_CLIENT_S_DN_ST     SSL_SERVER_S_DN_ST
SSL_CIPHER_USEKEYSIZE  SSL_CLIENT_S_DN_L      SSL_SERVER_S_DN_L
SSL_VERSION_LIBRARY    SSL_CLIENT_S_DN_O      SSL_SERVER_S_DN_O
SSL_VERSION_INTERFACE  SSL_CLIENT_S_DN_OU     SSL_SERVER_S_DN_OU
                       SSL_CLIENT_S_DN_CN     SSL_SERVER_S_DN_CN
                       SSL_CLIENT_S_DN_T      SSL_SERVER_S_DN_T
                       SSL_CLIENT_S_DN_I      SSL_SERVER_S_DN_I
                       SSL_CLIENT_S_DN_G      SSL_SERVER_S_DN_G
                       SSL_CLIENT_S_DN_S      SSL_SERVER_S_DN_S
                       SSL_CLIENT_S_DN_D      SSL_SERVER_S_DN_D
                       SSL_CLIENT_S_DN_UID    SSL_SERVER_S_DN_UID
                       SSL_CLIENT_S_DN_Email  SSL_SERVER_S_DN_Email
                       SSL_CLIENT_I_DN        SSL_SERVER_I_DN
                       SSL_CLIENT_I_DN_C      SSL_SERVER_I_DN_C
                       SSL_CLIENT_I_DN_ST     SSL_SERVER_I_DN_ST
                       SSL_CLIENT_I_DN_L      SSL_SERVER_I_DN_L
                       SSL_CLIENT_I_DN_O      SSL_SERVER_I_DN_O
                       SSL_CLIENT_I_DN_OU     SSL_SERVER_I_DN_OU
                       SSL_CLIENT_I_DN_CN     SSL_SERVER_I_DN_CN
                       SSL_CLIENT_I_DN_T      SSL_SERVER_I_DN_T
                       SSL_CLIENT_I_DN_I      SSL_SERVER_I_DN_I
                       SSL_CLIENT_I_DN_G      SSL_SERVER_I_DN_G
                       SSL_CLIENT_I_DN_S      SSL_SERVER_I_DN_S
                       SSL_CLIENT_I_DN_D      SSL_SERVER_I_DN_D
                       SSL_CLIENT_I_DN_UID    SSL_SERVER_I_DN_UID
                       SSL_CLIENT_I_DN_Email  SSL_SERVER_I_DN_Email
                       SSL_CLIENT_A_SIG       SSL_SERVER_A_SIG
                       SSL_CLIENT_A_KEY       SSL_SERVER_A_KEY
                       SSL_CLIENT_CERT        SSL_SERVER_CERT
                       SSL_CLIENT_CERT_CHAINn
                       SSL_CLIENT_VERIFY

SSLRequireSSL Directive

Description: | Deny access when SSL is not used for the HTTP request
Syntax: | SSLRequireSSL
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for the current connection. This is very handy inside the SSL-enabled virtual host or directories for defending against configuration errors that expose stuff that should be protected. When this directive is present all requests are denied which are not using SSL.

Example

SSLRequireSSL

SSLSessionCache Directive

Description: | Type of the global/inter-process SSL Session Cache
Syntax: | SSLSessionCache type
Default: | SSLSessionCache none
Context: | server config
Status: | Extension
Module: | mod_ssl

This configures the storage type of the global/inter-process SSL Session Cache. This cache is an optional facility which speeds up parallel request processing. For requests to the same server process (via HTTP keep-alive), OpenSSL already caches the SSL session information locally. But because modern clients request inlined images and other data via parallel requests (usually up to four parallel requests are common) those requests are served by different pre-forked server processes. Here an inter-process cache helps to avoid unneccessary session handshakes.

The following two storage types are currently supported:

  • none

    This is the default and just disables the global/inter-process Session Cache. There is no drawback in functionality, but a noticeable speed penalty can be observed.

  • dbm:/path/to/datafile

    This makes use of a DBM hashfile on the local disk to synchronize the local OpenSSL memory caches of the server processes. The slight increase in I/O on the server results in a visible request speedup for your clients, so this type of storage is generally recommended.

  • shm:/path/to/datafile[(size)]

    This makes use of a high-performance hash table (approx. size bytes in size) inside a shared memory segment in RAM (established via /path/to/datafile) to synchronize the local OpenSSL memory caches of the server processes. This storage type is not available on all platforms.

Examples

SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data
SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000)

SSLSessionCacheTimeout Directive

Description: | Number of seconds before an SSL session expires in the Session Cache
Syntax: | SSLSessionCacheTimeout seconds
Default: | SSLSessionCacheTimeout 300
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the timeout in seconds for the information stored in the global/inter-process SSL Session Cache and the OpenSSL internal memory cache. It can be set as low as 15 for testing, but should be set to higher values like 300 in real life.

Example

SSLSessionCacheTimeout 600

SSLVerifyClient Directive

Description: | Type of Client Certificate verification
Syntax: | SSLVerifyClient level
Default: | SSLVerifyClient none
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive sets the Certificate verification level for the Client Authentication. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotation with the reconfigured client verification level after the HTTP request was read but before the HTTP response is sent.

The following levels are available for level:

  • none: no client Certificate is required at all
  • optional: the client may present a valid Certificate
  • require: the client has to present a valid Certificate
  • optional_no_ca: the client may present a valid Certificate
    but it need not to be (successfully) verifiable.

In practice only levels none and require are really interesting, because level optional doesn't work with all browsers and level optional_no_ca is actually against the idea of authentication (but can be used to establish SSL test pages, etc.)

Example

SSLVerifyClient require

SSLVerifyDepth Directive

Description: | Maximum depth of CA Certificates in Client Certificate verification
Syntax: | SSLVerifyDepth number
Default: | SSLVerifyDepth 1
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive sets how deeply mod_ssl should verify before deciding that the clients don't have a valid certificate. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotation with the reconfigured client verification depth after the HTTP request was read but before the HTTP response is sent.

The depth actually is the maximum number of intermediate certificate issuers, i.e. the number of CA certificates which are max allowed to be followed while verifying the client certificate. A depth of 0 means that self-signed client certificates are accepted only, the default depth of 1 means the client certificate can be self-signed or has to be signed by a CA which is directly known to the server (i.e. the CA's certificate is under SSLCACertificatePath), etc.

Example

SSLVerifyDepth 10


mod_status - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_status

説明: | サーバの活動状況と性能に関する情報を提供する
ステータス: | Base
モジュール識別子: | status_module
ソースファイル: | mod_status.c

概要

この Status モジュールによりサーバ管理者はサーバがどのくらい の性能で動作しているかを知ることができるようになります。 現時点でのサーバの統計情報を読みやすい形式で現した HTML ページが 表示されます。必要であれば、このページは自動的にリフレッシュさせる こともできます (互換性のあるブラウザを使用している場合)。 別に、現時点でのサーバの状態を単純な機械読み取り可能なリストで 現すページもあります。

表示される情報は:

  • リクエストを扱っているワーカーの数
  • アイドル (訳注: リクエストを扱っていない) ワーカーの数
  • 各ワーカーの状態、ワーカーが扱ったリクエストの数、 ワーカーが送った総バイト数 (*)
  • 総アクセス数と総バイト数 (*)
  • サーバが起動もしくは再起動された時刻と動作している時間
  • 平均の 1 秒あたりのリクエスト数、1 秒あたりの送られたバイト数、 リクエストあたりのバイト数 (*)
  • 各ワーカーと Apache 全体で使用されている CPU の割合 (*)
  • 現時点のホストと処理されているリクエスト (*)

"(*)" の付いている情報を表示するためにはコンパイル時のオプション を使用する必要があります。これらの統計情報を得るために必要な コードは標準の Apache には含まれていません。

Status を使用可能にする

foo.com ドメインからのブラウザのみに対して ステータスの報告を使用可能にするには 以下のコードを httpd.conf 設定ファイルに追加します

<Location /server-status>
SetHandler server-status

Order Deny,Allow
Deny from all
Allow from .foo.com
</Location>

これで、サーバの統計情報をウェブブラウザを使って http://your.server.name/server-status をアクセスすることにより 知ることができるようになります。

自動更新

ブラウザが「リフレシュ」機能をサポートしていれば、ステータスページを 自動的に更新するようにできます。N 秒毎に更新させるためには http://your.server.name/server-status?refresh=N というページをアクセスしてください。

機械読み取り可能なステータスファイル

http://your.server.name/server-status?auto を アクセスすることにより、ステータスファイルの機械読み取り可能なバージョンを 得ることができます。これは自動的に実行されるときに便利です。 Apache の /support ディレクトリにある Perl プログラム log_server_status を見てください。

mod_status がサーバに組み込まれている 場合、ハンドラの機能はディレクトリ毎のファイル (すなわち、.htaccess) も含むすべての 設定ファイルで使用可能になることには注意をしておく必要があります。 これは、サイトによってはセキュリティに関する望ましくない結果を もたらすことがあるかもしれません。

ExtendedStatus ディレクティブ

説明: | 各リクエストに対して拡張ステータス情報を保存する
構文: | ExtendedStatus On|Off
デフォルト: | ExtendedStatus Off
コンテキスト: | サーバ設定ファイル
ステータス: | Base
モジュール: | mod_status
互換性: | ExtendedStatus は Apache 1.3.2 以降でのみ使用可能

この設定はサーバ全体に対して適用され、バーチャルホスト毎に 変更することはできません。拡張ステータス情報の収集はサーバの 動作を遅くすることがあります。


mod_suexec - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_suexec

説明: | 指定されたユーザとグループで CGI スクリプトを実行する
ステータス: | 拡張
モジュール識別子: | suexec_module
ソースファイル: | mod_suexec.c
互換性: | Apache 2.0 以降で使用可能

概要

このモジュールと suexec サポートプログラム により、CGI スクリプトが指定されたユーザとグループで 実行されるようにできます。

参照

  • SuEXEC サポート

SuexecUserGroup ディレクティブ

説明: | CGI プログラムのユーザパーミッション、グループパーミッション
構文: | SuexecUserGroup User Group
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | 拡張
モジュール: | mod_suexec
互換性: | SuexecUserGroup は 2.0 以降でのみ使用可能。

SuexecUserGroup ディレクティブは CGI プログラム が実行されるユーザとグループを指定できるようにします。CGI 以外の リクエストは User ディレクティブで指定されたユーザのままで処理されます。 このディレクティブは Apache 1.3 における VirtualHosts の中で User ディレクティブと Group ディレクティブを使う用法の代わりになります。

例

SuexecUserGroup nobody nogroup


mod_unique_id - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_unique_id

説明: | それぞれのリクエストに対する一意な識別子の入った環境変数を 提供する
ステータス: | Extension
モジュール識別子: | unique_id_module
ソースファイル: | mod_unique_id.c

概要

このモジュールは非常に制限された条件下で、 それぞれのリクエストに「すべて」のリクエストに対して 一意に決まることが保証されている魔法のトークンを提供します。 この一意な識別子は、適切に設定されたクラスタでは複数の マシンの間でさえも一意になります。それぞれのリクエストに対して環境変数 UNIQUE_ID に識別子が設定されます。 一意な識別子が便利な理由はいろいろありますが、 このドキュメントの目的からは外れるため、ここでは説明しません。

理論

まずはじめに、Apache サーバが Unix マシンでどのように動作をするかを簡単に説明します。 この機能は現時点では Windows NT ではサポートされていません。 Unix マシンでは Apache はいくつかの子プロセスを作成し、 その子プロセスが一つずつリクエストを処理します。それぞれの子プロセスは、 生存期間中に複数のリクエストを扱うことができます。 この議論では子プロセス間では一切データを共有しないことにします。 以後、この子プロセスのことを httpd プロセスと呼びます。

あなたのウェブサイトにはあなたが管理するいくつかのマシンがあるとします。 それらをまとめてクラスタと呼ぶことにします。それぞれのマシンは複数の Apache を実行することもできます。 これらすべてをまとめたものが「宇宙」であると考えられます。 いくつかの仮定の下で、クラスタのマシン間がたくさん通信をすることなく、 この宇宙の中でそれぞれのリクエストに一意な識別子を生成できることを示します。

クラスタにあるマシンは以下の要求を見たさなければなりません。 (マシンが一つだけだとしても、NTP で時計を合わせる方が良いです。)

  • NTP や他のネットワーク上で時間を合わせるプロトコルによって 各マシンの時間の同期が取られていること。
  • モジュールがホスト名を引いて違う IP アドレスを受け取ることができるように、 クラスタのそれぞれのマシンのホスト名が違うこと。

オペレーティングシステムにおいては、pid (プロセス ID) が 32 ビットの範囲内であることを仮定します。オペレーティングシステムの pid が 32 ビットを超える場合は、簡単な修正ではありますが、 コードを変更する必要があります。

これらの仮定が満たされていると、ある時点において、 クラスタ内のどのマシンのどの httpd プロセスでも、一意に同定することができます。これはマシンの IP アドレスと httpd プロセスの pid で十分に行なうことができます。 ですから、リクエストに一意な識別子を生成するためには、 時刻を区別する必要があるだけです。

時刻を区別するために、Unix のタイムスタンプ (UTC の 1970 年 1 月 1 日からの秒数) と、16 ビットのカウンタを使います。 タイムスタンプの粒度は一秒ですので、一秒間の 65536 までの値を表現するためにカウンタを使用します。四つの値 ( ip_addr, pid, time_stamp, counter ) で各 httpd プロセスで一秒の間に 65536 リクエストを数えあげることができます。 時間が経つと pid が再利用されるという問題がありますが、 この問題を解決するためにカウンタが使用されます。

httpd の子プロセスが作成されると、カウンタは (その時点のマイクロ秒 ÷ 10) modulo 65536 で初期化されます (この式はいくつかのシステムにある、マイクロ秒の タイマの下位ビットが異なるという問題を解決するために選ばれました)。 一意な識別子が生成されたとき、使用されるタイムスタンプは ウェブサーバにリクエストが到着した時刻になります。 カウンタは識別子が生成されるたびに増加します (あふれた場合は 0 に戻ります)。

カーネルはプロセスをフォークすると、それぞれのプロセスのために pid を生成します。pid は繰り返されることが許可されています (pid の値は多くの Unix では 16 ビットですが、新しいシステムでは 32 ビットに拡張されています)。 ですから、ある程度の時間が経過すると同じ pid が再び使用されます。 しかし、一秒内に再使用されなければ、 四つの値の一意性は保たれます。つまり、我々はシステムが一秒間 に 65536 個のプロセスを起動しないと仮定しています (いくつかの Unix では 32768 プロセスですが、それですらほとんどあり得ないでしょう)。

何らかの理由で、同じ時刻が繰り返されたとしましょう。 つまり、システムの時計が狂っていて、もう一度過去の時刻になってしまった (もしくは進みすぎていたときに、 正しい時刻に戻したために再び将来の時刻になってしまった) とします。 この場合、pid とタイムスタンプが再使用されることが簡単に示されます。 カウンタ初期化用の関数は、この問題の回避を手助けしようと選択されています。 本当はカウンタの初期化をするためにランダムな数字を使いたいのですが、 ほとんどのシステムでは簡単に使用できる数は無いことに注意してください (すなわち、rand ()は使えません。rand () には seed を与える必要があり、seed には時刻を使えません。一秒単位では、 その時刻はすでに繰り返されているからです)。 これは、完璧な対策ではありません。

この対策はどのくらい効果があるでしょうか? ここでは、マシン群の中の一つは最大で一秒に 500 リクエストを扱うと仮定します (これを書いている時点では妥当な上限です。 通常システムがすることは静的なファイルを取りだすだけではありませんから)。 それを行なうために、そのマシンは並行して来るクライアントの数に 応じた数の子プロセスを要求します。 しかしながら、悲観的に考えて、一つの子プロセスが一秒に 500 リクエストを扱えるとします。そうすると、(一秒の精度において) 時刻が同じ時を繰り返すと、この子プロセスがカウンタの値を再び使い、 一意性が壊れる可能性が 1.5% あります。 これは非常に悲観的な例で、実世界の値では、ほとんど起こりそうにありません。 それでもこれが起こる可能性のあるようなシステムなら、 (プログラムコードを編集して) カウンタを 32 ビットにするのが良いでしょう。

サマータイムにより時計が「戻される」ことを気にしている人が いるかもしれません。ここで使用される時間は UTC であり、 それは「常に」進むのでここでは問題になりません。x86 上の Unix はこの条件を満たすために適切な設定が必要かもしれないことに 注意してください。マザーボードの時計は UTC になっていて、 他の時間はそこから適切に補正されることを仮定できるように 設定されなければなりません。そのような場合でさえ、NTP を使っているならばリブート後にすぐ正しい UTC の時間になるでしょう。

UNIQUE_ID 環境変数は 112 ビット (32 ビット IP アドレス、32 ビット pid, 32 ビットタイムスタンプ、16 ビットカウンタの四つの組) をアルファベット [A-Za-z0-9@-] を用いて MIME の base64 符号化と同様の方法により符号化し、19 の文字を生成することにより作成されます。MIME の base64 のアルファベットは実際は [A-Za-z0-9+/] ですが、 + と / とは URL では特別な符号化が必要なので、あまり望ましくありません。 全ての値はネットワークバイトオーダで符号化されますので、 符号は違ったバイトオーダのアーキテクチャ間で比較可能です。 実際の符号化の順番は: タイムスタンプ、IP アドレス、pid, カウンタです。この順には目的がありますが、 アプリケーションは符号を解析するべきではないことを強調しておきます。 アプリケーションは符号化された UNIQUE_ID 全体を透過的なトークンとして扱うべきです。 UNIQUE_ID は他の UNIQUE_ID との等価性を調べるためだけにのみ使用できます。

この順番は将来、既存の UNIQUE_ID のデータベースとの衝突を心配することなく符号を変更することが 可能になるように選択しています。 新しい符号はタイムスタンプを最初の要素として残すのが望ましく、 それ以外は同じアルファベットとビット長を使うことができます。 タイムスタンプは本質的に増加系列ですので、 クラスタの全てのマシンがリクエストとサーバ機能を停止して、 古い符号化方式を使用するのをやめるフラグ秒があれば十分です。 その後は、リクエストを再開し、 新しい符号を発行することができるようになります。

我々はこれが、 この問題に対する比較的移植性の高い解決法だと考えています。 Windows NT のようなマルチスレッドのシステムに拡張することができますし、 将来必要になればさらに増やすこともできます。 ID は必要に応じて長くすることができますので、生成された ID は実質上、無限に有効です。また、クラスタのマシン間の通信も事実上必要なく (NTP による同期のみが必要で、これはオーバヘッドはあまりありません)、httpd プロセス間の通信も必要ありません (通信はカーネルにより割り当てられた pid の値により暗黙の内に行なわています)。 さらに限られた状況下では、ID はさらに短くすることができますが、 より多くの情報を仮定する必要がでてきます (例えば、32 ビット IP アドレスはどのサイトにおいても過剰な情報ですが、 それの代わりになる移植性のあるものはありません)。


mod_userdir - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

Apache モジュール mod_userdir

説明: | ユーザ専用のディレクトリを提供
ステータス: | Base
モジュール識別子: | userdir_module
ソースファイル: | mod_userdir.c

概要

このモジュールは、 http://example.com/~user/ 構文を使ってユーザ専用ディレクトリにアクセスできるようにします。

参照

  • URL から ファイルシステムへのマッピング
  • public_html チュートリアル

UserDir ディレクティブ

説明: | ユーザ専用ディレクトリの位置
構文: | UserDir directory-filename
デフォルト: | UserDir public_html
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_userdir

UserDir ディレクティブは、 ユーザのドキュメントへのリクエストを受けた時に使う ユーザのホームディレクトリ中の、実際のディレクトリを 設定します。 directory-filename には次のどれかを指定します:

  • ディレクトリ名か下に示すようなパターン。
  • disabled キーワード。 enabled キーワード (下記参照) で明示的に 指定されたユーザ以外の 全てのユーザ名-ディレクトリ変換を しないようにします。
  • disabled キーワードと、スペース区切りのユーザ名リスト。 このリスト中に含まれるユーザ名に対しては、たとえ enabled 節にあったとしても、 決してディレクトリ変換は行われません。
  • enebled キーワードとスペース区切りのユーザ名リスト。 全体では変換が無効になっていたといたとしても、 これらのユーザ名にはディレクトリ変換が行われます。 ただし、disabled 節にもあれば変換はされません。

もし enabled も disabled キーワードも UserDir に現われていなければ、 引数はファイル名パターンとして扱われ、 名前からディレクトリへの変換の指定を行なう時に使われます。 http://www.foo.com/~bob/one/two.html へのリクエストは次のように変換されます:

UserDir ディレクティブ | 変換後のパス
UserDir public_html | ~bob/public_html/one/two.html
UserDir /usr/web | /usr/web/bob/one/two.html
UserDir /home/*/www | /home/bob/www/one/two.html

次のディレクティブはクライアントに対してリダイレクトを 送信します:

UserDir ディレクティブ | 変換後のパス
UserDir http://www.foo.com/users | http://www.foo.com/users/bob/one/two.html
UserDir http://www.foo.com/*/usr | http://www.foo.com/bob/usr/one/two.html
UserDir http://www.foo.com/~*/ | http://www.foo.com/~bob/one/two.html
このディレクティブを使うときは注意してください; "UserDir ./" は "/~root" から "/" へマップしますが、 これは望ましい動作ではないでしょう。 "UserDir disabled root" 宣言を 設定の中に含めておくことを強くお薦めします。 追加情報に Directory ディレクティブや セキュリティ Tips のページもご覧下さい。

追加の例:

少数のユーザのみが UserDir ディレクトリを利用し、それ以外には利用させたくない場合は 次を使いましょう:

UserDir disabled
UserDir enabled user1 user2 user3

大部分のユーザは UserDir ディレクトリを利用するけれど、 少数の人は不許可にしたい場合は、次を使いましょう:

UserDir enabled
UserDir disabled user4 user5 user6

他のユーザディレクトリを指定することもできます。 次のようなコマンドを使うと:

Userdir public_html /usr/web http://www.foo.com/

http://www.foo.com/~bob/one/two.html へのリクエストはまず ~bob/public_html/one/two.html のページを調べ、その次に /usr/web/bob/one/two.html を調べ、最後に http://www.foo.com/bob/one/two.html へのリダイレクトを送ります。

リダイレクトを加える場合は、リストの最後の選択肢でなければなりません。 Apache はリダイレクトが成功するかどうかを決めることはできませんので、 リストの前の方にリダイレクトを書くと、それが必ず使用される選択肢に なってしまいます。

参照

  • public_html チュートリアル


mod_usertrack - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_usertrack

Description: | Clickstream logging of user activity on a site
Status: | Extension
Module?dentifier: | usertrack_module
Source?ile: | mod_usertrack.c

Summary

Previous releases of Apache have included a module which generates a 'clickstream' log of user activity on a site using cookies. This was called the "cookies" module, mod_cookies. In Apache 1.2 and later this module has been renamed the "user tracking" module, mod_usertrack. This module has been simplified and new directives added.

Logging

Previously, the cookies module (now the user tracking module) did its own logging, using the CookieLog directive. In this release, this module does no logging at all. Instead, a configurable log format file should be used to log user click-streams. This is possible because the logging module now allows multiple log files. The cookie itself is logged by using the text %{cookie}n in the log file format. For example:

CustomLog logs/clickstream "%{cookie}n %r %t"

For backward compatibility the configurable log module implements the old CookieLog directive, but this should be upgraded to the above CustomLog directive.

2-digit or 4-digit dates for cookies?

(the following is from message <022701bda43d$9d32bbb0$1201a8c0@christian.office.sane.com> in the new-httpd archives)

From: "Christian Allen" <christian@sane.com>
Subject: Re: Apache Y2K bug in mod_usertrack.c
Date: Tue, 30 Jun 1998 11:41:56 -0400

Did some work with cookies and dug up some info that might be useful.

True, Netscape claims that the correct format NOW is four digit dates, and
four digit dates do in fact work... for Netscape 4.x (Communicator), that
is.  However, 3.x and below do NOT accept them.  It seems that Netscape
originally had a 2-digit standard, and then with all of the Y2K hype and
probably a few complaints, changed to a four digit date for Communicator.
Fortunately, 4.x also understands the 2-digit format, and so the best way to
ensure that your expiration date is legible to the client's browser is to
use 2-digit dates.

However, this does not limit expiration dates to the year 2000; if you use
an expiration year of "13", for example, it is interpreted as 2013, NOT
1913!  In fact, you can use an expiration year of up to "37", and it will be
understood as "2037" by both MSIE and Netscape versions 3.x and up (not sure
about versions previous to those).  Not sure why Netscape used that
particular year as its cut-off point, but my guess is that it was in respect
to UNIX's 2038 problem.  Netscape/MSIE 4.x seem to be able to understand
2-digit years beyond that, at least until "50" for sure (I think they
understand up until about "70", but not for sure).

Summary:  Mozilla 3.x and up understands two digit dates up until "37"
(2037).  Mozilla 4.x understands up until at least "50" (2050) in 2-digit
form, but also understands 4-digit years, which can probably reach up until
9999.  Your best bet for sending a long-life cookie is to send it for some
time late in the year "37".

CookieDomain Directive

Description: | The domain to which the tracking cookie applies
Syntax: | CookieDomain domain
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

This directive controls the setting of the domain to which the tracking cookie applies. If not present, no domain is included in the cookie header field.

The domain string must begin with a dot, and must include at least one embedded dot. That is, ".foo.com" is legal, but "foo.bar.com" and ".com" are not.

CookieExpires Directive

Description: | Expiry time for the tracking cookie
Syntax: | CookieExpires expiry-period
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

When used, this directive sets an expiry time on the cookie generated by the usertrack module. The expiry-period can be given either as a number of seconds, or in the format such as "2 weeks 3 days 7 hours". Valid denominations are: years, months, weeks, days, hours, minutes and seconds. If the expiry time is in any format other than one number indicating the number of seconds, it must be enclosed by double quotes.

If this directive is not used, cookies last only for the current browser session.

CookieName Directive

Description: | Name of the tracking cookie
Syntax: | CookieName token
Default: | CookieName Apache
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

This directive allows you to change the name of the cookie this module uses for its tracking purposes. By default the cookie is named "Apache".

You must specify a valid cookie name; results are unpredictable if you use a name containing unusual characters. Valid characters include A-Z, a-z, 0-9, "_", and "-".

CookieStyle Directive

Description: | Format of the cookie header field
Syntax: | CookieStyle Netscape|Cookie|Cookie2|RFC2109|RFC2965
Default: | CookieStyle Netscape
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

This directive controls the format of the cookie header field. The three formats allowed are:

  • Netscape, which is the original but now deprecated syntax. This is the default, and the syntax Apache has historically used.
  • Cookie or RFC2109, which is the syntax that superseded the Netscape syntax.
  • Cookie2 or RFC2965, which is the most current cookie syntax.

Not all clients can understand all of these formats. but you should use the newest one that is generally acceptable to your users' browsers.

CookieTracking Directive

Description: | Enables tracking cookie
Syntax: | CookieTracking on|off
Default: | CookieTracking off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

When the user track module is compiled in, and "CookieTracking on" is set, Apache will start sending a user-tracking cookie for all new requests. This directive can be used to turn this behavior on or off on a per-server or per-directory basis. By default, compiling mod_usertrack will not activate cookies.


mod_vhost_alias - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_vhost_alias

Description: | Provides for dynamically configured mass virtual hosting
Status: | Extension
Module?dentifier: | vhost_alias_module
Source?ile: | mod_vhost_alias.c

Summary

This module creates dynamically configured virtual hosts, by allowing the IP address and/or the Host: header of the HTTP request to be used as part of the pathname to determine what files to serve. This allows for easy use of a huge number of virtual hosts with similar configurations.

Note

If mod_alias or mod_userdir are used for translating URIs to filenames, they will override the directives of mod_vhost_alias described below. For example, the following configuration will map /cgi-bin/script.pl to /usr/local/apache2/cgi-bin/script.pl in all cases:

ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/
VirtualScriptAlias /never/found/%0/cgi-bin/

See also

  • UseCanonicalName
  • Dynamically configured mass virtual hosting

Directory Name Interpolation

All the directives in this module interpolate a string into a pathname. The interpolated string (henceforth called the "name") may be either the server name (see the UseCanonicalName directive for details on how this is determined) or the IP address of the virtual host on the server in dotted-quad format. The interpolation is controlled by specifiers inspired by printf which have a number of formats:

%% | insert a %
%p | insert the port number of the virtual host
%N.M | insert (part of) the name

N and M are used to specify substrings of the name. N selects from the dot-separated components of the name, and M selects characters within whatever N has selected. M is optional and defaults to zero if it isn't present; the dot must be present if and only if M is present. The interpretation is as follows:

0 | the whole name
1 | the first part
2 | the second part
-1 | the last part
-2 | the penultimate part
2+ | the second and all subsequent parts
-2+ | the penultimate and all preceding parts
1+ and -1+ | the same as 0

If N or M is greater than the number of parts available a single underscore is interpolated.

Examples

For simple name-based virtual hosts you might use the following directives in your server configuration file:

UseCanonicalName Off
VirtualDocumentRoot /usr/local/apache/vhosts/%0

A request for http://www.example.com/directory/file.html will be satisfied by the file /usr/local/apache/vhosts/www.example.com/directory/file.html.

For a very large number of virtual hosts it is a good idea to arrange the files to reduce the size of the vhosts directory. To do this you might use the following in your configuration file:

UseCanonicalName Off
VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2

A request for http://www.domain.example.com/directory/file.html will be satisfied by the file /usr/local/apache/vhosts/example.com/d/o/m/domain/directory/file.html.

A more even spread of files can be achieved by hashing from the end of the name, for example:

VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2

The example request would come from /usr/local/apache/vhosts/example.com/n/i/a/domain/directory/file.html.

Alternatively you might use:

VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+

The example request would come from /usr/local/apache/vhosts/example.com/d/o/m/ain/directory/file.html.

For IP-based virtual hosting you might use the following in your configuration file:

UseCanonicalName DNS
VirtualDocumentRootIP /usr/local/apache/vhosts/%1/%2/%3/%4/docs
VirtualScriptAliasIP /usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin

A request for http://www.domain.example.com/directory/file.html would be satisfied by the file /usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html if the IP address of www.domain.example.com were 10.20.30.40. A request for http://www.domain.example.com/cgi-bin/script.pl would be satisfied by executing the program /usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl.

If you want to include the . character in a VirtualDocumentRoot directive, but it clashes with a % directive, you can work around the problem in the following way:

VirtualDocumentRoot /usr/local/apache/vhosts/%2.0.%3.0

A request for http://www.domain.example.com/directory/file.html will be satisfied by the file /usr/local/apache/vhosts/domain.example/directory/file.html.

The LogFormat directives %V and %A are useful in conjunction with this module.

VirtualDocumentRoot Directive

Description: | Dynamically configure the location of the document root for a given virtual host
Syntax: | VirtualDocumentRoot interpolated-directory|none
Default: | VirtualDocumentRoot none
Context: | server config, virtual host
Status: | Extension
Module: | mod_vhost_alias

The VirtualDocumentRoot directive allows you to determine where Apache will find your documents based on the value of the server name. The result of expanding interpolated-directory is used as the root of the document tree in a similar manner to the DocumentRoot directive's argument. If interpolated-directory is none then VirtualDocumentRoot is turned off. This directive cannot be used in the same context as VirtualDocumentRootIP.

VirtualDocumentRootIP Directive

Description: | Dynamically configure the location of the document root for a given virtual host
Syntax: | VirtualDocumentRootIP interpolated-directory|none
Default: | VirtualDocumentRootIP none
Context: | server config, virtual host
Status: | Extension
Module: | mod_vhost_alias

The VirtualDocumentRootIP directive is like the VirtualDocumentRoot directive, except that it uses the IP address of the server end of the connection for directory interpolation instead of the server name.

VirtualScriptAlias Directive

Description: | Dynamically configure the location of the CGI directory for a given virtual host
Syntax: | VirtualScriptAlias interpolated-directory|none
Default: | VirtualScriptAlias none
Context: | server config, virtual host
Status: | Extension
Module: | mod_vhost_alias

The VirtualScriptAlias directive allows you to determine where Apache will find CGI scripts in a similar manner to VirtualDocumentRoot does for other documents. It matches requests for URIs starting /cgi-bin/, much like ScriptAlias /cgi-bin/ would.

VirtualScriptAliasIP Directive

Description: | Dynamically configure the location of the cgi directory for a given virtual host
Syntax: | VirtualScriptAliasIP interpolated-directory|none
Default: | VirtualScriptAliasIP none
Context: | server config, virtual host
Status: | Extension
Module: | mod_vhost_alias

The VirtualScriptAliasIP directive is like the VirtualScriptAlias directive, except that it uses the IP address of the server end of the connection for directory interpolation instead of the server name.


Developer Documentation for Apache 2.0 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Developer Documentation for Apache 2.0

Many of the documents on these Developer pages are lifted from Apache 1.3's documentation. While they are all being updated to Apache 2.0, they are in different stages of progress. Please be patient, and point out any discrepancies or errors on the developer/ pages directly to the dev@httpd.apache.org mailing list.

Topics

  • Apache 1.3 API Notes
  • Apache 2.0 Hook Functions
  • Request Processing in Apache 2.0
  • How filters work in Apache 2.0
  • Converting Modules from Apache 1.3 to Apache 2.0
  • Debugging Memory Allocation in APR
  • Documenting Apache 2.0
  • Apache 2.0 Thread Safety Issues

External Resources

  • Tools provided by Ian Holsman:
    • Apache 2 cross reference
    • Autogenerated Apache 2 code documentation
  • Module Development Tutorials by Kevin O'Donnell
    • Integrating a module into the Apache build system
    • Handling configuration directives
  • Some notes on Apache module development by Ryan Bloom


Apache 1.3 API notes - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Apache 1.3 API notes

Warning

This document has not been updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

These are some notes on the Apache API and the data structures you have to deal with, etc. They are not yet nearly complete, but hopefully, they will help you get your bearings. Keep in mind that the API is still subject to change as we gain experience with it. (See the TODO file for what might be coming). However, it will be easy to adapt modules to any changes that are made. (We have more modules to adapt than you do).

A few notes on general pedagogical style here. In the interest of conciseness, all structure declarations here are incomplete -- the real ones have more slots that I'm not telling you about. For the most part, these are reserved to one component of the server core or another, and should be altered by modules with caution. However, in some cases, they really are things I just haven't gotten around to yet. Welcome to the bleeding edge.

Finally, here's an outline, to give you some bare idea of what's coming up, and in what order:

  • Basic concepts.
    • Handlers, Modules, and Requests
    • A brief tour of a module
  • How handlers work
    • A brief tour of the request_rec
    • Where request_rec structures come from
    • Handling requests, declining, and returning error codes
    • Special considerations for response handlers
    • Special considerations for authentication handlers
    • Special considerations for logging handlers
  • Resource allocation and resource pools
  • Configuration, commands and the like
    • Per-directory configuration structures
    • Command handling
    • Side notes --- per-server configuration, virtual servers, etc.

Basic concepts

We begin with an overview of the basic concepts behind the API, and how they are manifested in the code.

Handlers, Modules, and Requests

Apache breaks down request handling into a series of steps, more or less the same way the Netscape server API does (although this API has a few more stages than NetSite does, as hooks for stuff I thought might be useful in the future). These are:

  • URI -> Filename translation
  • Auth ID checking [is the user who they say they are?]
  • Auth access checking [is the user authorized here?]
  • Access checking other than auth
  • Determining MIME type of the object requested
  • `Fixups' -- there aren't any of these yet, but the phase is intended as a hook for possible extensions like SetEnv, which don't really fit well elsewhere.
  • Actually sending a response back to the client.
  • Logging the request

These phases are handled by looking at each of a succession of modules, looking to see if each of them has a handler for the phase, and attempting invoking it if so. The handler can typically do one of three things:

  • Handle the request, and indicate that it has done so by returning the magic constant OK.
  • Decline to handle the request, by returning the magic integer constant DECLINED. In this case, the server behaves in all respects as if the handler simply hadn't been there.
  • Signal an error, by returning one of the HTTP error codes. This terminates normal handling of the request, although an ErrorDocument may be invoked to try to mop up, and it will be logged in any case.

Most phases are terminated by the first module that handles them; however, for logging, `fixups', and non-access authentication checking, all handlers always run (barring an error). Also, the response phase is unique in that modules may declare multiple handlers for it, via a dispatch table keyed on the MIME type of the requested object. Modules may declare a response-phase handler which can handle any request, by giving it the key */* (i.e., a wildcard MIME type specification). However, wildcard handlers are only invoked if the server has already tried and failed to find a more specific response handler for the MIME type of the requested object (either none existed, or they all declined).

The handlers themselves are functions of one argument (a request_rec structure. vide infra), which returns an integer, as above.

A brief tour of a module

At this point, we need to explain the structure of a module. Our candidate will be one of the messier ones, the CGI module -- this handles both CGI scripts and the ScriptAlias config file command. It's actually a great deal more complicated than most modules, but if we're going to have only one example, it might as well be the one with its fingers in every place.

Let's begin with handlers. In order to handle the CGI scripts, the module declares a response handler for them. Because of ScriptAlias, it also has handlers for the name translation phase (to recognize ScriptAliased URIs), the type-checking phase (any ScriptAliased request is typed as a CGI script).

The module needs to maintain some per (virtual) server information, namely, the ScriptAliases in effect; the module structure therefore contains pointers to a functions which builds these structures, and to another which combines two of them (in case the main server and a virtual server both have ScriptAliases declared).

Finally, this module contains code to handle the ScriptAlias command itself. This particular module only declares one command, but there could be more, so modules have command tables which declare their commands, and describe where they are permitted, and how they are to be invoked.

A final note on the declared types of the arguments of some of these commands: a pool is a pointer to a resource pool structure; these are used by the server to keep track of the memory which has been allocated, files opened, etc., either to service a particular request, or to handle the process of configuring itself. That way, when the request is over (or, for the configuration pool, when the server is restarting), the memory can be freed, and the files closed, en masse, without anyone having to write explicit code to track them all down and dispose of them. Also, a cmd_parms structure contains various information about the config file being read, and other status information, which is sometimes of use to the function which processes a config-file command (such as ScriptAlias). With no further ado, the module itself:

        /* Declarations of handlers. */

int translate_scriptalias (request_rec *);
int type_scriptalias (request_rec *);
int cgi_handler (request_rec *);

/* Subsidiary dispatch table for response-phase
* handlers, by MIME type */

handler_rec cgi_handlers[] = {
{ "application/x-httpd-cgi", cgi_handler },
{ NULL }
};

/* Declarations of routines to manipulate the
* module's configuration info.  Note that these are
* returned, and passed in, as void *'s; the server
* core keeps track of them, but it doesn't, and can't,
* know their internal structure.
*/

void *make_cgi_server_config (pool *);
void *merge_cgi_server_config (pool *, void *, void *);

/* Declarations of routines to handle config-file commands */

extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
                                  char *real);

command_rec cgi_cmds[] = {
{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,
"a fakename and a realname"},
{ NULL }
};

module cgi_module = {

  STANDARD_MODULE_STUFF,
  NULL,                     /* initializer */
  NULL,                     /* dir config creator */
  NULL,                     /* dir merger */
  make_cgi_server_config,   /* server config */
  merge_cgi_server_config,  /* merge server config */
  cgi_cmds,                 /* command table */
  cgi_handlers,             /* handlers */
  translate_scriptalias,    /* filename translation */
  NULL,                     /* check_user_id */
  NULL,                     /* check auth */
  NULL,                     /* check access */
  type_scriptalias,         /* type_checker */
  NULL,                     /* fixups */
  NULL,                     /* logger */
  NULL                      /* header parser */
};

How handlers work

The sole argument to handlers is a request_rec structure. This structure describes a particular request which has been made to the server, on behalf of a client. In most cases, each connection to the client generates only one request_rec structure.

A brief tour of the request_rec

The request_rec contains pointers to a resource pool which will be cleared when the server is finished handling the request; to structures containing per-server and per-connection information, and most importantly, information on the request itself.

The most important such information is a small set of character strings describing attributes of the object being requested, including its URI, filename, content-type and content-encoding (these being filled in by the translation and type-check handlers which handle the request, respectively).

Other commonly used data items are tables giving the MIME headers on the client's original request, MIME headers to be sent back with the response (which modules can add to at will), and environment variables for any subprocesses which are spawned off in the course of servicing the request. These tables are manipulated using the ap_table_get and ap_table_set routines.

Note that the Content-type header value cannot be set by module content-handlers using the ap_table_*() routines. Rather, it is set by pointing the content_type field in the request_rec structure to an appropriate string. e.g.,

r->content_type = "text/html";

Finally, there are pointers to two data structures which, in turn, point to per-module configuration structures. Specifically, these hold pointers to the data structures which the module has built to describe the way it has been configured to operate in a given directory (via .htaccess files or <Directory> sections), for private data it has built in the course of servicing the request (so modules' handlers for one phase can pass `notes' to their handlers for other phases). There is another such configuration vector in the server_rec data structure pointed to by the request_rec, which contains per (virtual) server configuration data.

Here is an abridged declaration, giving the fields most commonly used:

struct request_rec {

pool *pool;
conn_rec *connection;
server_rec *server;

/* What object is being requested */

char *uri;
char *filename;
char *path_info;

char *args;           /* QUERY_ARGS, if any */
struct stat finfo;    /* Set by server core;
                       * st_mode set to zero if no such file */

char *content_type;
char *content_encoding;

/* MIME header environments, in and out. Also,
 * an array containing environment variables to
 * be passed to subprocesses, so people can write
 * modules to add to that environment.
 *
 * The difference between headers_out and
 * err_headers_out is that the latter are printed
 * even on error, and persist across internal
 * redirects (so the headers printed for
 * ErrorDocument handlers will have them).
 */

table *headers_in;
table *headers_out;
table *err_headers_out;
table *subprocess_env;

/* Info about the request itself... */

int header_only;     /* HEAD request, as opposed to GET */
char *protocol;      /* Protocol, as given to us, or HTTP/0.9 */
char *method;        /* GET, HEAD, POST, etc. */
int method_number;   /* M_GET, M_POST, etc. */

/* Info for logging */

char *the_request;
int bytes_sent;

/* A flag which modules can set, to indicate that
 * the data being returned is volatile, and clients
 * should be told not to cache it.
 */

int no_cache;

/* Various other config info which may change
 * with .htaccess files
 * These are config vectors, with one void*
 * pointer for each module (the thing pointed
 * to being the module's business).
 */

void *per_dir_config;   /* Options set in config files, etc. */
void *request_config;   /* Notes on *this* request */

};

Where request_rec structures come from

Most request_rec structures are built by reading an HTTP request from a client, and filling in the fields. However, there are a few exceptions:

  • If the request is to an imagemap, a type map (i.e., a *.var file), or a CGI script which returned a local `Location:', then the resource which the user requested is going to be ultimately located by some URI other than what the client originally supplied. In this case, the server does an internal redirect, constructing a new request_rec for the new URI, and processing it almost exactly as if the client had requested the new URI directly.
  • If some handler signaled an error, and an ErrorDocument is in scope, the same internal redirect machinery comes into play.

  • Finally, a handler occasionally needs to investigate `what would happen if' some other request were run. For instance, the directory indexing module needs to know what MIME type would be assigned to a request for each directory entry, in order to figure out what icon to use.

    Such handlers can construct a sub-request, using the functions ap_sub_req_lookup_file, ap_sub_req_lookup_uri, and ap_sub_req_method_uri; these construct a new request_rec structure and processes it as you would expect, up to but not including the point of actually sending a response. (These functions skip over the access checks if the sub-request is for a file in the same directory as the original request).

    (Server-side includes work by building sub-requests and then actually invoking the response handler for them, via the function ap_run_sub_req).

Handling requests, declining, and returning error codes

As discussed above, each handler, when invoked to handle a particular request_rec, has to return an int to indicate what happened. That can either be

  • OK -- the request was handled successfully. This may or may not terminate the phase.
  • DECLINED -- no erroneous condition exists, but the module declines to handle the phase; the server tries to find another.
  • an HTTP error code, which aborts handling of the request.

Note that if the error code returned is REDIRECT, then the module should put a Location in the request's headers_out, to indicate where the client should be redirected to.

Special considerations for response handlers

Handlers for most phases do their work by simply setting a few fields in the request_rec structure (or, in the case of access checkers, simply by returning the correct error code). However, response handlers have to actually send a request back to the client.

They should begin by sending an HTTP response header, using the function ap_send_http_header. (You don't have to do anything special to skip sending the header for HTTP/0.9 requests; the function figures out on its own that it shouldn't do anything). If the request is marked header_only, that's all they should do; they should return after that, without attempting any further output.

Otherwise, they should produce a request body which responds to the client as appropriate. The primitives for this are ap_rputc and ap_rprintf, for internally generated output, and ap_send_fd, to copy the contents of some FILE * straight to the client.

At this point, you should more or less understand the following piece of code, which is the handler which handles GET requests which have no more specific handler; it also shows how conditional GETs can be handled, if it's desirable to do so in a particular response handler -- ap_set_last_modified checks against the If-modified-since value supplied by the client, if any, and returns an appropriate code (which will, if nonzero, be USE_LOCAL_COPY). No similar considerations apply for ap_set_content_length, but it returns an error code for symmetry.

        int default_handler (request_rec *r)
{
int errstatus;
FILE *f;

if (r->method_number != M_GET) return DECLINED;
if (r->finfo.st_mode == 0) return NOT_FOUND;

if ((errstatus = ap_set_content_length (r, r->finfo.st_size))
||
             (errstatus = ap_set_last_modified (r, r->finfo.st_mtime)))
return errstatus;

f = fopen (r->filename, "r");

if (f == NULL) {
log_reason("file permissions deny server access", r->filename, r);
return FORBIDDEN;
}

register_timeout ("send", r);
ap_send_http_header (r);

if (!r->header_only) send_fd (f, r);
ap_pfclose (r->pool, f);
return OK;
}

Finally, if all of this is too much of a challenge, there are a few ways out of it. First off, as shown above, a response handler which has not yet produced any output can simply return an error code, in which case the server will automatically produce an error response. Secondly, it can punt to some other handler by invoking ap_internal_redirect, which is how the internal redirection machinery discussed above is invoked. A response handler which has internally redirected should always return OK.

(Invoking ap_internal_redirect from handlers which are not response handlers will lead to serious confusion).

Special considerations for authentication handlers

Stuff that should be discussed here in detail:

  • Authentication-phase handlers not invoked unless auth is configured for the directory.
  • Common auth configuration stored in the core per-dir configuration; it has accessors ap_auth_type, ap_auth_name, and ap_requires.
  • Common routines, to handle the protocol end of things, at least for HTTP basic authentication (ap_get_basic_auth_pw, which sets the connection->user structure field automatically, and ap_note_basic_auth_failure, which arranges for the proper WWW-Authenticate: header to be sent back).

Special considerations for logging handlers

When a request has internally redirected, there is the question of what to log. Apache handles this by bundling the entire chain of redirects into a list of request_rec structures which are threaded through the r->prev and r->next pointers. The request_rec which is passed to the logging handlers in such cases is the one which was originally built for the initial request from the client; note that the bytes_sent field will only be correct in the last request in the chain (the one for which a response was actually sent).

Resource allocation and resource pools

One of the problems of writing and designing a server-pool server is that of preventing leakage, that is, allocating resources (memory, open files, etc.), without subsequently releasing them. The resource pool machinery is designed to make it easy to prevent this from happening, by allowing resource to be allocated in such a way that they are automatically released when the server is done with them.

The way this works is as follows: the memory which is allocated, file opened, etc., to deal with a particular request are tied to a resource pool which is allocated for the request. The pool is a data structure which itself tracks the resources in question.

When the request has been processed, the pool is cleared. At that point, all the memory associated with it is released for reuse, all files associated with it are closed, and any other clean-up functions which are associated with the pool are run. When this is over, we can be confident that all the resource tied to the pool have been released, and that none of them have leaked.

Server restarts, and allocation of memory and resources for per-server configuration, are handled in a similar way. There is a configuration pool, which keeps track of resources which were allocated while reading the server configuration files, and handling the commands therein (for instance, the memory that was allocated for per-server module configuration, log files and other files that were opened, and so forth). When the server restarts, and has to reread the configuration files, the configuration pool is cleared, and so the memory and file descriptors which were taken up by reading them the last time are made available for reuse.

It should be noted that use of the pool machinery isn't generally obligatory, except for situations like logging handlers, where you really need to register cleanups to make sure that the log file gets closed when the server restarts (this is most easily done by using the function ap_pfopen, which also arranges for the underlying file descriptor to be closed before any child processes, such as for CGI scripts, are execed), or in case you are using the timeout machinery (which isn't yet even documented here). However, there are two benefits to using it: resources allocated to a pool never leak (even if you allocate a scratch string, and just forget about it); also, for memory allocation, ap_palloc is generally faster than malloc.

We begin here by describing how memory is allocated to pools, and then discuss how other resources are tracked by the resource pool machinery.

Allocation of memory in pools

Memory is allocated to pools by calling the function ap_palloc, which takes two arguments, one being a pointer to a resource pool structure, and the other being the amount of memory to allocate (in chars). Within handlers for handling requests, the most common way of getting a resource pool structure is by looking at the pool slot of the relevant request_rec; hence the repeated appearance of the following idiom in module code:

int my_handler(request_rec *r)
{
struct my_structure *foo;
...

foo = (foo *)ap_palloc (r->pool, sizeof(my_structure));
 }

Note that there is no ap_pfree -- ap_palloced memory is freed only when the associated resource pool is cleared. This means that ap_palloc does not have to do as much accounting as malloc(); all it does in the typical case is to round up the size, bump a pointer, and do a range check.

(It also raises the possibility that heavy use of ap_palloc could cause a server process to grow excessively large. There are two ways to deal with this, which are dealt with below; briefly, you can use malloc, and try to be sure that all of the memory gets explicitly freed, or you can allocate a sub-pool of the main pool, allocate your memory in the sub-pool, and clear it out periodically. The latter technique is discussed in the section on sub-pools below, and is used in the directory-indexing code, in order to avoid excessive storage allocation when listing directories with thousands of files).

Allocating initialized memory

There are functions which allocate initialized memory, and are frequently useful. The function ap_pcalloc has the same interface as ap_palloc, but clears out the memory it allocates before it returns it. The function ap_pstrdup takes a resource pool and a char * as arguments, and allocates memory for a copy of the string the pointer points to, returning a pointer to the copy. Finally ap_pstrcat is a varargs-style function, which takes a pointer to a resource pool, and at least two char * arguments, the last of which must be NULL. It allocates enough memory to fit copies of each of the strings, as a unit; for instance:

ap_pstrcat (r->pool, "foo", "/", "bar", NULL);

returns a pointer to 8 bytes worth of memory, initialized to "foo/bar".

Commonly-used pools in the Apache Web server

A pool is really defined by its lifetime more than anything else. There are some static pools in http_main which are passed to various non-http_main functions as arguments at opportune times. Here they are:

permanent_pool
never passed to anything else, this is the ancestor of all pools
pconf
  • subpool of permanent_pool
  • created at the beginning of a config "cycle"; exists until the server is terminated or restarts; passed to all config-time routines, either via cmd->pool, or as the "pool *p" argument on those which don't take pools
  • passed to the module init() functions
ptemp
  • sorry I lie, this pool isn't called this currently in 1.3, I renamed it this in my pthreads development. I'm referring to the use of ptrans in the parent... contrast this with the later definition of ptrans in the child.
  • subpool of permanent_pool
  • created at the beginning of a config "cycle"; exists until the end of config parsing; passed to config-time routines via cmd->temp_pool. Somewhat of a "bastard child" because it isn't available everywhere. Used for temporary scratch space which may be needed by some config routines but which is deleted at the end of config.
pchild
  • subpool of permanent_pool
  • created when a child is spawned (or a thread is created); lives until that child (thread) is destroyed
  • passed to the module child_init functions
  • destruction happens right after the child_exit functions are called... (which may explain why I think child_exit is redundant and unneeded)
ptrans
  • should be a subpool of pchild, but currently is a subpool of permanent_pool, see above
  • cleared by the child before going into the accept() loop to receive a connection
  • used as connection->pool
r->pool
  • for the main request this is a subpool of connection->pool; for subrequests it is a subpool of the parent request's pool.
  • exists until the end of the request (i.e., ap_destroy_sub_req, or in child_main after process_request has finished)
  • note that r itself is allocated from r->pool; i.e., r->pool is first created and then r is the first thing palloc()d from it

For almost everything folks do, r->pool is the pool to use. But you can see how other lifetimes, such as pchild, are useful to some modules... such as modules that need to open a database connection once per child, and wish to clean it up when the child dies.

You can also see how some bugs have manifested themself, such as setting connection->user to a value from r->pool -- in this case connection exists for the lifetime of ptrans, which is longer than r->pool (especially if r->pool is a subrequest!). So the correct thing to do is to allocate from connection->pool.

And there was another interesting bug in mod_include / mod_cgi. You'll see in those that they do this test to decide if they should use r->pool or r->main->pool. In this case the resource that they are registering for cleanup is a child process. If it were registered in r->pool, then the code would wait() for the child when the subrequest finishes. With mod_include this could be any old #include, and the delay can be up to 3 seconds... and happened quite frequently. Instead the subprocess is registered in r->main->pool which causes it to be cleaned up when the entire request is done -- i.e., after the output has been sent to the client and logging has happened.

Tracking open files, etc.

As indicated above, resource pools are also used to track other sorts of resources besides memory. The most common are open files. The routine which is typically used for this is ap_pfopen, which takes a resource pool and two strings as arguments; the strings are the same as the typical arguments to fopen, e.g.,

...
FILE *f = ap_pfopen (r->pool, r->filename, "r");

if (f == NULL) { ... } else { ... }

There is also a ap_popenf routine, which parallels the lower-level open system call. Both of these routines arrange for the file to be closed when the resource pool in question is cleared.

Unlike the case for memory, there are functions to close files allocated with ap_pfopen, and ap_popenf, namely ap_pfclose and ap_pclosef. (This is because, on many systems, the number of files which a single process can have open is quite limited). It is important to use these functions to close files allocated with ap_pfopen and ap_popenf, since to do otherwise could cause fatal errors on systems such as Linux, which react badly if the same FILE* is closed more than once.

(Using the close functions is not mandatory, since the file will eventually be closed regardless, but you should consider it in cases where your module is opening, or could open, a lot of files).

Other sorts of resources -- cleanup functions

More text goes here. Describe the the cleanup primitives in terms of which the file stuff is implemented; also, spawn_process.

Pool cleanups live until clear_pool() is called: clear_pool(a) recursively calls destroy_pool() on all subpools of a; then calls all the cleanups for a; then releases all the memory for a. destroy_pool(a) calls clear_pool(a) and then releases the pool structure itself. i.e., clear_pool(a) doesn't delete a, it just frees up all the resources and you can start using it again immediately.

Fine control -- creating and dealing with sub-pools, with a note on sub-requests

On rare occasions, too-free use of ap_palloc() and the associated primitives may result in undesirably profligate resource allocation. You can deal with such a case by creating a sub-pool, allocating within the sub-pool rather than the main pool, and clearing or destroying the sub-pool, which releases the resources which were associated with it. (This really is a rare situation; the only case in which it comes up in the standard module set is in case of listing directories, and then only with very large directories. Unnecessary use of the primitives discussed here can hair up your code quite a bit, with very little gain).

The primitive for creating a sub-pool is ap_make_sub_pool, which takes another pool (the parent pool) as an argument. When the main pool is cleared, the sub-pool will be destroyed. The sub-pool may also be cleared or destroyed at any time, by calling the functions ap_clear_pool and ap_destroy_pool, respectively. (The difference is that ap_clear_pool frees resources associated with the pool, while ap_destroy_pool also deallocates the pool itself. In the former case, you can allocate new resources within the pool, and clear it again, and so forth; in the latter case, it is simply gone).

One final note -- sub-requests have their own resource pools, which are sub-pools of the resource pool for the main request. The polite way to reclaim the resources associated with a sub request which you have allocated (using the ap_sub_req_... functions) is ap_destroy_sub_req, which frees the resource pool. Before calling this function, be sure to copy anything that you care about which might be allocated in the sub-request's resource pool into someplace a little less volatile (for instance, the filename in its request_rec structure).

(Again, under most circumstances, you shouldn't feel obliged to call this function; only 2K of memory or so are allocated for a typical sub request, and it will be freed anyway when the main request pool is cleared. It is only when you are allocating many, many sub-requests for a single main request that you should seriously consider the ap_destroy_... functions).

Configuration, commands and the like

One of the design goals for this server was to maintain external compatibility with the NCSA 1.3 server --- that is, to read the same configuration files, to process all the directives therein correctly, and in general to be a drop-in replacement for NCSA. On the other hand, another design goal was to move as much of the server's functionality into modules which have as little as possible to do with the monolithic server core. The only way to reconcile these goals is to move the handling of most commands from the central server into the modules.

However, just giving the modules command tables is not enough to divorce them completely from the server core. The server has to remember the commands in order to act on them later. That involves maintaining data which is private to the modules, and which can be either per-server, or per-directory. Most things are per-directory, including in particular access control and authorization information, but also information on how to determine file types from suffixes, which can be modified by AddType and DefaultType directives, and so forth. In general, the governing philosophy is that anything which can be made configurable by directory should be; per-server information is generally used in the standard set of modules for information like Aliases and Redirects which come into play before the request is tied to a particular place in the underlying file system.

Another requirement for emulating the NCSA server is being able to handle the per-directory configuration files, generally called .htaccess files, though even in the NCSA server they can contain directives which have nothing at all to do with access control. Accordingly, after URI -> filename translation, but before performing any other phase, the server walks down the directory hierarchy of the underlying filesystem, following the translated pathname, to read any .htaccess files which might be present. The information which is read in then has to be merged with the applicable information from the server's own config files (either from the <Directory> sections in access.conf, or from defaults in srm.conf, which actually behaves for most purposes almost exactly like <Directory />).

Finally, after having served a request which involved reading .htaccess files, we need to discard the storage allocated for handling them. That is solved the same way it is solved wherever else similar problems come up, by tying those structures to the per-transaction resource pool.

Per-directory configuration structures

Let's look out how all of this plays out in mod_mime.c, which defines the file typing handler which emulates the NCSA server's behavior of determining file types from suffixes. What we'll be looking at, here, is the code which implements the AddType and AddEncoding commands. These commands can appear in .htaccess files, so they must be handled in the module's private per-directory data, which in fact, consists of two separate tables for MIME types and encoding information, and is declared as follows:

typedef struct {
    table *forced_types;      /* Additional AddTyped stuff */
    table *encoding_types;    /* Added with AddEncoding... */
} mime_dir_config;

When the server is reading a configuration file, or <Directory> section, which includes one of the MIME module's commands, it needs to create a mime_dir_config structure, so those commands have something to act on. It does this by invoking the function it finds in the module's `create per-dir config slot', with two arguments: the name of the directory to which this configuration information applies (or NULL for srm.conf), and a pointer to a resource pool in which the allocation should happen.

(If we are reading a .htaccess file, that resource pool is the per-request resource pool for the request; otherwise it is a resource pool which is used for configuration data, and cleared on restarts. Either way, it is important for the structure being created to vanish when the pool is cleared, by registering a cleanup on the pool if necessary).

For the MIME module, the per-dir config creation function just ap_pallocs the structure above, and a creates a couple of tables to fill it. That looks like this:

void *create_mime_dir_config (pool *p, char *dummy)
{
mime_dir_config *new =
(mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config));
new->forced_types = ap_make_table (p, 4);
new->encoding_types = ap_make_table (p, 4);

return new;
 }

Now, suppose we've just read in a .htaccess file. We already have the per-directory configuration structure for the next directory up in the hierarchy. If the .htaccess file we just read in didn't have any AddType or AddEncoding commands, its per-directory config structure for the MIME module is still valid, and we can just use it. Otherwise, we need to merge the two structures somehow.

To do that, the server invokes the module's per-directory config merge function, if one is present. That function takes three arguments: the two structures being merged, and a resource pool in which to allocate the result. For the MIME module, all that needs to be done is overlay the tables from the new per-directory config structure with those from the parent:

void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
{
mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
mime_dir_config *subdir = (mime_dir_config *)subdirv;
mime_dir_config *new =
(mime_dir_config *)ap_palloc (p, sizeof(mime_dir_config));
new->forced_types = ap_overlay_tables (p, subdir->forced_types,
parent_dir->forced_types);
 new->encoding_types = ap_overlay_tables (p, subdir->encoding_types,
parent_dir->encoding_types);
return new;
 }

As a note -- if there is no per-directory merge function present, the server will just use the subdirectory's configuration info, and ignore the parent's. For some modules, that works just fine (e.g., for the includes module, whose per-directory configuration information consists solely of the state of the XBITHACK), and for those modules, you can just not declare one, and leave the corresponding structure slot in the module itself NULL.

Command handling

Now that we have these structures, we need to be able to figure out how to fill them. That involves processing the actual AddType and AddEncoding commands. To find commands, the server looks in the module's command table. That table contains information on how many arguments the commands take, and in what formats, where it is permitted, and so forth. That information is sufficient to allow the server to invoke most command-handling functions with pre-parsed arguments. Without further ado, let's look at the AddType command handler, which looks like this (the AddEncoding command looks basically the same, and won't be shown here):

char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)
{
if (*ext == '.') ++ext;
ap_table_set (m->forced_types, ext, ct);
return NULL;
 }

This command handler is unusually simple. As you can see, it takes four arguments, two of which are pre-parsed arguments, the third being the per-directory configuration structure for the module in question, and the fourth being a pointer to a cmd_parms structure. That structure contains a bunch of arguments which are frequently of use to some, but not all, commands, including a resource pool (from which memory can be allocated, and to which cleanups should be tied), and the (virtual) server being configured, from which the module's per-server configuration data can be obtained if required.

Another way in which this particular command handler is unusually simple is that there are no error conditions which it can encounter. If there were, it could return an error message instead of NULL; this causes an error to be printed out on the server's stderr, followed by a quick exit, if it is in the main config files; for a .htaccess file, the syntax error is logged in the server error log (along with an indication of where it came from), and the request is bounced with a server error response (HTTP error status, code 500).

The MIME module's command table has entries for these commands, which look like this:

command_rec mime_cmds[] = {
{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2,
"a mime type followed by a file extension" },
 { "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,
"an encoding (e.g., gzip), followed by a file extension" },
 { NULL }
 };

The entries in these tables are:

  • The name of the command
  • The function which handles it
  • a (void *) pointer, which is passed in the cmd_parms structure to the command handler --- this is useful in case many similar commands are handled by the same function.
  • A bit mask indicating where the command may appear. There are mask bits corresponding to each AllowOverride option, and an additional mask bit, RSRC_CONF, indicating that the command may appear in the server's own config files, but not in any .htaccess file.
  • A flag indicating how many arguments the command handler wants pre-parsed, and how they should be passed in. TAKE2 indicates two pre-parsed arguments. Other options are TAKE1, which indicates one pre-parsed argument, FLAG, which indicates that the argument should be On or Off, and is passed in as a boolean flag, RAW_ARGS, which causes the server to give the command the raw, unparsed arguments (everything but the command name itself). There is also ITERATE, which means that the handler looks the same as TAKE1, but that if multiple arguments are present, it should be called multiple times, and finally ITERATE2, which indicates that the command handler looks like a TAKE2, but if more arguments are present, then it should be called multiple times, holding the first argument constant.
  • Finally, we have a string which describes the arguments that should be present. If the arguments in the actual config file are not as required, this string will be used to help give a more specific error message. (You can safely leave this NULL).

Finally, having set this all up, we have to use it. This is ultimately done in the module's handlers, specifically for its file-typing handler, which looks more or less like this; note that the per-directory configuration structure is extracted from the request_rec's per-directory configuration vector by using the ap_get_module_config function.

        int find_ct(request_rec *r)
{
int i;
char *fn = ap_pstrdup (r->pool, r->filename);
mime_dir_config *conf = (mime_dir_config *)
ap_get_module_config(r->per_dir_config, &mime_module);
char *type;

if (S_ISDIR(r->finfo.st_mode)) {
r->content_type = DIR_MAGIC_TYPE;
return OK;
}

if((i=ap_rind(fn,'.')) < 0) return DECLINED;
++i;

if ((type = ap_table_get (conf->encoding_types, &fn[i])))
{
r->content_encoding = type;

/* go back to previous extension to try to use it as a type */
fn[i-1] = '\0';
if((i=ap_rind(fn,'.')) < 0) return OK;
++i;
}

if ((type = ap_table_get (conf->forced_types, &fn[i])))
{
r->content_type = type;
}

return OK;

        }

Side notes -- per-server configuration, virtual servers, etc.

The basic ideas behind per-server module configuration are basically the same as those for per-directory configuration; there is a creation function and a merge function, the latter being invoked where a virtual server has partially overridden the base server configuration, and a combined structure must be computed. (As with per-directory configuration, the default if no merge function is specified, and a module is configured in some virtual server, is that the base configuration is simply ignored).

The only substantial difference is that when a command needs to configure the per-server private module data, it needs to go to the cmd_parms data to get at it. Here's an example, from the alias module, which also indicates how a syntax error can be returned (note that the per-directory configuration argument to the command handler is declared as a dummy, since the module doesn't actually have per-directory config data):

char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
{
server_rec *s = cmd->server;
alias_server_conf *conf = (alias_server_conf *)
ap_get_module_config(s->module_config,&alias_module);
 alias_entry *new = ap_push_array (conf->redirects);

if (!ap_is_url (url)) return "Redirect to non-URL";

new->fake = f; new->real = url;
return NULL;
 }


Debugging Memory Allocation in APR - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Debugging Memory Allocation in APR

The allocation mechanism's within APR have a number of debugging modes that can be used to assist in finding memory problems. This document describes the modes available and gives instructions on activating them.

Available debugging options

Allocation Debugging - ALLOC_DEBUG

Debugging support: Define this to enable code which helps detect re-use of free()d memory and other such nonsense.

The theory is simple. The FILL_BYTE (0xa5) is written over all malloc'd memory as we receive it, and is written over everything that we free up during a clear_pool. We check that blocks on the free list always have the FILL_BYTE in them, and we check during palloc() that the bytes still have FILL_BYTE in them. If you ever see garbage URLs or whatnot containing lots of 0xa5s then you know something used data that's been freed or uninitialized.

Malloc Support - ALLOC_USE_MALLOC

If defined all allocations will be done with malloc() and free()d appropriately at the end.

This is intended to be used with something like Electric Fence or Purify to help detect memory problems. Note that if you're using efence then you should also add in ALLOC_DEBUG. But don't add in ALLOC_DEBUG if you're using Purify because ALLOC_DEBUG would hide all the uninitialized read errors that Purify can diagnose.

Pool Debugging - POOL_DEBUG

This is intended to detect cases where the wrong pool is used when assigning data to an object in another pool.

In particular, it causes the table_{set,add,merge}n routines to check that their arguments are safe for the apr_table_t they're being placed in. It currently only works with the unix multiprocess model, but could be extended to others.

Table Debugging - MAKE_TABLE_PROFILE

Provide diagnostic information about make_table() calls which are possibly too small.

This requires a recent gcc which supports __builtin_return_address(). The error_log output will be a message such as:

table_push: apr_table_t created by 0x804d874 hit limit of 10

Use l *0x804d874 to find the source that corresponds to. It indicates that a apr_table_t allocated by a call at that address has possibly too small an initial apr_table_t size guess.

Allocation Statistics - ALLOC_STATS

Provide some statistics on the cost of allocations.

This requires a bit of an understanding of how alloc.c works.

Allowable Combinations

Not all the options outlined above can be activated at the same time. the following table gives more information.

 | ALLOC DEBUG | ALLOC USE MALLOC | POOL DEBUG | MAKE TABLE PROFILE | ALLOC STATS
ALLOC DEBUG | - | No | Yes | Yes | Yes
ALLOC USE MALLOC | No | - | No | No | No
POOL DEBUG | Yes | No | - | Yes | Yes
MAKE TABLE PROFILE | Yes | No | Yes | - | Yes
ALLOC STATS | Yes | No | Yes | Yes | -

Additionally the debugging options are not suitable for multi-threaded versions of the server. When trying to debug with these options the server should be started in single process mode.

Activating Debugging Options

The various options for debugging memory are now enabled in the apr_general.h header file in APR. The various options are enabled by uncommenting the define for the option you wish to use. The section of the code currently looks like this (contained in srclib/apr/include/apr_pools.h)

/*
#define ALLOC_DEBUG
#define POOL_DEBUG
#define ALLOC_USE_MALLOC
#define MAKE_TABLE_PROFILE
#define ALLOC_STATS
*/

typedef struct ap_pool_t {
union block_hdr *first;
union block_hdr *last;
struct cleanup *cleanups;
struct process_chain *subprocesses;
struct ap_pool_t *sub_pools;
struct ap_pool_t *sub_next;
struct ap_pool_t *sub_prev;
struct ap_pool_t *parent;
char *free_first_avail;
 #ifdef ALLOC_USE_MALLOC
void *allocation_list;
 #endif
#ifdef POOL_DEBUG
struct ap_pool_t *joined;
 #endif
int (*apr_abort)(int retcode);
struct datastruct *prog_data;
 } ap_pool_t;

To enable allocation debugging simply move the #define ALLOC_DEBUG above the start of the comments block and rebuild the server.

Note

In order to use the various options the server must be rebuilt after editing the header file.


Documenting Apache 2.0 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Documenting Apache 2.0

Apache 2.0 uses Doxygen to document the APIs and global variables in the the code. This will explain the basics of how to document using Doxygen.

Brief Description

To start a documentation block, use /**
To end a documentation block, use */

In the middle of the block, there are multiple tags we can use:

Description of this functions purpose
@param parameter_name description
@return description
@deffunc signature of the function

The deffunc is not always necessary. DoxyGen does not have a full parser in it, so any prototype that use a macro in the return type declaration is too complex for scandoc. Those functions require a deffunc. An example (using &gt; rather than >):

/**
 * return the final element of the pathname
 * @param pathname The path to get the final element of
 * @return the final element of the path
 * @tip Examples:
 * <pre>
 * "/foo/bar/gum" -&gt; "gum"
 * "/foo/bar/gum/" -&gt; ""
 * "gum" -&gt; "gum"
 * "wi\\n32\\stuff" -&gt; "stuff"
 * </pre>
 * @deffunc const char * ap_filename_of_pathname(const char *pathname)
 */

At the top of the header file, always include:

/**
 * @package Name of library header
 */

Doxygen uses a new HTML file for each package. The HTML files are named {Name_of_library_header}.html, so try to be concise with your names.

For a further discussion of the possibilities please refer to the Doxygen site.


Apache 2.0 Hook Functions - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Apache 2.0 Hook Functions

Warning

This document is still in development and may be partially out of date.

In general, a hook function is one that Apache will call at some point during the processing of a request. Modules can provide functions that are called, and specify when they get called in comparison to other modules.

Creating a hook function

In order to create a new hook, four things need to be done:

Declare the hook function

Use the AP_DECLARE_HOOK macro, which needs to be given the return type of the hook function, the name of the hook, and the arguments. For example, if the hook returns an int and takes a request_rec * and an int and is called do_something, then declare it like this:

AP_DECLARE_HOOK(int, do_something, (request_rec *r, int n))

This should go in a header which modules will include if they want to use the hook.

Create the hook structure

Each source file that exports a hook has a private structure which is used to record the module functions that use the hook. This is declared as follows:

APR_HOOK_STRUCT(
APR_HOOK_LINK(do_something)
...
 )

Implement the hook caller

The source file that exports the hook has to implement a function that will call the hook. There are currently three possible ways to do this. In all cases, the calling function is called ap_run_hookname().

Void hooks

If the return value of a hook is void, then all the hooks are called, and the caller is implemented like this:

AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n), (r, n))

The second and third arguments are the dummy argument declaration and the dummy arguments as they will be used when calling the hook. In other words, this macro expands to something like this:

void ap_run_do_something(request_rec *r, int n)
{
...
do_something(r, n);
 }

Hooks that return a value

If the hook returns a value, then it can either be run until the first hook that does something interesting, like so:

AP_IMPLEMENT_HOOK_RUN_FIRST(int, do_something, (request_rec *r, int n), (r, n), DECLINED)

The first hook that does not return DECLINED stops the loop and its return value is returned from the hook caller. Note that DECLINED is the tradition Apache hook return meaning "I didn't do anything", but it can be whatever suits you.

Alternatively, all hooks can be run until an error occurs. This boils down to permitting two return values, one of which means "I did something, and it was OK" and the other meaning "I did nothing". The first function that returns a value other than one of those two stops the loop, and its return is the return value. Declare these like so:

AP_IMPLEMENT_HOOK_RUN_ALL(int, do_something, (request_rec *r, int n), (r, n), OK, DECLINED)

Again, OK and DECLINED are the traditional values. You can use what you want.

Call the hook callers

At appropriate moments in the code, call the hook caller, like so:

int n, ret;
request_rec *r;

ret=ap_run_do_something(r, n);

Hooking the hook

A module that wants a hook to be called needs to do two things.

Implement the hook function

Include the appropriate header, and define a static function of the correct type:

static int my_something_doer(request_rec *r, int n)
{
...
return OK;
 }

Add a hook registering function

During initialisation, Apache will call each modules hook registering function, which is included in the module structure:

static void my_register_hooks()
{
ap_hook_do_something(my_something_doer, NULL, NULL, HOOK_MIDDLE);
 }

mode MODULE_VAR_EXPORT my_module =
{
...
my_register_hooks /* register hooks */
 };

Controlling hook calling order

In the example above, we didn't use the three arguments in the hook registration function that control calling order. There are two mechanisms for doing this. The first, rather crude, method, allows us to specify roughly where the hook is run relative to other modules. The final argument control this. There are three possible values: HOOK_FIRST, HOOK_MIDDLE and HOOK_LAST.

All modules using any particular value may be run in any order relative to each other, but, of course, all modules using HOOK_FIRST will be run before HOOK_MIDDLE which are before HOOK_LAST. Modules that don't care when they are run should use HOOK_MIDDLE. (I spaced these out so people could do stuff like HOOK_FIRST-2 to get in slightly earlier, but is this wise? - Ben)

Note that there are two more values, HOOK_REALLY_FIRST and HOOK_REALLY_LAST. These should only be used by the hook exporter.

The other method allows finer control. When a module knows that it must be run before (or after) some other modules, it can specify them by name. The second (third) argument is a NULL-terminated array of strings consisting of the names of modules that must be run before (after) the current module. For example, suppose we want "mod_xyz.c" and "mod_abc.c" to run before we do, then we'd hook as follows:

static void register_hooks()
{
static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL };

ap_hook_do_something(my_something_doer, aszPre, NULL, HOOK_MIDDLE);
 }

Note that the sort used to achieve this is stable, so ordering set by HOOK_ORDER is preserved, as far as is possible.

Ben Laurie, 15th August 1999


モジュールの Apache 1.3 から Apache 2.0 への移植 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > Developer Documentation

モジュールの Apache 1.3 から Apache 2.0 への移植

この文書は mod_mmap_static モジュールを Apache 2.0 用に移植した時に 学んだ経験をもとに書いた、最初の手引き書です。まだまだ完全じゃないし、 ひょっとすると間違っている部分もあるかもしれませんが、 取っ掛りにはなるでしょう。

簡単な変更点

クリーンナップ ルーチン

クリーンナップルーチンは apr_status_t 型である必要があります。 そして、apr_status_t 型の値を返さなくてはなりません。 クリーンナップ中のエラーを通知する必要がなければ、返り値は普通、 ARP_SUCCESS です。たとえエラーを通知したとしても、 すべてのコードがその通知をチェックしたり、 エラーに応じた動作をするわけではないことに気をつけてください。

初期化ルーチン

初期化ルーチンは処理全体から見てしっくりくるような意味を表すように、 名前が変更されました。ですから、mmap_init から mmap_post_config のようにちょっと変更されました。 渡される引数は大幅に変更され、次のようになりました。

  • apr_pool_t *p
  • apr_pool_t *plog
  • apr_pool_t *ptemp
  • server_rec *s

データ型

データ型のほとんどは APR に移されました。つまり、 いくつかの名前が前述のように変更されています。 施すべき変更点の簡単な一覧を以下に示します。

  • pool becomes apr_pool_t
  • table becomes apr_table_t

もっと厄介な変更点…

フックの登録

新しいアーキテクチャでは作成した関数を呼び出すのに 一連のフックを使用します。このフックは、新しい関数 static void register_hooks(void) を使って登録するよう、 モジュールに書き足さなくてはなりません。 この関数は、なにをすべきか一旦理解してしまえば、 十分にわかりやすいものです。 リクエストの処理のあるステージで呼び出さなくてはならない 関数は登録する必要があります。ハンドラは登録する必要はありません。 関数を登録できるフェーズはたくさんあります。 それぞれのフェーズで、関数を呼び出す相対的な順番は、 かなりの程度制御できます。

以下は、mod_mmap_static に追加したコードです:

static void register_hooks(void)
{
    static const char * const aszPre[]={ "http_core.c",NULL };
    ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE);
    ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST);
};

ここでは呼びだすべき二つの関数を登録しています。一つは post_config ステージ用 (ほとんどすべてのモジュール はこれが必要です) で、もう一つは translate_name フェーズ用です。 それぞれの関数は名前は違うけれども形式は同じであることに注意してください。 それでは、形式はどのようになっているでしょうか?

ap_hook_phase_name(function_name, predecessors, successors, position);

三つの位置が定義されています…

  • HOOK_FIRST
  • HOOK_MIDDLE
  • HOOK_LAST

位置を定義するには、上記の「位置」を指定し、 修飾子である「先行」と「後行」で手を加えます。 「先行」「後行」は、呼ばれるべき関数のリストです。 「先行」は関数の実行前に呼ばれるもので、 「後行」は実行後に呼ばれるものです。

mod_mmap_static の場合、post_config ステージでは必要ありませんが、 mmap_static_xlat が core モジュールが名前の変換を実行した後に 呼ばれなければなりません。 そこで aszPre を使って HOOK_LAST の修飾子を定義しています。

モジュールの定義

モジュールの定義を作成する際に注意しなければならない ステージの数は激減しています。古い定義は次のようになっていました。

module MODULE_VAR_EXPORT module_name_module =
{
    STANDARD_MODULE_STUFF,
    /* initializer */
    /* dir config creater */
    /* dir merger --- default is to override */
    /* server config */
    /* merge server config */
    /* command handlers */
    /* handlers */
    /* filename translation */
    /* check_user_id */
    /* check auth */
    /* check access */
    /* type_checker */
    /* fixups */
    /* logger */
    /* header parser */
    /* child_init */
    /* child_exit */
    /* post read-request */
};

新しい構造体はとってもシンプルです…

module MODULE_VAR_EXPORT module_name_module =
{
    STANDARD20_MODULE_STUFF,
    /* create per-directory config structures */
    /* merge per-directory config structures  */
    /* create per-server config structures    */
    /* merge per-server config structures     */
    /* command handlers */
    /* handlers */
    /* register hooks */
};

このうちのいくつかは古いものから新しいものに直接読み替えられるもので、 いくつかはそうではありません。どうすればいいのかを要約してみます。

直接読み替えられるステージ:

/* ディレクトリ設定作成関数 */
/* ディレクトリ毎設定構造体作成 */
/* サーバ設定作成関数 */
/* サーバ毎設定構造体作成 */
/* ディレクトリ設定マージ関数 */
/* ディレクトリ毎設定構造体マージ */
/* サーバ設定マージ関数 */
/* サーバ毎設定構造体作成マージ */
/* コマンド・テーブル */
/* コマンド apr_table_t */
/* ハンドラ */
/* ハンドラ */

古い関数の残りのものはフックとして登録されるべきです。 現時点で次のようなフック・ステージが定義されています…

ap_hook_post_config
(以前の _init ルーチンが登録されるべき場所です)
ap_hook_http_method
(リクエストから HTTP メソッドを取得します (互換用))
ap_hook_open_logs
(特定のログのオープン)
ap_hook_auth_checker
(リソースが権限を必要とするかどうかの確認)
ap_hook_access_checker
(モジュール固有の制約の確認)
ap_hook_check_user_id
(ユーザ ID とパスワードの確認)
ap_hook_default_port
(サーバのデフォルト・ポートの取得)
ap_hook_pre_connection
(処理の直前に必要なことを実行。ただし accept 直後に呼ばれる)
ap_hook_process_connection
(プロトコルの処理)
ap_hook_child_init
(子プロセル起動直後)
ap_hook_create_request
(??)
ap_hook_fixups
(応答内容の生成を変更するラスト・チャンス)
ap_hook_handler
(応答内容の生成)
ap_hook_header_parser
(モジュールにヘッダの照会をさせる。ほとんどのモジュールでは使われません。post_read_request を使います)
ap_hook_insert_filter
(フィルタ・チェインにフィルタを挿入)
ap_hook_log_transaction
(リクエストについての情報を記録する)
ap_hook_optional_fn_retrieve
(オプションとして登録された関数の取得)
ap_hook_post_read_request
(リクエストを読みこんだ後、他のフェーズの前に呼ばれる)
ap_hook_quick_handler
リクエストの処理が始まる前に呼ばれる。キャッシュモジュールが 使用している
ap_hook_translate_name
(URI をファイル名に変換する)
ap_hook_type_checker
(文書型の決定と設定。あるいはその片方)


Request Processing in Apache 2.0 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Request Processing in Apache 2.0

Warning

Warning - this is a first (fast) draft that needs further revision!

Several changes in Apache 2.0 affect the internal request processing mechanics. Module authors need to be aware of these changes so they may take advantage of the optimizations and security enhancements.

The first major change is to the subrequest and redirect mechanisms. There were a number of different code paths in Apache 1.3 to attempt to optimize subrequest or redirect behavior. As patches were introduced to 2.0, these optimizations (and the server behavior) were quickly broken due to this duplication of code. All duplicate code has been folded back into ap_process_internal_request() to prevent the code from falling out of sync again.

This means that much of the existing code was 'unoptimized'. It is the Apache HTTP Project's first goal to create a robust and correct implementation of the HTTP server RFC. Additional goals include security, scalability and optimization. New methods were sought to optimize the server (beyond the performance of Apache 1.3) without introducing fragile or insecure code.

The Request Processing Cycle

All requests pass through ap_process_request_internal() in request.c, including subrequests and redirects. If a module doesn't pass generated requests through this code, the author is cautioned that the module may be broken by future changes to request processing.

To streamline requests, the module author can take advantage of the hooks offered to drop out of the request cycle early, or to bypass core Apache hooks which are irrelevant (and costly in terms of CPU.)

The Request Parsing Phase

Unescapes the URL

The request's parsed_uri path is unescaped, once and only once, at the beginning of internal request processing.

This step is bypassed if the proxyreq flag is set, or the parsed_uri.path element is unset. The module has no further control of this one-time unescape operation, either failing to unescape or multiply unescaping the URL leads to security reprecussions.

Strips Parent and This Elements from the URI

All /../ and /./ elements are removed by ap_getparents(). This helps to ensure the path is (nearly) absolute before the request processing continues.

This step cannot be bypassed.

Initial URI Location Walk

Every request is subject to an ap_location_walk() call. This ensures that <Location> sections are consistently enforced for all requests. If the request is an internal redirect or a sub-request, it may borrow some or all of the processing from the previous or parent request's ap_location_walk, so this step is generally very efficient after processing the main request.

translate_name

Modules can determine the file name, or alter the given URI in this step. For example, mod_vhost_alias will translate the URI's path into the configured virtual host, mod_alias will translate the path to an alias path, and if the request falls back on the core, the DocumentRoot is prepended to the request resource.

If all modules DECLINE this phase, an error 500 is returned to the browser, and a "couldn't translate name" error is logged automatically.

Hook: map_to_storage

After the file or correct URI was determined, the appropriate per-dir configurations are merged together. For example, mod_proxy compares and merges the appropriate <Proxy> sections. If the URI is nothing more than a local (non-proxy) TRACE request, the core handles the request and returns DONE. If no module answers this hook with OK or DONE, the core will run the request filename against the <Directory> and <Files> sections. If the request 'filename' isn't an absolute, legal filename, a note is set for later termination.

URI Location Walk

Every request is hardened by a second ap_location_walk() call. This reassures that a translated request is still subjected to the configured <Location> sections. The request again borrows some or all of the processing from its previous location_walk above, so this step is almost always very efficient unless the translated URI mapped to a substantially different path or Virtual Host.

Hook: header_parser

The main request then parses the client's headers. This prepares the remaining request processing steps to better serve the client's request.

The Security Phase

Needs Documentation. Code is:

switch (ap_satisfies(r)) {
case SATISFY_ALL:
case SATISFY_NOSPEC:
    if ((access_status = ap_run_access_checker(r)) != 0) {
        return decl_die(access_status, "check access", r);
    }

    if (ap_some_auth_required(r)) {
        if (((access_status = ap_run_check_user_id(r)) != 0)
            || !ap_auth_type(r)) {
            return decl_die(access_status, ap_auth_type(r)
                          ? "check user.  No user file?"
                          : "perform authentication. AuthType not set!",
                          r);
        }

        if (((access_status = ap_run_auth_checker(r)) != 0)
            || !ap_auth_type(r)) {
            return decl_die(access_status, ap_auth_type(r)
                          ? "check access.  No groups file?"
                          : "perform authentication. AuthType not set!",
                          r);
        }
    }
    break;

case SATISFY_ANY:
    if (((access_status = ap_run_access_checker(r)) != 0)) {
        if (!ap_some_auth_required(r)) {
            return decl_die(access_status, "check access", r);
        }

        if (((access_status = ap_run_check_user_id(r)) != 0)
            || !ap_auth_type(r)) {
            return decl_die(access_status, ap_auth_type(r)
                          ? "check user.  No user file?"
                          : "perform authentication. AuthType not set!",
                          r);
        }

        if (((access_status = ap_run_auth_checker(r)) != 0)
            || !ap_auth_type(r)) {
            return decl_die(access_status, ap_auth_type(r)
                          ? "check access.  No groups file?"
                          : "perform authentication. AuthType not set!",
                          r);
        }
    }
    break;
}

The Preparation Phase

Hook: type_checker

The modules have an opportunity to test the URI or filename against the target resource, and set mime information for the request. Both mod_mime and mod_mime_magic use this phase to compare the file name or contents against the administrator's configuration and set the content type, language, character set and request handler. Some modules may set up their filters or other request handling parameters at this time.

If all modules DECLINE this phase, an error 500 is returned to the browser, and a "couldn't find types" error is logged automatically.

Hook: fixups

Many modules are 'trounced' by some phase above. The fixups phase is used by modules to 'reassert' their ownership or force the request's fields to their appropriate values. It isn't always the cleanest mechanism, but occasionally it's the only option.

The Handler Phase

This phase is not part of the processing in ap_process_request_internal(). Many modules prepare one or more subrequests prior to creating any content at all. After the core, or a module calls ap_process_request_internal() it then calls ap_invoke_handler() to generate the request.

Hook: insert_filter

Modules that transform the content in some way can insert their values and override existing filters, such that if the user configured a more advanced filter out-of-order, then the module can move its order as need be. There is no result code, so actions in this hook better be trusted to always succeed.

Hook: handler

The module finally has a chance to serve the request in its handler hook. Note that not every prepared request is sent to the handler hook. Many modules, such as mod_autoindex, will create subrequests for a given URI, and then never serve the subrequest, but simply lists it for the user. Remember not to put required teardown from the hooks above into this module, but register pool cleanups against the request pool to free resources as required.


How filters work in Apache 2.0 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

How filters work in Apache 2.0

Warning

This is a cut 'n paste job from an email (<022501c1c529$f63a9550$7f00000a@KOJ>) and only reformatted for better readability. It's not up to date but may be a good start for further research.

Filter Types

There are three basic filter types (each of these is actually broken down into two categories, but that comes later).

CONNECTION
Filters of this type are valid for the lifetime of this connection. (AP_FTYPE_CONNECTION, AP_FTYPE_NETWORK)
PROTOCOL
Filters of this type are valid for the lifetime of this request from the point of view of the client, this means that the request is valid from the time that the request is sent until the time that the response is received. (AP_FTYPE_PROTOCOL, AP_FTYPE_TRANSCODE)
RESOURCE
Filters of this type are valid for the time that this content is used to satisfy a request. For simple requests, this is identical to PROTOCOL, but internal redirects and sub-requests can change the content without ending the request. (AP_FTYPE_RESOURCE, AP_FTYPE_CONTENT_SET)

It is important to make the distinction between a protocol and a resource filter. A resource filter is tied to a specific resource, it may also be tied to header information, but the main binding is to a resource. If you are writing a filter and you want to know if it is resource or protocol, the correct question to ask is: "Can this filter be removed if the request is redirected to a different resource?" If the answer is yes, then it is a resource filter. If it is no, then it is most likely a protocol or connection filter. I won't go into connection filters, because they seem to be well understood. With this definition, a few examples might help:

Byterange
We have coded it to be inserted for all requests, and it is removed if not used. Because this filter is active at the beginning of all requests, it can not be removed if it is redirected, so this is a protocol filter.
http_header
This filter actually writes the headers to the network. This is obviously a required filter (except in the asis case which is special and will be dealt with below) and so it is a protocol filter.
Deflate
The administrator configures this filter based on which file has been requested. If we do an internal redirect from an autoindex page to an index.html page, the deflate filter may be added or removed based on config, so this is a resource filter.

The further breakdown of each category into two more filter types is strictly for ordering. We could remove it, and only allow for one filter type, but the order would tend to be wrong, and we would need to hack things to make it work. Currently, the RESOURCE filters only have one filter type, but that should change.

How are filters inserted?

This is actually rather simple in theory, but the code is complex. First of all, it is important that everybody realize that there are three filter lists for each request, but they are all concatenated together. So, the first list is r->output_filters, then r->proto_output_filters, and finally r->connection->output_filters. These correspond to the RESOURCE, PROTOCOL, and CONNECTION filters respectively. The problem previously, was that we used a singly linked list to create the filter stack, and we started from the "correct" location. This means that if I had a RESOURCE filter on the stack, and I added a CONNECTION filter, the CONNECTION filter would be ignored. This should make sense, because we would insert the connection filter at the top of the c->output_filters list, but the end of r->output_filters pointed to the filter that used to be at the front of c->output_filters. This is obviously wrong. The new insertion code uses a doubly linked list. This has the advantage that we never lose a filter that has been inserted. Unfortunately, it comes with a separate set of headaches.

The problem is that we have two different cases were we use subrequests. The first is to insert more data into a response. The second is to replace the existing response with an internal redirect. These are two different cases and need to be treated as such.

In the first case, we are creating the subrequest from within a handler or filter. This means that the next filter should be passed to make_sub_request function, and the last resource filter in the sub-request will point to the next filter in the main request. This makes sense, because the sub-request's data needs to flow through the same set of filters as the main request. A graphical representation might help:

Default_handler --> includes_filter --> byterange --> ...

If the includes filter creates a sub request, then we don't want the data from that sub-request to go through the includes filter, because it might not be SSI data. So, the subrequest adds the following:

Default_handler --> includes_filter -/-> byterange --> ...
                                    /
Default_handler --> sub_request_core

What happens if the subrequest is SSI data? Well, that's easy, the includes_filter is a resource filter, so it will be added to the sub request in between the Default_handler and the sub_request_core filter.

The second case for sub-requests is when one sub-request is going to become the real request. This happens whenever a sub-request is created outside of a handler or filter, and NULL is passed as the next filter to the make_sub_request function.

In this case, the resource filters no longer make sense for the new request, because the resource has changed. So, instead of starting from scratch, we simply point the front of the resource filters for the sub-request to the front of the protocol filters for the old request. This means that we won't lose any of the protocol filters, neither will we try to send this data through a filter that shouldn't see it.

The problem is that we are using a doubly-linked list for our filter stacks now. But, you should notice that it is possible for two lists to intersect in this model. So, you do you handle the previous pointer? This is a very difficult question to answer, because there is no "right" answer, either method is equally valid. I looked at why we use the previous pointer. The only reason for it is to allow for easier addition of new servers. With that being said, the solution I chose was to make the previous pointer always stay on the original request.

This causes some more complex logic, but it works for all cases. My concern in having it move to the sub-request, is that for the more common case (where a sub-request is used to add data to a response), the main filter chain would be wrong. That didn't seem like a good idea to me.

Asis

The final topic. :-) Mod_Asis is a bit of a hack, but the handler needs to remove all filters except for connection filters, and send the data. If you are using mod_asis, all other bets are off.

Explanations

The absolutely last point is that the reason this code was so hard to get right, was because we had hacked so much to force it to work. I wrote most of the hacks originally, so I am very much to blame. However, now that the code is right, I have started to remove some hacks. Most people should have seen that the reset_filters and add_required_filters functions are gone. Those inserted protocol level filters for error conditions, in fact, both functions did the same thing, one after the other, it was really strange. Because we don't lose protocol filters for error cases any more, those hacks went away. The HTTP_HEADER, Content-length, and Byterange filters are all added in the insert_filters phase, because if they were added earlier, we had some interesting interactions. Now, those could all be moved to be inserted with the HTTP_IN, CORE, and CORE_IN filters. That would make the code easier to follow.


Glossary - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Glossary

This glossary defines some of the common terminology related to Apache in particular, and web serving in general. More information on each concept is provided in the links.

Definitions

Authentication
The positive identification of a network entity such as a server, a client, or a user.
See: Authentication, Authorization, and Access Control
Access Control
The restriction of access to network realms. In an Apache context usually the restriction of access to certain URLs.
See: Authentication, Authorization, and Access Control
Algorithm
An unambiguous formula or set of rules for solving a problem in a finite number of steps. Algorithms for encryption are usually called Ciphers.
APache eXtension Tool (apxs)
A perl script that aids in compiling module sources into Dynamic Shared Objects (DSOs) and helps install them in the Apache Web server.
See: Manual Page: apxs
Certificate
A data record used for authenticating network entities such as a server or a client. A certificate contains X.509 information pieces about its owner (called the subject) and the signing Certification Authority (called the issuer), plus the owner's public key and the signature made by the CA. Network entities verify these signatures using CA certificates.
See: SSL/TLS Encryption
Certification Authority (CA)
A trusted third party whose purpose is to sign certificates for network entities it has authenticated using secure means. Other network entities can check the signature to verify that a CA has authenticated the bearer of a certificate.
See: SSL/TLS Encryption
Certificate Signing Request (CSR)
An unsigned certificate for submission to a Certification Authority, which signs it with the Private Key of their CA Certificate. Once the CSR is signed, it becomes a real certificate.
See: SSL/TLS Encryption
Cipher
An algorithm or system for data encryption. Examples are DES, IDEA, RC4, etc.
See: SSL/TLS Encryption
Ciphertext
The result after Plaintext is passed through a Cipher.
See: SSL/TLS Encryption
Common Gateway Interface (CGI)
A standard definition for an interface between a web server and an external program that allows the external program to service requests. The interface was originally defined by NCSA but there is also an RFC project.
See: Dynamic Content with CGI
Configuration Directive
See: Directive
Configuration File
A text file containing Directives that control the configuration of Apache.
See: Configuration Files
CONNECT
An HTTP method for proxying raw data channels over HTTP. It can be used to encapsulate other protocols, such as the SSL protocol.
Context
An area in the configuration files where certain types of directives are allowed.
See: Terms Used to Describe Apache Directives
Digital Signature
An encrypted text block that validates a certificate or other file. A Certification Authority creates a signature by generating a hash of the Public Key embedded in a Certificate, then encrypting the hash with its own Private Key. Only the CA's public key can decrypt the signature, verifying that the CA has authenticated the network entity that owns the Certificate.
See: SSL/TLS Encryption
Directive
A configuration command that controls one or more aspects of Apache's behavior. Directives are placed in the Configuration File
See: Directive Index
Dynamic Shared Object (DSO)
Modules compiled separately from the Apache httpd binary that can be loaded on-demand.
See: Dynamic Shared Object Support
Environment Variable (env-variable)
Named variables managed by the operating system shell and used to store information and communicate between programs. Apache also contains internal variables that are referred to as environment variables, but are stored in internal Apache structures, rather than in the shell environment.
See: Environment Variables in Apache
Export-Crippled
Diminished in cryptographic strength (and security) in order to comply with the United States' Export Administration Regulations (EAR). Export-crippled cryptographic software is limited to a small key size, resulting in Ciphertext which usually can be decrypted by brute force.
See: SSL/TLS Encryption
Filter
A process that is applied to data that is sent or received by the server. Input filters process data sent by the client to the server, while output filters process documents on the server before they are sent to the client. For example, the INCLUDES output filter processes documents for Server Side Includes.
See: Filters
Fully-Qualified Domain-Name (FQDN)
The unique name of a network entity, consisting of a hostname and a domain name that can resolve to an IP address. For example, www is a hostname, example.com is a domain name, and www.example.com is a fully-qualified domain name.
Handler
An internal Apache representation of the action to be performed when a file is called. Generally, files have implicit handlers, based on the file type. Normally, all files are simply served by the server, but certain file types are "handled" separately. For example, the cgi-script handler designates files to be processed as CGIs.
See: Apache's Handler Use
Header
The part of the HTTP request and response that is sent before the actual content, and that contains meta-information describing the content.
.htaccess
A configuration file that is placed inside the web tree and applies configuration directives to the directory where it is placed and all sub-directories. Despite its name, this file can hold almost any type of directive, not just access-control directives.
See: Configuration Files
httpd.conf
The main Apache configuration file. The default location is /usr/local/apache2/conf/httpd.conf, but it may be moved using run-time or compile-time configuration.
See: Configuration Files
HyperText Transfer Protocol (HTTP)
The standard transmission protocol used on the World Wide Web. Apache implements version 1.1 of the protocol, referred to as HTTP/1.1 and defined by RFC 2616.
HTTPS
The HyperText Transfer Protocol (Secure), the standard encrypted communication mechanism on the World Wide Web. This is actually just HTTP over SSL.
See: SSL/TLS Encryption
Method
In the context of HTTP, an action to perform on a resource, specified on the request line by the client. Some of the methods available in HTTP are GET, POST, and PUT.
Message Digest
A hash of a message, which can be used to verify that the contents of the message have not been altered in transit.
See: SSL/TLS Encryption
MIME-type
A way to describe the kind of document being transmitted. Its name comes from that fact that its format is borrowed from the Multipurpose Internet Mail Extensions. It consists of a major type and a minor type, separated by a slash. Some examples are text/html, image/gif, and application/octet-stream. In HTTP, the MIME-type is transmitted in the Content-Type header.
See: mod_mime
Module
An independent part of a program. Much of Apache's functionality is contained in modules that you can choose to include or exclude. Modules that are compiled into the Apache httpd binary are called static modules, while modules that are stored separately and can be optionally loaded at run-time are called dynamic modules or DSOs. Modules that are included by default are called base modules. Many modules are available for Apache that are not distributed as part of the Apache HTTP Server tarball. These are referred to as third-party modules.
See: Module Index
Module Magic Number (MMN)
Module Magic Number is a constant defined in the Apache source code that is associated with binary compatibility of modules. It is changed when internal Apache structures, function calls and other significant parts of API change in such a way that binary compatibility cannot be guaranteed any more. On MMN change, all third party modules have to be at least recompiled, sometimes even slightly changed in order to work with the new version of Apache.
OpenSSL
The Open Source toolkit for SSL/TLS
see http://www.openssl.org/
Pass Phrase
The word or phrase that protects private key files. It prevents unauthorized users from encrypting them. Usually it's just the secret encryption/decryption key used for Ciphers.
See: SSL/TLS Encryption
Plaintext
The unencrypted text.
Private Key
The secret key in a Public Key Cryptography system, used to decrypt incoming messages and sign outgoing ones.
See: SSL/TLS Encryption
Proxy
An intermediate server that sits between the client and the origin server. It accepts requests from clients, transmits those requests on to the origin server, and then returns the response from the origin server to the client. If several clients request the same content, the proxy can deliver that content from its cache, rather than requesting it from the origin server each time, thereby reducing response time.
See: mod_proxy
Public Key
The publicly available key in a Public Key Cryptography system, used to encrypt messages bound for its owner and to decrypt signatures made by its owner.
See: SSL/TLS Encryption
Public Key Cryptography
The study and application of asymmetric encryption systems, which use one key for encryption and another for decryption. A corresponding pair of such keys constitutes a key pair. Also called Asymmetric Cryptography.
See: SSL/TLS Encryption
Regular Expression (Regex)
A way of describing a pattern in text - for example, "all the words that begin with the letter A" or "every 10-digit phone number" or even "Every sentence with two commas in it, and no capital letter Q". Regular expressions are useful in Apache because they let you apply certain attributes against collections of files or resources in very flexible ways - for example, all .gif and .jpg files under any "images" directory could be written as "/images/.*(jpg|gif)$". Apache uses Perl Compatible Regular Expressions provided by the PCRE library.
Reverse Proxy
A proxy server that appears to the client as if it is an origin server. This is useful to hide the real origin server from the client for security reasons, or to load balance.
Secure Sockets Layer (SSL)
A protocol created by Netscape Communications Corporation for general communication authentication and encryption over TCP/IP networks. The most popular usage is HTTPS, i.e. the HyperText Transfer Protocol (HTTP) over SSL.
See: SSL/TLS Encryption
Server Side Includes (SSI)
A technique for embedding processing directives inside HTML files.
See: Introduction to Server Side Includes
Session
The context information of a communication in general.
SSLeay
The original SSL/TLS implementation library developed by Eric A. Young
Symmetric Cryptography
The study and application of Ciphers that use a single secret key for both encryption and decryption operations.
See: SSL/TLS Encryption
Tarball
A package of files gathered together using the tar utility. Apache distributions are stored in compressed tar archives or using pkzip.
Transport Layer Security (TLS)
The successor protocol to SSL, created by the Internet Engineering Task Force (IETF) for general communication authentication and encryption over TCP/IP networks. TLS version 1 and is nearly identical with SSL version 3.
See: SSL/TLS Encryption
Uniform Resource Locator (URL)
The name/address of a resource on the Internet. This is the common informal term for what is formally called a Uniform Resource Identifier. URLs are usually made up of a scheme, like http or https, a hostname, and a path. A URL for this page is http://httpd.apache.org/docs-2.0/glossary.html.
Uniform Resource Identifier (URI)
A compact string of characters for identifying an abstract or physical resource. It is formally defined by RFC 2396. URIs used on the world-wide web are commonly referred to as URLs.
Virtual Hosting
Serving multiple websites using a single instance of Apache. IP virtual hosting differentiates between websites based on their IP address, while name-based virtual hosting uses only the name of the host and can therefore host many sites on the same IP address.
See: Apache Virtual Host documentation
X.509
An authentication certificate scheme recommended by the International Telecommunication Union (ITU-T) which is used for SSL/TLS authentication.
See: SSL/TLS Encryption


モジュール一覧 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

モジュール一覧

以下は Apache の配布の一部として配られているすべてのモジュールの 一覧です。すべての Apache ディレクティブ のアルファベット順のリストも見てください。

参照

  • マルチプロセッシングモジュール (MPMs)
  • ディレクティブ クイックリファレンス

コア機能と MPM

core
常に使用可能な Apache HTTP サーバのコア機能
mpm_common
二つ以上のマルチプロセッシングモジュール (MPM) で実装されているディレクティブのコレクション
beos
This Multi-Processing Module is optimized for BeOS.
leader
An experimental variant of the standard worker MPM
mpm_netware
Multi-Processing Module implementing an exclusively threaded web server optimized for Novell NetWare
mpmt_os2
Hybrid multi-process, multi-threaded MPM for OS/2
perchild
Multi-Processing Module allowing for daemon processes serving requests to be assigned a variety of different userids
prefork
スレッドを使わず、先行して fork を行なうウェブサーバを実装
threadpool
Yet another experimental variant of the standard worker MPM
mpm_winnt
Windows NT 向けに最適化されたマルチプロセッシングモジュール
worker
マルチスレッドとマルチプロセスのハイブリッド型 ウェブサーバを実装したマルチプロセッシングモジュール

他のモジュール

A | C | D | E | F | H | I | L | M | N | P | R | S | U | V

mod_access
クライアントのホスト名、IP アドレス、その他のクライアント のリクエストの特徴に基づいたアクセス制御機能を提供する
mod_actions
メディアタイプやリクエストメソッドに応じて CGI スクリプトを実行する機能を提供
mod_alias
ホストファイルシステム上のいろいろな違う場所を ドキュメントツリーにマップする機能と、 URL のリダイレクトを行なう機能を提供する
mod_asis
自分用の HTTP ヘッダの書かれているファイルを送信する
mod_auth
テキストファイルを用いたユーザ認証
mod_auth_anon
Allows "anonymous" user access to authenticated areas
mod_auth_dbm
Provides for user authentication using DBM files
mod_auth_digest
User authentication using MD5 Digest Authentication.
mod_auth_ldap
Allows an LDAP directory to be used to store the database for HTTP Basic authentication.
mod_autoindex
Unix の ls コマンドや Win32 の dir シェルコマンドに似た ディレクトリインデックスを生成する
mod_cache
Content cache keyed to URIs.
mod_cern_meta
CERN httpd metafile semantics
mod_cgi
CGI スクリプトの実行
mod_cgid
外部 CGI デーモンを使った CGI スクリプトの実行
mod_charset_lite
Specify character set translation or recoding
mod_dav
分散オーサリングとバージョン管理 (WebDAV) 機能
mod_dav_fs
mod_dav のためのファイルシステムプロバイダ
mod_deflate
クライアントへ送られる前にコンテンツを圧縮する
mod_dir
「最後のスラッシュ」のリダイレクトと、ディレクトリの インデックスファイルを扱う機能を提供する
mod_disk_cache
Content cache storage manager keyed to URIs
mod_echo
プロトコルモジュールの概要を示すための単純なエコーサーバ
mod_env
CGI スクリプト及び SSI ページに渡される環境変数を変更する機能を提供する
mod_example
Illustrates the Apache module API
mod_expires
ユーザの指定した基準に基づいた Expires と Cache-Control HTTP ヘッダの生成
mod_ext_filter
Pass the response body through an external program before delivery to the client
mod_file_cache
Caches a static list of files in memory
mod_headers
Customization of HTTP request and response headers
mod_imap
Server-side imagemap processing
mod_include
サーバがパースする html ドキュメント (Server Side Includes)
mod_info
サーバの設定の包括的な概観を提供する
mod_isapi
ISAPI Extensions within Apache for Windows
mod_ldap
LDAP connection pooling and result caching services for use by other LDAP modules
mod_log_config
サーバへのリクエストのロギング
mod_log_forensic
Forensic Logging of the requests made to the server
mod_logio
リクエスト毎に入力バイト数と出力バイト数とをロギング
mod_mem_cache
Content cache keyed to URIs
mod_mime
リクエストされたファイルの拡張子とファイルの振る舞い (ハンドラとフィルタ)、内容 (MIME タイプ、言語、文字セット、エンコーディング) とを関連付ける
mod_mime_magic
Determines the MIME type of a file by looking at a few bytes of its contents
mod_negotiation
コンテントネゴシエーション 機能を提供する
mod_nw_ssl
Enable SSL encryption for NetWare
mod_proxy
HTTP/1.1 proxy/gateway server
mod_proxy_connect
mod_proxy extension for CONNECT request handling
mod_proxy_ftp
FTP support module for mod_proxy
mod_proxy_http
HTTP support module for mod_proxy
mod_rewrite
Provides a rule-based rewriting engine to rewrite requested URLs on the fly
mod_setenvif
リクエストの特徴に基づいた環境変数の設定を可能にする
mod_so
起動時や再起動時に実行コードとモジュールをサーバにロードする
mod_speling
ユーザが入力したであろう間違った URL を、 大文字小文字の区別を無視することと一つ以下の綴り間違いを許容することで 修正を試みる
mod_ssl
Strong cryptography using the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols
mod_status
サーバの活動状況と性能に関する情報を提供する
mod_suexec
指定されたユーザとグループで CGI スクリプトを実行する
mod_unique_id
それぞれのリクエストに対する一意な識別子の入った環境変数を 提供する
mod_userdir
ユーザ専用のディレクトリを提供
mod_usertrack
Clickstream logging of user activity on a site
mod_vhost_alias
Provides for dynamically configured mass virtual hosting


ディレクティブ一覧 - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

ディレクティブ一覧

標準 Apache 配布にあるすべての Apache のディレクティブの一覧です。 これらは一貫した形式で書かれていて、使われている用語の 用語集 も用意されています。

各ディレクティブの概要を説明した ディレクティブクイックリファレンスも あります。

A | B | C | D | E | F | G | H | I | K | L | M | N | O | P | R | S | T | U | V | W | X

  • AcceptPathInfo
  • AccessFileName
  • Action
  • AddAlt
  • AddAltByEncoding
  • AddAltByType
  • AddCharset
  • AddDefaultCharset
  • AddDescription
  • AddEncoding
  • AddHandler
  • AddIcon
  • AddIconByEncoding
  • AddIconByType
  • AddInputFilter
  • AddLanguage
  • AddModuleInfo
  • AddOutputFilter
  • AddOutputFilterByType
  • AddType
  • Alias
  • AliasMatch
  • Allow
  • AllowCONNECT
  • AllowEncodedSlashes
  • AllowOverride
  • Anonymous
  • Anonymous_Authoritative
  • Anonymous_LogEmail
  • Anonymous_MustGiveEmail
  • Anonymous_NoUserID
  • Anonymous_VerifyEmail
  • AssignUserID
  • AuthAuthoritative
  • AuthDBMAuthoritative
  • AuthDBMGroupFile
  • AuthDBMType
  • AuthDBMUserFile
  • AuthDigestAlgorithm
  • AuthDigestDomain
  • AuthDigestFile
  • AuthDigestGroupFile
  • AuthDigestNcCheck
  • AuthDigestNonceFormat
  • AuthDigestNonceLifetime
  • AuthDigestQop
  • AuthDigestShmemSize
  • AuthGroupFile
  • AuthLDAPAuthoritative
  • AuthLDAPBindDN
  • AuthLDAPBindPassword
  • AuthLDAPCharsetConfig
  • AuthLDAPCompareDNOnServer
  • AuthLDAPDereferenceAliases
  • AuthLDAPEnabled
  • AuthLDAPFrontPageHack
  • AuthLDAPGroupAttribute
  • AuthLDAPGroupAttributeIsDN
  • AuthLDAPRemoteUserIsDN
  • AuthLDAPUrl
  • AuthName
  • AuthType
  • AuthUserFile
  • BrowserMatch
  • BrowserMatchNoCase
  • CacheDefaultExpire
  • CacheDirLength
  • CacheDirLevels
  • CacheDisable
  • CacheEnable
  • CacheExpiryCheck
  • CacheFile
  • CacheForceCompletion
  • CacheGcClean
  • CacheGcDaily
  • CacheGcInterval
  • CacheGcMemUsage
  • CacheGcUnused
  • CacheIgnoreCacheControl
  • CacheIgnoreNoLastMod
  • CacheLastModifiedFactor
  • CacheMaxExpire
  • CacheMaxFileSize
  • CacheMinFileSize
  • CacheNegotiatedDocs
  • CacheRoot
  • CacheSize
  • CacheTimeMargin
  • CGIMapExtension
  • CharsetDefault
  • CharsetOptions
  • CharsetSourceEnc
  • CheckSpelling
  • ChildPerUserID
  • ContentDigest
  • CookieDomain
  • CookieExpires
  • CookieLog
  • CookieName
  • CookieStyle
  • CookieTracking
  • CoreDumpDirectory
  • CustomLog
  • Dav
  • DavDepthInfinity
  • DavLockDB
  • DavMinTimeout
  • DefaultIcon
  • DefaultLanguage
  • DefaultType
  • DeflateBufferSize
  • DeflateCompressionLevel
  • DeflateFilterNote
  • DeflateMemLevel
  • DeflateWindowSize
  • Deny
  • <Directory>
  • DirectoryIndex
  • <DirectoryMatch>
  • DirectorySlash
  • DocumentRoot
  • EnableMMAP
  • EnableSendfile
  • ErrorDocument
  • ErrorLog
  • Example
  • ExpiresActive
  • ExpiresByType
  • ExpiresDefault
  • ExtendedStatus
  • ExtFilterDefine
  • ExtFilterOptions
  • FileETag
  • <Files>
  • <FilesMatch>
  • ForceLanguagePriority
  • ForceType
  • ForensicLog
  • Group
  • Header
  • HeaderName
  • HostnameLookups
  • IdentityCheck
  • <IfDefine>
  • <IfModule>
  • ImapBase
  • ImapDefault
  • ImapMenu
  • Include
  • IndexIgnore
  • IndexOptions
  • IndexOrderDefault
  • ISAPIAppendLogToErrors
  • ISAPIAppendLogToQuery
  • ISAPICacheFile
  • ISAPIFakeAsync
  • ISAPILogNotSupported
  • ISAPIReadAheadBuffer
  • KeepAlive
  • KeepAliveTimeout
  • LanguagePriority
  • LDAPCacheEntries
  • LDAPCacheTTL
  • LDAPOpCacheEntries
  • LDAPOpCacheTTL
  • LDAPSharedCacheFile
  • LDAPSharedCacheSize
  • LDAPTrustedCA
  • LDAPTrustedCAType
  • <Limit>
  • <LimitExcept>
  • LimitInternalRecursion
  • LimitRequestBody
  • LimitRequestFields
  • LimitRequestFieldSize
  • LimitRequestLine
  • LimitXMLRequestBody
  • Listen
  • ListenBackLog
  • LoadFile
  • LoadModule
  • <Location>
  • <LocationMatch>
  • LockFile
  • LogFormat
  • LogLevel
  • MaxClients
  • MaxKeepAliveRequests
  • MaxMemFree
  • MaxRequestsPerChild
  • MaxRequestsPerThread
  • MaxSpareServers
  • MaxSpareThreads
  • MaxThreads
  • MaxThreadsPerChild
  • MaxThreadsPerChild
  • MCacheMaxObjectCount
  • MCacheMaxObjectSize
  • MCacheMaxStreamingBuffer
  • MCacheMinObjectSize
  • MCacheRemovalAlgorithm
  • MCacheSize
  • MetaDir
  • MetaFiles
  • MetaSuffix
  • MimeMagicFile
  • MinSpareServers
  • MinSpareThreads
  • MMapFile
  • ModMimeUsePathInfo
  • MultiviewsMatch
  • NameVirtualHost
  • NoProxy
  • NumServers
  • NumServers
  • NWSSLTrustedCerts
  • NWSSLUpgradeable
  • Options
  • Order
  • PassEnv
  • PidFile
  • ProtocolEcho
  • <Proxy>
  • ProxyBadHeader
  • ProxyBlock
  • ProxyDomain
  • ProxyErrorOverride
  • ProxyIOBufferSize
  • <ProxyMatch>
  • ProxyMaxForwards
  • ProxyPass
  • ProxyPassReverse
  • ProxyPreserveHost
  • ProxyReceiveBufferSize
  • ProxyRemote
  • ProxyRemoteMatch
  • ProxyRequests
  • ProxyTimeout
  • ProxyVia
  • ReadmeName
  • Redirect
  • RedirectMatch
  • RedirectPermanent
  • RedirectTemp
  • RemoveCharset
  • RemoveEncoding
  • RemoveHandler
  • RemoveInputFilter
  • RemoveLanguage
  • RemoveOutputFilter
  • RemoveType
  • RequestHeader
  • Require
  • RewriteBase
  • RewriteCond
  • RewriteEngine
  • RewriteLock
  • RewriteLog
  • RewriteLogLevel
  • RewriteMap
  • RewriteOptions
  • RewriteRule
  • RLimitCPU
  • RLimitMEM
  • RLimitNPROC
  • Satisfy
  • ScoreBoardFile
  • Script
  • ScriptAlias
  • ScriptAliasMatch
  • ScriptInterpreterSource
  • ScriptLog
  • ScriptLogBuffer
  • ScriptLogLength
  • ScriptSock
  • SecureListen
  • SendBufferSize
  • ServerAdmin
  • ServerAlias
  • ServerLimit
  • ServerName
  • ServerPath
  • ServerRoot
  • ServerSignature
  • ServerTokens
  • SetEnv
  • SetEnvIf
  • SetEnvIfNoCase
  • SetHandler
  • SetInputFilter
  • SetOutputFilter
  • SSIEndTag
  • SSIErrorMsg
  • SSIStartTag
  • SSITimeFormat
  • SSIUndefinedEcho
  • SSLCACertificateFile
  • SSLCACertificatePath
  • SSLCARevocationFile
  • SSLCARevocationPath
  • SSLCertificateChainFile
  • SSLCertificateFile
  • SSLCertificateKeyFile
  • SSLCipherSuite
  • SSLEngine
  • SSLMutex
  • SSLOptions
  • SSLPassPhraseDialog
  • SSLProtocol
  • SSLProxyCACertificateFile
  • SSLProxyCACertificatePath
  • SSLProxyCARevocationFile
  • SSLProxyCARevocationPath
  • SSLProxyCipherSuite
  • SSLProxyEngine
  • SSLProxyMachineCertificateFile
  • SSLProxyMachineCertificatePath
  • SSLProxyProtocol
  • SSLProxyVerify
  • SSLProxyVerifyDepth
  • SSLRandomSeed
  • SSLRequire
  • SSLRequireSSL
  • SSLSessionCache
  • SSLSessionCacheTimeout
  • SSLVerifyClient
  • SSLVerifyDepth
  • StartServers
  • StartThreads
  • SuexecUserGroup
  • ThreadLimit
  • ThreadsPerChild
  • ThreadStackSize
  • TimeOut
  • TransferLog
  • TypesConfig
  • UnsetEnv
  • UseCanonicalName
  • User
  • UserDir
  • VirtualDocumentRoot
  • VirtualDocumentRootIP
  • <VirtualHost>
  • VirtualScriptAlias
  • VirtualScriptAliasIP
  • Win32DisableAcceptEx
  • XBitHack


ディレクティブ クイックリファレンス - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0 > モジュール

ディレクティブ クイックリファレンス

ディレクティブ クイックリファレンスでは、各 Apache 設定ディレクティブの 使用方法、デフォルト値、ステータスとコンテキストを示しています。 各ディレクティブの、より詳しい情報に関しては ディレクティブ辞書を ご覧下さい。

第 1 列目はディレクティブの名前と使用方法です。 第 2 列目は (もしあれば) デフォルト値となっています。 デフォルト値が長すぎて表示しきれない場合は、最初の文字列の後ろに 「 + 」が続きます。

第 3, 4 列は、下の表の注釈に従って、 ディレクティブの使用できるコンテキストと、 ディレクティブのステータスが示されています。

A | B | C | D | E | F | G | H | I | K | L | M | N | O | P | R | S | T | U | V | W | X
s | サーバ設定ファイル
v | バーチャルホスト
d | ディレクトリ
h | .htaccess

C | Core
M | MPM
B | Base
E | Extension
X | Experimental
AcceptPathInfo On|Off|Default | Default | svdh | C
後に続くパス名情報を受け付けるリソースの指定
AccessFileName filename [filename] ... | .htaccess | sv | C
分散設定ファイルの名前
Action action-type cgi-script |  | svdh | B
特定のハンドラやコンテントタイプに対して CGI を実行するように 設定
AddAlt string file [file] ... |  | svdh | B
アイコンの代わりに 表示される、ファイル名で選択された代替テキスト
AddAltByEncoding string MIME-encoding [MIME-encoding] ... |  | svdh | B
アイコンの代わりに表示される、MIME 符号化方法で選択された 代替テキスト
AddAltByType string MIME-type [MIME-type] ... |  | svdh | B
アイコンの代わりに 表示される、MIME タイプで選択された代替テキスト
AddCharset charset extension [extension] ... |  | svdh |
ファイル名の拡張子を指定された文字セットにマップする
AddDefaultCharset On|Off|charset | Off | svdh | C
明示的に文字セットを指定していない応答に追加される デフォルトの文字セット
AddDescription string file [file] ... |  | svdh | B
ファイルに対して表示する説明
AddEncoding MIME-enc extension [extension] ... |  | svdh |
ファイル名の拡張子を指定されたエンコーディング にマップする
AddHandler handler-name extension [extension] ... |  | svdh |
ファイル名の拡張子を指定されたハンドラにマップする
AddIcon icon name [name] ... |  | svdh | B
ファイルに表示するアイコンを名前で選択
AddIconByEncoding icon MIME-encoding [MIME-encoding] ... |  | svdh | B
ファイルに表示するアイコンを MIME 符号化方法で選択
AddIconByType icon MIME-type [MIME-type] ... |  | svdh | B
ファイルの隣に表示するアイコンを MIME タイプによって選択
AddInputFilter filter[;filter...] extension [extension] ... |  | svdh |
ファイルの拡張子をクライアントのリクエストを処理する フィルタにマップする
AddLanguage MIME-lang extension [extension] ... |  | svdh |
ファイル名を指定された言語にマップ
AddModuleInfo module-name string |  | sv | E
server-info ハンドラにより表示されるモジュールの情報に 追加の情報を付け加える
AddOutputFilter filter[;filter...] extension [extension] ... |  | svdh |
ファイル名の拡張子をサーバからの応答を処理するフィルタに マップする
AddOutputFilterByType filter[;filter...] MIME-type [MIME-type] ... |  | svdh | C
MIME-type に出力フィルタを割り当てる
AddType MIME-type extension [extension] ... |  | svdh |
ファイル名の拡張子を指定されたコンテントタイプにマップ
Alias URL-path file-path|directory-path |  | sv | B
URL をファイルシステムの位置にマップする
AliasMatch regex file-path|directory-path |  | sv | B
正規表現を使って URL をファイルシステムの位置にマップする
Allow from all|host|env=env-variable [host|env=env-variable] ... |  | dh | B
サーバのある領域にアクセスできるホストを制御する
AllowCONNECT port [port] ... | 443 563 | sv | E
Ports that are allowed to CONNECT through the proxy
AllowEncodedSlashes On|Off | Off | sv | C
URL 中の符号化されたパス分離文字が先に伝えられるのを許可するかどうかを 決定する
AllowOverride All|None|directive-type [directive-type] ... | All | d | C
.htaccess で許可されるディレクティブの種類
Anonymous user [user] ... |  | dh | E
Specifies userIDs that are allowed access without password verification
Anonymous_Authoritative On|Off | Off | dh | E
Configures if authorization will fall-through to other methods
Anonymous_LogEmail On|Off | On | dh | E
Sets whether the password entered will be logged in the error log
Anonymous_MustGiveEmail On|Off | On | dh | E
Specifies whether blank passwords are allowed
Anonymous_NoUserID On|Off | Off | dh | E
Sets whether the userID field may be empty
Anonymous_VerifyEmail On|Off | Off | dh | E
Sets whether to check the password field for a correctly formatted email address
AssignUserID user-id group-id |  | v | M
Tie a virtual host to a user and group ID
AuthAuthoritative On|Off | On | dh | B
認証と承認プロセスを、 より低いレベルのモジュールに移行させるかどうかを設定する
AuthDBMAuthoritative On|Off | On | dh | E
Sets whether authentication and authorization will be passwed on to lower level modules
AuthDBMGroupFile file-path |  | dh | E
Sets the name of the database file containing the list of user groups for authentication
AuthDBMType default|SDBM|GDBM|NDBM|DB | default | dh | E
Sets the type of database file that is used to store passwords
AuthDBMUserFile file-path |  | dh | E
Sets thename of a database file containing the list of users and passwords for authentication
AuthDigestAlgorithm MD5|MD5-sess | MD5 | dh | X
Selects the algorithm used to calculate the challenge and response hases in digest authentication
AuthDigestDomain URI [URI] ... |  | dh | X
URIs that are in the same protection space for digest authentication
AuthDigestFile file-path |  | dh | X
Location of the text file containing the list of users and encoded passwords for digest authentication
AuthDigestGroupFile file-path |  | dh | X
Name of the text file containing the list of groups for digest authentication
AuthDigestNcCheck On|Off | Off | s | X
Enables or disables checking of the nonce-count sent by the server
AuthDigestNonceFormat format |  | dh | X
Determines how the nonce is generated
AuthDigestNonceLifetime seconds | 300 | dh | X
How long the server nonce is valid
AuthDigestQop none|auth|auth-int [auth|auth-int] | auth | dh | X
Determines the quality-of-protection to use in digest authentication
AuthDigestShmemSize size | 1000 | s | X
The amount of shared memory to allocate for keeping track of clients
AuthGroupFile file-path |  | dh | B
認証に使用するユーザグループの一覧が格納されている、 テキストファイルの名前を設定する
AuthLDAPAuthoritative on|off | on | dh | X
Prevent other authentication modules from authenticating the user if this one fails
AuthLDAPBindDN distinguished-name |  | dh | X
Optional DN to use in binding to the LDAP server
AuthLDAPBindPassword password |  | dh | X
Password used in conjuction with the bind DN
AuthLDAPCharsetConfig file-path |  | s | X
Language to charset conversion configuration file
AuthLDAPCompareDNOnServer on|off | on | dh | X
Use the LDAP server to compare the DNs
AuthLDAPDereferenceAliases never|searching|finding|always | Always | dh | X
When will the module de-reference aliases
AuthLDAPEnabled on|off | on | dh | X
Turn on or off LDAP authentication
AuthLDAPFrontPageHack on|off | off | dh | X
Allow LDAP authentication to work with MS FrontPage
AuthLDAPGroupAttribute attribute |  | dh | X
LDAP attributes used to check for group membership
AuthLDAPGroupAttributeIsDN on|off | on | dh | X
Use the DN of the client username when checking for group membership
AuthLDAPRemoteUserIsDN on|off | off | dh | X
Use the DN of the client username to set the REMOTE_USER environment variable
AuthLDAPUrl url |  | dh | X
URL specifying the LDAP search parameters
AuthName auth-domain |  | dh | C
HTTP 認証の認可領域 (訳注: realm)
AuthType Basic|Digest |  | dh | C
ユーザ認証の種類
AuthUserFile file-path |  | dh | B
認証に使用するユーザとパスワードの一覧が格納されている、 テキストファイルの名前を設定する
BrowserMatch regex [!]env-variable[=value] [[!]env-variable[=value]] ... |  | svdh | B
HTTP User-Agent に基づいて環境変数を設定する
BrowserMatchNoCase regex [!]env-variable[=value] [[!]env-variable[=value]] ... |  | svdh | B
HTTP User-Agent に基づいて大文字小文字を区別せずに 環境変数を設定する
CacheDefaultExpire seconds | 3600 (one hour) | sv | X
The default duration to cache a document when no expiry date is specified.
CacheDirLength length | 2 | sv | X
The number of characters in subdirectory names
CacheDirLevels levels | 3 | sv | X
The number of levels of subdirectories in the cache.
CacheDisable url-string |  | sv | X
Disable caching of specified URLs
CacheEnable cache_type url-string |  | sv | X
Enable caching of specified URLs using a specified storage manager
CacheExpiryCheck On|Off | On | sv | X
Indicates if the cache observes Expires dates when seeking files
CacheFile file-path [file-path] ... |  | s | X
Cache a list of file handles at startup time
CacheForceCompletion Percentage | 60 | sv | X
Percentage of document served, after which the server will complete caching the file even if the request is cancelled.
CacheGcClean hours url-string | ? | sv | X
The time to retain unchanged cached files that match a URL
CacheGcDaily time | ? | sv | X
The recurring time each day for garbage collection to be run. (24 hour clock)
CacheGcInterval hours |  | sv | X
The interval between garbage collection attempts.
CacheGcMemUsage KBytes | ? | sv | X
The maximum kilobytes of memory used for garbage collection
CacheGcUnused hours url-string | ? | sv | X
The time to retain unreferenced cached files that match a URL.
CacheIgnoreCacheControl On|Off | Off | sv | X
Ignore the fact that the client requested the content not be cached.
CacheIgnoreNoLastMod On|Off | Off | sv | X
Ignore the fact that a response has no Last Modified header.
CacheLastModifiedFactor float | 0.1 | sv | X
The factor used to compute an expiry date based on the LastModified date.
CacheMaxExpire seconds | 86400 (one day) | sv | X
The maximum time in seconds to cache a document
CacheMaxFileSize bytes | 1000000 | sv | X
The maximum size (in bytes) of a document to be placed in the cache
CacheMinFileSize bytes | 1 | sv | X
The minimum size (in bytes) of a document to be placed in the cache
CacheNegotiatedDocs On|Off | Off | sv | B
コンテントネゴシエーションされたドキュメントをプロキシサーバが キャッシュできるようにする
CacheRoot directory |  | sv | X
The directory root under which cache files are stored
CacheSize KBytes | 1000000 | sv | X
The maximum amount of disk space that will be used by the cache in KBytes
CacheTimeMargin ? | ? | sv | X
The minimum time margin to cache a document
CGIMapExtension cgi-path .extension |  | dh | C
CGI スクリプトのインタープリタの位置を調べるための手法
CharsetDefault charset |  | svdh | X
Charset to translate into
CharsetOptions option [option] ... | DebugLevel=0 NoImpl + | svdh | X
Configures charset translation behavior
CharsetSourceEnc charset |  | svdh | X
Source charset of files
CheckSpelling on|off | Off | svdh | E
spelling モジュールを使用するようにする
ChildPerUserID user-id group-id num-children |  | s | M
Specify user ID and group ID for a number of child processes
ContentDigest On|Off | Off | svdh | C
Content-MD5 HTTP 応答ヘッダの生成を有効にする
CookieDomain domain |  | svdh | E
The domain to which the tracking cookie applies
CookieExpires expiry-period |  | svdh | E
Expiry time for the tracking cookie
CookieLog filename |  | sv | B
クッキングのロギングのためのファイル名を設定する
CookieName token | Apache | svdh | E
Name of the tracking cookie
CookieStyle Netscape|Cookie|Cookie2|RFC2109|RFC2965 | Netscape | svdh | E
Format of the cookie header field
CookieTracking on|off | off | svdh | E
Enables tracking cookie
CoreDumpDirectory directory |  | s | M
Apache がコアダンプする前に移動を試みるディレクトリ
CustomLog file|pipe format|nickname [env=[!]environment-variable] |  | sv | B
ログファイルの名前と書式を設定する
Dav On|Off|provider-name | Off | d | E
WebDAV HTTP メソッドを有効にします
DavDepthInfinity on|off | off | svd | E
PROPFIND, Depth: Infinity リクエストを許可します
DavLockDB file-path |  | sv | E
DAV ロックデータベースの位置
DavMinTimeout seconds | 0 | svd | E
サーバが DAV リソースのロックを維持する最小時間です。
DefaultIcon url-path |  | svdh | B
特定のアイコンが何も設定されていない時に ファイルに表示するアイコン
DefaultLanguage MIME-lang |  | svdh |
あるスコープのすべてのファイルを指定された言語に 設定する
DefaultType MIME-type | text/plain | svdh | C
サーバがコンテントタイプを決定できないときに 送られる MIME コンテントタイプ
DeflateBufferSize value | 8096 | sv | E
zlib が一度に圧縮する塊の大きさ
DeflateCompressionLevel value |  | sv | E
出力に対して行なう圧縮の程度
DeflateFilterNote [type] notename |  | sv | E
ロギング用に圧縮比をメモに追加
DeflateMemLevel value | 9 | sv | E
zlib が圧縮に使うメモリのレベルを指定
DeflateWindowSize value | 15 | sv | E
Zlib の圧縮用ウィンドウの大きさ
Deny from all|host|env=env-variable [host|env=env-variable] ... |  | dh | B
サーバがアクセスを拒否するホストを制御する
<Directory directory-path> ... </Directory> |  | sv | C
指定のファイルシステムのディレクトリとサブディレクトリとのみに 適用されるディレクティブを囲む
DirectoryIndex local-url [local-url] ... | index.html | svdh | B
クライアントがディレクトリをリクエストしたときに調べる リソースのリスト
<DirectoryMatch regex> ... </DirectoryMatch> |  | sv | C
正規表現にマッチするファイルシステムのディレクトリと サブディレクトリとのみに適用されるディレクティブを囲む
DirectorySlash On|Off | On | svdh | B
パス末尾のスラッシュでリダイレクトするかどうかのオンオフをトグルさせる
DocumentRoot directory-path | /usr/local/apache/h + | sv | C
ウェブから見えるメインのドキュメントツリーになる ディレクトリ
EnableMMAP On|Off | On | svdh | C
配送中にファイルを読み込むためにメモリマッピングを 使うかどうか
EnableSendfile On|Off | On | svdh | C
ファイルのクライアントへの配送時にカーネルの sendfile サポートを 使うかどうか
ErrorDocument error-code document |  | svdh | C
エラーが発生したときにサーバがクライアントに送るもの
ErrorLog file-path|syslog[:facility] | logs/error_log (Uni + | sv | C
サーバがエラーをログ収集する場所
Example |  | svdh | X
Demonstration directive to illustrate the Apache module API
ExpiresActive On|Off |  | svdh | E
Expires ヘッダの生成を有効にする
ExpiresByType MIME-type <code>seconds |  | svdh | E
MIME タイプによって設定される Expires ヘッダの値
ExpiresDefault <code>seconds |  | svdh | E
期限切れ期日を計算するデフォルトアルゴリズム
ExtendedStatus On|Off | Off | s | B
各リクエストに対して拡張ステータス情報を保存する
ExtFilterDefine filtername parameters |  | s | E
Define an external filter
ExtFilterOptions option [option] ... | DebugLevel=0 NoLogS + | d | E
Configure mod_ext_filter options
FileETag component ... | INode MTime Size | svdh | C
ETag HTTP 応答ヘッダを作成するために使用される ファイルの属性
<Files filename> ... </Files> |  | svdh | C
マッチするファイル名に適用されるディレクティブを囲む
<FilesMatch regex> ... </FilesMatch> |  | svdh | C
正規表現にマッチするファイル名に適用される ディレクティブを囲む
ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback] | Prefer | svdh | B
要求に合う単独のドキュメントが見つからなかったときに行なうことを指定
ForceType MIME-type|None |  | dh | C
すべてのマッチするファイルが指定の MIME コンテントタイプで 送られるようにする
ForensicLog filename|pipe |  | sv | E
Sets filename of the forensic log
Group unix-group | #-1 | sv | M
リクエストに応答する際に所属するグループ
Header [condition] set|append|add|unset|echo header [value] [env=[!]variable] |  | svdh | E
Configure HTTP response headers
HeaderName filename |  | svdh | B
インデックス一覧の先頭に挿入されるファイルの名前
HostnameLookups On|Off|Double | Off | svd | C
クライアントの IP アドレスの DNS ルックアップを 有効にする
IdentityCheck On|Off | Off | svd | C
リモートユーザの RFC1413 によるアイデンティティのロギングを 有効にする
<IfDefine [!]parameter-name> ... </IfDefine> |  | svdh | C
起動時にテストが真であるときのみに処理されるディレクティブを 囲む
<IfModule [!]module-name> ... </IfModule> |  | svdh | C
モジュールの存在するかしないかに応じて処理される ディレクティブを囲む
ImapBase map|referer|URL | http://servername/ | svdh | B
Default base for imagemap files
ImapDefault error|nocontent|map|referer|URL | nocontent | svdh | B
Default action when an imagemap is called with coordinates that are not explicitly mapped
ImapMenu none|formatted|semiformatted|unformatted |  | svdh | B
Action if no coordinates are given when calling an imagemap
Include file-path|directory-path |  | svd | C
サーバ設定ファイル中から他の設定ファイルを取り込む
IndexIgnore file [file] ... |  | svdh | B
ディレクトリ一覧を行なう際に無視すべき ファイルリストに追加
IndexOptions [+|-]option [[+|-]option] ... |  | svdh | B
ディレクトリインデックスの様々な設定項目
IndexOrderDefault Ascending|Descending Name|Date|Size|Description | Ascending Name | svdh | B
ディレクトリインデックスの標準の順番付けを設定
ISAPIAppendLogToErrors on|off | off | svdh | B
Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the error log
ISAPIAppendLogToQuery on|off | on | svdh | B
Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the query field
ISAPICacheFile file-path [file-path] ... |  | sv | B
ISAPI .dll files to be loaded at startup
ISAPIFakeAsync on|off | off | svdh | B
Fake asynchronous support for ISAPI callbacks
ISAPILogNotSupported on|off | off | svdh | B
Log unsupported feature requests from ISAPI extensions
ISAPIReadAheadBuffer size | 49152 | svdh | B
Size of the Read Ahead Buffer sent to ISAPI extensions
KeepAlive On|Off | On | sv | C
HTTP の持続的な接続を有効にする
KeepAliveTimeout seconds | 15 | sv | C
持続的な接続で次のリクエストが来るまでサーバが待つ時間
LanguagePriority MIME-lang [MIME-lang] ... |  | svdh | B
クライアントが優先度を示さなかったときの言語の variant の優先度を 指定
LDAPCacheEntries number | 1024 | s | X
Maximum number of entries in the primary LDAP cache
LDAPCacheTTL seconds | 600 | s | X
Time that cached items remain valid
LDAPOpCacheEntries number | 1024 | s | X
Number of entries used to cache LDAP compare operations
LDAPOpCacheTTL seconds | 600 | s | X
Time that entries in the operation cache remain valid
LDAPSharedCacheFile directory-path/filename |  | s | X
Sets the shared memory cache file
LDAPSharedCacheSize bytes | 102400 | s | X
Size in bytes of the shared-memory cache
LDAPTrustedCA directory-path/filename |  | s | X
Sets the file containing the trusted Certificate Authority certificate or database
LDAPTrustedCAType type |  | s | X
Specifies the type of the Certificate Authority file
<Limit method [method] ... > ... </Limit> |  | svdh | C
囲いの中にあるアクセス制御の適用を特定の HTTP メソッドのみに 制限する
<LimitExcept method [method] ... > ... </LimitExcept> |  | svdh | C
指定されたもの以外の HTTP メソッドにアクセス制御を 制限する
LimitInternalRecursion number [number] | 10 | sv | C
内部リダイレクトと入れ子になったサブリクエストの最大数を決定する
LimitRequestBody bytes | 0 | svdh | C
クライアントから送られる HTTP リクエストのボディの 総量を制限する
LimitRequestFields number | 100 | s | C
クライアントからの HTTP リクエストのヘッダフィールドの数を 制限する
LimitRequestFieldsize bytes |  | s | C
クライアントからの HTTP リクエストのヘッダの サイズを制限する
LimitRequestLine bytes | 8190 | s | C
クライアントからの HTTP リクエスト行のサイズを制限する
LimitXMLRequestBody bytes | 1000000 | svdh | C
XML 形式のリクエストのボディのサイズを制限する
Listen [IP-address:]portnumber |  | s | M
サーバが listen するIP アドレスとポート番号
ListenBacklog backlog |  | s | M
保留状態のコネクションのキューの最大長
LoadFile filename [filename] ... |  | s | E
指定されたオブジェクトファイルやライブラリをリンクする
LoadModule module filename |  | s | E
オブジェクトファイルやライブラリをリンクし、使用モジュールの リストに追加する
<Location URL-path|URL> ... </Location> |  | sv | C
囲んだディレクティブをマッチする URL のみに適用
<LocationMatch regex> ... </LocationMatch> |  | sv | C
囲んだディレクティブを正規表現にマッチする URL のみに 適用
LockFile filename | logs/accept.lock | s | M
受付を直列化するためのロックファイルの位置
LogFormat format|nickname [nickname] | "%h %l %u %t \"%r\" + | sv | B
ログファイルで使用する書式を設定する
LogLevel level | warn | sv | C
ErrorLog の冗長性を制御する
MaxClients number |  | s | M
リクエストに応答するために作成される 子プロセスの最大個数
MaxKeepAliveRequests number | 100 | sv | C
持続的な接続上で許可されるリクエストの数
MaxMemFree number |  | s | M
主メモリアロケータが free() を呼ばずに保持し続けられるメモリの 最大量
MaxRequestsPerChild number | 10000 | s | M
個々の子サーバが稼働中に扱うリクエスト数の上限
MaxRequestsPerThread number | 0 | s | M
Limit on the number of requests that an individual thread will handle during its life
MaxSpareServers number | 10 | s | M
アイドルな子サーバプロセスの最大個数
MaxSpareThreads number |  | s | M
アイドルスレッドの最大数
MaxThreads number | 2048 | s | M
Set the maximum number of worker threads
MaxThreadsPerChild number | 64 | s | M
子プロセス毎のスレッド数の最大数
MaxThreadsPerChild number | 64 | s | M
Maximum number of threads per child process
MCacheMaxObjectCount value | 1009 | s | X
The maximum number of objects allowed to be placed in the cache
MCacheMaxObjectSize bytes | 10000 | s | X
The maximum size (in bytes) of a document allowed in the cache
MCacheMaxStreamingBuffer size_in_bytes | the smaller of 1000 + | s | X
Maximum amount of a streamed response to buffer in memory before declaring the response uncacheable
MCacheMinObjectSize bytes | 0 | s | X
The minimum size (in bytes) of a document to be allowed in the cache
MCacheRemovalAlgorithm LRU|GDSF | GDSF | s | X
The algorithm used to select documents for removal from the cache
MCacheSize KBytes | 100 | s | X
The maximum amount of memory used by the cache in KBytes
MetaDir directory | .web | svdh | E
Name of the directory to find CERN-style meta information files
MetaFiles on|off | off | svdh | E
Activates CERN meta-file processing
MetaSuffix suffix | .meta | svdh | E
File name suffix for the file containg CERN-style meta information
MimeMagicFile file-path |  | sv | E
Enable MIME-type determination based on file contents using the specified magic file
MinSpareServers number | 5 | s | M
アイドルな子サーバプロセスの最小個数
MinSpareServers number |  | s | M
リクエストに応答することのできる アイドルスレッド数の最小数
MMapFile file-path [file-path] ... |  | s | X
Map a list of files into memory at startup time
ModMimeUsePathInfo On|Off | Off | d |
path_info コンポーネントをファイル名の一部として扱うように mod_mime に通知する
MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers [Handlers|Filters] | NegotiatedOnly | svdh |
MultiViews でのマッチングの検索に含ませる ファイルのタイプを指定する
NameVirtualHost addr[:port] |  | s | C
名前ベースのバーチャルホストのための IP アドレスを指定
NoProxy host [host] ... |  | sv | E
Hosts, domains, or networks that will be connected to directly
NumServers number | 2 | s | M
同時に起動している子プロセスの総数
NumServers number | 2 | s | M
Total number of children alive at the same time
NWSSLTrustedCerts filename [filename] ... |  | s | B
List of additional client certificates
NWSSLUpgradeable [IP-address:]portnumber |  | s | B
Allows a connection to be upgraded to an SSL connection upon request
Options [+|-]option [[+|-]option] ... | All | svdh | C
ディレクトリに対して使用可能な機能を設定する
Order ordering | Deny,Allow | dh | B
デフォルトのアクセス可能な状態と、Allow と Deny が評価される順番を制御する
PassEnv env-variable [env-variable] ... |  | svdh | B
シェルからの環境変数を渡す
PidFile filename | logs/httpd.pid | s | M
デーモンのプロセス ID をサーバが記録するためのファイル
ProtocolEcho On|Off |  | sv | X
エコーサーバの有効無効を設定します。
<Proxy wildcard-url> ...</Proxy> |  | sv | E
Container for directives applied to proxied resources
ProxyBadHeader IsError|Ignore|StartBody | IsError | sv | E
Determines how to handle bad header lines in a response
ProxyBlock *|word|host|domain [word|host|domain] ... |  | sv | E
Words, hosts, or domains that are banned from being proxied
ProxyDomain Domain |  | sv | E
Default domain name for proxied requests
ProxyErrorOverride On|Off | Off | sv | E
Override error pages for proxied content
ProxyIOBufferSize bytes | 8192 | sv | E
Determine size of internal data throughput buffer
<ProxyMatch regex> ...</ProxyMatch> |  | sv | E
Container for directives applied to regular-expression-matched proxied resources
ProxyMaxForwards number | 10 | sv | E
Maximium number of proxies that a request can be forwarded through
ProxyPass [path] !|url |  | svd | E
Maps remote servers into the local server URL-space
ProxyPassReverse [path] url |  | svd | E
Adjusts the URL in HTTP response headers sent from a reverse proxied server
ProxyPreserveHost On|Off | Off | sv | E
Use incoming Host HTTP request header for proxy request
ProxyReceiveBufferSize bytes | 0 | sv | E
Network buffer size for proxied HTTP and FTP connections
ProxyRemote match remote-server |  | sv | E
Remote proxy used to handle certain requests
ProxyRemoteMatch regex remote-server |  | sv | E
Remote proxy used to handle requests matched by regular expressions
ProxyRequests On|Off | Off | sv | E
Enables forward (standard) proxy requests
ProxyTimeout seconds | 300 | sv | E
Network timeout for proxied requests
ProxyVia On|Off|Full|Block | Off | sv | E
Information provided in the Via HTTP response header for proxied requests
ReadmeName filename |  | svdh | B
インデックス一覧の最後に挿入されるファイルの名前
Redirect [status] URL-path URL |  | svdh | B
クライアントが違う URL を取得するように外部へのリダイレクトを 送る
RedirectMatch [status] regex URL |  | svdh | B
現在の URL への正規表現のマッチにより 外部へのリダイレクトを送る
RedirectPermanent URL-path URL |  | svdh | B
クライアントが違う URL を取得するように外部への永久的な リダイレクトを送る
RedirectTemp URL-path URL |  | svdh | B
クライアントが違う URL を取得するように外部への一時的な リダイレクトを送る
RemoveCharset extension [extension] ... |  | vdh |
ファイルの拡張子に関連付けられたすべての文字セット を解除する
RemoveEncoding extension [extension] ... |  | vdh |
ファイルの拡張子に関連付けられたすべてのコンテントエンコーディング を解除する
RemoveHandler extension [extension] ... |  | vdh |
ファイルの拡張子に関連付けられたすべてのハンドラを 解除する
RemoveInputFilter extension [extension] ... |  | vdh |
ファイル拡張子に関連付けられた入力フィルタを解除する
RemoveLanguage extension [extension] ... |  | vdh |
ファイル拡張子に関連付けられた言語を解除する
RemoveOutputFilter extension [extension] ... |  | vdh |
ファイル拡張子に関連付けられた出力フィルタを解除する
RemoveType extension [extension] ... |  | vdh |
ファイルの拡張子と関連付けられたコンテントタイプを 解除する
RequestHeader set|append|add|unset header [value] |  | svdh | E
Configure HTTP request headers
Require entity-name [entity-name] ... |  | dh | C
どの認証済みユーザがリソースをアクセスできるかを選択する
RewriteBase URL-path |  | dh | E
Sets the base URL for per-directory rewrites
RewriteCond TestString CondPattern |  | svdh | E
Defines a condition under which rewriting will take place
RewriteEngine on|off | off | svdh | E
Enables or disables runtime rewriting engine
RewriteLock file-path |  | s | E
Sets the name of the lock file used for RewriteMap synchronization
RewriteLog file-path |  | sv | E
Sets the name of the file used for logging rewrite engine processing
RewriteLogLevel Level | 0 | sv | E
Sets the verbosity of the log file used by the rewrite engine
RewriteMap MapName MapType:MapSource |  | sv | E
Defines a mapping function for key-lookup
RewriteOptions Options | MaxRedirects=10 | svdh | E
Sets some special options for the rewrite engine
RewriteRule Pattern Substitution |  | svdh | E
Defines rules for the rewriting engine
RLimitCPU seconds|max [seconds|max] |  | svdh | C
Apache の子プロセスから起動されたプロセスの CPU 消費量を 制限する
RLimitMEM bytes|max [bytes|max] |  | svdh | C
Apache の子プロセスから起動されたプロセスのメモリ消費量を 制限する
RLimitNPROC number|max [number|max] |  | svdh | C
Apache の子プロセスから起動されたプロセスが起動するプロセスの 数を制限する
Satisfy Any|All | All | dh | C
ホストレベルのアクセス制御とユーザ認証との相互作用を指定
ScoreBoardFile file-path | logs/apache_status | s | M
子プロセスと連携するためのデータを保存する ファイルの位置
Script method cgi-script |  | svd | B
特定のリクエストメソッドに対して CGI スクリプトを 実行するように設定
ScriptAlias URL-path file-path|directory-path |  | sv | B
URL をファイルシステムの位置へマップし、マップ先を CGI スクリプトに指定
ScriptAliasMatch regex file-path|directory-path |  | sv | B
URL を正規表現を使ってファイルシステムの位置へマップし、マップ先を CGI スクリプトに指定
ScriptInterpreterSource Registry|Registry-Strict|Script | Script | svdh | C
CGI スクリプトのインタープリタの位置を調べるための手法
ScriptLog file-path |  | sv | B
CGI スクリプトのエラーログファイルの場所
ScriptLogBuffer bytes | 1024 | sv | B
スクリプトログに記録される PUT や POST リクエストの内容の上限
ScriptLogLength bytes | 10385760 | sv | B
CGI スクリプトのログファイルの大きさの上限
ScriptSock file-path | logs/cgisock | sv | B
CGI デーモンとの通信に使われるソケットの名前
SecureListen [IP-address:]portnumber Certificate-Name [MUTUAL] |  | s | B
Enables SSL encryption for the specified port
SendBufferSize bytes |  | s | M
TCP バッファサイズ
ServerAdmin email-address |  | sv | C
サーバがクライアントに送るエラーメッセージに含める電子メールの アドレス
ServerAlias hostname [hostname] ... |  | v | C
リクエストを名前ベースのバーチャルホストにマッチさせているときに 使用されるホストの別名
ServerLimit number | 256 (prefork), Serv + | s | M
設定可能なサーバプロセス数の上限
ServerName fully-qualified-domain-name[:port] |  | sv | C
サーバが自分自身を示すときに使うホスト名とポート
ServerPath URL-path |  | v | C
非互換のブラウザが名前ベースのバーチャルホストにアクセスしたときの ための互換用 URL パス名
ServerRoot directory-path | /usr/local/apache | s | C
インストールされたサーバのベースディレクトリ
ServerSignature On|Off|EMail | Off | svdh | C
サーバが生成するドキュメントのフッタを設定
ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full | Full | s | C
Server HTTP 応答ヘッダを設定する
SetEnv env-variable value |  | svdh | B
環境変数を設定する
SetEnvIf attribute regex [!]env-variable[=value] [[!]env-variable[=value]] ... |  | svdh | B
リクエストの属性に基づいて環境変数を設定する
SetEnvIfNoCase attribute regex [!]env-variable[=value] [[!]env-variable[=value]] ... |  | svdh | B
リクエストの属性に基づいて大文字小文字を区別せずに環境変数を設定する
SetHandler handler-name|None |  | svdh | C
マッチするファイルがハンドラで処理されるようにする
SetInputFilter filter[;filter...] |  | svdh | C
クライアントのリクエストや POST の入力を処理するフィルタを設定する
SetOutputFilter filter[;filter...] |  | svdh | C
サーバの応答を処理するフィルタを設定する
SSIEndTag tag | "-->" | sv | B
include 要素を終了させる文字列
SSIErrorMsg message | "[an error occurred + | svdh | B
SSI のエラーがあったときに表示されるエラーメッセージ
SSIStartTag tag | "<!--#" | sv | B
include 要素を開始する文字列
SSITimeFormat formatstring | "%A, %d-%b-%Y %H:%M + | svdh | B
日付けを現す文字列の書式を設定する
SSIUndefinedEcho string | "(none)" | sv | B
未定義の変数が echo されたときに表示される文字列
SSLCACertificateFile file-path |  | sv | E
File of concatenated PEM-encoded CA Certificates for Client Auth
SSLCACertificatePath directory-path |  | sv | E
Directory of PEM-encoded CA Certificates for Client Auth
SSLCARevocationFile file-path |  | sv | E
File of concatenated PEM-encoded CA CRLs for Client Auth
SSLCARevocationPath directory-path |  | sv | E
Directory of PEM-encoded CA CRLs for Client Auth
SSLCertificateChainFile file-path |  | sv | E
File of PEM-encoded Server CA Certificates
SSLCertificateFile file-path |  | sv | E
Server PEM-encoded X.509 Certificate file
SSLCertificateKeyFile file-path |  | sv | E
Server PEM-encoded Private Key file
SSLCipherSuite cipher-spec | ALL:!ADH:RC4+RSA:+H + | svdh | E
Cipher Suite available for negotiation in SSL handshake
SSLEngine on|off | off | sv | E
SSL Engine Operation Switch
SSLMutex type | none | s | E
Semaphore for internal mutual exclusion of operations
SSLOptions [+|-]option ... |  | svdh | E
Configure various SSL engine run-time options
SSLPassPhraseDialog type | builtin | s | E
Type of pass phrase dialog for encrypted private keys
SSLProtocol [+|-]protocol ... | all | sv | E
Configure usable SSL protocol flavors
SSLProxyCACertificateFile file-path |  | sv | E
File of concatenated PEM-encoded CA Certificates for Remote Server Auth
SSLProxyCACertificatePath directory-path |  | sv | E
Directory of PEM-encoded CA Certificates for Remote Server Auth
SSLProxyCARevocationFile file-path |  | sv | E
File of concatenated PEM-encoded CA CRLs for Remote Server Auth
SSLProxyCARevocationPath directory-path |  | sv | E
Directory of PEM-encoded CA CRLs for Remote Server Auth
SSLProxyCipherSuite cipher-spec | ALL:!ADH:RC4+RSA:+H + | svdh | E
Cipher Suite available for negotiation in SSL proxy handshake
SSLProxyEngine on|off | off | sv | E
SSL Proxy Engine Operation Switch
SSLProxyMachineCertificateFile filename |  | s | E
File of concatenated PEM-encoded client certificates and keys to be used by the proxy
SSLProxyMachineCertificatePath directory |  | s | E
Directory of PEM-encoded client certificates and keys to be used by the proxy
SSLProxyProtocol [+|-]protocol ... | all | sv | E
Configure usable SSL protocol flavors for proxy usage
SSLProxyVerify level | none | svdh | E
Type of remote server Certificate verification
SSLProxyVerifyDepth number | 1 | svdh | E
Maximum depth of CA Certificates in Remote Server Certificate verification
SSLRandomSeed context source [bytes] |  | s | E
Pseudo Random Number Generator (PRNG) seeding source
SSLRequire expression |  | dh | E
Allow access only when an arbitrarily complex boolean expression is true
SSLRequireSSL |  | dh | E
Deny access when SSL is not used for the HTTP request
SSLSessionCache type | none | s | E
Type of the global/inter-process SSL Session Cache
SSLSessionCacheTimeout seconds | 300 | sv | E
Number of seconds before an SSL session expires in the Session Cache
SSLVerifyClient level | none | svdh | E
Type of Client Certificate verification
SSLVerifyDepth number | 1 | svdh | E
Maximum depth of CA Certificates in Client Certificate verification
StartServers number | 5 | s | M
起動時に生成される子サーバプロセスの数
StartThreads number |  | s | M
起動時に生成されるスレッドの数
SuexecUserGroup User Group |  | sv |
CGI プログラムのユーザパーミッション、グループパーミッション
ThreadLimit number |  | s | M
設定可能な子プロセス毎のスレッド数の上限を 設定します
ThreadsPerChild number | 50 | s | M
子プロセスそれぞれに生成されるスレッド数
ThreadStackSize number | 65536 | s | M
Determine the stack size for each thread
TimeOut seconds | 300 | s | C
各イベントについて、リクエストを失敗させるまでにサーバが 待つ時間を設定
TransferLog file|pipe |  | sv | B
ログファイルの位置を指定
TypesConfig file-path | conf/mime.types | s |
mime.types ファイルの位置
UnsetEnv env-variable [env-variable] ... |  | svdh | B
環境から変数を取り除く
UseCanonicalName On|Off|Dns | On | svd | C
サーバが自分自身の名前とポートを決定する方法を設定する
User unix-userid | #-1 | sv | M
リクエストに応答する際に用いるユーザ ID
UserDir directory-filename | public_html | sv | B
ユーザ専用ディレクトリの位置
VirtualDocumentRoot interpolated-directory|none | none | sv | E
Dynamically configure the location of the document root for a given virtual host
VirtualDocumentRootIP interpolated-directory|none | none | sv | E
Dynamically configure the location of the document root for a given virtual host
<VirtualHost addr[:port] [addr[:port]] ...> ... </VirtualHost> |  | s | C
特定のホスト名や IP アドレスのみに適用されるディレクティブを 囲む
VirtualScriptAlias interpolated-directory|none | none | sv | E
Dynamically configure the location of the CGI directory for a given virtual host
VirtualScriptAliasIP interpolated-directory|none | none | sv | E
Dynamically configure the location of the cgi directory for a given virtual host
Win32DisableAcceptEx |  | s | M
ネットワーク接続の受け付けに accept() をAcceptEx の代わりに使う
XBitHack on|off|full | off | svdh | B
実行ビットが設定されたファイルの SSI ディレクティブを 解析する


Site Map - Apache HTTP サーバ

Apache HTTP サーバ バージョン 2.0

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.0

Site Map

このページは現時点で利用可能な Apache HTTP サーババージョン 2.0 のドキュメンテーション の一覧です。

リリースのメモ

  • 1.3 から 2.0 へのアップグレード
  • Apache 2.0 の新機能
  • Apache License

Apache HTTP サーバの使用

  • Apache のコンパイルとインストール
  • Apache の起動
  • サーバの停止と再起動
  • 設定ファイル
  • Directory, Location, Files セクションの動作方法
  • サーバ全体の設定
  • ログファイル
  • URL からファイルシステム上の位置へのマップ
  • セキュリティのコツ
  • 動的共有オブジェクト (DSO) サポート
  • コンテントネゴシエーション
  • カスタムエラーレスポンス
  • Apache が使用するアドレスとポートの設定
  • マルチプロセッシングモジュール (MPM)
  • Apache における環境変数
  • Apache のハンドラの使用
  • フィルタ
  • suEXEC サポート
  • 性能に関するヒント
  • URL リライトガイド

Apache バーチャルホストドキュメント

  • 概略
  • 名前ベースのバーチャルホスト
  • IP ベースのバーチャルホストのサポート
  • 動的に設定された大規模バーチャルホスト
  • VirtualHost の例
  • バーチャルホストのマッチングの詳しい説明
  • ファイル記述子の限界
  • DNS と Apache とに関係する問題

Apache サーバのよくある質問

  • 概略
  • サポート
  • エラーメッセージ

Apache の SSL/TLS 暗号化

  • 概略
  • SSL/TLS 暗号化: 入門
  • SSL/TLS 暗号化: 互換性
  • SSL/TLS 暗号化: ハウツー
  • SSL/TLS 暗号化: FAQ

ガイド、チュートリアル、ハウツー

  • 概略
  • 認証
  • CGI による動的コンテンツ
  • Server Side Includes 入門
  • .htaccess ファイル
  • ユーザ毎のウェブディレクトリ
  • Apache チュートリアル

プラットフォーム固有の情報

  • 概略
  • Microsoft Windows での Apache の使用
  • Microsoft Windows での Apache のコンパイル
  • Novell NetWare で Apache を使う
  • HPUX で高性能ウェブサーバを実行する
  • EBCDIC 版 Apache

Apache HTTP サーバとサポートプログラム

  • 概略
  • マニュアルページ: httpd
  • マニュアルページ: ab
  • マニュアルページ: apachectl
  • マニュアルページ: apxs
  • マニュアルページ: configure
  • マニュアルページ: dbmmanage
  • マニュアルページ: htdigest
  • マニュアルページ: htpasswd
  • マニュアルページ: logresolve
  • マニュアルページ: rotatelogs
  • マニュアルページ: suexec
  • 他のプログラム

Apache その他

  • 概略
  • カスタマイズされた 国際化サーバエラーメッセージ
  • FIN_WAIT_2 のコネクションと Apache
  • クライアントの既知の問題
  • 記述子と Apache
  • 関連する標準規格

Apache モジュール

  • Apache ディレクティブの説明に使われる用語
  • Apache ディレクティブを説明に使われる用語
  • Apache コア機能
  • Apache MPM 共通ディレクティブ
  • Apache MPM beos
  • Apache MPM leader
  • Apache MPM netware
  • Apache MPM os2
  • Apache MPM perchild
  • Apache MPM prefork
  • Apache MPM threadpool
  • Apache MPM winnt
  • Apache MPM worker
  • Apache モジュール mod_access
  • Apache モジュール mod_actions
  • Apache モジュール mod_alias
  • Apache モジュール mod_asis
  • Apache モジュール mod_auth
  • Apache モジュール mod_auth_anon
  • Apache モジュール mod_auth_dbm
  • Apache モジュール mod_auth_digest
  • Apache モジュール mod_auth_ldap
  • Apache モジュール mod_autoindex
  • Apache モジュール mod_cache
  • Apache モジュール mod_cern_meta
  • Apache モジュール mod_cgi
  • Apache モジュール mod_cgid
  • Apache モジュール mod_charset_lite
  • Apache モジュール mod_dav
  • Apache モジュール mod_dav_fs
  • Apache モジュール mod_deflate
  • Apache モジュール mod_dir
  • Apache モジュール mod_disk_cache
  • Apache モジュール mod_echo
  • Apache モジュール mod_env
  • Apache モジュール mod_example
  • Apache モジュール mod_expires
  • Apache モジュール mod_ext_filter
  • Apache モジュール mod_file_cache
  • Apache モジュール mod_headers
  • Apache モジュール mod_imap
  • Apache モジュール mod_include
  • Apache モジュール mod_info
  • Apache モジュール mod_isapi
  • Apache モジュール mod_ldap
  • Apache モジュール mod_log_config
  • Apache モジュール mod_log_forensic
  • Apache モジュール mod_logio
  • Apache モジュール mod_mem_cache
  • Apache モジュール mod_mime
  • Apache モジュール mod_mime_magic
  • Apache モジュール mod_negotiation
  • Apache モジュール mod_nw_ssl
  • Apache モジュール mod_proxy
  • Apache モジュール mod_proxy_connect
  • Apache モジュール mod_proxy_ftp
  • Apache モジュール mod_proxy_http
  • Apache モジュール mod_rewrite
  • Apache モジュール mod_setenvif
  • Apache モジュール mod_so
  • Apache モジュール mod_speling
  • Apache モジュール mod_ssl
  • Apache モジュール mod_status
  • Apache モジュール mod_suexec
  • Apache モジュール mod_unique_id
  • Apache モジュール mod_userdir
  • Apache モジュール mod_usertrack
  • Apache モジュール mod_vhost_alias

開発者のためのドキュメント

  • 概略
  • Apache API メモ
  • APR のメモリアロケーションのデバッグ
  • Apache 2.0 の説明を書く
  • Apache 2.0 フック関数
  • Apache 1.3 から Apache 2.0 にモジュールを 移植する
  • Apache 2.0 のリクエスト処理
  • Apache 2.0 のフィルタの動作の仕方

用語集と索引

  • 用語集
  • モジュール索引
  • ディレクティブ索引
  • ディレクティブ クイックリファレンス


Apache 2.0 Thread Safety Issues - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Apache 2.0 Thread Safety Issues

When using any of the threaded mpms in Apache 2.0 it is important that every function called from Apache be thread safe. When linking in 3rd party extensions it can be difficult to determine whether the resulting server will be thread safe. Casual testing generally won't tell you this either as thread safety problems can lead to subtle race conditons that may only show up in certain conditions under heavy load.

Global and static variables

When writing your module or when trying to determine if a module or 3rd party library is thread safe there are some common things to keep in mind.

First, you need to recognize that in a threaded model each individual thread has its own program counter, stack and registers. Local variables live on the stack, so those are fine. You need to watch out for any static or global variables. This doesn't mean that you are absolutely not allowed to use static or global variables. There are times when you actually want something to affect all threads, but generally you need to avoid using them if you want your code to be thread safe.

In the case where you have a global variable that needs to be global and accessed by all threads, be very careful when you update it. If, for example, it is an incrementing counter, you need to atomically increment it to avoid race conditions with other threads. You do this using a mutex (mutual exclusion). Lock the mutex, read the current value, increment it and write it back and then unlock the mutex. Any other thread that wants to modify the value has to first check the mutex and block until it is cleared.

If you are using APR, have a look at the apr_atomic_* functions and the apr_thread_mutex_* functions.

errno

This is a common global variable that holds the error number of the last error that occurred. If one thread calls a low-level function that sets errno and then another thread checks it, we are bleeding error numbers from one thread into another. To solve this, make sure your module or library defines _REENTRANT or is compiled with -D_REENTRANT. This will make errno a per-thread variable and should hopefully be transparent to the code. It does this by doing something like this:

#define errno (*(__errno_location()))

which means that accessing errno will call __errno_location() which is provided by the libc. Setting _REENTRANT also forces redefinition of some other functions to their *_r equivalents and sometimes changes the common getc/putc macros into safer function calls. Check your libc documentation for specifics. Instead of, or in addition to _REENTRANT the symbols that may affect this are _POSIX_C_SOURCE, _THREAD_SAFE, _SVID_SOURCE, and _BSD_SOURCE.

Common standard troublesome functions

Not only do things have to be thread safe, but they also have to be reentrant. strtok() is an obvious one. You call it the first time with your delimiter which it then remembers and on each subsequent call it returns the next token. Obviously if multiple threads are calling it you will have a problem. Most systems have a reentrant version of of the function called strtok_r() where you pass in an extra argument which contains an allocated char * which the function will use instead of its own static storage for maintaining the tokenizing state. If you are using APR you can use apr_strtok().

crypt() is another function that tends to not be reentrant, so if you run across calls to that function in a library, watch out. On some systems it is reentrant though, so it is not always a problem. If your system has crypt_r() chances are you should be using that, or if possible simply avoid the whole mess by using md5 instead.

Common 3rd Party Libraries

The following is a list of common libraries that are used by 3rd party Apache modules. You can check to see if your module is using a potentially unsafe library by using tools such as ldd(1) and nm(1). For PHP, for example, try this:

% ldd libphp4.so
libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)
libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)
libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)
libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)
libz.so.1 => /usr/lib/libz.so.1 (0x403e2000)
libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)
libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11 (0x40411000)
libming.so => /usr/lib/libming.so (0x40449000)
libm.so.6 => /lib/libm.so.6 (0x40487000)
libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)
libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)
libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)
libssl.so.2 => /lib/libssl.so.2 (0x40532000)
libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)
libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)
libdl.so.2 => /lib/libdl.so.2 (0x40634000)
libnsl.so.1 => /lib/libnsl.so.1 (0x40637000)
libc.so.6 => /lib/libc.so.6 (0x4064b000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)

In addition to these libraries you will need to have a look at any libraries linked statically into the module. You can use nm(1) to look for individual symbols in the module.

Library List

Please drop a note to dev@httpd.apache.org if you have additions or corrections to this list.

Library | Version | Thread Safe? | Notes
ASpell/PSpell |  | ? |
Berkeley DB | 3.x, 4.x | Yes | Be careful about sharing a connection across threads.
bzip2 |  | Yes | Both low-level and high-level APIs are thread-safe. However, high-level API requires thread-safe access to errno.
cdb |  | ? |
C-Client |  | Perhaps | c-client uses strtok() and gethostbyname() which are not thread-safe on most C library implementations. c-client's static data is meant to be shared across threads. If strtok() and gethostbyname() are thread-safe on your OS, c-client may be thread-safe.
cpdflib |  | ? |
libcrypt |  | ? |
Expat |  | Yes | Need a separate parser instance per thread
FreeTDS |  | ? |
FreeType |  | ? |
GD 1.8.x |  | ? |
GD 2.0.x |  | ? |
gdbm |  | No | Errors returned via a static gdbm_error variable
ImageMagick | 5.2.2 | Yes | ImageMagick docs claim it is thread safe since version 5.2.2 (see Change log).
Imlib2 |  | ? |
libjpeg | v6b | ? |
libmysqlclient |  | Yes | Use mysqlclient_r library variant to ensure thread-safety. For more information, please read http://www.mysql.com/doc/en/Threaded_clients.html.
Ming | 0.2a | ? |
Net-SNMP | 5.0.x | ? |
OpenLDAP | 2.1.x | Yes | Use ldap_r library variant to ensure thread-safety.
OpenSSL | 0.9.6g | Yes | Requires proper usage of CRYPTO_num_locks, CRYPTO_set_locking_callback, CRYPTO_set_id_callback
liboci8 (Oracle 8+) | 8.x,9.x | ? |
pdflib | 5.0.x | Yes | PDFLib docs claim it is thread safe; changes.txt indicates it has been partially thread-safe since V1.91: http://www.pdflib.com/products/pdflib/index.html.
libpng | 1.0.x | ? |
libpng | 1.2.x | ? |
libpq (PostgreSQL) | 7.x | Yes | Don't share connections across threads and watch out for crypt() calls
Sablotron | 0.95 | ? |
zlib | 1.1.4 | Yes | Relies upon thread-safe zalloc and zfree functions Default is to use libc's calloc/free which are thread-safe.


Frequently Asked Questions - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > FAQ

Frequently Asked Questions

The latest version of this FAQ is always available from the main Apache web site, at <http://httpd.apache.org/docs-2.0/faq/>.

Since Apache 2.0 is quite new, we don't yet know what the Frequently Asked Questions will be. While this section fills up, you should also consult the Apache 1.3 FAQ to see if your question is answered there.

Topics

Support
What do I do when I have problems?
Error Messages
What does this error message mean?

Support

  • "Why can't I ...? Why won't ... work?" What to do in case of problems
  • Whom do I contact for support?

"Why can't I ...? Why won't ... work?" What to do in case of problems

If you are having trouble with your Apache server software, you should take the following steps:

Check the errorlog!
Apache tries to be helpful when it encounters a problem. In many cases, it will provide some details by writing one or messages to the server error log. Sometimes this is enough for you to diagnose & fix the problem yourself (such as file permissions or the like). The default location of the error log is /usr/local/apache2/logs/error_log, but see the ErrorLog directive in your config files for the location on your server.
Check the FAQ!
The latest version of the Apache Frequently-Asked Questions list can always be found at the main Apache web site.
Check the Apache bug database
Most problems that get reported to The Apache Group are recorded in the bug database. Please check the existing reports, open and closed, before adding one. If you find that your issue has already been reported, please don't add a "me, too" report. If the original report isn't closed yet, we suggest that you check it periodically. You might also consider contacting the original submitter, because there may be an email exchange going on about the issue that isn't getting recorded in the database.
Ask in a user support forum

Apache has an active community of users who are willing to share their knowledge. Participating in this community is usually the best and fastest way to get answers to your questions and problems.

Users mailing list

USENET newsgroups:

  • comp.infosystems.www.servers.unix [news] [google]
  • comp.infosystems.www.servers.ms-windows [news] [google]
  • comp.infosystems.www.authoring.cgi [news] [google]
If all else fails, report the problem in the bug database

If you've gone through those steps above that are appropriate and have obtained no relief, then please do let the httpd developers know about the problem by logging a bug report.

If your problem involves the server crashing and generating a core dump, please include a backtrace (if possible). As an example,

# cd ServerRoot
# dbx httpd core
(dbx) where

(Substitute the appropriate locations for your ServerRoot and your httpd and core files. You may have to use gdb instead of dbx.)

Whom do I contact for support?

With several million users and fewer than forty volunteer developers, we cannot provide personal support for Apache. For free support, we suggest participating in a user forum.

Professional, commercial support for Apache is available from a number of companies.

Error Messages

  • Invalid argument: core_output_filter: writing data to the network
  • AcceptEx failed
  • Premature end of script headers

Invalid argument: core_output_filter: writing data to the network

Apache uses the sendfile syscall on platforms where it is available in order to speed sending of responses. Unfortunately, on some systems, Apache will detect the presence of sendfile at compile-time, even when it does not work properly. This happens most frequently when using network or other non-standard file-system.

Symptoms of this problem include the above message in the error log and zero-length responses to non-zero-sized files. The problem generally occurs only for static files, since dynamic content usually does not make use of sendfile.

To fix this problem, simply use the EnableSendfile directive to disable sendfile for all or part of your server. Also see the EnableMMAP, which can help with similar problems.

AcceptEx Failed

If you get error messages related to the AcceptEx syscall on win32, see the Win32DisableAcceptEx directive.

Premature end of script headers

Most problems with CGI scripts result in this message written in the error log together with an Internal Server Error delivered to the browser. A guide to helping debug this type of problem is available in the CGI tutorial.