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

Apache HTTP サーバ バージョン 2.2

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

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

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

リリースノート

  • Apache 2.1/2.2 の新機能
  • Apache 2.0 の新機能
  • 2.0 から 2.2 へのアップグレード
  • 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 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


2.0 から 2.2 へのアップグレード - Apache HTTP サーバ バージョン 2.2

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

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

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

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

この文書は 2.0 から 2.2 への変更点だけを説明します。 もし 1.3 からのアップグレードをするのであれば、1.3 から 2.0 へのアップグレードの文書 も参考にしてください。

参照

  • Apache 2.2 の新機能 の概要

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

コンパイルの過程はバージョン 2.0 で使われているものと非常に よく似ています。古い configure コマンドライン (インストールしたサーバのディレクトリにある build/config.nice) が、ときには使えるでしょう。最も大きな変更点はモジュールの名前の 変更を入れるために必要とされるもので、特に認証と認可のモジュール の変更点です。 変更の詳細の一部は:

  • mod_imap は mod_imagemap に名前を 変更しました
  • mod_auth は mod_auth_basic と、 mod_authn_file, mod_authz_user そして、mod_authz_groupfile に分かれ ました。
  • mod_access は mod_authz_host に名前を 変更しました。
  • mod_auth_ldap は mod_authnz_ldap に 名前を変更しました。
  • APR 1.0 API を必要とするようにアップグレードされました。
  • バンドルされている PCRE は、 5.0 にアップデートされています。

実行時の設定の変更

あなたが使っているバージョン 2.0 用の設定ファイルとスタート アップスクリプトは通常バージョン 2.2 でも変更せずに使えます。 特定の設定については 以下に議論するようにいくらか小さな 調整が必要となるかもしれません。 さらに、 LoadModule ディレクティブを使って動的にモジュールを読み込んで使って いる場合には、上に挙げたモジュール名の変更を考慮する必要が あるでしょう。

もし、あなたがバージョン 2.2 のデフォルトの実行時設定を使う ことを選ぶなら 最も基本的な設定以外は除外されていて 非常に 簡単化されていることに気付くでしょう。 より高度な機能に関する実行時の設定の例が、インストールした サーバの conf/extra/ のディレクトリに入ります。 デフォルトの設定ファイルは conf/original にインストールされます。

実行時の設定の主な変更点を挙げると:

  • apachectl のオプションであった startssl は無くなりました。 SSL サポートを有効にするには httpd.conf を 編集して関連する mod_ssl ディレクティブを 入れるようにし、それから apachectl start で サーバをスタートしてください。 mod_ssl を有効にする設定ファイルの例が conf/extra/httpd-ssl.conf にあります。
  • デフォルトの設定としての UseCanonicalName は Off となりました。もし、このディレクティブを 実行時設定ファイルに書いていなかったら、旧バージョンでの ふるまいを維持したい場合には UseCanonicalName On を 加えておくことができます。
  • mod_userdir モジュールは、 ディレクトリ名を指定したUserDir ディレクティブが 設定ファイルに書かれていなければ リクエスト時に動作しないようになりました。 古いデフォルト 動作を復元させたい場合には、設定ファイルに UserDir public_html を入れておいてください。
  • mod_auth_digest にあった AuthDigestFile ディレクティブは、 AuthUserFile に吸収され、 mod_authn_file の一部となりました。

その他の変更

  • Apache 2.0 で実験的なモジュールだった mod_cache は標準モジュールになりました。
  • Apache 2.0 で実験的なモジュールだった mod_disk_cache は標準モジュールになりました。
  • Apache 2.0 で実験的なモジュールだった mod_mem_cache は標準モジュールになりました。
  • Apache 2.0 で実験的なモジュールだった mod_charset_lite は標準モジュールになりました。
  • Apache 2.0 で実験的なモジュールだった mod_dumpio は標準モジュールになりました。

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

バージョン 2.0 のために設計された多くのサードパーティ モジュールは Apache HTTP サーバ・バージョン 2.2 で、変更無しで 動作するでしょう。しかし、全てのモジュールはロードの前に再コンパイル する必要があります。


Apache 2.2 の新機能の概要 - Apache HTTP サーバ バージョン 2.2

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

Apache 2.2 の新機能の概要

この文書では、Apache HTTP サーババージョン 2.0 と 2.2 の主な違いについて 記述しています。 バージョン 1.3 からの新機能 については 2.0 の新機能 の文書をご覧下さい。

コア機能の拡張

Authn/Authz
認証と認可のモジュールは再構成されました。 新しい mod_authn_alias モジュールは認証の設定を 非常に簡単化してくれます。 モジュール名の変更 と 開発者向けの変更 を見てください。 そこには、 これらの変更がどのようにユーザとモジュール開発者に影響するかが 書いてあります。
キャッシュ
mod_cache と mod_disk_cache そして、 mod_mem_cache はとても多くの変更を受けていて、 製品としての品質があると考えられます。 htcacheclean が導入され、 mod_disk_cache の設定がシンプルになりました。
設定
デフォルトの設定レイアウトは簡単化されモジュラー化されました。 共通して使用される機能に使われる設定の断片は、今や Apache に 組み込まれていて、メインのサーバ設定に容易に追加することが できます。
緩やかな停止
最新の prefork と、worker そして event MPM は httpd を、 graceful-stop のシグナル経由で、緩やかにシャットダウンさせます。 GracefulShutdownTimeout のディレクティブがオプションのタイムアウトとして追加され、これに よってhttpd は、サービス中リクエストの 状態如何に関わらず強制終了します。
プロキシ
新しいモジュール mod_proxy_balancer は、 負荷分散サービスを mod_proxy に提供します。 新しいモジュール mod_proxy_ajp は、 Apache Tomcat で使われる、 Apache JServ Protocol version 1.3 の サポートを提供します。
正規表現ライブラリの更新
Perl Compatible Regular Expression Library (PCRE: Perl 互換正規表現ライブラリ) の バージョン 5.0 を入れました。 httpd の configure 時に --with-pcre のフラグを渡すことで、システムが インストールしている PCRE を利用するように設定できます。
高機能フィルター
mod_filter は、出力フィルターの連鎖に動的な 設定を導入しています。 これは、2.0 アーキテクチャにある、ややこしい依存と順序問題を 回避するために、リクエスト又はレスポンスヘッダや環境変数に 基づいて、フィルターを条件付きで挿入できるようにしています。
大ファイルサポート
httpd は、最新の 32-bit Unix システムでの 2GB より大きなファイルのサポートを取り入れてビルドされます。 >2GB であるリクエストボディの扱いも追加されています。
Event MPM
event MPM は、 Keep Alive のリクエストを受け付けて 処理するのに、別個のスレッドを使います。伝統的には Keep Alive の リクエストを扱うのに、ワーカを使用する必要がありました。 Keep Alive のタイムアウトが来るまでは、そのワーカを再利用 できませんでした。
SQL データベースのサポート

mod_dbdと、 apr_dbd の枠組みを 併用することで、SQL を必要とするモジュールを直接サポートします。 スレッド MPM でコネクションプールをサポートします。

モジュールの拡張

Authn/Authz
aaa ディレクトリのモジュールは名前を変えられ、ダイジェスト認証を よりよくサポートするようになっています。 例えば、 mod_auth は mod_auth_basic と mod_authn_file に分けられ、 mod_auth_dbm は mod_authn_dbm と名前を変更し、 mod_access は、 mod_authz_hostと名前を変えられています。 また、新しいモジュール mod_authn_alias ができて、 ある種の認証設定を簡単化します。
mod_authnz_ldap
このモジュールは 2.0 モジュールmod_auth_ldap の 2.2 Authn/Authz 枠組みへの取り込みです。 LDAP の属性値と複雑な検索フィルターを使って Require ディレクティブに 取り込むことを新機能として含んでいます。
mod_authz_owner
ファイルシステムの所有者に基づいてファイルへのアクセスを認可する 新しいモジュールです。
mod_version
稼働するサーバのバージョン数に基づいて設定ブロックを有効にする、 新しいモジュールです。
mod_info
新しく、 ?config 引数を追加しました。 これは、Apache によって解析される設定ディレクティブを、ファイル名と 行数を付けて表示します。 また、モジュールは httpd -V と同様の、リクエストフックの 順序と追加のビルド情報を表示します。
mod_ssl
RFC 2817 に従って、非暗号クリアテキストから TLS 暗号へのコネクション グレードアップを追加しました。
mod_imagemap
mod_imap は、ユーザの混同を避けるため、 mod_imagemap へと名前の変更を行いました。

プログラムの拡張

httpd
新しくコマンドラインのオプションとして -M が追加されました。このオプションでは現在の設定で読み込まれる 全てのモジュールがリストされます。 -l オプションとは違って、このリストには mod_so で読み込まれる DSO を含んでいます。
httxt2dbm
テキストの入力から dbm ファイルを生成するのに使われる、新しい プログラムです。 RewriteMap で使われる dbm のマップタイプに使用されます。

モジュール開発者向けの変更

APR 1.0 API
Apache 2.2 は APR 1.0 API　を使用します。 使われなくなった関数とシンボルは APR と APR-Utilから削除されました。 詳細については APR Webサイトを見てください。
Authn/Authz
付属の認証と認可のモジュールは次のように名前を変更しました：
  • mod_auth_* -> HTTP 認証メカニズムを実装する モジュール
  • mod_authn_* -> 認証バックエンドを提供する モジュール
  • mod_authz_* -> 認可（又はアクセスの制御）を 実装するモジュール
  • mod_authnz_* -> 認証と認可の両方を実装する モジュール
新しい認証バックエンド提供のスキームがあって、新しいバックエンドの 構築を非常にやさしくしてくれます。
接続エラーのログ
新しい関数 ap_log_cerror が、クライアントの接続の 際のエラーを記録するために追加されました。ログの出力メッセージには クライアントの IP アドレスが含まれます。
設定テストのフックを追加
あたらしいフックである test_config が追加されました。 これにより、ユーザが -t を httpd の 起動時に与えた時だけに実行される、特別なコードを入れることが できます。
スレッド MPM's のスタックサイズ設定
新しいディレクティブである、 ThreadStackSize が全てのスレッド MPM のスタックサイズの 設定に追加されました。これはサードパーティのモジュールで、 デフォルトのスタックサイズが小さいことがあるために、必要と なりました。
出力フィルターのプロトコルハンドリング
過去においては、個々のフィルターは、それぞれが影響をおよぼす ところでは、応答ヘッダを正しく生成する責任がありました。 フィルターは、今は、共通するプロトコル管理を ap_register_output_filter_protocol 又は ap_filter_protocol を呼び出して mod_filter に 委任することができます。
モニターフックを追加
モニターフックを使って、モジュールを親 (root) のプロセスで レギュラー又はスケジュールのジョブを実行することが できます。
正規表現の API を変更
pcreposix.h ヘッダは既に削除されました; 新しい ap_regex.h によって置き換えました。 古いヘッダである POSIX.2 regex.h によって 公開されている実装は、今は、ap_regex.h の ap_ 名前空間の下に存在します。 regcomp と、 regexec 等々への呼び出しは ap_regcomp, ap_regexec などに置き換え られます。
DBD フレームワーク (SQL データベース API)

Apache 1.x と 2.0 では、SQL バックエンドを必要とするモジュールは それを自分で管理する責任がありました。車輪の再発明の問題を除いても、 これはとても非効率的なことです。例えばそれぞれのモジュールが自分 で接続を維持しなければなりません。

Apache 2.1 とその後は、 ap_dbd API が提供されており、 これを使ってデータベースの接続（スレッド化された又はスレッドでない MPM に最適化した戦略を含んで）を管理することができます。 一方、APR 1.2 および以降では apr_dbd API でデータ ベースとのやりとりを提供しています。

新しいモジュールはこれらを全ての SQL データベースの運用に利用する べきです。現存のアプリケーションは、実現可能であればどこでもこれらを 使うように更新され、透過的にあるいは推奨オプションとして ユーザに提供されるべきです。


Apache 2.0 の新機能の概要 - Apache HTTP サーバ バージョン 2.2

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

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 [2001:db8::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 Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2

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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


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

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

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

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

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

Apache HTTPd では他の Open Source プロジェクトと同様、 ビルド環境構築に libtool と autoconf を使うようになっています。

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

参照

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

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

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

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

Apache HTTP サーバのコンパイルとインストールに必要なものをはじめとして、 コンパイルとインストールについては、次に詳しく記述されています。

必要なもの

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

ディスクスペース
ディスクに少なくとも 50 MB の一時的な空き容量があるように 気を付けてください。インストール後は Apache は 10 MB 程度の ディスクスペースを占めます。実際に必要になるディスクスペースは、 設定オプションやサードパーティー製モジュールをどう選択するかによって 大きく変わるでしょう。
ANSI-C コンパイラとビルドシステム
ANSI-C コンパイラをインストールしておいて下さい。お薦めは Free Software Foundation (FSF) による GNU C compiler (GCC) です。GCC がない場合は、 少なくとも提供されているコンパイラが ANSI 準拠であることを確認しておいて下さい。 それから、変数 PATH には make といった基本的なビルドツールが含まれている必要があります。
時刻を正確にする
HTTP プロトコルの要素は日時の時刻で表現されています。ですから、 正確な時刻にシンクロさせる機能をシステムに設定することを吟味してみて下さい。 Network Time Protocol (NTP) をベースとした ntpdate や xntpd プログラムが この目的によく用いられます。NTP ソフトウェアや公開 NTP サーバに関する詳細は、NTP ホームページ をご覧下さい。
Perl 5 [オプション]
提供されているスクリプト幾つか、例えば apxs や dbmmanage は Perl で書かれているので、Perl 5 インタプリタが必要になります (5.003 以降)。 Perl インタプリタを複数インストールしている (たとえば全体のシステムの一部 としてインストールされている Perl 4 と、自分で追加でインストールした Perl 5 があるなどの) 場合、--with-perl オプション (下記参照) を使って configure が意図したものを使うように 明示的に指定すると良いでしょう。 configure スクリプトで Perl 5 インタプリタが 見つからない場合は、この影響を受けるサポートスクリプトが使えなくなります。 もちろん、Apache HTTPd のコンパイルとインストールは問題なく行えます。
apr/apr-util >= 1.2
apr と apr-util は Apache HTTPd ソースリリースに同梱されていますし、どんな環境でもほぼ問題なく 使えるはずです。ただし apr と apr-util のバージョン 1.0 や 1.1 がシステムの一部として既にインストールされている場合、 apr/apr-util を 1.2 にアップグレードするか、 httpd を隔離した環境でビルドする必要があります。 バンドルされている apr/apr-util を使って アップグレードする場合は、これらを手動でインストールする必要があります :

# Build and install apr 1.2
cd srclib/apr
./configure --prefix=/usr/local/apr-httpd/
make
make install

# Build and install apr-util 1.2
cd ../apr-util
./configure --prefix=/usr/local/apr-util-httpd/ --with-apr=/usr/local/apr-httpd/
make
make install

# Configure httpd
cd ../../
./configure --with-apr=/usr/local/apr-httpd/ --with-apr-util=/usr/local/apr-util-httpd/

ダウンロード

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

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

展開

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

$ gzip -d httpd-NN.tar.gz
$ tar xvf httpd-NN.tar

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

ソースツリーを設定する

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

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

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

この時点で、モジュール を有効にしたり 無効にしたりすることで Apache HTTPd 本体に含まれる 機能 を指定できます。Apache HTTPd 本体にはデフォルトで、モジュールの 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 HTTPd の様々なパーツをビルドすることができます。 次のコマンドを単純に実行するだけです:

$ make

基本的な設定をするのに数分かかりますが、 あらかじめご了承ください。 また、時間はハードウェアや有効にしたモジュールの数に 大きく依存するでしょう。

インストール

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

$ make install

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

カスタマイズ

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

$ vi PREFIX/conf/httpd.conf

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

テスト

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

$ PREFIX/bin/apachectl -k start

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

$ PREFIX/bin/apachectl -k stop

アップグレード

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

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

マイナーバージョンでアップグレードする場合は、 既にインストールされているサーバの build ディレクトリ内か、 以前インストールに使ったソースコードツリーの最上位ディレクトリ内にある、 config.nice ファイルを探してください。 このファイルにはソースツリーを設定した時に使った configure コマンドラインが、そのまま入っています。 次のバージョンにアップグレードする場合は config.nice ファイルを新しいバージョンのソースツリーにコピーし、 必要であればそれを編集した後に、次のように実行します。

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

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


Apache の起動 - Apache HTTP サーバ バージョン 2.2

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

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 サーバ バージョン 2.2

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

停止と再起動

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

この文書では 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, graceful-stop を指定できます。 これらは httpd の引数ですが、 制御用のスクリプト apachectl はそれらの引数をそのまま httpd に渡します。

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

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

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

急な停止

シグナル: TERM
apachectl -k stop

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

緩やかな再起動 (Graceful Restart)

シグナル: USR1
apachectl -k graceful

親プロセスは USR1 あるいは 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 が送られた場合に サーバ統計がゼロに設定されることに注意してください。

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

緩やかな停止 (Graceful Stop)

Signal: WINCH
apachectl -k graceful-stop

親プロセスは WINCH あるいは graceful-stop シグナルを受け取ると、子プロセスに現在のリクエストの処理の後に終了する (あるいは何もしていなければすぐに終了する) ように助言します。 その後に親プロセスは PidFile を削除し、全ポートからの Listen をやめます。 親プロセスはこのまま継続し、子プロセスがリクエストを処理する のを監視しています。子プロセスが全て処理を終えて終了するか、GracefulShutdownTimeout で指定されたタイムアウトに達した後で、親プロセスも終了します。 タイムアウトに達した場合は、残りの子プロセスには TERM シグナルが送信され、強制終了されます。

TERM シグナルによって、"graceful" 状態にある親プロセスと 子プロセスの全てが直ちに終了します。ただし、 PidFile は既に削除 されてしまっていますので、apachectl や httpd でこれらにシグナルを送ることはできません。

graceful-stop シグナルを使うと、まったく同一の設定 ファイルを使った httpd を同時に複数起動することが できるようになります。 この機能を使うと、Apache をアップグレードする際にとても便利でしょう。 ただし、設定によってはデッドロックや競合状態 (レースコンディション) を引き起こすかもしれません。

Lockfile や ScriptSock などでのディスク上のファイルについては、 ファイルにサーバの PID が含まれるようになっていて、httpd が複数同時に動作していても 問題がおきないように注意が払われています。 しかし、設定ディレクティブやサードパーティ製モジュール、CGI で使用される永続的な ディスクを使ったロックや状態ファイルを活用している場合についても、 複数の httpd が動作している状態であっても、それぞれで ファイルを上書きしないように注意しなければなりません。

潜在的な競合状態についても心配する必要があるでしょう。 たとえば rotatelogs 形式のパイプによるログなどが該当します。 複数の rotatelogs インスタンスが同時に同じログファイルを rotate しようとすると、ログファイルが破壊されるかもしれません。


設定ファイル - Apache HTTP サーバ バージョン 2.2

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

設定ファイル

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

この文書では、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 ファイルはすべてのリクエストで読み込まれるため、 変更はすぐに反映されます。

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

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


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

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

セクションの設定

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

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

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

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

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

<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>

<IfVersion> ディレクティブは <IfDefine> や <IfModule> によく似ていますが、サーバが特定のバージョンであるときにのみ有効にしたい ディレクティブを囲むのに使います。 テストスイートや大規模ネットワークなどの、さまざまなバージョンの httpd を 異なる設定で扱う用途向けにデザインされています。

<IfVersion >= 2.1>
# this happens only in versions greater or
# equal 2.1.0.
 </IfVersion>

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

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

最もよく使われる設定のセクションコンテナはファイルシステムやウェブ空間の 特定の場所の設定を変更するものです。まず、この二つの違いを理解することが 大切です。ファイルシステムはオペレーティングシステムから見たディスクの内容です。 たとえば、デフォルトのインストールでは 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 ワイルドカードセクションは次のようになります。

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

mod_proxy でリクエストが処理される場合は、 処理順番のうち、<Directory> コンテナの部分が <Proxy> コンテナに取って代わられます。

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

技術メモ

実際には、名前を変換する段階 (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>

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


Caching Guide - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2

Caching Guide

This document supplements the mod_cache, mod_disk_cache, mod_mem_cache, mod_file_cache and htcacheclean reference documentation. It describes how to use Apache's caching features to accelerate web and proxy serving, while avoiding common problems and misconfigurations.

Introduction

As of Apache HTTP server version 2.2 mod_cache and mod_file_cache are no longer marked experimental and are considered suitable for production use. These caching architectures provide a powerful means to accelerate HTTP handling, both as an origin webserver and as a proxy.

mod_cache and its provider modules mod_mem_cache and mod_disk_cache provide intelligent, HTTP-aware caching. The content itself is stored in the cache, and mod_cache aims to honour all of the various HTTP headers and options that control the cachability of content. It can handle both local and proxied content. mod_cache is aimed at both simple and complex caching configurations, where you are dealing with proxied content, dynamic local content or have a need to speed up access to local files which change with time.

mod_file_cache on the other hand presents a more basic, but sometimes useful, form of caching. Rather than maintain the complexity of actively ensuring the cachability of URLs, mod_file_cache offers file-handle and memory-mapping tricks to keep a cache of files as they were when Apache was last started. As such, mod_file_cache is aimed at improving the access time to local static files which do not change very often.

As mod_file_cache presents a relatively simple caching implementation, apart from the specific sections on CacheFile and MMapFile, the explanations in this guide cover the mod_cache caching architecture.

To get the most from this document, you should be familiar with the basics of HTTP, and have read the Users' Guides to Mapping URLs to the Filesystem and Content negotiation.

Caching Overview

Related Modules Related Directives
  • mod_cache
  • mod_mem_cache
  • mod_disk_cache
  • mod_file_cache
  • CacheEnable
  • CacheDisable
  • CacheFile
  • MMapFile
  • UseCanonicalName
  • CacheNegotiatedDocs

There are two main stages in mod_cache that can occur in the lifetime of a request. First, mod_cache is a URL mapping module, which means that if a URL has been cached, and the cached version of that URL has not expired, the request will be served directly by mod_cache.

This means that any other stages that might ordinarily happen in the process of serving a request -- for example being handled by mod_proxy, or mod_rewrite -- won't happen. But then this is the point of caching content in the first place.

If the URL is not found within the cache, mod_cache will add a filter to the request handling. After Apache has located the content by the usual means, the filter will be run as the content is served. If the content is determined to be cacheable, the content will be saved to the cache for future serving.

If the URL is found within the cache, but also found to have expired, the filter is added anyway, but mod_cache will create a conditional request to the backend, to determine if the cached version is still current. If the cached version is still current, its meta-information will be updated and the request will be served from the cache. If the cached version is no longer current, the cached version will be deleted and the filter will save the updated content to the cache as it is served.

Improving Cache Hits

When caching locally generated content, ensuring that UseCanonicalName is set to On can dramatically improve the ratio of cache hits. This is because the hostname of the virtual-host serving the content forms a part of the cache key. With the setting set to On virtual-hosts with multiple server names or aliases will not produce differently cached entities, and instead content will be cached as per the canonical hostname.

Because caching is performed within the URL to filename translation phase, cached documents will only be served in response to URL requests. Ordinarily this is of little consequence, but there is one circumstance in which it matters: If you are using Server Side Includes;

<!-- The following include can be cached -->
<!--#include virtual="/footer.html" -->

<!-- The following include can not be cached -->
<!--#include file="/path/to/footer.html" -->

If you are using Server Side Includes, and want the benefit of speedy serves from the cache, you should use virtual include types.

Expiry Periods

The default expiry period for cached entities is one hour, however this can be easily over-ridden by using the CacheDefaultExpire directive. This default is only used when the original source of the content does not specify an expire time or time of last modification.

If a response does not include an Expires header but does include a Last-Modified header, mod_cache can infer an expiry period based on the use of the CacheLastModifiedFactor directive.

For local content, mod_expires may be used to fine-tune the expiry period.

The maximum expiry period may also be controlled by using the CacheMaxExpire.

A Brief Guide to Conditional Requests

When content expires from the cache and is re-requested from the backend or content provider, rather than pass on the original request, Apache will use a conditional request instead.

HTTP offers a number of headers which allow a client, or cache to discern between different versions of the same content. For example if a resource was served with an "Etag:" header, it is possible to make a conditional request with an "If-None-Match:" header. If a resource was served with a "Last-Modified:" header it is possible to make a conditional request with an "If-Modified-Since:" header, and so on.

When such a conditional request is made, the response differs depending on whether the content matches the conditions. If a request is made with an "If-Modified-Since:" header, and the content has not been modified since the time indicated in the request then a terse "304 Not Modified" response is issued.

If the content has changed, then it is served as if the request were not conditional to begin with.

The benefits of conditional requests in relation to caching are twofold. Firstly, when making such a request to the backend, if the content from the backend matches the content in the store, this can be determined easily and without the overhead of transferring the entire resource.

Secondly, conditional requests are usually less strenuous on the backend. For static files, typically all that is involved is a call to stat() or similar system call, to see if the file has changed in size or modification time. As such, even if Apache is caching local content, even expired content may still be served faster from the cache if it has not changed. As long as reading from the cache store is faster than reading from the backend (e.g. an in-memory cache compared to reading from disk).

What Can be Cached?

As mentioned already, the two styles of caching in Apache work differently, mod_file_cache caching maintains file contents as they were when Apache was started. When a request is made for a file that is cached by this module, it is intercepted and the cached file is served.

mod_cache caching on the other hand is more complex. When serving a request, if it has not been cached previously, the caching module will determine if the content is cacheable. The conditions for determining cachability of a response are;

  1. Caching must be enabled for this URL. See the CacheEnable and CacheDisable directives.
  2. The response must have a HTTP status code of 200, 203, 300, 301 or 410.
  3. The request must be a HTTP GET request.
  4. If the request contains an "Authorization:" header, the response will not be cached.
  5. If the response contains an "Authorization:" header, it must also contain an "s-maxage", "must-revalidate" or "public" option in the "Cache-Control:" header.
  6. If the URL included a query string (e.g. from a HTML form GET method) it will not be cached unless the response specifies an explicit expiration by including an "Expires:" header or the max-age or s-maxage directive of the "Cache-Control:" header, as per RFC2616 sections 13.9 and 13.2.1.
  7. If the response has a status of 200 (OK), the response must also include at least one of the "Etag", "Last-Modified" or the "Expires" headers, or the max-age or s-maxage directive of the "Cache-Control:" header, unless the CacheIgnoreNoLastMod directive has been used to require otherwise.
  8. If the response includes the "private" option in a "Cache-Control:" header, it will not be stored unless the CacheStorePrivate has been used to require otherwise.
  9. Likewise, if the response includes the "no-store" option in a "Cache-Control:" header, it will not be stored unless the CacheStoreNoStore has been used.
  10. A response will not be stored if it includes a "Vary:" header containing the match-all "*".

What Should Not be Cached?

In short, any content which is highly time-sensitive, or which varies depending on the particulars of the request that are not covered by HTTP negotiation, should not be cached.

If you have dynamic content which changes depending on the IP address of the requester, or changes every 5 minutes, it should almost certainly not be cached.

If on the other hand, the content served differs depending on the values of various HTTP headers, it might be possible to cache it intelligently through the use of a "Vary" header.

Variable/Negotiated Content

If a response with a "Vary" header is received by mod_cache when requesting content by the backend it will attempt to handle it intelligently. If possible, mod_cache will detect the headers attributed in the "Vary" response in future requests and serve the correct cached response.

If for example, a response is received with a vary header such as;

Vary: negotiate,accept-language,accept-charset

mod_cache will only serve the cached content to requesters with accept-language and accept-charset headers matching those of the original request.

Security Considerations

Authorization and Access Control

Using mod_cache is very much like having a built in reverse-proxy. Requests will be served by the caching module unless it determines that the backend should be queried. When caching local resources, this drastically changes the security model of Apache.

As traversing a filesystem hierarchy to examine potential .htaccess files would be a very expensive operation, partially defeating the point of caching (to speed up requests), mod_cache makes no decision about whether a cached entity is authorised for serving. In other words; if mod_cache has cached some content, it will be served from the cache as long as that content has not expired.

If, for example, your configuration permits access to a resource by IP address you should ensure that this content is not cached. You can do this by using the CacheDisable directive, or mod_expires. Left unchecked, mod_cache - very much like a reverse proxy - would cache the content when served and then serve it to any client, on any IP address.

Local exploits

As requests to end-users can be served from the cache, the cache itself can become a target for those wishing to deface or interfere with content. It is important to bear in mind that the cache must at all times be writable by the user which Apache is running as. This is in stark contrast to the usually recommended situation of maintaining all content unwritable by the Apache user.

If the Apache user is compromised, for example through a flaw in a CGI process, it is possible that the cache may be targeted. When using mod_disk_cache, it is relatively easy to insert or modify a cached entity.

This presents a somewhat elevated risk in comparison to the other types of attack it is possible to make as the Apache user. If you are using mod_disk_cache you should bear this in mind - ensure you upgrade Apache when security upgrades are announced and run CGI processes as a non-Apache user using suEXEC if possible.

Cache Poisoning

When running Apache as a caching proxy server, there is also the potential for so-called cache poisoning. Cache Poisoning is a broad term for attacks in which an attacker causes the proxy server to retrieve incorrect (and usually undesirable) content from the backend.

For example if the DNS servers used by your system running Apache are vulnerable to DNS cache poisoning, an attacker may be able to control where Apache connects to when requesting content from the origin server. Another example is so-called HTTP request-smuggling attacks.

This document is not the correct place for an in-depth discussion of HTTP request smuggling (instead, try your favourite search engine) however it is important to be aware that it is possible to make a series of requests, and to exploit a vulnerability on an origin webserver such that the attacker can entirely control the content retrieved by the proxy.

File-Handle Caching

Related Modules Related Directives
  • mod_file_cache
  • mod_mem_cache
  • CacheFile
  • CacheEnable
  • CacheDisable

The act of opening a file can itself be a source of delay, particularly on network filesystems. By maintaining a cache of open file descriptors for commonly served files, Apache can avoid this delay. Currently Apache provides two different implementations of File-Handle Caching.

CacheFile

The most basic form of caching present in Apache is the file-handle caching provided by mod_file_cache. Rather than caching file-contents, this cache maintains a table of open file descriptors. Files to be cached in this manner are specified in the configuration file using the CacheFile directive.

The CacheFile directive instructs Apache to open the file when Apache is started and to re-use this file-handle for all subsequent access to this file.

CacheFile /usr/local/apache2/htdocs/index.html

If you intend to cache a large number of files in this manner, you must ensure that your operating system's limit for the number of open files is set appropriately.

Although using CacheFile does not cause the file-contents to be cached per-se, it does mean that if the file changes while Apache is running these changes will not be picked up. The file will be consistently served as it was when Apache was started.

If the file is removed while Apache is running, Apache will continue to maintain an open file descriptor and serve the file as it was when Apache was started. This usually also means that although the file will have been deleted, and not show up on the filesystem, extra free space will not be recovered until Apache is stopped and the file descriptor closed.

CacheEnable fd

mod_mem_cache also provides its own file-handle caching scheme, which can be enabled via the CacheEnable directive.

CacheEnable fd /

As with all of mod_cache this type of file-handle caching is intelligent, and handles will not be maintained beyond the expiry time of the cached content.

In-Memory Caching

Related Modules Related Directives
  • mod_mem_cache
  • mod_file_cache
  • CacheEnable
  • CacheDisable
  • MMapFile

Serving directly from system memory is universally the fastest method of serving content. Reading files from a disk controller or, even worse, from a remote network is orders of magnitude slower. Disk controllers usually involve physical processes, and network access is limited by your available bandwidth. Memory access on the other hand can take mere nano-seconds.

System memory isn't cheap though, byte for byte it's by far the most expensive type of storage and it's important to ensure that it is used efficiently. By caching files in memory you decrease the amount of memory available on the system. As we'll see, in the case of operating system caching, this is not so much of an issue, but when using Apache's own in-memory caching it is important to make sure that you do not allocate too much memory to a cache. Otherwise the system will be forced to swap out memory, which will likely degrade performance.

Operating System Caching

Almost all modern operating systems cache file-data in memory managed directly by the kernel. This is a powerful feature, and for the most part operating systems get it right. For example, on Linux, let's look at the difference in the time it takes to read a file for the first time and the second time;

colm@coroebus:~$ time cat testfile > /dev/null
real    0m0.065s
user    0m0.000s
sys     0m0.001s
colm@coroebus:~$ time cat testfile > /dev/null
real    0m0.003s
user    0m0.003s
sys     0m0.000s

Even for this small file, there is a huge difference in the amount of time it takes to read the file. This is because the kernel has cached the file contents in memory.

By ensuring there is "spare" memory on your system, you can ensure that more and more file-contents will be stored in this cache. This can be a very efficient means of in-memory caching, and involves no extra configuration of Apache at all.

Additionally, because the operating system knows when files are deleted or modified, it can automatically remove file contents from the cache when necessary. This is a big advantage over Apache's in-memory caching which has no way of knowing when a file has changed.

Despite the performance and advantages of automatic operating system caching there are some circumstances in which in-memory caching may be better performed by Apache.

Firstly, an operating system can only cache files it knows about. If you are running Apache as a proxy server, the files you are caching are not locally stored but remotely served. If you still want the unbeatable speed of in-memory caching, Apache's own memory caching is needed.

MMapFile Caching

mod_file_cache provides the MMapFile directive, which allows you to have Apache map a static file's contents into memory at start time (using the mmap system call). Apache will use the in-memory contents for all subsequent accesses to this file.

MMapFile /usr/local/apache2/htdocs/index.html

As with the CacheFile directive, any changes in these files will not be picked up by Apache after it has started.

The MMapFile directive does not keep track of how much memory it allocates, so you must ensure not to over-use the directive. Each Apache child process will replicate this memory, so it is critically important to ensure that the files mapped are not so large as to cause the system to swap memory.

mod_mem_cache Caching

mod_mem_cache provides a HTTP-aware intelligent in-memory cache. It also uses heap memory directly, which means that even if MMap is not supported on your system, mod_mem_cache may still be able to perform caching.

Caching of this type is enabled via;

# Enable memory caching
CacheEnable mem /

# Limit the size of the cache to 1 Megabyte
MCacheSize 1024

Disk-based Caching

Related Modules Related Directives
  • mod_disk_cache
  • CacheEnable
  • CacheDisable

mod_disk_cache provides a disk-based caching mechanism for mod_cache. As with mod_mem_cache this cache is intelligent and content will be served from the cache only as long as it is considered valid.

Typically the module will be configured as so;

CacheRoot   /var/cache/apache/
CacheEnable disk /
CacheDirLevels 2
CacheDirLength 1

Importantly, as the cached files are locally stored, operating system in-memory caching will typically be applied to their access also. So although the files are stored on disk, if they are frequently accessed it is likely the operating system will ensure that they are actually served from memory.

Understanding the Cache-Store

To store items in the cache, mod_disk_cache creates a 22 character hash of the URL being requested. This hash incorporates the hostname, protocol, port, path and any CGI arguments to the URL, to ensure that multiple URLs do not collide.

Each character may be any one of 64-different characters, which mean that overall there are 64^22 possible hashes. For example, a URL might be hashed to xyTGxSMO2b68mBCykqkp1w. This hash is used as a prefix for the naming of the files specific to that URL within the cache, however first it is split up into directories as per the CacheDirLevels and CacheDirLength directives.

CacheDirLevels specifies how many levels of subdirectory there should be, and CacheDirLength specifies how many characters should be in each directory. With the example settings given above, the hash would be turned into a filename prefix as /var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w.

The overall aim of this technique is to reduce the number of subdirectories or files that may be in a particular directory, as most file-systems slow down as this number increases. With setting of "1" for CacheDirLength there can at most be 64 subdirectories at any particular level. With a setting of 2 there can be 64 * 64 subdirectories, and so on. Unless you have a good reason not to, using a setting of "1" for CacheDirLength is recommended.

Setting CacheDirLevels depends on how many files you anticipate to store in the cache. With the setting of "2" used in the above example, a grand total of 4096 subdirectories can ultimately be created. With 1 million files cached, this works out at roughly 245 cached URLs per directory.

Each URL uses at least two files in the cache-store. Typically there is a ".header" file, which includes meta-information about the URL, such as when it is due to expire and a ".data" file which is a verbatim copy of the content to be served.

In the case of a content negotiated via the "Vary" header, a ".vary" directory will be created for the URL in question. This directory will have multiple ".data" files corresponding to the differently negotiated content.

Maintaining the Disk Cache

Although mod_disk_cache will remove cached content as it is expired, it does not maintain any information on the total size of the cache or how little free space may be left.

Instead, provided with Apache is the htcacheclean tool which, as the name suggests, allows you to clean the cache periodically. Determining how frequently to run htcacheclean and what target size to use for the cache is somewhat complex and trial and error may be needed to select optimal values.

htcacheclean has two modes of operation. It can be run as persistent daemon, or periodically from cron. htcacheclean can take up to an hour or more to process very large (tens of gigabytes) caches and if you are running it from cron it is recommended that you determine how long a typical run takes, to avoid running more than one instance at a time.

Figure 1: Typical cache growth / clean sequence.

Because mod_disk_cache does not itself pay attention to how much space is used you should ensure that htcacheclean is configured to leave enough "grow room" following a clean.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


サーバ全体の設定 - Apache HTTP サーバ バージョン 2.2

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

サーバ全体の設定

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

サーバ ID

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

ServerAdmin, ServerTokens, UseCanonicalPhysicalPort ディレクティブは、エラーメッセージなどのサーバが作るドキュメントに、 どのようなサーバの情報を表示するかを制御します。 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 サーバ バージョン 2.2

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

ログファイル

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

ウェブサーバを効果的に管理するためには、サーバの活動やパフォーマンス、 今発生しているかもしれない問題に関するフィードバックを得ることが必要です。 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_logio
  • mod_log_forensic
  • mod_cgi
  • mod_rewrite
  • LogFormat
  • ForensicLog
  • PidFile
  • RewriteLog
  • RewriteLogLevel
  • ScriptLog
  • ScriptLogBuffer
  • ScriptLogLength

実際に送受信したバイト数のログ

mod_logio は、 ネットワーク上で実際に送受信した数をログする 二つのフィールド (%I と %O) を LogFormat ディレクティブに追加します。

Forensic ログ

mod_log_forensic はクライアントリクエストの forensic ログを取ります。ログはリクエスト処理前と処理後に 行われますので、1 リクエストに対して 2 行のログが出力されます。 forensic ロガーはとても厳密でカスタマイズできません。 デバッグやセキュリティ用のツールとして有効かもしれません。

PID ファイル

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

スクリプトログ

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

リライトログ

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


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

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

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

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

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

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

関連モジュール 関連ディレクティブ
  • mod_alias
  • mod_proxy
  • mod_rewrite
  • mod_userdir
  • mod_speling
  • mod_vhost_alias
  • Alias
  • AliasMatch
  • CheckSpelling
  • DocumentRoot
  • ErrorDocument
  • Options
  • ProxyPass
  • ProxyPassReverse
  • ProxyPassReverseCookieDomain
  • ProxyPassReverseCookiePath
  • 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/
ProxyPassReverseCookieDomain internal.example.com public.example.com
ProxyPassReverseCookiePath /foo/ /bar/

ProxyPass ディレクティブは サーバが適切なドキュメントを取得するように設定し、 ProxyPassReverse ディレクティブは internal.example.com からのリダイレクトがローカルサーバの 適切なディレクトリを指すように書き換えます。 同様に ProxyPassReverseCookieDomain と ProxyPassReverseCookiePath でバックエンド側サーバの発行した Cookie を書き換えることができます。

ただし、ドキュメントの中のリンクは書き換えられない、 ということは知っておいてください。 ですから、internal.example.com への絶対パスによるリンクでは、 クライアントがプロキシサーバを抜け出して internal.example.com に 直接リクエストを送る、ということになります。 サードパーティ製モジュールの mod_proxy_html は、HTML と XHTML 中のリンクを書き換えることができます。

リライトエンジン

より一層強力な置換が必要なときは、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 Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 designated 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 allow 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.example.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.example.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>

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


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

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

動的共有オブジェクト (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.2 の 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 サーバ バージョン 2.2

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

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

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

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=(.+)" prefer-language=$1

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 クライアントからのリクエストには効力を持ちません。

HTTP/1.1 クライアントに対しては、レスポンスのネゴシエーション次元 を示すために Vary HTTP レスポンスヘッダを送ります。 キャッシュは、これを使って後続のリクエストに対してローカルコピーで応答できるか どうかを決定できます。 ネゴシエーション次元とは関係なしにローカルコピーの使用を優先するようにするには、 force-no-vary 環境変数を 設定します。


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

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

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

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

ウェブマスターが何らかのエラーや問題に対する 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 サーバ バージョン 2.2

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

バインド

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

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.0.2.1:80
Listen 192.0.2.5:8000

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

Listen [2001:db8::a00:20ff:fea7:ccea]:80

IPv6 の特記事項

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

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

一方で、Linux や Tru64 といったプラットホームで IPv4 と IPv6 の両方を扱うには、マップトアドレスを使用する以外の方法はありません。 IPv4 と IPv6 のコネクションを最小限のソケットで扱いたいのであれば、 IPv4 マップの IPv6 アドレスを使用する必要があり、 --enable-v4-mapped configure オプションを指定します。

--enable-v4-mapped は、 FreeBSD, NetBSD, OpenBSD 以外の全てのプラットホームでのデフォルトです。 ですから、おそらくお手元の Apache はこの設定でビルドされているでしょう。

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

Listen 0.0.0.0:80
Listen 192.0.2.1:80

条件を満たすプラットホームで、Apache が IPv4 と IPv6 のコネクションを個別のソケットで扱うようにしたい場合 (つまり IPv4 マップのアドレスを無効にしたい場合) は、--disable-v4-mapped configure オプションを指定して、次のように個別指定の Listen ディレクティブを使用してください。 --disable-v4-mapped は、 FreeBSD, NetBSD, OpenBSD プラットホームでのデフォルトです。

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

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


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

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

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

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

はじめに

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

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

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

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

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

MPM を選ぶ

MPM は設定中に選択して、サーバ内部にコンパイルされなければ なりません。 コンパイラは、スレッドが使用されている場合に様々な機能を最適化できますが、 そのためにはそもそもスレッドが使われているということを知る必要があります。

望みの 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 サーバ バージョン 2.2

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

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_authz_host
  • 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-gzip

DEFLATE フィルタが使用するように設定されているときに、 この環境変数はブラウザの accept-encoding の設定を無視して常に 圧縮された出力を送るようにします。

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 出力フィルタを無効にします。 また、静的に、既に圧縮されたファイルを使用したい場合、 (gzip だけでなく、"identity" と異なる全てのエンコードに対して) mod_negotiation も変数を評価します。

no-gzip

セットされると、mod_deflate の DEFLATE フィルタがオフになります。 そして mod_negotiation はエンコードされたリソースを送らないようにします。

nokeepalive

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

prefer-language

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

redirect-carefully

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

suppress-error-charset

Apache 2.2 以降で利用可能

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

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

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

force-proxy-request-1.0, proxy-nokeepalive, proxy-sendchunked, proxy-sendcl

これらの指示子は mod_proxy の挙動を変更します。 詳細は mod_proxy のドキュメントをご参照ください。

例

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

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

古いバージョンの Apache では、クライアントの問題に対応するために 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 サーバ バージョン 2.2

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

Apache のハンドラの使用

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

ハンドラとは

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

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

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

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

  • default-handler:default_handelr() を使ってファイルを送ります。 静的なコンテンツを扱うときにデフォルトで使用されるハンドラです。 (core)
  • send-as-is: HTTP ヘッダのあるファイルをそのまま送ります。 (mod_asis)
  • cgi-script: ファイルを CGI スクリプトとして扱います。 (mod_cgi)
  • imap-file: イメージマップのルールファイルとして解析します。 (mod_imagemap)
  • 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 サーバ バージョン 2.2

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

フィルタ

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

Apache 2 のフィルタ

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

Apache 2.0 以降ではフィルタチェイン機能が使え、データが どこから来るかに関わらず、非常に柔軟で調整しやすい方法で 入出力データを処理できます。 入力データをプリプロセスしたり出力データをポストプロセスしたりできます。 この処理は、これまでのリクエスト処理フェーズとは根本的に独立した 処理になります。

Filters can be chained, in a Data Axis orthogonal to request processing

Apache の標準的なディストリビューションでのフィルタ例は :

  • mod_include で、サーバサイドインクルード SSI を実装しています
  • mod_ssl で、SSL 暗号化 (https) を実装しています。
  • mod_deflate で、on-the-fly のデータ圧縮・展開機能を実装しています。
  • mod_charset_lite で、異なる文字セット間の変換を実装しています。
  • mod_ext_filter で、外部プログラムをフィルタとして実行します。

チャンキングやバイトレンジ処理といった処理を行うために Apache は、内部的にいくつかのフィルタを使っています。

様々なアプリケーションがサードパーティ製のフィルタモジュールとして 実装されていて、modules.apache.org などから取得できます。たとえば :

  • HTML や XML の処理と書き換え
  • XSLT 変換と XIncludes
  • XML 名前空間のサポート
  • ファイルアップロード処理や HTML フォームのデコード
  • 画像処理
  • PHP スクリプトなどのアプリケーションに対する保護機能
  • テキストの検索置換・編集機能

スマートフィルタ

Smart filtering applies different filter providers according to the state of request processing

Apache 2.1 移行に含まれる mod_filter では、 実行時に動的にフィルタチェインを有効にできます。 ですからたとえば、HTML を HTML フィルタで、JPEG 画像をそれとは 全く別のフィルタで、書き換えるようなプロクシを設定することもできます。 その上、そのプロクシはどのオリジンサーバがコンテンツを送信するか 事前情報無しでいいように構成できます。 これは、実行時に実際のコンテンツに応じて別々のフィルタプロバイダに ディスパッチするフィルタハーネスを使うことで実現されています。 チェインの中に直接入れて無条件に適用したり、動的にプロバイダとして 適用するようにしたりすることは、どんなフィルタでもできます。 たとえば、

  • HTML 処理フィルタはコンテントが text/html あるいは application/xhtml+xml の場合にのみ実行されます
  • 圧縮フィルタは圧縮可能な入力で、非圧縮状態のものに 対してのみ実行されます
  • 文字セット変換フィルタはテキスト文書が 希望の文字セットになっていない場合に挿入されます

フィルタの使い方

フィルタの使い方には二つの方法があります: シンプルとダイナミック。 一般的にはどちらかのみを使ったほうがよいでしょう。 これらを組み合わせて使用すると、予期しない結果になるかもしれません。 (とはいえ、シンプルな入力フィルタとシンプルあるいはダイナミックな 出力フィルタを組み合わせることは自由に出来ます。)

シンプルな方法は、入力フィルタのみを設定し、必要に応じて 静的なフィルタチェインを出力フィルタとして設定する方法です。 関連するディレクティブは、 SetInputFilter, SetOutputFilter, AddInputFilter, AddOutputFilter, RemoveInputFilter, RemoveOutputFilter になります。

ダイナミックな方法は、静的なものとフレキシブルなものを両方有効にする 方法で、mod_filter のページで述べられています。 関連するディレクティブは、 FilterChain, FilterDeclare, FilterProvider になります。

ディレクティブ AddOutputFilterByType はまだサポートされていますが、種々の問題をはらんでおり、非推奨です。 ダイナミックな設定方法を代わりに使ってください。


suEXEC サポート - Apache HTTP サーバ バージョン 2.2

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

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 Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Miscellaneous Documentation

Apache Performance Tuning

Apache 2.x 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.x is capable of high performance in many real-world situations.

Compared to Apache 1.3, release 2.x 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.x 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 that it starts swapping. The 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 patch level 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, or 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 two DNS lookups (a reverse, followed by a forward lookup 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 need 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.x 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.x 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.x can ignore the contents of the file to be delivered -- for example, when serving static file content -- it normally uses the kernel sendfile support for 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 of 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 it 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 5 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 you are 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.x 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 that 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" behavior 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 behavior 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 shut down 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 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 to accomplish 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 behavior 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.x 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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


URL Rewriting Guide - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Miscellaneous Documentation

URL Rewriting Guide

This document is obsolete. It has been replaced with a new Rewrite Guide.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Apache バーチャルホスト説明書 - Apache HTTP サーバ バージョン 2.2

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

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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > バーチャルホスト

名前ベースのバーチャルホスト

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

この文書では名前ベースのバーチャルホストをどんなとき、 どうやって使うかを説明します。

参照

  • ネームベースのバーチャルホスト
  • バーチャルホストのマッチングについての詳細
  • 大量のバーチャルホストの動的な設定
  • バーチャルホストの一般的な設定例
  • 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 ベースのバーチャルホストサポート - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > バーチャルホスト

Apache の IP ベースのバーチャルホストサポート

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

参照

  • 名前ベースのバーチャルホストサポート

システム要件

IP ベース という名前が示すように、サーバには IP ベースのバーチャルホストそれぞれにつき、別々の IP アドレスが 必要です。複数の物理コネクションを持っているマシンを用意するか、 最近のオペレーティングシステムでサポートされているバーチャル インタフェース (詳細はシステムの説明書を読んでください。たいていは "ip エイリアス" と呼ばれていて、設定には普通 "ifconfig" コマンドを 使います) を使うかで実現できます。

Apache の設定方法

複数のホストをサポートするように Apache を設定する方法は 二通りあります。別の httpd デーモンを各ホスト毎に実行するか、 すべてのバーチャルホストをサポートするデーモンを一つ実行するかです。

以下のときには複数のデーモンを使うと良いでしょう:

  • 会社1 はウェブ経由以外では会社2 からはデータを読まれたくない、 といったセキュリティの分離の問題があるとき。この場合、それぞれ User, Group, Listen, ServerRoot の設定が違う二つのデーモンを 実行する必要があります。
  • マシンのすべての IP エイリアスを listen するだけの メモリとファイル記述子の余裕があるとき。Listen は「ワイルドカード」 アドレスか、特定のアドレスのみを listen することができます。 ですから、何らかの理由で特定のアドレスを listen しなけばならない ときは、その特定のアドレスをすべて listen する必要があります。 (ただし、一つの httpd が N-1 個のアドレスを listen し、 別の httpd が残りのアドレスを listen するといったことは可能です。)

以下のときには単独のデーモンを使うと良いでしょう:

  • バーチャルホスト間での httpd の設定を共有してもよいとき。
  • マシンが多くのリクエストを扱うため、別デーモンを実行することによる 性能の低下の影響が著しいとき。

複数デーモンの設定

各バーチャルホストに対して別の httpd のインストールを行ないます。 設定ファイル中の Listen ディレクティブを使って、 各インストールでデーモンが扱う IP アドレス (バーチャルホスト) を選択します。例えば

Listen www.smallco.com:80

ここで、ホスト名の代わりに IP アドレスを使う方が推奨されていることに 注意しておいてください (DNS の注意事項 参照)。

複数のバーチャルホストの設定をした デーモンを一つ設定する

この場合は、一つの httpd が主サーバとすべてのバーチャルホストのリクエストを 処理します。設定ファイルの VirtualHost ディレクティブを使って、 ServerAdmin, ServerName, DocumentRoot, ErrorLog, TransferLog や CustomLog 設定ディレクティブの値が各ホスト毎に異なる値に設定されるようにします。 例えば

<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>

ここで、ホスト名の代わりに IP アドレスを使う方が推奨されていることに 注意しておいてください (DNS の注意事項 参照)。

プロセス生成を制御するディレクティブやその他のいくつかのディレクティブを 除いて、ほぼすべての設定ディレクティブを VirtualHost ディレクティブの中に書くことができます。ディレクティブが VirtualHost ディレクティブで使用できるかどうかは ディレクティブ索引を使ってコンテキストの 欄を調べてください。

suEXECラッパーを使っている場合は、 SuexecUserGroup ディレクティブを VirtualHost ディレクティブの中で使用することができます。

セキュリティ: ログファイルを書く場所を指定するときは、 Apache を起動したユーザ以外がそのディレクトリに書き込み権限を 持っている場合にセキュリティ上の危険があることに注意してください。 詳細はセキュリティのこつドキュメントを 参照してください。


Dynamically configured mass virtual hosting - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Virtual Hosts

Dynamically configured mass virtual hosting

This document describes how to efficiently serve an arbitrary number of virtual hosts with Apache.

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>

Note

If the first VirtualHost block does not include a ServerName directive, the reverse DNS of the relevant IP will be used instead. If this is not the server name you wish to use, a bogus entry (ServerName none.example.com) can be added to get around this behaviour.

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

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

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


バーチャルホストの例 - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > バーチャルホスト

バーチャルホストの例

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

この文書は、バーチャルホストの設定の際に よくある質問に答えるものです。想定している対象は 名前ベース や IP ベース のバーチャルホストを使って 一つのサーバで複数のウェブサイトを運用している状況です。

一つの IP アドレスでいくつかの名前ベースの ウェブサイトを実行する

サーバは IP アドレスを一つ割り当てられていて、DNS でマシンに 複数の名前 (CNAME) が指定されています。このマシンで www.example.com と www.example.org のためのウェブサーバを実行させたいとします。

注

Apache サーバの設定でバーチャルホストの設定をしただけで、 知らない間にそのホスト名に対応する DNS のエントリが 作成されたりはしません。そのサーバの IP アドレスに解決される ように DNS に名前を登録しなければなりません。 そうでないと誰もあなたのウェブサイトを見ることはできません。 ローカルでのテストのために hosts ファイルに エントリを追加することもできますが、この場合はその hosts エントリのあるマシンからしか動作しません。

サーバ設定

# 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.example.com

# Other directives here

 </VirtualHost>

<VirtualHost *:80>
DocumentRoot /www/example2
ServerName www.example.org

# Other directives here

 </VirtualHost>

アスタリスクはすべてのアドレスにマッチしますので、主サーバは リクエストを扱いません。www.example.com は 最初にあるため、優先順位は一番高くなり、default もしくは primary のサーバと考えることができます。つまり、リクエストが どの ServerName ディレクティブにもマッチしない場合、 一番最初の VirtualHost により扱われます。

注

* をシステムの実際の IP アドレスに置き換える こともできます。その場合は VirtualHost の引数は NameVirtualHost の引数と同じにしなければなりません :

NameVirtualHost 172.20.30.40

<VirtualHost 172.20.30.40>
# etc ...

しかし、IP アドレスが予測不可能なシステム ――例えばプロバイダから動的に IP アドレスを取得して何らかの ダイナミック DNS を使っている場合など――においては、* 指定はさらに便利です。* はすべての IP アドレスに マッチしますので、この設定にしておけば IP アドレスが変更されても 設定変更せずに動作します。

名前ベースのバーチャルホスティングではほぼすべての状況で、 上記の設定で希望の設定になっていることでしょう。 実際この設定が動作しないのは、IP アドレスやポートの違いによって 違うコンテンツを送るときだけです。

複数の IP アドレスのあるホストで名前ベースの ホスティングを行なう

注

ここで説明されている方法は IP アドレスが 何個あっても同様にできます。

サーバには二つ IP アドレスがついています。一つ目 (172.20.30.40) では主サーバ server.domain.com を扱い、もう一方 (172.20.30.50) では二つかそれ以上の数の バーチャルホストを扱います。

サーバの設定

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.example.com

# Other directives here ...

 </VirtualHost>

<VirtualHost 172.20.30.50>
DocumentRoot /www/example2
ServerName www.example.org

# Other directives here ...

 </VirtualHost>

172.20.30.50 以外のアドレスへのリクエストは主サーバ が扱います。172.20.30.50 への、未知のホスト名または Host: ヘッダなしのリクエストは www.example.com が扱います。

違う IP アドレス (例えば、内部と外部アドレス) で同じコンテンツを送る

サーバマシンは IP アドレスを二つ (192.168.1.1 と 172.20.30.40) 持っています。このマシンは内部 (イントラネット) と 外部 (インターネット) のネットワークの間に あります。server.example.com はネットワークの外からは 外部アドレス (172.20.30.40) として解決されますが、 ネットワークの中からは内部アドレス (192.168.1.1) として解決されます。

VirtualHost 一つだけでサーバが内部のリクエストと 外部のリクエストの両方に同じコンテンツで応答するようにできます。

サーバの設定

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>

これでどちらのネットワークからのリクエストも同じ VirtualHost で扱われるようになります。

注:

内部ネットワークでは完全なホスト名の server.example.com の代わりに、単に server を使うことができます。

上の例では、IP アドレスのリストを、すべてのアドレスに 同じコンテンツで応答する * に置き換えられます。

違うポートで違うサイトを運営する

同じ IP に複数のドメインがあり、さらに複数のポートを使って リクエストを扱いたいときがあります。"NameVirtualHost" タグの中で ポートを定義することで、これを動作させられます。 NameVirtualHost name:port 無しや Listen ディレクティブで <VirtualHost name:port> を使おうとしても、その設定は動作しません。

サーバの設定

Listen 80
Listen 8080

NameVirtualHost 172.20.30.40:80
NameVirtualHost 172.20.30.40:8080

<VirtualHost 172.20.30.40:80>
ServerName www.example.com
DocumentRoot /www/domain-80
 </VirtualHost>

<VirtualHost 172.20.30.40:8080>
ServerName www.example.com
DocumentRoot /www/domain-8080
 </VirtualHost>

<VirtualHost 172.20.30.40:80>
ServerName www.example.org
DocumentRoot /www/otherdomain-80
 </VirtualHost>

<VirtualHost 172.20.30.40:8080>
ServerName www.example.org
DocumentRoot /www/otherdomain-8080
 </VirtualHost>

IP ベースのバーチャルホスティング

サーバは www.example.com と www.example.org にそれぞれ解決される、二つの IP アドレス (172.20.30.40 と 172.20.30.50) があります。

サーバの設定

Listen 80

<VirtualHost 172.20.30.40>
DocumentRoot /www/example1
ServerName www.example.com
 </VirtualHost>

<VirtualHost 172.20.30.50>
DocumentRoot /www/example2
ServerName www.example.org
 </VirtualHost>

<VirtualHost> ディレクティブのどれでも 指定されていないアドレス (例えば localhost) は、 主サーバがあればそこに行きます。

ポートベースと IP ベースの混ざった バーチャルホスト

サーバマシンはそれぞれ www.example.com と www.example.org にそれぞれ解決される、IP アドレスを二つ (172.20.30.40 と 172.20.30.50) 持っています。 どちらもポート 80 と 8080 でホストを走らせます。

サーバの設定

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.example.com
 </VirtualHost>

<VirtualHost 172.20.30.40:8080>
DocumentRoot /www/example1-8080
ServerName www.example.com
 </VirtualHost>

<VirtualHost 172.20.30.50:80>
DocumentRoot /www/example2-80
ServerName www.example.org
 </VirtualHost>

<VirtualHost 172.20.30.50:8080>
DocumentRoot /www/example2-8080
ServerName www.example.org
 </VirtualHost>

名前ベースと IP ベースを混ぜた バーチャルホスト

いくつかのマシンでは名前ベースの、その他では IP ベースのバーチャル ホストをします。

サーバの設定

Listen 80

NameVirtualHost 172.20.30.40

<VirtualHost 172.20.30.40>
DocumentRoot /www/example1
ServerName www.example.com
 </VirtualHost>

<VirtualHost 172.20.30.40>
DocumentRoot /www/example2
ServerName www.example.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>

Virtual_host と mod_proxy を併用する

次の例は、フロント側のバーチャルホストで他のマシンへプロクシします。 例では 192.168.111.2 のマシンではバーチャルホスト名は 同じ名前で設定されています。複数のホスト名を一台のマシンにプロクシする 場合は、ProxyPreserveHost On ディレクティブを使って、希望のホスト名を渡せるようになります。

<VirtualHost *:*>
ProxyPreserveHost On
ProxyPass / http://192.168.111.2
ProxyPassReverse / http://192.168.111.2/
ServerName hostname.example.com
</VirtualHost>

_default_ のバーチャルホストを 使う

すべてのポートに対する _default_ バーチャルホスト

未指定の IP アドレスとポート、つまり他のバーチャルホストに 使われていないアドレスとポートの組み合わせ、へのすべてのリクエストを 受け取ります。

サーバの設定

<VirtualHost _default_:*>
DocumentRoot /www/default
 </VirtualHost>

このようにワイルドカードのポートでデフォルトのバーチャルホストを 指定すると、主サーバにリクエストが行くのを防げます。

デフォルトのバーチャルホストは名前ベースのバーチャルホストに 使われているアドレスとポートの組に送られたリクエストを扱うことは ありません。リクエストが不明な Host: ヘッダやその ヘッダがなかったりする場合は基本名前ベースバーチャルホスト (その アドレスとポートで設定ファイル中で最初のバーチャルホスト) により 扱われます。

どんなリクエストでも AliasMatch や RewriteRule を使って 単一の情報ページ (やスクリプト) に書き換えることができます。

違うポートのための _default_ バーチャルホスト

一つめの設定とほぼ同じですが、サーバは複数のポートを listen しており、 80 番ポートに対して二つめの _default_ バーチャルホストを 設定したい場合です。

サーバの設定

<VirtualHost _default_:80>
DocumentRoot /www/default80
# ...
 </VirtualHost>

<VirtualHost _default_:*>
DocumentRoot /www/default
# ...
 </VirtualHost>

80 番ポートのデフォルトバーチャルホスト (ワイルドカードポートの デフォルトバーチャルホストよりも前に書かれていなければなりません) は 未指定の IP アドレスに送られたすべてのリクエストを扱います。 主サーバはリクエストを扱いません。

一つのポートに対してだけの _default_ バーチャルホスト

80 番ポートにはデフォルトのバーチャルホストが必要で、他の バーチャルホストはデフォルトが必要ない場合です。

サーバの設定

<VirtualHost _default_:80>
DocumentRoot /www/default
...
</VirtualHost>

80 番ポートへのアドレス未指定のリクエストはデフォルトのバーチャル ホストから送られます。他の未指定のアドレスとポートへのリクエストは 主サーバから送られます。

名前ベースのバーチャルホストから IP ベースの バーチャルホストに移行する

ホスト名が名前 www.example.org のバーチャルホスト (名前ベースの例の 2 番目の設定) が専用の IP アドレスを 得たとします。名前ベースのバーチャルホストの古い IP アドレスを キャッシュしているネームサーバやプロキシのために移行期間中は両方の バーチャルホストを提供したいとします。

答は簡単です。単に新しい IP アドレス (172.20.30.50) を VirtualHost ディレクティブに追加することで できます。

サーバ設定

Listen 80
ServerName www.example.com
DocumentRoot /www/example1

NameVirtualHost 172.20.30.40

<VirtualHost 172.20.30.40 172.20.30.50>
DocumentRoot /www/example2
ServerName www.example.org
# ...
 </VirtualHost>

<VirtualHost 172.20.30.40>
DocumentRoot /www/example3
ServerName www.example.net
ServerAlias *.example.net
# ...
 </VirtualHost>

このバーチャルホストは新しいアドレス (IP ベースのバーチャルホストとして) と古いアドレス(名前ベースのバーチャルホストとして) の両方から アクセスできます。

ServerPath ディレクティブを 使う

名前ベースのバーチャルホストが二つあるサーバがあるとします。 正しいバーチャルホストを得るためにはクライアントは正しい Host: ヘッダを送らなければなりません。 古い HTTP/1.0 はそのようなヘッダを送らないので、Apache はクライアントが どのバーチャルホストを意図したのかさっぱりわかりません (なので、主バーチャルホストでリクエストを扱います)。 可能な限りの下位互換性を得るため、名前ベースのバーチャルホストの URL 接頭辞へのリンクの書かれたページを返す、 主バーチャルホストが作成されます。

サーバの設定

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>

ServerPath ディレクティブの設定に より、URL http://www.sub1.domain.tld/sub1/ は 常に sub1-vhost により扱われます。URL http://www.sub1.domain.tld/ へのリクエストは クライアントが正しい Host: ヘッダを送ったときにのみ sub1-vhost から送られます。Host: ヘッダがなければ クライアントは主ホストの情報ページを得ます。

一つ奇妙な動作をする点があることは覚えておいてください。 http://www.sub2.domain.tld/sub1/ へのリクエストも Host: ヘッダがなければ sub1-vhost により扱われます。

正しい Host: ヘッダを送ったクライアントはどちらの URL、つまり接頭辞がある方も無い方も使えるように RewriteRule ディレクティブが 使われています。


An In-Depth Discussion of Virtual Host Matching - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 ServerName and ServerPath can appear anywhere within the definition of a server. However, each appearance overrides the previous appearance (within that server).

The main_server has no default ServerPath, or ServerAlias. The default ServerName is deduced from the server's IP address.

Port numbers specified in the VirtualHost directive do not influence what port numbers Apache will listen on, they only discriminate between which VirtualHost will be selected to handle a request.

Each address appearing in the VirtualHost directive can have an optional port. If the port is unspecified it is treated as a wildcard port. 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 the exact IP address and port pair in the VirtualHost directive, Apache selects the best match only on the basis of the IP address (or wildcard) and port number. If there are multiple identical best matches, the first VirtualHost appearing in the configuration file will be selected.

If you want Apache to further discriminate on the basis of the HTTP Host header supplied by the client, the NameVirtualHost directive must appear with the exact IP address (or wildcard) and port pair used in a corresponding set of VirtualHost directives.

The name-based virtual host selection occurs only after a single IP-based virtual host has been selected, and only considers the set of virtual hosts that carry an identical IP address and port pair.

Hostnames can be used in place of IP addresses in a virtual host definition, but it is resolved at startup and is not recommended.

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.)

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, Timeout, KeepAliveTimeout, KeepAlive, MaxKeepAliveRequests, ReceiveBufferSize, 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.

The complete list of names in the VirtualHost directive are treated just like a (non wildcard) ServerAlias (but are not overridden by any ServerAlias statement).

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.
  • The 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. Note that this is simply an extension of the "best match" principle, as a specific and exact match is favored over a wildcard.
  • 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").

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


ファイル記述子の限界 - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > バーチャルホスト

ファイル記述子の限界

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

たくさんのバーチャルホストを運用する場合、もし、 各バーチャルホストごとに異なるログファイルが指定してあると、 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

ログファイルの分割

複数のバーチャルホストのログを同じログファイルに収集しようとしているときには、 各バーチャルホストについて統計的な解析を実行するために後でログファイルを 分割したくなるかもしれません。これは以下のようにして実現できます。

まず、バーチャルホストの情報をログのエントリに追加する必要があります。 これは 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 サーバ バージョン 2.2

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

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 のアドレスが 192.0.2.1 だとします。では、次の設定について考えてみましょう。

<VirtualHost 192.0.2.1>
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>

現在のリリースでは Apache は DNS 逆引きを使用して このバーチャルホストの ServerName を見つけます。 その逆引きが失敗した場合は部分的にバーチャルホストを無効にします (Apache 1.2 より前では起動すらしません)。 バーチャルホストが名前ベースであれば完全に無効になりますが、 IP ベースであれば概ね動作します。しかしながら、サーバ名を 含む完全な URL を生成しなければならない場合は、正しい URL の生成ができません。

次の例は上記の問題を解決しています。

<VirtualHost 192.0.2.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>

192.0.2.1 を www.abc.dom に、 192.0.2.2 を www.def.dom に割り当てているとします。 また、def.dom は顧客自身の DNS の制御下にあるとします。この設定で、abc.dom に向けられたトラフィック全てを奪うことができる位置に def.dom を設置できています。後は単に www.def.dom が 192.0.2.1 を参照するように 設定するだけです。DNS は顧客側の DNS でコントロールされているので、 www.def.dom レコードが好きな場所を指すように 設定できてしまうのを止めさせることができません。

192.0.2.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 Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2

Frequently Asked Questions

The FAQ has moved to the HTTP Server Wiki.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Apache の SSL/TLS 暗号化 - Apache HTTP サーバ バージョン 2.2

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

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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > 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 Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > SSL/TLS

SSL/TLS Strong Encryption: Compatibility

This page covers backwards compatibility between mod_ssl and other SSL solutions. mod_ssl is not the only SSL solution for Apache; four additional products are (or were) also available: Ben Laurie's freely available Apache-SSL (from where mod_ssl were originally derived in 1998), Red Hat's commercial Secure Web Server (which was based on mod_ssl), Covalent's commercial Raven SSL Module (also based on mod_ssl) and finally C2Net's (now Red Hat'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).

mod_ssl mostly provides a superset of the functionality of all the other solutions, so it's simple to migrate from one of the older modules to mod_ssl. The configuration directives and environment variable names used by the older SSL solutions vary from those used in mod_ssl; mapping tables are included here to give the equivalents used by mod_ssl.

Configuration Directives

The mapping between configuration directives used by Apache-SSL 1.x and mod_ssl 2.0.x is given in Table 1. The mapping from Sioux 1.x and Stronghold 2.x is only partial because of special functionality in these interfaces which mod_ssl 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 | - | Use per-module LogLevel setting instead.
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 | - | Use per-module LogLevel setting instead.
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 engine | SSLCryptoDevice engine | renamed
StrongholdKey dir | - | functionality not needed
StrongholdLicenseFile dir | - | functionality not needed
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 | SSLProxyMachineCertificatePath dir | renamed
SSLProxyMachineCertFile file | SSLProxyMachineCertificateFile file | renamed
SSLProxyCipherList spec | SSLProxyCipherSpec spec | renamed

Environment Variables

The mapping between environment variable names used by the older SSL solutions and the names used by mod_ssl is given 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 enabled, 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)

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


SSL/TLS Strong Encryption: How-To - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > SSL/TLS

SSL/TLS Strong Encryption: How-To

The solution to this problem is trivial and is left as an exercise for the reader.

-- Standard textbook cookie

How to solve particular security problems for an SSL-aware webserver is not always obvious because of the interactions between SSL, HTTP and Apache's way of processing requests. This chapter gives instructions on how to solve some 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 how it interacts with other systems.

Cipher Suites and Enforcing Strong Security

  • How can I create a real SSLv2-only server?
  • How can I create an SSL server which accepts strong encryption only?
  • How can I create an SSL server which accepts strong encryption only, but allows export browsers to upgrade to stronger encryption?
  • How can I create an SSL server which accepts all types of ciphers in general, but requires a strong cipher for access to a particular URL?

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 requires a Global ID server certificate, signed by a special CA certificate from Verisign. This enables strong encryption in 'export' versions of browsers, which traditionally could not support it (because of US export restrictions).

When a browser connects with an export cipher, the server sends its Global ID certificate. The browser verifies this, and can then upgrade its cipher suite before any HTTP communication takes place. The problem lies in allowing browsers to upgrade in this fashion, but still requiring strong encryption. In other words, we want browsers to either start a connection with strong encryption, or to start with export ciphers but upgrade to strong encryption before beginning HTTP communication.

This can be done as follows:

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, a server-wide SSLCipherSuite which restricts ciphers to the strong variants, isn't the answer here. However, mod_ssl can be reconfigured within Location blocks, to give a per-directory solution, and can automatically force a renegotiation of the SSL parameters to meet the new configuration. This can be done as follows:

# 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

  • How can I force clients to authenticate using certificates?
  • How can I force clients to authenticate using certificates for a particular URL, but still allow arbitrary clients to access the rest of the server?
  • How can I allow only clients who have certificates to access a particular URL, but allow all clients to access the rest of the server?
  • How can I require HTTPS with strong ciphers, and either basic authentication or client certificates, for access to part of the Intranet website, for clients coming from the Internet?

How can I force clients to authenticate using certificates?

When you know all of your users (eg, as is often the case on a corporate Intranet), you can require plain certificate authentication. All you need 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 force clients to authenticate using certificates for a particular URL, but still allow arbitrary clients to access the rest of the server?

To force clients to authenticate using certificates for a particular URL, you can use the per-directory reconfiguration features of mod_ssl:

httpd.conf

SSLVerifyClient none
SSLCACertificateFile conf/ssl.crt/ca.crt

<Location /secure/area>
SSLVerifyClient require
SSLVerifyDepth 1
</Location>

How can I allow only clients who have certificates to access a particular URL, but allow all clients to access the rest of the server?

The key to doing this is checking that part of the client certificate matches what you expect. Usually this means checking all or part of the Distinguished Name (DN), to see if it contains some known string. There are two ways to do this, using either mod_auth_basic or SSLRequire.

The mod_auth_basic method is generally required when the certificates are completely arbitrary, or when their DNs have no common fields (usually the organisation, etc.). In this case, you should establish a password database containing all clients allowed, as follows:

httpd.conf

SSLCACertificateFile conf/ssl.crt/ca.crt
SSLCACertificatePath conf/ssl.crt
SSLVerifyClient      none

<Directory /usr/local/apache2/htdocs/secure/area>
SSLVerifyClient      require
SSLVerifyDepth       5
SSLOptions           +FakeBasicAuth
SSLRequireSSL
AuthName             "Snake Oil Authentication"
AuthType             Basic
AuthBasicProvider    file
AuthUserFile         /usr/local/apache2/conf/httpd.passwd
Require              valid-user
</Directory>

The password used in this example is the DES encrypted string "password". See the SSLOptions docs for more information.

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

When your clients are all part of a common hierarchy, which is encoded into the DN, you can match them more easily using SSLRequire, as follows:

httpd.conf

SSLVerifyClient      none
SSLCACertificateFile conf/ssl.crt/ca.crt
SSLCACertificatePath conf/ssl.crt

<Directory /usr/local/apache2/htdocs/secure/area>
  SSLVerifyClient      require
  SSLVerifyDepth       5
  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 part of the Intranet website, for clients coming from the Internet? I still want to allow plain HTTP access for clients on the Intranet.

These examples presume that clients on the Intranet have IPs in the range 192.168.1.0/24, and that the part of the Intranet website you want to allow internet access to is /usr/local/apache2/htdocs/subarea. This configuration should remain outside of your HTTPS virtual host, so that 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"
AuthBasicProvider    file
AuthUserFile         conf/protected.passwd
Require              valid-user
</Directory>

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


SSL/TLS Strong Encryption: FAQ - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 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.

After US export restrictions on cryptographic software were loosened, mod_ssl became part of the Apache HTTP Server with the release of Apache httpd 2.

Is mod_ssl affected by 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 in 1995, to control trade in conventional arms and dual-use goods and technology. It replaced the previous CoCom regime. Further details on both the Arrangement and its signatories are available 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, that is, something 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 we find In the public domain defined as "technology" or "software" which has been made available without restrictions upon its further dissemination. Note: 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 Arrangement and its List of Dual Use Goods and Technologies And Munitions List, and thus not affected by its provisions.

Installation

  • Why do I get permission errors related to SSLMutex when I start Apache?
  • Why does mod_ssl stop with the error "Failed to generate temporary 512 bit RSA private key" when I start Apache?

Why do I get permission errors related to SSLMutex when I start Apache?

Errors such as ``mod_ssl: Child could not open SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows) [...] System: Permission denied (errno: 13)'' are usually caused by overly 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 for, at minimum, the UID under which Apache's children are running (see the User directive).

Why does mod_ssl stop with the error "Failed to generate temporary 512 bit RSA private key" when I start Apache?

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.

To prevent this error, mod_ssl has to provide enough entropy to the PRNG to allow it to work correctly. This can be done via the SSLRandomSeed directive.

Configuration

  • Is it possible to provide HTTP and HTTPS from the same server?
  • Which port does HTTPS use?
  • How do I speak HTTPS manually for testing purposes?
  • Why does the connection hang when I connect to my SSL-aware Apache server?
  • Why do I get ``Connection Refused'' errors, when trying to access my newly installed Apache+mod_ssl server via HTTPS?
  • Why are the SSL_XXX variables not available to my CGI & SSI scripts?
  • How can I switch between HTTP and HTTPS in relative hyperlinks?

Is it possible to provide HTTP and HTTPS from the same server?

Yes. HTTP and HTTPS use different server ports (HTTP binds to port 80, HTTPS to port 443), so there is no direct conflict between them. You can either run two separate server instances bound to these ports, or use Apache's elegant virtual hosting facility to create two virtual servers, both served by the same instance of Apache - one responding over HTTP to requests on port 80, and the other responding over HTTPS to requests on port 443.

Which port does HTTPS use?

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. For example, if your server is set up to serve pages over HTTPS on port 8080, you can access them at https://example.com:8080/

How do I speak HTTPS manually for testing purposes?

While you usually just use

$ telnet localhost 80
GET / HTTP/1.0

for simple testing of Apache via HTTP, it's not so easy for HTTPS because of the SSL protocol between TCP and HTTP. With the help of OpenSSL's s_client command, however, you can do a similar check via HTTPS:

$ openssl s_client -connect localhost:443 -state -debug
GET / HTTP/1.0

Before the actual HTTP response you will receive detailed information about the SSL handshake. For a more general command line client which directly understands both HTTP and HTTPS, can perform GET and POST operations, can use a proxy, supports byte ranges, etc. you should have a look at the nifty cURL tool. Using this, you can check that Apache is responding correctly to requests via HTTP and HTTPS as follows:

$ curl http://localhost/
$ curl https://localhost/

Why does the connection hang when I connect to my SSL-aware Apache server?

This can happen when you try to connect to a HTTPS server (or virtual server) via HTTP (eg, using http://example.com/ instead of https://example.com). It can also happen when trying to connect via HTTPS to a HTTP server (eg, using https://example.com/ on a server which doesn't support HTTPS, or which supports it on a non-standard port). Make sure that you're connecting to a (virtual) server that supports SSL.

Why do I get ``Connection Refused'' messages, when trying to access my newly installed Apache+mod_ssl server via HTTPS?

This error can be caused by an incorrect configuration. Please make sure that your Listen directives match your <VirtualHost> directives. If all else fails, please start afresh, using the default configuration provided by mod_ssl.

Why are the SSL_XXX variables not available to my CGI & SSI scripts?

Please make sure you have ``SSLOptions +StdEnvVars'' enabled for the context of your CGI/SSI requests.

How can I switch between HTTP and HTTPS in relative hyperlinks?

Usually, to switch between HTTP and HTTPS, you have to use fully-qualified hyperlinks (because you have to change the URL scheme). Using mod_rewrite however, you can manipulate relative hyperlinks, to achieve the same effect.

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">, to switch to HTTPS in a relative link. (Replace SSL with NOSSL to switch to HTTP.)

Certificates

  • What are RSA Private Keys, CSRs and Certificates?
  • Is there a difference on startup between a non-SSL-aware Apache and an SSL-aware Apache?
  • How do I create a self-signed SSL Certificate for testing purposes?
  • How do I create a real SSL Certificate?
  • How do I create and use my own Certificate Authority (CA)?
  • How can I change the pass-phrase on my private key file?
  • How can I get rid of the pass-phrase dialog at Apache startup time?
  • How do I verify that a private key matches its Certificate?
  • Why do connections fail with an "alert bad certificate" error?
  • Why does my 2048-bit private key not work?
  • Why is client authentication broken after upgrading from SSLeay version 0.8 to 0.9?
  • How can I convert a certificate from PEM to DER format?
  • Why can't I find the getca or getverisign programs mentioned by Verisign, for installing my Verisign certificate?
  • Can I use the Server Gated Cryptography (SGC) facility (aka Verisign Global ID) with mod_ssl?
  • Why do browsers complain that they cannot verify my server certificate?

What are RSA Private Keys, CSRs and Certificates?

An 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), who will convert it into a real Certificate, by signing it.

A Certificate contains your RSA public key, your name, the name of the CA, and is digitally signed by the 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.

Is there a difference on startup between a non-SSL-aware Apache and an SSL-aware Apache?

Yes. In general, starting Apache with mod_ssl built-in is just like starting Apache without it. However, if you have a passphrase on your SSL private key file, a startup dialog will pop up which asks you to enter the pass phrase.

Having to manually enter the passphrase when starting the server can be problematic - for example, when starting the server from the system boot scripts. In this case, you can follow the steps below to remove the passphrase from your private key. Bear in mind that doing so brings additional security risks - proceed with caution!

How do I create a self-signed SSL Certificate for testing purposes?

  1. Make sure OpenSSL is installed and in your PATH.

  2. Run the following command, to create server.key and server.crt files:
    $ openssl req -new -x509 -nodes -out server.crt -keyout server.key
    These can be used as follows in your httpd.conf file:
                 SSLCertificateFile    /path/to/this/server.crt
             SSLCertificateKeyFile /path/to/this/server.key
  3. It is important that you are aware that this server.key does not have any passphrase. To add a passphrase to the key, you should run the following command, and enter & verify the passphrase as requested.

    $ openssl rsa -des3 -in server.key -out server.key.new
    $ mv server.key.new server.key

    Please backup the server.key file, and the passphrase you entered, in a secure location.

How do I create a real SSL Certificate?

Here is a step-by-step description:

  1. Make sure OpenSSL is installed and in your PATH.

  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 the pass-phrase you entered in a secure location. You can see the details of this RSA private key by using the command:

    $ openssl rsa -noout -text -in server.key

    If necessary, you can also create a decrypted PEM version (not recommended) of this RSA private key with:

    $ 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 by using

    $ openssl req -noout -text -in server.csr

  4. You now have to send this Certificate Signing Request (CSR) to a Certifying Authority (CA) to be signed. Once the CSR has been signed, you will have a real Certificate, which can be used by Apache. You can have a CSR signed by a commercial CA, or you can create your own CA to sign it.
    Commercial CAs usually ask you to post the CSR into a web form, pay for the signing, and then send a signed Certificate, which you can store in a server.crt file. For more information about commercial CAs see the following locations:

    1. Verisign
      http://digitalid.verisign.com/server/apacheNotice.htm
    2. Thawte
      http://www.thawte.com/
    3. CertiSign Certificadora Digital Ltda.
      http://www.certisign.com.br
    4. IKS GmbH
      http://www.iks-jena.de/leistungen/ca/
    5. Uptime Commerce Ltd.
      http://www.uptimecommerce.com
    6. BelSign NV/SA
      http://www.belsign.be
    For details on how to create your own CA, and use this to sign a CSR, see below.
    Once your CSR has been signed, you can see the details of the Certificate as follows:

    $ openssl x509 -noout -text -in server.crt
  5. You should now have two files: server.key and server.crt. These can be used as follows in your httpd.conf file:
           SSLCertificateFile    /path/to/this/server.crt
       SSLCertificateKeyFile /path/to/this/server.key
    The server.csr file is no longer needed.

How do 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. Unless you have a good reason not to, you should use these for preference. If you cannot, you can create a self-signed Certificate as follows:

  1. Create a RSA private key for your server (will be Triple-DES encrypted and PEM formatted):

    $ openssl genrsa -des3 -out server.key 1024

    Please backup this server.key file and the pass-phrase you entered in a secure location. You can see the details of this RSA private key by using the command:

    $ openssl rsa -noout -text -in server.key

    If necessary, you can also create a decrypted PEM version (not recommended) of this RSA private key with:

    $ openssl rsa -in server.key -out server.key.unsecure

  2. Create a self-signed Certificate (X509 structure) with the RSA key you just created (output will be PEM formatted):

    $ openssl req -new -x509 -nodes -sha1 -days 365 -key server.key -out server.crt

    This signs the server CSR and results in a server.crt file.
    You can see the details of this Certificate using:

    $ openssl x509 -noout -text -in server.crt

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, 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

The first time you're asked for a PEM pass-phrase, you should enter the old pass-phrase. After that, you'll be asked again to enter a pass-phrase - this time, use the new pass-phrase. If you are asked to verify the pass-phrase, you'll need to enter the new pass-phrase a second time.

How can I get rid of the pass-phrase dialog at Apache startup time?

The reason 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 decrypt this file, so it can be read and parsed. Removing the pass-phrase removes a layer of security from your server - proceed with caution!

  1. Remove the encryption from the RSA private key (while keeping a backup copy of 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 only readable by root:

    $ chmod 400 server.key

Now server.key contains 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 this file are 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 user, and have the key readable only by root).

As an alternative approach you can use the ``SSLPassPhraseDialog exec:/path/to/program'' facility. Bear in mind that this is neither more nor less secure, of course.

How do I verify that a private key matches its Certificate?

A private key contains a series of numbers. Two of these numbers form the "public key", the others are part of the "private key". The "public key" bits are included when you generate a CSR, and subsequently form part of the associated Certificate.

To check that the public key in your Certificate matches the public portion of your private key, you simply need to compare these 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. As the public exponent is usually 65537 and it's difficult to visually check that the long modulus numbers are the same, you can use the following approach:

$ openssl x509 -noout -modulus -in server.crt | openssl md5
$ openssl rsa -noout -modulus -in server.key | openssl md5

This leaves you with two rather shorter numbers to compare. It is, in theory, possible that these numbers may be the same, without the modulus numbers being the same, but the chances of this are overwhelmingly remote.

Should you wish to check to which key or certificate a particular CSR belongs you can perform the same calculation on the CSR as follows:

$ openssl req -noout -modulus -in server.csr | openssl md5

Why do connections fail with an "alert bad certificate" error?

Errors such as OpenSSL: error:14094412: SSL routines:SSL3_READ_BYTES:sslv3 alert bad certificate in the SSL logfile, are usually caused by a browser which is unable to handle the server certificate/private-key. For example, Netscape Navigator 3.x is unable to handle RSA key lengths not equal to 1024 bits.

Why does my 2048-bit private key not work?

The private key sizes for SSL must be either 512 or 1024 bits, 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. However, the algorithm used to calculate the hash for a certificate changed between SSLeay 0.8 and 0.9. You will need to remove all old hash symlinks and create new ones after upgrading. Use the Makefile provided by mod_ssl.

How can I convert a certificate from PEM to DER format?

The default certificate format for SSLeay/OpenSSL is PEM, which is simply 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 using the following command: $ openssl x509 -in cert.pem -out cert.der -outform DER

Why can't I find the getca or getverisign programs mentioned by Verisign, for installing my Verisign certificate?

Verisign has never provided specific instructions for Apache+mod_ssl. The instructions provided are for C2Net's Stronghold (a commercial Apache based server with SSL support).

To install your certificate, all you need to do is to save the certificate to a file, and give the name of that file to the SSLCertificateFile directive. You will also need to give it the key file. For more information, see the SSLCertificateKeyFile directive.

Can I use the Server Gated Cryptography (SGC) facility (aka Verisign Global ID) with mod_ssl?

Yes. mod_ssl has included support for the SGC facility since version 2.1. No special configuration is required - just use the Global ID as your server certificate. The step up of the clients is then automatically handled by mod_ssl at run-time.

Why do browsers complain that they cannot verify my server certificate?

One reason this might happen is because your server certificate is signed by an intermediate CA. Various CAs, such as Verisign or Thawte, have started signing certificates not with their root certificate but with intermediate certificates.

Intermediate CA certificates lie between the root CA certificate (which is installed in the browsers) and the server certificate (which you installed on the server). In order for the browser to be able to traverse and verify the trust chain from the server certificate to the root certificate it needs need to be given the intermediate certificates. The CAs should be able to provide you such intermediate certificate packages that can be installed on the server.

You need to include those intermediate certificates with the SSLCertificateChainFile directive.

The SSL Protocol

  • Why do I get lots of random SSL protocol errors under heavy server load?
  • Why does my webserver have a higher load, now that it serves SSL encrypted traffic?
  • Why do HTTPS connections to my server sometimes take up to 30 seconds to establish a connection?
  • What SSL Ciphers are supported by mod_ssl?
  • Why do I get ``no shared cipher'' errors, when trying to use Anonymous Diffie-Hellman (ADH) ciphers?
  • Why do I get a 'no shared ciphers' error when connecting to my newly installed server?
  • Why can't I use SSL with name-based/non-IP-based virtual hosts?
  • Is it possible to use Name-Based Virtual Hosting to identify different SSL virtual hosts?
  • How do I get SSL compression working?
  • When I use Basic Authentication over HTTPS the lock icon in Netscape browsers stays unlocked when the dialog pops up. Does this mean the username/password is being sent unencrypted?
  • Why do I get I/O errors when connecting via HTTPS to an Apache+mod_ssl server with Microsoft Internet Explorer (MSIE)?
  • Why do I get I/O errors, or the message "Netscape has encountered bad data from the server", when connecting via HTTPS to an Apache+mod_ssl server with Netscape Navigator?
  • Why do I get handshake failures with Java-based clients when using a certificate with more than 1024 bits?

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 the most likely source of the problem, so using the SHM session cache (or no cache at all) may help.

Why does my webserver have a higher load, now that it serves SSL encrypted traffic?

SSL uses strong cryptographic encryption, which necessitates a lot of number crunching. When you request a webpage via HTTPS, everything (even the images) is encrypted before it is transferred. So increased HTTPS traffic leads to load increases.

Why do HTTPS connections to my server sometimes take up to 30 seconds to establish a connection?

This is usually caused by a /dev/random device for SSLRandomSeed which blocks the read(2) call until enough entropy is available to service the request. More information is available in the reference manual for the SSLRandomSeed directive.

What SSL Ciphers are supported by mod_ssl?

Usually, any SSL ciphers supported by the version of OpenSSL in use, are also supported by mod_ssl. Which ciphers are available can depend on the way you built OpenSSL. Typically, at least the following ciphers are supported:

  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 ciphers available, you should run the following:

$ openssl ciphers -v

Why do I get ``no shared cipher'' errors, when trying to use Anonymous Diffie-Hellman (ADH) ciphers?

By default, OpenSSL does not allow ADH ciphers, for security reasons. Please be sure you are aware of the potential side-effects if you choose to enable these ciphers.

In order to use Anonymous Diffie-Hellman (ADH) ciphers, you must build OpenSSL with ``-DSSL_ALLOW_ADH'', and then add ``ADH'' into your SSLCipherSuite.

Why do I get a 'no shared ciphers' error when connecting to my newly installed server?

Either you have made a mistake with your SSLCipherSuite directive (compare it with the pre-configured example in httpd.conf-dist) or you chose to use 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 cannot communicate using RSA-based SSL ciphers (at least until you configure an additional RSA-based certificate/key pair). Modern browsers like NS or IE can only communicate over SSL using RSA ciphers. The result is the "no shared ciphers" error. To fix this, regenerate your server certificate/key pair, using the RSA algorithm.

Why can't I use SSL with name-based/non-IP-based virtual hosts?

The reason is very technical, and a somewhat "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 go to the correct virtual server Apache has to know the Host HTTP header field. To do this, the HTTP request header has to be read. This cannot be done before the SSL handshake is finished, but the information is needed in order to complete the SSL handshake phase. See the next question for how to circumvent this issue.

Note that if you have a wildcard SSL certificate, or a certificate that has multiple hostnames on it using subjectAltName fields, you can use SSL on name-based virtual hosts without further workarounds.

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 is possible, but only if using a 2.2.12 or later web server, built with 0.9.8j or later OpenSSL. This is because it requires a feature that only the most recent revisions of the SSL specification added, called Server Name Indication (SNI).

Note that if you have a wildcard SSL certificate, or a certificate that has multiple hostnames on it using subjectAltName fields, you can use SSL on name-based virtual hosts without further workarounds.

The reason is that the SSL protocol is a separate layer which encapsulates the HTTP protocol. So the SSL session is a separate transaction, that takes place before the HTTP session has begun. The server receives an SSL request on IP address X and port Y (usually 443). Since the SSL request did not contain any Host: field, the server had no way to decide which SSL virtual host to use. Usually, it just used the first one it found which matched the port and IP address specified.

If you are using a version of the web server and OpenSSL that support SNI, though, and the client's browser also supports SNI, then the hostname is included in the original SSL request, and the web server can select the correct SSL virtual host.

You can, of course, use Name-Based Virtual Hosting to identify many non-SSL virtual hosts (all on port 80, for example) and then have a single 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 include:

Using separate IP addresses for different SSL hosts. Using different port numbers for different SSL hosts.

How do I get SSL compression working?

Although SSL compression negotiation was defined in the specification of SSLv2 and TLS, it took until May 2004 for RFC 3749 to define DEFLATE as a negotiable standard compression method.

OpenSSL 0.9.8 started to support this by default when compiled with the zlib option. If both the client and the server support compression, it will be used. However, most clients still try to initially connect with an SSLv2 Hello. As SSLv2 did not include an array of prefered compression algorithms in its handshake, compression cannot be negotiated with these clients. If the client disables support for SSLv2, either an SSLv3 or TLS Hello may be sent, depending on which SSL library is used, and compression may be set up. You can verify whether clients make use of SSL compression by logging the %{SSL_COMPRESS_METHOD}x variable.

When I use Basic Authentication over HTTPS the lock icon in Netscape browsers stays unlocked when the dialog pops up. Does this mean the username/password is being sent unencrypted?

No, the username/password is transmitted encrypted. The icon in Netscape browsers is not actually synchronized with the SSL/TLS layer. It only toggles to the locked state when the first part of the actual webpage data is transferred, which may confuse people. The Basic Authentication facility is part of the HTTP layer, which is above the SSL/TLS layer in HTTPS. Before any HTTP data communication takes place in HTTPS, the SSL/TLS layer has already completed its handshake phase, and switched to encrypted communication. So don't be confused by this icon.

Why do I get I/O errors when connecting via HTTPS to an Apache+mod_ssl server with Microsoft Internet Explorer (MSIE)?

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 in some MSIE versions. You can work around these problems by forcing Apache not to use HTTP/1.1, keep-alive connections or send 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

Further, some MSIE versions have problems with particular ciphers. Unfortunately, it is not possible to implement a MSIE-specific workaround for this, because the ciphers are needed as early as the SSL handshake phase. So a MSIE-specific SetEnvIf won't solve these problems. Instead, you will have to make more drastic adjustments to the global parameters. Before you decide to do this, make sure your clients really have problems. If not, do not make these changes - they will affect all your clients, MSIE or otherwise.

The next problem is that 56bit export versions of MSIE 5.x browsers have a broken SSLv3 implementation, which interacts badly with OpenSSL versions greater than 0.9.4. You can accept this and require your clients to upgrade their browsers, you can downgrade to OpenSSL 0.9.4 (not advised), or you can work around this, accepting that your workaround will affect other browsers too:

SSLProtocol all -SSLv3

will completely disables the SSLv3 protocol and allow those browsers to work. A better workaround is to disable only those ciphers which cause trouble.

SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP

This also allows the broken MSIE versions to 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/ (where 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). Connecting 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 the SSLSessionCache directive).

Why do I get I/O errors, or the message "Netscape has encountered bad data from the server", when connecting via HTTPS to an Apache+mod_ssl server with Netscape Navigator?

This usually occurs when you have created a new server certificate for a given domain, but had previously told your browser to always accept the old server certificate. Once you clear the entry for the old certificate from your browser, everything should be fine. Netscape's SSL implementation is correct, so when you encounter I/O errors with Netscape Navigator it is usually caused by the configured certificates.

Why do I get handshake failures with Java-based clients when using a certificate with more than 1024 bits?

Beginning with version 2.2.30, mod_ssl will use DH parameters which include primes with lengths of more than 1024 bits. Java 7 and earlier limit their support for DH prime sizes to a maximum of 1024 bits, however.

If your Java-based client aborts with exceptions such as java.lang.RuntimeException: Could not generate DH keypair and java.security.InvalidAlgorithmParameterException: Prime size must be multiple of 64, and can only range from 512 to 1024 (inclusive), and httpd logs tlsv1 alert internal error (SSL alert number 80) (at LogLevel info or higher), you can either rearrange mod_ssl's cipher list with SSLCipherSuite (possibly in conjunction with SSLHonorCipherOrder), or you can use custom DH parameters with a 1024-bit prime, which will always have precedence over any of the built-in DH parameters.

To generate custom DH parameters, use the openssl dhparam 1024 command. Alternatively, you can use the following standard 1024-bit DH parameters from RFC 2409, section 6.2:

-----BEGIN DH PARAMETERS-----
MIGHAoGBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR
Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL
/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7OZTgf//////////AgEC
-----END DH PARAMETERS-----

Add the custom parameters including the "BEGIN DH PARAMETERS" and "END DH PARAMETERS" lines to the end of the first certificate file you have configured using the SSLCertificateFile directive.

mod_ssl Support

  • What information resources are available in case of mod_ssl problems?
  • What support contacts are available in case of mod_ssl problems?
  • What information should I provide when writing a bug report?
  • I had a core dump, can you help me?
  • How do I get a backtrace, to help find the reason for my core dump?

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.2/ssl/ssl_faq.html
First check the F.A.Q. (this text). If your problem is a common one, it may have been answered several times before, and been included in this doc.
Postings from the modssl-users Support Mailing List http://www.modssl.org/support/
Search for your problem in the archives of the modssl-users mailing list. You're probably not the first person to have had this problem!

What support contacts are available in case of mod_ssl problems?

The following lists all support possibilities for mod_ssl, in order of preference. Please go through these possibilities in this order - don't just pick the one you like the look of.

  1. Send a Problem Report to the modssl-users Support Mailing List
    modssl-users@modssl.org
    This is the preferred way of submitting your problem report, because this way, others can see the problem, and learn from any answers. You must subscribe to the list first, but you can then easily discuss your problem with both the author and the whole mod_ssl user community.
  2. Send a Problem Report to the Apache httpd Users Support Mailing List
    users@httpd.apache.org
    This is the second way of submitting your problem report. Again, you must subscribe to the list first, but you can then easily discuss your problem with the whole Apache httpd user community.
  3. Write a Problem Report in the Bug Database
    http://httpd.apache.org/bug_report.html
    This is the last way of submitting your problem report. You should only do this if you've already posted to the mailing lists, and had no success. Please follow the instructions on the above page carefully.

What information should I provide when writing a bug report?

You should always provide at least 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, if you have Lynx installed, you can run the command lynx -mime_header http://localhost/ | grep Server to gather this 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. If this is not possible, you should at least provide the configure command line you used.
In case of core dumps please include a Backtrace
If your Apache+mod_ssl+OpenSSL dumps its core, please attach a stack-frame ``backtrace'' (see below for information on how to get this). This information is required in order to find a reason for your core dump.
A detailed description of your problem
Don't laugh, we really mean it! Many problem reports don't include a description of what the actual problem is. Without this, it's very difficult for anyone to help you. So, it's in your own interest (you want the problem be solved, don't you?) to include as much detail as possible, please. Of course, you should still include all the essentials above too.

I had 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.

How do I get a backtrace, to help find the reason for my core dump?

Following are the steps you will need to complete, to get a backtrace:

  1. Make sure you have debugging symbols available, at least in Apache. On platforms where you use GCC/GDB, you will have to build Apache+mod_ssl with ``OPTIM="-g -ggdb3"'' to get this. On other platforms at least ``OPTIM="-g"'' is needed.
  2. Start the server and try to reproduce the core-dump. For this you may want to use a directive like ``CoreDumpDirectory /tmp'' to make sure that the core-dump file can be written. This should result in a /tmp/core or /tmp/httpd.core file. If you don't get one of these, try running your server under a non-root UID. Many modern 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). If necessary, 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. In GDB, all you have to do then is to enter bt, and voila, you get the backtrace. For other debuggers consult your local debugger manual.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


How-To / チュートリアル - Apache HTTP サーバ バージョン 2.2

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

How-To / チュートリアル

How-To / チュートリアル

認証と承認

認証とは、誰かが自分は誰であるかを名乗っているものを検証する 処理のことです。承認とは、誰かが望みの場所に辿り着けたり、 望みの情報を手に入れたりすることを許可する処理のことです。

参照: 認証と承認

アクセス制御

アクセス制御とは、さまざまな戦略に基づいてリソースに対する アクセスを制限したり許可したりするプロセスを指します。 アクセス制御を実現する方法には、さまざまな方法があります。

See: アクセス制御

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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > How-To / チュートリアル

認証、承認、アクセス制御

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

「認証」とは、誰かが自分は誰であるかを主張した場合に、 それを確認するための全過程を指します。「承認」とは、 誰かが行きたい場所に行けるように、あるいは欲しい情報を 得ることができるようにするための全過程を指します。

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

関連モジュール 関連ディレクティブ
  • mod_auth_basic
  • mod_authn_file
  • mod_authz_groupfile
  • mod_authz_host
  • 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 で実装されています。しかしながら、 これは気を付けるべき重要なポイントなのですが、 Basic 認証はクライアントからサーバへ、 パスワードを暗号化せずに送ります。ですから、 この方法は特に機密性の高いデータに対しては用いるべきでは ありません。 Apache ではもう一つ別の認証方法: AuthType Digest をサポートしています。 この方法は mod_auth_digest で実装されていて、もっと安全です。 ごくごく最近のクライアントしか Digest 認証をサポートしていないようです。

AuthName ディレクティブでは、認証に使う Realm (訳注: 領域) を設定します。Realm は大きく分けて二つの機能を提供します。 一つ目は、クライアントがパスワードダイアログボックスの 一部としてユーザにこの情報をよく提示する、というものです。 二つ目には、クライアントが与えられた認証領域に対してどのパスワードを 送信すれば良いのかを決定するために使われる、という機能です。

例えば、"Restricted Files" 領域中で 一度認証されれば、同一サーバ上で "Restricted Files" Realm としてマークされたどんな領域でも、クライアントは 自動的に同じパスワードを使おうと試みます。 このおかげで、複数の制限領域に同じ realm を共有させて、 ユーザがパスワードを何度も要求される事態を 防ぐことができます。もちろん、セキュリティ上の理由から、 サーバのホスト名が変わればいつでも必ず、 クライアントは再びパスワードを尋ねる必要があります。

AuthUserFile ディレクティブは htpasswd で作った パスワードファイルへのパスを設定します。 ユーザ数が多い場合は、リクエスト毎のユーザの認証のための プレーンテキストの探索が非常に遅くなることがあります。 Apache ではユーザ情報を高速なデータベースファイルに 保管することもできます。 mod_authn_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_basic と mod_authz_host の文書も読むとよいでしょう。


Apache Tutorial: CGI による動的コンテンツ - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > 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://www.example.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 ファイル

.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 プログラムが他の環境変数に依存している場合は、その環境変数が Apache から渡されるようにする必要があります。

プログラムエラー

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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > 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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > How-To / チュートリアル

Apache チュートリアル: .htaccess ファイル

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

.htaccess ファイルはディレクトリ毎に設定を変更する方法を 提供します。

.htaccess ファイル

関連モジュール 関連ディレクティブ
  • core
  • mod_authn_file
  • mod_authz_groupfile
  • 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 のマージ

As discussed in the documentation on Configuration Sections, .htaccess files can override the <Directory> sections for the corresponding directory, but will be overriden by other types of configuration sections from the main configuration files. This fact can be used to enforce certain configurations, even in the presence of a liberal AllowOverride setting. For example, to prevent script execution while allowing anything else to be set in .htaccess you can use:

セクションの設定 に記載されているように、.htaccess ファイルを使って <Directory> セクションの設定をディレクトリ毎に上書きできますが、 メイン設定ファイル中にある、他の種類の設定セクションによって さらに上書きされることもあります。 この特徴を使って、 AllowOverride で自由度の高い設定があったとしても、ある特定の設定が確実に 反映されるようにできます。例えば、CGI スクリプトの実行は 不許可に、かつ、.htaccess でその他の項目は 設定できるように、という場合は次のようにできます :

<Directory />
Allowoverride All
 </Directory>

<Location />
Options +IncludesNoExec -ExecCGI
 </Location>

認証の例

もし認証の方法を知るためにこの部分に直接来たのであれば、次のことを 知っておくことが重要です。よくある誤解に、パスワード認証を行なうためには .htaccess ファイルを使う必要がある、というものがあります。 これは正しくありません。主サーバ設定ファイルの <Directory> セクションに 認証用のディレクティブを書く方が推奨される方法で、.htaccess ファイルは主サーバ設定ファイルを変更できないときにのみ使用すべきです。 いつ .htaccess ファイルを使うべきで、いつ使うべきではないかに ついては 上を参照してください。

以上のことをふまえた上で、もし .htaccess の使用が まだ必要だと思う場合は、次のようなものが望みのことをしてくれるかも しれません。

.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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > 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 チュートリアル を読んで ください。


Platform Specific Notes - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2

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

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Using Apache HTTP Server on Microsoft Windows - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Platform Specific Notes

Using Apache HTTP Server on Microsoft Windows

This document explains how to install, configure and run Apache 2.2 under Microsoft Windows. If you have questions after reviewing the documentation (and any event and error logs), you should consult the peer-supported users' mailing list.

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.

Operating System Requirements

The primary Windows platform for running Apache 2.2 is Windows 2000 or later. The binary installer only works with the x86 family of processors, such as Intel and AMD processors. Always obtain and install the current service pack to avoid operating system bugs.

Running Apache on Windows 9x is ignored by the developers, and is strongly discouraged. On Windows NT 4.0, installing Service Pack 6 is required. Apache HTTP Server versions later than 2.2 will not run on any operating system earlier than Windows 2000.

Downloading Apache for Windows

The Apache HTTP Server Project itself does not provide binary releases of software, only source code. Individual committers may provide binary packages as a convenience, but it is not a release deliverable.

If you cannot compile the Apache HTTP Server yourself, you can obtain a binary package from numerous binary distributions available on the Internet.

Popular options for deploying Apache httpd, and, optionally, PHP and MySQL, on Microsoft Windows, include:

  • ApacheHaus
  • Apache Lounge
  • BitNami WAMP Stack
  • WampServer
  • XAMPP

Installing Apache for Windows

You need Microsoft Installer 2.0 or above for the installation to work. For Windows NT 4.0 and 2000 refer to Microsoft's article KB 292539. Windows XP and later do not require this update. The Windows 98/ME installer engine appears to no longer be available from Microsoft, and these instructions no longer detail such prerequisites.

Note that you cannot install two versions of Apache 2.2 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.2 series on the same computer without problems. If you need to have two different 2.2 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 Software Foundation under which a directory called Apache2.2 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.

Advanced Installation Topics

One feature of the installer, "Build Headers and Libraries", can be ignored by most users, but should be installed if compiling third party modules. The "APR Iconv Code Pages" can similarly be omitted by most users, unless using mod_charset_lite or a third party module which relies on APR internationalization features.

There are requests to ship a .zip file from time to time. There is no point in the ASF consuming additional storage, mirroring and bandwidth for this purpose, because the .msi installer allows the installation artifacts to all be unpacked using the msiexec /a network installation option. Using this command against any .msi will result in an exploded tree of all of the individual files and components.

The installation options above can be customized by users familiar with msiexec.exe options and silent installation. The actual installer sources are available in the httpd/httpd/win32-msi/ tree of the httpd project subversion respository. For reference, some of the more common variables which may be modified are;

  • AgreeToLicense (toggle to "Yes")
  • ALLUSERS (choose between Null and "1")
  • ApplicationUsers (toggle to "OnlyCurrentUser")
  • EXISTING_APACHE_SERVICE_PATH
  • INSTALLDIR (default "ProgramFilesFolder\Apache Software Foundation\Apache2.2\")
  • INSTALLLEVEL (default "100", refer to list below)
  • RESOLVED_WINSOCK2 (toggle to "1")
  • SERVERADMIN
  • SERVERDOMAIN
  • SERVERNAME
  • SERVERPORT (default "80")
  • SERVERSSLPORT (default "443")
  • SERVICEINTERNALNAME (default "Apache2.2", no spaces!)
  • SERVICENAME (default "Apache2.2", include spaces)
  • SetupType (default "Typical")

The installation level of various features, which may be individually toggled, include;

  • Apache (1, base Apache HTTP Server 2.2 feature)
  • ApacheDocs (11, Apache Documentation)
  • ApacheMonitoring (41, Apache Service Taskbar Icon)
  • ApacheRuntime (1, Apache Runtime)
  • BuildFiles (101, Build Headers and Libraries)
  • Iconv (21, APR Iconv Code Pages)
  • OpensslBin (31, OpenSSL Runtime)
  • SslBin (41, Ssl Binaries)

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 can 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 (actually, connections) which a single child process will serve before exiting. However, unlike on Unix, a replacement process is not instantly available. Use the default MaxRequestsPerChild 0, unless instructed to change the behavior to overcome a memory leak in third party modules or in-process applications.

    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 150, but this must be adjusted to reflect the greatest anticipated number of simultaneous connections to accept.

  • The directives that accept filenames as arguments must use Windows filenames instead of Unix ones. However, because Apache may interpret backslashes as an "escape character" sequence, you should consistently use forward slashes in path names, not backslashes.

  • While filenames are generally case-insensitive on Windows, URLs are still treated internally as case-sensitive before they are mapped to the filesystem. For example, the <Location>, Alias, and ProxyPass directives all use case-sensitive arguments. For this reason, it is particularly important to use the <Directory> directive when attempting to limit access to content in the filesystem, since this directive applies to any content in a directory, regardless of how it is accessed. If you wish to assure that only lowercase is used in URLs, you can use something like:

    RewriteEngine On
    RewriteMap lowercase int:tolower
    RewriteCond %{REQUEST_URI} [A-Z]
    RewriteRule (.*) ${lowercase:$1} [R,L]

  • When running, Apache needs write access only to the logs directory and any configured cache directory tree. Due to the issue of case insensitive and short 8.3 format names, Apache must validate all path names given. This means that each directory which Apache evaluates, from the drive root up to the directory leaf, must have read, list and traverse directory permissions. If Apache2.2 is installed at C:\Program Files, then the root directory, Program Files and Apache2.2 must all be visible to Apache.

  • 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.2\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 such as those used by Microsoft IIS and other Windows servers. More information is available. Note that Apache cannot load ISAPI Filters, and ISAPI Handlers with some Microsoft feature extensions will not work.

  • 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 is not yet prepared to use the error.log file. You can review the Windows Application Event Log by using the Event Viewer, e.g. Start - Settings - Control Panel - Administrative Tools - Event Viewer.

Running Apache as a Service

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:

httpd.exe -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. If you specify a name during the install, you have to also specify it during any other -k operation.

httpd.exe -k install -n "MyServiceName"

If you need to have specifically named configuration files for different services, you must use this:

httpd.exe -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.2 and the configuration will be assumed to be conf\httpd.conf.

Removing an Apache service is easy. Just use:

httpd.exe -k uninstall

The specific Apache service to be uninstalled can be specified by using:

httpd.exe -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.2 and NET STOP Apache2.2 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:

httpd.exe -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:

httpd.exe -k start -n "MyServiceName"

To stop an Apache service via the command line switches, use this:

httpd.exe -k stop -n "MyServiceName"

or

httpd.exe -k shutdown -n "MyServiceName"

You can also restart a running service and force it to reread its configuration file by using:

httpd.exe -k restart -n "MyServiceName"

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.

It is recommended that users create a separate account for running Apache service(s). If you have to access network resources via Apache, this is required.

  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 httpd.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.2 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.2 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.

If you are having problems with the service, it is suggested you follow the instructions below to try starting httpd.exe from a console window, and work out the errors before struggling to start it as a service again.

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:

httpd.exe

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.2.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.

If Apache is running as a service, you can tell it to stop by opening another console window and entering:

httpd.exe -k shutdown

Running as a service should be preferred over running in a console window because this lets Apache end any current operations and clean up gracefully.

But if the server is running in a console window, you can only stop it by pressing Control-C in the same window.

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, either press Control-Break in the console window you used for starting Apache, or enter

httpd.exe -k restart

if the server is running as a service.

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 httpd.exe, 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 Software Foundation\Apache2.2\bin"
httpd.exe

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:

    httpd.exe -f "c:\my server files\anotherconfig.conf"

    or

    httpd.exe -f files\anotherconfig.conf

  • -n specifies the installed Apache service whose configuration file is to be used:

    httpd.exe -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:

httpd.exe -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 httpd.exe -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 Software Foundation\Apache\2.2.2

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 Software Foundation\Apache\2.2.2

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 you should see "It Works!". 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/

If you happen to be running Apache on an alternate port, you need to explicitly put that in the URL:

http://127.0.0.1:8080/

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, some firewall implementations, and even some client applications (such as Skype) which will use port 80 to attempt to bypass firewall issues.

Configuring Access to Network Resources

Access to files over the network can be specified using two mechanisms provided by Windows:

Mapped drive letters
e.g., Alias /images/ Z:/
UNC paths
e.g., Alias /images/ //imagehost/www/images/

Mapped drive letters allow the administrator to maintain the mapping to a specific machine and path outside of the Apache httpd configuration. However, these mappings are associated only with interactive sessions and are not directly available to Apache httpd when it is started as a service. Use only UNC paths for network resources in httpd.conf so that the resources can be accessed consistently regardless of how Apache httpd is started. (Arcane and error prone procedures may work around the restriction on mapped drive letters, but this is not recommended.)

Example DocumentRoot with UNC path

DocumentRoot //dochost/www/html/

Example DocumentRoot with IP address in UNC path

DocumentRoot //192.168.1.50/docs/

Example Alias and corresponding Directory with UNC path

Alias /images/ //imagehost/www/images/

<Directory //imagehost/www/images/>
...
<Directory>

When running Apache httpd as a service, you must create a separate account in order to access network resources, as described above.

Windows Tuning

  • If more than a few dozen piped loggers are used on an operating system instance, scaling up the "desktop heap" is often necessary. For more detailed information, refer to the piped logging documentation.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Compiling Apache for Microsoft Windows - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 200 MB of free disk space available. After installation Apache requires approximately 80 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, especially when OpenSSL is also built. Because many files are text and very easily compressed, NTFS filesystem compression cuts these requirements in half.

  • Appropriate Patches

    The httpd binary is built with the help of several patches to third party packages, which ensure the released code is buildable and debuggable. These patches are available and distributed from http://www.apache.org/dist/httpd/binaries/win32/patches_applied/ and are recommended to be applied to obtain identical results as the "official" ASF distributed binaries.

  • Microsoft Visual C++ 6.0 (Visual Studio 97) or later.

    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.bat script.

    You may want the Visual Studio Processor Pack for your older version of Visual Studio, or a full (not Express) version of newer Visual Studio editions, for the ml.exe assembler. This will allow you to build OpenSSL, if desired, using the more efficient assembly code implementation.
    Only the Microsoft compiler tool chain is actively supported by the active httpd contributors. Although the project regularly accepts patches to ensure MinGW and other alternative builds work and improve upon them, they are not actively maintained and are often broken in the course of normal development.

  • Updated Microsoft Windows Platform SDK, February 2003 or later.

    An appropriate Windows Platform SDK is included by default in the full (not express/lite) versions of Visual C++ 7.1 (Visual Studio 2002) and later, these users can ignore these steps unless explicitly choosing a newer or different version of the Platform SDK.

    To use Visual C++ 6.0 or 7.0 (Studio 2000 .NET), the Platform SDK environment must be prepared using the setenv.bat script (installed by the Platform SDK) before starting the command line build or launching the msdev/devenv GUI environment. Installing the Platform SDK for Visual Studio Express versions (2003 and later) should adjust the default environment appropriately.

    "c:\Program Files\Microsoft Visual Studio\VC98\Bin\VCVARS32"
    "c:\Program Files\Platform SDK\setenv.bat"

  • Perl and awk

    Several steps recommended here require a perl interpreter during the build preparation process, but it is otherwise not required.

    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 modifying configuration files upon installation. Brian Kernighan's http://www.cs.princeton.edu/~bwk/btl.mirror/ site has a compiled native Win32 binary, http://www.cs.princeton.edu/~bwk/btl.mirror/awk95.exe which you must save with the name awk.exe (rather than awk95.exe).

    If awk.exe is not found, Makefile.win's install target will not perform substitutions in the installed .conf files. You must manually modify the installed .conf files to allow the server to start. Search and replace all "@token@" tags as appropriate.
    The Visual Studio IDE will only find awk.exe from the PATH, or executable path specified in the menu option Tools -> Options -> (Projects ->) Directories. Ensure awk.exe is in your system path.
    Also note that if you are using Cygwin tools (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 this building InstallBin will fail. A workaround is to delete awk.exe from the cygwin installation and copy gawk.exe to awk.exe. Also note the cygwin/mingw ports of gawk 3.0.x were buggy, please upgrade to 3.1.x before attempting to use any gawk port.

  • [Optional] zlib library (for mod_deflate)

    Zlib must be installed into a srclib subdirectory named zlib. This must be built in-place. Zlib can be obtained from http://www.zlib.net/ -- the mod_deflate is confirmed to work correctly with version 1.2.3.

    nmake -f win32\Makefile.msc
    nmake -f win32\Makefile.msc test

  • [Optional] OpenSSL libraries (for mod_ssl and ab.exe with ssl support)

    The OpenSSL library is cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See http://www.wassenaar.org/ for more information.

    Configuring and building OpenSSL requires perl to be installed.

    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.exe project, which is ab.c with SSL support enabled. To prepare OpenSSL to be linked to Apache mod_ssl or abs.exe, and disable patent encumbered features in OpenSSL, you might use the following build commands:

    perl Configure no-rc5 no-idea enable-mdc2 enable-zlib VC-WIN32 -Ipath/to/srclib/zlib -Lpath/to/srclib/zlib
    ms\do_masm.bat
    nmake -f ms\ntdll.mak

    It is not advisable to use zlib-dynamic, as that transfers the cost of deflating SSL streams to the first request which must load the zlib dll. Note the suggested patch enables the -L flag to work with windows builds, corrects the name of zdll.lib and ensures .pdb files are generated for troubleshooting. If the assembler is not installed, you would add no-asm above and use ms\do_ms.bat instead of the ms\do_masm.bat script.

  • [Optional] Database libraries (for mod_dbd and mod_authn_dbm)

    The apr-util library exposes dbm (keyed database) and dbd (query oriented database) client functionality to the httpd server and its modules, such as authentication and authorization. The sdbm dbm and odbc dbd providers are compiled unconditionally.

    The dbd support includes the Oracle instantclient package, MySQL, PostgreSQL and sqlite. To build these all, for example, set up the LIB to include the library path, INCLUDE to include the headers path, and PATH to include the dll bin path of all four SDK's, and set the DBD_LIST environment variable to inform the build which client driver SDKs are installed correctly, e.g.;

    set DBD_LIST=sqlite3 pgsql oracle mysql

    Similarly, the dbm support can be extended with DBM_LIST to build a Berkeley DB provider (db) and/or gdbm provider, by similarly configuring LIB, INCLUDE and PATH first to ensure the client library libs and headers are available.

    set DBM_LIST=db gdbm

    Depending on the choice of database distributions, it may be necessary to change the actual link target name (e.g. gdbm.lib vs. libgdb.lib) that are listed in the corresponding .dsp/.mak files within the directories srclib\apr-util\dbd or ...\dbm.

    See the README-win32.txt file for more hints on obtaining the various database driver SDKs.

Command-Line Build

Makefile.win is the top level Apache makefile. To compile Apache on Windows, simply use one of the following commands to build the release or debug flavor:

nmake /f Makefile.win _apacher

nmake /f Makefile.win _apached

Either command will compile Apache. The latter will disable optimization of the resulting files, making it easier to single step the code to find bugs and track down problems.

You can add your apr-util dbd and dbm provider choices with the additional make (environment) variables DBD_LIST and DBM_LIST, see the comments about [Optional] Database libraries, above. Review the initial comments in Makefile.win for additional options that can be provided when invoking the build.

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 Studio 6.0 (98) format. Visual C++ 5.0 (97) will recognize them. Visual Studio 2002 (.NET) and later users must convert Apache.dsw plus the .dsp files into an Apache.sln plus .msproj files. Be sure you reconvert the .msproj file again if its source .dsp file changes! This is really trivial, just open Apache.dsw in the VC++ 7.0 IDE once again and reconvert.

There is a flaw in the .vcproj conversion of .dsp files. devenv.exe will mis-parse the /D flag for RC flags containing long quoted /D'efines which contain spaces. The command:

perl srclib\apr\build\cvtdsp.pl -2005

will convert the /D flags for RC flags to use an alternate, parseable syntax; unfortunately this syntax isn't supported by Visual Studio 97 or its exported .mak files. These /D flags are used to pass the long description of the mod_apachemodule.so files to the shared .rc resource version-identifier build.

Visual Studio 2002 (.NET) and later users should also use the Build menu, Configuration Manager dialog to uncheck both the Debug and Release Solution modules abs, mod_deflate and mod_ssl components, as well as every component starting with apr_db*. These modules are built by invoking nmake, or the IDE directly with the BinBuild target, which builds those modules conditionally if the srclib directories openssl and/or zlib exist, and based on the setting of DBD_LIST and DBM_LIST environment variables.

Exporting command-line .mak files

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. The .mak files also support a broader range of C++ tool chain distributions, such as Visual Studio Express.

You must first build all projects in order to create all dynamic auto-generated targets, so that dependencies can be parsed correctly. Build the entire project from within the Visual Studio 6.0 (98) IDE, using the BuildAll target, then use the Project Menu Export for all makefiles (checking on "with dependencies".) Run the following command to correct absolute paths into relative 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.

Always review the generated .mak and .dep files for Platform SDK or other local, machine specific file paths. The DevStudio\Common\MSDev98\bin\ (VC6) directory contains a sysincl.dat file, which lists all exceptions. Update this file (including both forward and backslashed paths, such as both sys/time.h and sys\time.h) to ignore such newer dependencies. Including local-install paths in a distributed .mak file will cause the build to fail completely.

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 can be recognized by all Visual Studio environments.

Installation

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 provides the installation directory; it can be omitted if Apache is to be installed into \Apache22 (of the current drive).

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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Using Apache With Novell NetWare - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 module 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 source code directory.

    Set AP_WORK=D:\httpd-2.0.x

  • Set the environment variable APR_WORK to the full path of the apr source code directory. Typically \httpd\srclib\apr but the APR project can be outside of the httpd directory structure.

    Set APR_WORK=D:\apr-1.x.x

  • Set the environment variable APU_WORK to the full path of the apr-util source code directory. Typically \httpd\srclib\apr-util but the APR-UTIL project can be outside of the httpd directory structure.

    Set APU_WORK=D:\apr-util-1.x.x

  • 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 and build the prebuild utilities by running "gmake -f nwgnumakefile prebuild". This target will create the directory \httpd-2.0\nwprebuild and copy each of the utilities to this location that are necessary to complete the following build steps.
  • Copy the files \httpd-2.0\nwprebuild\GENCHARS.nlm and \httpd-2.0\nwprebuild\DFTABLES.nlm 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 prebuild

    Builds all of the prebuild utilities and copies them to the \nwprebuild 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.o or \debug.o 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.

Additional environment variable options

  • To build all of the experimental modules, set the environment variable EXPERIMENTAL:

    Set EXPERIMENTAL=1

  • To build Apache using standard BSD style sockets rather than Winsock, set the environment variable USE_STDSOCKETS:

    Set USE_STDSOCKETS=1

Building mod_ssl for the NetWare platform

By default Apache for NetWare uses the built-in module mod_nw_ssl to provide SSL services. This module simply enables the native SSL services implemented in NetWare OS to handle all encryption for a given port. Alternatively, mod_ssl can also be used in the same manner as on other platforms.

Before mod_ssl can be built for the NetWare platform, the OpenSSL libraries must be provided. This can be done through the following steps:

  • Download the recent OpenSSL 0.9.8 release source code from the OpenSSL Source page (older 0.9.7 versions need to be patched and are therefore not recommended).
  • Edit the file NetWare/set_env.bat and modify any tools and utilities paths so that they correspond to your build environment.
  • From the root of the OpenSSL source directory, run the following scripts:

    Netware\set_env netware-libc
    Netware\build netware-libc

    For performance reasons you should enable to build with ASM code. Download NASM from the SF site. Then configure OpenSSL to use ASM code:

    Netware\build netware-libc nw-nasm enable-mdc2 enable-md5

    Warning: dont use the CodeWarrior Assembler - it produces broken code!
  • Before building Apache, set the environment variable OSSLSDK to the full path to the root of the openssl source code directory, and set WITH_MOD_SSL to 1.

    Set OSSLSDK=d:\openssl-0.9.8x
    Set WITH_MOD_SSL=1

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Running a High-Performance Web Server on HPUX - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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.netperf.org/netperf/

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


The Apache EBCDIC Port - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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_imagemap | + |
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
JK (Formerly 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

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


サーバーと補助プログラム - Apache HTTP サーバ バージョン 2.2

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

サーバーと補助プログラム

このページでは Apache HTTP サーバー に含まれる全ての 実行可能プログラムについて説明します。

Index

httpd
Apache ハイパーテキスト転送プロトコルサーバー
apachectl
Apache HTTP サーバー制御インタフェース
ab
Apache HTTP サーバー・ベンチマークツール
apxs
Apache 拡張 (APache eXtenSion) ツール
configure
ソースツリーの設定
dbmmanage
Basic 認証用 ユーザ認証ファイルを DBM 形式で作成・更新するプログラム
htcacheclean
ディスクキャッシュのクリーンアップ
htdigest
Digest 認証用のユーザ認証ファイルの作成と更新
htdbm
DBM パスワードデータベースの操作
htpasswd
Basic 認証用のユーザ認証ファイルの作成と更新
httxt2dbm
RewriteMap 用に dbm ファイルを作成する
logresolve
Apache のログファイルの IP アドレスをホスト名に解決する
rotatelogs
サーバを停止せずに Apache ログファイルのローテーションを行う
suexec
Exec (CGI) のためにユーザを変更する
その他のプログラム
マニュアルページの無いサポートツール

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


httpd - Apache Hypertext Transfer Protocol Server - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 httpd
  • Stopping Apache httpd
  • 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|graceful-stop ] [ -R directory ] [ -h ] [ -l ] [ -L ] [ -S ] [ -t ] [ -v ] [ -V ] [ -X ] [ -M ] [ -T ]

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|graceful-stop
Signals httpd to start, restart, or stop. See Stopping Apache httpd 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. Also can be used to set certain less-common startup parameters including -DNO_DETACH (prevent the parent from forking) and -DFOREGROUND (prevent the parent from calling setsid() et al).
-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.
-M
Dump a list of loaded Static and Shared Modules.
-S
Show the settings as parsed from the config file (currently only shows the virtualhost settings).
-T (Available in 2.2.17 and later)
Skip document root check at startup/restart.
-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. If -D DUMP_MODULES is set, all loaded modules 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 httpd as a Windows NT service; change startup options for the Apache httpd service; and uninstall the Apache httpd service.
-n name
The name of the Apache httpd service to signal.
-w
Keep the console window open on error so that the error message can be read.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


ab - Apache HTTP server benchmarking tool - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 ]
    [ -b windowsize ]
    [ -c concurrency ]
    [ -C cookie-name=value ]
    [ -d ]
    [ -e csv-file ]
    [ -f protocol ]
    [ -g gnuplot-file ]
    [ -h ]
    [ -H custom-header ]
    [ -i ]
    [ -k ]
    [ -n requests ]
    [ -p POST-file ]
    [ -P proxy-auth-username:password ]
    [ -q ]
    [ -r ]
    [ -s ]
    [ -S ]
    [ -t timelimit ]
    [ -T content-type ]
    [ -u PUT-file ]
    [ -v verbosity]
    [ -V ]
    [ -w ]
    [ -x <table>-attributes ]
    [ -X proxy[:port] ]
    [ -y <tr>-attributes ]
    [ -z <td>-attributes ]
    [ -Z ciphersuite ]
    [http[s]://]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).
-b windowsize
Size of TCP send/receive buffer, in bytes.
-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'.
-f protocol
Specify SSL/TLS protocol (SSL2, SSL3, TLS1, or ALL).
-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 Excel. 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. Remember to also set -T.
-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.
-r
Don't exit on socket receive errors.
-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/PUT data, eg. application/x-www-form-urlencoded. Default: text/plain.
-u PUT-file
File containing data to PUT. Remember to also set -T.
-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>.
-Z ciphersuite
Specify SSL/TLS cipher suite (See openssl ciphers).

Description of output

The following list describes the values returned by ab:

Server Software
The value, if any, returned in the server HTTP header of the first successful response. This includes all characters in the header from beginning to the point a character with decimal value of 32 (most notably: a space or CR/LF) is detected.
Server Hostname
The DNS or IP address given on the command line
Server Port
The port to which ab is connecting. If no port is given on the command line, this will default to 80 for http and 443 for https.
SSL/TLS Protocol
The protocol parameters negotiated between the client and server. This will only be printed if SSL is used.
Document Path
The request URI parsed from the command line string.
Document Length
This is size in bytes of the first succesfully returning document. If the document length changes during testing, the response is considered an error.
Concurrency Level
The number of concurrent clients used during the test
Time taken for tests
This is the time taken from the moment the first socket connection is created to the moment the last response is recieved
Complete requests
The number of successful responses recieved
Failed requests
The number of requests that were considered a failure. If the number is greater than zero, another line will be printed showing the numer of requests that failed due to connecting, reading, incorrect content length, or exceptions.
Write errors
The number of errors that failed during write (broken pipe).
Non-2xx responses
The number of responses that were not in the 200 series of response codes. If all responses were 200, this field is not printed.
Keep-Alive requests
The number of connections that resulted in Keep-Alive requests
Total body sent
If configured to send data as part of the test, this is the total number of bytes sent during the tests. This field is omitted if the test did not include a body to send.
Total transferred
The total number of bytes received from the server. This number is essentially the number of bytes sent over the wire.
HTML transferred
The total number of document bytes received from the server. This number excludes bytes received in HTTP headers
Requests per second
This is the number of requests per second. This value is the result of dividing the number of requests by the total time taken
Time per request
The average time spent per request. The first value is calculated with the formula concurrency * timetaken * 1000 / done while the second value is calculated with the formula timetaken * 1000 / done
Transfer rate
The rate of transfer as calculated by the formula totalread / 1024 / timetaken

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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


apachectl - Apache HTTP Server Control Interface - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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.
graceful-stop
Gracefully stops the Apache httpd daemon. This differs from a normal stop in that currently open connections are not aborted. A side effect is that old log files will not be closed immediately. This is equivalent to apachectl -k graceful-stop.
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 option was available in earlier versions but has been removed.

startssl
To start httpd with SSL support, you should edit your configuration file to include the relevant directives and then use the normal apachectl start.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


apxs - APache eXtenSion tool - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 libtool --mode=compile command. Use this to add local compiler-specific options.
-Wl,linker-flags
This option passes linker-flags as additional flags to the libtool --mode=link 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
/path/to/libtool --mode=compile gcc ... -c mod_foo.c
/path/to/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo
$ _

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.la
/path/to/instdso.sh mod_foo.la /path/to/apache/modules
/path/to/libtool --mode=install cp mod_foo.la /path/to/apache/modules ... chmod 755 /path/to/apache/modules/mod_foo.so
[activating module `foo' in /path/to/apache/conf/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/modules.mk
Creating [FILE] foo/mod_foo.c
Creating [FILE] foo/.deps
$ _

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
/path/to/libtool --mode=compile gcc ... -c mod_foo.c
/path/to/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo
apxs -i -a -n "foo" mod_foo.la
/path/to/instdso.sh mod_foo.la /path/to/apache/modules
/path/to/libtool --mode=install cp mod_foo.la /path/to/apache/modules ... chmod 755 /path/to/apache/modules/mod_foo.so
[activating module `foo' in /path/to/apache/conf/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
$ _

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


configure - Configure the source tree - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 are 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/modules.
--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/conf.

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-basic
Disable user-based access control provided by mod_auth_basic. 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-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 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-imagemap
Disable support for server based imagemaps, which provided by mod_imagemap.
--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 this module 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-authn-anon
Enable anonymous user access provided by mod_authn_anon.
--enable-authn-dbm
mod_authn_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-authz-dbm
mod_authz_dbm provides for HTTP Basic Authorization, where the usernames and groups 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-authnz-ldap
Enable LDAP based authentication provided by mod_authnz_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 separate 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-dav-lock
Enable mod_dav_lock which provides generic DAV locking support for backend modules. This module needs at least mod_dav to function, 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 AJP13, CONNECT, FTP, HTTP and the balancer are provided by the separate modules mod_proxy_ajp, mod_proxy_connect, mod_proxy_ftp, mod_proxy_http and mod_proxy_balancer. These five modules are also automatically enabled with --enable-proxy.
--enable-proxy-ajp
Enable proxy support for AJP13 (Apache JServ Protocol 1.3) request handling, which is provided by mod_proxy_ajp. This module is an extension for the mod_proxy module, so you should also use --enable-proxy.
--enable-proxy-balancer
Enable load balancing support for the AJP13, FTP and HTTP protocols, which is provided by mod_proxy_balancer. This module is an extension for the mod_proxy module, so you should also use --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_speling.
--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[, module-type:module-file]

Add one or more third-party modules 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. If it is not found there configure is considering module-file to be an absolute file path and tries to copy the source file into the module-type subdirectory. If the subdirectory doesn't exist it will be created and populated with a standard Makefile.in.

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, mpmt_os2, prefork, 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.

Caveat: --enable-mods-shared=all does not actually build all modules. To build all modules then, one might use:

./configure \
--with-ldap \
--enable-mods-shared="all ssl ldap cache proxy authn_alias mem_cache file_cache authnz_ldap charset_lite dav_lock disk_cache"

--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 is yes.
--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 exist 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 exist 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, mod_authz_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, but 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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


dbmmanage - Manage user authentication files in DBM format - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 via mod_authn_dbm. 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_authn_dbm
  • mod_authz_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.

dbmmanage passwords.dat add rbowen foKntnEF3KSXA

adduser
Asks for a password and then adds an entry for username to filename.

dbmmanage passwords.dat adduser krietz

check
Asks for a password and then checks if username is in filename and if it's password matches the specified one.

dbmmanage passwords.dat check rbowen

delete
Deletes the username entry from filename.

dbmmanage passwords.dat delete rbowen

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.

dbmmanage passwords.dat update rbowen

view
Just displays the contents of the DBM file. If you specify a username, it displays the particular record only.

dbmmanage passwords.dat view

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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


htcacheclean - Clean up the disk cache - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Programs

htcacheclean - Clean up the disk cache

htcacheclean is used to keep the size of mod_disk_cache's storage within a certain limit. This tool can run either manually or in daemon mode. When running in daemon mode, it sleeps in the background and checks the cache directories at regular intervals for cached content to be removed. You can stop the daemon cleanly by sending it a TERM or INT signal.

See also

  • mod_disk_cache

Synopsis

htcacheclean
    [ -D ]
    [ -v ]
    [ -t ]
    [ -r ]
    [ -n ]
    -ppath
    -llimit

htcacheclean [ -n ] [ -t ] [ -i ] -dinterval -ppath -llimit

Options

-dinterval
Daemonize and repeat cache cleaning every interval minutes. This option is mutually exclusive with the -D, -v and -r options. To shutdown the daemon cleanly, just send it a SIGTERM or SIGINT.
-D
Do a dry run and don't delete anything. This option is mutually exclusive with the -d option.
-v
Be verbose and print statistics. This option is mutually exclusive with the -d option.
-r
Clean thoroughly. This assumes that the Apache web server is not running (otherwise you may get garbage in the cache). This option is mutually exclusive with the -d option and implies the -t option.
-n
Be nice. This causes slower processing in favour of other processes. htcacheclean will sleep from time to time so that (a) the disk IO will be delayed and (b) the kernel can schedule other processes in the meantime.
-t
Delete all empty directories. By default only cache files are removed, however with some configurations the large number of directories created may require attention. If your configuration requires a very large number of directories, to the point that inode or file allocation table exhaustion may become an issue, use of this option is advised.
-ppath
Specify path as the root directory of the disk cache. This should be the same value as specified with the CacheRoot directive.
-llimit
Specify limit as the total disk cache size limit. The value is expressed in bytes by default (or attaching B to the number). Attach K for Kbytes or M for MBytes.
-i
Be intelligent and run only when there was a modification of the disk cache. This option is only possible together with the -d option.

Exit Status

htcacheclean returns a zero status ("true") if all operations were successful, 1 otherwise.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


htdbm - Manipulate DBM password databases - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Programs

htdbm - Manipulate DBM password databases

htdbm is used to manipulate the DBM format files used to store usernames and password for basic authentication of HTTP users via mod_authn_dbm. See the dbmmanage documentation for more information about these DBM files.

See also

  • httpd
  • dbmmanage
  • mod_authn_dbm

Synopsis

htdbm [ -TDBTYPE ] [ -c ] [ -m | -d | -p | -s ] [ -t ] [ -v ] [ -x ] filename username

htdbm -b [ -TDBTYPE ] [ -c ] [ -m | -d | -p | -s ] [ -t ] [ -v ] filename username password

htdbm -n [ -c ] [ -m | -d | -p | -s ] [ -t ] [ -v ] username

htdbm -nb [ -c ] [ -m | -d | -p | -s ] [ -t ] [ -v ] username password

htdbm -v [ -TDBTYPE ] [ -c ] [ -m | -d | -p | -s ] [ -t ] [ -v ] filename username

htdbm -vb [ -TDBTYPE ] [ -c ] [ -m | -d | -p | -s ] [ -t ] [ -v ] filename username password

htdbm -x [ -TDBTYPE ] [ -m | -d | -p | -s ] filename username

htdbm -l [ -TDBTYPE ]

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 database. 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 htdbm 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 htdbm will support creation on all platforms, the httpd daemon will only accept plain text passwords on Windows, Netware and TPF.
-l
Print each of the usernames and comments from the database on stdout.
-t
Interpret the final parameter as a comment. When this option is specified, an additional string can be appended to the command line; this string will be stored in the "Comment" field of the database, associated with the specified username.
-v
Verify the username and password. The program will print a message indicating whether the supplied password is valid. If the password is invalid, the program exits with error code 3.
-x
Delete user. If the username exists in the specified DBM file, it will be deleted.
filename
The filename of the DBM format file. Usually without the extension .db, .pag, or .dir. If -c is given, the DBM file is created if it does not already exist, or updated 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 DBM file. Used only with the -b flag.
-TDBTYPE
Type of DBM file (SDBM, GDBM, DB, or "default").

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, GNU GDBM, and Berkeley/Sleepycat DB 2/3/4. 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 htdbm expects to see. htdbm 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.

One can usually use the file program supplied with most Unix systems to see what format a DBM file is in.

Exit Status

htdbm returns a zero status ("true") if the username and password have been successfully added or updated in the DBM File. htdbm 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 DBM password file.

Examples

htdbm /usr/local/etc/apache/.htdbm-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, htdbm will do nothing except return an error.

htdbm -c /home/doe/public_html/.htdbm 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 htdbm will display a message and return an error status.

htdbm -mb /usr/web/.htdbm-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 htdbm 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 htdbm are limited to no more than 255 characters in length. Longer passwords will be truncated to 255 characters.

The MD5 algorithm used by htdbm 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 :.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


htdigest - manage user files for digest authentication - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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. See http://tools.ietf.org/html/rfc2617#section-3.2.1 for more details.
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.

Security Considerations

This program is not safe as a setuid executable. Do not make it setuid.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


htpasswd - Manage user files for basic authentication - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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. This is the default (since version 2.2.18).
-d
Use crypt() encryption for passwords. This is not supported by the httpd server on Windows and Netware and TPF. This algorithm limits the password length to 8 characters. This algorithm is insecure by today's standards. It used to be the default algorithm until version 2.2.17.
-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. The password will be encrypted using the modified Apache MD5 algorithm. 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 -db /usr/web/.htpasswd-all jones Pwd4Steve

Encrypts the password from the command line (Pwd4Steve) using the crypt() 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.

This program is not safe as a setuid executable. Do not make it setuid.

The use of the -b option is discouraged, since when it is used the unencrypted password appears on the command line.

When using the crypt() algorithm, note that only the first 8 characters of the password are used to form the password. If the supplied password is longer, the extra characters will be silently discarded.

The SHA encryption format does not use salting: for a given password, there is only one encrypted representation. The crypt() and MD5 formats permute the representation by prepending a random salt string, to make dictionary attacks against the passwords more difficult.

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 :.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


logresolve - Resolve IP-addresses to hostnames in Apache log files - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 separated 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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


rotatelogs - Piped logging program to rotate Apache logs - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Programs

rotatelogs - Piped logging program to rotate Apache logs

rotatelogs is a simple program for use in conjunction with Apache's piped logfile feature. It supports rotation based on a time interval or maximum size of the log.

Synopsis

rotatelogs [ -l ] [ -f ] logfile rotationtime|filesizeM [ offset ]

Options

-l
Causes the use of local time rather than GMT as the base for the interval or for strftime(3) formatting with size-based rotation. Note that using -l in an environment which changes the GMT offset (such as for BST or DST) can lead to unpredictable results!
-f
Causes the logfile to be opened immediately, as soon as rotatelogs starts, instead of waiting for the first logfile entry to be read (for non-busy sites, there may be a substantial delay between when the server is started and when the first request is handled, meaning that the associated logfile does not "exist" until then, which causes problems from some automated logging tools). Available in version 2.2.9 and later.
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. For example, if a rotation time of 86400 is specified, the hour, minute, and second fields created from the strftime(3) format will all be zero, referring to the beginning of the current 24-hour period (midnight).

When using strftime(3) filename formatting, be sure the log file format has enough granularity to produce a different file name each time the logs are rotated. Otherwise rotation will overwrite the same file instead of starting a new one. For example, if logfile was /var/logs/errorlog.%Y-%m-%d with log rotation at 5 megabytes, but 5 megabytes was reached twice in the same day, the same log file name would be produced and log rotation would keep writing to the same file.

rotationtime
The time between log file rotations in seconds. The rotation occurs at the beginning of this interval. For example, if the rotation time is 3600, the log file will be rotated at the beginning of every hour; if the rotation time is 86400, the log file will be rotated every night at midnight. (If no data is logged during an interval, no file will be created.)
filesizeM
The maximum file size in megabytes followed by the letter M to specify size rather than time.
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. In most cases, -l should be used instead of specifying an offset.

Examples

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 -l /var/logs/logfile.%Y.%m.%d 86400" common

This creates the files /var/logs/logfile.yyyy.mm.dd where yyyy is the year, mm is the month, and dd is the day of the month. Logging will switch to a new file every day at midnight, local time.

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.

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 `%'

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


suexec - Switch user before executing external programs - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 the security model of suexec please refer to the suexec documentation (http://httpd.apache.org/docs/2.2/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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Other Programs - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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.

split-logfile < access_log

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Apache Miscellaneous Documentation - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2

Apache Miscellaneous Documentation

Below is a list of additional documentation pages that apply to the Apache web server development project.

Warning

The documents below have not been fully updated to take into account changes made in the 2.1 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.

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.

Relevant Standards

This document acts as a reference page for most of the relevant standards that Apache follows.

Password Encryption Formats

Discussion of the various ciphers supported by Apache for authentication purposes.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Relevant Standards - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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.php - 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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Apache モジュールの解説で使用する用語 - Apache HTTP サーバ バージョン 2.2

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

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 サーバ バージョン 2.2

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

ディレクティブの解説に使われる用語

この文書は各 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>, <Proxy> コンテナの中で、 設定セクション で説明されている制限の下で使用できることを示します。
.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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache コア機能

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | 常に使用可能な Apache HTTP サーバのコア機能
ステータス: | Core

AcceptFilter ディレクティブ

説明: | プロトコルを Listen しているソケットの最適化を設定する
構文: | AcceptFilter protocol accept_filter
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core
互換性: | 2.1.5 以降

Listen しているソケットに対して、OS が固有に持っているプロトコルについての最適化を 有効にするディレクティブです。大前提となる条件は、データが受信されるか HTTP リクエスト全体がバッファされるかするまで、カーネルがサーバプロセスに ソケットを送らないようになっている、ということです。現在サポートされているのは、 FreeBSD の Accept Filter と Linux のプリミティブな TCP_DEFER_ACCEPT のみです。

FreeBSD のデフォルト値は :

AcceptFilter http httpready
AcceptFilter https dataready

httpready Accept Filter は HTTP リクエスト全体を、 カーネルレベルでバッファリングします。リクエスト全体を受信し終わると、 その後サーバプロセスにそれを送ります。詳細については accf_http(9) を参照してください。HTTPS のリクエストは暗号化されているので accf_data(9) フィルタのみが使用されます。

Linux でのデフォルト値は :

AcceptFilter http data
AcceptFilter https data

Linux の TCP_DEFER_ACCEPT は HTTP リクエストのバッファリングを サポートしていません。none 以外の値で TCP_DEFER_ACCEPT が有効になります。詳細については Linux man ページ tcp(7) を参照してください。

引数に none を指定すると、プロトコルに対する全ての Accept Filter が無効になります。nntp といった、先にサーバにデータを 送る必要のあるプロトコルに有効です :

AcceptFilter nntp none

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-handler のようにスクリプトを扱うハンドラは 一般的にデフォルトで 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 ディレクティブ

説明: | レスポンスのコンテントタイプが text/plain あるいは text/html の場合に追加するデフォルトの charset パラメータ
構文: | AddDefaultCharset On|Off|charset
デフォルト: | AddDefaultCharset Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core

レスポンスのコンテントタイプが text/plain あるいは text/html の場合に限りますが、レスポンスに追加するメディアタイプの文字セットパラメータ (文字エンコーディングの名前) のデフォルト値を、このディレクティブで指定します。 これはレスポンス (訳注: レスポンスの HTML) 内で META 要素で指定された、どのような文字セットも無効にしますが、 最終的な挙動はユーザのクライアント側の設定で決まります。 この機能は AddDefaultCharset Off という設定で無効になります。 AddDefaultCharset On にすれば、 Apache 内部のデフォルト文字セット iso-8859-1 に設定されます。 その他 charset に指定できる値であれば、どんな値でも使えます。 指定する値は、MIME メディアタイプとして使われる IANA に登録されている文字セット名のうちの一つにすべきです。 例えば:

AddDefaultCharset utf-8

AddDefaultCharset を使うときは、全てのテキストリソースが 指定する文字エンコードになっていると分かっていて、かつ、 リソースの個々に文字セットを指定するのが大変な場合のみです。 例を挙げると、レガシーな CGI スクリプトなどの、動的に生成される コンテンツを含むリソースに文字セットパラメータを追加する場合で、 ユーザの入力データが出力に入り、クロスサイトスクリプティングが 引き起こされうる場合です。デフォルト文字セットをセットしたとしても、 ブラウザの "文字エンコードの自動選択" 機能が有効になっているユーザを 守ることにはならないので、もちろんより良い解決策は単にスクリプトを修正 (あるいは削除) することです。

参照

  • AddCharset

AddOutputFilterByType ディレクティブ

説明: | MIME-type に出力フィルタを割り当てる
構文: | AddOutputFilterByType filter[;filter...] MIME-type [MIME-type] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core
互換性: | Apache 2.0.33 以降で使用可能。ただし 2.1 以降で非推奨。

このディレクティブは応答の MIME タイプ に応じて出力フィルタを使用するようにします。 ただし下で説明される理由により、本ディレクティブは非推奨です。 同等の機能は mod_filter で利用できます。

次の例は 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 と合わせて 使うときに一番役に立ちます。

注

符号化されたスラッシュを許可することは、復号をすることを 意味しません。%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* ディレクティブなど)、 ドキュメントのメタデータを制御するディレクティブ (Header, RequestHeader, SetEnvIf, SetEnvIfNoCase, BrowserMatch, CookieExpires, CookieDomain, CookieStyle, CookieTracking, CookieName), mod_rewrite のディレクティブ RewriteEngine, RewriteOptions, RewriteBase, RewriteCond, RewriteRule) と mod_actions の Action ディレクティブの使用を許可する。
Indexes
ディレクトリインデックスを制御するためのディレクティブの使用を許可する (AddDescription, AddIcon, AddIconByEncoding, AddIconByType, DefaultIcon, DirectoryIndex, FancyIndexing, HeaderName, IndexIgnore, IndexOptions, ReadmeName など)。
Limit
ホストへのアクセス制御を行うためのディレクティブの使用を許可する (Allow, Deny, Order).
Options[=Option,...]
特定のディレクトリにおける機能を指定するためのディレクティブの使用を許可する (Options と XBitHack)。 Options で設定するオプション を、(空白を含めない) コンマ区切りのリストにして等号の後に続けることで 設定できます。

例:

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 (mod_auth_basic で実装) と Digest (mod_auth_digest で実装) です。

認証を有効にするには、AuthName と Require ディレクティブも 使う必要があります。それに加えて認証プロバイダモジュールの mod_authn_file 等と、承認モジュール mod_authz_user 等もサーバに組み込む必要があります。

参照

  • 認証、承認、アクセス制御

CGIMapExtension ディレクティブ

説明: | CGI スクリプトのインタープリタの位置を調べるための手法
構文: | CGIMapExtension cgi-path .extension
コンテキスト: | ディレクトリ, .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 及び RFC2616 において定義されている Content-MD5 ヘッダーの生成を有効にします。

MD5 は、任意長のデータの「メッセージダイジェスト」(「指紋」 と表現されることもある) を計算するアルゴリズムで、 データの変更があった場合には非常に高い信頼度でメッセージダイジェストに変更が 反映されます。

Content-MD5 ヘッダは、エンドツーエンドで エンティティボディーに含まれるメッセージの完全性チェック (Message Integrity Check - MIC)を提供します。 このヘッダを調べることで、プロキシやクライアントは、 途中経路におけるエンティティボディの予期せぬ変更などを 検出することができます。ヘッダの例:

Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==

リクエスト毎にメッセージダイジェストを計算する (値はキャッシュされません) ことから、 サーバパフォーマンスが低下することについて注意してください。

Content-MD5は、core 機能により処理された ドキュメントを送るときのみ有効であり、 SSI ドキュメントや CGI スクリプトの出力、バイトレンジを指定した 応答の場合にはこのヘッダは付与されません。

DefaultType ディレクティブ

説明: | サーバがコンテントタイプを決定できないときに 送られる MIME コンテントタイプ
構文: | DefaultType MIME-type|none
デフォルト: | DefaultType text/plain
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Core
モジュール: | core

サーバは、MIME タイプ のマッピングでは決定できない ドキュメントの送信を要求されることがあります。

サーバは、ドキュメントのコンテントタイプをクライアントに通知するべき(SHOULD)です。 もし通常の方法ではコンテントタイプが分からない場合は、 DefaultType で指定されたタイプを利用します。 例:

DefaultType image/gif

これは .gif という拡張子がファイル名に含まれていない 多くの GIF 画像が含まれているディレクトリに適しているでしょう。

サーバ側でも管理者側(たとえば proxy)でもコンテントタイプが分からない場合で、 MIME タイプの情報が誤ってついているかもしれないぐらいであればむしろ無いほうがよい、 という場合もあるでしょう。このような場合は、次のようにします。

DefaultType None

DefaultType None は httpd-2.2.7 以降で使えます。

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/dir/.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 が返されます。 directory-path が絶対パスでない場合は、 ServerRoot からの相対パスとみなされます。

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 オフロードのバグを踏んでしまいます。
  • Itanium で動いている Linux で、sendfile は 2GB 以上の ファイルを扱うことができないでしょう。
  • ネットワークマウントされた 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 の場合は、スラッシュで始まる (/) ローカルの web-path ( DocumentRoot からの相対パス ) か、クライアントが解決できる完全な 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 にあります。

ほとんどのエラーメッセージを上書きすることができますが、特定の状況下では ErrorDocument の設定にかかわらず 内蔵のメッセージが使われます。 特に、不正な形式のリクエストが検出された場合、通常のリクエスト処理は 即座に中止され、内蔵のエラーメッセージが返されます。 この処置は不正なリクエストによって引き起こされる、セキュリティ問題から 守るために必要な措置です。

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 と同じになります。

警告

WebDAV を使っていて、mod_dav_fs をストレージプロバイダとして 使っているような Directory や Location では、デフォルト値を変更しないでください。 条件つきリクエスト中で、mod_dav_fs では INode MTime Size という形式の固定フォーマットであることを前提として ETag の比較を行っています。もし ETag フォーマットを FileETag で変えてしまうと、条件つきリクエストが うまく動作しなくなるでしょう。

<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>

GprofDir ディレクティブ

説明: | Directory to write gmon.out profiling data to.
構文: | GprofDir /tmp/gprof/|/tmp/gprof/%
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

HostnameLookups ディレクティブ

説明: | クライアントの IP アドレスの DNS ルックアップを 有効にする
構文: | HostnameLookups On|Off|Double
デフォルト: | HostnameLookups Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Core
モジュール: | core

このディレクティブは、ホスト名をログ収集できるように DNS ルックアップを有効にします (さらに、CGI/SSI に REMOTE_HOST 変数として渡します)。 Doubleを指定した場合、2 重の逆引きを行ないます。 つまり、逆引きの後に、その結果に対して正引きを行ないます。正引きの 結果の IP アドレスの中にオリジナルのアドレスと一致するものがなければ なりません。("tcpwrappers" の用語では PARANOID と呼ばれています。)

mod_authz_host でホスト名によるアクセス 制御を行なう場合には、 設定の如何によらず 2 重の逆引きが実行されます。 これは、セキュリティを保つために必要です。 HostnameLookups Double を設定しない限り、 他の部分はこの 2 重逆引きの結果を使うことはできません。 例えば、HostnameLookups On と設定してある状態で、 ホスト名によるアクセス制限を行なったオブジェクトへの リクエストを受けたとすると、2 重の逆引きが成功するか否かによらず、 REMOTE_HOST には通常の逆引き結果が渡されます。

ディレクティブのデフォルトは 本当に逆引きを必要としているわけではないサイトの ネットワークトラフィックを低減させるために、Off になっています。 ルックアップによる余計な遅延がなくなるため、 エンドユーザにとっても良いでしょう。 DNS のルックアップには、かなりの時間が必要となる場合が多く、 負荷の高いサイトではこのディレクティブは Off にすべきです。 なお、/support ディレクトリに含まれ、デフォルトでは インストールディレクトリの bin サブディレクトリに インストールされる logresolve ユーティリティにより、 Apache の動作とは別に、ログに残されている IP アドレスからホスト名を ルックアップすることが可能です。

HttpProtocolOptions ディレクティブ

説明: | Modify restrictions on HTTP Request Messages
構文: | HttpProtocolOptions [Strict|Unsafe] [RegisteredMethods|LenientMethods] [Allow0.9|Require1.0]
デフォルト: | HttpProtocolOptions Strict LenientMethods Allow0.9
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core
互換性: | 2.2.32 or 2.4.24 and later

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

<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-file|module-identifier> ... </IfModule>
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Core
モジュール: | core
互換性: | モジュール識別子はバージョン 2.1 以降で使用可能。

<IfModule test>...</IfModule> セクションは、モジュールが存在するときに処理されるディレクティブを 指定するために利用します。 <IfModule> セクションに 含まれるディレクティブは、test で指定するモジュールが組み込まれているときのみ処理されます。 もし test が組み込まれていなければ、開始と終了の間のディレクティブ は無視されます。

<IfModule> セクションディレクティブに 指定する test は、 次の二つの形式のうちの一つをとります。

  • module
  • !module

前者の場合は、module と名付けられたモジュールが Apache に組み込まれていれば (コンパイル済みのものと、LoadModule を利用して 動的に読み込んだものの両方)、 開始と終了の間のディレクティブが処理されます。 後者の場合は逆で、module が組み込まれていない 場合に処理されます。

module 引数は、モジュール識別子か コンパイルをした時のモジュールのファイル名です。 例えば、rewrite_module は識別子で 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 5
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | 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 を指定します。

LimitRequestFieldSize ディレクティブは、 HTTP リクエストヘッダで許容されるサイズを増減させることができます。 サーバは、このディレクティブの値として、 一般的なクライアントからリクエストが送られた際に、そのリクエストに 付属しているどのヘッダフィールドについても、 十分足りる大きさになっていなければなりません。 一般的なリクエストヘッダのサイズといっても、その大きさは個々の クライアントの実装によって大きく異なり、 詳細なコンテントネゴシエーションをサポートするかどうかの、 ブラウザの設定にも影響されたりします。 SPNEGO 認証ヘッダでは 12392 バイトにまで及ぶことすらあります。

このディレクティブは、 管理者にクライアントからの異常なリクエストを制御できるようにし、 何らかの形のサービス拒否攻撃 (訳注:DoS) を避けるのに有効です。

例:

LimitRequestFieldSize 4094

通常はデフォルトから変更する必要はありません。

LimitRequestLine ディレクティブ

説明: | クライアントからの HTTP リクエスト行のサイズを制限する
構文: | LimitRequestLine bytes
デフォルト: | LimitRequestLine 8190
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core

このディレクティブは、HTTP リクエスト行内で許容されるバイト数 bytes を指定します。

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 にはワイルドカードを利用することができます。 ? は任意の一文字、* は任意の文字列にマッチします。 どちらのワイルドカード文字も URL-path の / にはマッチしません。

~ という文字を追加することで、正規表現を 利用することもできます。 例えば:

<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

MaxRanges ディレクティブ

説明: | Number of ranges allowed before returning the complete resource
構文: | MaxRanges default | unlimited | none | number-of-ranges
デフォルト: | MaxRanges 200
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Core
モジュール: | core
互換性: | Available in Apache HTTP Server 2.2.21 and later

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

MergeTrailers ディレクティブ

説明: | Determines whether trailers are merged into headers
構文: | MergeTrailers [on|off]
デフォルト: | MergeTrailers off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core
互換性: | 2.2.28 and later

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

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 [2001:db8::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> 内に このオプションを指定しても無視されることに 注意してください。

このオプションを省略したからといってセキュリティの強化にはなりません。 なぜなら symlink の検査はレースコンディションを引き起こす可能性があり、 そのため回避可能になるからです。

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> 内にこのオプションを 指定しても無視されます。

このオプションはセキュリティの強化にはなりません。 なぜなら symlink の検査はレースコンディションを引き起こす可能性があり、 そのため回避可能になるからです。

通常、ディレクトリに対して複数の Options が 適用可能な場合、 最も近いもの一つのみが適用され、他のものは無視されます。 複数の指定がマージされるわけではありません。(セクションのマージ方法を参照してください。) しかし、すべての 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 に なります。

Protocol ディレクティブ

説明: | Protocol for a listening socket
構文: | Protocol protocol
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core
互換性: | Available in Apache 2.1.5 and later. On Windows, from Apache 2.3.3 and later.

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

参照

  • AcceptFilter
  • Listen

RegisterHttpMethod ディレクティブ

説明: | Register non-standard HTTP methods
構文: | RegisterHttpMethod method [method [...]]
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

Require ディレクティブ

説明: | どの認証済みユーザがリソースをアクセスできるかを選択する
構文: | Require entity-name [entity-name] ...
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Core
モジュール: | core

このディレクティブは、認証されたユーザがリソースに対して アクセスできるかを制御します。 制限条件は承認モジュールで処理されます。 mod_authz_user と mod_authz_groupfile で提供されている構文には、次のようなものもあります:

Require user userid [userid] ...
指定されたユーザのみ、ディレクトリへのアクセスを許可します。
Require group group-name [group-name] ...
指定されたグループに属するユーザのみ、ディレクトリへのアクセスを許可します。
Require valid-user
全ての認証されたユーザに、ディレクトリへのアクセスを許可します。

require オプションを実装している他の承認モジュールには、 mod_authnz_ldap, mod_authz_dbm, mod_authz_owner といったものがあります。

Require は、正しく動作するためには AuthName 及び AuthType ディレクティブや、 (ユーザとグループを指定するために) AuthUserFile 及び AuthGroupFile といったディレクティブと共に 指定する必要があります。 例えば:

AuthType Basic
AuthName "Restricted Resource"
AuthUserFile /web/users
AuthGroupFile /web/groups
Require group admin

このようにして適用されたアクセス制御は、全てのメソッドに 対して行なわれます。 通常は、これが望ましい動作です。 もし、特定のメソッドに対してのみアクセスの制御を適用し、 他のメソッドは制限しない場合には、<Limit> セクション内に Require を 指定してください。

Require を Allow ディレクティブや Deny ディレクティブと 組み合わせて使った場合、これらの制約の相互作用は Satisfy ディレクティブで制御されます。

サブディレクトリで制御を解除する方法

Satisfy ディレクティブ で、保護されたディレクトリのサブディレクトリ内でアクセス制御を 無効にする例は、下のようになります。 mod_authz_host によるアクセス制御も無効化されるので、 このテクニックは注意してご活用ください。

<Directory /path/to/protected/>
Require user david
 </Directory>
<Directory /path/to/protected/unprotected>
# All access controls and authentication are disabled
# in this directory
Satisfy Any
Allow from all
 </Directory>

参照

  • 認証・承認・アクセス制御
  • Satisfy
  • mod_authz_host

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
Order allow,deny
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 オプションが指定されたときの動作に戻ります。

たとえば、レジストリの設定で .pl 拡張子が perl に関連付けられている：

HKEY_CLASSES_ROOT\.pl\Shell\ExecCGI\Command\(Default) => C:\Perl\bin\perl.exe -wT

セキュリティ

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|URL
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

ServerAdmin は、クライアントに返すさまざまな エラーメッセージ中に記述する、 問合せアドレスを設定します。与えられた引数を httpd が URL と認識しない場合は、email-address だと解釈して、 ハイパーリンクのターゲットに mailto: を付けます。 実際には、ここには電子メールアドレスを使うことが推奨されています。 多くの CGI スクリプトはそうなっていることを仮定しています。 URL を使う場合は、あなたの管理下にある別サーバを指すようにしてください。 そうでないと、エラーが起こったときに連絡をすることができなくなって しまいます。

その際、これのために専用のアドレスを設定するのが良いでしょう。 例えば、

ServerAdmin www-admin@foo.example.com

といったようにします。ユーザはいつもサーバに関する話であるということを 明記してくるわけではありませんので。

ServerAlias ディレクティブ

説明: | リクエストを名前ベースのバーチャルホストにマッチさせているときに 使用されるホストの別名
構文: | ServerAlias hostname [hostname] ...
コンテキスト: | バーチャルホスト
ステータス: | Core
モジュール: | core

ServerAlias ディレクティブは、ネームベースのバーチャルホストにおいて 使用するホストの別名を指定します。ServerAlias は適切であればワイルドカードも含めることができます。

<VirtualHost *>
ServerName server.domain.com
ServerAlias server server2.domain.com server2
# ...
</VirtualHost>

参照

  • Apache バーチャルホスト説明書

ServerName ディレクティブ

説明: | サーバが自分自身を示すときに使うホスト名とポート
構文: | ServerName [scheme://]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: ヘッダに現れる必要があるのかを指定します。

リバースプロキシやロードバランサやSSL負荷軽減装置のような、 SSLを処理するマシンの後ろでサーバを動かす場合は、 サーバが正しい自己参照 URLを確実に生成するように、 https:// スキームとクライアントが接続するポート番号を、 ServerName ディレクティブに指定してください。

自己参照 URL (例えば mod_dir モジュールによるものなど) が指定されたポートを使うか、クライアントのリクエストのポート番号を使うかを 決定する設定は UseCanonicalName ディレクティブと UseCanonicalPhysicalPort ディレクティブを参照してください。

参照

  • DNS と Apache に関する話
  • Apache バーチャルホスト説明書
  • UseCanonicalName
  • UseCanonicalPhysicalPort
  • 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/ といったサブディレクトリが 存在します。 また、他の設定ディレクティブ (例えば Include や LoadModule など) における相対パスは、 このディレクトリからの相対位置となります。

例

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 で定義された設定を無効にすることが できます。

注意:SetHandler はデフォルトのハンドラをオーバーライド しますので、通常の挙動、たとえば、スラッシュ (/) で終わる URL が リクエストされたときにディレクトリやインデックスファイルを返すよう取り扱う挙動は、 行われなくなります。

参照

  • 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>

複数のフィルタを指定するときは、データを処理する順番に セミコロンで区切る必要があります。

参照

  • フィルタ説明書

Suexec ディレクティブ

説明: | Enable or disable the suEXEC feature
構文: | Suexec On|Off
デフォルト: | On if suexec binary exists with proper owner and mode, Off otherwise
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core
互換性: | Available in Apache httpd 2.2.18 and later

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

TimeOut ディレクティブ

説明: | 各イベントについて、リクエストを失敗させるまでにサーバが 待つ時間を設定
構文: | TimeOut seconds
デフォルト: | TimeOut 300
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Core
モジュール: | core

TimeOut ディレクティブは、現在のところ 以下の三つの待ち時間についての定義を行います:

  1. GET リクエストを受け取るのにかかる総時間
  2. POST や PUTリクエストにおいて、次の TCP パケットが届くまでの待ち時間
  3. レスポンスを返す際、TCP の ACK が帰ってくるまでの時間

将来には別々の設定をすることが可能にできるよう考慮中です。 Apache 1.2 以前はタイマーは 1200 がデフォルトでしたが、 300 に下げられました。300 でもほとんどの場合は十分すぎる値です。 コード中の変な場所にまだパケットを送る際にタイマをリセットしない 場所があるかもしれないので、デフォルトをより小さい値にはしていません。

TraceEnable ディレクティブ

説明: | TRACE メソッドのリクエストに対する応答方法を決める
構文: | TraceEnable [on|off|extended]
デフォルト: | TraceEnable on
コンテキスト: | サーバ設定ファイル
ステータス: | Core
モジュール: | core
互換性: | Apache 1.3.34, 2.0.55 以降

コアサーバと mod_proxy 両方の TRACE の挙動をオーバーライドします。デフォルトの TraceEnable on は、リクエストボディを受け入れないような、RFC2616 に準拠した TRACE リクエストを受け付けます。 TraceEnable off と設定すると、コアサーバと mod_proxy は 405 (メソッド不許可) エラーをクライアントに返します。

最後に、テストや調査目的などの限定用途として、仕様に準拠しない TraceEnable extended を使って、リクエストボディを 受け付けるように挙動を変更できます。(オリジンサーバとしての) コアサーバでは、リクエストボディのサイズは 64k ( Transfer-Encoding: chunked が使われている場合は chunk ヘッダ用に +8k) に制限されます。 コアサーバは、フルヘッダと全ての chunk ヘッダをレスポンスの ボディとして返却します。 proxy サーバとしては、リクエストボディのサイズは 64k に制限されません。

UseCanonicalName ディレクティブ

説明: | サーバが自分自身の名前とポートを決定する方法を設定する
構文: | UseCanonicalName On|Off|Dns
デフォルト: | UseCanonicalName Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Core
モジュール: | core

多くの状況で Apache は自己参照 URL、すなわち 同じサーバを指す URL、を作成する必要があります。 UseCanonicalName On の場合は、ServerName ディレクティブで指定されている ホスト名とポート番号を使って、その正規名 (自己参照の名前) を生成します。 この名前は、すべての自己参照 URL で使われますし、CGI の SERVER_NAME と SERVER_PORT でも使われます。

UseCanonicalName Off の場合、 クライアントがホスト名とポートを指定したときには、 それらを元に自己参照 URL を作成します (指定がなかったときは 上の定義と同様にして正規名を解決します)。 これらの値は名前ベースの バーチャルホストを実装で使われているのと同じ値で、 同じクライアントで取得できる値になっています。 CGI 変数 SERVER_NAME と SERVER_PORT もクライアントから与えられた値から作成されます。

このような挙動が便利な例は、イントラネットのサーバで www のような短い名前でユーザがマシンに接続するときです。 ユーザの入力で短いホスト名が使われていて、URL が最後のスラッシュ無しの ディレクトリになっている http://www/splat のようなとき、 Apache はリクエストを http://www.domain.com/splat/ へリダイレクトします。 認証をするように設定していると、この場合 ユーザは 2 回認証をしなければならなくなります (www に 対して 1 回、www.domain.com に対してもう 1 回 -- 詳細は この話題の FAQ を参照してください)。 しかし UseCanonicalName が Off になっていると、 Apache は http://www/splat/ にリダイレクトします。

三つ目のオプション UseCanonicalName DNS は、 大規模な IP ベースのバーチャルホスティングで、 Host: ヘッダを提供しない古いクライアントを サポートする場合を想定しています。 このオプションでは Apache は、クライアントが接続した IP アドレスに対して DNS の逆引きを行なって、自己参照 URL を作成します。

警告

CGI が SERVER_NAME に関して何らかの前提条件を 仮定しているときには、このオプションの設定によっては動作しなく なるかもしれません。クライアントは実質的にはホスト名として 何でも望みの値を指定することができます。CGI が SERVER_NAME を使って自己参照 URL を作成することしかしない 場合は、どの設定を行なっても大丈夫なはずです。

参照

  • UseCanonicalPhysicalPort
  • ServerName
  • Listen

UseCanonicalPhysicalPort ディレクティブ

説明: | サーバの名前とポートの解決方法を設定する
構文: | UseCanonicalPhysicalPort On|Off
デフォルト: | UseCanonicalPhysicalPort Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Core
モジュール: | core

Apache は様々な状況で 自己参照 URL つまりサーバが自分自身を指し示す URL を生成する必要があります。 UseCanonicalName ディレクティブの 設定によってサーバの別名を構成するようになりますが、 その際の別名に使うポートは UseCanonicalPhysicalPort On という設定があれば、 実際のポート番号をポート番号として使う候補に入れてリクエストを 処理するようになります。UseCanonicalPhysicalPort Off という設定であれば、実際のポート番号は使用せず、設定されている情報を 全て信じてポート番号を構成するようになります。

注

実際のポート番号が使われる順序は次のようになっています :

UseCanonicalName On

  • ServerName で指定されているポート番号
  • 実際のポート番号
  • デフォルトのポート番号
UseCanonicalName Off | DNS
  • Host: ヘッダから抽出されたポート番号
  • 実際のポート番号
  • ServerName で指定されているポート番号
  • デフォルトのポート番号

UseCanonicalPhysicalPort Off で、 実際のポート番号が上の順序から取り除かれます。

参照

  • UseCanonicalName
  • 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 [2001:db8::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 コマンドにより 達成できます)。

注意点

<VirtualHost> は Apache が Listen する IP アドレスには影響を与えません。 Listen を 使って Apache が正しいアドレスを listen するように設定する必要があります。

IP ベースのバーチャルホストを使っている場合は、特別な名前 _default_ を指定することができます。その場合は そのバーチャルホストは他のバーチャルホストで明示的に挙げられていない すべての IP アドレスにマッチします。_default_ バーチャルホストが無い 場合に IP がバーチャルホストで指定されたものにマッチしないときは、 VirtualHost セクションの外のすべての定義からなる「主」サーバ設定が 使われます。(ただし、NameVirtualHost ディレクティブにマッチする すべての IP アドレスは「主」サーバ設定も _default_ バーチャルホストも 使わないことに注意してください。詳しくは ネームベースのバーチャルホスト を 参照してください。)

:port といった形式で記述することにより、 マッチさせるポートを変更可能です。 この指定をしない場合には、主サーバ設定における 一番最後に Port で指定されたポートが デフォルトとなります。 :* を指定することにより、 アドレス上の全てのポートにマッチします。(_default_ のときは これを使うことが推奨されています。)

それぞれの <VirtualHost> ブロック内で ServerName を指定します。もしこれが無いと、"main" サーバ設定の ServerName が引き継がれます。

セキュリティ

サーバーを起動した以外のユーザがログファイルが保管されるディレクトリに 書き込み可能なときになぜセキュリティが破られる可能性があるかの詳細は セキュリティに関するコツ を 参照してください。

参照

  • Apache バーチャルホスト説明書
  • DNS と Apache に関する話
  • Apache が使用するアドレスとポートの設定
  • リクエストを受けた際にこれらの異なるセクションが 組み合わされる方法については <Directory>, <Location>, <Files> セクションの動作法


mpm_common - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache MPM 共通ディレクティブ

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | 二つ以上のマルチプロセッシングモジュール (MPM) で実装されているディレクティブのコレクション
ステータス: | MPM

AcceptMutex ディレクティブ

説明: | 複数の子プロセスがネットワークソケットでリクエストを accept しようとしているときに、Apache がそれらの子プロセスを直列化するために 使う方法
構文: | AcceptMutex default|method
デフォルト: | AcceptMutex default
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | prefork, worker

AcceptMutex ディレクティブは、 ネットワークソケットのリクエストを accept しようとしている複数の子プロセスを Apache が直列化するために使う方法を設定します。 Apache 2.0 以前は、このメソッドはコンパイル時にのみ選択できました。 最適な方法は、アーキテクチャやプラットホームに大きく依存します。 詳細に関しては、性能のチューニング ドキュメントをご覧下さい。

このディレクティブが Default に設定されていれば、コンパイル時に選択されたデフォルト値が使われます。 他の使用可能なメソッドの一覧は下にあります。 全てのメソッドが全てのプラットホームで使用可能であるわけではない、 ということに注意してください。 使用可能でないメソッドが指定された場合は、 使用可能なメソッドの一覧を含んだメッセージが エラーログに出力されます。

flock
LockFile ディレクティブで定義したファイルのロックに、 flock(2) システムコールを使います。
fcntl
LockFile ディレクティブで定義したファイルのロックに、 fcntl(2) システムコールを使います。
posixsem
排他処理の実装に POSIX 互換セマフォを使用します
pthread
POSIX Threads (PThreads) 規格で実装されている POSIX 排他処理を使います。
sysvsem
排他処理の実装に SySV 形式のセマフォを使います。

コンパイル時にシステムのデフォルトに選ばれたものが何かを見たい場合は、 LogLevel を debug に設定するとよいでしょう。デフォルトの AcceptMutex が ErrorLog に書き込まれます。

警告

ほとんどのシステムにおいては、pthread オプションが 選ばれていると、子プロセスが AcceptCntl mutex を 保持しているときに異常終了した場合、サーバはリクエストへの応答を 停止してしまいます。これが発生した場合は、サーバを復旧させるためには 手動で再起動させる必要があります。

Solaris は例外で、Apache も使用している、子プロセスが mutex を 保持して異常終了した後に mutex を復旧させるための機構を提供をしています。

御使用のシステムが pthread_mutexattr_setrobust_np() 関数を 実装している場合は、pthread オプションを安全に使用できる 可能性があります。

ChrootDir ディレクティブ

説明: | Directory for apache to run chroot(8) after startup.
構文: | ChrootDir /path/to/directory
デフォルト: | none
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | event, prefork, worker
互換性: | Available in Apache 2.2.10 and later

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

CoreDumpDirectory ディレクティブ

説明: | Apache がコアダンプする前に移動を試みるディレクトリ
構文: | CoreDumpDirectory directory
デフォルト: | デフォルトの設定は説明文を読んでください
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, mpm_winnt, prefork, worker

Apache がコアダンプする前に移動を試みるディレクトリを制御します。 デフォルト値は ServerRoot ディレクトリですが、このディレクトリはサーバの実行されているユーザ権限で 書き込み可能であるべきではないので、通常はコアダンプは書き込まれません。 デバッグのためにコアダンプが必要であれば、 このディレクティブを使って他の位置にコアダンプを書き出すようにできます。

Linux でのコアダンプ

Apache が root として起動されて、別のユーザの権限に以降した場合は Linux のカーネルはディレクトリがプロセスの権限で書き込み可能な場合でさえも コアダンプを無効にします。Apache (2.0.46 以降) は Linux 2.4 以降ではコアダンプを行なうように再指定しますが、それは CoreDumpDirectory を明示的に設定したときに 限ります。

EnableExceptionHook ディレクティブ

説明: | クラッシュの後に例外ハンドラを実行するフックを有効にする
構文: | EnableExceptionHook On|Off
デフォルト: | EnableExceptionHook Off
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | prefork, worker
互換性: | 2.0.49 以降

安全上の理由から、--enable-exception-hook configure オプションを有効にした場合にのみ、このディレクティブを利用できます。 外部モジュールをプラグインして、子がクラッシュした後に何か実行できるような フックを有効にします。

このような外部モジュールは、既に二つ存在していて、 mod_whatkilledus と mod_backtrace がこのフックを活用します。これらの詳細については Jeff Trawick さんの EnableExceptionHook site を参照してください。

GracefulShutdownTimeout ディレクティブ

説明: | 穏やかな停止をかけた後、終了するまで待つ時間
構文: | GracefulShutDownTimeout seconds
デフォルト: | GracefulShutDownTimeout 0
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | prefork, worker, event
互換性: | 2.2 以降

GracefulShutdownTimeout には サーバーが "graceful-stop" シグナルを受け取ってから現在の リクエストの処理を最大で何秒間続けるかを指定します。

この値をゼロに設定すると、処理中として残っているリクエストが 全て完了するまでサーバーは終了しません。

Group ディレクティブ

説明: | リクエストに応答する際に所属するグループ
構文: | Group unix-group
デフォルト: | Group #-1
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, mpmt_os2, prefork, worker
互換性: | Apache 2.0 以降で、グローバル設定でのみ有効です。

Group ディレクティブで、 リクエストに応答する際に所属しておくグループを設定します。 このディレクティブを使用するためには、 サーバは最初に root 権限で起動されている必要があります。 非 root ユーザでサーバを起動した場合は、指定したグループに変化できずに、 結果的に起動したユーザの属するグループで実行されることになります。 unix-group は次のうちのいずれかです:

グループ名
グループを名前で参照します
# に続いてグループ番号
グループを番号で参照します。

例

Group www-group

サーバを実行するために特定の新しいグループを設定することを お薦めします。nobody を使用する管理者もいますが、 可能であったり望ましい訳では必ずしもありません。

セキュリティ

正確にどんなことをやっているのか、その危険性を知らないで、 Group (や User) を root に 設定しないでください。

特記事項: このディレクティブを <VirtualHost> で使用することはサポートされなくなりました。Apache 2.0 で suexec を設定したい場合は、 SuexecUserGroup を使用してください。

注意

Group ディレクティブは beos と mpmt_os2 MPM にも存在しますが、実質的に無効で、互換性のためだけに存在します。

Listen ディレクティブ

説明: | サーバが listen するIP アドレスとポート番号
構文: | Listen [IP-address:]portnumber [protocol]
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, mpm_netware, mpm_winnt, mpmt_os2, prefork, worker, event
互換性: | Apache 2.0 から必須ディレクティブ。protocol 引数は 2.1.5 で追加。

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 [2001:db8::a00:20ff:fea7:ccea]:80

protocol オプション引数は通常の設定では必要ありません。 無指定の場合、443 番ポートには https が、他のポートには http がデフォルト値として使用されます。 protocol 指定は、どのモジュールがリクエストを処理するかを決定し、 AcceptFilter によるプロトコル特有の最適化を行うようにします。

非標準なポートで運用している際にのみ protocol 指定が必要になります。 たとえば https なサイトを 8443 番ポートで運用している場合 :

Listen 192.170.2.1:8443 https

エラー条件

同一 IP アドレスとポートの組に、複数の Listen ディレクティブを指定してしまうと、Address already in use というエラーメッセージを受けることになります。

参照

  • DNS の問題
  • Apache が使用するアドレスとポートの設定

ListenBackLog ディレクティブ

説明: | 保留状態のコネクションのキューの最大長
構文: | ListenBacklog backlog
デフォルト: | ListenBacklog 511
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, mpm_netware, mpm_winnt, mpmt_os2, prefork, worker

保留状態のコネクションのキューの最大長です。 一般的には調整する必要はありませんし、調整は望ましくありません。 しかし、TCP SYN フラッドアタックの状況下におかれる場合に、 増やした方が望ましいシステムもあります。 listen(2) システムコールのバックログパラメータを ご覧下さい。

この値は OS により、小さな数に抑えられます。 値は OS 毎に異なっています。また多くの OS では、 バックログとして指定されている値ちょうどまで使っているわけではなく、 設定されている値に基づいて (通常は設定値よりも大きな値を) 使っていることに注意してください。

LockFile ディレクティブ

説明: | 受付を直列化するためのロックファイルの位置
構文: | LockFile filename
デフォルト: | LockFile logs/accept.lock
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | prefork, worker

AcceptMutex が fcntl や flock に設定されて使用されている場合に、使用されるロックファイルへのパスを LockFile ディレクティブで設定します。 このディレクティブは通常はそのままにしておきます。 主に logs ディレクトリが NFS でマウントされている場合などに値を変えます。 なぜならロックファイルはローカルディスクに 保存されなければならないからです。 メインサーバプロセスの PID がファイル名に自動的に付加されます。

セキュリティ

/var/tmp といった、誰でも書き込めるディレクトリにファイルを 置かない方がよいです。なぜなら、サーバが起動時に作成する ロックファイルの作成自体を妨害することによって、 誰でもサービス拒否アタックを引き起こすことができるからです。

参照

  • AcceptMutex

MaxClients ディレクティブ

説明: | リクエストに応答するために作成される 子プロセスの最大個数
構文: | MaxClients number
デフォルト: | 詳細は使用法をご覧下さい。
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, prefork, worker

MaxClients ディレクティブは、 応答することのできる同時リクエスト数を設定します。 MaxClients 制限数を越えるコネクションは通常、 ListenBacklog ディレクティブで設定した数までキューに入ります。 他のリクエストの最後まで達して子プロセスが空くと、 次のコネクションに応答します。

スレッドを用いないサーバ (すなわち prefork) では、MaxClients は、リクエストに応答するために起動される 子プロセスの最大数となります。 デフォルト値は 256 で、これを増加させたい場合は、 ServerLimit の値も増加させる必要があります。

スレッドを用いるサーバや、ハイブリッドサーバ (すなわち beos worker) では、MaxClients は、クライアントに応答できるスレッドの総数を制限します。 beos でのデフォルト値は 50 です。 ハイブリッド MPM でのデフォルト値は 16 ServerLimit の 25 倍 (ThreadsPerChild) です。 MaxClients を 16 プロセス以上必要な値まで増加させたい場合は、 ServerLimit も増加させる必要があります。

MaxMemFree ディレクティブ

説明: | free() が呼ばれない限り、 主メモリアロケータが保持し続けられるメモリの最大量
構文: | MaxMemFree KBytes
デフォルト: | MaxMemFree 0
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, mpm_netware, prefork, worker, mpm_winnt

MaxMemFree ディレクティブは free() が呼ばれない限り、 主アロケータが保持できる空のメモリの最大値をキロバイト単位で設定します。 設定されていないか、零に設定されているときは、無制限になります。

MaxRequestsPerChild ディレクティブ

説明: | 個々の子サーバが稼働中に扱うリクエスト数の上限
構文: | MaxRequestsPerChild number
デフォルト: | MaxRequestsPerChild 10000
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | mpm_netware, mpm_winnt, mpmt_os2, prefork, worker

MaxRequestsPerChild ディレクティブは、 個々の子サーバプロセスが扱うことのできるリクエストの制限数を 設定します。MaxRequestsPerChild 個のリクエストの後に、子プロセスは終了します。 MaxRequestsPerChild が 0 に設定されている場合は、プロセスは期限切れにより終了することはありません。

その他のデフォルト値

mpm_netware と mpm_winnt でのデフォルト値は 0 です。

MaxRequestsPerChild を非ゼロに制限することには、二つの利点があります:

  • (偶発的な) メモリーリークが起こった場合に プロセスが消費するメモリの総量を制限できる
  • プロセスに有限のライフタイムを設定することで、 サーバ負荷が下がった時にプロセス数を少なくすることができる

注

KeepAlive リクエストの場合は、 一つ目のリクエストだけがこの制限に該当します。 実効的には、一つの子プロセスあたりのコネクション数を 制限するように挙動が変化します。

MaxSpareThreads ディレクティブ

説明: | アイドルスレッドの最大数
構文: | MaxSpareThreads number
デフォルト: | 詳細は使用法をご覧下さい。
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, mpm_netware, mpmt_os2, worker

アイドルなスレッドの最大数です。異なる MPM ではそれぞれ、 このディレクティブは異なる取り扱われ方をされます。

worker では、 デフォルトは MaxSpareThreads 250 です。 この MPM はアイドルスレッド数をサーバ全体で監視します。 サーバでアイドルスレッド数が多すぎる場合は、 この数字よりも少ない数になるまで子プロセスを終了します。

mpm_netware では、 デフォルトは MaxSpareThreads 100 です。 この MPM はシングルプロセスで実行されますので、 スペアスレッド数もサーバ全体で勘定します。

beos と mpmt_os2 は mpm_netware と似た挙動をします。 beos でのデフォルト値は MaxSpareThreads 50 です。mpmt_os2 でのデフォルト値は 10 です。

制限事項

MaxSpareThreads の取る値には制限があります。 Apache は次の規則に従って自動的に補正します。

  • mpm_netware は MinSpareThreads よりも大きい必要があります。
  • worker では、 MinSpareThreads と ThreadsPerChild で決まる総和と等しいか大きい必要があります。

参照

  • MinSpareThreads
  • StartServers

MinSpareThreads ディレクティブ

説明: | リクエストに応答することのできる アイドルスレッド数の最小数
構文: | MinSpareThreads number
デフォルト: | 詳細は使用方法をご覧下さい。
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, mpm_netware, mpmt_os2, worker

リクエストに応答するスレッド数の最小値です。 異なる MPM ではそれぞれ、 このディレクティブは異なる取り扱われ方をします。

worker では、 デフォルトは MinSpareThreads 75 で、 アイドルスレッド数をサーバ全体で監視します。 もしサーバに十分な数のアイドルスレッドがなければ、 アイドルスレッド数がこの数よりも大きくなるまで 新しい子プロセスが生成されます。

mpm_netware では、 デフォルトは MinSpareThreads 10 で、 シングルプロセス MPM ですので、サーバ全体で管理されます。

beos と mpmt_os2 は、 mpm_netwareによく似ています。 beos でのデフォルトは MinSpareThreads 1 です。mpmt_os2 でのデフォルトは 5 です。

参照

  • MaxSpareThreads
  • StartServers

PidFile ディレクティブ

説明: | デーモンのプロセス ID をサーバが記録するためのファイル
構文: | PidFile filename
デフォルト: | PidFile logs/httpd.pid
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, mpm_winnt, mpmt_os2, prefork, worker

PidFile ディレクティブで、 デーモンのプロセス ID をサーバが記録するファイルを設定します。 ファイル名が絶対パスでない場合は、 ServerRoot からの相対的なものとして扱われます。

例

PidFile /var/run/apache.pid

サーバが ErrorLog や TransferLog を閉じて開き直したり、設定ファイルを 再読込したりさせるために、サーバにシグナルを送ることができると 便利なことがあります。 これは SIGHUP (kill -1) シグナルを PidFile に書かれているプロセス ID に送ることでできます。

PidFile には、ログファイルの設置位置や セキュリティ と全く同じ注意点があります。

注意

Apache 2 では、 apachectl スクリプトのみを使用してサーバの (再) 起動や停止を 行なうことを推奨しています。

ReceiveBufferSize ディレクティブ

説明: | TCP 受信バッファサイズ
構文: | ReceiveBufferSize bytes
デフォルト: | ReceiveBufferSize 0
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, mpm_netware, mpm_winnt, mpmt_os2, prefork, worker

サーバは TCP 受信バッファサイズを指定されたバイト数に設定します。

0にした場合、OS のデフォルト値が使用されます。

ScoreBoardFile ディレクティブ

説明: | 子プロセスと連携するためのデータを保存する ファイルの位置
構文: | ScoreBoardFile file-path
デフォルト: | ScoreBoardFile logs/apache_status
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, mpm_winnt, prefork, worker

Apache は親プロセスと子プロセス間の通信にスコアボードを用います。 この通信機能にファイルを必要とするアーキテクチャもあります。 ファイルが指定されていなければ、Apache はまずメモリ上 (匿名共有メモリ) にスコアボードを作ろうとし、それが失敗すると ディスク上にファイル (ファイルベースの共有メモリ) を作ろうとします。 このディレクティブを指定すると、Apache は必ずディスクにファイルを生成します。

例

ScoreBoardFile /var/run/apache_status

ファイルベースの共有メモリは、サードパーティー製のアプリケーションで スコアボードに直接アクセスする必要がある場合に役に立ちます。

ScoreBoardFile を使う場合、 RAM ディスク上に置くとスピードが向上するでしょう。 しかし、ログファイルの設置位置や セキュリティ と同様の注意点があるので、注意してください。

参照

  • Apache の停止と再起動

SendBufferSize ディレクティブ

説明: | TCP バッファサイズ
構文: | SendBufferSize bytes
デフォルト: | SendBufferSize 0
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, mpm_netware, mpm_winnt, mpmt_os2, prefork, worker

サーバは TCP 送信バッファサイズを指定されたバイト数に設定します。 高速で高レイテンシな環境で (例 100ms 程度、大陸横断高速通信路など) 古い一般的な OS のデフォルト値を増やすのに非常に便利です。

0にした場合、OS のデフォルト値が使用されます。

ServerLimit ディレクティブ

説明: | 設定可能なサーバプロセス数の上限
構文: | ServerLimit number
デフォルト: | 詳細は使用法を参照
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | prefork, worker

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 とくらべて、必要となるサーバプロセス数以上に大きな値を 設定することは避けてください。

注意

ServerLimit 20000 という制限付きでコンパイルされています (prefork MPM では 200000) 。 これはスペルミスによって誤って酷い状況になるのを、 回避するための処置です。

参照

  • Apache の停止と再起動

StartServers ディレクティブ

説明: | 起動時に生成される子サーバプロセスの数
構文: | StartServers number
デフォルト: | 詳細は使用方法を参照
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | mpmt_os2, prefork, worker

StartServers ディレクティブは、 起動時に生成される子サーバプロセスの数を設定します。 プロセス数は負荷に応じて動的に制御されますので、 通常はこの値を調整する理由はあまりないでしょう。

デフォルト値は MPM ごとに異なります。 worker は StartServers 3 です。 prefork は 5 で、 mpmt_os2 は 2 です。

StartThreads ディレクティブ

説明: | 起動時に生成されるスレッドの数
構文: | StartThreads number
デフォルト: | 詳細は使用方法を参照
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | beos, mpm_netware

起動時に生成されるスレッドの数です。 スレッド数は負荷に応じて動的に制御されますので、 通常はこの値を調整する理由はあまりないでしょう。

mpm_netware でのデフォルトは StartThreads 50 で、 この場合プロセスは一つしかないので、 起動時にリクエストに応答するスレッドの総数となります。

beos でのデフォルトは StartThreads 10 です。 また、起動時に生成されるスレッドの総数にも反映されます。

ThreadLimit ディレクティブ

説明: | 設定可能な子プロセス毎のスレッド数の上限を 設定します
構文: | ThreadLimit number
デフォルト: | 詳細は使用方法を参照
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | mpm_winnt, worker
互換性: | Apache 2.0.41 とそれ以降の mpm_winnt で利用可能

このディレクティブは Apache プロセス稼働中における ThreadsPerChild に設定可能な上限値を設定します。再起動時にこのディレクティブの値を 変更しても無視されますが、 ThreadsPerChild は再起動中に、このディレクティブで指定された上限値まで 変更することができます。

このディレクティブを使用する際は特に注意してください。 ThreadLimit が ThreadsPerChild よりもずっと大きな値に設定された場合は、 余計な未使用共有メモリが割り当てられてしまいます。 ThreadLimit が ThreadsPerChild の両方がシステムの扱える範囲を超えている場合は、 Apache は起動しないか、起動したとしても不安定になるでしょう。 このディレクティブの値は今使用している Apache の ThreadsPerChild の予想上限値を 超えた値には設定しないでください。

ThreadLimit のデフォルト値は mpm_winnt のときは 1920 で、 他の場合は 64 です。

注意

ThreadLimit 20000 (mpm_winnt の場合は ThreadLimit 15000 ) という制限付きでコンパイルされています。 これはスペルミスによって誤って酷い状況になるのを、 回避するための処置です。

ThreadsPerChild ディレクティブ

説明: | 子プロセスそれぞれに生成されるスレッド数
構文: | ThreadsPerChild number
デフォルト: | 詳細は使用方法を参照
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | mpm_winnt, worker

このディレクティブは、それぞれの子プロセスで生成される スレッド数を設定します。 子プロセスは開始時にこれらのスレッドを生成して、 その後は生成しません。mpm_winnt のような、 子プロセスが一つしかないような MPM を利用しているのであれば、 この値はサーバの負荷全体を十分取り扱える程度に、 大きくなければなりません。worker のような、 子プロセスが複数あるような MPM を利用しているのであれば、 サーバの通常負荷を十分扱える程度に、 スレッド総数が多くなければなりません。

mpm_winntでの ThreadsPerChild のデフォルト値は 64 で、他の場合は 25 です。

ThreadStackSize ディレクティブ

説明: | クライアントのコネクションを受け持つスレッドが使用する スタックのバイト数
構文: | ThreadStackSize size
デフォルト: | NetWare では 65536。他の OS では違った値
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | mpm_netware, mpm_winnt, worker
互換性: | 2.1 以降

クライアントコネクションを受け持ち、コネクション処理に必要なモジュールの 呼び出しを行なっているスレッドの、(自動変数用の) スタックサイズは ThreadStackSize ディレクティブで指定します。 大抵の場合 OS の指定しているスタックサイズのデフォルト値は 適切なものですが、調整が必要になる場合もあります:

  • スレッドスタックサイズのデフォルト値が比較的小さく設定されている プラットホーム (例えば HP-UX) では、自動変数用の領域で大きな容量を 使用するサードパーティ製モジュールのために Apache がクラッシュする 場合もあります。そのモジュールは他のプラットホームでは スタックサイズが大きいために、快調に動作するかもしれません。 このタイプのクラッシュは、ThreadStackSize で OS のデフォルト値より大きな値を指定することで解決します。 サードパーティ製モジュールでこの処置が必要であると記載されている 場合か、Apache の出力するメッセージでスレッドスタックサイズが 小さすぎると指摘されている場合にのみ、この調整をしてください。
  • デフォルトスレッドスタックサイズが、Web サーバ用途に必要な量よりも 明らかに大きすぎる場合、ThreadStackSize を OS のデフォルト値よりも小さな値にすることで、子プロセスあたりの スレッド数をより多く持たせられるようになります。 このタイプの調整は、テスト環境でウェブサーバを完全に テストできる場合に限って行なうべきです。 まれに多数のスタックが要求されるリクエストを受けることがあるかも しれないからです。 Web サーバの設定を変更すると、現在の ThreadStackSize の設定が取り消される場合があります。

User ディレクティブ

説明: | リクエストに応答する際に用いるユーザ ID
構文: | User unix-userid
デフォルト: | User #-1
コンテキスト: | サーバ設定ファイル
ステータス: | MPM
モジュール: | prefork, worker
互換性: | Apache 2.0 以降で、グローバル設定でのみ有効です。

User ディレクティブは サーバがリクエストに応答する際に用いるユーザ ID を設定します。 このディレクティブを使用するためには、スタンドアロン型の サーバは最初に root 権限で起動されている必要があります。 非 root ユーザでサーバを起動した場合は、 権限の低いユーザへと変わることができず、 結局元のユーザのプロセスとして実行され続けます。 root で起動した場合に親プロセスが root として実行されているのは正常な動作です。 Unix-userid は次のどれかです。

ユーザ名
ユーザを名前で参照します。
# に続いてユーザ番号
ユーザを番号で参照します。

このユーザは、外部に見せるように意図していないファイルに、 アクセス可能になってしまうような権限を持つべきではないですし、 同様に HTTP リクエストに対して応答するように意図していない 実行コードを、実行できるような権限を持つべきではないです。 サーバを実行するために特定の新しいユーザとグループを 設定することをお薦めいたします。 nobody ユーザを使用する管理者もいますが、 これが常に望ましいわけではありません。 なぜなら nobody ユーザは、システムで 他の役割を担っているかも知れないからです。

セキュリティ

正確にどんなことをやっているのか、その危険性を知らないで、 User (や Group) を root に 設定しないでください。

特記事項: このディレクティブを <VirtualHost> で使用することはサポートされなくなりました。 suexec 向けにサーバを設定するのであれば、 SuexecUserGroup を使用してください。

注意

User ディレクティブは beos と mpmt_os2 MPM にも存在しますが、実質的に無効で、互換性のためだけに存在します。


beos - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache MPM beos

Description: | This Multi-Processing Module is optimized for BeOS.
Status: | MPM
Module Identifier: | mpm_beos_module
Source File: | 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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


event - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache MPM event

Description: | An experimental variant of the standard worker MPM
Status: | MPM
Module Identifier: | mpm_event_module
Source File: | event.c

Summary

Warning

This MPM is experimental, so it may or may not work as expected.

The event Multi-Processing Module (MPM) is designed to allow more requests to be served simultaneously by passing off some processing work to supporting threads, freeing up the main threads to work on new requests. It is based on the worker MPM, which implements a hybrid multi-process multi-threaded server. Run-time configuration directives are identical to those provided by worker.

To use the event MPM, add --with-mpm=event to the configure script's arguments when building the httpd.

See also

  • The worker MPM

How it Works

This MPM tries to fix the 'keep alive problem' in HTTP. After a client completes the first request, the client can keep the connection open, and send further requests using the same socket. This can save significant overhead in creating TCP connections. However, Apache traditionally keeps an entire child process/thread waiting for data from the client, which brings its own disadvantages. To solve this problem, this MPM uses a dedicated thread to handle both the Listening sockets, and all sockets that are in a Keep Alive state.

The MPM assumes that the underlying apr_pollset implementation is reasonably threadsafe. This enables the MPM to avoid excessive high level locking, or having to wake up the listener thread in order to send it a keep-alive socket. This is currently only compatible with KQueue and EPoll.

Requirements

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.

This MPM does not perform well on older platforms which lack good threading, but the requirement for EPoll or KQueue makes this moot.

  • To use this MPM on FreeBSD, FreeBSD 5.3 or higher is recommended. However, it is possible to run this MPM on FreeBSD 5.2.1, if you use libkse (see man libmap.conf).
  • For NetBSD, at least version 2.0 is recommended.
  • For Linux, a 2.6 kernel is recommended. It is also necessary to ensure that your version of glibc has been compiled with support for EPoll.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mpm_netware - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache MPM netware

Description: | Multi-Processing Module implementing an exclusively threaded web server optimized for Novell NetWare
Status: | MPM
Module Identifier: | mpm_netware_module
Source File: | 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

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mpmt_os2 - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache MPM os2

Description: | Hybrid multi-process, multi-threaded MPM for OS/2
Status: | MPM
Module Identifier: | mpm_mpmt_os2_module
Source File: | 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

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


prefork - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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


mpm_winnt - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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_actions - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_actions

説明: | メディアタイプやリクエストメソッドに応じて CGI スクリプトを実行する機能を提供
ステータス: | Base
モジュール識別子: | actions_module
ソースファイル: | mod_actions.c

概要

このモジュールには二つのディレクティブがあります。Action ディレクティブは特定の MIME タイプ のファイルをリクエストされた場合に CGI スクリプトが実行されるようにします。Script ディレクティブはリクエストで特定のメソッドが使用されたときに CGI スクリプトが実行されるようにします。 これはファイルを処理するスクリプトの実行をずっと簡単にします。

参照

  • mod_cgi
  • CGI による動的コンテンツ
  • Apache のハンドラの使用

Action ディレクティブ

説明: | 特定のハンドラやコンテントタイプに対して CGI を実行するように 設定
構文: | Action action-type cgi-script [virtual]
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_actions
互換性: | virtual 修飾子とハンドラ渡しは Apache 2.1 で導入されました

このディレクティブは action-type がリクエストされたときに cgi-script が実行されるという動作を追加します。cgi-script は ScriptAlias や AddHandler によって CGI スクリプトに設定されたリソースへの URL-path です。 Action-type には handler か MIME コンテントタイプを指定できます。リクエストされたドキュメントの URL とファイルのパスは標準 CGI 環境変数 PATH_INFO と PATH_TRANSLATED を使って伝えられます。 特定のリクエストに対して使用されるハンドラへは、 REDIRECT_HANDLER 変数を使って渡せます。

例

# Requests for files of a particular MIME content 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 で処理されます。

オプションの virtual 修飾子を使用すると、 リクエストされたファイルが実際に存在するかどうかを検査しないようにできます。 これは例えば、Action ディレクティブをバーチャルな Location に使用したい、といった場合に便利です。

例

<Location /news>
SetHandler news-handler
Action news-handler /cgi-bin/news.cgi virtual
 </Location>

参照

  • 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

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


mod_alias - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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 を返します。完全なパスセグメントが 一致した時にのみ働きますので、上の例は http://myserver/imagefoo.gif に対するリクエストにはマッチしません。正規表現を使ったより複雑な マッチングに関しては AliasMatch ディレクティブをご覧ください。

もし 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-path (% が復号された) パスは、 スラッシュで始まるものです。相対パスは使用できません。 新しい URL は絶対 URL 、つまりスキームとホスト名で 始まるものであるべきですが、URL-path の、スラッシュで始まるものも 使用可能です。その場合は、現在のスキームとホスト名が追加されたことに なります。

URL-Path で始まるどんなリクエストも、ターゲットの URL へとリダイレクトが返されます。URL-Path にマッチした path 情報は、ターゲット URL の後ろに追加された 形で引き継がれます。

例

Redirect /service http://foo2.example.com/service

クライアントは http://example.com/service/foo.txt へのリクエストを行なうと、代わりに http://foo2.example.com/service/foo.txt をアクセスするように告げられます。 パスセグメントが完全に一致したもののみがマッチしますので、 上記の例は http://example.com/servicefoo.txt にはマッチしません。 正規表現を使ったより複雑なマッチングについては、 RedirectMatch ディレクティブをご覧ください。

注意

設定ファイル中の順番に関わらず、 Redirect 系のディレクティブは Alias ディレクティブと ScriptAlias ディレクティブよりも優先されます。

もし 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 permanent とまったく同じです。

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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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 ヘッダはファイルそれ自体から mod_cgi と同じ規則で読み取られますので、asis ファイルには適切なヘッダが 含まれていなければなりませんし、CGI での Status: ヘッダを 書いて 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_basic - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_auth_basic

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | 基本認証
ステータス: | Base
モジュール識別子: | auth_basic_module
ソースファイル: | mod_auth_basic.c
互換性: | Apache 2.1 以降

概要

与えられたプロバイダ (訳注: 認証での照会を行う問い合わせ先) でユーザを検索し、HTTP 基本認証でアクセス制限できるようになります。 HTTP ダイジェスト認証については mod_auth_digest で提供されます。

参照

  • AuthName
  • AuthType

AuthBasicAuthoritative ディレクティブ

説明: | 認証と承認を、より低いレベルのモジュールに移行させるかを 設定します。
構文: | AuthBasicAuthoritative On|Off
デフォルト: | AuthBasicAuthoritative On
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Base
モジュール: | mod_auth_basic

AuthBasicAuthoritative ディレクティブで明示的に Offに設定すると、 与えられた認証ユーザ ID に対してユーザ ID がない またはルールがない場合に、 認証と承認の両方のプロセスが、 より低いレベルのモジュール (modules.c ファイルで定義) に移行するようにできます。 ユーザ ID がある、かつまたは、ルールが指定されている場合は、 通常のパスワードとアクセスチェックが適用されて、 認証に失敗すると "Authentication Required" 応答が返されます。

ですから、二つ以上のモジュールのデータベースで同一の ユーザ ID が現われたり、 または、正しい Require ディレクティブが二つ以上のモジュールで現われたりした場合は、 一つ目のモジュールが認定を行って、AuthAuthoritative 設定に関わらず、アクセスは移行しません。

デフォルトでは、制御は移行しません。そして、未知のユーザ ID や ルールがあっても "Authentication Required" 応答が返されます。 ですから、このディレクティブを設定しないことでシステムの安全を維持できて、また、 NCSA 準拠の挙動を強制できます。

AuthBasicProvider ディレクティブ

説明: | この位置に対する認証プロバイダを設定します。
構文: | AuthBasicProvider On|Off|provider-name [provider-name] ...
デフォルト: | AuthBasicProvider On
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Base
モジュール: | mod_auth_basic

AuthBasicProvider ディレクティブで、 この位置に対するユーザ認証に用いられる認証プロバイダを設定します。 On に設定するとデフォルトの認証プロバイダ (file) が使用されます。file プロバイダは mod_authn_file モジュールで実装されていますので、 このモジュールがサーバに入っていることを確認してください。

Example

<Location /secure>
AuthBasicProvider dbm
AuthDBMType SDBM
AuthDBMUserFile /www/etc/dbmpasswd
Require valid-user
 </Location>

認証プロバイダについては mod_authn_dbm と mod_authn_file をご覧下さい。

Off はプロバイダリストをクリアして、デフォルトの 状態に戻します。


mod_auth_digest - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_auth_digest

Description: | User authentication using MD5 Digest Authentication.
Status: | Extension
Module Identifier: | auth_digest_module
Source File: | mod_auth_digest.c

Summary

This module implements HTTP Digest Authentication (RFC2617), and provides an alternative to mod_auth_basic where the password is not transmitted as cleartext. However, this does not lead to a significant security advantage over basic authentication. On the other hand, the password storage on the server is much less secure with digest authentication than with basic authentication. Therefore, using basic auth and encrypting the whole connection using mod_ssl is a much better alternative.

See also

  • AuthName
  • AuthType
  • Require
  • Satisfy
  • Authentication howto

Using Digest Authentication

Using MD5 Digest authentication is very simple. Simply set up authentication normally, using AuthType Digest and AuthDigestProvider instead of the normal AuthType Basic and AuthBasicProvider. 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/

AuthDigestProvider file
AuthUserFile /web/auth/.digest_pw
Require valid-user
 </Location>

Note

Digest authentication was intended to be more secure than basic authentication, but no longer fulfills that design goal. A man-in-the-middle attacker can trivially force the browser to downgrade to basic authentication. And even a passive eavesdropper can brute-force the password using today's graphics hardware, because the hashing algorithm used by digest authentication is too fast. Another problem is that the storage of the passwords on the server is insecure. The contents of a stolen htdigest file can be used directly for digest authentication. Therefore using mod_ssl to encrypt the whole connection is strongly recommended.

AuthDigestAlgorithm Directive

Description: | Selects the algorithm used to calculate the challenge and response hashes in digest authentication
Syntax: | AuthDigestAlgorithm MD5|MD5-sess
Default: | AuthDigestAlgorithm MD5
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
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: | Extension
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; 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. including 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.

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: | Extension
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: | Extension
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: | Extension
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.

AuthDigestProvider Directive

Description: | Sets the authentication provider(s) for this location
Syntax: | AuthDigestProvider provider-name [provider-name] ...
Default: | AuthDigestProvider file
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_digest

The AuthDigestProvider directive sets which provider is used to authenticate the users for this location. The default file provider is implemented by the mod_authn_file module. Make sure that the chosen provider module is present in the server.

See mod_authn_dbm, mod_authn_file, and mod_authn_dbd for providers.

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: | Extension
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: | Extension
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 necessary 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

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_authn_alias - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_authn_alias

Description: | Provides the ability to create extended authentication providers based on actual providers
Status: | Extension
Module Identifier: | authn_alias_module
Source File: | mod_authn_alias.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module allows extended authentication providers to be created within the configuration file and assigned an alias name. The alias providers can then be referenced through the directives AuthBasicProvider or AuthDigestProvider in the same way as a base authentication provider. Besides the ability to create and alias an extended provider, it also allows the same extended authentication provider to be reference by multiple locations.

Examples

This example checks for passwords in two different text files.

Checking multiple text password files

# Check here first
<AuthnProviderAlias file file1>
AuthUserFile /www/conf/passwords1
 </AuthnProviderAlias>

# Then check here
<AuthnProviderAlias file file2>
AuthUserFile /www/conf/passwords2
 </AuthnProviderAlias>

<Directory /var/web/pages/secure>
AuthBasicProvider file1 file2

AuthType Basic
AuthName "Protected Area"
Require valid-user
 </Directory>

The example below creates two different ldap authentication provider aliases based on the ldap provider. This allows a single authenticated location to be serviced by multiple ldap hosts:

Checking multiple LDAP servers

LoadModule authn_alias_module modules/mod_authn_alias.so

<AuthnProviderAlias ldap ldap-alias1>
AuthLDAPBindDN cn=youruser,o=ctx
AuthLDAPBindPassword yourpassword
AuthLDAPURL ldap://ldap.host/o=ctx
 </AuthnProviderAlias>

<AuthnProviderAlias ldap ldap-other-alias>
AuthLDAPBindDN cn=yourotheruser,o=dev
AuthLDAPBindPassword yourotherpassword
AuthLDAPURL ldap://other.ldap.host/o=dev?cn
 </AuthnProviderAlias>

Alias /secure /webpages/secure
<Directory /webpages/secure>
Order deny,allow
Allow from all

AuthBasicProvider ldap-other-alias ldap-alias1

AuthType Basic
AuthName LDAP_Protected_Place
AuthzLDAPAuthoritative off
Require valid-user
 </Directory>

<AuthnProviderAlias> Directive

Description: | Enclose a group of directives that represent an extension of a base authentication provider and referenced by the specified alias
Syntax: | <AuthnProviderAlias baseProvider Alias> ... </AuthnProviderAlias>
Context: | server config
Status: | Extension
Module: | mod_authn_alias

<AuthnProviderAlias> and </AuthnProviderAlias> are used to enclose a group of authentication directives that can be referenced by the alias name using one of the directives AuthBasicProvider or AuthDigestProvider.

This directive has no affect on authorization, even for modules that provide both authentication and authorization.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_authn_anon - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_authn_anon

説明: | 認証が必要な領域への "anonymous" ユーザのアクセスを許可する
ステータス: | Extension
モジュール識別子: | authn_anon_module
ソースファイル: | mod_authn_anon.c
互換性: | Apache 2.1 以降

概要

このモジュールは mod_auth_basic のような 認証フロントエンドとして、anonymous-ftp サイトのような、「魔法の」ユーザ ID 'anonymous' と電子メールアドレスをパスワードにしたユーザ認証を 行なう機能を提供します。この電子メールアドレスはログ収集することが できます。

他の (データベースによる) アクセス制御方法と組み合わせることで、 「未登録」ユーザに対してサイトを公開しつつ、効率よくユーザ追跡したり、 ユーザのプロファイルに応じたカスタマイズをしたりできます。 このような認証に基づいたユーザ追跡の利点の一つは、 マジッククッキーに基づくユーザ追跡方法や、 珍妙な URL の接頭辞や接尾辞を利用したユーザ追跡方法とは異なり、 完全にブラウザ非依存であり、ユーザ間で URL を共有することができるという 点です。

mod_auth_basic を使用している場合は、このモジュールは AuthBasicProvider に anon という値を設定することで起動されます。

例

以下の例は「普通」の htpasswd ファイルに基づいた認証と組み合わされて おり、以下の要件を見たすユーザを「ゲスト」として許可します:

  • ユーザは userID を入力しなければなりません。 (Anonymous_NoUserID)
  • ユーザはパスワードを入力しなければなりません。 (Anonymous_MustGiveEmail)
  • 入力されたパスワードは有効な電子メールアドレスでなければ なりません。すなわち、少くとも一つの '@' と '.' が 含まれている必要があります。 (Anonymous_VerifyEmail)
  • userID は anonymous guest www test welcome のどれかでなければなりません。 ユーザ名の比較は大文字小文字を区別しません。
  • パスワード欄に入力された電子メールアドレスはエラーログファイルに ロギングされます。 (Anonymous_LogEmail)

例

<Directory /foo> AuthName "Use 'anonymous' & Email address for guest entry"
AuthType Basic
AuthBasicProvider file anon
AuthUserFile /path/to/your/.htpasswd

Anonymous_NoUserID off
Anonymous_MustGiveEmail on
Anonymous_VerifyEmail on
Anonymous_LogEmail on
Anonymous anonymous guest www test welcome

Order Deny,Allow
Allow from all

Require valid-user
 </Directory>

Anonymous ディレクティブ

説明: | パスワードの検査無しでアクセスを許可する userID を指定する
構文: | Anonymous user [user] ...
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Extension
モジュール: | mod_authn_anon

パスワードの検査をしないでアクセスを許可する「魔法の」 userID を 設定します。userID 中に空白を使えるようにするため、 エスケープ文字 \ による方法と、引用符 ' と " によるクオーティング を使うことができます。

ユーザ名の比較は大文字小文字を区別しないことに 注意してください。
魔法のユーザ名 'anonymous' が許可されている userID に 含むようにすることは強く推奨されています。

例:

Anonymous anonymous "Not Registered" "I don't know"

これは、userID "anonymous", "AnonyMous", "Not Registered", "I Don't Know" のどれかを使っても パスワード無しでユーザがサイトに入れるようにします。

Apache 2.1 では userID に "*" を指定することができます。 この場合、すべてのuserID を許可します。

Anonymous_LogEmail ディレクティブ

説明: | 入力されたパスワードがエラーログにロギングされるかどうかを 設定する
構文: | Anonymous_LogEmail On|Off
デフォルト: | Anonymous_LogEmail On
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Extension
モジュール: | mod_authn_anon

デフォルトの On に設定された場合は、 入力された (まっとうな電子メールアドレスであることが 期待される) 「パスワード」がエラーログにロギングされます。

Anonymous_MustGiveEmail ディレクティブ

説明: | 空パスワードを許可するかどうかを指定する
構文: | Anonymous_MustGiveEmail On|Off
デフォルト: | Anonymous_MustGiveEmail On
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Extension
モジュール: | mod_authn_anon

ユーザがパスワードとして電子メールアドレスを指定する必要があるかどうかを 設定します。これは空パスワードを禁止します。

Anonymous_NoUserID ディレクティブ

説明: | 空 userID を許可するかを指定する
構文: | Anonymous_NoUserID On|Off
デフォルト: | Anonymous_NoUserID Off
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Extension
モジュール: | mod_authn_anon

On に設定すると、ユーザは userID (とおそらくは パスワード欄も) 空にすることができます。これは単にリターンキーを 叩いたり OK ボタンを直接クリックしたりする MS-Explorer ユーザには 非常に便利です。そのような操作はごくごく自然なものでしょう。

Anonymous_VerifyEmail ディレクティブ

説明: | パスワード欄が正しい形式の電子メールアドレスであることを 調べるかどうかを設定する
構文: | Anonymous_VerifyEmail On|Off
デフォルト: | Anonymous_VerifyEmail Off
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Extension
モジュール: | mod_authn_anon

On に設定されている場合、ユーザが有効な電子メール アドレスを入力することを推奨するため、入力された「パスワード」は 少なくとも一つの '@' と '.' を含んでいるかどうかを調べます (上の Anonymous_LogEmail 参照)。


mod_authn_dbd - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_authn_dbd

Description: | User authentication using an SQL database
Status: | Extension
Module Identifier: | authn_dbd_module
Source File: | mod_authn_dbd.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module provides authentication front-ends such as mod_auth_digest and mod_auth_basic to authenticate users by looking up users in SQL tables. Similar functionality is provided by, for example, mod_authn_file.

This module relies on mod_dbd to specify the backend database driver and connection parameters, and manage the database connections.

When using mod_auth_basic or mod_auth_digest, this module is invoked via the AuthBasicProvider or AuthDigestProvider with the dbd value.

See also

  • AuthName
  • AuthType
  • AuthBasicProvider
  • AuthDigestProvider
  • DBDriver
  • DBDParams

Configuration Example

This simple example shows use of this module in the context of the Authentication and DBD frameworks. Please note that you need to load an authorization module, such as mod_authz_user, to get it working.

# mod_dbd configuration
DBDriver pgsql
DBDParams "dbname=apacheauth user=apache password=xxxxxx"

DBDMin  4
DBDKeep 8
DBDMax  20
DBDExptime 300

<Directory /usr/www/myhost/private>
  # core authentication and mod_auth_basic configuration
  # for mod_authn_dbd
  AuthType Basic
  AuthName "My Server"
  AuthBasicProvider dbd

  # core authorization configuration
  Require valid-user

  # mod_authn_dbd SQL query to authenticate a user
  AuthDBDUserPWQuery \
    "SELECT password FROM authn WHERE user = %s"
</Directory>

Exposing Login Information

If httpd was built against APR version 1.3.0 or higher, then whenever a query is made to the database server, all column values in the first row returned by the query are placed in the environment, using environment variables with the prefix "AUTHENTICATE_".

If a database query for example returned the username, full name and telephone number of a user, a CGI program will have access to this information without the need to make a second independent database query to gather this additional information.

This has the potential to dramatically simplify the coding and configuration required in some web applications.

AuthDBDUserPWQuery Directive

Description: | SQL query to look up a password for a user
Syntax: | AuthDBDUserPWQuery query
Context: | directory
Status: | Extension
Module: | mod_authn_dbd

The AuthDBDUserPWQuery specifies an SQL query to look up a password for a specified user. The user's ID will be passed as a single string parameter when the SQL query is executed. It may be referenced within the query statement using a %s format specifier.

Example

AuthDBDUserPWQuery \
  "SELECT password FROM authn WHERE user = %s"

The first column value of the first row returned by the query statement should be a string containing the encrypted password. Subsequent rows will be ignored. If no rows are returned, the user will not be authenticated through mod_authn_dbd.

If httpd was built against APR version 1.3.0 or higher, any additional column values in the first row returned by the query statement will be stored as environment variables with names of the form AUTHENTICATE_COLUMN.

The encrypted password format depends on which authentication frontend (e.g. mod_auth_basic or mod_auth_digest) is being used. See Password Formats for more information.

AuthDBDUserRealmQuery Directive

Description: | SQL query to look up a password hash for a user and realm.
Syntax: | AuthDBDUserRealmQuery query
Context: | directory
Status: | Extension
Module: | mod_authn_dbd

The AuthDBDUserRealmQuery specifies an SQL query to look up a password for a specified user and realm in a digest authentication process. The user's ID and the realm, in that order, will be passed as string parameters when the SQL query is executed. They may be referenced within the query statement using %s format specifiers.

Example

AuthDBDUserRealmQuery \
  "SELECT password FROM authn WHERE user = %s AND realm = %s"

The first column value of the first row returned by the query statement should be a string containing the encrypted password. Subsequent rows will be ignored. If no rows are returned, the user will not be authenticated through mod_authn_dbd.

If httpd was built against APR version 1.3.0 or higher, any additional column values in the first row returned by the query statement will be stored as environment variables with names of the form AUTHENTICATE_COLUMN.

The encrypted password format depends on which authentication frontend (e.g. mod_auth_basic or mod_auth_digest) is being used. See Password Formats for more information.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_authn_dbm - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_authn_dbm

説明: | DBM ファイルを用いたユーザ認証
ステータス: | Extension
モジュール識別子: | authn_dbm_module
ソースファイル: | mod_authn_dbm.c
互換性: | Apache 2.1 以降

概要

本モジュールは mod_auth_digest や mod_auth_basic といった認証フロントエンドに対して、 dbm パスワードファイル内からのユーザ検索による ユーザ認証機能を提供します。似たような機能は mod_authn_file でも提供されています。

mod_auth_basic や mod_auth_digest を使用する際には、このモジュールは AuthBasicProvider や AuthDigestPrivider で dbm と指定することで起動されます。

参照

  • AuthName
  • AuthType
  • AuthBasicProvider
  • AuthDigestProvider

AuthDBMType ディレクティブ

説明: | パスワードを保存するために必要なデータベースファイルの種類を 設定する
構文: | AuthDBMType default|SDBM|GDBM|NDBM|DB
デフォルト: | AuthDBMType default
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Extension
モジュール: | mod_authn_dbm

パスワードを保存するために使用するデータベースファイルの種類を 設定します。デフォルトのデータベースの種類はコンパイル時に決まります。 他の種類のデータベースが使用可能かどうかも コンパイル時の設定に依存します。

パスワードファイルを作成するのに使用するプログラムが同じ種類のデータベースを 使用するように設定することは非常に重要です。

AuthDBMUserFile ディレクティブ

説明: | 認証用のユーザとパスワードのリストを保持している データベースファイル名を設定する
構文: | AuthDBMUserFile file-path
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Extension
モジュール: | mod_authn_dbm

AuthDBMUserFile ディレクティブは 認証用のユーザとパスワードのリストを保持している DBM ファイルの 名前を設定します。File-path はユーザファイルへの 絶対パスです。

ユーザファイルのキーはユーザ名です。ユーザに対して返される値は 暗号化されたパスワードで、その後に、コロンに続いて任意のデータが 続いていることもあります。コロンとその後のデータはサーバは 無視します。

セキュリティ

AuthDBMUserFile は、 ウェブサーバのドキュメントツリーの外側に保管するようにしてください。 保護しようとしているディレクトリ以下には 置かないで下さい。 そうしないとクライアントが AuthUserFile を ダウンロードできてしまいます。

重要な互換性に関する注意: apache module の dbmopen の実装は 文字列が NULL で終わっていることに依存するのではなく、DBM データストラクチャ のハッシュ値の文字列の長さを読み取ります。Netscape ウェブサーバなど、 アプリケーションの中には文字列が NULL で終わっていることに依存している ものがあります。ですから、異なるアプリケーション間での DBM ファイルの 使用に問題がある場合は、これが原因になっている可能性があります。

Apache には dbmmanage という perl スクリプトが含まれています。このプログラムを使ってこの モジュールが使用する DBM フォーマットのパスワードファイルを作成したり 更新したりすることができます。


mod_authn_default - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_authn_default

説明: | 認証フォールバックモジュール
ステータス: | Base
モジュール識別子: | authn_default_module
ソースファイル: | mod_authn_default.c
互換性: | Apache 2.1 以降

概要

mod_auth_basic のような認証モジュールを 設定しなかった場合は、本モジュールがフォールバックとなります。 ユーザから提示されたどんな証書も単に拒否します。

AuthDefaultAuthoritative ディレクティブ

説明: | 次の低次レベルの認証モジュールに制御を渡すかどうかを 設定します
構文: | AuthDefaultAuthoritative On|Off
デフォルト: | AuthDefaultAuthoritative On
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Base
モジュール: | mod_authn_default

AuthDefaultAuthoritative ディレクティブを 明示的に Off に設定すると、 認証を次の (modules.c ファイルで定義されている) 低次レベルのモジュールに渡します。

注意

mod_authn_default 自体がとても低い レベルとして定義されていますので、通常はこれよりも低次の モジュールは存在しません。ですから AuthDefaultAuthoritative はデフォルト (On) のままにしたほうが良いでしょう。


mod_authn_file - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_authn_file

説明: | テキストファイルを用いたユーザ認証
ステータス: | Base
モジュール識別子: | authn_file_module
ソースファイル: | mod_authn_file.c
互換性: | Apache 2.1 以降

概要

本モジュールは mod_auth_digest や mod_auth_basic といった認証フロントエンドに対して、 プレインテキストのパスワードファイル内からユーザを検索することで、 ユーザ認証機能を提供します。似たような機能は mod_authn_dbm でも提供されています。

mod_auth_basic や mod_auth_digest を使用する際には、 AuthBasicProvider や AuthDigestPrivider で file と指定することでこのモジュールは起動されます。

参照

  • AuthBasicProvider
  • AuthDigestProvider
  • htpasswd
  • htdigest

AuthUserFile ディレクティブ

説明: | 認証に使用するユーザとパスワードの一覧が格納されている、 テキストファイルの名前を設定する
構文: | AuthUserFile file-path
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Base
モジュール: | mod_authn_file

AuthUserFile ディレクティブは、 ユーザ認証のためのユーザとパスワードの一覧を格納した テキストファイルの名前を設定します。file-path はユーザファイルへのパスです。 もし絶対パスでなければ、 ServerRoot からの相対パスとして扱われます。

ユーザファイルの各行には、ユーザ名、コロン、 暗号化したパスワードを記述します。 同一ユーザ ID が複数回登録された時は、 mod_authn_file は最初に見つかったパスワードを使用して認証します。

バイナリ配布の一部としてインストールされるか、 あるいは src/support にある htpasswd ユーティリティで、この HTTP 基本認証 用パスワードファイルをメインテナンスします。 詳細は man ページをご覧頂くとして、簡単には:

初期 ID username で、Filename というパスワードファイルを生成します。 次のコマンドを発行するとパスワードが要求されます:

htpasswd -c Filename username

パスワードファイル Filename に、username2 を追加したり修正したりします:

htpasswd Filename username2

(訳注: 非常に多くのユーザを登録すると大きなファイルになりますが) 大きなテキストファイルを検索するのは非常に効率が悪い ということに注意してください。そのような必要のある時は、 AuthDBMUserFile を代わりに使ってください。

HTTP ダイジェスト認証を使用する場合は、 htpasswd プログラムでは不十分です。その代わりに htdigest を使用してください。ダイジェスト認証用のデータと 基本認証用のデータを同一ファイルに混ぜて保存できない、 ということに注意してください。

セキュリティ

AuthUserFile は、ウェブサーバのドキュメントツリーの外側に保管するようにしてください。 保護しようとしているディレクトリ以下には、置かないで下さい。 そうしないと AuthUserFile は ダウンロードできてしまいます。


mod_authnz_ldap - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_authnz_ldap

Description: | Allows an LDAP directory to be used to store the database for HTTP Basic authentication.
Status: | Extension
Module Identifier: | authnz_ldap_module
Source File: | mod_authnz_ldap.c
Compatibility: | Available in version 2.1 and later

Summary

This module provides authentication front-ends such as mod_auth_basic to authenticate users through an ldap directory.

mod_authnz_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.
  • 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).

When using mod_auth_basic, this module is invoked via the AuthBasicProvider directive with the ldap value.

See also

  • mod_ldap
  • mod_auth_basic
  • mod_authz_user
  • mod_authz_groupfile

Contents

  • Operation
    • The Authentication Phase
    • The Authorization Phase
  • The Require Directives
    • Require ldap-user
    • Require ldap-group
    • Require ldap-dn
    • Require ldap-attribute
    • Require ldap-filter
  • Examples
  • Using TLS
  • Using SSL
  • Exposing Login Information
  • Using Microsoft FrontPage with mod_authnz_ldap
    • How It Works
    • Caveats

Operation

There are two phases in granting access to a user. The first phase is authentication, in which the mod_authnz_ldap authentication provider verifies that the user's credentials are valid. This is also called the search/bind phase. The second phase is authorization, in which mod_authnz_ldap determines if the authenticated user is allowed access to the resource in question. This is also known as the compare phase.

mod_authnz_ldap registers both an authn_ldap authentication provider and an authz_ldap authorization handler. The authn_ldap authentication provider can be enabled through the AuthBasicProvider directive using the ldap value. The authz_ldap handler extends the Require directive's authorization types by adding ldap-user, ldap-dn and ldap-group values.

The Authentication Phase

During the authentication phase, mod_authnz_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_authnz_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_authnz_ldap attempts to determine if the user is authorized to access the resource. Many of these checks require mod_authnz_ldap to do a compare operation on the LDAP server. This is why this phase is often referred to as the compare phase. mod_authnz_ldap accepts the following Require directives to determine if the credentials are acceptable:

  • Grant access if there is a Require ldap-user directive, and the username in the directive matches the username passed by the client.
  • Grant access if there is a Require ldap-dn directive, and the DN in the directive matches the DN fetched from the LDAP directory.
  • Grant access if there is a Require ldap-group directive, and the DN fetched from the LDAP directory (or the username passed by the client) occurs in the LDAP group.
  • Grant access if there is a Require ldap-attribute directive, and the attribute fetched from the LDAP directory matches the given value.
  • Grant access if there is a Require ldap-filter directive, and the search filter successfully finds a single user object that matches the dn of the authenticated user.
  • otherwise, deny or decline access

Other Require values may also be used which may require loading additional authorization modules. Note that if you use a Require value from another authorization module, you will need to ensure that AuthzLDAPAuthoritative is set to off to allow the authorization phase to fall back to the module providing the alternate Require value. When no LDAP-specific Require directives are used, authorization is allowed to fall back to other modules as if AuthzLDAPAuthoritative was set to off.

  • Grant access to all successfully authenticated users if there is a Require valid-user directive. (requires mod_authz_user)
  • Grant access if there is a Require group directive, and mod_authz_groupfile has been loaded with the AuthGroupFile directive set.
  • others...

mod_authnz_ldap uses the following directives during the compare phase:

AuthLDAPURL | The attribute specified in the URL is used in compare operations for the Require ldap-user operation.
AuthLDAPCompareDNOnServer | Determines the behavior of the Require ldap-dn directive.
AuthLDAPGroupAttribute | Determines the attribute to use for comparisons in the Require ldap-group directive.
AuthLDAPGroupAttributeIsDN | Specifies whether to use the user DN or the username when doing comparisons for the Require ldap-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. mod_authnz_ldap extends the authorization types with ldap-user, ldap-dn, ldap-group, ldap-attribute and ldap-filter. Other authorization types may also be used but may require that additional authorization modules be loaded.

Require ldap-user

The Require ldap-user directive specifies what usernames can access the resource. Once mod_authnz_ldap has retrieved a unique DN from the directory, it does an LDAP compare operation using the username specified in the Require ldap-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 ldap-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 ldap-user "Barbara Jenson"
Require ldap-user "Fred User"
Require ldap-user "Joe Manager"

Because of the way that mod_authnz_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 ldap-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 ldap-user bjenson fuser jmanager

Require ldap-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 ldap-group cn=Administrators, o=Airius

Behavior of this directive is modified by the AuthLDAPGroupAttribute and AuthLDAPGroupAttributeIsDN directives.

Require ldap-dn

The Require ldap-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 ldap-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 ldap-dn cn=Barbara Jenson, o=Airius

Behavior of this directive is modified by the AuthLDAPCompareDNOnServer directive.

Require ldap-attribute

The Require ldap-attribute directive allows the administrator to grant access based on attributes of the authenticated user in the LDAP directory. If the attribute in the directory matches the value given in the configuration, access is granted.

The following directive would grant access to anyone with the attribute employeeType = active

Require ldap-attribute employeeType=active

Multiple attribute/value pairs can be specified on the same line separated by spaces or they can be specified in multiple Require ldap-attribute directives. The effect of listing multiple attribute/values pairs is an OR operation. Access will be granted if any of the listed attribute values match the value of the corresponding attribute in the user object. If the value of the attribute contains a space, only the value must be within double quotes.

The following directive would grant access to anyone with the city attribute equal to "San Jose" or status equal to "Active"

Require ldap-attribute city="San Jose" status=active

Require ldap-filter

The Require ldap-filter directive allows the administrator to grant access based on a complex LDAP search filter. If the dn returned by the filter search matches the authenticated user dn, access is granted.

The following directive would grant access to anyone having a cell phone and is in the marketing department

Require ldap-filter &(cell=*)(department=marketing)

The difference between the Require ldap-filter directive and the Require ldap-attribute directive is that ldap-filter performs a search operation on the LDAP directory using the specified search filter rather than a simple attribute comparison. If a simple attribute comparison is all that is required, the comparison operation performed by ldap-attribute will be faster than the search operation used by ldap-filter especially within a large directory.

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 it 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 ldap-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 pager, 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. 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 LDAPTrustedClientCert, LDAPTrustedGlobalCert and LDAPTrustedMode.

An optional second parameter can be added to the AuthLDAPURL to override the default connection type set by LDAPTrustedMode. This will allow the connection established by an ldap:// Url to be upgraded to a secure connection on the same port.

Using SSL

To use SSL, see the mod_ldap directives LDAPTrustedClientCert, LDAPTrustedGlobalCert and LDAPTrustedMode.

To specify a secure LDAP server, use ldaps:// in the AuthLDAPURL directive, instead of ldap://.

Exposing Login Information

When this module performs authentication, LDAP attributes specified in the AuthLDAPUrl directive are placed in environment variables with the prefix "AUTHENTICATE_".

If the attribute field contains the username, common name and telephone number of a user, a CGI program will have access to this information without the need to make a second independent LDAP query to gather this additional information.

This has the potential to dramatically simplify the coding and configuration required in some web applications.

Using Microsoft FrontPage with mod_authnz_ldap

Normally, FrontPage uses FrontPage-web-specific user/group files (i.e., the mod_authn_file and mod_authz_groupfile modules) 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"
AuthGroupFile mygroupfile
Require group mygroupfile

How It Works

FrontPage restricts access to a web by adding the Require valid-user directive to the .htaccess files. 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. By substituting the ldap-group with group file authorization, Apache is allowed to consult the local user file (which is managed by FrontPage) - instead of LDAP - when handling authorizing the user.

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_authn_file 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_basic, mod_authn_file and mod_authz_groupfile in order to use FrontPage support. This is because Apache will still use the mod_authz_groupfile 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_authnz_ldap has to be able to grab the AuthGroupFile directive that is found in FrontPage .htaccess files so that it knows where to look for the valid user list. If the mod_authnz_ldap directives aren't in the same .htaccess file as the FrontPage directives, then the hack won't work, because mod_authnz_ldap will never get a chance to process the .htaccess file, and won't be able to find the FrontPage-managed user file.

AuthLDAPBindAuthoritative Directive

Description: | Determines if other authentication providers are used when a user can be mapped to a DN but the server cannot successfully bind with the user's credentials.
Syntax: | AuthLDAPBindAuthoritativeoff|on
Default: | AuthLDAPBindAuthoritative on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap
Compatibility: | Available in versions later than 2.2.14

By default, subsequent authentication providers are only queried if a user cannot be mapped to a DN, but not if the user can be mapped to a DN and their password cannot be verified with an LDAP bind. If AuthLDAPBindAuthoritative is set to off, other configured authentication modules will have a chance to validate the user if the LDAP bind (with the current user's credentials) fails for any reason.

This allows users present in both LDAP and AuthUserFile to authenticate when the LDAP server is available but the user's account is locked or password is otherwise unusable.

See also

  • AuthUserFile
  • AuthBasicProvider

AuthLDAPBindDN Directive

Description: | Optional DN to use in binding to the LDAP server
Syntax: | AuthLDAPBindDN distinguished-name
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap

An optional DN used to bind to the server when searching for entries. If not provided, mod_authnz_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: | Extension
Module: | mod_authnz_ldap
Compatibility: | exec: was added in 2.2.25.

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.

If the value begins with exec: the resulting command will be executed and the first line returned to standard output by the program will be used as the password.

#Password used as-is
AuthLDAPBindPassword secret

#Run /path/to/program to get my password
AuthLDAPBindPassword exec:/path/to/program

#Run /path/to/otherProgram and provide arguments
AuthLDAPBindPassword "exec:/path/to/otherProgram argument1"

AuthLDAPCharsetConfig Directive

Description: | Language to charset conversion configuration file
Syntax: | AuthLDAPCharsetConfig file-path
Context: | server config
Status: | Extension
Module: | mod_authnz_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: | Extension
Module: | mod_authnz_ldap

When set, mod_authnz_ldap will use the LDAP server to compare the DNs. This is the only foolproof way to compare DNs. mod_authnz_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_authnz_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: | Extension
Module: | mod_authnz_ldap

This directive specifies when mod_authnz_ldap will de-reference aliases during LDAP operations. The default is always.

AuthLDAPGroupAttribute Directive

Description: | LDAP attributes used to check for group membership
Syntax: | AuthLDAPGroupAttribute attribute
Default: | AuthLDAPGroupAttribute member uniquemember
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_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_authnz_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: | Extension
Module: | mod_authnz_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_authnz_ldap will check if the group has cn=Babs Jenson, o=Airius as a member. If this directive is not set, then mod_authnz_ldap will check if the group has bjenson as a member.

AuthLDAPRemoteUserAttribute Directive

Description: | Use the value of the attribute returned during the user query to set the REMOTE_USER environment variable
Syntax: | AuthLDAPRemoteUserAttribute uid
Default: | none
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap

If this directive is set, the value of the REMOTE_USER environment variable will be set to the value of the attribute specified. Make sure that this attribute is included in the list of attributes in the AuthLDAPUrl definition, otherwise this directive will have no effect. This directive, if present, takes precedence over AuthLDAPRemoteUserIsDN. This directive is useful should you want people to log into a website using an email address, but a backend application expects the username as a userid.

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: | Extension
Module: | mod_authnz_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 [NONE|SSL|TLS|STARTTLS]
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_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_authnz_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_authnz_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 more 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)).

An optional parameter can be added to allow the LDAP Url to override the connection type. This parameter can be one of the following:

NONE
Establish an unsecure connection on the default LDAP port. This is the same as ldap:// on port 389.
SSL
Establish a secure connection on the default secure LDAP port. This is the same as ldaps://
TLS | STARTTLS
Establish an upgraded secure connection on the default LDAP port. This connection will be initiated on port 389 by default and then upgraded to a secure connection on the same port.

See above for examples of AuthLDAPURL URLs.

When AuthLDAPURL is enabled in a particular context, but some other module has performed authentication for the request, the server will try to map the username to a DN during authorization regardless of whether or not LDAP-specific requirements are present. To ignore the failures to map a username to a DN during authorization, set AuthzLDAPAuthoritative to "off".

AuthzLDAPAuthoritative Directive

Description: | Prevent other authentication modules from authenticating the user if this one fails
Syntax: | AuthzLDAPAuthoritative on|off
Default: | AuthzLDAPAuthoritative on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authnz_ldap

Set to off if this module should let other authorization modules attempt to authorize the user, should authorization 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).

When no LDAP-specific Require directives are used, authorization is allowed to fall back to other modules as if AuthzLDAPAuthoritative was set to off.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_authz_dbm - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_authz_dbm

Description: | Group authorization using DBM files
Status: | Extension
Module Identifier: | authz_dbm_module
Source File: | mod_authz_dbm.c
Compatibility: | Available in Apache 2.1 and later

Summary

This module provides authorization capabilities so that authenticated users can be allowed or denied access to portions of the web site by group membership. Similar functionality is provided by mod_authz_groupfile.

See also

  • Require
  • Satisfy

AuthDBMGroupFile Directive

Description: | Sets the name of the database file containing the list of user groups for authorization
Syntax: | AuthDBMGroupFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authz_dbm

The AuthDBMGroupFile directive sets the name of a DBM file containing the list of user groups for user authorization. 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

Encrypted 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 authorization module. This is what www.telescope.org uses for its combined password and group database.

AuthzDBMAuthoritative Directive

Description: | Sets whether authorization will be passed on to lower level modules
Syntax: | AuthzDBMAuthoritative On|Off
Default: | AuthzDBMAuthoritative On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authz_dbm

Setting the AuthzDBMAuthoritative directive explicitly to Off allows group authorization to be passed on to lower level modules (as defined in the modules.c file) if there is no group found for the supplied userID. If there are any groups specified, the usual 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 AuthAuthoritative setting.

A common use for this is in conjunction with one of the auth providers; such as mod_authn_dbm or mod_authn_file. 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 group 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.

AuthzDBMType Directive

Description: | Sets the type of database file that is used to store list of user groups
Syntax: | AuthzDBMType default|SDBM|GDBM|NDBM|DB
Default: | AuthzDBMType default
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authz_dbm

Sets the type of database file that is used to store the list of user groups. 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 group files is configured to use the same type of database.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_authz_default - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_authz_default

説明: | 承認フォールバックモジュール
ステータス: | Base
モジュール識別子: | authz_default_module
ソースファイル: | mod_authz_default.c
互換性: | Apache 2.1 以降

概要

このモジュールは mod_authz_user や mod_authz_groupfile といった承認モジュールを 設定しなかった場合のフォールバックモジュールとして設計されています。 どのような承認リクエストも単に拒否します。

AuthzDefaultAuthoritative ディレクティブ

説明: | 承認が低位のモジュールに渡されるかどうかを設定する
構文: | AuthzDefaultAuthoritative On|Off
デフォルト: | AuthzDefaultAuthoritative On
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Base
モジュール: | mod_authz_default

AuthzDefaultAuthoritative ディレクティブを 明示的に Off に設定すると 認証を次の (modules.c ファイルで定義されている) 低位のモジュールに渡すことを許可します。

注意

mod_authz_default 自体がとても低い レベルとして定義されていますので、通常はこれよりも低次の モジュールは存在しません。ですから AuthDefaultAuthoritative はデフォルト (On) のままにしたほうが良いでしょう。


mod_authz_groupfile - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_authz_groupfile

説明: | プレーンテキストファイルを用いたグループ承認
ステータス: | Base
モジュール識別子: | authz_groupfile_module
ソースファイル: | mod_authz_groupfile.c
互換性: | Apache 2.1 以降

概要

このモジュールは認証されたユーザがグループのメンバーか 否かによってウェブサイトの一部へのアクセスを許可するか拒否するかの 承認機能を提供します。同様の機能は mod_authz_dbm によっても提供されています。

参照

  • Require
  • Satisfy

AuthGroupFile ディレクティブ

説明: | 証認に使用するユーザグループの一覧が格納されている、 テキストファイルの名前を設定する
構文: | AuthGroupFile file-path
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Base
モジュール: | mod_authz_groupfile

AuthGroupFile ディレクティブは、 証認に使用するユーザグループの一覧が格納されている、 テキストファイルの名前を設定します。 file-path はグループファイルへのパスです。 絶対パスでなければ、 ServerRoot からの相対パスとして扱われます。

グループファイル各行は、グループ名、コロン、そして スペース区切りでそのメンバーのユーザ名を記述します。

例:

mygroup: bob joe anne

大きなファイルを探索するのは、非常に効率が悪いという点に 注意してください。そのような場合は、 AuthDBMGroupFile の方がずっと良い性能を発揮します。

セキュリティ

AuthGroupFile は、 ウェブサーバのドキュメントツリーの外側に 保管するようにしてください。 保護しようとしているディレクトリ以下には、置かないで下さい。 そうしないとクライアントが AuthGroupFile を ダウンロードできてしまう可能性があります。

AuthzGroupFileAuthoritative ディレクティブ

説明: | 承認が下位のモジュールに渡されるかどうかを設定する
構文: | AuthzGroupFileAuthoritative On|Off
デフォルト: | AuthzGroupFileAuthoritative On
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Base
モジュール: | mod_authz_groupfile

AuthzGroupFileAuthoritative ディレクティブを 明示的に Off に設定すると userID に対応する グループがない場合に、 (module.c で定義されている) 下位のモジュールにグループ承認を 渡すことを許可します。

デフォルトでは制御は渡されず、未知のグループの場合は Authentication Required 応答が返されます。ですから、これを設定しないと システムを安全に保つことができ、NCSA 互換の振る舞いをさせることになります。

セキュリティ

ユーザの .htaccess ファイルで他の承認手段への 委譲ができるようにすることの意味するところは十分に考慮しておいてください。 そしてそれが、本当に望む挙動であることを確かめてください。 通常は一つの .htpasswd ファイルを安全にする方が より多くのアクセスインタフェースを持つかもしれないデータベースを 安全にするよりも簡単です。


mod_authz_host - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_authz_host

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | ホスト (名前もしくは IP アドレス) に基づいたグループ承認
ステータス: | Base
モジュール識別子: | authz_host_module
ソースファイル: | mod_authz_host.c
互換性: | Apache 2.1 以降

概要

mod_authz_host により提供されるディレクティブは サーバの特定の部分への アクセスを制御するために <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_authz_host

Allow ディレクティブはどのホストが サーバのある領域をアクセスできるかに影響を与えます。 アクセスはホスト名、IP アドレス、IP アドレスの範囲や、 環境変数として取得された、その他のクライアントのリクエストの 特徴によって制御することができます。

このディレクティブの最初の引数は常に from です。 それに続く引数は三つの違った形式があります。Allow from all が指定されていれば、すべてのホストにアクセスを許可し、 アクセス制限は下で説明されているように、 Deny ディレクティブと Order ディレクティブの設定で決まります。 特定のホストやホスト群にのみサーバへのアクセスを許可するためには、 以下のどれかの形式で host を指定することができます:

ドメイン名 (の一部)

例

Allow from apache.org
Allow from .net example.edu

この文字列に合うか、これで終わる名前のホストのアクセスが許可されます。 各部分が完全に合うものだけに適用されますので、上の例は foo.apache.org にはマッチしますが、 fooapache.org にはマッチしません。 この設定をすると、Apache は HostnameLookups の設定に関わらず、クライアントの IP アドレスに対して DNS の 2 重逆引きを行ないます。 ホスト名からオリジナルの IP アドレスを順引きします。 順引きと逆引きが一致し、ホスト名が該当した場合にのみ、 アクセスが許可されます。

完全な IP アドレス

例

Allow from 10.1.2.3
Allow from 192.168.1.104 192.168.1.205

アクセスを許可する IP アドレスです。

IP アドレスの一部

例

Allow from 10.1
Allow from 10 172.20 192.168.2

サブネットの制限用の、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 2001:db8::a00:20ff:fea7:ccea
Allow from 2001:db8::a00:20ff:fea7:ccea/10

Allow ディレクティブの引数の三つ目の形式は、 環境変数 の存在によりアクセスの制御を行なえるようにするものです。 Allow from env=env-variable が指定されていると、環境変数 env-variable が存在した場合にリクエストはアクセスを許可されます。サーバは mod_setenvif のディレクティブにより、クライアントのリクエスト の特徴に基づいて柔軟に環境変数を設定する機能を提供します。 ですから、このディレクティブはクライアントの User-Agent (ブラウザの種類)、Referer や他の HTTP リクエストのヘッダフィールドなどに基づいて アクセス許可をするために使うことができます。

Example:

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_authz_host

このディレクティブはホスト名、IP アドレス、環境変数に基づいてサーバへのアクセスを制限します。 Deny ディレクティブの引数は Allow ディレクティブとまったく同じです。

Order ディレクティブ

説明: | デフォルトのアクセス可能な状態と、Allow と Deny が評価される順番を制御する
構文: | Order ordering
デフォルト: | Order Deny,Allow
コンテキスト: | ディレクトリ, .htaccess
上書き: | Limit
ステータス: | Base
モジュール: | mod_authz_host

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_authz_owner - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_authz_owner

説明: | ファイルの所有者に基づいた承認
ステータス: | Extension
モジュール識別子: | authz_owner_module
ソースファイル: | mod_authz_owner.c
互換性: | Apache 2.1 以降で使用可能

概要

このモジュールはリクエストされたファイルのファイルシステムの 所有者やグループを HTTP 認証に使われたユーザ ID (ウェブユーザ ID) と 比較することでアクセスを承認します。提供されたユーザ名とパスワードは mod_auth_basic や mod_auth_digest のような認証モジュールで既に 適切に検証されている必要があります。mod_authz_owner は以下のように、Require ディレクティブの file-owner と file-group という二つの引数を認識します:

file-owner
提供されたウェブユーザ名はリクエストされたファイルの所有者の システムにおける名前と一致する必要があります。つまり、オペレーティング システムがファイルは jones により所有されている と言ったときは、ウェブからのアクセスに使われるユーザ名も jones でなければなりません。
file-group
ファイルを所有するシステムのグループの名前が、例えば mod_authz_groupfile や mod_authz_dbm により提供されるグループデータベースに存在していて、 ウェブユーザ名がそのグループに属していなければなりません。 例えば、オペレーティングシステムがファイルは (システムの) グループ accounts により所有されていると言ったときは、 accounts がグループデータベースに存在して、 リクエストに使用されたウェブユーザ名がそのグループに属している 必要があります。

注

ファイルシステムに実際には存在しないリソース (つまり バーチャルなリソース) の承認に mod_authz_owner が使用されたときは、 アクセスは拒否されます。

特に、コンテント ネゴシエーションされた"MultiViews" のリソースは 決して承認しません。

参照

  • Require
  • Satisfy

設定例

Require file-owner

複数ユーザのシステムで Apache ウェブサーバが実行されていて、 ~/public_html/private に各ユーザがファイルを置いているとします。 AuthDBMUserFile データベースが一つだけあり、すべてのウェブユーザ名が列挙されており、 このユーザ名がサーバで実際にファイルを所有しているユーザ名と一致している場合、 次の節のような設定で、ユーザが自分自身のファイルにアクセスできるようになります。 /home/smith/public_html/private の中のファイルは、所有者が smith の代わりに jones になっていない限り、 jones にはアクセスは許可されません。

<Directory /home/*/public_html/private>
AuthType Basic
AuthName MyPrivateFiles
AuthBasicProvider dbm
AuthDBMUserFile /usr/local/apache2/etc/.htdbm-all
Satisfy All
Require file-owner
 </Directory>

Require file-group

上記のようなシステムで、数人のユーザがプロジェクトのファイルを ~/public_html/project-foo で共有しているとします。 ファイルはシステムのグループ foo に所有されていて、 AuthDBMGroupFile データベースが一つだけあり、そこにすべてのウェブユーザ名と グループのメンバが列挙されている、つまり、それらの ユーザは少なくとも foo というグループに属している、とします。 jones とsmith の二人共がグループ foo のメンバである場合、どちらの人も両方の project-foo にアクセスが許可されます。

<Directory /home/*/public_html/project-foo>
AuthType Basic
AuthName "Project Foo Files"
AuthBasicProvider dbm

# combined user/group database
AuthDBMUserFile /usr/local/apache2/etc/.htdbm-all
AuthDBMGroupFile /usr/local/apache2/etc/.htdbm-all

Satisfy All
Require file-group
 </Directory>

AuthzOwnerAuthoritative ディレクティブ

説明: | 承認が下位承認モジュールに渡されるかどうかを設定する
構文: | AuthzOwnerAuthoritative On|Off
デフォルト: | AuthzOwnerAuthoritative On
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Extension
モジュール: | mod_authz_owner

AuthzOwnerAuthoritative ディレクティブを 明示的に Off に設定すると、以下の場合に認証が (modules.c で定義されている) 下位のモジュールに 渡されるようにします:

  • file-owner の場合は、提供されたウェブユーザ名に ファイルシステムの所有者が一致しないか、所有者がわからない場合。
  • file-group の場合は、提供されたウェブユーザ名が ファイルシステムグループに存在しないか、わからない場合。

値を Off に設定すると、file-owner と file-group を組み合わせることもできるようになり、 その場合はどちらか (両方でも) にマッチした場合にアクセスを許可されます。

デフォルトでは制御は渡されず、未知のグループの場合は Authentication Required 応答が返されます。ですから、Off に設定しないことで システムを安全に保つことができ、NCSA 互換の振る舞いをさせることになります。


mod_authz_user - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_authz_user

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | ユーザ承認
ステータス: | Base
モジュール識別子: | authz_user_module
ソースファイル: | mod_authz_user.c
互換性: | Apache 2.1 以降で使用可能

概要

このモジュールは、認証されたユーザにウェブサイトの一部への アクセスを許可したり拒否したりするための承認機能を提供します。 mod_authz_user は認証されたユーザが Require user ディレクティブに書かれていれば アクセスを認めます。認証に成功したユーザすべてにアクセスを 許可するには、代わりに require valid-user を 使うことができます。

参照

  • Require
  • Satisfy

AuthzUserAuthoritative ディレクティブ

説明: | 承認が下位のモジュールに渡されるかどうかを設定する
構文: | AuthzUserAuthoritative On|Off
デフォルト: | AuthzUserAuthoritative On
コンテキスト: | ディレクトリ, .htaccess
上書き: | AuthConfig
ステータス: | Base
モジュール: | mod_authz_user

AuthzUserAuthoritative ディレクティブを 明示的に Off に設定すると userID に対応する グループがない場合に、 (module.c で定義されている) 下位のモジュールにグループ承認を 渡すことを許可します。

デフォルトでは制御は渡されず、未知のグループの場合は Authentication Required 応答が返されます。ですから、これを設定しないと システムを安全に保つことができ、NCSA 互換の振る舞いをさせることになります。


mod_autoindex - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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 を設定して、これらのタグが繰り返されないようにしたいと思うでしょう。

IndexHeadInsert ディレクティブ

説明: | Inserts text in the HEAD section of an index page.
構文: | IndexHeadInsert "markup ..."
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex
互換性: | Available in Apache 2.2.11 and later

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

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 に負荷をかけます。
ShowForbidden
指定した場合であっても、サブリクエストの結果が HTTP_UNAUTHORIZED や HTTP_FORBIDDEN のファイルは通常通り隠された状態のまま、 ファイル一覧が生成されます。
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 インデックスオプションとを組み合わせることで、 ディレクトリ一覧をある特定の順番でのみ表示するようにできます。 これは、 クライアントが別の順番でディレクトリ一覧をリクエストすることを防ぎます。

IndexStyleSheet ディレクティブ

説明: | ディレクトリインデックスに CSS スタイルシートを追加する
構文: | IndexStyleSheet url-path
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_autoindex

IndexStyleSheet ディレクティブは インデックス表示に使用される CSS のファイル名を設定します。

例

IndexStyleSheet "/css/style.css"

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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_cache

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | URI をキーにしたコンテンツのキャッシュ
ステータス: | Extension
モジュール識別子: | cache_module
ソースファイル: | mod_cache.c

概要

使用方法については注意する必要があり、 Allow や Deny ディレクティブを迂回する設定もできてしまいます。 ホスト名やアドレスや環境変数に基づいてクライアントからの アクセスを制限したい場合は、キャッシュ機能を有効にすべきでは ありません。

mod_cache はローカルのコンテンツやプロキシされた コンテンツをキャッシュするために使われる RFC 2616 準拠の HTTP コンテンツキャッシュを実装しています。mod_cache の動作にはストレージを管理するモジュールが必要です。標準 Apache 配布には二つストレージ管理モジュールが含まれています:

mod_disk_cache
ディスクを使用したストレージ管理機構を実装しています。
mod_mem_cache
メモリを使用したストレージ管理機構を実装しています。 mod_mem_cache は次の二つのモードのどちらかで動作する ように設定できます: オープンされているファイル記述子をキャッシュするモードか、 ヒープ上でのオブジェクトの自体をキャッシュをするモードです。 mod_mem_cache はローカルで生成されるコンテンツや、 mod_proxy が ProxyPass を使って設定されている ときの (つまりリバースプロキシ での) バックエンドサーバの コンテンツをキャッシュするのに使えます。

コンテンツのキャッシュへの保存と取得は URI に基づいたキーが使われます。 アクセス保護のかけられているコンテンツはキャッシュされません。

詳細や解説、例については Caching Guide を参照して下さい。

参照

  • Caching Guide

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

関連モジュール 関連ディレクティブ
  • mod_disk_cache
  • mod_mem_cache
  • CacheRoot
  • CacheDirLevels
  • CacheDirLength
  • CacheMinFileSize
  • CacheMaxFileSize
  • MCacheSize
  • MCacheMaxObjectCount
  • MCacheMinObjectSize
  • MCacheMaxObjectSize
  • MCacheRemovalAlgorithm
  • MCacheMaxStreamingBuffer

サンプル設定

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
# If you want to use mod_disk_cache instead of mod_mem_cache,
# uncomment the line above and comment out the LoadModule line below.
<IfModule mod_disk_cache.c>
CacheRoot c:/cacheroot
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>

# When acting as a proxy, don't cache the list of security updates
CacheDisable http://security.update.server/update-list/
 </IfModule>

CacheDefaultExpire ディレクティブ

説明: | 期日が指定されていないときにドキュメントをキャッシュするデフォルトの期間
構文: | CacheDefaultExpire seconds
デフォルト: | CacheDefaultExpire 3600 (1時間)
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

CacheDefaultExpire ディレクティブは、ドキュメントに 有効期限 (expiry) や最終修正時刻 (last-modified) が指定されていない場合の デフォルトの時間を指定します。CacheMaxExpire ディレクティブで指定された値はこの設定を上書きしません。

CacheDefaultExpire 86400

CacheDisable ディレクティブ

説明: | 特定の URL をキャッシュしない
構文: | CacheDisable url-string
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

CacheDisable ディレクティブで mod_cache モジュールが url-string 以下の URL をキャッシュしないようにします。

例

CacheDisable /local_files

CacheEnable ディレクティブ

説明: | 指定したストレージ管理方式を使ってのキャッシュを有効にする
構文: | CacheEnable cache_type url-string
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

CacheEnable ディレクティブで mod_cache モジュールが url-string 以下の URL をキャッシュするようにします。 キャッシュストレージ管理方式は cache_type 引数で指定します。 cache_type mem で、 mod_mem_cache で実装されているメモリを使ったストレージ 管理方式を使うように mod_cache に指示します。 cache_type disk で、 mod_disk_cache で実装されているディスクを使ったストレージ 管理を使うように mod_cache に指示します。 cache_type fd は mod_cache に mod_mem_cache により実装されているファイル記述子の キャッシュを使うように指示します。

(下の例のように) CacheEnable ディレクティブの URL 空間が重複しているときは、該当するストレージ方式を順に試して、 実際にリクエストの処理ができると、その方式で処理します。 ストレージ管理方式が実行される順番は設定ファイル中の CacheEnable の順番により決定されます。

CacheEnable mem /manual
CacheEnable fd /images
CacheEnable disk /

フォワードプロクシサーバとして動作させる場合は、 url-string でリモートサイトとプロクシするプロトコルを 指定して、何に対してキャッシュを有効にするか指定することもできます。

# Cache proxied url's
CacheEnable disk /

# Cache FTP-proxied url's
CacheEnable disk ftp://

# Cache content from www.apache.org
CacheEnable disk http://www.apache.org/

CacheIgnoreCacheControl ディレクティブ

説明: | キャッシュされているコンテンツを返さないようにクライアントから リクエストされても無視する
構文: | CacheIgnoreCacheControl On|Off
デフォルト: | CacheIgnoreCacheControl Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

Cache-Control: no-cache ヘッダや Pragma: no-store ヘッダのあるリクエストに 対しては、通常キャッシュを使いません。CacheIgnoreCacheControl ディレクティブを使うと、この動作を上書きできます。 CacheIgnoreCacheControl On とすると、 リクエストに no-cache という値があっても、キャッシュを使ってドキュメントを 返すようになります。認証を必要とするドキュメントは決して キャッシュされません。

CacheIgnoreCacheControl On

警告

このディレクティブを使うと、ドキュメント取得時にキャッシュを使わないように クライアントがリクエストしているにもかかわらず、キャッシュを 使うようになります。その結果、 古いコンテンツが送られ続けることになってしまうかもしれません。

参照

  • CacheStorePrivate
  • CacheStoreNoStore

CacheIgnoreHeaders ディレクティブ

説明: | 指定された HTTP ヘッダをキャッシュに保存しない。
構文: | CacheIgnoreHeaders header-string [header-string] ...
デフォルト: | CacheIgnoreHeaders None
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

RFC 2616 によると、hop-by-hop HTTP ヘッダはキャッシュには保管されません。 以下のヘッダは hop-by-hop ヘッダに該当しますので、 CacheIgnoreHeaders の設定に関係なくキャッシュには保管されません:

  • Connection
  • Keep-Alive
  • Proxy-Authenticate
  • Proxy-Authorization
  • TE
  • Trailers
  • Transfer-Encoding
  • Upgrade

CacheIgnoreHeaders で キャッシュに保管しない追加の HTTP ヘッダを指定します。 例えば、クッキーをキャッシュに保管しないようにした方がよい場合も あるでしょう。

CacheIgnoreHeaders の引数は、 キャッシュに保管しない HTTP ヘッダを空白区切りにしたリスト形式です。 キャッシュに保管しないヘッダが hop-by-hop ヘッダだけの場合 (RFC 2616 準拠の動作のとき) は、 CacheIgnoreHeaders を None に設定できます。

例 1

CacheIgnoreHeaders Set-Cookie

例 2

CacheIgnoreHeaders None

警告:

Expires のような適切のキャッシュ管理のために必要な ヘッダが CacheIgnoreHeaders の設定により 保管されていないときは、mod_cache の動作は定義されていません。

CacheIgnoreNoLastMod ディレクティブ

説明: | 応答に Last Modified が無くても気にしないようにする
構文: | CacheIgnoreNoLastMod On|Off
デフォルト: | CacheIgnoreNoLastMod Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

通常、Last-Modified による最終修正時刻の無いドキュメントはキャッシュ されません。(例えば mod_include による処理のときなどに) Last-Modified 時刻が消去されたり、そもそも最初から提供されていない 状況があります。CacheIgnoreNoLastMod ディレクティブを使うと、Last-Modified 日時が指定されていない ドキュメントでもキャッシュするように指定できます。ドキュメントに 最終修正時刻 (Last-Modified) 有効期限 (expiry) がない場合は、有効期限の 生成に CacheDefaultExpire が使われます。

CacheIgnoreNoLastMod On

CacheIgnoreQueryString ディレクティブ

説明: | Ignore query string when caching
構文: | CacheIgnoreQueryString On|Off
デフォルト: | CacheIgnoreQueryString Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache
互換性: | Available in Apache 2.2.6 and later

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

CacheIgnoreURLSessionIdentifiers ディレクティブ

説明: | Ignore defined session identifiers encoded in the URL when caching
構文: | CacheIgnoreURLSessionIdentifiers identifier [identifier] ...
デフォルト: | CacheIgnoreURLSessionIdentifiers None
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

CacheLastModifiedFactor ディレクティブ

説明: | LastModified の日付に基づいて有効期限 (expiry) を計算するための重みを指定する
構文: | CacheLastModifiedFactor float
デフォルト: | CacheLastModifiedFactor 0.1
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

ドキュメントに Last-Modified の日付が無いけれども有効期限 (expiry) の日付があるというときに、有効期限を最終修正時刻からの経過時間として 計算するようにできます。有効期限を次の計算式に従って生成するのですが、 そのときに使われる factor を CacheLastModifiedFactor ディレクティブで指定します。

expiry-period = time-since-last-modified-date * factor expiry-date = current-date + expiry-period

例えば、ドキュメントが 10 時間前に最後に修正されていて、 factor が 0.1 であれば、期日は 10*0.1 = 1 時間に 設定されます。現在時刻が 3:00pm であれば、計算された期日は 3:00pm + 1hour = 4:00pm になります。

期日が CacheMaxExpire で設定されている値 より大きくなってしまっている場合は、CacheMaxExpire の設定値が優先されます。

CacheLastModifiedFactor 0.5

CacheLock ディレクティブ

説明: | Enable the thundering herd lock.
構文: | CacheLock on|off
デフォルト: | CacheLock off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache
互換性: | Available in Apache 2.2.15 and later

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

CacheLockMaxAge ディレクティブ

説明: | Set the maximum possible age of a cache lock.
構文: | CacheLockMaxAge integer
デフォルト: | CacheLockMaxAge 5
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

CacheLockPath ディレクティブ

説明: | Set the lock path directory.
構文: | CacheLockPath directory
デフォルト: | CacheLockPath /tmp/mod_cache-lock
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

CacheMaxExpire ディレクティブ

説明: | ドキュメントをキャッシュする最大時間を秒数で表したもの
構文: | CacheMaxExpire seconds
デフォルト: | CacheMaxExpire 86400 (一日)
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

CacheMaxExpire ディレクティブは、 キャッシュする HTTP ドキュメントを、元のサーバに問い合わせないまま最大何秒 保持してもよいかを指定します。つまり、ドキュメントは最大でこの秒数間ぶん古く なることになります。この最大値は、(訳注:レスポンス中で)ドキュメントと共に ドキュメントの期日が提供されている場合でも適用されます。

CacheMaxExpire 604800

CacheStoreNoStore ディレクティブ

説明: | no-store と指定されているレスポンスのキャッシュを試みる。
構文: | CacheStoreNoStore On|Off
デフォルト: | CacheStoreNoStore Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

通常 Cache-Control: no-store ヘッダのついているレスポンスは キャッシュされません。CacheStoreNoCache ディレクティブでこの挙動を上書きできます。 CacheStoreNoCache On で no-store ヘッダのついている リソースに対してもキャッシュを試みるようになります。 ただし認証の求められるリソースは 決して キャッシュされません。

CacheStoreNoStore On

警告:

RFC 2616 に記載されているように no-store ディレクティブは、 "不注意による機密情報の漏洩や残留 (バックアップテープ等) を防ぐ" 目的で使われますが、このオプションを有効にすると、 機密情報を保持することになってしまいます。 ですので、ここで警告しておきます。

参照

  • CacheIgnoreCacheControl
  • CacheStorePrivate

CacheStorePrivate ディレクティブ

説明: | private と指定されているレスポンスのキャッシュを試みる。
構文: | CacheStorePrivate On|Off
デフォルト: | CacheStorePrivate Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_cache

通常 Cache-Control: private ヘッダのついているレスポンスは キャッシュされません。CacheStorePrivate ディレクティブでこの挙動を上書きできます。 CacheStorePrivate On で private ヘッダのついている リソースに対してもキャッシュを試みるようになります。 ただし認証の求められるリソースは 決して キャッシュされません。

CacheStorePrivate On

警告:

上流サーバがキャッシュしないように指定してきても、 それを無視してキャッシュするようになります。 望ましい挙動になるのは、本当に 'private' なキャッシュについてのみでしょう。

参照

  • CacheIgnoreCacheControl
  • CacheStoreNoStore


mod_cern_meta - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_cern_meta

Description: | CERN httpd metafile semantics
Status: | Extension
Module Identifier: | cern_meta_module
Source File: | 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

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_cgi - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_cgi

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | CGI スクリプトの実行
ステータス: | Base
モジュール識別子: | cgi_module
ソースファイル: | mod_cgi.c

概要

ハンドラ cgi-script が指定されているファイルは CGI スクリプトとして扱われ、 サーバにより実行され、その出力がクライアントに返されます。 ファイルは、AddHandler ディレクティブに指定された 拡張子を名前に含むか、 ScriptAlias ディレクトリに存在することによりこのハンドラになります。

Apache で CGI スクリプトを使用するためのイントロダクションは、 CGI による動的コンテンツ を参照してください。

Unix でマルチスレッドの MPM を使っている場合は、このモジュールの 代わりに mod_cgid を使う必要があります。 ユーザレベルではこの二つのモジュールは本質的には同一です。

後方互換性のため、MIME タイプがapplication/x-httpd-cgi のファイルにも CGI スクリプトのハンドラが有効になります。 この独自 MIME タイプの利用は非推奨です。

参照

  • 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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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 で実行する

CGIDScriptTimeout ディレクティブ

説明: | The length of time to wait for more output from the CGI program
構文: | CGIDScriptTimeout time[s|ms]
デフォルト: | value of Timeout directive when unset
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
ステータス: | Base
モジュール: | mod_cgid
互換性: | CGIDScriptTimeout defaults to zero in releases 2.4 and earlier

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

ScriptSock ディレクティブ

説明: | CGI デーモンとの通信に使われるソケットのファイル名の接頭辞
構文: | ScriptSock file-path
デフォルト: | ScriptSock logs/cgisock
コンテキスト: | サーバ設定ファイル
ステータス: | Base
モジュール: | mod_cgid

このディレクティブは CGI デーモンとの通信に使われるソケットの ファイル名の接頭辞を設定します。また、ファイル名にはサーバのプロセスIDが 追加されます。ソケットは Apache が起動されたユーザ (通常 root) の パーミッションを用いてオープンされます。CGI スクリプトとの通信の セキュリティを保つために、ソケットの存在するディレクトリに 他のユーザが書き込み権限を持っていないようにすることが重要です。

例

ScriptSock /var/run/cgid.sock

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


mod_charset_lite - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_charset_lite

Description: | Specify character set translation or recoding
Status: | Extension
Module Identifier: | charset_lite_module
Source File: | mod_charset_lite.c

Summary

mod_charset_lite allows the server to change the character set of responses before sending them to the client. In an EBCDIC environment, Apache always translates HTTP protocol content (e.g. response headers) from the code page of the Apache process locale to ISO-8859-1, but not the body of responses. In any environment, mod_charset_lite can be used to specify that response bodies should be translated. For example, if files are stored in EBCDIC, then mod_charset_lite can translate them to ISO-8859-1 before sending them to the client.

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: | Extension
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: | Extension
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.
TranslateAllMimeTypes | NoTranslateAllMimeTypes
Normally, mod_charset_lite will only perform translation on a small subset of possible mimetypes. When the TranslateAllMimeTypes keyword is specified for a given configuration section, translation is performed without regard for mimetype.

CharsetSourceEnc Directive

Description: | Source charset of files
Syntax: | CharsetSourceEnc charset
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_dav - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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>
Order Allow,Deny
Allow from all
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>

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


mod_dav_fs - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


mod_dav_lock - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_dav_lock

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | mod_dav 用の汎用ロックモジュール
ステータス: | Extension
モジュール識別子: | dav_lock_module
ソースファイル: | mod_dav_lock.c
互換性: | バージョン 2.1 以降

概要

このモジュールは mod_dav のどのバックエンド からでも使える汎用ロック API を提供します。 使用には最低限 mod_dav を必要としますが、これを利用するバックエンドが存在しないと役に立たないので、 そのような場合はサーバに読み込むべきではありません。 mod_dav_lock を実際に利用するバックエンドモジュールの例としては subversion プロバイダモジュールの mod_dav_svn があります。

mod_dav_fs は特化された専用のバージョンを 使うため、この汎用モジュールは必要ないことに注意して ください。

mod_dav_lock を機能させるには、 以下で説明されている DavGenericLockDB を使って ロックデータベースの場所を指定するだけです。

開発者向けのメモ

ロックを提供している関数へのポインタを取得するためには、 ap_lookup_provider API を、引数 dav-lock, generic, 0 を指定して使う必要が あります。

参照

  • mod_dav

DavGenericLockDB ディレクティブ

説明: | DAV ロックデータベースの場所
構文: | DavGenericLockDB file-path
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_dav_lock

DavGenericLockDB ディレクティブを 使って、拡張子を除いたロックデータベースへのフルパスを 指定します。絶対パスでないときは ServerRoot からの相対パスとして 扱われます。mod_dav_lock の実装ではユーザの ロックを追跡するのに SDBM データベースを使います。

例

DavGenericLockDB var/DavLock

ロックデータベースファイルのあるディレクトリは Apache が実行されている User と Group によって 書き込み可能でなければなりません。セキュリティ上の理由から、 既存のディレクトリのパーミッションを変更するのではなく、 専用のディレクトリを作るのが良いでしょう。上の例では、 Apache は ServerRoot の下の var/ ディレクトリに、ファイル名の本体が DavLock で サーバが選択した拡張子を持つファイルを作成します。


mod_dbd - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_dbd

Description: | Manages SQL database connections
Status: | Extension
Module Identifier: | dbd_module
Source File: | mod_dbd.c
Compatibility: | Version 2.1 and later

Summary

mod_dbd manages SQL database connections using APR. It provides database connections on request to modules requiring SQL database functions, and takes care of managing databases with optimal efficiency and scalability for both threaded and non-threaded MPMs. For details, see the APR website and this overview of the Apache DBD Framework by its original developer.

See also

  • Password Formats

Connection Pooling

This module manages database connections, in a manner optimised for the platform. On non-threaded platforms, it provides a persistent connection in the manner of classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python). On threaded platform, it provides an altogether more scalable and efficient connection pool, as described in this article at ApacheTutor. Note that mod_dbd supersedes the modules presented in that article.

Apache DBD API

mod_dbd exports five functions for other modules to use. The API is as follows:

typedef struct {
    apr_dbd_t *handle;
    apr_dbd_driver_t *driver;
    apr_hash_t *prepared;
} ap_dbd_t;

/* Export functions to access the database */

/* acquire a connection that MUST be explicitly closed.
 * Returns NULL on error
 */
AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);

/* release a connection acquired with ap_dbd_open */
AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);

/* acquire a connection that will have the lifetime of a request
 * and MUST NOT be explicitly closed.  Return NULL on error.
 * This is the preferred function for most applications.
 */
AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);

/* acquire a connection that will have the lifetime of a connection
 * and MUST NOT be explicitly closed.  Return NULL on error.
 */
AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*);

/* Prepare a statement for use by a client module */
AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);

/* Also export them as optional functions for modules that prefer it */
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));

SQL Prepared Statements

mod_dbd supports SQL prepared statements on behalf of modules that may wish to use them. Each prepared statement must be assigned a name (label), and they are stored in a hash: the prepared field of an ap_dbd_t. Hash entries are of type apr_dbd_prepared_t and can be used in any of the apr_dbd prepared statement SQL query or select commands.

It is up to dbd user modules to use the prepared statements and document what statements can be specified in httpd.conf, or to provide their own directives and use ap_dbd_prepare.

Caveat

When using prepared statements with a MySQL database, it is preferred to set reconnect to 0 in the connection string as to avoid errors that arise from the MySQL client reconnecting without properly resetting the prepared statements. If set to 1, any broken connections will be attempted fixed, but as mod_dbd is not informed, the prepared statements will be invalidated.

SECURITY WARNING

Any web/database application needs to secure itself against SQL injection attacks. In most cases, Apache DBD is safe, because applications use prepared statements, and untrusted inputs are only ever used as data. Of course, if you use it via third-party modules, you should ascertain what precautions they may require.

However, the FreeTDS driver is inherently unsafe. The underlying library doesn't support prepared statements, so the driver emulates them, and the untrusted input is merged into the SQL statement.

It can be made safe by untainting all inputs: a process inspired by Perl's taint checking. Each input is matched against a regexp, and only the match is used, according to the Perl idiom:

  $untrusted =~ /([a-z]+)/;
  $trusted = $1;

To use this, the untainting regexps must be included in the prepared statements configured. The regexp follows immediately after the % in the prepared statement, and is enclosed in curly brackets {}. For example, if your application expects alphanumeric input, you can use:

"SELECT foo FROM bar WHERE input = %s"

with other drivers, and suffer nothing worse than a failed query. But with FreeTDS you'd need:

"SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s"

Now anything that doesn't match the regexp's $1 match is discarded, so the statement is safe.

An alternative to this may be the third-party ODBC driver, which offers the security of genuine prepared statements.

DBDExptime Directive

Description: | Keepalive time for idle connections
Syntax: | DBDExptime time-in-seconds
Default: | DBDExptime 300
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

Set the time to keep idle connections alive when the number of connections specified in DBDKeep has been exceeded (threaded platforms only).

DBDKeep Directive

Description: | Maximum sustained number of connections
Syntax: | DBDKeep number
Default: | DBDKeep 2
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

Set the maximum number of connections per process to be sustained, other than for handling peak demand (threaded platforms only).

DBDMax Directive

Description: | Maximum number of connections
Syntax: | DBDMax number
Default: | DBDMax 10
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

Set the hard maximum number of connections per process (threaded platforms only).

DBDMin Directive

Description: | Minimum number of connections
Syntax: | DBDMin number
Default: | DBDMin 1
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

Set the minimum number of connections per process (threaded platforms only).

DBDParams Directive

Description: | Parameters for database connection
Syntax: | DBDParams param1=value1[,param2=value2]
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

As required by the underlying driver. Typically this will be used to pass whatever cannot be defaulted amongst username, password, database name, hostname and port number for connection.

Connection string parameters for current drivers include:

FreeTDS (for MSSQL and SyBase - see SECURITY note)
username, password, appname, dbname, host, charset, lang, server
MySQL
host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect
ODBC
datasource, user, password, connect, ctimeout, stimeout, access, txmode, bufsize
Oracle
user, pass, dbname, server
PostgreSQL
The connection string is passed straight through to PQconnectdb
SQLite2
The connection string is split on a colon, and part1:part2 is used as sqlite_open(part1, atoi(part2), NULL)
SQLite3
The connection string is passed straight through to sqlite3_open

DBDPersist Directive

Description: | Whether to use persistent connections
Syntax: | DBDPersist On|Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

If set to Off, persistent and pooled connections are disabled. A new database connection is opened when requested by a client, and closed immediately on release. This option is for debugging and low-usage servers.

The default is to enable a pool of persistent connections (or a single LAMP-style persistent connection in the case of a non-threaded server), and should almost always be used in operation.

Prior to version 2.2.2, this directive accepted only the values 0 and 1 instead of Off and On, respectively.

DBDPrepareSQL Directive

Description: | Define an SQL prepared statement
Syntax: | DBDPrepareSQL "SQL statement" label
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

For modules such as authentication that repeatedly use a single SQL statement, optimum performance is achieved by preparing the statement at startup rather than every time it is used. This directive prepares an SQL statement and assigns it a label.

DBDriver Directive

Description: | Specify an SQL driver
Syntax: | DBDriver name
Context: | server config, virtual host
Status: | Extension
Module: | mod_dbd

Selects an apr_dbd driver by name. The driver must be installed on your system (on most systems, it will be a shared object or dll). For example, DBDriver mysql will select the MySQL driver in apr_dbd_mysql.so.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_deflate - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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
# 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 フィルタは内部的なサブリクエストを関知しません。

注

SetEnv で設定される force-gzip 環境変数がありますが、これは ブラウザの accept-encoding 設定を無視し、圧縮した出力をします。

出力の伸長

mod_deflate モジュールは、gzip 圧縮されたレスポンス 本文を inflate/uncompress するフィルタも提供しています。 この機能を有効にするには、SetOutputFilter や AddOutputFilter を使って、 INFLATE フィルタを出力フィルタチェインに挿入します。 例えば次のようにします。

<Location /dav-area>
ProxyPass http://example.com/
SetOutputFilter INFLATE
 </Location>

この例では、example.com からの gzip 圧縮された出力を伸長し、 その他のフィルタがさらにその出力を処理できるようにします。

入力の伸張

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

DeflateInflateLimitRequestBody ディレクティブ

説明: | Maximum size of inflated request bodies
構文: | DeflateInflateLimitRequestBodyvalue
デフォルト: | None, but LimitRequestBody applies after deflation
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
ステータス: | Extension
モジュール: | mod_deflate
互換性: | 2.2.28 and later

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

DeflateInflateRatioBurst ディレクティブ

説明: | Maximum number of times the inflation ratio for request bodies can be crossed
構文: | DeflateInflateRatioBurst value
デフォルト: | 3
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
ステータス: | Extension
モジュール: | mod_deflate
互換性: | 2.2.28 and later

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

DeflateInflateRatioLimit ディレクティブ

説明: | Maximum inflation ratio for request bodies
構文: | DeflateInflateRatioLimit value
デフォルト: | 200
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
ステータス: | Extension
モジュール: | mod_deflate
互換性: | 2.2.28 and later

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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 ファイルが返されます。しかしスラッシュのないリクエストに対しては、 ディレクトリの内容一覧を返してしまいます。

FallbackResource ディレクティブ

説明: | Define a default URL for requests that don't map to a file
構文: | FallbackResource disabled | local-url
デフォルト: | None - httpd will return 404 (Not Found)
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Indexes
ステータス: | Base
モジュール: | mod_dir
互換性: | Apache HTTP Server 2.2.16 and later - The disabled argument is supported since 2.2.24

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。


mod_disk_cache - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_disk_cache

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | URI をキーにしたコンテンツキャッシュストレージ管理
ステータス: | Extension
モジュール識別子: | disk_cache_module
ソースファイル: | mod_disk_cache.c

概要

mod_disk_cache はディスクを使用したストレージ 管理機構を実装しています。主に mod_cache と組み合わせて使われます。

コンテンツのキャッシュへの保存と取得は URI に基づいたキーが使われます。 アクセス保護のかけられているコンテンツはキャッシュされません。

キャッシュの大きさを最大レベルで維持するために htcacheclean を使うことができます。

注:

mod_disk_cache は mod_cache を必要とします

CacheDirLength ディレクティブ

説明: | サブディレクトリ名の文字数
構文: | CacheDirLength length
デフォルト: | CacheDirLength 2
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_disk_cache

CacheDirLength ディレクティブはキャッシュ 階層の各サブディレクトリの文字数を設定します。

CacheDirLevels* CacheDirLength の 結果は 20 以内でなければなりません。

CacheDirLength 4

CacheDirLevels ディレクティブ

説明: | キャッシュのサブディレクトリの深さの数
構文: | CacheDirLevels levels
デフォルト: | CacheDirLevels 3
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_disk_cache

CacheDirLevels ディレクティブはキャッシュの サブディレクトリの深さを設定します。キャッシュデータは CacheRoot ディレクトリから このディレクトリの深さ分下のディレクトリに保存されます。

CacheDirLevels* CacheDirLength の 結果は 20 以内でなければなりません。

CacheDirLevels 5

CacheMaxFileSize ディレクティブ

説明: | キャッシュに保管されるドキュメントの最大の (バイトでの) サイズ
構文: | CacheMaxFileSize bytes
デフォルト: | CacheMaxFileSize 1000000
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_disk_cache

CacheMaxFileSize ディレクティブは、ドキュメントを キャッシュするかどうかを判定する、最大のサイズをバイト数で設定します。

CacheMaxFileSize 64000

CacheMinFileSize ディレクティブ

説明: | キャッシュに保管されるドキュメントの最小限の (バイトでの) 大きさ
構文: | CacheMinFileSize bytes
デフォルト: | CacheMinFileSize 1
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_disk_cache

CacheMinFileSize ディレクティブは、ドキュメントを キャッシュするかどうかを判定する、最小のサイズをバイト数で設定します。

CacheMinFileSize 64

CacheRoot ディレクティブ

説明: | キャッシュファイルが保管されるルートディレクトリ
構文: | CacheRoot directory
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_disk_cache

CacheRoot ディレクティブはキャッシュファイルを 保管するためのディスク上のディレクトリを指定します。mod_disk_cache モジュールが Apache サーバにロードされて いるか、組み込まれていれば、このディレクティブは必ず 定義しなければなりません。 CacheRoot の値を指定しなければ、 設定ファイルの処理でエラーになります。CacheDirLevels ディレクティブと CacheDirLength ディレクティブが 指定されたルートディレクトリ下のディレクトリ構成を定義します。

CacheRoot c:/cacheroot

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


mod_dumpio - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_dumpio

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | 望むようにすべての I/O をエラーログにダンプする
ステータス: | Extension
モジュール識別子: | dumpio_module
ソースファイル: | mod_dumpio.c

概要

mod_dumpio を使うと、Apache が受け取ったすべての入力と Apache により送られたすべての出力との、両方もしくはどちらか一方を、 エラーログファイルにログ収集 (訳注: ダンプ dump) できます。

データのロギングは、SSL 復号化の直後 (入力) と SSL 暗号化の直前 (出力) に行なわれます。ご想像の通り、 このモジュールはとてつもないデータ量を出力しますので、 問題をデバッグしているときにのみ使用するようにしてください。

dumpio サポートを有効にする

このモジュールを有効にするには、モジュールがコンパイルされていて、 実行する Apache の設定でサーバに組み込まれている必要があります。 ロギング機能は、以下のディレクティブを使って有効にしたり 無効にしたりできます。

DumpIOInput ディレクティブ

説明: | エラーログにすべての入力データをダンプ
構文: | DumpIOInput On|Off
デフォルト: | DumpIOInput Off
コンテキスト: | サーバ設定ファイル
ステータス: | Extension
モジュール: | mod_dumpio
互換性: | DumpIOInput は Apache 2.1.3 以降のみで使用可能

すべての入力のダンプを有効にします。

例

DumpIOInput On

DumpIOLogLevel ディレクティブ

説明: | Controls the logging level of the DumpIO output
構文: | DumpIOLogLevel level
デフォルト: | DumpIOLogLevel debug
コンテキスト: | サーバ設定ファイル
ステータス: | Extension
モジュール: | mod_dumpio
互換性: | DumpIOLogLevel is only available in Apache 2.2.4 and later.

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

DumpIOOutput ディレクティブ

説明: | エラーログにすべての出力データをダンプ
構文: | DumpIOOutput On|Off
デフォルト: | DumpIOOutput Off
コンテキスト: | サーバ設定ファイル
ステータス: | Extension
モジュール: | mod_dumpio
互換性: | DumpIOOutput は Apache 2.1.3 以降でのみ使用可能

すべての出力のダンプを有効にします。

例

DumpIOOutput On

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


mod_echo - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_echo

説明: | プロトコルモジュールの概要を示すための単純なエコーサーバ
ステータス: | Experimental
モジュール識別子: | echo_module
ソースファイル: | mod_echo.c
互換性: | Apache 2.0 以降

概要

本モジュールはコンセプトを伝えるためのプロトコルモジュールの 実装例となっています。単純なエコーサーバを提供します。 Telnet で接続し、文字列を送信すると、エコーを返します。

ProtocolEcho ディレクティブ

説明: | エコーサーバの有効無効を設定します。
構文: | ProtocolEcho On|Off
デフォルト: | ProtocolEcho Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Experimental
モジュール: | mod_echo
互換性: | Apache 2.0 以降で使用可能

ProtocolEcho ディレクティブで エコーサーバの有効無効を設定します。

例

ProtocolEcho On

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


mod_env - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


mod_example - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_example

Description: | Illustrates the Apache module API
Status: | Experimental
Module Identifier: | example_module
Source File: | mod_example.c

Summary

Some files in the modules/experimental 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. Run configure with --enable-example option.
  2. Make the server (run "make").

To add another module of your own:

  1. cp modules/experimental/mod_example.c modules/new_module/mod_myexample.c
  2. Modify the file.
  3. Create modules/new_module/config.m4.
    1. Add APACHE_MODPATH_INIT(new_module).
    2. Copy APACHE_MODULE line with "example" from modules/experimental/config.m4.
    3. Replace the first argument "example" with myexample.
    4. Replace the second argument with brief description of your module. It will be used in configure --help.
    5. If your module needs additional C compiler flags, linker flags or libraries, add them to CFLAGS, LDFLAGS and LIBS accordingly. See other config.m4 files in modules directory for examples.
    6. Add APACHE_MODPATH_FINISH.
  4. Create module/new_module/Makefile.in. If your module doesn't need special build instructions, all you need to have in that file is include $(top_srcdir)/build/special.mk.
  5. Run ./buildconf from the top-level directory.
  6. Build the server with --enable-myexample

Using the mod_example Module

To activate the example module, include a block similar to the following in your httpd.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".

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_expires - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_ext_filter

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | レスポンスのボディをクライアントに送る前に外部プログラムで処理する
ステータス: | Extension
モジュール識別子: | ext_filter_module
ソースファイル: | mod_ext_filter.c

概要

mod_ext_filter では フィルタ の慣れ親しんだ単純なプログラミングモデルが提供されます。このモジュールを 使えば、標準入力から読み込んで、標準出力に書き出すプログラム (すなわち Unix 形式のフィルタコマンド) を Apache のフィルタにすることが できます。このフィルタの機構は、Apache API 向けに書かれた Apache サーバプロセス内で実行される専用のフィルタよりもずっと遅いですが、 以下のような利点もあります。

  • ずっとシンプルなプログラミングモデル
  • プログラムが標準入力から読んで標準出力に書くものである限り、 どんなプログラム言語やスクリプト言語でも使うことができる
  • 既存のプログラムを変更することなく Apache のフィルタとして 使うことができる

性能の問題により実運用に適さないとしても、フィルタのプロトタイプ用の 環境としては mod_ext_filter は使えます。

参照

  • フィルタ

例

他のタイプのレスポンスから HTML を生成する

# 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>

コンテントエンコーディングのフィルタを実装する

注: この gzip の例はデモ用です。実用的な実装は mod_deflate を参照してください。

# 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>

サーバを遅くする

# 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>

sed を使って応答中のテキストを置換する

# 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>

別のフィルタのトレース

# 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>

データをトレースするフィルタ:

#!/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 ディレクティブ

説明: | 外部フィルタを定義
構文: | ExtFilterDefine filtername parameters
コンテキスト: | サーバ設定ファイル
ステータス: | Extension
モジュール: | mod_ext_filter

ExtFilterDefine は、実行するプログラムや 引数など、外部フィルタの特性を定義します。

filtername は定義するフィルタの名前を指定します。 この名前は後で SetOutputFilter ディレクティブで指定できます。名前は登録されるすべてのフィルタで 一意でなくてはなりません。現時点では、フィルタの登録 API からは エラーは報告されません。ですから、重複する名前を使ってしまったときでも ユーザにはそのことは報告されません。

続くパラメータの順番は関係無く、それらは実行する外部コマンドと、 他の特性を定義します。cmd= だけが必須のパラメータです。 指定可能なパラメータは:

cmd=cmdline
cmd= キーワードは実行する外部コマンドを指定します。 プログラム名の後に引数がある場合は、コマンド行は引用符で囲む 必要があります (例えば、cmd="/bin/mypgm arg1 arg2" のように)。プログラムは シェル経由でなく、直接実行されますので、通常のシェル用の エスケープは必要ありません。プログラムの引数は空白で区切られます。 プログラムの引数の一部となる必要のある空白はバックスペースでエスケープ できます。引数の一部になるバックスラッシュはバックスラッシュで エスケープする必要があります。標準の CGI 環境変数に加えて、 環境変数 DOCUMENT_URI, DOCUMENT_PATH_INFO, and QUERY_STRING_UNESCAPED がプログラムのために設定されます。
mode=mode
応答を処理するフィルタには mode=output (デフォルト) を使います。リクエストを処理するフィルタには mode=input を使います。mode=input は Apache 2.1 以降で使用できます。
intype=imt
このパラメータはフィルタされるべきドキュメントの インターネットメディアタイプ (すなわち、MIME タイプ) を 指定します。デフォルトではすべてのドキュメントがフィルタされます。 intype= が指定されていれば、フィルタは指定されていない ドキュメントには適用されなくなります。
outtype=imt
このパラメータはフィルタされたドキュメントの インターネットメディアタイプ (すなわち、MIME タイプ) を 指定します。フィルタ動作にともなってインターネットメディアタイプが 変わる場合に有用です。デフォルトではインターネットメディアタイプは 変更されません。
PreservesContentLength
PreservesContentLength キーワードはフィルタが content length (訳注: コンテントの長さ) を変更しないということを指定します。ほとんどのフィルタは content length を変更するため、これはデフォルトではありません。 フィルタが長さを変えないときは、このキーワードを指定すると よいでしょう。
ftype=filtertype
このパラメータはフィルタが登録されるべきフィルタタイプの 数値を指定します。ほとんどの場合は、デフォルトの AP_FTYPE_RESOURCE で 十分です。フィルタがフィルタチェーンの別の場所で動作する必要がある 場合は、このパラメータを指定する必要があります。指定可能な値は util_filter.h の AP_FTYPE_foo 定義を参照してください。
disableenv=env
設定されていた場合にフィルタを無効にするための環境変数を 指定します。
enableenv=env
このパラメータはフィルタが有効になるために設定されていなければ ならない環境変数を指定します。

ExtFilterOptions ディレクティブ

説明: | mod_ext_filter のオプションを設定
構文: | ExtFilterOptions option [option] ...
デフォルト: | ExtFilterOptions DebugLevel=0 NoLogStderr
コンテキスト: | ディレクトリ
ステータス: | Extension
モジュール: | mod_ext_filter

ExtFilterOptions ディレクティブは mod_ext_filter の特別な処理用のオプションを 指定します。Option には以下のどれかを指定します。

DebugLevel=n
DebugLevel で mod_ext_filter の生成するデバッグメッセージのレベルを設定できます。 デフォルトでは、デバッグメッセージは生成されません。 これは DebugLevel=0 と設定するのと同じです。 数字が大きくなればなるほど、より多くのデバッグメッセージが 生成され、サーバの性能は落ちます。数値の実際の意味は mod_ext_filter.c の先頭近くの DBGLVL_ 定数の 定義で説明されています。

注: デバッグメッセージを Apache のエラーログに 保存するようにするためには、core のディレクティブ LogLevel を使う必要があります。

LogStderr | NoLogStderr
LogStderr キーワードは外部フィルタプログラムにより 標準エラー (訳注: stderr) に書かれたメッセージを Apache のエラーログに保存するようにします。NoLogStderr は 逆に保存しないようにします。

例

ExtFilterOptions LogStderr DebugLevel=0

この例では、フィルタの標準出力に書かれたメッセージは Apache のエラーログに保存されます。mod_ext_filter からは デバッグメッセージは生成されません。


mod_file_cache - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_file_cache

Description: | Caches a static list of files in memory
Status: | Experimental
Module Identifier: | file_cache_module
Source File: | 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. 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 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

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_filter - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_filter

Description: | Context-sensitive smart filter configuration module
Status: | Base
Module Identifier: | filter_module
Source File: | mod_filter.c
Compatibility: | Version 2.1 and later

Summary

This module enables smart, context-sensitive configuration of output content filters. For example, apache can be configured to process different content-types through different filters, even when the content-type is not known in advance (e.g. in a proxy).

mod_filter works by introducing indirection into the filter chain. Instead of inserting filters in the chain, we insert a filter harness which in turn dispatches conditionally to a filter provider. Any content filter may be used as a provider to mod_filter; no change to existing filter modules is required (although it may be possible to simplify them).

Smart Filtering

In the traditional filtering model, filters are inserted unconditionally using AddOutputFilter and family. Each filter then needs to determine whether to run, and there is little flexibility available for server admins to allow the chain to be configured dynamically.

mod_filter by contrast gives server administrators a great deal of flexibility in configuring the filter chain. In fact, filters can be inserted based on any Request Header, Response Header or Environment Variable. This generalises the limited flexibility offered by AddOutputFilterByType, and fixes it to work correctly with dynamic content, regardless of the content generator. The ability to dispatch based on Environment Variables offers the full flexibility of configuration with mod_rewrite to anyone who needs it.

Filter Declarations, Providers and Chains

[This image displays the traditional filter model]
Figure 1: The traditional filter model

In the traditional model, output filters are a simple chain from the content generator (handler) to the client. This works well provided the filter chain can be correctly configured, but presents problems when the filters need to be configured dynamically based on the outcome of the handler.

[This image shows the mod_filter model]
Figure 2: The mod_filter model

mod_filter works by introducing indirection into the filter chain. Instead of inserting filters in the chain, we insert a filter harness which in turn dispatches conditionally to a filter provider. Any content filter may be used as a provider to mod_filter; no change to existing filter modules is required (although it may be possible to simplify them). There can be multiple providers for one filter, but no more than one provider will run for any single request.

A filter chain comprises any number of instances of the filter harness, each of which may have any number of providers. A special case is that of a single provider with unconditional dispatch: this is equivalent to inserting the provider filter directly into the chain.

Configuring the Chain

There are three stages to configuring a filter chain with mod_filter. For details of the directives, see below.

Declare Filters
The FilterDeclare directive declares a filter, assigning it a name and filter type. Required only if the filter is not the default type AP_FTYPE_RESOURCE.
Register Providers
The FilterProvider directive registers a provider with a filter. The filter may have been declared with FilterDeclare; if not, FilterProvider will implicitly declare it with the default type AP_FTYPE_RESOURCE. The provider must have been registered with ap_register_output_filter by some module. The remaining arguments to FilterProvider are a dispatch criterion and a match string. The former may be an HTTP request or response header, an environment variable, or the Handler used by this request. The latter is matched to it for each request, to determine whether this provider will be used to implement the filter for this request.
Configure the Chain
The above directives build components of a smart filter chain, but do not configure it to run. The FilterChain directive builds a filter chain from smart filters declared, offering the flexibility to insert filters at the beginning or end of the chain, remove a filter, or clear the chain.

Filtering and Response Status

mod_filter normally only runs filters on responses with HTTP status 200 (OK). If you want to filter documents with other response statuses, you can set the filter-errordocs environment variable, and it will work on all responses regardless of status. To refine this further, you can use expression conditions with FilterProvider.

Examples

Server side Includes (SSI)
A simple case of using mod_filter in place of AddOutputFilterByType

FilterDeclare SSI
FilterProvider SSI INCLUDES resp=Content-Type $text/html
FilterChain SSI

Server side Includes (SSI)
The same as the above but dispatching on handler (classic SSI behaviour; .shtml files get processed).

FilterProvider SSI INCLUDES Handler server-parsed
FilterChain SSI

Emulating mod_gzip with mod_deflate
Insert INFLATE filter only if "gzip" is NOT in the Accept-Encoding header. This filter runs with ftype CONTENT_SET.

FilterDeclare gzip CONTENT_SET
FilterProvider gzip inflate req=Accept-Encoding !$gzip
FilterChain gzip

Image Downsampling
Suppose we want to downsample all web images, and have filters for GIF, JPEG and PNG.

FilterProvider unpack jpeg_unpack Content-Type $image/jpeg
FilterProvider unpack gif_unpack Content-Type $image/gif
FilterProvider unpack png_unpack Content-Type $image/png

FilterProvider downsample downsample_filter Content-Type $image
FilterProtocol downsample "change=yes"

FilterProvider repack jpeg_pack Content-Type $image/jpeg
FilterProvider repack gif_pack Content-Type $image/gif
FilterProvider repack png_pack Content-Type $image/png
<Location /image-filter>
FilterChain unpack downsample repack
 </Location>

Protocol Handling

Historically, each filter is responsible for ensuring that whatever changes it makes are correctly represented in the HTTP response headers, and that it does not run when it would make an illegal change. This imposes a burden on filter authors to re-implement some common functionality in every filter:

  • Many filters will change the content, invalidating existing content tags, checksums, hashes, and lengths.
  • Filters that require an entire, unbroken response in input need to ensure they don't get byteranges from a backend.
  • Filters that transform output in a filter need to ensure they don't violate a Cache-Control: no-transform header from the backend.
  • Filters may make responses uncacheable.

mod_filter aims to offer generic handling of these details of filter implementation, reducing the complexity required of content filter modules. This is work-in-progress; the FilterProtocol implements some of this functionality for back-compatibility with Apache 2.0 modules. For httpd 2.1 and later, the ap_register_output_filter_protocol and ap_filter_protocol API enables filter modules to declare their own behaviour.

At the same time, mod_filter should not interfere with a filter that wants to handle all aspects of the protocol. By default (i.e. in the absence of any FilterProtocol directives), mod_filter will leave the headers untouched.

At the time of writing, this feature is largely untested, as modules in common use are designed to work with 2.0. Modules using it should test it carefully.

FilterChain Directive

Description: | Configure the filter chain
Syntax: | FilterChain [+=-@!]filter-name ...
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Base
Module: | mod_filter

This configures an actual filter chain, from declared filters. FilterChain takes any number of arguments, each optionally preceded with a single-character control that determines what to do:

+filter-name
Add filter-name to the end of the filter chain
@filter-name
Insert filter-name at the start of the filter chain
-filter-name
Remove filter-name from the filter chain
=filter-name
Empty the filter chain and insert filter-name
!
Empty the filter chain
filter-name
Equivalent to +filter-name

FilterDeclare Directive

Description: | Declare a smart filter
Syntax: | FilterDeclare filter-name [type]
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Base
Module: | mod_filter

This directive declares an output filter together with a header or environment variable that will determine runtime configuration. The first argument is a filter-name for use in FilterProvider, FilterChain and FilterProtocol directives.

The final (optional) argument is the type of filter, and takes values of ap_filter_type - namely RESOURCE (the default), CONTENT_SET, PROTOCOL, TRANSCODE, CONNECTION or NETWORK.

FilterProtocol Directive

Description: | Deal with correct HTTP protocol handling
Syntax: | FilterProtocol filter-name [provider-name] proto-flags
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Base
Module: | mod_filter

This directs mod_filter to deal with ensuring the filter doesn't run when it shouldn't, and that the HTTP response headers are correctly set taking into account the effects of the filter.

There are two forms of this directive. With three arguments, it applies specifically to a filter-name and a provider-name for that filter. With two arguments it applies to a filter-name whenever the filter runs any provider.

proto-flags is one or more of

change=yes
The filter changes the content, including possibly the content length
change=1:1
The filter changes the content, but will not change the content length
byteranges=no
The filter cannot work on byteranges and requires complete input
proxy=no
The filter should not run in a proxy context
proxy=transform
The filter transforms the response in a manner incompatible with the HTTP Cache-Control: no-transform header.
cache=no
The filter renders the output uncacheable (eg by introducing randomised content changes)

FilterProvider Directive

Description: | Register a content filter
Syntax: | FilterProvider filter-name provider-name [req|resp|env]=dispatch match
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Base
Module: | mod_filter

This directive registers a provider for the smart filter. The provider will be called if and only if the match declared here matches the value of the header or environment variable declared as dispatch.

provider-name must have been registered by loading a module that registers the name with ap_register_output_filter.

The dispatch argument is a string with optional req=, resp= or env= prefix causing it to dispatch on (respectively) the request header, response header, or environment variable named. In the absence of a prefix, it defaults to a response header. A special case is the word handler, which causes mod_filter to dispatch on the content handler.

The match argument specifies a match that will be applied to the filter's dispatch criterion. The match may be a string match (exact match or substring), a regex, an integer (greater, lessthan or equals), or unconditional. The first characters of the match argument determines this:

First, if the first character is an exclamation mark (!), this reverses the rule, so the provider will be used if and only if the match fails.

Second, it interprets the first character excluding any leading ! as follows:

Character | Description
(none) | exact match
$ | substring match
/ | regex match (delimited by a second /)
= | integer equality
< | integer less-than
<= | integer less-than or equal
> | integer greater-than
>= | integer greater-than or equal
* | Unconditional match

FilterTrace Directive

Description: | Get debug/diagnostic information from mod_filter
Syntax: | FilterTrace filter-name level
Context: | server config, virtual host, directory
Status: | Base
Module: | mod_filter

This directive generates debug information from mod_filter. It is designed to help test and debug providers (filter modules), although it may also help with mod_filter itself.

The debug output depends on the level set:

0 (default)
No debug information is generated.
1
mod_filter will record buckets and brigades passing through the filter to the error log, before the provider has processed them. This is similar to the information generated by mod_diagnostics.
2 (not yet implemented)
Will dump the full data passing through to a tempfile before the provider. For single-user debug only; this will not support concurrent hits.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_headers - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_headers

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | HTTP リクエストのヘッダと応答のヘッダのカスタマイズ
ステータス: | Extension
モジュール識別子: | headers_module
ソースファイル: | mod_headers.c

概要

このモジュールは HTTP のリクエストヘッダと応答ヘッダを制御し、 変更するためのディレクティブを提供します。ヘッダを追加したり、 置き換えたり、削除したりすることができます。

処理の順番

mod_header のディレクティブはサーバ設定のほぼどこにでも 書くことができ、影響する範囲を設定用セクションで囲むことで限定する ことができます。

処理の順番は重要で、設定ファイル中の順番と、設定用セクション内の位置との両方に 影響されます。以下の二つのヘッダは順番が逆になると 違う結果になります:

RequestHeader append MirrorID "mirror 12"
RequestHeader unset MirrorID

この順番の場合は、MirrorID ヘッダは設定されません。 逆になっていると、MirrorID ヘッダは "mirror 12" に設定されます。

早期処理、後期処理

mod_headers では、リクエストの早期か後期かの どちらで適用するかを選べます。通常は後期モードで、 コンテンツ生成が実行される直前にリクエストヘッダがセットされ、 レスポンスとして送出される直前にレスポンスヘッダがセットされます。 運用中のサーバでは必ず後期モードを使ってください。

早期モードは開発者向けのテスト/デバッグ用に設計されています。 early キーワード指定されたディレクティブによって、 リクエスト処理の開始地点になります。 つまり、異なるリクエストを試したりテストケースをセットアップするのに 活用できる一方で、レスポンスを生成する前に他のモジュールによって ヘッダが書き換えられてしまうかもしれないということを意味します。

early ディレクティブではリクエストパスの設定が解決される前に 処理されるので、メインサーバかバーチャルホストコンテキストでのみ、 早期ヘッダをセットできます。early ディレクティブはリクエストパスに 依存することはできませんので、<Directory> や <Location> といったコンテキスト内では使用 できません。

例

  1. リクエストヘッダ中の "TS" で始まるフィールドをすべて応答ヘッダに コピーします:

    Header echo ^TS

  2. リクエストを受け付けた時刻とリクエストを処理した時間を入れたヘッダ、 MyHeader を応答に追加します。このヘッダはクライアントが サーバの負荷を直観的に知るためや、クライアント-サーバ間の ボトルネックを調べるために使うことができます。

    Header add MyHeader "%D %t"

    上記の設定では、以下のようなヘッダが応答に追加されることになります:

    MyHeader: D=3775428 t=991424704447256

  3. Joe にあいさつをします:

    Header add MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."

    以下のようなヘッダが応答に追加されることになります

    MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.

  4. リクエストに "MyRequestHeader" があるときに限り MyHeader を応答に 付けます。これは、クライアントの要求に応えてヘッダを作成するときに 役に立ちます。この例では mod_setenvif モジュールが必要なことに 注意してください。

    SetEnvIf MyRequestHeader value HAVE_MyRequestHeader
    Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader

    もし HTTP リクエストに MyRequestHeader: value ヘッダが あると、応答には以下のようなヘッダが付加されます。

    MyHeader: D=3775428 t=991424704447256 mytext

Header ディレクティブ

説明: | HTTP 応答ヘッダの設定
構文: | Header [condition] set|append|add|unset|echo header [value] [early|env=[!]variable]
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Extension
モジュール: | mod_headers

このディレクティブは HTTP 応答ヘッダを置換、追加、削除できます。 ヘッダはコンテントハンドラや出力フィルタが実行された直後に実行され、 出て行くヘッダを変更できるようになっています。

オプションの condition は onsuccess か always のどちらかを指定できます。これは内部ヘッダテーブルのどれを 操作するかを決定します。onsuccess は 2xx ステータスコードの、always は全てのステータスコード (2xx を含む) の意味になります。 あるモジュールでセットされるヘッダをアンセットしたい場合は特に、 どのテーブルが影響を受けるかを実際に試したほうがよいでしょう。

行なう処理は二番目のの引数で決まります。 この引数には次の値を指定できます:

set
応答ヘッダを設定します。同じ名前のヘッダが存在する場合はそれを 置き換えます。value にはフォーマット文字列を 指定することもできます。
append
応答ヘッダを既に存在する同じ名前のヘッダに追加します。 新しい値が既存のヘッダに追加されるときには、既存のヘッダの 後にコンマで区切られて追加されます。これはヘッダに複数の値を 指定するときの HTTP の標準の方法です。
add
ヘッダが既に存在しているときでさえも、応答ヘッダを 既存のヘッダに追加します。これにより、二つ (かそれ以上) の ヘッダの名前が同じになることがあります。その結果、想定できない ことが起こる可能性がありますので、一般的には append の方を 使う方が良いでしょう。
unset
もし指定された名前の応答ヘッダが存在していれば、削除されます。 同じ名前のヘッダが複数あるときは、すべて削除されます。 value をつけてはいけません。
echo
指定されたものと同じ名前のリクエストヘッダを応答ヘッダで そのまま返します。header には正規表現も指定できます。 value をつけてはいけません。

この引数の後にはヘッダ名 (header) が続きます。 ヘッダ名には最後にコロンを含めることもできますが、無くても構いません。 set, append, add, unset では大文字小文字は 区別されません。echo の header 名は大文字小文字を区別し、 正規表現を指定することもできます。

add, append, set では value を三つ目の 引数として指定します。value に空白がある場合は二重引用符で 囲む必要があります。value は文字のみからなる文字列、 フォーマット指示子を含む文字列、もしくは両方からなる文字列を指定できます。 value は以下のフォーマット指示子をサポートします:

フォーマット | 解説
%% | パーセント記号
%t | リクエストを受け取った時刻を、 Universal Coordinated Time での始まりの時刻 (Jan. 1, 1970) から経過した 時間をマイクロ秒として表したもの。値の最初には t= が付加されます。
%D | リクエストを受け取った時刻と、ヘッダを送り出した 時間との差。これは、リクエストが存在していた期間を表します。 値の最初には D= が付加されます。
%{FOOBAR}e | 環境変数 FOOBAR の値です。
%{FOOBAR}s | mod_ssl が有効な場合、 SSL 環境変数 FOOBAR の内容

注

%s フォーマット指定子は 2.1 以降でのみ利用できます。 SSLOptions +StdEnvVars を有効にすることによるオーバーヘッドを 避けるため、%e の代わりとして使えます。 他の理由などがあって、どうしても SSLOptions +StdEnvVars を有効にしなければならない場合は、%e のほうが %s よりも処理効率は良いです。

Header ディレクティブには追加の引数を持たせることが できて、どういったアクションが行われたかの条件を指定したり、 早期処理 を指定する early キーワードを 指定できます。 env=... 引数で指定された 環境変数 が存在する (もしくは env=!... が指定されていて環境変数が存在しない) 場合は、Header ディレクティブで指定された動作が行なわれます。そうでない場合は、 ディレクティブはそのリクエストには何もしません。

早期処理モードの場合以外では、 Header ディレクティブは応答がネットワークに送られる直前に 処理されます。これは、ヘッダフィルタにより追加されるヘッダを 除き、ほとんどのヘッダを設定したり上書きしたりすることが 可能、ということです。

RequestHeader ディレクティブ

説明: | HTTP リクエストヘッダの設定
構文: | RequestHeader set|append|add|unset header [value] [early|env=[!]variable]
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Extension
モジュール: | mod_headers

このディレクティブは HTTP リクエストヘッダを置換、追加、削除できます。 ヘッダはコンテントハンドラが実行される直前に実行され、 入って来るヘッダを変更することが可能になっています。 行なう処理は第 1 引数により決まります。これには以下の値を指定 することができます:

set
リクエストヘッダを設定します。同じ名前のヘッダが存在していると、 それを置き換えます。
append
リクエストヘッダは、既に存在する同じ名前のヘッダに追加されます。 新しい値が既存のヘッダに追加されるときには、既存のヘッダの 後にコンマで区切られて追加されます。これはヘッダに複数の値を 指定するときの HTTP の標準の方法です。
add
ヘッダが既に存在しているときでさえも、リクエストヘッダを 既存のヘッダに追加します。これにより、二つ (かそれ以上) の ヘッダの名前が同じになることがあります。その結果、想定できない ことが起こる可能性がありますので、一般的には append の方を 使う方が良いでしょう。
unset
もし指定された名前のリクエストヘッダが存在していれば、削除されます。 同じ名前の複数のヘッダがあるときは、すべて削除されます。 value をつけてはいけません。

この引数の後にはヘッダ名 (header) が続きます。 ヘッダ名には最後にコロンを含めることもできますが、無くても構いません。 大文字小文字は区別されません。add, append, set の場合は、value が三つ目の 引数として指定されます。value に空白がある場合は二重引用符で 囲む必要があります。unset の場合は、value は指定しません。 value は文字列、フォーマット指定子、あるいは、その混合です。 使うことのできるフォーマット指定子は、Header と同じですので、 詳細はそちらをご覧ください。

RequestHeader ディレクティブは、 どういった条件下でアクションを行うかを指定する追加引数 あるいは、早期処理 を指定する early キーワードを設定することができます。 env=... の引数で設定されている 環境変数 が存在している (あるいは env=!... で指定された環境変数が 存在しない) 場合、RequestHeader ディレクティブは 有効になります。それ以外の場合、ディレクティブは効力を持ちません。

early モードでない場合に限り、 RequestHeader ディレクティブは fixup フェーズでリクエストがハンドラに扱われる直前に 処理されます。これにより、ブラウザや Apache の入力フィルタにより 生成されたヘッダを上書きしたり修正したりできるようになっています。


mod_ident - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_ident

説明: | RFC 1413 ident lookups
ステータス: | Extension
モジュール識別子: | ident_module
ソースファイル: | mod_ident.c
互換性: | Apache 2.1 で使用可能

概要

このモジュールはリモートホストの RFC 1413 互換デーモン にコネクションの所有者を訊きます。

参照

  • mod_log_config

IdentityCheck ディレクティブ

説明: | リモートユーザの RFC 1413 によるアイデンティティのロギングを 有効にする
構文: | IdentityCheck On|Off
デフォルト: | IdentityCheck Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_ident
互換性: | Apache 2.1 で core から移動

このディレクティブは、クライアントマシン上で identd やそれに類似したデーモンが動作しているときに、 それぞれの接続に対して RFC 1413 に準処したリモートユーザの 名前のロギングを行なうようにします。 この情報は、%...l フォーマット文字列を使ってアクセスログに収集されます。

ここで得られた情報は簡単なユーザ追跡に使う以外は、 まったく信頼するべきではありません。

すべてのリクエストに対してルックアップが行なわれますので、 深刻な遅延の問題を起こすかもしれないことに注意してください。 (訳注: 例えばクライアント側に) ファイアウォールやプロキシサーバがあると、 ルックアップが失敗し、各リクエストに IdentityCheckTimeoutで定義されている遅延が加わることに なる可能性があります。 従って、一般的にはインターネットからアクセス可能なパブリックなサーバで 有益なものではありません。

IdentityCheckTimeout ディレクティブ

説明: | Ident リクエストがタイムアウトするまでの期間を決める
構文: | IdentityCheckTimeout seconds
デフォルト: | IdentityCheckTimeout 30
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_ident

このディレクティブは ident リクエストのタイムアウト時間を決めます。 デフォルトの値である 30 秒は、主にネットワーク遅延の考慮のために RFC 1413 により 推奨されています。しかし、おそらくローカルネットワークの速度に 合わせてタイムアウト値を調節するのがよいでしょう。


mod_imagemap - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_imagemap

Description: | Server-side imagemap processing
Status: | Base
Module Identifier: | imagemap_module
Source File: | mod_imagemap.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 be 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 be 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://example.com/">Menu text</a>

If no quoted text is present, the name of the link will be used as the text:

<a href="http://example.com/">http://example.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.example.com/lincoln/feedback/ 195,0 305,27
rect another_file "in same directory as referer" 306,0 419,27
point http://www.zyzzyva.example.com/ 100,100
point http://www.tripod.example.com/ 200,200
rect mailto:nate@tripod.example.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_imagemap

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_imagemap

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_imagemap

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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_include - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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 になります)。

詳しい情報は 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 要素

次のコマンドは解析の様々な側面を制御します。属性は次の通りです。

echomsg (Apache 2.1 以降)
指定される値は、echo 要素が未定義の変数をエコーしようとした際に、 クライアントに送られるメッセージになります。 SSIUndefinedEcho ディレクティブを上書きします。
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 がサーバに組み込まれているいなければ なりません。Options IncludesNOEXEC はこのコマンドを無効にします。 使用可能な属性は次の通りです。

cgi

値は (%-エンコードされた) URL を指定します。パスが スラッシュ (/) で始まらないときは、ドキュメントからの 相対パスとして扱われます。このパスで参照されているドキュメントは サーバが CGI スクリプトとして扱っていなくても CGI スクリプトとして 起動されます。ただし、スクリプトのあるディレクトリでは (ScriptAlias や Options 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 要素

このコマンドは別の文書やファイルのテキストを解析しているファイルに 挿入します。挿入されるファイルはアクセス制御の管理下にあります。 解析しているファイルの存在するディレクトリに Options 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 になります。

真偽値表現の最適化

式がもっと複雑になり、処理の速度低下が顕著になった場合は、 評価ルールに従って最適化してみると良いでしょう。

  • 評価は左から右に向かって行われます。
  • 二値真偽値オペレータ (&& と ||) は、出来る限り短絡評価されます。つまり結果として上記のルールは、 mod_include が左の評価式を評価します。 左側で結果を十分決定できる場合は、評価はそこで停止します。 そうでない場合は右側を評価して、左と右の両方から結果を計算します。
  • 短絡評価は評価の対象に正規表現が含まれる場合、オフになります。 後方参照する変数 ($1 .. $9) を埋めるために、実際に評価する必要があるからです。

特定の式がどのように扱われるかを知りたい場合は、 -DDEBUG_INCLUDE コンパイラオプションを付けて mod_include をリコンパイルすると良いでしょう。 これにより、全てのパースされた式に対して、字句解析情報、 パースツリーと、 それがどのようにクライアントに送られた出力まで評価されたかを 挿入します。

SSIEnableAccess ディレクティブ

説明: | Enable the -A flag during conditional flow control processing.
構文: | SSIEnableAccess on|off
デフォルト: | SSIEnableAccess off
コンテキスト: | ディレクトリ, .htaccess
ステータス: | Base
モジュール: | mod_include

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

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 -->"

SSIETag ディレクティブ

説明: | Controls whether ETags are generated by the server.
構文: | SSIETag on|off
デフォルト: | SSIETag off
コンテキスト: | ディレクトリ, .htaccess
ステータス: | Base
モジュール: | mod_include
互換性: | Available in version 2.2.15 and later.

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

SSILastModified ディレクティブ

説明: | Controls whether Last-Modified headers are generated by the server.
構文: | SSILastModified on|off
デフォルト: | SSILastModified off
コンテキスト: | ディレクトリ, .htaccess
ステータス: | Base
モジュール: | mod_include
互換性: | Available in version 2.2.15 and later.

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

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)"
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | 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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_info

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | サーバの設定の包括的な概観を提供する
ステータス: | Extension
モジュール識別子: | info_module
ソースファイル: | mod_info.c

概要

mod_info を設定するには、以下を httpd.conf ファイルに加えます。

<Location /server-info>
SetHandler server-info
 </Location>

<Location> の中で mod_access を使って、サーバ設定情報への アクセスを制限したいと思うかもしれません :

<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from yourcompany.com
 </Location>

一旦設定すると、http://your.host.example.com/server-info にアクセスすることでサーバの情報を得られるようになります。

Security Issues

一旦 mod_info がサーバに読み込まれると、 提供しているハンドラ機能はディレクトリ毎の設定ファイル (例えば .htaccess) を含む すべての設定ファイルで有効になります。 このモジュールを有効にするときはセキュリティの問題を考慮する必要が あるでしょう。

特に、このモジュールはシステムパス、ユーザ名/パスワード、 データベース名など、他の Apache モジュールの設定ディレクティブから セキュリティ上微妙な情報を漏らす可能性があります。 ですから、このモジュールはきちんとアクセス制御された環境でのみ、 注意して使ってください。

設定情報へのアクセスを制限するために、mod_authz_host を 使うのが良いでしょう。

アクセス制御

<Location /server-info>
SetHandler server-info
Order allow,deny
# Allow access from server itself
Allow from 127.0.0.1
# Additionally, allow access from local workstation
Allow from 192.168.1.17
 </Location>

表示される情報の選択

デフォルトでは、サーバ情報はすべての有効なモジュールと、 各モジュールについて、モジュールが理解するディレクティブ、 実装している、フック、現時点での設定の関連するディレクティブに なっています。

server-info リクエストへクエリーを追加することで、 設定情報の他の表示形式を選ぶことができます。例えば、 http://your.host.example.com/server-info?config は すべての設定ディレクティブを表示します。

?<module-name>
指定されたモジュールに関連する情報のみ
?config
モジュールでソートせずに、設定ディレクティブのみ
?hooks
各モジュールが使用するフックのみ
?list
有効なモジュールの簡単なリストのみ
?server
基本サーバ情報のみ

既知の制限

mod_info は、元の設定ファイルを読むのではなく、 既にパースされた設定を読み込むことで情報を提供します。従って、 パース済みの設定情報の木が生成される方法による制限がいくつかあります:

  • パースされた設定に保存されずに、すぐに実行されるディレクティブは 一覧に現れません。これには ServerRoot, LoadModule, LoadFile があります。
  • Include, <IfModule>, <IfDefine>, のような設定ファイル自身を制御するディレクティブは表示されません。 そのディレクティブの中にあり、有効になっているディレクティブは 表示されます。
  • コメントは表示されません。(これは仕様だと思ってください。)
  • .htaccess ファイルの設定ディレクティブは表示されません (永久的なサーバ設定の一部ではないからです)。
  • <Directory> のようなコンテナディレクティブは普通に表示されますが、 mod_info は閉じタグの </Directory> などの数を知ることはできません。
  • mod_perl のようなサードパーティモジュール のディレクティブは表示されないかもしれません。

AddModuleInfo ディレクティブ

説明: | server-info ハンドラにより表示されるモジュールの情報に 追加の情報を付け加える
構文: | AddModuleInfo module-name string
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_info
互換性: | Apache 1.3 以降

これは、string の内容がモジュール module-name の追加情報 として HTML として解釈され、表示されるようにします。例:

AddModuleInfo mod_deflate.c 'See <a \
href="http://www.apache.org/docs/2.2/mod/mod_deflate.html">\
http://www.apache.org/docs/2.2/mod/mod_deflate.html</a>'


mod_isapi - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_isapi

Description: | ISAPI Extensions within Apache for Windows
Status: | Base
Module Identifier: | isapi_module
Source File: | 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-handler 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-handler .dll

In older versions of the Apache server, isapi-isa was the proper handler name, rather than isapi-handler. For compatibility, configurations may continue using isapi-isa through all versions of Apache prior to 2.3.0.

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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_ldap - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_ldap

Description: | LDAP connection pooling and result caching services for use by other LDAP modules
Status: | Extension
Module Identifier: | ldap_module
Source File: | 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/TLS support is dependent on which LDAP toolkit has been linked to APR. As of this writing, APR-util supports: OpenLDAP SDK (2.x or later), Novell LDAP SDK, Mozilla LDAP SDK, native Solaris LDAP SDK (Mozilla based), native Microsoft LDAP SDK, or the iPlanet (Netscape) SDK. See the APR website for details.

Example Configuration

The following is an example configuration that uses mod_ldap to increase the performance of HTTP Basic authentication provided by mod_authnz_ldap.

# Enable the LDAP connection pool and shared
# memory cache. Enable the LDAP cache status
# handler. Requires that mod_ldap and mod_authnz_ldap
# be loaded. Change the "yourdomain.example.com" to
# match your domain.

LDAPSharedCacheSize 500000
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
AuthLDAPURL ldap://127.0.0.1/dc=example,dc=com?uid?one
AuthzLDAPAuthoritative off
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_authnz_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/TLS

The ability to create an SSL and TLS connections to an LDAP server is defined by the directives LDAPTrustedGlobalCert, LDAPTrustedClientCert and LDAPTrustedMode. These directives specify the CA and optional client certificates to be used, as well as the type of encryption to be used on the connection (none, SSL or TLS/STARTTLS).

# Establish an SSL LDAP connection on port 636. Requires that
# mod_ldap and mod_authnz_ldap be loaded. Change the
# "yourdomain.example.com" to match your domain.

LDAPTrustedGlobalCert CA_DER /certs/certfile.der

<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one
AuthzLDAPAuthoritative off
Require valid-user
 </Location>

# Establish a TLS LDAP connection on port 389. Requires that
# mod_ldap and mod_authnz_ldap be loaded. Change the
# "yourdomain.example.com" to match your domain.

LDAPTrustedGlobalCert CA_DER /certs/certfile.der

<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
AuthLDAPURL ldap://127.0.0.1/dc=example,dc=com?uid?one TLS
AuthzLDAPAuthoritative off
Require valid-user
 </Location>

SSL/TLS Certificates

The different LDAP SDKs have widely different methods of setting and handling both CA and client side certificates.

If you intend to use SSL or TLS, read this section CAREFULLY so as to understand the differences between configurations on the different LDAP toolkits supported.

Netscape/Mozilla/iPlanet SDK

CA certificates are specified within a file called cert7.db. The SDK will not talk to any LDAP server whose certificate was not signed by a CA specified in this file. If client certificates are required, an optional key3.db file may be specified with an optional password. The secmod file can be specified if required. These files are in the same format as used by the Netscape Communicator or Mozilla web browsers. The easiest way to obtain these files is to grab them from your browser installation.

Client certificates are specified per connection using the LDAPTrustedClientCert directive by referring to the certificate "nickname". An optional password may be specified to unlock the certificate's private key.

The SDK supports SSL only. An attempt to use STARTTLS will cause an error when an attempt is made to contact the LDAP server at runtime.

# Specify a Netscape CA certificate file
LDAPTrustedGlobalCert CA_CERT7_DB /certs/cert7.db
# Specify an optional key3.db file for client certificate support
LDAPTrustedGlobalCert CERT_KEY3_DB /certs/key3.db
# Specify the secmod file if required
LDAPTrustedGlobalCert CA_SECMOD /certs/secmod
<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
LDAPTrustedClientCert CERT_NICKNAME <nickname> [password]
AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one
AuthzLDAPAuthoritative off
Require valid-user
 </Location>

Novell SDK

One or more CA certificates must be specified for the Novell SDK to work correctly. These certificates can be specified as binary DER or Base64 (PEM) encoded files.

Note: Client certificates are specified globally rather than per connection, and so must be specified with the LDAPTrustedGlobalCert directive as below. Trying to set client certificates via the LDAPTrustedClientCert directive will cause an error to be logged when an attempt is made to connect to the LDAP server..

The SDK supports both SSL and STARTTLS, set using the LDAPTrustedMode parameter. If an ldaps:// URL is specified, SSL mode is forced, override this directive.

# Specify two CA certificate files
LDAPTrustedGlobalCert CA_DER /certs/cacert1.der
LDAPTrustedGlobalCert CA_BASE64 /certs/cacert2.pem
# Specify a client certificate file and key
LDAPTrustedGlobalCert CERT_BASE64 /certs/cert1.pem
LDAPTrustedGlobalCert KEY_BASE64 /certs/key1.pem [password]
# Do not use this directive, as it will throw an error
#LDAPTrustedClientCert CERT_BASE64 /certs/cert1.pem

OpenLDAP SDK

One or more CA certificates must be specified for the OpenLDAP SDK to work correctly. These certificates can be specified as binary DER or Base64 (PEM) encoded files.

Client certificates are specified per connection using the LDAPTrustedClientCert directive.

The documentation for the SDK claims to support both SSL and STARTTLS, however STARTTLS does not seem to work on all versions of the SDK. The SSL/TLS mode can be set using the LDAPTrustedMode parameter. If an ldaps:// URL is specified, SSL mode is forced. The OpenLDAP documentation notes that SSL (ldaps://) support has been deprecated to be replaced with TLS, although the SSL functionality still works.

# Specify two CA certificate files
LDAPTrustedGlobalCert CA_DER /certs/cacert1.der
LDAPTrustedGlobalCert CA_BASE64 /certs/cacert2.pem
<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
LDAPTrustedClientCert CERT_BASE64 /certs/cert1.pem
LDAPTrustedClientCert KEY_BASE64 /certs/key1.pem
AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one
AuthzLDAPAuthoritative off
Require valid-user
 </Location>

Solaris SDK

SSL/TLS for the native Solaris LDAP libraries is not yet supported. If required, install and use the OpenLDAP libraries instead.

Microsoft SDK

SSL/TLS certificate configuration for the native Microsoft LDAP libraries is done inside the system registry, and no configuration directives are required.

Both SSL and TLS are supported by using the ldaps:// URL format, or by using the LDAPTrustedMode directive accordingly.

Note: The status of support for client certificates is not yet known for this toolkit.

LDAPCacheEntries Directive

Description: | Maximum number of entries in the primary LDAP cache
Syntax: | LDAPCacheEntries number
Default: | LDAPCacheEntries 1024
Context: | server config
Status: | Extension
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: | Extension
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).

LDAPConnectionTimeout Directive

Description: | Specifies the socket connection timeout in seconds
Syntax: | LDAPConnectionTimeout seconds
Context: | server config
Status: | Extension
Module: | mod_ldap

This directive configures the LDAP_OPT_NETWORK_TIMEOUT option in the underlying LDAP client library, when available. This value typically controls how long the LDAP client library will wait for the TCP connection to the LDAP server to complete.

If a connection is not successful with the timeout period, either an error will be returned or the LDAP client library will attempt to connect to a secondary LDAP server if one is specified (via a space-separated list of hostnames in the AuthLDAPURL).

The default is 10 seconds, if the LDAP client library linked with the server supports the LDAP_OPT_NETWORK_TIMEOUT option.

LDAPConnectionTimeout is only available when the LDAP client library linked with the server supports the LDAP_OPT_NETWORK_TIMEOUT option, and the ultimate behavior is dictated entirely by the LDAP client library.

LDAPOpCacheEntries Directive

Description: | Number of entries used to cache LDAP compare operations
Syntax: | LDAPOpCacheEntries number
Default: | LDAPOpCacheEntries 1024
Context: | server config
Status: | Extension
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: | Extension
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: | Extension
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 500000
Context: | server config
Status: | Extension
Module: | mod_ldap

Specifies the number of bytes to allocate for the shared memory cache. The default is 500kb. If set to 0, shared memory caching will not be used.

LDAPTrustedClientCert Directive

Description: | Sets the file containing or nickname referring to a per connection client certificate. Not all LDAP toolkits support per connection client certificates.
Syntax: | LDAPTrustedClientCert type directory-path/filename/nickname [password]
Context: | server config, virtual host, directory, .htaccess
Status: | Extension
Module: | mod_ldap

It specifies the directory path, file name or nickname of a per connection client certificate used when establishing an SSL or TLS connection to an LDAP server. Different locations or directories may have their own independent client certificate settings. Some LDAP toolkits (notably Novell) do not support per connection client certificates, and will throw an error on LDAP server connection if you try to use this directive (Use the LDAPTrustedGlobalCert directive instead for Novell client certificates - See the SSL/TLS certificate guide above for details). The type specifies the kind of certificate parameter being set, depending on the LDAP toolkit being used. Supported types are:

  • CERT_DER - binary DER encoded client certificate
  • CERT_BASE64 - PEM encoded client certificate
  • CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)
  • KEY_DER - binary DER encoded private key
  • KEY_BASE64 - PEM encoded private key

LDAPTrustedGlobalCert Directive

Description: | Sets the file or database containing global trusted Certificate Authority or global client certificates
Syntax: | LDAPTrustedGlobalCert type directory-path/filename [password]
Context: | server config
Status: | Extension
Module: | mod_ldap

It specifies the directory path and file name of the trusted CA certificates and/or system wide client certificates mod_ldap should use when establishing an SSL or TLS connection to an LDAP server. Note that all certificate information specified using this directive is applied globally to the entire server installation. Some LDAP toolkits (notably Novell) require all client certificates to be set globally using this directive. Most other toolkits require clients certificates to be set per Directory or per Location using LDAPTrustedClientCert. If you get this wrong, an error may be logged when an attempt is made to contact the LDAP server, or the connection may silently fail (See the SSL/TLS certificate guide above for details). The type specifies the kind of certificate parameter being set, depending on the LDAP toolkit being used. Supported types are:

  • CA_DER - binary DER encoded CA certificate
  • CA_BASE64 - PEM encoded CA certificate
  • CA_CERT7_DB - Netscape cert7.db CA certificate database file
  • CA_SECMOD - Netscape secmod database file
  • CERT_DER - binary DER encoded client certificate
  • CERT_BASE64 - PEM encoded client certificate
  • CERT_KEY3_DB - Netscape key3.db client certificate database file
  • CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)
  • CERT_PFX - PKCS#12 encoded client certificate (Novell SDK)
  • KEY_DER - binary DER encoded private key
  • KEY_BASE64 - PEM encoded private key
  • KEY_PFX - PKCS#12 encoded private key (Novell SDK)

LDAPTrustedMode Directive

Description: | Specifies the SSL/TLS mode to be used when connecting to an LDAP server.
Syntax: | LDAPTrustedMode type
Context: | server config, virtual host
Status: | Extension
Module: | mod_ldap

The following modes are supported:

  • NONE - no encryption
  • SSL - ldaps:// encryption on default port 636
  • TLS - STARTTLS encryption on default port 389

Not all LDAP toolkits support all the above modes. An error message will be logged at runtime if a mode is not supported, and the connection to the LDAP server will fail.

If an ldaps:// URL is specified, the mode becomes SSL and the setting of LDAPTrustedMode is ignored.

LDAPVerifyServerCert Directive

Description: | Force server certificate verification
Syntax: | LDAPVerifyServerCert On|Off
Default: | LDAPVerifyServerCert On
Context: | server config
Status: | Extension
Module: | mod_ldap

Specifies whether to force the verification of a server certificate when establishing an SSL connection to the LDAP server.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_log_config - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_log_config

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | サーバへのリクエストのロギング
ステータス: | Base
モジュール識別子: | log_config_module
ソースファイル: | mod_log_config.c

概要

このモジュールはクライアントのリクエストを柔軟にログ収集する機能を 提供します。ログはカスタマイズ可能な書式で書かれ、ファイルに直接 書いたり、外部プログラムに渡したりすることができます。個々のリクエストを 特徴に応じてログに書いたり書かなかったりできるように、条件による ログ収集も提供されています。

このモジュールは三つのディレクティブ提供します: ログファイルを作成するための TransferLog, 新しい書式を 定義する LogFormat, ログファイルと 書式を一度に定義する CustomLog です。 各リクエストが複数回ログ収集されるようにするために TransferLog ディレクティブと CustomLog ディレクティブは複数回使用することができます。

参照

  • Apache ログファイル

カスタムログ書式

LogFormat ディレクティブと CustomLog ディレクティブの書式を指定する引数は文字列です。この文字列を使ってそれぞれの リクエストがログファイルにログ収集されます。その文字列には ログファイルにそのまま 書かれる文字列や、それぞれ改行とタブを表す C 言語 形式の制御文字 "\n" と "\t" とを含めることができます。そのまま出力させたい引用符とバックスラッシュは バックスラッシュでエスケープする必要があります。

リクエストの特徴そのものは "%" ディレクティブを書式の文字列に書くことで ログ収集されます。"%" ディレクティブはログファイル中では以下のような 値で置換されます:

フォーマット文字列 | 説明
%% パーセント記号
%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 からもし提供されていれば) リモートログ名。 これは mod_ident がサーバに存在して、 IdentityCheck ディレクティブが On に設定されていない限り、 - になります。
%m | リクエストメソッド
%{Foobar}n | 他のモジュールからのメモ Foobar の内容
%{Foobar}o | 応答の Foobar: ヘッダの内容
%p | リクエストを扱っているサーバの正式なポート
%P | リクエストを扱った子プロセスのプロセス ID
%{format}P | リクエストを扱ったワーカーのプロセス ID かスレッド ID。 format として有効な値は pid, tid, hextid です。hextid を使うには APR 1.2.0 以降が必要です。
%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 が必要

修飾子

特定の要素は "%" の直後に HTTP ステータスコードをカンマ区切りで 指定することで、表示を制限することができます。例えば "%400,501{User-agent}i" では、 400 と 500 番エラーでのみ User-agent をログします。 他のステータスコードでは "-" という文字列が ログされます。ステータスコードのリストは "!" で否定を指定することができます : "%!200,304,302{Referer}i" は、指定された 3 つのコードのどれにも該当しないリクエスト全てで Referer をログします。

修飾子 "<" と ">" は内部リダイレクトされたリクエストのログに 元のリクエストか最終的なリクエストのどちらを使用するかを 指定するために使います。デフォルトでは、% ディレクティブの %s, %U, %T, %D, %r は元のリクエストを、他は最終的なリクエストを 使用します。例えば、リクエストの最終ステータスを記録するには %>s を、内部的に認証されていないリソースへリダイレクトされた リクエストで元のリクエストで認証されたユーザを記録するためには %<u を使うことができます。

その他注意点

セキュリティ上の理由により 2.0.46 より、 %r, %i, %o に入っている、 印字不可能な文字と他の特別な文字は、\xhh という形式の文字列でエスケープされるようになりました。hh は そのままのバイトの値の 16 進での値です。この規則の例外には、 バックスラッシュを使ってエスケープされる " と \ と、 C 形式の表記法が使われる空白文字 (\n, \t など) があります。2.0.46 以前のバージョンではエスケープ処理は行われませんので、 生ログファイルを扱う際に注意が必要です。

httpd 2.0 では 1.3 とは異なり、%b と %B フォーマット文字列はクライアントに送信されたバイト数そのものではなく、 HTTP レスポンスのバイト数です (これらは異なるもので、たとえば、 コネクションが途中で破棄された場合や、SSL 使用時に一致しません) 。 mod_logio で提供されている %O フォーマット文字列で、ネットワーク経由で実際に転送されたバイト数を 記録できます。

例

よく使われるフォーマット文字列は:

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"

セキュリティに関して

ログファイルが保存されているディレクトリがサーバを起動した以外のユーザで 書き込み可能なときにセキュリティの問題が発生する理由の詳細はセキュリティのこつ を参照してください。

BufferedLogs ディレクティブ

説明: | ディスクに書き出す前にメモリにログエントリをバッファする
構文: | BufferedLogs On|Off
デフォルト: | BufferedLogs Off
コンテキスト: | サーバ設定ファイル
ステータス: | Base
モジュール: | mod_log_config
互換性: | 2.0.41 以降

BufferedLogs ディレクティブを使うと mod_log_config の挙動が変化して、 複数のログを書き出す際に、それぞれのリクエスト処理後毎に 書き出すのではなく、いったんメモリに蓄えてから、 まとめてディスクに書き出すようになります。 この結果ディスクアクセスがより効率的になり、 高いパフォーマンスの得られるシステムもあるでしょう。 このディレクティブはサーバ全体で一度だけ設定できます; バーチャルホストごとに設定することはできません。

このディレクティブは実験的なものですので、 使用する際は注意してください。

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

古い RefererIgnore ディレクティブと同じ挙動をさせたい場合は、 次のようにします:

SetEnvIf Referer example\.com localreferer
CustomLog referer.log referer env=!localreferer

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

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


mod_log_forensic - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_log_forensic

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | サーバに送られたリクエストの forensic ロギング
ステータス: | Extension
モジュール識別子: | log_forensic_module
ソースファイル: | mod_log_forensic.c
互換性: | mod_unique_id はバージョン 2.1 からは必須では なくなった

概要

このモジュールはクライアントリクエストの forensic ロギングを 行ないます。ログ収集はリクエストの処理の前と後に行なわれますので、 forensic ログは各リクエストに対して二行ログ収集します。 Forensic ロガーは非常に厳密です。これは以下のことを意味します:

  • フォーマットは固定です。実行時にロギングフォーマットを変更することは できません。
  • データを書けない場合は子プロセスはその場で終了し、さらにコアを ダンプするかもしれません (CoreDumpDirectory ディレクティブの設定に依ります)。

Forensic ログの出力を検査するためには、 配布物の support ディレクトリにある check_forensic スクリプトが役に立つでしょう。

参照

  • Apache ログファイル
  • mod_log_config

Forensic ログフォーマット

各リクエストは2回ログ収集されます。最初はリクエストが処理される 前 (つまり、ヘッダを受け取った後) です。2度目のログは リクエストが処理された後、通常のログ収集と同じときに 行なわれます。

各リクエストを識別するために、リクエストには 一意なリクエスト ID が割り当てられます。この forensic ID は フォーマット文字列 %{forensic-id}n を使うことで 通常の transfer ログにログ収集することもできます。 mod_unique_id を使っている場合は、それが生成する ID が使われます。

最初の行は forensic ID、リクエスト行と受け取ったすべてのヘッダを パイプ文字 (|) で分離してログ収集します。 例えば以下のようになります (実際はすべて同じ行になります):

+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...

最初のプラス文字がこのログは最初のログであることを示します。 二番目の行はマイナス文字と ID のみです:

-yQtJf8CoAB4AAFNXBIEAAAAA

check_forensic スクリプトは引数としてログファイルの名前を 取ります。+/- の ID の組を調べ、完了していない リクエストがある場合は警告を発します。

セキュリティの問題

ログファイルが保存されるディレクトリがサーバを起動したユーザ 以外で書き込み可能になっているときにセキュリティが破られる可能性が あることについての詳細はセキュリティのこつを 参照してください。

ForensicLog ディレクティブ

説明: | Forensic ログのファイル名を設定する
構文: | ForensicLog filename|pipe
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_log_forensic

ForensicLog ディレクティブは forensic 解析のための サーバへのリクエストをログ収集に使います。 各ログエントリには、普通の CustomLog ディレクティブを使ってリクエストと関連付けることの できる 一意な ID が割り当てられます。mod_log_forensic は forensic-id というトークンを作成し、フォーマット文字列 %{forensic-id}n を使うことでそのトークンを transfer ログに 追加することができます。

引数はログが書き出される位置を指定し、以下の 2種類の値のどちらかを 取ることができます:

filename
ServerRoot からの 相対ファイル名
pipe
パイプ文字 "|" と、その後にログ情報を標準入力から 受け取るプログラム。プログラム名は ServerRoot からの相対パスとしても 指定できます。

セキュリティ:

プログラムを使う場合、そのプログラムは httpd を起動したユーザで 実行されます。つまり、サーバが root で実行された場合は root で 実行されるということです。プログラムが安全であるか、より権限の少ない ユーザに切り替えるようになっていることを確かめてください。

注

Unix 以外のプラットフォームでファイル名を入力するときは、 プラットフォームがバックスラッシュの使用を許可している場合でも、 スラッシュのみが使われるように気をつけてください。 普通は設定ファイルすべてにおいて、スラッシュの方を使用するように してください。


mod_logio - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_mem_cache

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | URI をキーにしたコンテンツのキャッシュ
ステータス: | Extension
モジュール識別子: | mem_cache_module
ソースファイル: | mod_mem_cache.c

概要

このモジュールは mod_cache を必要とします。 これは mod_cache のサポートモジュールとして 動作し、メモリを使用したストレージ管理機構を提供します。 mod_mem_cache は二つのモードのどちらかで動作するように 設定できます: ファイル記述子のキャッシュかヒープ中のオブジェクトの キャッシュです。ローカルで生成されたコンテンツに対してキャッシュするときや、 mod_proxy を使って ProxyPass (つまりリバースプロキシ向け) に設定したときのバックエンドサーバのコンテンツに対して キャッシュをするときに、たいへん効果的です。

コンテンツのキャッシュへの保存と取得は URI に基づいたキーが使われます。 アクセス保護のかけられているコンテンツはキャッシュされません。

参照

  • mod_cache
  • mod_disk_cache

MCacheMaxObjectCount ディレクティブ

説明: | キャッシュに保管されるオブジェクトの最大数
構文: | MCacheMaxObjectCount value
デフォルト: | MCacheMaxObjectCount 1009
コンテキスト: | サーバ設定ファイル
ステータス: | Extension
モジュール: | mod_mem_cache

MCacheMaxObjectCount ディレクティブは キャッシュされるオブジェクトの最大数を指定します。 この値はハッシュテーブルを作成するときに使われます。 新しいオブジェクトを挿入するときに、オブジェクトの最大数に 達してしまっているとき、新しいオブジェクトをキャッシュできるように、 オブジェクトを一つ消去します。オブジェクトは MCacheRemovalAlgorithm で指定されたアルゴリズムに従って削除されます。

例

MCacheMaxObjectCount 13001

MCacheMaxObjectSize ディレクティブ

説明: | キャッシュに保管できるドキュメントの最大サイズ (バイト)
構文: | MCacheMaxObjectSize bytes
デフォルト: | MCacheMaxObjectSize 10000
コンテキスト: | サーバ設定ファイル
ステータス: | Extension
モジュール: | mod_mem_cache

MCacheMaxObjectSize はドキュメントを キャッシュするかどうかを判定する、最大のサイズをバイト数で設定します。

例

MCacheMaxObjectSize 6400000

注

MCacheMaxObjectSize の値は MCacheMinObjectSize で指定した値よりも大きくなければなりません。

MCacheMaxStreamingBuffer ディレクティブ

説明: | ストリームされている応答をキャッシュ不能と決定するまでに メモリにバッファする最大量
構文: | MCacheMaxStreamingBuffer size_in_bytes
デフォルト: | MCacheMaxStreamingBuffer of 100000 か MCacheMaxObjectSize の少い方
コンテキスト: | サーバ設定ファイル
ステータス: | Extension
モジュール: | mod_mem_cache

MCacheMaxStreamingBuffer ディレクティブは、 サイズが大きすぎてキャッシュできないと判断するまでの、 ストリーム応答のバッファのための最大バイト数を指定します。 ストリーム応答とは、コンテンツの全体がすぐには得られず、 Content-Length がわからない応答を指します。 ストリーム応答を行なうようなものにはプロキシされた応答や、 CGI スクリプトの出力などがあります。デフォルトではストリームの応答は Content-Length がない限りキャッシュされません。 このような動作になっている理由は、結局キャッシュに収まりきらないと 判断することになってしまうような、サイズの大きな応答のバッファリングに、 大量のメモリが消費されるのを避けるためです。 MCacheMaxStreamingBuffer ディレクティブを使うと、 Content-Length を含まない応答に対して指定された最大量まで バッファするようにできます。バッファを使い切ると、バッファ中の コンテンツは捨てられ、キャッシュ動作を中止します。

注:

MCacheMaxStreamingBuffer に非零の値を 使っても、クライアントへの応答の転送に特に遅延は発生しません。 mod_mem_cache はストリームコンテンツの断片を バッファにコピーした後、即座に、その部分をクライアントへの配送の 次段の出力フィルタに送ります。

# Enable caching of streamed responses up to 64KB:
MCacheMaxStreamingBuffer 65536

MCacheMinObjectSize ディレクティブ

説明: | キャッシュに保管されるドキュメントの最小サイズ (バイト)
構文: | MCacheMinObjectSize bytes
デフォルト: | MCacheMinObjectSize 0
コンテキスト: | サーバ設定ファイル
ステータス: | Extension
モジュール: | mod_mem_cache

MCacheMinObjectSize ディレクティブは、ドキュメントを キャッシュするかどうかを判定する、最小のサイズをバイト数で設定します。

例

MCacheMinObjectSize 10000

MCacheRemovalAlgorithm ディレクティブ

説明: | キャッシュから削除するドキュメントを選ぶためのアルゴリズム
構文: | MCacheRemovalAlgorithm LRU|GDSF
デフォルト: | MCacheRemovalAlgorithm GDSF
コンテキスト: | サーバ設定ファイル
ステータス: | Extension
モジュール: | mod_mem_cache

MCacheRemovalAlgorithm ディレクティブは、 キャッシュから削除するドキュメントを選択するためのアルゴリズムを 指定します。選択肢は二つあります:

LRU (Least Recently Used)
LRU 一番長くアクセスされていないドキュメントを削除します。
GDSF (GreadyDual-Size)
GDSF はキャッシュミスのコストとドキュメントのサイズをもとに、 ドキュメントのキャッシュに対して優先度をつけます。 優先度の一番低いドキュメントが最初に削除されます。

例

MCacheRemovalAlgorithm GDSF
MCacheRemovalAlgorithm LRU

MCacheSize ディレクティブ

説明: | キャッシュに使われるメモリの最大量をバイト単位で指定
構文: | MCacheSize KBytes
デフォルト: | MCacheSize 100
コンテキスト: | サーバ設定ファイル
ステータス: | Extension
モジュール: | mod_mem_cache

MCacheSize ディレクティブはキャッシュに 使われるメモリの大きさをキロバイト (1024 バイト単位) で設定します。 新しいオブジェクトをキャッシュに挿入することになり、オブジェクトの サイズが残りのメモリより大きい場合は、その新しいオブジェクトの挿入が 可能になるまで、古いオブジェクトが削除されていきます。 オブジェクトは MCacheRemovalAlgorithm で指定したアルゴリズムに従って削除されます。

例

MCacheSize 700000

注

MCacheSize の値は MCacheMaxObjectSize ディレクティブで指定した値より 大きくなければなりません。


mod_mime - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_mime

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | リクエストされたファイルの拡張子とファイルの振る舞い (ハンドラとフィルタ)、内容 (MIME タイプ、言語、文字セット、エンコーディング) とを関連付ける
ステータス: | Base
モジュール識別子: | 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_imagemap の) imap-file にマップされていて、.html が MIME タイプ text/html にマップされているときは、ファイル world.imap.html は imap-file ハンドラと text/html MIME タイプに関連付けられます。ファイルが処理されるときは imap-file ハンドラが使用されますので、そのファイルは mod_imagemap のイメージマップファイルとして扱われることになります。

コンテントエンコーディング

特定の 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
ステータス: | Base
モジュール: | 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
ステータス: | Base
モジュール: | 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
ステータス: | Base
モジュール: | 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
ステータス: | Base
モジュール: | mod_mime
互換性: | 2.0.26 以降で使用可能

AddInputFilter はファイルの拡張子 extension をクライアントのリクエストや POST がサーバに来たときに 処理をするフィルタにマップします。 これは、SetInputFilter ディレクティブも 含め、他の場所で定義されているフィルタに加えられます。 このマッピングはすでにあるものより優先されてマージされ、 同じ extension に対する既存のマッピングを上書きします。

複数のフィルタを指定するときは、データを処理する順番にセミコロンで 繋いで書く必要があります。フィルタと extension との 両方の引数は大文字小文字を区別せず、拡張子の最初のドットは あってもなくても構いません。

参照

  • RemoveInputFilter
  • SetInputFilter

AddLanguage ディレクティブ

説明: | ファイル名を指定された言語にマップ
構文: | AddLanguage MIME-lang extension [extension] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | 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
ステータス: | Base
モジュール: | 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
ステータス: | Base
モジュール: | 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
ステータス: | Base
モジュール: | 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
コンテキスト: | ディレクトリ
ステータス: | Base
モジュール: | 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
ステータス: | Base
モジュール: | 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
ステータス: | Base
モジュール: | mod_mime
互換性: | 2.0.24 以降で使用可能

RemoveCharset ディレクティブ は与えられた拡張子に関連付けられた文字セットを取り消します。 これにより、サブディレクトリにある .htaccess ファイルが親ディレクトリやサーバの設定ファイル から継承した関連付けを取り消すことができます。例えば:

extension は大文字小文字を区別しません。 また、最初のドットはあってもなくても構いません。

例

RemoveCharset .html .shtml

RemoveEncoding ディレクティブ

説明: | ファイルの拡張子に関連付けられたすべてのコンテントエンコーディング を解除する
構文: | RemoveEncoding extension [extension] ...
コンテキスト: | バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | 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
ステータス: | Base
モジュール: | 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
ステータス: | Base
モジュール: | mod_mime
互換性: | 2.0.26 以降で使用可能

RemoveInputFilter ディレクティブは 指定されたファイル拡張子に関連付けられた入力フィルタを解除します。 これを利用することで、親ディレクトリやサーバ設定ファイルから 継承した関連付けを サブディレクトリ内において .htaccess ファイルで取り消すことができます。

extension 引数は大文字小文字を区別しません。また、 最初のドットはあってもなくても構いません。

参照

  • AddInputFilter
  • SetInputFilter

RemoveLanguage ディレクティブ

説明: | ファイル拡張子に関連付けられた言語を解除する
構文: | RemoveLanguage extension [extension] ...
コンテキスト: | バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_mime
互換性: | 2.0.24 以降で使用可能

RemoveLanguage ディレクティブは 指定されたファイル拡張子に関連付けられた言語を解除します。 これを利用することで、親ディレクトリやサーバ設定ファイルから 継承した関連付けを サブディレクトリ内において .htaccess ファイルで取り消すことができます。

extension 引数は大文字小文字を区別しません。また、 最初のドットはついてもつかなくても構いません。

RemoveOutputFilter ディレクティブ

説明: | ファイル拡張子に関連付けられた出力フィルタを解除する
構文: | RemoveOutputFilter extension [extension] ...
コンテキスト: | バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | mod_mime
互換性: | 2.0.26 以降でのみ使用可能

RemoveOutputFilter ディレクティブは 指定されたファイル拡張子に関連付けられた出力フィルタを解除します。 これを利用することで、親ディレクトリやサーバ設定ファイルから 継承した関連付けを サブディレクトリ内において .htaccess ファイルで取り消すことができます。

extension は大文字小文字を区別しません。 また、最初のドットはあってもなくても構いません。

例

RemoveOutputFilter shtml

参照

  • AddOutputFilter

RemoveType ディレクティブ

説明: | ファイルの拡張子と関連付けられたコンテントタイプを 解除する
構文: | RemoveType extension [extension] ...
コンテキスト: | バーチャルホスト, ディレクトリ, .htaccess
上書き: | FileInfo
ステータス: | Base
モジュール: | 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
コンテキスト: | サーバ設定ファイル
ステータス: | Base
モジュール: | mod_mime

TypesConfig ディレクティブは、MIME タイプ設定ファイルの位置を設定します。filename は ServerRoot からの相対パスです。 このファイルはファイルの拡張子からコンテントタイプへの デフォルトのマッピングを設定します。 ほとんどの管理者は、よく使われるファイル名の拡張子を IANA に登録されたコンテントタイプに関連付けている、 Apache の mime.types ファイルを使います。 現在の一覧は http://www.iana.org/assignments/media-types/index.html で管理されています。これは、主要なメディアタイプの定義を提供して、 必要ところを 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 Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 Identifier: | mime_magic_module
Source File: | 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

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_negotiation - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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 Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_nw_ssl

Description: | Enable SSL encryption for NetWare
Status: | Base
Module Identifier: | nwssl_module
Source File: | 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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_proxy - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_proxy

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | HTTP/1.1 プロキシ/ゲートウェイサーバ
ステータス: | Extension
モジュール識別子: | proxy_module
ソースファイル: | mod_proxy.c

概要

警告

サーバを安全にするまで ProxyRequests は有効にしないでください。 オープンプロキシサーバはあなた自身のネットワークにとっても、 インターネット全体にとっても危険です。

このモジュールは Apache のプロキシ/ゲートウェイ機能を実装しています。 AJP13 (Apache JServe Protocol version 1.3), FTP, CONNECT (SSL 用), HTTP/0.9, HTTP/1.0, HTTP/1.1 のプロキシ機能を実装しています。これらのプロトコルやその他のプロトコル用の プロキシ機能を持った、他のモジュールに接続するようにも設定できます。

Apache のプロキシ機能は mod_proxy の他に、 いくつかのモジュールに分割されています: mod_proxy_http, mod_proxy_ftp, mod_proxy_ajp, mod_proxy_balancer, mod_proxy_connect です。ですから、 特定のプロキシの機能を使いたい場合は、mod_proxy と 該当するモジュールをサーバに (コンパイル時に静的に行なうか LoadModule で動的に読み込むかして) 組み込む必要があります。

これに加えて、他のモジュールによって拡張機能が提供されています。 キャッシュは mod_cache と関連モジュールで 提供されています。SSL/TLS で遠隔サーバに接続する機能は mod_ssl の SSLProxy* ディレクティブで 提供されています。これらの機能を利用するためには、該当するモジュールを 組み込んで設定しなければなりません。

参照

  • mod_cache
  • mod_proxy_http
  • mod_proxy_ftp
  • mod_proxy_connect
  • mod_proxy_balancer
  • mod_ssl

フォワードプロキシとリバースプロキシ/ゲートウェイ

Apache は フォワード プロキシとしても、 リバース プロキシ (別名 ゲートウェイ) としても設定できます。

通常の フォワードプロキシ はクライアントと オリジンサーバ (訳注: コンテンツ生成元のサーバ) の間に位置する中間サーバです。 オリジンサーバからコンテンツを取得するために、クライアントは 行き先をオリジンサーバに指定したリクエストをプロキシに送ります。 プロキシはオリジンサーバからコンテンツを受け取り、 取得したコンテンツをクライアントに返します。 クライアントがフォワードプロキシ経由で他のサイトにアクセスするには、 特別にそのための設定をしなければなりません。

フォワードプロキシの一般的な使用方法は、ファイアウォールによって 制限されている内部のクライアントに、インターネットへのアクセスを 提供するものです。フォワードプロキシはネットワークの使用量を 減らすために (mod_cache で提供されている) キャッシュ機能を用いることもできます。

フォワードプロキシは ProxyRequests ディレクティブで 有効になります。フォワードプロキシを使うと、クライアントは本当の身元を 隠して任意のサイトにアクセスできるようになります。このため、フォワードプロキシを 有効にする前に、承認されたクライアントのみがプロキシにアクセスできるように サーバを安全にすることが重要です。

一方 リバースプロキシ (ゲートウェイ) は、 クライアントから普通のウェブサーバのように見えます。 クライアント側に特別な設定は必要ありません。 クライアントはリバースプロキシの名前空間内のコンテンツに対して通常どおりの リクエストを行ないます。リバースプロキシはリクエストをどこに送れば良いかを判定し、 あたかも自分自身がオリジンサーバであったかのようにクライアントに コンテンツを返します。

リバースプロキシのよくある利用方法は、インターネットユーザに ファイアウォールの中にあるサーバにアクセスさせる場合です。 リバースプロキシは複数のバックエンドサーバへ負荷分散をするために 使ったり、遅いバックエンドエンドサーバのためにキャッシュ機能を提供したり するためにも使えます。また、リバースプロキシは複数のサーバを 同じ URL 空間にまとめるために使うこともできます。

リバースプロキシは ProxyPass ディレクティブや RewriteRule ディレクティブの [P] フラグを使うことで有効になります。リバースプロキシの 設定のために ProxyRequests を設定する必要は ありません。

基本の例

以下の例は手始めの簡単な例です。個々のディレクティブの意味は それぞれの説明をお読みください。

またキャッシュ機能を有効にしたい場合は、mod_cache の説明を読んでください。

リバースプロキシ

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

フォワードプロキシ

ProxyRequests On
ProxyVia On

<Proxy *>
Order deny,allow
Deny from all
Allow from internal.example.com
 </Proxy>

ワーカー

プロキシは ワーカー と呼ばれるオブジェクトで オリジンサーバとの通信パラメータの設定を管理します。 ふたつの組み込みワーカーが存在します。デフォルトのフォワードプロキシワーカーと デフォルトのリバースプロキシワーカーです。 追加のワーカーを明示的に設定可能です。

ふたつのデフォルトワーカーは固定の設定を持ちます。 リクエストが他のワーカーにマッチしない場合に使われます。 これらは HTTP のキープアライブもコネクションプーリングも使いません。 オリジンサーバへの TCP 接続はリクエストのたびに接続と切断をします。

明示的に設定するワーカーは、URL で識別されます。 通常、ProxyPass または ProxyPassMatch をリバースプロキシ設定に使うことで、これらのワーカーを生成および設定します:

ProxyPass /example http://backend.example.com connectiontimeout=5 timeout=30

上記はオリジンサーバの http://backend.example.com の URL に関連するワーカーを生成します。ワーカーは指定したタイムアウト値を持ちます。 フォワードプロキシで使われる時、ワーカーは一般に ProxySet ディレクティブで 定義します:

ProxySet http://backend.example.com connectiontimeout=5 timeout=30

または、別の方法として Proxy と ProxySetでも定義できます:

<Proxy http://backend.example.com>
ProxySet connectiontimeout=5 timeout=30 </Proxy>

フォワードモードで明示的に設定したワーカーを使うのは、あまり一般的ではありません。 なぜなら、通常フォワードプロキシは多くの異なるオリジンサーバと通信するからです。 もし一部のオリジンサーバを頻繁に利用するなら、それらに対して 明示的にワーカーを生成するのは有用です。明示的に設定したワーカーは、 それ自体はフォワードプロキシかリバースプロキシかのコンセプトを持ちません。 それらはオリジンサーバと通信する共通のコンセプトを抱えています。 リバースプロキシで使うために ProxyPass で生成したワーカーは、オリジンサーバへの URL がワーカーの URL にマッチすれば いつでもフォワードプロキシとして使えます。これは、逆も成り立ちます。

ワーカーを識別する URL はそのオリジンサーバの URL です。 URL は指定したパス部分も含みます:

ProxyPass /examples http://backend.example.com/examples
ProxyPass /docs http://backend.example.com/docs

この例はふたつの異なるワーカーを定義しています。 それぞれ別のコネクションプールと設定を使います。

ワーカーの共有

もしワーカーの URL に重なりがあれば、ワーカーの共有が起きます。 重なりとは、ワーカーの URL が、設定ファイル内で後から定義した 別のワーカーの URL の先頭文字列と部分一致することです。 次の例で

ProxyPass /apps http://backend.example.com/ timeout=60
ProxyPass /examples http://backend.example.com/examples timeout=10

ふたつめのワーカーは実際には生成されません。 その代わり、ひとつめのワーカーを使います。この利点は、ただひとつの コネクションプールで済む点です。このため、コネクションをより頻繁に再利用できます。 後ろのワーカーに明示的に書いた設定のすべてのパラメータと一部の設定のデフォルト値は、 最初のワーカーに書いた設定を上書きするのを注意してください。 これは警告としてログに残ります。上記の例で言えば、/apps の URL に対するタイムアウト値は、結果として 60 ではなく 10になるのです。

もしワーカーの共有を避けたければ、ワーカーの定義を URL の長さでソートしてください。 そして、長い URL から並べてください。もしワーカーの共有を最大限にしたいなら、 逆順に並べます。ProxyPass ディレクティブの並びについて、関連する警告も見てください。

明示的に設定するワーカーにはふたつの種類があります: 直接のワーカー と バランサー (負荷分散) ワーカー です。 これらは後ほど ProxyPass ディレクティブの中で説明する重要な設定パラメータを数多くサポートします。 同じパラメータは ProxySet を使っても設定可能です。

直接のワーカーで利用できるパラメータはプロトコルに依存します。 プロトコルはオリジンサーバの URL で指定されます。 利用可能なプロトコルは ajp, ftp, http, scgi です。

バランサーワーカーは仮想ワーカーです。直接のワーカーを リクエストを実際に処理するメンバーとして使います。 それぞれのバランサーは複数のメンバーを持ちえます。 リクエストを処理する時、設定した負荷分散のアルゴリズムにもとづき メンバーのひとつを選択します。

ワーカーの URL のプロトコルスキームに balancer を使うと、バランサワーカーが生成されます。 バランサーの URL が、バランサワーカーを一意に識別します。 BalancerMember を使って、バランサーにメンバーを追加します。

プロキシへのアクセス制御

プロキシへのアクセスは以下のように <Proxy> コンテナの中に ディレクティブを書くことで制御できます:

<Proxy *>
Order Deny,Allow
Deny from all
Allow from 192.168.0
 </Proxy>

アクセス制御のためのディレクティブのより詳しい情報は mod_authz_host をお読みください。

(ProxyRequests ディレクティブを 使って) フォワードプロキシを設定している場合は、厳しくアクセス 制限を行なうことが非常に大切です。そうしないと、任意のクライアントが 身元を明かすことなく任意のホストにアクセスするためにプロキシサーバを使うことが できてしまいます。これはあなた自身のネットワークにとっても、インターネット 全体にとっても危険なことです。(ProxyRequests Off にして ProxyPass ディレクティブを使って) リバースプロキシを使っている場合には、クライアントはあなたが明示的に 設定したホストにしかアクセスできないため、フォワードプロキシのとき ほどアクセス制御に力を注がなくても大丈夫です。

遅い起動

ProxyBlock ディレクティブを使っている場合、 後に行うマッチ判定のため、起動時にホストの名前解決をして IP アドレスをキャッシュします。ホスト名の名前解決の 速さによっては、数秒 (かそれ以上) かかるかもしれません。

イントラネットプロキシ

イントラネットにある Apache プロキシサーバは外部へのリクエストを 会社のファイアウォールを通して送らなければなりません。(このためには 個々の scheme についてそれぞれ、ファイアウォールの プロキシにフォワードされるように ProxyRemote ディレクティブを 設定してください)。しかしイントラネット内のリソースにアクセスするときは、 ファイアウォールを通さないでもアクセスできます。 どのホストがイントラネットに属し、直接アクセスすべきかを指定するには、 NoProxy ディレクティブが 役に立ちます。

イントラネット内のユーザは WWW のリクエストでローカルドメインを 省略することがよくあります。http://somehost.example.com/ というリクエストの代わりに "http://somehost/" をリクエストしたりします。 このようなリクエストを受け付け、サーバに設定されているローカルドメインが 暗黙のうちに使われていると解釈して、単純にリクエストを処理するものも 商用プロキシサーバの中にはあります。 サーバが プロキシのサービス用に設定されていて ProxyDomain ディレクティブが 使用された場合には、Apache はクライアントにリダイレクト応答を送って、 正しい、完全な (訳注: fully qualified) サーバのアドレスに送ることができます。このように リダイレクトすると、ユーザのブックマークが正しい完全なホスト名を含む ことにもなるため、より好ましい方法と言えるでしょう。

プロトコルの調整

Keepalive や HTTP/1.1 を適切に実装していないオリジンサーバに対して mod_proxy がリクエストを送信する場合、 HTTP/1.0 を使って keepalive を無しにしてリクエストを送るようにする 環境変数が二つあります。これらは SetEnv ディレクティブで設定します。

force-proxy-request-1.0 と proxy-nokeepalive がその環境変数です。

<Location /buggyappserver/>
ProxyPass http://buggyappserver:7001/foo/
SetEnv force-proxy-request-1.0 1
SetEnv proxy-nokeepalive 1
 </Location>

リクエストボディ

POST メソッドなどのリクエストには、リクエストボディがあります。 HTTP プロトコル仕様によると、ボディのあるリクエストは chunked 転送を使うか、Content-Length ヘッダを送信しなければなりません。 このようなリクエストをオリジンサーバに送信する場合、 mod_proxy_http は常に Content-Length を送ろうと試みます。しかし、ボディが大きく、オリジナルのリクエストで chunked 転送が使われている場合、上流へのリクエストに chunked 転送も使われます。 この挙動は 環境変数で制御できます。 proxy-sendcl を設定すると、 常に Content-Length を送り、最大限の互換性を確保します。 逆に proxy-sendchunked を設定すると、 chunked エンコードを使ってリソース消費を抑えます。

リバースプロキシのリクエストヘッダ

リバースプロキシとして振る舞う時 (例えば、ProxyPass ディレクティブを使う時) 、 mod_proxy_http は、オリジンサーバに情報を渡すために いくつかのリクエストヘッダを追加します。これらのヘッダは以下になります。

X-Forwarded-For
クライアントの IP アドレス。
X-Forwarded-Host
オリジナルのホスト名。クライアントが Host リクエストヘッダで渡す。
X-Forwarded-Server
プロキシサーバのホスト名。

オリジンサーバ上でこれらのヘッダを扱う時は注意してください。 と言うのも、オリジナルのリクエストが既に同じヘッダを持っていると、 ヘッダが一つ以上の値 (コンマで区切られます) を持つ可能性があるからです。 例えば、 オリジンサーバ上でオリジナルのクライアントのIPアドレスをログに 記録するため、ログフォーマットに %{X-Forwarded-For}i を 指定したとします。この時、リクエストが複数のプロキシを経由していると、 複数のアドレスがログに載る可能性があります。

ProxyPreserveHost と ProxyVia ディレクティブ も参照してください。これらは他のリクエストヘッダに影響を与えます。

AllowCONNECT ディレクティブ

説明: | プロキシを経由して、どのポートに CONNECT できるかを指定する
構文: | AllowCONNECT port [port] ...
デフォルト: | AllowCONNECT 443 563
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy

AllowCONNECT はプロキシの CONNECT メソッドが接続を許可するポート番号のリストを指定します。 今日のブラウザは、https コネクションが要求されていて、 HTTP 上でのプロキシによるトンネリングができるときに、 このメソッドを使います。

デフォルトの設定では、https のデフォルトポート (443) と デフォルトの snews ポート (563) が有効になっています。 このデフォルトを上書きして、リストに記載したポートにのみ接続を許可したい場合、 AllowCONNECT ディレクティブを使用します。

CONNECT を使用するには、mod_proxy_connect がサーバに組み込まれていなければならないことに注意してください。

BalancerMember ディレクティブ

説明: | ロードバランサのグループにメンバーを追加
構文: | BalancerMember [balancerurl] url [key=value [key=value ...]]
コンテキスト: | ディレクトリ
ステータス: | Extension
モジュール: | mod_proxy
互換性: | BalancerMember は Apache 2.2 以降でのみ使用可能

このディレクティブでロードバランサのグループにメンバを追加します。 <Proxy balancer://...> ディレクティブのコンテナ 内で使われることが多く、ProxyPass ディレクティブと共通のキーバリューペアのパラメータを取ります。

<Proxy balancer://...> ディレクティブの コンテナ内に書かない場合のみ、 balancerurl 引数が必要です。 これは ProxyPass ディレクティブで バランサを定義した時の URL と同じ働きをします。

NoProxy ディレクティブ

説明: | 直接接続する ホスト、ドメイン、ネットワーク
構文: | NoProxy host [host] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy

このディレクティブはイントラネット中の Apache プロキシサーバにのみ 有用です。NoProxy ディレクティブは空白区切りで、 サブネット、IP アドレス、ホスト、ドメインのリストを指定します。 これらのどれかにマッチするホストへのリクエストは ProxyRemote で設定されたプロキシサーバに フォワードされず、直接処理されます。

例

ProxyRemote * http://firewall.example.com:81
NoProxy .example.com 192.168.112.0/21

NoProxy ディレクティブの host 引数は 以下の種類のどれかです:

Domain

Domain は先頭にピリオドを書いた部分 DNS ドメイン名です。 同一 DNS ドメイン及びゾーン (すなわち、ホスト名の末尾がすべて Domain で終わっているということ) に属するホストのリストを 表します)。

例

.com .apache.org.

Domain を Hostname と区別するために (意味的にも構文的にも。DNS ドメインも DNS の A レコードを持つことができるのです!)、Domain は 常にピリオドで始まります。

注

ドメイン名の比較は大文字小文字を区別せずに行なわれ、Domain は常に DNS ツリーのルートから始まるものとみなされます。ですから、 次の二つのドメイン .ExAmple.com と .example.com. (最後のピリオドに注目) は同一であると みなされます。ドメインの比較は DNS ルックアップなしで行なわれるため、 サブネットの比較よりもずっと効率的です。

SubNet

SubNet は数値形式 (ドットで区切られた四つの数字) の 部分インターネットアドレスです。後にスラッシュと Subnet の意味のあるビット数を指定するネットマスクとを続けることができます。 共通のネットワークインタフェースを使って到達することのできるサブネットを 表すために使われます。明示的にネットマスクを指定しない場合は 最後の省略された (もしくは値が 0 の) 数字がマスクを指定します。 (この場合は、ネットマスクは 8 ビット単位でしか指定できません。) 例:

192.168 もしくは 192.168.0.0
サブネット 192.168.0.0 と暗黙の 16 ビット有効なネットマスク (255.255.0.0 というネットマスクの形式で使われることも あります)
192.168.112.0/21
サブネット192.168.112.0/21 と 21 ビット有効な ネットマスク (255.255.248.0 という形式で使われることも あります)

特別な場合に、32 ビット有効な SubNet は IPAddr と同等で、 0 ビット有効な SubNet (例えば、0.0.0.0/0) は すべての IP アドレスにマッチする定数 _Default_ と同じです。

IPAddr

IPAddr は数値形式 (ドットで区切られた四つの数字) の 完全インターネットアドレスです。通常はこのアドレスはホストを 表しますが、必ずしもアドレスに対応する DNS ドメイン名があるわけでは ありません。

例

192.168.123.7

注

IPAddr は DNS システムにより解決される必要がないので、 apache の性能が向上するかもしれません。

Hostname

Hostname は DNS ドメインサービスにより一つもしくは 複数の IPAddr に解決可能な 完全な DNS ドメイン名です。これは (Domain と違って、説明は上記を参照) 論理的なホストを表し、少くとも一つの IPAddr (もしくは違う IPAddr のホストのリスト) に解決 されなければなりません)。

例

prep.ai.example.com
www.apache.org

注

多くの場合、Hostname の代わりに IPAddr を指定した方が、DNS ルックアップを 避けることができるため、効率が良くなります。Apache の名前解決は ネームサーバへの接続が遅い PPP 上の場合などにかなり時間を取られる ことがあります。

Hostname の比較は大文字小文字を区別せずに行なわれ、 Hostname は常に DNS ツリーのルートから始まるものとみなされます。 ですから、二つのドメイン WWW.ExAmple.com と www.example.com. (最後のピリオドに注目) は同一であると みなされます。

参照

  • DNS に関する問題

<Proxy> ディレクティブ

説明: | プロキシされるリソースに適用されるコンテナ
構文: | <Proxy wildcard-url> ...</Proxy>
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy

<Proxy> セクション中の ディレクティブはマッチするプロキシされるコンテンツにのみ適用されます。 シェル形式のワイルドカードが使えます。

例えば、次の設定は yournetwork.example.com の ホストにのみプロキシサーバを経由したアクセスを許可します:

<Proxy *>
Order Deny,Allow
Deny from all
Allow from yournetwork.example.com
 </Proxy>

次の例は example.com の foo ディレクトリの すべてのファイルに対して、プロキシサーバを通して送られたときには INCLUDES フィルタを通して送るように設定します:

<Proxy http://example.com/foo/*>
SetOutputFilter INCLUDES
 </Proxy>

参照

  • <ProxyMatch>

ProxyBadHeader ディレクティブ

説明: | 応答におかしなヘッダがある場合の扱い方を決める
構文: | ProxyBadHeader IsError|Ignore|StartBody
デフォルト: | ProxyBadHeader IsError
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy
互換性: | Apache 2.0.44 以降で使用可能

ProxyBadHeader ディレクティブは構文的に 間違ったレスポンスヘッダ (つまり コロンを含まないもの) を受け取ったときに mod_proxy がどう振る舞うかを決めます。以下の引数を 取ることができます:

IsError
リクエストを中止して 502 (Bad Gateway) 応答を返す。 これがデフォルトの動作です。
Ignore
間違ったヘッダ行をそもそも存在しなかったものとして扱う。
StartBody
間違ったヘッダ行を受け取ったら、ヘッダの読み込みを終了して、 それ以降の残りをボディとして扱う。これはヘッダとボディの間に空行を入れ忘れて しまっているような、きちんと動作していないバックエンドサーバがあるときに、 問題を回避するのに役に立ちます。

ProxyBlock ディレクティブ

説明: | プロキシ接続を禁止する語句、ホスト名、ドメインを指定する
構文: | ProxyBlock *|word|host|domain [word|host|domain] ...
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy

ProxyBlock ディレクティブは空白で区切られた 語句、ホスト名、ドメインのリストを指定します。サイト名にその語句、ホスト名、 ドメインを含むサイトへの HTTP、HTTPS、FTP によるドキュメントのリクエストは プロキシサーバにより ブロックされます。プロキシモジュールは 起動時にホスト名と思しき項目の IP アドレスを調べ、後のテストのために キャッシュします。これにより、サーバの起動が少し遅くなるかもしれません。

Example

ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu

rocky.wotsamattau.edu が IP アドレスで参照されたときでも マッチします。

wotsamattau.edu のマッチには wotsamattau だけでも十分です。

ProxyBlock *

はすべてのサイトへの接続をブロックすることに注意してください。

ProxyDomain ディレクティブ

説明: | プロキシされたリクエストのデフォルトのドメイン名
構文: | ProxyDomain Domain
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy

このディレクティブはイントラネット内の Apache プロキシサーバにのみ 有用です。ProxyDomain ディレクティブは apache プロキシサーバが属するデフォルトのドメインを指定します。 ドメイン名の無いリクエストを受けた場合、設定された Domain が追加された同じホストへのリダイレクト応答が返されます。

例

ProxyRemote * http://firewall.example.com:81
NoProxy .example.com 192.168.112.0/21
ProxyDomain .example.com

ProxyErrorOverride ディレクティブ

説明: | プロキシされたコンテンツのエラーページを上書きする
構文: | ProxyErrorOverride On|Off
デフォルト: | ProxyErrorOverride Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy
互換性: | Apache 2.0 以降で使用可能

このディレクティブはリバースプロキシを使用していて、 エンドユーザに送られるエラーページの外見を共通のものにしたいときに 有用です。このディレクティブは (mod_include の SSI によって) インクルードされたファイルがエラーコードを取得して、正しく動作を するようにもします (デフォルトの動作は、プロキシされたサーバの エラーページの表示で、このディレクティブを有効にすると SSI のエラー メッセージを表示します)。

このディレクティブは informational (1xx), 成功 (2xx), リダイレクト (3xx) ステータスのレスポンス処理には影響しません。

ProxyFtpDirCharset ディレクティブ

説明: | プロキシされた FTP (の一覧表示) のキャラクタセットを定義
構文: | ProxyFtpDirCharset character set
デフォルト: | ProxyFtpDirCharset ISO-8859-1
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_proxy
互換性: | Apache 2.2.7 以降で使用可能

ProxyFtpDirCharset ディレクティブは、 mod_proxy_ftp が HTML 形式で生成する FTP のディレクトリ一覧 画面のキャラクタセットを定義します。

ProxyIOBufferSize ディレクティブ

説明: | 内部データスループットバッファのサイズを決定する
構文: | ProxyIOBufferSize bytes
デフォルト: | ProxyIOBufferSize 8192
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy

ProxyIOBufferSize ディレクティブは入力と 出力用の一時メモリとして使われる内部バッファのサイズを調整します。 サイズは 8192 以下でなければなりません。

ほとんどすべての場合、この値を変更する理由はありません。

<ProxyMatch> ディレクティブ

説明: | 正規表現でのマッチによるプロキシリソース用のディレクティブコンテナ
構文: | <ProxyMatch regex> ...</ProxyMatch>
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy

<ProxyMatch> は URL のマッチに 正規表現 を用いることを除けば <Proxy> ディレクティブと同じです。

参照

  • <Proxy>

ProxyMaxForwards ディレクティブ

説明: | リクエストがフォワードされるプロキシの最大数
構文: | ProxyMaxForwards number
デフォルト: | ProxyMaxForwards -1
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy
互換性: | Apache 2.0 以降で使用可能; Apache 2.2.7でデフォルト動作が変わりました

ProxyMaxForwards ディレクティブは リクエストに Max-Forwards ヘッダが指定されていない場合に リクエストが通過可能なプロキシの最大数を設定します。これは プロキシの無限ループや DoS 攻撃を防ぐために設定されるかもしれません。

例

ProxyMaxForwards 15

ProxyMaxForwards の設定は、HTTP/1.1 (RFC2616) に違反します。と言うのも、RFC2616 は、クライアントが Max-Forwards ヘッダをセットしない時、プロキシが Max-Forwards ヘッダを セットすることを禁じているからです。 Apache の初期バージョンは常にセットする可能性がありました。 ProxyMaxForwards に負数 (デフォルト値の -1 も含む) を指定すると、HTTP/1.1 準拠の動作になります。しかし、これは無限ループの危険性を残します。

ProxyPass ディレクティブ

説明: | リモートサーバをローカルサーバの URL 空間にマップする
構文: | ProxyPass [path] !|url [key=value key=value ...]] [nocanon] [interpolate]
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_proxy

このディレクティブはリモートサーバをローカルサーバの名前空間に マップできるようにします。ローカルサーバは通常の意味でのプロキシと しては動作せず、リモートサーバのミラーとして振る舞います。 ローカルサーバはしばしば リバースプロキシ や ゲートウェイ と呼ばれます。 path はローカルの仮想パスの名前です。url は リモートサーバの部分 URL になり、クエリー文字列を含むことはできません。

ProxyPass ディレクティブを 使っているときは ProxyRequests ディレクティブは通常は off に設定されているべきです。

ローカルサーバのアドレスが http://example.com/ であると します。すると、

ProxyPass /mirror/foo/ http://backend.example.com/

と設定すると http://example.com/mirror/foo/bar への リクエストが内部的に http://backend.example.com/bar への プロキシリクエストに変換されることになります。

もし第一引数が / で終端するならば、第二引数も / で終端すべきです。逆もまた然りで、第一引数が終端しないならば、 第二引数も終端すべきではありません。 これに反すると、バックエンドサーバ向けに変換されたリクエストは 必要なスラッシュを欠く可能性があり、バックエンドサーバは期待する結果を返しません。

サブディレクトリをリバースプロキシしたくないときに ! は 役に立ちます。例えば、

ProxyPass /mirror/foo/i !
ProxyPass /mirror/foo http://backend.example.com

は /mirror/foo/i を 除く /mirror/foo へのすべてのリクエストを backend.example.com にプロキシします。

ProxyPass ディレクティブの順序

ProxyPass と ProxyPassMatch のルールの 設定は設定ファイル中の順序どおりにチェックされます。 最初にマッチしたルールが勝ちます。このため通常は、 マッチが重なる ProxyPass ルールは、長い URL が先になるように並べるべきです。 そうしないと、後に書かれた長い URL にマッチするルールが、 先に書かれた短い URL の先頭の部分にマッチしたルールで隠される可能性があります。 ワーカーの共有とも多少の関係があることにも注意してください。

同じ理由で、否定処理も一般的な ProxyPass ディレクティブの 前に 書くべきです。

Apache HTTP サーバ 2.1 以降、バックエンドサーバとの接続に プールされたコネクションを使えるようになりました。 要求に応じて生成されたコネクションは将来の使用のためにプール内に維持されます。 プールサイズとその他の設定の制限は ProxyPass ディレクティブに key=value パラメータで設定します。 パラメータは後述する表に示します。

デフォルトで、mod_proxy は Web サーバの子プロセスが同時に使いうる 最大数のコネクションを許し維持するようにします。 この数をデフォルトから減らすには max パラメータを使ってください。 生存期間を設定するには ttl パラメータを使ってください。 ttl 秒を越えて使われていないコネクションは切断されます。 バックエンドサーバのキープアライブがタイムアウトして、切断されようとしている コネクションが使われることを防ぐために ttl を使えます。

コネクションプールは Web サーバの子プロセスごとに維持されます。 max やその他の設定は、すべての子プロセスの間で調整はされません。 ただし、設定により、ただひとつの子プロセスに設定を委ねた場合や MPM 設計によってはこの限りではありません。

例

ProxyPass /example http://backend.example.com max=20 ttl=120 retry=300

パラメータ | デフォルト値 | 説明
min | 0 | コネクションプール内で実際の接続に関連していないエントリの最小数です。 デフォルト値から変更する必要があるのは、バックエンドとの接続に必要な ヒープメモリを事前に割り当てるか維持しなければいけない特別な状況のみです。
max | 1...n | バックエンドサーバとの接続数の最大値です。 デフォルト値は、使用している MPM のプロセスあたりのスレッド数になっています。 Prefork MPM では常に 1 で、他の MPM では ThreadsPerChild ディレクティブで調節できます。
smax | max | もしコネクションプール内の接続中エントリが ttl パラメータ で設定した生存期間より長く未使用のままであれば、 この指定値を越える分のエントリを解放します。 もしエントリが関連するコネクションを持てば、接続を閉じます。 デフォルト値から変更する必要があるとすれば、 コネクションが生存期間を越えてしまった時に、 コネクションプール内の該当エントリの解放とコネクションの切断を より積極的に必要とする特別な場合のみです。
acquire - 設定すると、コネクションプールからフリーのコネクションを取得するために 待機する待ち時間 (ミリ秒単位) の最大値になります。フリーのコネクションがプールになかった場合は、 SERVER_BUSY ステータスをクライアントに返します。
connectiontimeout | timeout | 接続タイムアウトを秒で指定します。 バックエンドに接続を完了するまでの Apache の待ち時間です。 値の最後に ms を書くと、タイムアウトの単位をミリ秒にできます。
disablereuse | Off | 使用後すぐに mod_proxy がバックエンドとの接続を切断してほしい時は、 このパラメータを有効にすべきです。そうすることで、バックエンドとの 永続的な接続とプーリングを無効にできます。 これはいくつかの状況下で役に立ちます。例えば、Apache とバックエンドサーバ の間にファイアウォールが存在し (プロトコルは問わないとします)、黙って 接続を切られる場合や、あるいは、バックエンドサーバ自体が DNS で ラウンドロビンされている場合などです。コネクションプーリングによる再利用を 無効にするには、このパラメータ値を On にしてください。
flushpackets | off | プロキシモジュールが "chunk" ごとに出力データを自動的に強制送信(フラッシュ) するかを指定します。 'off' は必要な時だけ強制送信します。 'on' はそれぞれの "chunk" データごとに強制送信します。 'auto' は、一定時間待機し、 'flushwait' で指定したミリ秒の間、入力データが無ければ強制送信します。 現在、このパラメータは AJP でのみ意味があります。
flushwait | 10 | 'flushpackets' パラメータの値が 'auto' の場合、出力データを強制送信する前に、 次の入力をどのぐらい待つかをミリ秒単位で指定します。
keepalive Off

バックエンドサーバと Apache の間にファイアーウォールがある場合には、 このパラメータを使ってください。ファイアウォールは往々にして、 非活動状態のコネクションを落とそうとします。 このフラグは OS に指示して、KEEP_ALIVE メッセージを非活動状態の コネクションでも送るようにします。これによってファイアウォールによってコネクションが 落とされることを防げます。keepalive を有効にするには、このプロパティを On にしてください。

初期およびその後の TCP キープアライブの間隔は OS のグローバル設定に依存しますが、 2 時間以上にしたほうがよいでしょう。有効性を考えると、 OS で設定した間隔はファイアウォールで使われる閾値より小さくあるべきです。

lbset | 0 | ワーカーが属するロードバランサのクラスタセットを設定します。 ロードバランサは、より小さい lbset 値を持つメンバーから使おうとします。
ping | 0 | この設定により、Web サーバは ajp13 通信でリクエストを送信する前に CPING を送るようになります。 パラメータ値は、CPONG リプライを待つ時間を秒単位で指定します。 この機能は、ハングしたり高負荷状態の Tomcat に起因する問題を回避するために 追加されました。 また、ajp13 側に ping/pong 機能のサポートが必要です。 Tomcat は 3.3.2 以降, 4.1.28 以降, 5.0.13 以降が ping/pong 機能を実装しています。 この機能は、通常利用でのネットワークトラフィックを増やす可能性があり、 問題になるかもしれません。しかし、クラスタを形成するノードの一部が ダウンしたり高負荷になった時にはトラフィックを抑制できる可能性があります。 現在、この設定は AJP でのみ意味があります。 値の最後に ms を書くと、単位をミリ秒にできます。
loadfactor | 1 | ワーカーあたりの負荷係数です。BalancerMember で使います。 1 から 100 までの数字でそのワーカーに対する正規化された負荷率を指定します。
redirect - ワーカーのリダイレクション経路です。この値は通常は、 クラスタから安全にノードを取り除けるように動的にセットされます。 もし設定すると、セッション ID 無しの全てのリクエストは、 この値と同じルーティングパラメータを持つ BalancerMember にリダイレクトされます。
retry | 60 | コネクションをプーリングするための、リトライのタイムアウトを秒で 指定します。バックエンドサーバへのコネクションプーリングが失敗した場合は、 タイムアウトの期間が過ぎるまで、そのサーバにリクエストをフォワードしません。 この機能を使うと、バックエンドサーバをメンテナンスのためにシャットダウンし、 後でオンラインに復帰させるといったことができます。 0 を指定すると、失敗したワーカーへ、タイムアウト無しで常にリトライします。
route - ロードバランサで使われた場合のワーカーのルート値。 ルート値はセッション ID に付加される値です。
status - 一文字でワーカーの初期状態を定義します: 'D' は無効 (disabled)、 'S' は停止 (stopped)、 'I' はエラー無視 (ignore-errors)、 'H' はホットスタンバイ (hot-standby)、 'E' はエラー状態 (error) です。 '+' を文字の前に書いて有効にするか (これがデフォルト動作です)、 あるいは '-' を書いて無効にできます。つまり、 'S-E' の指定は、ワーカーを停止状態 かつ、エラー状態フラグのクリアを意味します。
timeout | ProxyTimeout | コネクションタイムアウトを秒で指定します。 バックエンドからのデータ受信およびバックエンドへのデータ送信の Apache の待ち時間です。
ttl - 非活動状態のコネクションと、関連するコネクションプール内のエントリの 生存時間を秒で指定します。いったんこの制限に達すると、 コネクションはふたたび使われることはありません。 つまり、コネクションは一定時間後に閉じられます。

もし ProxyPass ディレクティブのスキームが balancer:// で始まる場合 (例えば balancer://cluster/、 パス情報は無視されます)、バックエンドのサーバと実際には通信しない 仮想ワーカーが生成されます。通信しない代わりに、このワーカーは幾つかの "本物の" ワーカーの管理をつかさどります。 この場合、いくつかの特殊パラメータを、この仮想ワーカーに対して設定できます。 ロードバランス動作のより詳しい情報は、mod_proxy_balancer を参照してください。

パラメータ | デフォルト値 | 説明
lbmethod | byrequests | Balancer のロードバランス方法。使用するロードバランスの スケジューリング方法を選びます。処理したリクエストの数で重み付けする byrequests か、転送量のバイト数で重み付けする bytraffic か、待機中のリクエスト数で振り分ける bybusyness を設定できます (Apache HTTP サーバ 2.2.10 以降)。 デフォルトはbyrequests です。
maxattempts | ワーカーの数よりひとつ少ない数。あるいはワーカーがひとつであれば1 | フェイルオーバーを試みる最大の回数を指定します。
nofailover | Off | On になっていると、ワーカーがエラーを起こしたり 無効になっている場合にセッションが切れます。 バックエンドサーバがセッションレプリケーションをサポートしていない場合は、 On にしてください。
stickysession | - | バランサーのスティッキーセッション名です。通常はこの値は JSESSIONID や PHPSESSIONID といったものになりますが、この値は セッションをサポートするバックエンドのアプリケーションサーバに依存します。 バックエンドのアプリケーションサーバが、クッキーやURLエンコードID に異なるセッション名を使う場合(サーブレットコンテナのように)、 | 文字でふたつの名前を区切ってください。 最初の名前がクッキー用で、二番目がURLパス用です。
scolonpathdelim | Off | On にセットすると、セミコロン文字 ';' をスティッキーセッション の別の区切り文字として使えるようになります。 これは主に mod_jk の動作に合わせるために使います。例えば、 JSESSIONID=6736bcf34;foo=aabfa のような指定です。
timeout | 0 | バランサーのタイムアウトを秒で指定します。 この値を設定すると、フリーのワーカーを取得するまでの最大待機時間になります。 デフォルトでは待機しません。
failonstatus | - | ひとつ、あるいはコンマ区切りの複数の HTTP ステータスコードです。 この値を設定すると、列挙したステータスコードのどれかをバックエンドが返した時、 そのワーカーをエラー状態にします。ワーカーのエラーからの回復は 他のワーカーエラーと同じように動作します。 Apache HTTP サーバ 2.2.17 以降で使用可能です。

バランサーの設定例

ProxyPass /special-area http://special.example.com smax=5 max=10
ProxyPass / balancer://mycluster/ stickysession=JSESSIONID|jsessionid nofailover=On
<Proxy balancer://mycluster>
BalancerMember ajp://1.2.3.4:8009
BalancerMember ajp://1.2.3.5:8009 loadfactor=20
# Less powerful server, don't send as many requests there,
BalancerMember ajp://1.2.3.6:8009 loadfactor=5
 </Proxy>

ホットスタンバイの設定例です。他のメンバーが利用できない場合のみ 使われます。

ProxyPass / balancer://hotcluster/
<Proxy balancer://hotcluster>
BalancerMember ajp://1.2.3.4:8009 loadfactor=1
BalancerMember ajp://1.2.3.5:8009 loadfactor=2
# The below is the hot standby
BalancerMember ajp://1.2.3.6:8009 status=+H
ProxySet lbmethod=bytraffic </Proxy>

通常、mod_proxy は ProxyPass した URL を正規化します。 しかし、これによりバックエンドの互換性に問題が生じることがあります。 特に、PATH_INFO を使っている場合に起きがちです。 nocanon オプションは正規化を抑制し、URL のパスをそのまま ("raw") バックエンドに伝えます。これがバックエンドのセキュリティに影響を与える可能性に 注意してください。と言うのも、プロキシによって提供されていた、 URL ベースの攻撃への通常の一定の防御を無くすことになるからです。

オプショナルな interpolate キーワード (httpd 2.2.9 以降で利用可能) を ProxyPassInterpolateEnv ディレクティブと 一緒に使うと、${VARNAME} 形式で、 ProxyPass 設定に環境変数を 使えるようになります。この時、標準的な CGI 由来の環境変数の多くは 置換に使えないことに注意してください。そのため、複雑なルールの記述のためには、 mod_rewrite に頼ることになるでしょう。

<Location> セクションの中で使われた場合、最初の引数は 省略され、ローカルディレクトリは <Location> から取得されます。 同じことは <LocationMatch> セクション内でも起きます。しかし、ProxyPass は正規表現を解釈しないので、 この状況では代わりに ProxyPassMatch を使う必要があります。

このディレクティブは <Directory> や <Files> セクション内では使えません。

より柔軟なリバースプロキシの設定が必要な場合は、[P] フラグ付きの RewriteRule ディレクティブを参照してください。

ProxyPassInterpolateEnv ディレクティブ

説明: | リバースプロキシ設定内での環境変数の使用を有効にする
構文: | ProxyPassInterpolateEnv On|Off
デフォルト: | ProxyPassInterpolateEnv Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_proxy
互換性: | Apache 2.2.9 以降で使用可能

ProxyPass, ProxyPassReverse, ProxyPassReverseCookieDomain, ProxyPassReverseCookiePath の interpolate 引数と一緒にこのディレクティブを使うと、 環境変数を使ってリバースプロキシを動的に設定できます。 mod_rewrite など他のモジュールで環境変数を設定する想定です。 ProxyPass ディレクティブ, ProxyPassReverse ディレクティブ, ProxyPassReverseCookieDomain ディレクティブ, ProxyPassReverseCookiePath ディレクティブ の動作に影響を与え、これらの設定ディレクティブ内の ${varname} の文字列を 環境変数 varname の値で置き換えます。 (interpolate オプションがセットされていれば)

必要にならない限り、このディレクティブは無効にしてください。 (サーバのパフォーマンスのため)

ProxyPassMatch ディレクティブ

説明: | 正規表現を使ってリモートサーバをローカルサーバの URL 空間にマップする
構文: | ProxyPassMatch [regex] !|url [key=value [key=value ...]]
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_proxy
互換性: | Apache 2.2.5 以降で使用可能

単純な文字列前方一致ではなく正規表現を用いることを除いて、このディレクティブは ProxyPass と同じです。 指定した正規表現で url に対してマッチを試みます。 マッチすると、サーバはマッチした丸括弧部分を前方参照の置換に使い、新しい url にします。

ローカルサーバのアドレスが http://example.com/ だとします; すると

ProxyPassMatch ^(/.*\.gif)$ http://backend.example.com$1

は、ローカルの http://example.com/foo/bar.gif へのリクエストを 内部的に http://backend.example.com/foo/bar.gif へのプロキシリクエスト に変換します。

注意

URL 引数は正規表現による置換の 前 でも (当然、置換後でも)、 URL として解釈できなければいけません。これは使えるマッチに制約をもたらします。 例えば、上記の例で

ProxyPassMatch ^(/.*\.gif)$ http://backend.example.com:8000$1

と書いたとします。これはサーバ起動時にシンタックスエラーを起こすでしょう。 これはバグです (ASF bugzilla の PR 46665)。 回避策としてマッチ判定を書き換える必要があります:

ProxyPassMatch ^/(.*\.gif)$ http://backend.example.com:8000/$1

サブディレクトリをリバースプロキシしたくないときに ! は 役に立ちます。

<LocationMatch> セクションの中で使われた場合は、 最初の引数は省略され、正規表現は <LocationMatch> から取得されます。

より柔軟なリバースプロキシの設定が必要な場合は、[P] フラグ付きの RewriteRule ディレクティブを参照してください。

セキュリティの警告

ルールの対象 URL の生成には注意してください。あなたのサーバがプロキシ として振る舞う可能性のある URL に対して、クライアントへの影響があります。 これによるセキュリティインパクトを考慮してください。URL のうち、スキームとホスト名 の部分をそれぞれ確実に固定してください。そうでないと、クライアントに不当な影響を 与えかねません。

ProxyPassReverse ディレクティブ

説明: | リバースプロキシされたサーバから送られた HTTP レスポンスヘッダの URL を調整する
構文: | ProxyPassReverse [path] url [interpolate]
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_proxy

このディレクティブは Apache に HTTP リダイレクト応答の Location, Content-Location, URI ヘッダの調整をさせます。これは、Apache がリバースプロキシ (ゲートウェイ) として使われているときに、リバースプロキシを通らないアクセスを防止するのに重要です。 このようなアクセスは、リバースプロキシの背後にいるバックエンドサーバへの HTTP リダイレクトが原因で起きます。

上記の特別なリダイレクト用の HTTP レスポンスヘッダのみが書き換えられます。 Apache は他のレスポンスヘッダを書き換えたり、HTML ページの中の URL 参照を 書き換えたりすることはありません。つまり、リバースプロキシされた HTML ページ内に 絶対 URL 参照が存在すると、プロキシを通さずにアクセスする可能性があります。 HTML の中を見て、URL 参照を書き換えるモジュールに Nick Kew さんの mod_proxy_html があります。

path はローカル仮想パスの名前です。url は リモートサーバの部分 URL です。これらは ProxyPass ディレクティブと同様です。

例えば、ローカルサーバのアドレスが http://example.com/ だとします。すると

ProxyPass /mirror/foo/ http://backend.example.com/
ProxyPassReverse /mirror/foo/ http://backend.example.com/
ProxyPassReverseCookieDomain backend.example.com public.example.com
ProxyPassReverseCookiePath / /mirror/foo/

という設定をすると、http://example.com/mirror/foo/bar へのローカルリクエストが http://backend.example.com/bar へのプロキシリクエストに内部で変換されるだけではありません (これは ProxyPass の機能です)。backend.example.com サーバが送るリダイレクトの面倒もみます。http://backend.example.com/bar が http://backend.example.com/quux にリダイレクトされたとき、 Apache は HTTP リダイレクト応答をクライアントに送る前に、リダイレクト先を http://example.com/mirror/foo/quux に変更します。 URL を構成するのに使われるホスト名は UseCanonicalName の設定に応じて選択されることに 注意してください。

ProxyPassReverse ディレクティブは 対応する ProxyPass ディレクティブと独立して利用できるので、 mod_rewrite のプロキシ通過機能 (RewriteRule ... [P]) と併せて使用することもできます。

オプショナルな interpolate キーワード (httpd 2.2.9 以降で利用可能) を ProxyPassInterpolateEnv ディレクティブと 一緒に使うと、${VARNAME} 形式で、 ProxyPassReverse 設定に環境変数を 使えるようになります。

<Location> セクションの中で使われた場合は、 最初の引数は省略され、ローカルディレクトリは <Location> から取得されます。 同じことは <LocationMatch> セクション内でも起きますが、 おそらく意図どおりに動きません。と言うのも、ProxyPassReverse が正規表現をそのまま文字列でパスとして解釈しようとするからです。 もしこのような状況で必要なら、セクションの外で ProxyPassReverse を指定するか、あるいは別の <Location> セクション内で指定してください。

このディレクティブは <Directory> や <Files> セクション内では使えません。

ProxyPassReverseCookieDomain ディレクティブ

説明: | リバースプロキシサーバからの Set-Cookie ヘッダの Domain 文字列を 調整する
構文: | ProxyPassReverseCookieDomain internal-domain public-domain [interpolate]
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_proxy

使用法は基本的に ProxyPassReverse と同じですが、 ヘッダの URL の代わりに Set-Cookie ヘッダ内の domain 文字列を書き換えます。

ProxyPassReverseCookiePath ディレクティブ

説明: | リバースプロキシサーバからの Set-Cookie ヘッダの Path 文字列を 調整する
構文: | ProxyPassReverseCookiePath internal-path public-path [interpolate]
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_proxy

バックエンドの URL パスがリバースプロキシ上の公開パスにマップされる状況で、 ProxyPassReverse といっしょに 役立ちます。このディレクティブは Set-Cookie ヘッダ内の path 文字列を書き換えます。もしクッキーのパスが internal-path に先頭マッチすれば、クッキーのパスは public-path に置換されます。

ProxyPassReverse での例を使うと、ディレクティブ:

ProxyPassReverseCookiePath / /mirror/foo/

は、バックエンドのパスが / (あるいは /example あるいは実際のところなんでも) のクッキーを /mirror/foo/ に書き換えます。

ProxyPreserveHost ディレクティブ

説明: | プロキシリクエストに、受け付けた Host HTTP ヘッダを使う
構文: | ProxyPreserveHost On|Off
デフォルト: | ProxyPreserveHost Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy
互換性: | Apache 2.0.31 以降で使用可能

このオプションが有効になっている場合、ProxyPass で指定したホスト名の代わりに、受け付けたリクエストの Host: 行を プロキシ先のホストに送ります。

このオプションは通常は Off に設定してください。 ほとんどの場合、これは大量の名前ベースのバーチャルホスティングを行なっていて、 元々の Host ヘッダをバックエンドサーバが解釈する必要のあるときのような、 特別な設定が必要な場合にのみ有用です。

ProxyReceiveBufferSize ディレクティブ

説明: | プロキシされる HTTP と FTP 接続のためのネットワークバッファサイズ
構文: | ProxyReceiveBufferSize bytes
デフォルト: | ProxyReceiveBufferSize 0
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy

ProxyReceiveBufferSize ディレクティブは スループットを上げるために明示的に (TCP/IP) ネットワークバッファのサイズを 設定します。値は 512 以上か、システムのデフォルトのバッファ サイズを意味する 0 でなければなりません。

例

ProxyReceiveBufferSize 2048

ProxyRemote ディレクティブ

説明: | 特定のリクエストを扱う時に使われるリモートプロキシを指定する
構文: | ProxyRemote match remote-server
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy

このディレクティブはこのプロキシに対するリモートプロキシを定義します。 match はリモートプロキシがサポートする URL スキーム、 あるいはリモートプロキシを使うべき URL の一部分、あるいはすべての リクエストにリモートプロキシが使われることを示す * のどれかになります。 remote-server はリモートプロキシの部分 URL です。構文:

remote-server = scheme://hostname[:port]

scheme は実際上リモートサーバとの通信に使われるプロトコルを 決定します。このモジュールでは http と https だけがサポートされています。 https が使われると、HTTP CONNECT メソッドを使って リクエストはリモートプロキシに転送されます。

例

ProxyRemote http://goodguys.example.com/ http://mirrorguys.example.com:8000
ProxyRemote * http://cleverproxy.localdomain
ProxyRemote ftp http://ftpproxy.mydomain:8080

最後の例では、プロキシは FTP リクエストを別の HTTP リクエストで包んで そのようなリクエストを扱える別のプロキシに転送します。

このオプションはリバースプロキシの設定もサポートします。 バックエンドウェブサーバが別のフォワードプロキシの後ろに隠されている場合でも バックエンドウェブサーバをバーチャルホストの URL 空間に入れることが できます。

ProxyRemoteMatch ディレクティブ

説明: | 正規表現でのマッチによるリクエストを扱うリモートプロキシの指定
構文: | ProxyRemoteMatch regex remote-server
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy

ProxyRemoteMatch は最初の引数がリクエストされた URL にマッチする正規表現であることを除けば ProxyRemote ディレクティブと同じです。

ProxyRequests ディレクティブ

説明: | フォワード (標準の) プロキシリクエストを有効にする
構文: | ProxyRequests On|Off
デフォルト: | ProxyRequests Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy

これは Apache のフォワードプロキシサーバとしての動作を 有効もしくは無効にします。(ProxyRequests を Off に 設定しても、ProxyPass の設定は無効になりません。)

通常のリバースプロキシ/ゲートウェイの設定では、このオプションは Off に設定してください。

HTTP や FTP サイトへのプロキシの機能を有効にしたい場合は、 mod_proxy_http や mod_proxy_ftp が サーバに組み込まれていなければなりません。

警告

サーバを安全にするまで ProxyRequests は有効にしないでください。 オープンプロキシサーバはあなた自身のネットワークにとっても、 インターネット全体にとっても危険です。

参照

  • フォワードプロキシとリバースプロキシ/ゲートウェイ

ProxySet ディレクティブ

説明: | プロキシのバランサやメンバのパラメータをセット
構文: | ProxySet url key=value [key=value ...]
コンテキスト: | ディレクトリ
ステータス: | Extension
モジュール: | mod_proxy
互換性: | ProxySet は Apache 2.2 以降でのみ使用可能

このディレクティブは、通常は ProxyPass ディレクティブで行うプロキシのバランサやワーカーに対するパラメータを 別の方法で設定できるようにします。 <Proxy balancer url|worker url> ディレクティブのコンテナ内で使う場合、url 引数は必要ありません。 副次的に、それぞれのバランサやワーカーが生成されます。 ProxyPass ディレクティブではなく、 RewriteRule でリバースプロキシ 設定をする時にこのディレクティブは有用です。

<Proxy balancer://hotcluster>
BalancerMember http://www2.example.com:8009 loadfactor=1
BalancerMember http://www3.example.com:8009 loadfactor=2
ProxySet lbmethod=bytraffic
 </Proxy>

<Proxy http://backend>
ProxySet keepalive=On
 </Proxy>

ProxySet balancer://foo lbmethod=bytraffic timeout=15

ProxySet ajp://backend:7001 timeout=15

警告

設定対象がバランサかワーカーかで、パラメータ名が同じでも意味が異なる可能性 に注意してください。例えば、タイムアウトに関連する上記ふたつの例がそうです。

ProxyStatus ディレクティブ

説明: | mod_status でプロキシのロードバランサの状態を表示
構文: | ProxyStatus Off|On|Full
デフォルト: | ProxyStatus Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy
互換性: | Apache 2.2 以降で使用可能

このディレクティブは mod_status によるサーバステータスのページ にプロキシのロードバランサの状態を表示するか否かを決めます。

注意

Full は On の別名です。

ProxyTimeout ディレクティブ

説明: | プロキシされたリクエストのネットワークタイムアウト
構文: | ProxyTimeout seconds
デフォルト: | Timeout の値
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy
互換性: | Apache 2.0.31 以降で使用可能

このディレクティブはユーザがプロキシリクエストのタイムアウトを 指定できるようにします。これはハングしてしまうほど遅い、もしくは挙動の 怪しいサーバがあり、サーバがデータを返すまでひたすら待ち続けるよりも タイムアウトを返してより緩やかに(訳注: graceful に) 失敗させたい場合に役に立ちます。

ProxyVia ディレクティブ

説明: | プロキシされたリクエストの Via HTTP レスポンスヘッダ により提供される情報
構文: | ProxyVia On|Off|Full|Block
デフォルト: | ProxyVia Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_proxy

このディレクティブはプロキシの Via: HTTP ヘッダの使用を 制御します。想定されている使い方は、プロキシサーバがいくつも繋がっているときに プロキシリクエストの流れを制御することです。Via: ヘッダ行の 説明は RFC 2616 (HTTP/1.1) の 14.45 節を読んでください。

  • デフォルトの Off に設定されていると、特別な処理は 行なわれません。リクエストやリプライに Via: ヘッダがあれば、 変更されずにそのまま渡します。
  • On に設定されていれば、各リクエストとリプライに Via: 行が追加されます。
  • Full に設定されていれば、Via: ヘッダは コメント部分に Apache サーバのバージョンも含むようになります。
  • Block に設定されていれば、すべてのプロキシリクエストから Via: ヘッダが取り除かれます。新たに Via: が 生成されることはありません。


mod_proxy_ajp - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_proxy_ajp

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | mod_proxy で AJP をサポートするためのモジュール
ステータス: | Extension
モジュール識別子: | proxy_ajp_module
ソースファイル: | mod_proxy_ajp.c

概要

本モジュールには mod_proxy が必要です。 Apache JServ Protocol version 1.3 (以降 AJP13) をサポートします。

AJP13 プロトコルを扱えるようにするには mod_proxy と mod_proxy_ajp をサーバに組み込む必要があります。

警告

安全なサーバにするまでプロクシ機能は有効にしないでください。 オープンプロキシサーバはあなた自身のネットワークにとっても、 インターネット全体にとっても危険です。

参照

  • mod_proxy

プロトコルの概要

AJP13 プロトコルはパケット指向です。 可読なプレーンテキスト形式ではなくバイナリ形式になったのは、 おそらくパフォーマンス上の理由によります。 ウェブサーバはサーブレットコンテナと TCP コネクションで通信します。 ソケット生成は重い処理なので、負荷を減らすために、サーブレットコンテナとの TCP 接続を維持し、複数のリクエスト・レスポンス処理サイクルに対して一つの コネクションを使いまわすようになっています。

あるリクエストにコネクションが割り当てられると、その処理サイクルが 完了するまで他のものに使われることはありません。 つまりコネクション上では、リクエストの同時処理は行われません。 このため、コネクション両端での実行するコードを簡潔にできる一方で、 同時に開くコネクションは多くなっています。

サーブレットコンテナへのコネクションを開いた後は、コネクションの状態は 次のどれかになります:

  • Idle
    コネクション上で処理されているリクエストはありません。
  • Assigned
    コネクションはリクエストを処理中です。

コネクションが特定のリクエストにアサインされると、基本的な情報 (例えば HTTP ヘッダ等) が圧縮された形 (例えば通常の文字列は整数にエンコードされます) で転送されます。詳細は下記の「リクエストパケットの構造」を参照してください。 リクエストにボディが存在 (content-length > 0) すれば、 基本的な情報の直後に別パケットで転送されます。

この時点でおそらく、サーブレットコンテナは処理を開始できるようになります。 ですので、次のメッセージをウェブサーバに戻して知らせられるようになります。

  • SEND_HEADERS
    ブラウザにヘッダを送信します。
  • SEND_BODY_CHUNK
    ブラウザにボディデータのチャンクを送ります。
  • GET_BODY_CHUNK
    リクエストのデータを全て受け取り終わっていないときに、 残っているデータを受け取ります。パケットにある定まった最大長があり、任意の 大きさのデータがリクエストのボディとして含まれうる場合 (例えばファイルのアップロードの場合) に必要となります。 (注: HTTP のチャンク転送とは関連ありません。)
  • END_RESPONSE
    リクエスト処理サイクルを終了します。

個々のメッセージはそれぞれ異なるデータパケット形式になっています。 後述の「レスポンスパケットの構造」を参照してください。

基本パケット構造

このプロトコルには XDR から受け継いだ部分が少しありますが、多くの点で 異なります (例えば 4 バイトアライメントでないことなど) 。

バイトオーダー: 個々のバイトのエンディアンがどうなっているかは、 私は詳しくないのですが、リトルエンディアンになっていると思います。 XDR 仕様でそうなっているのと、素晴らしいことに sys/socket ライブラリが (C で) そういう風にできているのでそうなのだと思いました。 ソケット呼び出しの内部についてより詳しい方がいらっしゃいましたら、 ご教授ください。

プロトコルには 4 つのデータタイプがあります: byte, boolean, integer, string です。

Byte
バイト一つです。
Boolean
バイト一つで、1 = true, 0 = false です。 (C のように) 非零を真として扱ってしまうと、ある場合は動くかもしれませんし、 動かないかもしれません。
Integer
0 から 2^16 (32768) の範囲の数字。高次の 2 バイトが 先に格納されます。
String
可変長の文字列 (2^16 が長さの上限) 。長さ情報のパケット 2 バイトの後に 文字列 (終端文字 '\0' を含む) が続く形式でエンコードされます。 エンコードされている長さ情報は最後の '\0' をカウントしない ことに注意してください――これは strlen と同様です。 これらの終端文字をスキップするために、あまり意味の無いインクリメント文 をたくさん書かないといけないのは、 Java の側から見ると少し紛らわしく感じられるかもしれません。 こうなった理由はおそらく、Servlet コンテナから返される文字列を読み出す時に、 効率よく C のコードを書けるようにする――サーブレットから返される 文字列は \0 文字で終端されているので、C のコードではわざわざコピーをせずに、 一つのバッファへのリファレンスを取り回すように書くことができる―― ためだと思われます。 '\0' 文字がない場合は、C では文字列の規則に合うようにコピーしなければ いけなくなってしまいます。

パケットサイズ

多くのコードでそうなっているのですが、パケットサイズの最大サイズは 8 * 1024 (8K) です。パケットの実際の長さはヘッダに エンコードされて入っています。

パケットヘッダ

サーバからコンテナに送出されるパケットは 0x1234 で始まります。 コンテナからサーバに送られるパケットは AB (ASCII コード A と ASCII コード B) で始まります。この二バイトの後に、ペイロード長が (上記の形式で) 続きます。このため、ペイロード長の最大値は 2^16 にできるように思えますが、 実際にはコードでは最大値は 8K に設定されています。

パケット形式 (Server->Container)
Byte | 0 | 1 | 2 | 3 | 4...(n+3)
Contents | 0x12 | 0x34 | データ長 (n) |  | Data
パケット形式 (Container->Server)
Byte | 0 | 1 | 2 | 3 | 4...(n+3)
Contents | A | B | データ長 (n) |  | Data

ほとんどのパケットで、ペイロードの最初のバイトがメッセージの型をエンコード しています。例外はサーバからコンテナに送られるリクエストボディパケットです ――これらは標準的なパケット形式 (0x1234 とパケット長) ですが、その後に続くプレフィックスコードがありません。

ウェブサーバは次のメッセージをサーブレットコンテナに送出できます。

コード | パケットの型 | 意味
2 | Forward Request | リクエスト処理サイクルを後続のデータとともに開始する。
7 | Shutdown | ウェブサーバがコンテナに、コンテナを終了するように伝える。
8 | Ping | ウェブサーバがコンテナに制御を受け持つように伝える (セキュアログインフェーズ) 。
10 | CPing | ウェブサーバがコンテナに CPong で即座に応答するように伝える。
none | Data | サイズ (2 バイト) とそれに続くボディデータ。

基本的なセキュリティを確保するため、ホストされているマシンと同一の マシンからのリクエストに対してのみ、コンテナは実際に Shutdown を実行します。

最初の Data パケットは、Forward Request の直後にウェブサーバから送られます。

サーブレットコンテナはウェブサーバに、次のタイプのメッセージを送ることが できます :

コード | パケットの型 | 意味
3 | Send Body Chunk | サーブレットコンテナからウェブサーバに (そしておそらくそのままブラウザに)、ボディのチャンクを送る。
4 | Send Headers | サーブレットコンテナからウェブサーバに (そしておそらくそのままブラウザに) レスポンスヘッダを送る。
5 | End Response | レスポンス (つまりリクエスト処理サイクル) 終了の目印を送る。
6 | Get Body Chunk | まだ全て転送されていない場合、残っているリクエストのデータを受け取る。
9 | CPong 応答 | CPing リクエストに応答する。

上記メッセージは、それぞれ内部構造が異なっています。詳細は下記をご覧ください。

リクエストパケット構造

サーバからコンテナへ送られるメッセージが Forward Request 型の場合 :

AJP13_FORWARD_REQUEST :=
    prefix_code      (byte) 0x02 = JK_AJP13_FORWARD_REQUEST
    method           (byte)
    protocol         (string)
    req_uri          (string)
    remote_addr      (string)
    remote_host      (string)
    server_name      (string)
    server_port      (integer)
    is_ssl           (boolean)
    num_headers      (integer)
    request_headers *(req_header_name req_header_value)
    attributes      *(attribut_name attribute_value)
    request_terminator (byte) OxFF

request_headers は次のような構造になっています :

req_header_name :=
    sc_req_header_name | (string)  [see below for how this is parsed]

sc_req_header_name := 0xA0xx (integer)

req_header_value := (string)

属性 はオプションで、次のような構造をしています :

attribute_name := sc_a_name | (sc_a_req_attribute string)

attribute_value := (string)

もっとも重要なヘッダは content-length だということに 注意してください。コンテナは次のパケットを探すかどうかを、 それを見て決めるからです。

Forward Request 要素の詳細な説明

Request prefix

リクエストについては全て、この値は 2 になります。他の Prefix コードの詳細は 上記をご覧ください。

Method

HTTP メソッドは 1 バイトにエンコードされます :

Command Name | Code
OPTIONS | 1
GET | 2
HEAD | 3
POST | 4
PUT | 5
DELETE | 6
TRACE | 7
PROPFIND | 8
PROPPATCH | 9
MKCOL | 10
COPY | 11
MOVE | 12
LOCK | 13
UNLOCK | 14
ACL | 15
REPORT | 16
VERSION-CONTROL | 17
CHECKIN | 18
CHECKOUT | 19
UNCHECKOUT | 20
SEARCH | 21
MKWORKSPACE | 22
UPDATE | 23
LABEL | 24
MERGE | 25
BASELINE_CONTROL | 26
MKACTIVITY | 27

今後の ajp13 バージョンでは、この一覧にない、今後追加されるメソッドを 送るかもしれません。

protocol, req_uri, remote_addr, remote_host, server_name, server_port, is_ssl

これらはまさに文字通りのものです。どれも必要で、リクエストの毎回につき 送られます。

Headers

request_headers の構造は次のようなものです : まずヘッダの数 num_headers がエンコードされます。 次にヘッダ名 req_header_name / 値 req_header_value の組が続きます。効率のため、一般的なヘッダは整数でエンコードして転送します。 ヘッダ名が基本ヘッダの一覧に無い場合は、通常通り (文字列として、長さ プレフィックス付きで) 転送されます。一般的なヘッダ sc_req_header_name の一覧とそのコードは次の通りです (どれも大文字小文字を区別します) :

名前 | コードの値 | コード名
accept | 0xA001 | SC_REQ_ACCEPT
accept-charset | 0xA002 | SC_REQ_ACCEPT_CHARSET
accept-encoding | 0xA003 | SC_REQ_ACCEPT_ENCODING
accept-language | 0xA004 | SC_REQ_ACCEPT_LANGUAGE
authorization | 0xA005 | SC_REQ_AUTHORIZATION
connection | 0xA006 | SC_REQ_CONNECTION
content-type | 0xA007 | SC_REQ_CONTENT_TYPE
content-length | 0xA008 | SC_REQ_CONTENT_LENGTH
cookie | 0xA009 | SC_REQ_COOKIE
cookie2 | 0xA00A | SC_REQ_COOKIE2
host | 0xA00B | SC_REQ_HOST
pragma | 0xA00C | SC_REQ_PRAGMA
referer | 0xA00D | SC_REQ_REFERER
user-agent | 0xA00E | SC_REQ_USER_AGENT

これを読み込む Java のコードでは、最初の 2 バイト整数を取り込み、 目印になるバイト '0xA0' であれば、ヘッダ名の配列の インデックスを使います。先頭バイトが 0xA0 でない場合は、 先頭 2 バイトは文字列長を表す整数であると解釈し、読み込みはじめます。

ヘッダ名の長さは 0x9999 (==0xA000 -1) 以上にならないという 仮定の下に動いていて、少しあいまいですが合理的な挙動になっています。

注:

content-length ヘッダはとても重要です。 存在していて非ゼロであれば、リクエストにはボディがある (例えば POST リクエスト) と推測し、そのボディを取り込むために 直後のパケットを入力ストリームから読み込みはじめます。

属性

? プレフィックスで始まる属性 (例 ?context) は。省略可能です。それぞれ属性の型を示す 1 バイトのコードと、 値の文字列が続きます。 これらは順不同で送ることができます (C のコードは常に下の一覧順に 送るようですが) 。 オプションの属性のリストの最後には、特別な終了コードが送られます。 コードの一覧は :

Information | Code Value | Note
?context | 0x01 | 未実装
?servlet_path | 0x02 | 未実装
?remote_user | 0x03 |
?auth_type | 0x04 |
?query_string | 0x05 |
?jvm_route | 0x06 |
?ssl_cert | 0x07 |
?ssl_cipher | 0x08 |
?ssl_session | 0x09 |
?req_attribute | 0x0A | Name (the name of the attribute follows)
?ssl_key_size | 0x0B |
are_done | 0xFF | request_terminator

context と servlet_path は現在の C の コードではセットされていません。また、ほとんどの Java のコードでも、 このフィールドで何が送られても無視されます (これらのコードの後に文字列が 送られると壊れるものもあります)。 これがバグなのか、単に未実装なのか、歴史的経緯で残っているコードなのか 分かりませんが、コネクションの両側ともで見当たりません。

remote_user と auth_type はおそらく HTTP レベルの認証を参照していて、リモートユーザのユーザ名と認証に使用した タイプ (例 Basic, Digest) についてやり取りします。

query_string, ssl_cert, ssl_cipher, ssl_session は HTTP と HTTPS の対応する部分を参照します。

jvm_route はスティッキーセッションのサポート―― ロードバランスしている複数のサーバ中の特定の Tomcat インスタンスと、 ユーザのセッションとを紐付ける機能――に使われます。

この基本属性一覧に無いものについては、req_attribute コード 0x0A 経由で属性を何個でも送ることができます。 属性の名前と値の文字列の組を、それぞれこのコードの直後に送ります。 環境変数はこの方法で伝えられます。

最後に属性が全て送信された後に、属性の終端を示す 0xFF が送出されます。この信号は属性の一覧の終わりを示すと同時に、リクエスト パケットの終端をも示しています。

レスポンスパケット構造

コンテナがサーバに送り返すことのできるメッセージ:

AJP13_SEND_BODY_CHUNK :=
  prefix_code   3
  chunk_length  (integer)
  chunk        *(byte)

AJP13_SEND_HEADERS :=
  prefix_code       4
  http_status_code  (integer)
  http_status_msg   (string)
  num_headers       (integer)
  response_headers *(res_header_name header_value)

res_header_name :=
    sc_res_header_name | (string)   [see below for how this is parsed]

sc_res_header_name := 0xA0 (byte)

header_value := (string)

AJP13_END_RESPONSE :=
  prefix_code       5
  reuse             (boolean)

AJP13_GET_BODY_CHUNK :=
  prefix_code       6
  requested_length  (integer)

詳細 :

Send Body Chunk

チャンクは基本的にはバイナリデータで、ブラウザに直接送られます。

Send Headers

ステータスコードとメッセージが通常の HTTP の通信にはあります (例 200 と OK)。レスポンスヘッダ名は、 リクエストヘッダ名と同様の方法でエンコードされます。 コードと文字列の判別方法の詳細に関しては、上記の header_encoding を参照してください。 一般的なヘッダのコードは :

名前 | コードの値
Content-Type | 0xA001
Content-Language | 0xA002
Content-Length | 0xA003
Date | 0xA004
Last-Modified | 0xA005
Location | 0xA006
Set-Cookie | 0xA007
Set-Cookie2 | 0xA008
Servlet-Engine | 0xA009
Status | 0xA00A
WWW-Authenticate | 0xA00B

コードかヘッダ文字列の直後には、ヘッダの値がエンコードされます。

End Response

リクエスト処理サイクルの終了を知らせます。reuse フラグが真 (==1) の場合、現在使用している TCP コネクションは次の新しい リクエストに使えるようになります。reuse が偽 (C のコードでは 1 以外の全て) の場合は、コネクションを閉じることになります。

Get Body Chunk

(ボディのサイズが大きすぎて最初のパケットに収まらない場合や、 リクエストがチャンク転送された場合などには、) コンテナはリクエストからの データ読み込み要求をします。サーバ側はそれに対して、最小 request_length 最大 (8186 (8 Kbytes - 6)) の範囲で、未転送で残っているリクエストボディの大きさのデータを 送り返します。
ボディにそれ以上データが残っていない場合 (つまりサーブレットが ボディの最後を超えて読み込もうとした場合) 、サーバは ペイロード長 0 の空パケット(0x12,0x34,0x00,0x00) を送り返します。


mod_proxy_balancer - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_proxy_balancer

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | 負荷分散のための mod_proxy 拡張
ステータス: | Extension
モジュール識別子: | proxy_balancer_module
ソースファイル: | mod_proxy_balancer.c
互換性: | Apache 2.1 以降で使用可能

概要

本モジュールには mod_proxy が必要です。 本モジュールは HTTP と FTP と AJP13 プロトコルのロードバランス機能を持っています。

ですから、 ロードバランスを有効にする場合 mod_proxy と mod_proxy_balancer がサーバに組み込まれて いなければいけません。

警告

安全なサーバにするまでプロキシ機能は有効にしないでください。 オープンプロキシサーバはあなた自身のネットワークにとっても、 インターネット全体にとっても危険です。

参照

  • mod_proxy

ロードバランサのスケジューラのアルゴリズム

現時点では 3 種類のロードバランサスケジューラアルゴリズムから選べます。 リクエスト回数によるもの (訳注: Request Counting) 、トラフィック量によるもの (訳注: Weighted Traffic Counting) と、処理中リクエスト数によるもの (訳注: Pending Request Counting) とがあります。バランサの設定 lbmethod 値で、どれを使うか指定します。 詳細は ProxyPass ディレクティブを 参照してください。

ロードバランサのスティッキネス

バランサはスティッキネスをサポートします。リクエストがあるバックエンドに プロキシされた時、続く同じユーザからのリクエストは、すべてその同じバックエンドに プロキシされるべきです。多くのロードバランサはこの機能をクライアントの IP アドレスとバックエンドの対応表を持つことで実現します。 この方法はクライアントにもバックエンドにも透過に動作しますが、 次に挙げるいくつかの問題があります。 もしクライアント自身がプロキシの背後にいる場合、負荷分散が不均一になります。 もし動的な IP アドレスを持つクライアントのアドレスがセッション中に変わると スティッキネスは期待どおりに動作しません。 もし対応表があふれると、スティッキネスが失われます。

mod_proxy_balancer はスティッキネスを 2 種類の別手法をもとに実装しています。クッキーと URL エンコーディングのふたつです。 クッキーはバックエンドもしくは Apache Web サーバ自身により提供されます。 URL エンコーディングは通常バックエンドにより行われます。

ロードバランサの設定例

技術的な詳細に入る前に例を示します。以下は、2 台のバックエンドサーバを ロードバランスするための mod_proxy_balancer の使い方の一例です:

<Proxy balancer://mycluster>
BalancerMember http://192.168.1.50:80
BalancerMember http://192.168.1.51:80
</Proxy>
ProxyPass /test balancer://mycluster

別の例として、mod_headers を使ってスティッキネス を実現するロードバランサの設定例を示します。バックエンドのサーバが 適切なセッションクッキーをセットしなくても動作します。

Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED
<Proxy balancer://mycluster>
BalancerMember http://192.168.1.50:80 route=1
BalancerMember http://192.168.1.51:80 route=2
ProxySet stickysession=ROUTEID
</Proxy>
ProxyPass /test balancer://mycluster

Request Counting アルゴリズム

lbmethod=byrequests で有効になります。 このスケジューラの背景にある考え方は、様々なワーカーがそれぞれ、 設定されている分担リクエスト数をきちんと受け取れるように、 リクエストを扱うという考え方です。次のように動作します:

lbfactor は、どの程度ワーカーに仕事を振るか つまりワーカーのクオータを指します。この値は "分担" 量を表す正規化された値です。

lbstatus は、ワーカーのクオータを満たすために どのぐらい急ぎで働かなければならないかを指します。

ワーカーはロードバランサのメンバで、通常は、 サポートされるプロトコルのうちの一つを提供しているリモートホストです。

まず個々のワーカーにワーカークオータを割り振り、どのワーカーが最も急ぎで 働かなければならないか (lbstatus が最大のもの) を調べます。 次に仕事をするようにこのワーカーを選択し、選択したワーカーの lbstatus から全ワーカーに割り振ったクオータの合計を引きます。ですから、lbstatus の総量は 結果的に変化しません(*)し、リクエストは期待通りに分散されます。

あるワーカーが無効になっても、他のものは正常にスケジュールされ続けます。

for each worker in workers
    worker lbstatus += worker lbfactor
    total factor    += worker lbfactor
    if worker lbstatus > candidate lbstatus
        candidate = worker

candidate lbstatus -= total factor

バランサを次のように設定した場合:

worker | a | b | c | d
lbfactor | 25 | 25 | 25 | 25
lbstatus | 0 | 0 | 0 | 0

そして b が無効になった場合、次のようなスケジュールが 行われます。

worker | a | b | c | d
lbstatus | -50 | 0 | 25 | 25
lbstatus | -25 | 0 | -25 | 50
lbstatus | 0 | 0 | 0 | 0
(repeat)

つまりこのようにスケジュールされます: a c d a c d a c d ... 次の点に注意してください:

worker | a | b | c | d
lbfactor | 25 | 25 | 25 | 25

この挙動は、次の設定と全く同じになります:

worker | a | b | c | d
lbfactor | 1 | 1 | 1 | 1

と言うのも、lbfactor の値は全て正規化されたもので、 他との相対値だからです。次の設定では:

worker | a | b | c
lbfactor | 1 | 4 | 1

ワーカー b は、平均して、a と c の 4 倍の数のリクエストを受け持つことになります。

次のような非対称な設定では、こうなると予想されるでしょう:

worker | a | b
lbfactor | 70 | 30
lbstatus | -30 | 30
lbstatus | 40 | -40
lbstatus | 10 | -10
lbstatus | -20 | 20
lbstatus | -50 | 50
lbstatus | 20 | -20
lbstatus | -10 | 10
lbstatus | -40 | 40
lbstatus | 30 | -30
lbstatus | 0 | 0
(repeat)

スケジュールは 10 スケジュール後に繰り返され、a 7 回と b 3 回でまばらに選ばれます。

Weighted Traffic Counting アルゴリズム

lbmethod=bytraffic で有効になります。 このスケジューラの背景にある考え方は、Request Counting と非常に似ていますが、次の違いがあります:

lbfactor は どれだけのバイト数のトラフィック量を、 このワーカーに処理してもらいたいか を表します。 この値も同様に正規化された値で、ワーカー全体のうちでの "分担" 量を表現しています。リクエスト数を単純に数える代わりに、 どれだけの転送量を処理したかを数えます。

次のようにバランサを設定した場合:

worker | a | b | c
lbfactor | 1 | 2 | 1

b には a や c の 2 倍 処理してほしいということになります。 b は 2 倍の I/O を処理するという意味になり、 2 倍のリクエスト数を処理するということにはなりません。 ですからリクエストとレスポンスのサイズが、 重み付けと振り分けのアルゴリズムに効いています。

Pending Request Counting アルゴリズム

lbmethod=bybusyness で有効になります。このスケジューラは 現在どのぐらいのリクエストが個々のワーカーにアサインされているかを把握しています。 新しいリクエストは、最も処理途中のリクエスト数が少ないワーカーに 自動的に割り振られます。これは、ワーカーが Apache と無関係に入力リクエストを キューに溜め込む場合に有効で、キューの長さを同程度に維持しつつも、 最も早く処理できそうなワーカーに常にリクエストを割り振ります。

複数のワーカーが最少の処理中リクエスト数で並んだ場合、Request Counting アルゴリズムと同じ統計情報（と重み付け）を使って順番を決めます。 時間が経つと、割り振りの割合は byrequests と似たような 傾向を示すようになるでしょう。

このアルゴリズムは Apache HTTP サーバ 2.2.10以降で利用可能です。

エクスポートされる環境変数

現在、6 つの環境変数がエクスポートされます:

BALANCER_SESSION_STICKY

現在のリクエストに使われる stickysession 値になります。 スティッキーセッションのためのクッキー名もしくはリクエストパラメータ名です。

BALANCER_SESSION_ROUTE

現在のリクエストをパースして得られる route 値です。

BALANCER_NAME

現在のリクエストが使うバランサ名です。balancer://foo のような値です。

BALANCER_WORKER_NAME

現在のリクエストが使うワーカー名です。http://hostA:1234 のような値です。

BALANCER_WORKER_ROUTE

現在のリクエストが使うワーカーの route 値です。

BALANCER_ROUTE_CHANGED

セッションルートとワーカールートが一致しない時 (BALANCER_SESSION_ROUTE != BALANCER_WORKER_ROUTE) あるいは、セッションがまだルートを確立していない時、値が 1 になります。 スティッキーセッションを使う時、ルートの更新をクライアントに送る必要があるかを 判断するためにこの環境変数を使えます。

バランサマネージャのサポートを有効にする

このモジュールは mod_status のサービスを 必要とします。 バランサマネージャを使うと、バランサのメンバーの動的な更新が できます。バランサマネージャを使って、バランス係数 (lbfactor) を変更したり、メンバーを変更したり、特定のメンバーを オフラインモードにしたりできます。

ですから、ロードバランサ管理機能を使いたければ、 mod_status と mod_proxy_balancer をサーバに組み込まなければなりません。

example.com ドメインのブラウザからロードバランサ管理機能を 使えるようにするには、次のようなコードを httpd.conf に追加します。

<Location /balancer-manager>
SetHandler balancer-manager

Order Deny,Allow
Deny from all
Allow from .example.com
</Location>

こうすると、http://your.server.name/balancer-manager のページ経由で、ウェブブラウザからロードバランサマネージャに アクセスできるようになります。

ロードバランサのスティッキネスの詳細

クッキーをもとにスティッキネスを使う場合、どのバックエンドに割り振るべきか を決めるクッキーの名前を指定する必要があります。 クッキー名は ProxyPass または ProxySet のいずれか に付与する stickysession 属性で設定します。 クッキー名は大文字小文字を区別します。 バランサはそのクッキーの値を取り出し、その値に一致する route 値の ワーカーを探します。 route も ProxyPass または ProxySet のいずれかに設定しなければいけません。 クッキーはバックエンドによって設定されるか、あるいは 上記の 例 のように Apache Web サーバ自身 によって設定されます。

バックエンドの中の一部は少し異なる形式のスティッキネスクッキーを使います。 たとえば Apache Tomcat がそうです。Tomcat は自身のインスタンス名を セッション ID のクッキーの最後に付け加えます。この時、セッション ID との区切り文字にドット (.) を使います。 このため、Apache Web サーバがドットをスティッキネスクッキー値の中に見つけると、 route を探すためにドット以降の部分のみを使うようにします。 Tomcat 側で自身のインスタンス名を設定するには、Tomcat の設定ファイル conf/server.xml の中の jvmRoute 属性に 指定する必要があります。値はそれぞれの Tomcat に接続するワーカーの route 値と一致させます。 Tomcat およびサーブレットベースの Java Web アプリサーバが一般に使う セッションクッキーの名前は JSESSIONID (すべて大文字) です。 この名前は設定により変更も可能です。

スティッキネスを実装するふたつめの手段は URL エンコーディングです。 Web サーバはリクエストの URL の中からクエリパラメータを探します。 探すパラメータ名は同じように stickysession 属性で指定します。 パラメータ値と一致する route 値のワーカーを探します。 レスポンスに含まれるすべての URL リンクを探しだし書き換えるのは簡単ではないので、 一般にそれぞれのリンクにクエリパラメータを付け加えるのは、 そのコンテンツを生成したバックエンドの仕事です。 時には、mod_substitute を使って Web サーバにこの書き換えを させるのが可能な場合もあります。 ただし、パフォーマンスを落とす可能性があります。

Java 標準は URL エンコーディングを少し異なる形で実装します。 URL のパス情報をセミコロン (;) で区切って セッション ID を付け加えます。 クッキーの場合と同じように、 Apache Tomcat はこのパス情報に jvmRoute の設定値を含めます。 Apache にこの種のパス情報を見つけさせるには、 ProxyPass あるいは ProxySet の scolonpathdelim を On にします。

最後に、クッキーと URL エンコーディングの両方が指定できることを示します。 次の例のように、クッキー名と URL パラメータ名を垂直バー (|) で区切って指定します:

ProxyPass /test balancer://mycluster stickysession=JSESSIONID|jsessionid scolonpathdelim=On
<Proxy balancer://mycluster>
BalancerMember http://192.168.1.50:80 route=node1
BalancerMember http://192.168.1.51:80 route=node2
</Proxy>

もし同じリクエストが、クッキーとリクエストパラメータの両方のルーティング情報を 提供した場合、リクエストパラメータのほうが使われます。

ロードバランサのスティッキネスのトラブルシューティング

もしアプリのセッションが失われてユーザが再ログインしなければいけないなど スティッキネス関連のエラーに遭遇したら、 この原因はバックエンドの応答に支障があったせいか、 あるいは設定ミスによるものかを最初に切り分けたいでしょう。 バックエンドの安定性に関して起きうる問題を見つけるには、 Apache のエラーログにプロキシエラーのメッセージがないか確認してください。

設定が正しいかを確認するには、最初にスティッキネスを クッキーと URL エンコーディングのどちらで行っているかを確認してください。 次に、LogFormat を変更して アクセスログに適切なデータが残るようにするとよいでしょう。 次のフィールドが便利です:

%{MYCOOKIE}C
MYCOOKIE という名前のクッキーの値。 この名前は stickysession 属性の指定値と同じはずです。
%{Set-Cookie}o
これによりバックエンドがセットするクッキーをログに出せます。 バックエンドが期待するセッションクッキーをセットしているかと、 どんな値がセットされているかを追跡できます。
%{BALANCER_SESSION_STICKY}e
ルーティング情報を決めるために使われたクッキー名もしくは リクエストパラメータ名。
%{BALANCER_SESSION_ROUTE}e
リクエスト内に見つかった route 値の情報
%{BALANCER_WORKER_ROUTE}e
選択されたワーカーの route 値
%{BALANCER_ROUTE_CHANGED}e
リクエストの route 値がワーカーの route 値と異なる場合に 1 になります。つまり、リクエストはスティッキーとして 処理されていません。

セッションが失われる原因でよくあるものは、セッションタイムアウトですが、 これは通常バックエンドのサーバで変更可能です。

ログレベルを debug 以上に設定すると、 バランサはスティッキネス動作の詳細な情報をエラーログに書き出します。 これはスティッキネスの問題のトラブルシューティングする簡単な手法ですが、 高負荷な本番サーバではログの分量が膨大になってしまうかもしれません。


mod_proxy_connect - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_proxy_connect

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | CONNECT リクエストを扱う mod_proxy 用の拡張
ステータス: | Extension
モジュール識別子: | proxy_connect_module
ソースファイル: | mod_proxy_connect.c

概要

本モジュールには mod_proxy が必要です。 CONNECT HTTP メソッドをサポートします。 このメソッドは主にプロキシに SSL リクエストを通す (訳注: SSLトンネリング)に使われます。

CONNECT リクエストを扱えるようにするには mod_proxy と mod_proxy_connect をサーバに組み込む必要があります。

警告

安全なサーバにするまでプロキシ機能は有効にしないでください。 オープンプロキシサーバはあなた自身のネットワークにとっても、 インターネット全体にとっても危険です。

参照

  • AllowCONNECT
  • mod_proxy


mod_proxy_ftp - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_proxy_ftp

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | mod_proxy のための FTP サポートモジュール
ステータス: | Extension
モジュール識別子: | proxy_ftp_module
ソースファイル: | mod_proxy_ftp.c

概要

本モジュールには mod_proxy が必要です。 本モジュールは FTP サイトへのプロキシ機能を提供します。 現状、 FTP サポートは GET メソッドに限定されていることに注意してください。

FTP プロキシリクエストを扱うためには、mod_proxy と mod_proxy_ftpが サーバに組み込まれて いなければいけません。

警告

安全なサーバにするまでプロキシ機能は有効にしないでください。 オープンプロキシサーバはあなた自身のネットワークにとっても、 インターネット全体にとっても危険です。

参照

  • mod_proxy

なぜファイルタイプ xxx は FTP ダウンロードできないのでしょう?

おそらく、プロキシの mime.types 設定ファイルでそのファイルタイプを application/octet-stream として定義していないのでしょう。 以下の行が便利でしょう。

application/octet-stream   bin dms lha lzh exe class tgz taz

デフォルトで全てをバイナリにするのもいいかもしれません:

DefaultType application/octet-stream

ファイル xxx を ASCII モードで FTP ダウンロードさせるにはどうすればいいのでしょう?

稀に、特定のファイルを FTP の ASCII 転送モードでダウンロードしなければ ならない場合があります (なお、デフォルトの転送モードは binary です)。 この場合、リクエストの末尾に ;type=a を加えることで mod_proxy のデフォルト動作を変更して、 ASCII 転送モードにできます。 (一方、 FTP のディレクトリ一覧は常に ASCII モードです。)

FTP アップロードはできますか?

現状、 mod_proxy は FTP の GET のみサポートしています。 もちろん、 Apache プロキシで HTTP アップロード (POST または PUT) はできます。

ホームディレクトリ外のファイルに FTP アクセスするにはどうすればよいでしょうか?

FTP の URI はログイン中のユーザのホームディレクトリの相対パスとして 解釈されます。より上位のディレクトリに行くために /../ を使っても無駄です。 と言うのも、ドットふたつはブラウザが解釈するだけで、実際に FTP サーバには 送られないからです。この問題に対して、 Apache の FTP プロキシは いわゆる Squid %2f hack を実装しています; Squid Proxy Cache などの 他の有名なプロキシサーバも採用している解決方法です。 リクエストのパスの先頭に /%2f をつけると、これらのプロキシ は FTP のディレクトリを / 開始にします (ホームディレクトリではなく)。 例えば、/etc/motd ファイルを取得するには、次の URL を 使えばよいでしょう:

ftp://user@host/%2f/etc/motd

ブラウザの URL 欄に FTP のパスワードがそのまま 載らないようにするにはどうすればよいでしょうか?

FTP サーバにユーザ名とパスワードを使ってログインするために、 Apache は異なる戦略を使います。 URL にユーザ名もパスワードも無ければ、 Apache は FTP サーバに匿名 (anonymous) ログインしようとします。 例

user: anonymous
password: apache_proxy@

匿名アクセスを設定したすべての有名な FTP サーバでこれは動作します。

特定のユーザ名でログインするために、 URL に次のようにユーザ名を埋め込めます:

ftp://username@host/myfile

FTP サーバがこのユーザ名に対してパスワードを求めると (そうあるべきです) 、 Apache は 401 (Authorization required) レスポンスを返します。 これによりブラウザはユーザ名とパスワードを求めるダイアログ画面をポップアップします。 パスワードを入力すると、もう一度接続しなおし、認証が成功すると、 要求していたリソースが現れます。このやりとりの利点は、ブラウザがパスワードを そのまま表示しないことです。もし最初に次の URL を使っていると

ftp://username:password@host/myfile

パスワードがそのまま見えてしまいます。

注意

このように送信するパスワードはネットワーク上は暗号化されません。 ブラウザと Apache プロキシサーバの間は base64 エンコードした生パスワードで、 Apache プロキシサーバと FTP サーバの間はプレインテキストです。 このため、 HTTP 経由で FTP サーバにアクセスする時 (とにかく FTP で個人的な ファイルにアクセスする時 ) 、倍の慎重さが求められます。 安全でないネットワークを使っている場合、経路上でパスワードを盗み取られる 可能性があります。


mod_proxy_http - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_proxy_http

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | mod_proxy のための HTTP サポートモジュール
ステータス: | Extension
モジュール識別子: | proxy_http_module
ソースファイル: | mod_proxy_http.c

概要

本モジュールには mod_proxy が 必要です。 本モジュールは HTTP および HTTPS リクエストのプロキシに使う機能を提供します。 mod_proxy_http は、 HTTP/0.9 と HTTP/1.0 と HTTP/1.1 をサポートします。キャッシュ機能は 持ちません。 キャッシュ機能を持つプロキシを設定したい場合、mod_cache と組み合わせるのがよいでしょう。

HTTP リクエストのプロキシを有効にするには、mod_proxy と mod_proxy_http がサーバに組み込まれて いなければいけません。

警告

安全なサーバにするまでプロキシ機能は有効にしないでください。 オープンプロキシサーバはあなた自身のネットワークにとっても、 インターネット全体にとっても危険です。

参照

  • mod_proxy
  • mod_proxy_connect

環境変数

mod_proxy の動作を制御する設定ディレクティブ に加えて、HTTP 動作を制御する多くの 環境変数 があります:

proxy-sendextracrlf
プロキシが、リクエストの最後に追加の CR-LF 改行コードを送るように します。これはいくつかのブラウザにあるバグの回避用です。
force-proxy-request-1.0
プロキシがバックエンドに HTTP/1.0 でリクエストを送るようにし、 HTTP/1.1 の機能を無効にします。
proxy-nokeepalive
プロキシがリクエスト終了後にバックエンドとの接続を切るようにします。
proxy-chain-auth
プロキシが認証を要求する場合、プロキシはクライアントから送られるユーザ情報で 認証しますが、ユーザ情報はその先に転送しません。 proxy-chain-auth を有効にすると、プロキシはユーザ認証情報を 次のプロキシにも転送します。ユーザ認証を共有しているプロキシを連結している時、 この動作が必要でしょう。セキュリティ上の警告: 必要性が分からない限り、この動作を有効にしてはいけません。 と言うのも、大事な情報を転送してしまうからです。
proxy-sendcl
HTTP/1.0 では、ボディのあるリクエスト (例えば POST リクエスト) はすべて Content-Length ヘッダを持つ必要があります。 この環境変数で、クライアントがプロキシに送ったのが何であるかに関わらず、 Apache のプロキシがバックエンドサーバにこのヘッダを送るように強制します。 これにより、HTTP/1.0 もしくはバージョン不明のバックエンドに転送する時の 互換性を保証します。しかし、この動作のためにプロキシはリクエストすべてをバッファリング する必要があるかもしれません。このため、大きなサイズのリクエストで 非常に非効率になります。
proxy-sendchunks or proxy-sendchunked
これは proxy-sendcl の逆です。 リクエストのボディを chunked 転送エンコーディングでバックエンドに 送れるようにします。効率的なストリーム転送ができますが、 バックエンドサーバが HTTP/1.1 をサポートしている必要があります。
proxy-interim-response
この環境変数の値は RFC か Suppress です。 httpd の初期のバージョンはバックエンドからの HTTP interim レスポンス (1xx) を捨てることがありました。これは技術的には HTTP のプロトコル違反です。 実際には、バックエンドが interim レスポンスを返すとしたら、 そのバックエンドはプロトコルを我々の預かり知らない方法で独自拡張しているか、 単におかしいかどちらかでしょう。 なので、 interim に対する動作を設定で変更可能にしています。 proxy-interim-response RFC と設定すると、 プロトコル準拠の動作になります。proxy-interim-response Suppress と設定すると、 interim レスポンスをプロキシしません。
proxy-initial-not-pooled
この環境変数をセットすると、クライアントの最初の接続にはプールした 接続を使わなくなります。これは競合状態を原因とする "proxy: error reading status line from remote server" エラーメッセージを 回避します。競合状態は、プロキシがプールした接続をチェックした後、 プロキシの送ったデータがバックエンドに到達する前にバックエンドが接続を閉じると発生します。 この変数をセットすることでパフォーマンスが劣化することを知っておくべきです。 特に HTTP/1.0 のクライアントに影響します。


mod_proxy_scgi - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_proxy_scgi

説明: | mod_proxy のための SCGI ゲートウェイモジュール
ステータス: | Extension
モジュール識別子: | proxy_scgi_module
ソースファイル: | mod_proxy_scgi.c
互換性: | Apache 2.2.14 以降で使用可能

概要

本モジュールには mod_proxy が必要です。 本モジュールは SCGI protocol, version 1 をサポートします。

SCGI プロトコルを扱うためには、mod_proxy と mod_proxy_scgiが サーバに組み込まれて いなければいけません。

警告

安全なサーバにするまでプロキシ機能は有効にしないでください。 オープンプロキシサーバはあなた自身のネットワークにとっても、 インターネット全体にとっても危険です。

参照

  • mod_proxy
  • mod_proxy_balancer

例

以下の例を動かすには、mod_proxy と mod_proxy_scgi を有効にしなければいけないことを忘れないでください。

簡単なゲートウェイ

ProxyPass /scgi-bin/ scgi://localhost:4000/

ロードバランスするゲートウェイには、既に言及したプロキシモジュール に加えて mod_proxy_balancer が必要です。

ロードバランスするゲートウェイ

ProxyPass /scgi-bin/ balancer://somecluster/
<Proxy balancer://somecluster/>
BalancerMember scgi://localhost:4000/
BalancerMember scgi://localhost:4001/
 </Proxy>

ProxySCGIInternalRedirect ディレクティブ

説明: | バックエンドからの内部的なリダイレクトレスポンスを有効あるいは無効にする
構文: | ProxySCGIInternalRedirect On|Off
デフォルト: | ProxySCGIInternalRedirect On
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_proxy_scgi

ProxySCGIInternalRedirect で、 バックエンドが内部的にゲートウェイを別の URL にリダイレクトできるようにします。 この機能は mod_cgi 起源で、レスポンスステータスが OK (200) で、かつレスポンスが Location ヘッダを持ち、かつヘッダ値の先頭がスラッシュ (/) であれば、 内部的にリダイレクトします。このヘッダ値が内部的なリダイレクト先の 新しい URL として解釈されます。

機能を無効にしない限り、mod_proxy_scgi は 上記の点で mod_cgi と同じ動作をします。

例

ProxySCGIInternalRedirect Off

ProxySCGISendfile ディレクティブ

説明: | X-Sendfile 疑似レスポンスヘッダの評価を有効にする
構文: | ProxySCGISendfile On|Off|Headername
デフォルト: | ProxySCGISendfile Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ
ステータス: | Extension
モジュール: | mod_proxy_scgi

ProxySCGISendfile ディレクティブを設定すると、 SCGI バックエンドの代わりにゲートウェイが直接ファイルを転送できるようにします。 これはパフォーマンス向上のために使えます。 httpd は sendfile などの最適化を行うことができます。これはバックエンドからソケット経由でファイルを 受けた時にはできない最適化です。

ProxySCGISendfile の引数でゲートウェイの動作 を制御します:

Off
特別な動作をしません。
On
ゲートウェイはバックエンドのレスポンスヘッダから X-Sendfile と 呼ばれるヘッダを探し、その値を転送対象のファイル名と見なします。 ヘッダは最終的なレスポンスヘッダからは除かれます。 次の設定と等価です。 ProxySCGISendfile X-Sendfile.
その他
On にした場合に似ていますが、ハードコードしたヘッダ名の 代わりに、引数がヘッダ名として使われます。

Example

# Use the default header (X-Sendfile)
ProxySCGISendfile On

# Use a different header
ProxySCGISendfile X-Send-Static

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


mod_reqtimeout - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_reqtimeout

Description: | Set timeout and minimum data rate for receiving requests
Status: | Extension
Module Identifier: | reqtimeout_module
Source File: | mod_reqtimeout.c
Compatibility: | Available in Apache 2.2.15 and later

Examples

  1. Allow 10 seconds to receive the request including the headers and 30 seconds for receiving the request body:

    RequestReadTimeout header=10 body=30

  2. Allow at least 10 seconds to receive the request body. If the client sends data, increase the timeout by 1 second for every 1000 bytes received, with no upper limit for the timeout (exept for the limit given indirectly by LimitRequestBody):

    RequestReadTimeout body=10,MinRate=1000

  3. Allow at least 10 seconds to receive the request including the headers. If the client sends data, increase the timeout by 1 second for every 500 bytes received. But do not allow more than 30 seconds for the request including the headers:

    RequestReadTimeout header=10-30,MinRate=500

  4. Usually, a server should have both header and body timeouts configured. If a common configuration is used for http and https virtual hosts, the timeouts should not be set too low:

    RequestReadTimeout header=20-40,MinRate=500 body=20,MinRate=500

RequestReadTimeout Directive

Description: | Set timeout values for receiving request headers and body from client.
Syntax: | RequestReadTimeout [header=timeout[[-maxtimeout],MinRate=rate] [body=timeout[[-maxtimeout],MinRate=rate]
Default: | Unset; no limit
Context: | server config, virtual host
Status: | Extension
Module: | mod_reqtimeout

This directive can set various timeouts for receiving the request headers and the request body from the client. If the client fails to send headers or body within the configured time, a 408 REQUEST TIME OUT error is sent.

For SSL virtual hosts, the header timeout values include the time needed to do the initial SSL handshake. If the user's browser is configured to query certificate revocation lists and the CRL server is not reachable, the initial SSL handshake may take a significant time until the browser gives up waiting for the CRL. Therefore the header timeout values should not be set to very low values for SSL virtual hosts. The body timeout values include the time needed for SSL renegotiation (if necessary).

When an AcceptFilter is in use (usually the case on Linux and FreeBSD), the socket is not sent to the server process before at least one byte (or the whole request for httpready) is received. The header timeout configured with RequestReadTimeout is only effective after the server process has received the socket.

For each of the two timeout types (header or body), there are three ways to specify the timeout:

  • Fixed timeout value:

    type=timeout

    The time in seconds allowed for reading all of the request headers or body, respectively. A value of 0 means no limit.

  • Timeout value that is increased when data is received:

    type=timeout,MinRate=data_rate

    Same as above, but whenever data is received, the timeout value is increased according to the specified minimum data rate (in bytes per second).

  • Timeout value that is increased when data is received, with an upper bound:

    type=timeout-maxtimeout,MinRate=data_rate

    Same as above, but the timeout will not be increased above the second value of the specified timeout range.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_rewrite - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_rewrite

Description: | Provides a rule-based rewriting engine to rewrite requested URLs on the fly
Status: | Extension
Module Identifier: | rewrite_module
Source File: | mod_rewrite.c
Compatibility: | Available in Apache 1.3 and later

Summary

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, of server variables, environment variables, HTTP headers, or time stamps. Even external database lookups in various formats can be used to achieve highly 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 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.

Further details, discussion, and examples, are provided in the detailed mod_rewrite documentation.

See also

  • Rewrite Flags

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 backslash ('\') 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.

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, that is, before any rewriting. This is important to note 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/

Rewriting in Virtual Hosts

By default, mod_rewrite configuration settings from the main server context are not inherited by virtual hosts. To make the main server settings apply to virtual hosts, you must place the following directives in each <VirtualHost> section:

RewriteEngine On
RewriteOptions Inherit

Practical Solutions

For numerous examples of common, and not-so-common, uses for mod_rewrite, see the extended rewrite documentation.

RewriteBase Directive

Description: | Sets the base URL for per-directory rewrites
Syntax: | RewriteBase URL-path
Default: | None
Context: | directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteBase directive specifies the URL prefix to be used for per-directory (htaccess) RewriteRule directives that substitute a relative path.

This directive is required when you use a relative path in a substitution in per-directory (htaccess) context unless either of the following conditions are true:

  • The original request, and the substitution, are underneath the DocumentRoot (as opposed to reachable by other means, such as Alias).
  • The filesystem path to the directory containing the RewriteRule, suffixed by the relative substitution is also valid as a URL path on the server (this is rare).

In the example below, RewriteBase is necessary to avoid rewriting to http://example.com/opt/myapp-1.2.3/welcome.html since the resource was not relative to the document root. This misconfiguration would normally cause the server to look for an "opt" directory under the document root.

DocumentRoot /var/www/example.com
Alias /myapp /opt/myapp-1.2.3
<Directory /opt/myapp-1.2.3>
RewriteEngine On
RewriteBase /myapp/
RewriteRule ^index\.html$  welcome.html
</Directory>

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. One or more RewriteCond can precede a RewriteRule directive. The following rule is then only used if both the current state of the URI matches its pattern, and if these conditions are met.

TestString is a string which can contain 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 (in parentheses) of the pattern, from the RewriteRule which is subject to the current set of RewriteCond conditions..
  • RewriteCond backreferences: These are backreferences of the form %N (1 <= N <= 9), which provide access to the grouped parts (again, in parentheses) of the pattern, from the last matched RewriteCond in the current set 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_PORT
    REMOTE_USER
    REMOTE_IDENT
    REQUEST_METHOD
    SCRIPT_FILENAME
    PATH_INFO
    QUERY_STRING
    AUTH_TYPE
    server internals: date and time: 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.

    SERVER_NAME and SERVER_PORT depend on the values of UseCanonicalName and UseCanonicalPhysicalPort respectively.

    Those that are special to mod_rewrite include those below.

    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. This value has not been unescaped (decoded), unlike most other variables below.
    REQUEST_URI
    The path component of the requested URI, such as "/index.html". This notably excludes the query string which is available as as its own variable named QUERY_STRING.
    REQUEST_FILENAME
    The full local filesystem path to the file or script matching the request, if this has already been determined by the server at the time REQUEST_FILENAME is referenced. Otherwise, such as when used in virtual host context, the same value as REQUEST_URI.
    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 or not mod_ssl is loaded).

Other things you should be aware of:

  1. The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same value - the value of the filename field of the internal request_rec structure of the Apache server. The first name is the commonly known CGI variable name while the second is the appropriate counterpart of REQUEST_URI (which contains the value of the uri field of request_rec).

    If a substitution occurred and the rewriting continues, the value of both variables will be updated accordingly.

    If used in per-server context (i.e., before the request is mapped to the filesystem) SCRIPT_FILENAME and REQUEST_FILENAME cannot contain the full local filesystem path since the path is unknown at this stage of processing. Both variables will initially contain the value of REQUEST_URI in that case. In order to obtain the full local filesystem path of the request in per-server context, use an URL-based look-ahead %{LA-U:REQUEST_FILENAME} to determine the final value of REQUEST_FILENAME.

  2. %{ENV:variable}, where variable can be any environment variable, is also available. This is looked-up via internal Apache structures and (if not found there) via getenv() from the Apache server process.
  3. %{SSL:variable}, where variable is the name of an SSL environment variable, 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. These variables are available even without setting the StdEnvVars option of the SSLOptions directive.
  4. %{HTTP:header}, where header can be any HTTP MIME-header name, can always be used to obtain the value of a header sent in the HTTP request. Example: %{HTTP:Proxy-Connection} is the value of the HTTP header ``Proxy-Connection:''.

    If a HTTP header is used in a condition this header is added to the Vary header of the response in case the condition evaluates to true for the request. It is not added if the condition evaluates to false for the request. Adding the HTTP header to the Vary header of the response is needed for proper caching.

    It has to be kept in mind that conditions follow a short circuit logic in the case of the 'ornext|OR' flag so that certain conditions might not be evaluated at all.

  5. %{LA-U:variable} can be used for look-aheads which perform an internal (URL-based) sub-request to determine the final value of variable. This can be used to access variable for rewriting which is not available at the current stage, but will be set in a later phase.

    For instance, to rewrite according to the REMOTE_USER variable from within the per-server context (httpd.conf file) you must use %{LA-U:REMOTE_USER} - this variable is set by the authorization phases, which come after the URL translation phase (during which 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} in that context.

  6. %{LA-F:variable} can be used to perform 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, a regular expression which is applied to the current instance of the TestString. TestString is first evaluated, before being 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' (lexicographically precedes)
      Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString lexicographically precedes CondPattern.
    • '>CondPattern' (lexicographically follows)
      Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString lexicographically follows CondPattern.
    • '=CondPattern' (lexicographically equal)
      Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString is lexicographically equal to CondPattern (the two strings are exactly equal, character for character). If CondPattern is "" (two quotation marks) this compares TestString to the empty string.
    • '-d' (is directory)
      Treats the TestString as a pathname and tests whether or not it exists, and is a directory.
    • '-f' (is regular file)
      Treats the TestString as a pathname and tests whether or not it exists, and is a regular file.
    • '-s' (is regular file, with size)
      Treats the TestString as a pathname and tests whether or not it exists, and is a regular file with size greater than zero.
    • '-l' (is symbolic link)
      Treats the TestString as a pathname and tests whether or not it exists, and is a symbolic link.
    • '-x' (has executable permissions)
      Treats the TestString as a pathname and tests whether or not it exists, and has executable permissions. These permissions are determined according to the underlying OS.
    • '-F' (is existing file, via subrequest)
      Checks whether or not TestString is a valid file, accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to do the check, so use it with care - it can impact your server's performance!

    • '-U' (is existing URL, via subrequest)
      Checks whether or not TestString is a valid URL, accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to do the check, so use it with care - it can impact your server's performance!

      This flag only returns information about things like access control, authentication, and authorization. This flag does not return information about the status code the configured handler (static file, CGI, proxy, etc.) would have returned.

    Note:

    All of these tests can also be prefixed by an exclamation mark ('!') to negate their meaning.
  3. You can also set special flags for CondPattern by appending [flags] as the third argument to the RewriteCond directive, where flags is a comma-separated list of any of the following flags:
    • 'nocase|NC' (no case)
      This makes the test case-insensitive - differences between 'A-Z' and 'a-z' are ignored, 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 condition/rule pair three times.
    • 'novary|NV' (no vary)
      If a HTTP header is used in the condition, this flag prevents this header from being added to the Vary header of the response.
      Using this flag might break proper caching of the response if the representation of this response varies on the value of this header. So this flag should be only used if the meaning of the Vary header is well understood.

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]

Explanation: If you use a browser which identifies itself as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you get the max homepage (which could include frames, or other special features). If you use the Lynx browser (which is terminal-based), then you get the min homepage (which could be a version designed for easy, text-only browsing). If neither of these conditions apply (you use any other browser, or your browser identifies itself as something non-standard), you get the std (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 rewrite configurations are not inherited by virtual hosts. This means that you need to have a RewriteEngine on directive for each virtual host in which you wish to use rewrite rules.

RewriteMap directives of the type prg are not started during server initialization if they're defined in a context that does not have RewriteEngine set to on

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|pipe
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!

The RewriteLog log file format is as follows:

Description | Example
Remote host IP address | 192.168.200.166
Remote login name | Will usually be "-"
HTTP user auth name | Username, or "-" if no auth
Date and time of request | [28/Aug/2009:13:09:09 --0400]
Virtualhost and virtualhost ID | [www.example.com/sid#84a650]
Request ID, and whether it's a subrequest | [rid#9f0e58/subreq]
Log entry severity level | (2)
Text error message | forcing proxy-throughput with http://127.0.0.1:8080/index.html

Security

See the Apache Security Tips document for details on how 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

# Log to a file:
RewriteLog "/usr/local/var/apache/logs/rewrite.log"

# Log to a pipe:
RewriteLog "|/path/to/parser.pl"

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. Empty values behave as if the key was absent, therefore it is not possible to distinguish between empty-valued keys and absent keys.

For example, you might define a RewriteMap as:

RewriteMap examplemap txt:/path/to/file/map.txt

You would then be able to use this map in a RewriteRule as follows:

RewriteRule ^/ex/(.*) ${examplemap:$1}

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. For example, you might use the following map file and directives to provide a random load balancing between several back-end servers, via a reverse-proxy. Images are sent to one of the servers in the 'static' pool, while everything else is sent to one of the 'dynamic' pool.

    Example:

    Rewrite map file

    ##
##  map.txt -- rewriting map
##

static   www1|www2|www3|www4
dynamic  www5|www6

    Configuration directives

    RewriteMap servers rnd:/path/to/file/map.txt

    RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]
    RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]

  • 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 omitted, the compile-time default will be chosen.

    To create a dbm file from a source text file, use the httxt2dbm utility.

    $ httxt2dbm -i mapfile.txt -o mapfile.map

  • Internal Function
    MapType: int, MapSource: Internal Apache function

    Here, the source is an internal Apache function. Module authors can provide additional internal functions by registering them with the ap_register_rewrite_mapfunc API. The functions that are provided by default are:

    • toupper:
      Converts the key to all upper case.
    • tolower:
      Converts the key to all lower case.
    • escape:
      Translates special characters in the key to hex-encodings.
    • unescape:
      Translates hex-encodings in the 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 a language of your choice, but the result has to be an executable program (either object-code or a script with the magic cookie trick '#!/path/to/interpreter' as the first line).

    This program is started once, when the Apache server is started, and then communicates with the rewriting engine via 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:

    External rewriting programs are not started if they're defined in a context that does not have RewriteEngine set to on.

    #!/usr/bin/perl
$| = 1;
while (<STDIN>) {
    # ...put here any transformations or lookups...
    print $_;
}

    But be very careful:

    1. ``Keep it simple, stupid'' (KISS). If this program hangs, it will cause Apache to hang when trying to use the relevant rewrite rule.
    2. A common mistake is to use buffered I/O on stdout. Avoid this, as it will cause a deadloop! ``$|=1'' is used above, to prevent this.
    3. The RewriteLock directive can be used to define a lockfile which mod_rewrite can use to synchronize communication with the mapping 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
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite
Compatibility: | MaxRedirects is no longer available in version 2.1 and later

The RewriteOptions directive sets some special options for the current per-server or per-directory configuration. The Option string can currently only 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.

Rules inherited from the parent scope are applied after rules specified in the child scope.
AllowAnyURI

When RewriteRule is used in VirtualHost or server context with version 2.2.23 or later of httpd, mod_rewrite will only process the rewrite rules if the request URI is a URL-path. This avoids some security issues where particular rules could allow "surprising" pattern expansions (see CVE-2011-3368 and CVE-2011-4317). To lift the restriction on matching a URL-path, the AllowAnyURI option can be enabled, and mod_rewrite will apply the rule set to any request URI string, regardless of whether that string matches the URL-path grammar required by the HTTP specification.

Security Warning

Enabling this option will make the server vulnerable to security issues if used with rewrite rules which are not carefully authored. It is strongly recommended that this option is not used. In particular, beware of input strings containing the '@' character which could change the interpretation of the transformed URI, as per the above CVE names.

MergeBase

With this option, the value of RewriteBase is copied from where it's explicitly defined into any sub-directory or sub-location that doesn't define its own RewriteBase. Not copying was the default until 2.2.22. In version 2.2.23 copying was the default. The flag to explicitly control it is available for Apache HTTP Server 2.2.24 and later.

RewriteRule Directive

Description: | Defines rules for the rewriting engine
Syntax: | RewriteRule Pattern Substitution [flags]
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteRule directive is the real rewriting workhorse. The directive can occur more than once, with each instance defining a single rewrite rule. The order in which these rules are defined is important - this is the order in which they will be applied at run-time.

Pattern is a perl compatible regular expression. On the first RewriteRule it is applied to the (%-decoded) URL-path of the request; subsequent patterns are applied to the output of the last matched RewriteRule.

What is matched?

In VirtualHost context, The Pattern will initially be matched against the part of the URL after the hostname and port, and before the query string (e.g. "/app1/index.html").

In Directory and htaccess context, the Pattern will initially be matched against the filesystem path, after removing the prefix that led the server to the current RewriteRule (e.g. "app1/index.html" or "index.html" depending on where the directives are defined).

If you wish to match against the hostname, port, or query string, use a RewriteCond with the %{HTTP_HOST}, %{SERVER_PORT}, or %{QUERY_STRING} variables respectively.

Per-directory Rewrites

  • The rewrite engine may be used in .htaccess files and in <Directory> sections, with some additional complexity.
  • To enable the rewrite engine in this context, you need to set "RewriteEngine On" and "Options FollowSymLinks" must be enabled. If your administrator has disabled override of FollowSymLinks for a user's directory, then you cannot use the rewrite engine. This restriction is required for security reasons.
  • When using the rewrite engine in .htaccess files the per-directory prefix (which always is the same for a specific directory) is automatically removed for the RewriteRule pattern matching and automatically added after any relative (not starting with a slash or protocol name) substitution encounters the end of a rule set. See the RewriteBase directive for more information regarding what prefix will be added back to relative substitutions.
  • If you wish to match against the full URL-path in a per-directory (htaccess) RewriteRule, use the %{REQUEST_URI} variable in a RewriteCond.
  • The removed prefix always ends with a slash, meaning the matching occurs against a string which never has a leading slash. Therefore, a Pattern with ^/ never matches in per-directory context.
  • Although rewrite rules are syntactically permitted in <Location> and <Files> sections, this should never be necessary and is unsupported.

For some hints on regular expressions, see the mod_rewrite Introduction.

In mod_rewrite, the NOT character ('!') is also available as a possible pattern prefix. This enables you 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.

Note

When using the NOT character to negate a pattern, you cannot include grouped wildcard parts in that pattern. This is because, when the pattern does NOT match (ie, the negation matches), there are no contents for the groups. Thus, if negated patterns are used, you cannot use $N in the substitution string!

The Substitution of a rewrite rule is the string that replaces the original URL-path that was matched by Pattern. The Substitution may be a:

file-system path
Designates the location on the file-system of the resource to be delivered to the client. Substitutions are only treated as a file-system path when the rule is configured in server (virtualhost) context and the first component of the path in the substitution is exists in the file-system
URL-path
A DocumentRoot-relative path to the resource to be served. Note that mod_rewrite tries to guess whether you have specified a file-system path or a URL-path by checking to see if the first segment of the path exists at the root of the file-system. For example, if you specify a Substitution string of /www/file.html, then this will be treated as a URL-path unless a directory named www exists at the root or your file-system (or, in the case of using rewrites in a .htaccess file, relative to your document root), in which case it will be treated as a file-system path. If you wish other URL-mapping directives (such as Alias) to be applied to the resulting URL-path, use the [PT] flag as described below.
Absolute URL
If an absolute URL is specified, mod_rewrite checks to see whether the hostname matches the current host. If it does, the scheme and hostname are stripped out and the resulting path is treated as a URL-path. Otherwise, an external redirect is performed for the given URL. To force an external redirect back to the current host, see the [R] flag below.
- (dash)
A dash indicates that no substitution should be performed (the existing path is passed through untouched). This is used when a flag (see below) needs to be applied without changing the path.

In addition to plain text, the Substition string can include

  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 identifiers of the form $N (N=0..9), 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 above.

Rewrite rules are applied to the results of previous rewrite rules, in the order in which they are defined in the config file. The URL is completely replaced by the Substitution and the rewriting process continues until all rules have been applied, or it is explicitly terminated by a L flag, or other flag which implies immediate termination, such as F.

Modifying the Query String

By default, the query string is passed through unchanged. You can, however, create URLs in the substitution string containing a query string part. Simply use a question mark inside the substitution string to indicate that the following text should be re-injected into the query string. When you want to erase an existing query string, end the substitution string with just a question mark. To combine new and old query strings, use the [QSA] flag.

Additionally you can set special actions to be performed by appending [flags] as the third argument to the RewriteRule directive. Flags is a comma-separated list, surround by square brackets, of any of the flags in the following table. More details, and examples, for each flag, are available in the Rewrite Flags document.

Flag and syntax | Function
B | Escape non-alphanumeric characters before applying the transformation. details ...
chain|C | Rule is chained to the following rule. If the rule fails, the rule(s) chained to it will be skipped. details ...
cookie|CO=NAME:VAL | Sets a cookie in the client browser. Full syntax is: CO=NAME:VAL:domain[:lifetime[:path[:secure[:httponly]]]] details ...
discardpath|DPI | Causes the PATH_INFO portion of the rewritten URI to be discarded. details ...
env|E=[!]VAR[:VAL] | Causes an environment variable VAR to be set (to the value VAL if provided). The form !VAR causes the environment variable VAR to be unset.details ...
forbidden|F | Returns a 403 FORBIDDEN response to the client browser. details ...
gone|G | Returns a 410 GONE response to the client browser. details ...
Handler|H=Content-handler | Causes the resulting URI to be sent to the specified Content-handler for processing. details ...
last|L | Stop the rewriting process immediately and don't apply any more rules. Especially note caveats for per-directory and .htaccess context. details ...
next|N | Re-run the rewriting process, starting again with the first rule, using the result of the ruleset so far as a starting point. details ...
nocase|NC | Makes the pattern comparison case-insensitive. details ...
noescape|NE | Prevent mod_rewrite from applying hexcode escaping of special characters in the result of the rewrite. details ...
nosubreq|NS | Causes a rule to be skipped if the current request is an internal sub-request. details ...
proxy|P | Force the substitution URL to be internally sent as a proxy request. details ...
passthrough|PT | Forces the resulting URI to be passed back to the URL mapping engine for processing of other URI-to-filename translators, such as Alias or Redirect. details ...
qsappend|QSA | Appends any query string from the original request URL to any query string created in the rewrite target.details ...
redirect|R[=code] | Forces an external redirect, optionally with the specified HTTP status code. details ...
skip|S=num | Tells the rewriting engine to skip the next num rules if the current rule matches. details ...
type|T=MIME-type | Force the MIME-type of the target file to be the specified type. details ...

Home directory expansion

When the substitution string begins with a string resembling "/~user" (via explicit text or backreferences), mod_rewrite performs home directory expansion independent of the presence or configuration of mod_userdir.

This expansion does not occur when the PT flag is used on the RewriteRule directive.

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                      invalid, not supported

^/somepath(.*) otherpath$1  [R]                 invalid, not supported

^/somepath(.*) otherpath$1  [P]                 invalid, not supported
----------------------------------------------  ----------------------------------
^/somepath(.*) /otherpath$1                     /otherpath/pathinfo

^/somepath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
                                                via external redirection

^/somepath(.*) /otherpath$1 [P]                 doesn't make sense, not supported
----------------------------------------------  ----------------------------------
^/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]  doesn't make sense, not supported
----------------------------------------------  ----------------------------------
^/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
(/physical/path/to/somepath/.htaccess, with 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]                 doesn't make sense, not supported
----------------------------------------------  ----------------------------------
^localpath(.*) /otherpath$1                     /otherpath/pathinfo

^localpath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
                                                via external redirection

^localpath(.*) /otherpath$1 [P]                 doesn't make sense, not supported
----------------------------------------------  ----------------------------------
^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]  doesn't make sense, not supported
----------------------------------------------  ----------------------------------
^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

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_setenvif - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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

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) は 正規表現です。 regex が attribute にマッチする場合は、 残りの引数が評価されます。

残りの引数は設定する変数の名前で、設定される値を指定することもできます。 これは、

  1. varname
  2. !varname
  3. varname=value

のどれかの形式になります。

最初の形式では、値は "1" に設定されます。 二つ目はもし値が定義されていればそれを取り除きます。 三つ目は変数を value の与えられた値に設定します。 2.0.51 以降では、value 内に $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

SetEnvIfNoCase は意味的には SetEnvIf ディレクティブと 同じです。違いは、正規表現のマッチングが大文字小文字を区別しないで 行なわれることです。例えば:

SetEnvIfNoCase Host Apache\.Org site=apache

これは HTTP リクエストヘッダにフィールド Host: が あり、その値が Apache.Org や apache.org、 その他の大文字小文字の組み合わせであったときに site 環境変数を "apache" に設定します。


mod_so - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_speling

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | ユーザが入力したであろう間違った URL を、 大文字小文字の区別を無視することと一つ以下の綴り間違いを許容することで 修正を試みる
ステータス: | Extension
モジュール識別子: | speling_module
ソースファイル: | mod_speling.c

概要

リクエストの綴りが間違っていたり、 大文字小文字が違っていたりするために、Apache のコアサーバが ドキュメントへのリクエストへの応答を正しく提供できないことがあります。 このモジュールは、他のすべてのモジュールがあきらめた後であったとしても、 リクエストに合うドキュメントを見つけようとすることによりこの問題の 解決を試みます。このモジュールはリクエストされたディレクトリにある それぞれのドキュメントの名前と、リクエストされたドキュメントの名前とを 大文字小文字の区別を無視し、一文字までの 綴りの間違い (文字の挿入/省略/隣合う文字の置換、間違った文字) を許可して比較することにより、目的を達成しようとします。 この方法でリクエストに合うドキュメントの一覧が作成されます。

ディレクトリをスキャンした後に、

  • 適切なドキュメントが見つからなかった場合、 Apache はいつもと同じように処理をし、 「ドキュメントが見つからない」というエラーを返します。
  • リクエストに「ほとんど」合うドキュメントが一つだけ見つかった場合、 それがリダイレクト応答として返されます。
  • よく似たドキュメントが複数見つかった場合、 そのリストがクライアントに返され、 クライアントが正しい候補を選択できるようにします。

CheckCaseOnly ディレクティブ

説明: | Limits the action of the speling module to case corrections
構文: | CheckCaseOnly on|off
デフォルト: | CheckCaseOnly Off
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | Options
ステータス: | Extension
モジュール: | mod_speling

このディレクティブの解説文書は まだ翻訳されていません。英語版をご覧ください。

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" として間違って扱われるかもしれません。

DAV が有効なディレクトリでは mod_speling は有効にしないでください。 新しく作成したリソース名を既に存在するファイル名に「修正」しようとする、 例えば、新規ドキュメント doc43.html が既に存在する doc34.html にリダイレクトされて、 期待とは違う挙動になるからです。


mod_ssl - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_ssl

Description: | Strong cryptography using the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols
Status: | Extension
Module Identifier: | ssl_module
Source File: | 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 can be configured to provide several items of SSL information as additional environment variables to the SSI and CGI namespace. This information is not provided by default for performance reasons. (See SSLOptions StdEnvVars, below.) 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, TLSv1.1, TLSv1.2)
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_COMPRESS_METHOD | string | SSL compression method negotiated
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_V_REMAIN | string | Number of days until client's certificate expires
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
SSL_TLS_SNI | string | Contents of the SNI TLS extension (if supplied with ClientHello)

x509 specifies a component of an X.509 DN; one of C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email. In Apache 2.1 and later, x509 may also include a numeric _n suffix. If the DN in question contains multiple attributes of the same name, this suffix is used as an index to select a particular attribute. For example, where the server certificate subject DN included two OU fields, SSL_SERVER_S_DN_OU_0 and SSL_SERVER_S_DN_OU_1 could be used to reference each.

SSL_CLIENT_V_REMAIN is only available in version 2.1 and later.

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"

These formats even work without setting the StdEnvVars option of the SSLOptions directive.

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.

Example

SSLCACertificatePath /usr/local/apache2/conf/ssl.crt/

SSLCADNRequestFile Directive

Description: | File of concatenated PEM-encoded CA Certificates for defining acceptable CA names
Syntax: | SSLCADNRequestFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

When a client certificate is requested by mod_ssl, a list of acceptable Certificate Authority names is sent to the client in the SSL handshake. These CA names can be used by the client to select an appropriate client certificate out of those it has available.

If neither of the directives SSLCADNRequestPath or SSLCADNRequestFile are given, then the set of acceptable CA names sent to the client is the names of all the CA certificates given by the SSLCACertificateFile and SSLCACertificatePath directives; in other words, the names of the CAs which will actually be used to verify the client certificate.

In some circumstances, it is useful to be able to send a set of acceptable CA names which differs from the actual CAs used to verify the client certificate - for example, if the client certificates are signed by intermediate CAs. In such cases, SSLCADNRequestPath and/or SSLCADNRequestFile can be used; the acceptable CA names are then taken from the complete set of certificates in the directory and/or file specified by this pair of directives.

SSLCADNRequestFile must specify an all-in-one file containing a concatenation of PEM-encoded CA certificates.

Example

SSLCADNRequestFile /usr/local/apache2/conf/ca-names.crt

SSLCADNRequestPath Directive

Description: | Directory of PEM-encoded CA Certificates for defining acceptable CA names
Syntax: | SSLCADNRequestPath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This optional directive can be used to specify the set of acceptable CA names which will be sent to the client when a client certificate is requested. See the SSLCADNRequestFile directive for more details.

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.

Example

SSLCADNRequestPath /usr/local/apache2/conf/ca-names.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.

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 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.

But be careful: Providing the certificate chain works only if you are using a single 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
Compatibility: | ECC support is available in Apache 2.2.26 and later

This directive points to a file with certificate data in PEM format. At a minimum, the file must include an end-entity (leaf) certificate. The directive can be used up to three times (referencing different filenames) when an RSA, a DSA, and an ECC based server certificate is used in parallel.

Custom DH parameters and an EC curve name for ephemeral keys, can be added to end of the first file configured using SSLCertificateFile. This is supported in version 2.2.30 or later. Such parameters can be generated using the commands openssl dhparam and openssl ecparam. The parameters can be added as-is to the end of the first certificate file. Only the first file can be used for custom parameters, as they are applied independently of the authentication algorithm type.

Finally the the end-entity certificate's private key can also be added to the certificate file instead of using a separate SSLCertificateKeyFile directive. This practice is highly discouraged. If the private key is encrypted, the pass phrase dialog is forced at startup time.

DH parameter interoperability with primes > 1024 bit

Beginning with version 2.2.30, mod_ssl makes use of standardized DH parameters with prime lengths of 2048, 3072, 4096, 6144 and 8192 bits (from RFC 3526), and hands them out to clients based on the length of the certificate's RSA/DSA key. With Java-based clients in particular (Java 7 or earlier), this may lead to handshake failures - see this FAQ answer for working around such issues.

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
Compatibility: | ECC support is available in Apache 2.2.26 and later

This directive points to the PEM-encoded private key file for the server. If the contained private key is encrypted, the pass phrase dialog is forced at startup time.

The directive can be used up to three times (referencing different filenames) when an RSA, a DSA, and an ECC based private key is used in parallel. For each SSLCertificateKeyFile directive, there must be a matching SSLCertificateFile directive.

The private key may also be combined with the certificate in the file given by SSLCertificateFile, but this practice is highly discouraged.

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 renegotiation 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
  • +: move matching ciphers to the current location in list
  • -: remove cipher from list (can be added later again)
  • !: kill cipher from list completely (can not be added later again)

aNULL, eNULL and EXP ciphers are always disabled

Beginning with version 2.2.30, null and export-grade ciphers are always disabled, as mod_ssl unconditionally prepends any supplied cipher suite string with !aNULL:!eNULL:!EXP: at initialization.

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

SSLCompression Directive

Description: | Enable compression on the SSL level
Syntax: | SSLCompression on|off
Default: | SSLCompression off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.2.24 and later, if using OpenSSL 0.9.8 or later; virtual host scope available if using OpenSSL 1.0.0 or later. The default used to be on in versions 2.2.24 to 2.2.25.

This directive allows to enable compression on the SSL level.

Enabling compression causes security issues in most setups (the so called CRIME attack).

SSLCryptoDevice Directive

Description: | Enable use of a cryptographic hardware accelerator
Syntax: | SSLCryptoDevice engine
Default: | SSLCryptoDevice builtin
Context: | server config
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in Apache 2.1 and later, if using -engine flavor of OpenSSL 0.9.6, or OpenSSL 0.9.7 or later

This directive enables use of a cryptographic hardware accelerator board to offload some of the SSL processing overhead. This directive can only be used if the SSL toolkit is built with "engine" support; OpenSSL 0.9.7 and later releases have "engine" support by default, the separate "-engine" releases of OpenSSL 0.9.6 must be used.

To discover which engine names are supported, run the command "openssl engine".

Example

# For a Broadcom accelerator:
SSLCryptoDevice ubsec

SSLEngine Directive

Description: | SSL Engine Operation Switch
Syntax: | SSLEngine on|off|optional
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 should be used inside a <VirtualHost> section to enable SSL/TLS for a that 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>

In Apache 2.1 and later, SSLEngine can be set to optional. This enables support for RFC 2817, Upgrading to TLS Within HTTP/1.1. At this time no web browsers support RFC 2817.

SSLFIPS Directive

Description: | SSL FIPS mode Switch
Syntax: | SSLFIPS on|off
Default: | SSLFIPS off
Context: | server config
Status: | Extension
Module: | mod_ssl

This directive toggles the usage of the SSL library FIPS_mode flag. It must be set in the global server context and cannot be configured with conflicting settings (SSLFIPS on followed by SSLFIPS off or similar). The mode applies to all SSL library operations.

If httpd was compiled against an SSL library which did not support the FIPS_mode flag, SSLFIPS on will fail. Refer to the FIPS 140-2 Security Policy document of the SSL provider library for specific requirements to use mod_ssl in a FIPS 140-2 approved mode of operation; note that mod_ssl itself is not validated, but may be described as using FIPS 140-2 validated cryptographic module, when all components are assembled and operated under the guidelines imposed by the applicable Security Policy.

SSLHonorCipherOrder Directive

Description: | Option to prefer the server's cipher preference order
Syntax: | SSLHonorCipherOrder flag
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in Apache 2.1 and later, if using OpenSSL 0.9.7 or later

When choosing a cipher during an SSLv3 or TLSv1 handshake, normally the client's preference is used. If this directive is enabled, the server's preference will be used instead.

Example

SSLHonorCipherOrder on

SSLInsecureRenegotiation Directive

Description: | Option to enable support for insecure renegotiation
Syntax: | SSLInsecureRenegotiation flag
Default: | SSLInsecureRenegotiation off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.2.15 and later, if using OpenSSL 0.9.8m or later

As originally specified, all versions of the SSL and TLS protocols (up to and including TLS/1.2) were vulnerable to a Man-in-the-Middle attack (CVE-2009-3555) during a renegotiation. This vulnerability allowed an attacker to "prefix" a chosen plaintext to the HTTP request as seen by the web server. A protocol extension was developed which fixed this vulnerability if supported by both client and server.

If mod_ssl is linked against OpenSSL version 0.9.8m or later, by default renegotiation is only supported with clients supporting the new protocol extension. If this directive is enabled, renegotiation will be allowed with old (unpatched) clients, albeit insecurely.

Security warning

If this directive is enabled, SSL connections will be vulnerable to the Man-in-the-Middle prefix attack as described in CVE-2009-3555.

Example

SSLInsecureRenegotiation on

The SSL_SECURE_RENEG environment variable can be used from an SSI or CGI script to determine whether secure renegotiation is supported for a given SSL connection.

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() function 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.

  • 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 -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).

  • |/path/to/program [args...]

    This mode allows an external program to be used which acts as a pipe to a particular input device; the program is sent the standard prompt text used for the builtin mode on stdin, and is expected to write password strings on stdout. If several passwords are needed (or an incorrect password is entered), additional prompt text will be written subsequent to the first password being returned, and more passwords must then be written back.

  • 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'', ``DSA'', or ``ECC''), 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. Though its use has been deprecated, because of weaknesses in the security of the protocol.

  • SSLv3

    This is the Secure Sockets Layer (SSL) protocol, version 3.0, from the Netscape Corporation. It is the successor to SSLv2 and the predecessor to TLSv1. 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 is defined in RFC 2246.

  • TLSv1.1 (when using OpenSSL 1.0.1 and later)

    A revision of the TLS 1.0 protocol, as defined in RFC 4346.

  • TLSv1.2 (when using OpenSSL 1.0.1 and later)

    A revision of the TLS 1.1 protocol, as defined in RFC 5246.

  • All

    This is a shortcut for ``+SSLv2 +SSLv3 +TLSv1'' or - when using OpenSSL 1.0.1 and later - ``+SSLv2 +SSLv3 +TLSv1 +TLSv1.1 +TLSv1.2'', respectively.

Example

# enable SSLv3 and all available TLSv1 flavors, 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.

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.

Example

SSLProxyCARevocationPath /usr/local/apache2/conf/ssl.crl/

SSLProxyCheckPeerCN Directive

Description: | Whether to check the remote server certificates CN field
Syntax: | SSLProxyCheckPeerCN on|off
Default: | SSLProxyCheckPeerCN off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets whether the remote server certificates CN field is compared against the hostname of the request URL. If both are not equal a 502 status code (Bad Gateway) is sent.

Example

SSLProxyCheckPeerCN on

SSLProxyCheckPeerExpire Directive

Description: | Whether to check if remote server certificate is expired
Syntax: | SSLProxyCheckPeerExpire on|off
Default: | SSLProxyCheckPeerExpire off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets whether it is checked if the remote server certificate is expired or not. If the check fails a 502 status code (Bad Gateway) is sent.

Example

SSLProxyCheckPeerExpire on

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 both for the main server and all configured virtual hosts.

Note that the SSLProxyEngine directive should not, in general, be included in a virtual host that will be acting as a forward proxy (using <Proxy> or <ProxyRequest> directives. SSLProxyEngine is not required to enable a forward proxy server to proxy SSL/TLS requests.

Example

<VirtualHost _default_:443>
SSLProxyEngine on
...
</VirtualHost>

SSLProxyMachineCertificateChainFile Directive

Description: | File of concatenated PEM-encoded CA certificates to be used by the proxy for choosing a certificate
Syntax: | SSLProxyMachineCertificateChainFile filename
Context: | server config
Override: | Not applicable
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in Apache 2.2.23 and later

This directive sets the all-in-one file where you keep the certificate chain for all of the client certs in use. This directive will be needed if the remote server presents a list of CA certificates that are not direct signers of one of the configured client certificates.

This referenced file is simply the concatenation of the various PEM-encoded certificate files. Upon startup, each client certificate configured will be examined and a chain of trust will be constructed.

Security warning

If this directive is enabled, all of the certificates in the file will be trusted as if they were also in SSLProxyCACertificateFile.

Example

SSLProxyMachineCertificateChainFile /usr/local/apache2/conf/ssl.crt/proxyCA.pem

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.

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
Status: | Extension
Module: | mod_ssl

When a proxy is configured to forward requests to a remote SSL server, this directive can be used to configure certificate verification of the remote server.

Note that even when certificate verification is enabled, mod_ssl does not check whether the commonName (hostname) attribute of the server certificate matches the hostname used to connect to the server. In other words, the proxy does not guarantee that the SSL connection to the backend server is "secure" beyond the fact that the certificate is signed by one of the CAs configured using the SSLProxyCACertificatePath and/or SSLProxyCACertificateFile directives. In order to get this check done please have a look at SSLProxyCheckPeerCN and SSLProxyCheckPeerExpire directives which are off by default.

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
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.

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. Its 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 chosen 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 derivatives 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 a tool like EGD (Entropy Gathering Daemon) and run its 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

SSLRenegBufferSize Directive

Description: | Set the size for the SSL renegotiation buffer
Syntax: | SSLRenegBufferSize bytes
Default: | SSLRenegBufferSize 131072
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

If an SSL renegotiation is required in per-location context, for example, any use of SSLVerifyClient in a Directory or Location block, then mod_ssl must buffer any HTTP request body into memory until the new SSL handshake can be performed. This directive can be used to set the amount of memory that will be used for this buffer.

Note that in many configurations, the client sending the request body will be untrusted so a denial of service attack by consumption of memory must be considered when changing this configuration setting.

Example

SSLRenegBufferSize 262144

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 is a very powerful directive because the requirement specification is an arbitrarily complex boolean expression containing any number of access checks.

The implementation of SSLRequire is not thread safe. Using SSLRequire inside .htaccess files on a threaded MPM may cause random crashes.

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 "in" "OID(" word ")"
           | 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, specifically in a .htaccess 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]+$/

The OID() function expects to find zero or more instances of the given OID in the client certificate, and compares the left-hand side string against the value of matching OID attributes. Every matching OID is checked, until a match is found.

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_CHAIN_n
                       SSL_CLIENT_VERIFY      SSL_TLS_SNI

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 unnecessary session handshakes.

The following four storage types are currently supported:

  • none

    This disables the global/inter-process Session Cache. This will incur a noticeable speed penalty and may cause problems if using certain browsers, particularly if client certificates are enabled. This setting is not recommended.

  • nonenotnull

    This disables any global/inter-process Session Cache. However it does force OpenSSL to send a non-null session ID to accommodate buggy clients that require one.

  • 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. This session cache may suffer reliability issues under high load.

  • shm:/path/to/datafile[(size)]

    This makes use of a high-performance cyclic buffer (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 is the recommended session cache.

  • dc:UNIX:/path/to/socket

    This makes use of the distcache distributed session caching libraries. The argument should specify the location of the server or proxy to be used using the distcache address syntax; for example, UNIX:/path/to/socket specifies a UNIX domain socket (typically a local dc_client proxy); IP:server.example.com:9001 specifies an IP address.

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
Compatibility: | Applies also to RFC 5077 TLS session resumption in Apache 2.2.28 and later

This directive sets the timeout in seconds for the information stored in the global/inter-process SSL Session Cache, the OpenSSL internal memory cache and for sessions resumed by TLS session resumption (RFC 5077). 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

SSLSessionTicketKeyFile Directive

Description: | Persistent encryption/decryption key for TLS session tickets
Syntax: | SSLSessionTicketKeyFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.2.30 and later, if using OpenSSL 0.9.8h or later

Optionally configures a secret key for encrypting and decrypting TLS session tickets, as defined in RFC 5077. Primarily suitable for clustered environments where TLS sessions information should be shared between multiple nodes. For single-instance httpd setups, it is recommended to not configure a ticket key file, but to rely on (random) keys generated by mod_ssl at startup, instead.

The ticket key file must contain 48 bytes of random data, preferrably created from a high-entropy source. On a Unix-based system, a ticket key file can be created as follows:

dd if=/dev/random of=/path/to/file.tkey bs=1 count=48

Ticket keys should be rotated (replaced) on a frequent basis, as this is the only way to invalidate an existing session ticket - OpenSSL currently doesn't allow to specify a limit for ticket lifetimes. A new ticket key only gets used after restarting the web server. All existing session tickets become invalid after a restart.

The ticket key file contains sensitive keying material and should be protected with file permissions similar to those used for SSLCertificateKeyFile.

SSLSessionTickets Directive

Description: | Enable or disable use of TLS session tickets
Syntax: | SSLSessionTickets on|off
Default: | SSLSessionTickets on
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in httpd 2.2.30 and later, if using OpenSSL 0.9.8f or later.

This directive allows to enable or disable the use of TLS session tickets (RFC 5077).

TLS session tickets are enabled by default. Using them without restarting the web server with an appropriate frequency (e.g. daily) compromises perfect forward secrecy.

SSLStrictSNIVHostCheck Directive

Description: | Whether to allow non SNI clients to access a name based virtual host.
Syntax: | SSLStrictSNIVHostCheck on|off
Default: | SSLStrictSNIVHostCheck off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in Apache 2.2.12 and later

This directive sets whether a non SNI client is allowed to access a name based virtual host. If set to on in the non default name based virtual host, non SNI clients are not allowed to access this particular virtual host. If set to on in the default name based virtual host, non SNI clients are not allowed to access any name based virtual host belonging to this IP / port combination.

This option is only available if httpd was compiled against an SNI capable version of OpenSSL.

Example

SSLStrictSNIVHostCheck on

SSLUserName Directive

Description: | Variable name to determine user name
Syntax: | SSLUserName varname
Context: | server config, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl
Compatibility: | Available in Apache 2.0.51 and later

This directive sets the "user" field in the Apache request object. This is used by lower modules to identify the user with a character string. In particular, this may cause the environment variable REMOTE_USER to be set. The varname can be any of the SSL environment variables.

Note that this directive has no effect if the FakeBasicAuth option is used (see SSLOptions).

Example

SSLUserName SSL_CLIENT_S_DN_CN

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 renegotiation 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 renegotiation 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

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_status - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_status

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | サーバの活動状況と性能に関する情報を提供する
ステータス: | Base
モジュール識別子: | status_module
ソースファイル: | mod_status.c

概要

この Status モジュールによりサーバ管理者はサーバがどのくらい の性能で動作しているかを知ることができるようになります。 現時点でのサーバの統計情報を読みやすい形式で表した HTML ページが 表示されます。必要であれば、このページは自動的にリフレッシュさせる こともできます (互換性のあるブラウザを使用している場合)。 別に、現時点でのサーバの状態を単純な機械読み取り可能なリストで 表すページもあります。

表示される情報は:

  • リクエストを扱っているワーカーの数
  • アイドル (訳注: リクエストを扱っていない) ワーカーの数
  • 各ワーカーの状態、ワーカーが扱ったリクエストの数、 ワーカーが送った総バイト数 (*)
  • 総アクセス数と総バイト数 (*)
  • サーバが起動もしくは再起動された時刻と動作している時間
  • 平均の 1 秒あたりのリクエスト数、1 秒あたりの送られたバイト数、 リクエストあたりのバイト数 (*)
  • 各ワーカーと Apache 全体で使用されている CPU の割合 (*)
  • 現時点のホストと処理されているリクエスト (*)

"(*)" の付いている情報を表示するには ExtendedStatus が On になっている必要があります。

Status を使用可能にする

example.com ドメインからのブラウザのみに対して ステータスの報告を使用可能にするには 以下のコードを httpd.conf 設定ファイルに追加します

<Location /server-status>
SetHandler server-status

Order Deny,Allow
Deny from all
Allow from .example.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 以降でのみ使用可能

この設定はサーバ全体に対して適用され、バーチャルホスト毎に 変更することはできません。拡張ステータス情報の収集はサーバの 動作を遅くすることがあります。

SeeRequestTail ディレクティブ

説明: | リクエストの最初の 63 文字か最後の 63 文字 のどちらを mod_status が表示するかを決める
構文: | SeeRequestTail On|Off
デフォルト: | SeeRequestTail Off
コンテキスト: | サーバ設定ファイル
ステータス: | Base
モジュール: | mod_status
互換性: | Apache 2.2.7 以降

ExtendedStatus On に設定すると mod_status は処理中のリクエスト(訳注: の文字列)を表示します。 歴史的な理由で、リクエストのうちの63文字だけが表示用に記録されます。 このディレクティブで、最初の63文字を記録する(従来からの動作、 そして現在もデフォルト)か、最後の63文字を記録するかを決めます。 もちろん、リクエストの長さが64文字以上のときに効果があります (訳注: 63文字以下だと結果的に同じ動作)。

Apache が GET /disk1/storage/apache/htdocs/images/imagestore1/food/apples.jpg HTTP/1.1 というリクエストを扱っているとき、 mod_status は以下のように表示します:

Off (デフォルト) | GET /disk1/storage/apache/htdocs/images/imagestore1/food/fruits
On | orage/apache/htdocs/images/imagestore1/food/apples.jpg HTTP/1.1


mod_substitute - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_substitute

Description: | Perform search and replace operations on response bodies
Status: | Extension
Module Identifier: | substitute_module
Source File: | mod_substitute.c
Compatibility: | Available in Apache 2.2.7 and later

Summary

mod_substitute provides a mechanism to perform both regular expression and fixed string substitutions on response bodies.

Substitute Directive

Description: | Pattern to filter the response content
Syntax: | Substitute s/pattern/substitution/[infq]
Context: | directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_substitute

The Substitute directive specifies a search and replace pattern to apply to the response body.

The meaning of the pattern can be modified by using any combination of these flags:

i
Perform a case-insensitive match.
n
By default the pattern is treated as a regular expression. Using the n flag forces the pattern to be treated as a fixed string.
f
The f flag causes mod_substitute to flatten the result of a substitution allowing for later substitutions to take place on the boundary of this one. This is the default.
q
The q flag causes mod_substitute to not flatten the buckets after each substitution. This can result in much faster response and a decrease in memory utilization, but should only be used if there is no possibility that the result of one substitution will ever match a pattern or regex of a subsequent one.

Example

<Location /> AddOutputFilterByType SUBSTITUTE text/html
Substitute s/foo/bar/ni
 </Location>

If either the pattern or the substitution contain a slash character then an alternative delimiter should be used:

Example of using an alternate delimiter

<Location /> AddOutputFilterByType SUBSTITUTE text/html
Substitute "s|<BR */?>|<br />|i" </Location>

SubstituteInheritBefore Directive

Description: | Change the merge order of inherited patterns
Syntax: | SubstituteInheritBefore on|off
Default: | SubstituteInheritBefore off
Context: | directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_substitute
Compatibility: | Available in httpd 2.2.32 and later

Whether to apply the inherited Substitute patterns first (on), or after the ones of the current context (off). SubstituteInheritBefore is itself inherited, hence contexts that inherit it (those that don't specify their own SubstituteInheritBefore value) will apply the closest defined merge order.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_suexec - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_suexec

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | 指定されたユーザとグループで CGI スクリプトを実行する
ステータス: | Extension
モジュール識別子: | suexec_module
ソースファイル: | mod_suexec.c
互換性: | Apache 2.0 以降で使用可能

概要

このモジュールと suexec サポートプログラム により、CGI スクリプトが指定されたユーザとグループで 実行されるようにできます。

参照

  • SuEXEC サポート

SuexecUserGroup ディレクティブ

説明: | CGI プログラムのユーザパーミッション、グループパーミッション
構文: | SuexecUserGroup User Group
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Extension
モジュール: | mod_suexec
互換性: | SuexecUserGroup は 2.0 以降でのみ使用可能。

SuexecUserGroup ディレクティブは CGI プログラム が実行されるユーザとグループを指定できるようにします。CGI 以外の リクエストは User ディレクティブで指定されたユーザのままで処理されます。 このディレクティブは Apache 1.3 における VirtualHosts の中で User ディレクティブと Group ディレクティブを使う用法の代わりになります。

例

SuexecUserGroup nobody nogroup

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


mod_unique_id - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

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 サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_userdir

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明: | ユーザ専用のディレクトリを提供
ステータス: | Base
モジュール識別子: | userdir_module
ソースファイル: | mod_userdir.c

概要

このモジュールは、 http://example.com/~user/ 構文を使ってユーザ専用ディレクトリにアクセスできるようにします。

参照

  • URL から ファイルシステムへのマッピング
  • public_html チュートリアル

UserDir ディレクティブ

説明: | ユーザ専用ディレクトリの位置
構文: | UserDir directory-filename
コンテキスト: | サーバ設定ファイル, バーチャルホスト
ステータス: | Base
モジュール: | mod_userdir

UserDir ディレクティブは、 ユーザのドキュメントへのリクエストを受けた時に使う ユーザのホームディレクトリ中の、実際のディレクトリを 設定します。 directory-filename には次のどれかを指定します:

  • ディレクトリ名か下に示すようなパターン。
  • disabled キーワード。 enabled キーワード (下記参照) で明示的に 指定されたユーザ以外の 全てのユーザ名-ディレクトリ変換を しないようにします。
  • disabled キーワードと、スペース区切りのユーザ名リスト。 このリスト中に含まれるユーザ名に対しては、たとえ enabled 節にあったとしても、 決してディレクトリ変換は行われません。
  • enabled キーワードとスペース区切りのユーザ名リスト。 全体では変換が無効になっていたとしても、 これらのユーザ名にはディレクトリ変換が行われます。 ただし、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 はリダイレクトが成功するかどうかを決めることはできませんので、 リストの前の方にリダイレクトを書くと、それが必ず使用される選択肢に なってしまいます。

2.1.4 以降では、ユーザディレクトリ置換機能はデフォルトでは起動しません。 それ以前のバージョンでは、UserDir ディレクティブが存在しなければ、UserDir public_html であると仮定されていました。

参照

  • public_html チュートリアル


mod_usertrack - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_usertrack

Description: | Clickstream logging of user activity on a site
Status: | Extension
Module Identifier: | usertrack_module
Source File: | 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, .example.com is legal, but foo.example.com and .com are not.

Most browsers in use today will not allow cookies to be set for a two-part top level domain, such as .co.uk, although such a domain ostensibly fulfills the requirements above.
These domains are equivalent to top level domains such as .com, and allowing such cookies may be a security risk. Thus, if you are under a two-part top level domain, you should still use your actual domain, as you would with any other top level domain (for example, use .foo.co.uk).

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. At the time of writing, most browsers only fully support CookieStyle Netscape.

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 mod_usertrack is loaded, and CookieTracking on is set, Apache will send 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, enabling mod_usertrack will not activate cookies.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


mod_version - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

Apache モジュール mod_version

説明: | バージョン依存の設定
ステータス: | Extension
モジュール識別子: | version_module
ソースファイル: | mod_version.c
互換性: | Apache 2.0.56 以降で使用可能

概要

様々なバージョンの httpd の異なる設定を扱うことになる、 テストスイートや大規模ネットワークでの使用のために設計されています。 このモジュールは新しいコンテナ ― <IfVersion> を 提供します。これを使うと、数字の比較や正規表現による柔軟な バージョンチェックができるようになります。

例

<IfVersion 2.1.0>
# current httpd version is exactly 2.1.0
 </IfVersion>

<IfVersion >= 2.2>
# use really new features :-)
 </IfVersion>

詳細は以下を読んでください。

<IfVersion> ディレクティブ

説明: | バージョン依存の設定を入れる
構文: | <IfVersion [[!]operator] version> ... </IfVersion>
コンテキスト: | サーバ設定ファイル, バーチャルホスト, ディレクトリ, .htaccess
上書き: | All
ステータス: | Extension
モジュール: | mod_version

<IfVersion> は httpd のバージョン が基準を満たしたときにのみ実行させたいディレクティブを囲みます。 通常の (数値) 比較のときは version 引数は major[.minor[.patch]] という 形式、例えば、2.1.0 や 2.2 となります。 minor と patch は省略可能です。省略された場合は、 0 を指定したものとみなされます。比較には次の数値 operator を 指定できます:

operator | 説明
= と == | 同じ httpd バージョン
> | より大きい httpd バージョン
>= | 指定以上の httpd バージョン
< | 指定未満の httpd バージョン
<= | 指定以下の httpd バージョン

例

<IfVersion >= 2.1>
# this happens only in versions greater or
# equal 2.1.0.
 </IfVersion>

数値比較に加えて、http のバージョン番号に対して 正規表現 による マッチングができます。二種類の書き方があります:

operator | 説明
= or == | version は /regex/ 形式
~ | version は regex 形式

例

<IfVersion = /^2.1.[01234]$/>
# e.g. workaround for buggy versions </IfVersion>

マッチングの否定を表現するために、すべてのオペレータは前に 感嘆符 (!)を付けることができます:

<IfVersion !~ ^2.1.[01234]$>
# not for those versions
 </IfVersion>

operator が省略されたときは = と みなされます。


mod_vhost_alias - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

Apache Module mod_vhost_alias

Description: | Provides for dynamically configured mass virtual hosting
Status: | Extension
Module Identifier: | vhost_alias_module
Source File: | 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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Developer Documentation for Apache 2.x - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2

Developer Documentation for Apache 2.x

Warning

Many of the documents listed here are in need of update. 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
  • Documenting Apache 2.0
  • Apache 2.x Thread Safety Issues

External Resources

  • Developer articles at apachetutor include:
    • Request Processing in Apache
    • Configuration for Modules
    • Resource Management in Apache
    • Connection Pooling in Apache
    • Introduction to Buckets and Brigades

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Apache 1.3 API notes - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 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;
 }

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Debugging Memory Allocation in APR - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Developer Documentation

Debugging Memory Allocation in APR

This document has been removed.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Documenting Apache 2.0 - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Developer Documentation

Documenting Apache 2.0

Apache 2.0 uses Doxygen to document the APIs and global variables in 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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Apache 2.0 Hook Functions - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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 traditional hook return value 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, the server 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, APR_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: APR_HOOK_FIRST, APR_HOOK_MIDDLE and APR_HOOK_LAST.

All modules using any particular value may be run in any order relative to each other, but, of course, all modules using APR_HOOK_FIRST will be run before APR_HOOK_MIDDLE which are before APR_HOOK_LAST. Modules that don't care when they are run should use APR_HOOK_MIDDLE. These values are spaced out, so that positions like APR_HOOK_FIRST-2 are possible to hook slightly earlier than other functions.

Note that there are two more values, APR_HOOK_REALLY_FIRST and APR_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, APR_HOOK_MIDDLE);
 }

Note that the sort used to achieve this is stable, so ordering set by APR_HOOK_ORDER is preserved, as far as is possible.

Ben Laurie, 15th August 1999

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


モジュールの Apache 1.3 から Apache 2.0 への移植 - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > 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 the Apache HTTP Server 2.x - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Developer Documentation

Request Processing in the Apache HTTP Server 2.x

Warning

Warning - this is a first (fast) draft that needs further revision!

Several changes in 2.0 and above 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 the Apache HTTP Server 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_request_internal() 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 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 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 repercussions.

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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


How filters work in Apache 2.0 - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


用語 - Apache HTTP サーバ バージョン 2.2

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

用語

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

この用語集では Apacheに特化した用語と、 ウェブサーバ全般で一般的な用語をいくつか定義しています。 それぞれの概念の、より詳細な情報はリンク先にあります。

定義

アクセス制御
ネットワーク認可領域へのアクセスを制限します。Apache においては、 普通はアクセスの制限は URL に対するものとなります。
参照: 認証、承認、アクセス制御
アルゴリズム
有限回のステップで問題を解くためのあいまいでない式もしくは規則の 集合。暗号のためのアルゴリズムは通常 Cipher と呼ばれます。
APache eXtension Tool (apxs)
モジュール ソースを 動的共有オブジェクト (DSO) にコンパイルし、 Apache Web サーバにインストールする手助けをする perl スクリプト。
参照: マニュアルページ: apxs
Apache Portable Runtime (APR)
サーバ(訳注: Apache HTTP Server)と OS の 間の基本的なインターフェースの多くを提供する(訳注: OS の差を吸収する)ライブラリのセット。 APR は 独立した プロジェクトとして Apache HTTP Server と平行して開発が行われています。
参照: Apache Portable Runtime プロジェクト
認証
サーバ、クライアント、ユーザといったネットワークエンティティの 身元の特定。
参照: 認証、承認、アクセス制御
証明書
サーバやクライアントといったネットワークエンティティを認証するのに 使用されるデータレコード。証明書には (subject と呼ばれる) 所有者と、 (issuer と呼ばれる) 認証局 の署名、所有者の 公開鍵 と、CA による署名という X.509 の情報が含まれます。ネットワークエンティティはそれらの署名を CA 証明書を使って検証します。
参照: SSL/TLS 暗号化
証明書署名リクエスト (訳注: Certificate Signing Request) (CSR)
認証局 に提出 する未署名の 証明書。 認証局は CA 証明書 の 秘密鍵 で署名します。 一旦 CSR に署名がなされると、それは本物の証明書になります。
参照: SSL/TLS 暗号化
証明局 (訳注: Certification Authority) (CA)
安全な方法で認証を行なったネットワークエンティティの証明書を 署名するための信頼できる第三者機関。他のネットワークエンティティは 証明書の保持者が CA に認証されたかを署名を検証することで調べることが できます。
参照: SSL/TLS 暗号化
Cipher
データ暗号化のためのアルゴリズム。例えば DES, IDEA, RC4 など。
参照: SSL/TLS 暗号化
暗号文
平文 が Cipher をかけられた結果。
参照: SSL/TLS 暗号化
Common Gateway Interface (CGI)
外部プログラムがリクエストを扱うことができるようにするための ウェブサーバと外部プログラム間のインタフェースの標準仕様。 インタフェースは元々 NCSA により定義 されていましたが RFC プロジェクト も存在します。
参照: CGI による動的コンテンツ
設定ディレクティブ
参照: ディレクティブ
設定ファイル
Apache の設定を制御する ディレクティブ の書かれたテキストファイル。
参照: 設定ファイル
CONNECT
データチャネルをそのまま HTTP 上でプロキシするための HTTP メソッド。SSL のような他の プロトコルをくるむために使うことができます。
コンテキスト
設定ファイル 中で、 特定の種類の ディレクティブ が許可されている場所。
参照: Apache のディレクティブの 説明に使われている用語
デジタル署名
証明書や他のファイルを検証するための暗号化されたテキストブロック。 認証局 は 証明書 に埋め込まれた 公開鍵 のハッシュを作成し、 それを自身の 秘密鍵 で暗号化することで署名を作成します。 CA の公開鍵でのみその署名を復号することができますので、それにより 証明書 を保有するネットワークエンティティを CA が認証した ことを検証できます。
参照: SSL/TLS 暗号化
ディレクティブ
Apache のいろいろな振る舞いを制御する設定コマンド。ディレクティブは 設定ファイル に 書かれます。
参照: ディレクティブ索引
動的 共有オブジェクト (訳注: Dynamic Shared Object) (DSO)
必要に応じて読み込むことが可能な、Apache httpd とは 別にコンパイルされた モジュール
参照: 動的共有オブジェクトサポート
環境変数 (env-variable)
情報を保管したり、プログラム間の通信をするために使われる、 オペレーティングシステムのシェルにより管理されている名前付きの変数。 Apache も環境変数と呼ばれる内部変数を持っていますが、こちらは シェル環境ではなく、Apache の内部構造体に保持されています。
参照: Apache の環境変数
輸出強度削減 (訳注: Export-Crippled)
アメリカの Export Administration Regulations (EAR) (訳注: 輸出管理規則) に従うために暗号の強度 (とセキュリティ) を削減すること。輸出強度削減された暗号ソフトウェアは小さいキーに 制限され、通常総当たり攻撃で復号できてしまう 暗号文 を生成する ことになります。
参照: SSL/TLS 暗号化
フィルタ
サーバから送られるデータとサーバが受け取るデータに適用される処理。 入力フィルタはクライアントからサーバに送られたデータを処理し、 出力フィルタはサーバにある文書をクライアントに送る前に処理します。 例えば、INCLUDES 出力フィルタは Server Side Includes の文書を 処理します。
参照: フィルタ
完全修飾ドメイン名 (訳注: Fully-Qualified Domain-Name) (FQDN)
IP アドレスに解決できるホスト名と、ドメイン名からなるネットワーク エンティティの一意な名前。例えば、www はホスト名で、 example.com はドメイン名なので、 www.example.com は完全修飾ドメイン名になります。
ハンドラ
ファイルが呼ばれたときに行なわれる動作の Apache の内部での表現。 一般にファイルにはファイルの種類に応じて暗黙のハンドラが設定されて います。普通はすべてのファイルがサーバにより送られますが、別に 扱われる (訳注: handle) ファイルの種類も存在します。 例えば cgi-script はファイルが CGI として処理されるように指定します。
参照: Apache のハンドラの使用
ハッシュ
任意の文字列から固定長の文字列を生成する、数学的な一方向で不可逆な アルゴリズム。異なった入力文字列からは普通は違うハッシュが生成されます (ハッシュ関数に依存します)。
ヘッダ
実際のコンテンツの前に送られ、コンテンツを説明するメタ情報の 入った HTTP リクエストと応答の一部分。
.htaccess
ウェブツリーに置かれて、そのディレクトリとサブディレクトリに ディレクティブ を適用する 設定ファイル。 名前とは裏腹に、このファイルにはアクセス制御ディレクティブだけでなく、 ほとんどどんな種類のディレクティブでも書くことができます。
参照: 設定ファイル
httpd.conf
メインの Apache 設定 ファイル。デフォルトの場所は /usr/local/apache2/conf/httpd.conf ですが、実行時やコンパイル時の設定により違う場所に移動されて いるかもしれません。
参照: 設定ファイル
HyperText Transfer Protocol (HTTP)
World Wide Web で使われる標準の転送プロトコル。Apache は HTTP/1.1 と呼ばれ、RFC 2616 で定義されているプロトコルのバージョン 1.1 を実装しています。
HTTPS
The HyperText Transfer Protocol (Secure), World Wide Web での暗号化された標準の通信機構。これは実際は 単に SSL 上での HTTP です。
参照: SSL/TLS 暗号化
メソッド
HTTP の文脈では、 クライアントから指定されたリクエスト行に対応するリソース に対して行なう動作。HTTP では GET, POST, PUT といったようなメソッドがあります。
メッセージダイジェスト
メッセージのハッシュで、メッセージの内容が転送時に変更されていないことの検証に 使える。
参照: SSL/TLS 暗号化
MIME タイプ
送信されているドキュメントの種類を表すための方法。 この名前はフォーマットが Multipurpose Internet Mail Extensions から 借りてこられたことによります。これはスラッシュで分離された、 主タイプと副タイプからなります。例えば、text/html, image/gif, application/octet-stream など があります。HTTP では、MIME タイプは Content-Type ヘッダ で送信されます。
参照: mod_mime
モジュール
プログラムの独立した一部分。Apache の機能の多くは使用するかしないかを 選択できるモジュールの中にあります。Apache httpd に組み込まれているモジュールは静的モジュールと呼ばれ、 別に保存され、実行時に読み込むことのできるモジュールは 動的モジュール もしくは DSO と 呼ばれます。デフォルトで含まれているモジュールはbase モジュール と呼ばれます。Apache HTTP サーバの tarball の一部としては配られていない Apache 用のモジュールがあります。 それらは サードパーティモジュール と呼ばれます。
参照: モジュール索引
Module Magic Number (MMN)
Apache ソースコードで定義されている、モジュールのバイナリ互換性に 関する定数。バイナリ互換性が保てなくなるような Apache 内部の構造体や、 関数呼び出し、その他の API の重要な部分の変更があったときに変更されます。 MMN が変わると、すべてのサードパーティモジュールは少なくとも再コンパイルを する必要があり、場合によっては新しいバージョンの Apache で動作するために 少し変更する必要さえあるかもしれません。
OpenSSL
SSL/TLS 用のオープンソースツールキット
参照 http://www.openssl.org/#
パスフレーズ
秘密鍵のファイルを保護するための語句。権限の無いユーザが 暗号化するのを防ぎます。通常は単に Cipher の秘密の暗号用と復号用のキーです。
参照: SSL/TLS 暗号化
平文
暗号化されていないテキスト。
秘密鍵
受け取るメッセージの復号と送出するメッセージの署名に使われる、 公開鍵暗号 の 秘密鍵。
参照: SSL/TLS 暗号化
プロキシ
クライアントと オリジンのサーバ の間に存在する中間サーバ。 クライアントからのリクエストを受け取り、オリジンのサーバに送信して、オリジンの サーバからの応答をクライアントに返します。複数のクライアントが同じ コンテンツを要求する場合は、毎回元のサーバにリクエストを送る代わり プロキシはキャッシュからコンテンツを送り、応答時間を短縮することが できます。
参照: mod_proxy
公開鍵
所有者に向けられたメッセージの暗号化と所有者による署名の復号に使われる、 公開鍵暗号システムに おける公けにされている鍵。
参照: SSL/TLS 暗号化
公開鍵暗号
ある鍵を暗号に使い、別の鍵を復号に使う非対称暗号システムについての研究や その応用を指す。対応する鍵はキーペアと呼ばれます。非対称暗号とも呼ばれます。
参照: SSL/TLS 暗号化
正規表現 (Regex)
テキストのパターンを表現する方式の一つ。例えば、 「A で始まるすべての単語」や「すべての 10 桁の電話番号」や、 「コンマが二つあり、大文字の Q がないすべての文」というのでさえ表現 できます。 正規表現は Apache においても便利なもので、ファイルやリソースの集まりに対して 何らかの属性を適用することがとても柔軟にできます。例えば、 すべての "images" ディレクトリの下の、すべての .gif と .jpg ファイル は /images/.*(jpg|gif)$ と書くことができます。 Apache では PCRE ライブラリが提供する Perl 互換正規表現 (訳注: Perl Compatible Regular Expressions) を使います。
リバースプロキシ
クライアントには オリジンのサーバ のように見える プロキシ サーバ。セキュリティの ためや、負荷分散のためにクライアントからオリジンのサーバを隠したいときに 便利です。
Secure Sockets Layer (SSL)
Netscape Communications Corporation により TCP/IP ネットワーク上で一般の通信の認証と暗号用に作られたプロトコル。 最もよく使われているものは HTTPS つまり SSL 上での HyperText Transfer Protocol (HTTP) です。
参照: SSL/TLS 暗号化
Server Side Includes (SSI)
HTML ファイル中に処理ディレクティブを埋め込む技術の一つ。
参照: Server Side Includes 入門
セッション
一般的な通信における文脈情報。
SSLeay
Eric A. Young 氏による SSL/TLS を実装した元々のライブラリ。
対称暗号
一つの秘密鍵を暗号化と復号の両方に使う Cipher の 研究や応用を指す。
Tarball
tar ユーティリティを使ってまとめられたファイルのパッケージ。 Apache 配布は圧縮された tar アーカイブか pkzip で保管されています。
Transport Layer Security (TLS)
TCP/IP ネットワーク上での一般通信の認証と暗号化用に Internet Engineering Task Force (IETF) により作成された SSL の 後継プロトコル。TLS バージョン 1 は SSL バージョン 3 とほぼ同じです。
参照: SSL/TLS 暗号化
Uniform Resource Locator (URL)
Internet のリソースの名前、もしくはアドレス。これは正式には Uniform Resource Identifier と呼ばれるもののよく使われる非公式な名前です。URL は普通は、 http や https といったスキームとホスト名、 パスからなります。このページの URL はおそらく http://httpd.apache.org/docs/2.2/glossary.html と思われます。
Uniform Resource Identifier (URI)
抽象的なリソースや物理リソースを同定するためのコンパクトな文字列。 正式には RFC 2396 で 定義されています。WWW で使われている URI は通常 URL と呼ばれます。
バーチャルホスト
一つの Apache を使って複数のウェブサイトを扱うこと。 IP バーチャルホスト は IP アドレスを使ってウェブサイトを 区別します。また 名前ベースのバーチャルホスト は ホストの名前だけを使って区別するので、同じ IP アドレス上での多くのサイトを ホストできます。
参照: Apache バーチャルホストの文書
X.509
SSL/TLS 認証に使われている International Telecommunication Union (ITU-T) により推奨されている認証証明書の形式。
参照: SSL/TLS 暗号化

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


モジュール一覧 - Apache HTTP サーバ バージョン 2.2

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

モジュール一覧

以下は Apache の配布の一部として配られているすべてのモジュールの 一覧です。すべての Apache ディレクティブ のアルファベット順のリストも見てください。

参照

  • マルチプロセッシングモジュール (MPMs)
  • ディレクティブ クイックリファレンス

コア機能と MPM

core
常に使用可能な Apache HTTP サーバのコア機能
mpm_common
二つ以上のマルチプロセッシングモジュール (MPM) で実装されているディレクティブのコレクション
beos
This Multi-Processing Module is optimized for BeOS.
event
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
prefork
スレッドを使わず、先行して fork を行なうウェブサーバを実装
mpm_winnt
Windows NT 向けに最適化されたマルチプロセッシングモジュール
worker
マルチスレッドとマルチプロセスのハイブリッド型 ウェブサーバを実装したマルチプロセッシングモジュール

他のモジュール

A | C | D | E | F | H | I | L | M | N | P | R | S | U | V

mod_actions
メディアタイプやリクエストメソッドに応じて CGI スクリプトを実行する機能を提供
mod_alias
ホストファイルシステム上のいろいろな違う場所を ドキュメントツリーにマップする機能と、 URL のリダイレクトを行なう機能を提供する
mod_asis
自分用の HTTP ヘッダの書かれているファイルを送信する
mod_auth_basic
基本認証
mod_auth_digest
User authentication using MD5 Digest Authentication.
mod_authn_alias
Provides the ability to create extended authentication providers based on actual providers
mod_authn_anon
認証が必要な領域への "anonymous" ユーザのアクセスを許可する
mod_authn_dbd
User authentication using an SQL database
mod_authn_dbm
DBM ファイルを用いたユーザ認証
mod_authn_default
認証フォールバックモジュール
mod_authn_file
テキストファイルを用いたユーザ認証
mod_authnz_ldap
Allows an LDAP directory to be used to store the database for HTTP Basic authentication.
mod_authz_dbm
Group authorization using DBM files
mod_authz_default
承認フォールバックモジュール
mod_authz_groupfile
プレーンテキストファイルを用いたグループ承認
mod_authz_host
ホスト (名前もしくは IP アドレス) に基づいたグループ承認
mod_authz_owner
ファイルの所有者に基づいた承認
mod_authz_user
ユーザ承認
mod_autoindex
Unix の ls コマンドや Win32 の dir シェルコマンドに似た ディレクトリインデックスを生成する
mod_cache
URI をキーにしたコンテンツのキャッシュ
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_dav_lock
mod_dav 用の汎用ロックモジュール
mod_dbd
Manages SQL database connections
mod_deflate
クライアントへ送られる前にコンテンツを圧縮する
mod_dir
「最後のスラッシュ」のリダイレクトと、ディレクトリの インデックスファイルを扱う機能を提供する
mod_disk_cache
URI をキーにしたコンテンツキャッシュストレージ管理
mod_dumpio
望むようにすべての I/O をエラーログにダンプする
mod_echo
プロトコルモジュールの概要を示すための単純なエコーサーバ
mod_env
CGI スクリプト及び SSI ページに渡される環境変数を変更する機能を提供する
mod_example
Illustrates the Apache module API
mod_expires
ユーザの指定した基準に基づいた Expires と Cache-Control HTTP ヘッダの生成
mod_ext_filter
レスポンスのボディをクライアントに送る前に外部プログラムで処理する
mod_file_cache
Caches a static list of files in memory
mod_filter
Context-sensitive smart filter configuration module
mod_headers
HTTP リクエストのヘッダと応答のヘッダのカスタマイズ
mod_ident
RFC 1413 ident lookups
mod_imagemap
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 ロギング
mod_logio
リクエスト毎に入力バイト数と出力バイト数とをロギング
mod_mem_cache
URI をキーにしたコンテンツのキャッシュ
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 プロキシ/ゲートウェイサーバ
mod_proxy_ajp
mod_proxy で AJP をサポートするためのモジュール
mod_proxy_balancer
負荷分散のための mod_proxy 拡張
mod_proxy_connect
CONNECT リクエストを扱う mod_proxy 用の拡張
mod_proxy_ftp
mod_proxy のための FTP サポートモジュール
mod_proxy_http
mod_proxy のための HTTP サポートモジュール
mod_proxy_scgi
mod_proxy のための SCGI ゲートウェイモジュール
mod_reqtimeout
Set timeout and minimum data rate for receiving requests
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_substitute
Perform search and replace operations on response bodies
mod_suexec
指定されたユーザとグループで CGI スクリプトを実行する
mod_unique_id
それぞれのリクエストに対する一意な識別子の入った環境変数を 提供する
mod_userdir
ユーザ専用のディレクトリを提供
mod_usertrack
Clickstream logging of user activity on a site
mod_version
バージョン依存の設定
mod_vhost_alias
Provides for dynamically configured mass virtual hosting


ディレクティブ一覧 - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

ディレクティブ一覧

標準 Apache 配布にあるすべての Apache のディレクティブの一覧です。 これらは一貫した形式で書かれていて、使われている用語の 用語集 も用意されています。

各ディレクティブの概要を説明した ディレクティブクイックリファレンスも あります。

A | B | C | D | E | F | G | H | I | K | L | M | N | O | P | R | S | T | U | V | W | X

  • AcceptFilter
  • AcceptMutex
  • 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_LogEmail
  • Anonymous_MustGiveEmail
  • Anonymous_NoUserID
  • Anonymous_VerifyEmail
  • AuthBasicAuthoritative
  • AuthBasicProvider
  • AuthDBDUserPWQuery
  • AuthDBDUserRealmQuery
  • AuthDBMGroupFile
  • AuthDBMType
  • AuthDBMUserFile
  • AuthDefaultAuthoritative
  • AuthDigestAlgorithm
  • AuthDigestDomain
  • AuthDigestNcCheck
  • AuthDigestNonceFormat
  • AuthDigestNonceLifetime
  • AuthDigestProvider
  • AuthDigestQop
  • AuthDigestShmemSize
  • AuthGroupFile
  • AuthLDAPBindAuthoritative
  • AuthLDAPBindDN
  • AuthLDAPBindPassword
  • AuthLDAPCharsetConfig
  • AuthLDAPCompareDNOnServer
  • AuthLDAPDereferenceAliases
  • AuthLDAPGroupAttribute
  • AuthLDAPGroupAttributeIsDN
  • AuthLDAPRemoteUserAttribute
  • AuthLDAPRemoteUserIsDN
  • AuthLDAPUrl
  • AuthName
  • <AuthnProviderAlias>
  • AuthType
  • AuthUserFile
  • AuthzDBMAuthoritative
  • AuthzDBMType
  • AuthzDefaultAuthoritative
  • AuthzGroupFileAuthoritative
  • AuthzLDAPAuthoritative
  • AuthzOwnerAuthoritative
  • AuthzUserAuthoritative
  • BalancerMember
  • BrowserMatch
  • BrowserMatchNoCase
  • BufferedLogs
  • CacheDefaultExpire
  • CacheDirLength
  • CacheDirLevels
  • CacheDisable
  • CacheEnable
  • CacheFile
  • CacheIgnoreCacheControl
  • CacheIgnoreHeaders
  • CacheIgnoreNoLastMod
  • CacheIgnoreQueryString
  • CacheIgnoreURLSessionIdentifiers
  • CacheLastModifiedFactor
  • CacheLock
  • CacheLockMaxAge
  • CacheLockPath
  • CacheMaxExpire
  • CacheMaxFileSize
  • CacheMinFileSize
  • CacheNegotiatedDocs
  • CacheRoot
  • CacheStoreNoStore
  • CacheStorePrivate
  • CGIDScriptTimeout
  • CGIMapExtension
  • CharsetDefault
  • CharsetOptions
  • CharsetSourceEnc
  • CheckCaseOnly
  • CheckSpelling
  • ChrootDir
  • ContentDigest
  • CookieDomain
  • CookieExpires
  • CookieLog
  • CookieName
  • CookieStyle
  • CookieTracking
  • CoreDumpDirectory
  • CustomLog
  • Dav
  • DavDepthInfinity
  • DavGenericLockDB
  • DavLockDB
  • DavMinTimeout
  • DBDExptime
  • DBDKeep
  • DBDMax
  • DBDMin
  • DBDParams
  • DBDPersist
  • DBDPrepareSQL
  • DBDriver
  • DefaultIcon
  • DefaultLanguage
  • DefaultType
  • DeflateBufferSize
  • DeflateCompressionLevel
  • DeflateFilterNote
  • DeflateInflateLimitRequestBody
  • DeflateInflateRatioBurst
  • DeflateInflateRatioLimit
  • DeflateMemLevel
  • DeflateWindowSize
  • Deny
  • <Directory>
  • DirectoryIndex
  • <DirectoryMatch>
  • DirectorySlash
  • DocumentRoot
  • DumpIOInput
  • DumpIOLogLevel
  • DumpIOOutput
  • EnableExceptionHook
  • EnableMMAP
  • EnableSendfile
  • ErrorDocument
  • ErrorLog
  • Example
  • ExpiresActive
  • ExpiresByType
  • ExpiresDefault
  • ExtendedStatus
  • ExtFilterDefine
  • ExtFilterOptions
  • FallbackResource
  • FileETag
  • <Files>
  • <FilesMatch>
  • FilterChain
  • FilterDeclare
  • FilterProtocol
  • FilterProvider
  • FilterTrace
  • ForceLanguagePriority
  • ForceType
  • ForensicLog
  • GprofDir
  • GracefulShutdownTimeout
  • Group
  • Header
  • HeaderName
  • HostnameLookups
  • HttpProtocolOptions
  • IdentityCheck
  • IdentityCheckTimeout
  • <IfDefine>
  • <IfModule>
  • <IfVersion>
  • ImapBase
  • ImapDefault
  • ImapMenu
  • Include
  • IndexHeadInsert
  • IndexIgnore
  • IndexOptions
  • IndexOrderDefault
  • IndexStyleSheet
  • ISAPIAppendLogToErrors
  • ISAPIAppendLogToQuery
  • ISAPICacheFile
  • ISAPIFakeAsync
  • ISAPILogNotSupported
  • ISAPIReadAheadBuffer
  • KeepAlive
  • KeepAliveTimeout
  • LanguagePriority
  • LDAPCacheEntries
  • LDAPCacheTTL
  • LDAPConnectionTimeout
  • LDAPOpCacheEntries
  • LDAPOpCacheTTL
  • LDAPSharedCacheFile
  • LDAPSharedCacheSize
  • LDAPTrustedClientCert
  • LDAPTrustedGlobalCert
  • LDAPTrustedMode
  • LDAPVerifyServerCert
  • <Limit>
  • <LimitExcept>
  • LimitInternalRecursion
  • LimitRequestBody
  • LimitRequestFields
  • LimitRequestFieldSize
  • LimitRequestLine
  • LimitXMLRequestBody
  • Listen
  • ListenBackLog
  • LoadFile
  • LoadModule
  • <Location>
  • <LocationMatch>
  • LockFile
  • LogFormat
  • LogLevel
  • MaxClients
  • MaxKeepAliveRequests
  • MaxMemFree
  • MaxRanges
  • MaxRequestsPerChild
  • MaxRequestsPerThread
  • MaxSpareServers
  • MaxSpareThreads
  • MaxThreads
  • MCacheMaxObjectCount
  • MCacheMaxObjectSize
  • MCacheMaxStreamingBuffer
  • MCacheMinObjectSize
  • MCacheRemovalAlgorithm
  • MCacheSize
  • MergeTrailers
  • MetaDir
  • MetaFiles
  • MetaSuffix
  • MimeMagicFile
  • MinSpareServers
  • MinSpareThreads
  • MMapFile
  • ModMimeUsePathInfo
  • MultiviewsMatch
  • NameVirtualHost
  • NoProxy
  • NWSSLTrustedCerts
  • NWSSLUpgradeable
  • Options
  • Order
  • PassEnv
  • PidFile
  • Protocol
  • ProtocolEcho
  • <Proxy>
  • ProxyBadHeader
  • ProxyBlock
  • ProxyDomain
  • ProxyErrorOverride
  • ProxyFtpDirCharset
  • ProxyIOBufferSize
  • <ProxyMatch>
  • ProxyMaxForwards
  • ProxyPass
  • ProxyPassInterpolateEnv
  • ProxyPassMatch
  • ProxyPassReverse
  • ProxyPassReverseCookieDomain
  • ProxyPassReverseCookiePath
  • ProxyPreserveHost
  • ProxyReceiveBufferSize
  • ProxyRemote
  • ProxyRemoteMatch
  • ProxyRequests
  • ProxySCGIInternalRedirect
  • ProxySCGISendfile
  • ProxySet
  • ProxyStatus
  • ProxyTimeout
  • ProxyVia
  • ReadmeName
  • ReceiveBufferSize
  • Redirect
  • RedirectMatch
  • RedirectPermanent
  • RedirectTemp
  • RegisterHttpMethod
  • RemoveCharset
  • RemoveEncoding
  • RemoveHandler
  • RemoveInputFilter
  • RemoveLanguage
  • RemoveOutputFilter
  • RemoveType
  • RequestHeader
  • RequestReadTimeout
  • Require
  • RewriteBase
  • RewriteCond
  • RewriteEngine
  • RewriteLock
  • RewriteLog
  • RewriteLogLevel
  • RewriteMap
  • RewriteOptions
  • RewriteRule
  • RLimitCPU
  • RLimitMEM
  • RLimitNPROC
  • Satisfy
  • ScoreBoardFile
  • Script
  • ScriptAlias
  • ScriptAliasMatch
  • ScriptInterpreterSource
  • ScriptLog
  • ScriptLogBuffer
  • ScriptLogLength
  • ScriptSock
  • SecureListen
  • SeeRequestTail
  • SendBufferSize
  • ServerAdmin
  • ServerAlias
  • ServerLimit
  • ServerName
  • ServerPath
  • ServerRoot
  • ServerSignature
  • ServerTokens
  • SetEnv
  • SetEnvIf
  • SetEnvIfNoCase
  • SetHandler
  • SetInputFilter
  • SetOutputFilter
  • SSIEnableAccess
  • SSIEndTag
  • SSIErrorMsg
  • SSIETag
  • SSILastModified
  • SSIStartTag
  • SSITimeFormat
  • SSIUndefinedEcho
  • SSLCACertificateFile
  • SSLCACertificatePath
  • SSLCADNRequestFile
  • SSLCADNRequestPath
  • SSLCARevocationFile
  • SSLCARevocationPath
  • SSLCertificateChainFile
  • SSLCertificateFile
  • SSLCertificateKeyFile
  • SSLCipherSuite
  • SSLCompression
  • SSLCryptoDevice
  • SSLEngine
  • SSLFIPS
  • SSLHonorCipherOrder
  • SSLInsecureRenegotiation
  • SSLMutex
  • SSLOptions
  • SSLPassPhraseDialog
  • SSLProtocol
  • SSLProxyCACertificateFile
  • SSLProxyCACertificatePath
  • SSLProxyCARevocationFile
  • SSLProxyCARevocationPath
  • SSLProxyCheckPeerCN
  • SSLProxyCheckPeerExpire
  • SSLProxyCipherSuite
  • SSLProxyEngine
  • SSLProxyMachineCertificateChainFile
  • SSLProxyMachineCertificateFile
  • SSLProxyMachineCertificatePath
  • SSLProxyProtocol
  • SSLProxyVerify
  • SSLProxyVerifyDepth
  • SSLRandomSeed
  • SSLRenegBufferSize
  • SSLRequire
  • SSLRequireSSL
  • SSLSessionCache
  • SSLSessionCacheTimeout
  • SSLSessionTicketKeyFile
  • SSLSessionTickets
  • SSLStrictSNIVHostCheck
  • SSLUserName
  • SSLVerifyClient
  • SSLVerifyDepth
  • StartServers
  • StartThreads
  • Substitute
  • SubstituteInheritBefore
  • Suexec
  • SuexecUserGroup
  • ThreadLimit
  • ThreadsPerChild
  • ThreadStackSize
  • TimeOut
  • TraceEnable
  • TransferLog
  • TypesConfig
  • UnsetEnv
  • UseCanonicalName
  • UseCanonicalPhysicalPort
  • User
  • UserDir
  • VirtualDocumentRoot
  • VirtualDocumentRootIP
  • <VirtualHost>
  • VirtualScriptAlias
  • VirtualScriptAliasIP
  • Win32DisableAcceptEx
  • XBitHack


ディレクティブ クイックリファレンス - Apache HTTP サーバ バージョン 2.2

Apache > HTTP サーバ > ドキュメンテーション > バージョン 2.2 > モジュール

ディレクティブ クイックリファレンス

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

ディレクティブ クイックリファレンスでは、各 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
AcceptFilter protocol accept_filter |  | s | C
プロトコルを Listen しているソケットの最適化を設定する
AcceptMutex default|method | default | s | M
複数の子プロセスがネットワークソケットでリクエストを accept しようとしているときに、Apache がそれらの子プロセスを直列化するために 使う方法
AcceptPathInfo On|Off|Default | Default | svdh | C
後に続くパス名情報を受け付けるリソースの指定
AccessFileName filename [filename] ... | .htaccess | sv | C
分散設定ファイルの名前
Action action-type cgi-script [virtual] |  | 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 | B
ファイル名の拡張子を指定された文字セットにマップする
AddDefaultCharset On|Off|charset | Off | svdh | C
レスポンスのコンテントタイプが text/plain あるいは text/html の場合に追加するデフォルトの charset パラメータ
AddDescription string file [file] ... |  | svdh | B
ファイルに対して表示する説明
AddEncoding MIME-enc extension [extension] ... |  | svdh | B
ファイル名の拡張子を指定されたエンコーディング にマップする
AddHandler handler-name extension [extension] ... |  | svdh | B
ファイル名の拡張子を指定されたハンドラにマップする
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 | B
ファイルの拡張子をクライアントのリクエストを処理する フィルタにマップする
AddLanguage MIME-lang extension [extension] ... |  | svdh | B
ファイル名を指定された言語にマップ
AddModuleInfo module-name string |  | sv | E
server-info ハンドラにより表示されるモジュールの情報に 追加の情報を付け加える
AddOutputFilter filter[;filter...] extension [extension] ... |  | svdh | B
ファイル名の拡張子をサーバからの応答を処理するフィルタに マップする
AddOutputFilterByType filter[;filter...] MIME-type [MIME-type] ... |  | svdh | C
MIME-type に出力フィルタを割り当てる
AddType MIME-type extension [extension] ... |  | svdh | B
ファイル名の拡張子を指定されたコンテントタイプにマップ
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
プロキシを経由して、どのポートに CONNECT できるかを指定する
AllowEncodedSlashes On|Off | Off | sv | C
URL 中の符号化されたパス分離文字が先に伝えられるのを許可するかどうかを 決定する
AllowOverride All|None|directive-type [directive-type] ... | All | d | C
.htaccess で許可されるディレクティブの種類
Anonymous user [user] ... |  | dh | E
パスワードの検査無しでアクセスを許可する userID を指定する
Anonymous_LogEmail On|Off | On | dh | E
入力されたパスワードがエラーログにロギングされるかどうかを 設定する
Anonymous_MustGiveEmail On|Off | On | dh | E
空パスワードを許可するかどうかを指定する
Anonymous_NoUserID On|Off | Off | dh | E
空 userID を許可するかを指定する
Anonymous_VerifyEmail On|Off | Off | dh | E
パスワード欄が正しい形式の電子メールアドレスであることを 調べるかどうかを設定する
AuthBasicAuthoritative On|Off | On | dh | B
認証と承認を、より低いレベルのモジュールに移行させるかを 設定します。
AuthBasicProvider On|Off|provider-name [provider-name] ... | On | dh | B
この位置に対する認証プロバイダを設定します。
AuthDBDUserPWQuery query |  | d | E
SQL query to look up a password for a user
AuthDBDUserRealmQuery query |  | d | E
SQL query to look up a password hash for a user and realm.
AuthDBMGroupFile file-path |  | dh | E
Sets the name of the database file containing the list of user groups for authorization
AuthDBMType default|SDBM|GDBM|NDBM|DB | default | dh | E
パスワードを保存するために必要なデータベースファイルの種類を 設定する
AuthDBMUserFile file-path |  | dh | E
認証用のユーザとパスワードのリストを保持している データベースファイル名を設定する
AuthDefaultAuthoritative On|Off | On | dh | B
次の低次レベルの認証モジュールに制御を渡すかどうかを 設定します
AuthDigestAlgorithm MD5|MD5-sess | MD5 | dh | E
Selects the algorithm used to calculate the challenge and response hashes in digest authentication
AuthDigestDomain URI [URI] ... |  | dh | E
URIs that are in the same protection space for digest authentication
AuthDigestNcCheck On|Off | Off | s | E
Enables or disables checking of the nonce-count sent by the server
AuthDigestNonceFormat format |  | dh | E
Determines how the nonce is generated
AuthDigestNonceLifetime seconds | 300 | dh | E
How long the server nonce is valid
AuthDigestProvider provider-name [provider-name] ... | file | dh | E
Sets the authentication provider(s) for this location
AuthDigestQop none|auth|auth-int [auth|auth-int] | auth | dh | E
Determines the quality-of-protection to use in digest authentication
AuthDigestShmemSize size | 1000 | s | E
The amount of shared memory to allocate for keeping track of clients
AuthGroupFile file-path |  | dh | B
証認に使用するユーザグループの一覧が格納されている、 テキストファイルの名前を設定する
AuthLDAPBindAuthoritativeoff|on | on | dh | E
Determines if other authentication providers are used when a user can be mapped to a DN but the server cannot successfully bind with the user's credentials.
AuthLDAPBindDN distinguished-name |  | dh | E
Optional DN to use in binding to the LDAP server
AuthLDAPBindPassword password |  | dh | E
Password used in conjuction with the bind DN
AuthLDAPCharsetConfig file-path |  | s | E
Language to charset conversion configuration file
AuthLDAPCompareDNOnServer on|off | on | dh | E
Use the LDAP server to compare the DNs
AuthLDAPDereferenceAliases never|searching|finding|always | Always | dh | E
When will the module de-reference aliases
AuthLDAPGroupAttribute attribute | member uniquemember + | dh | E
LDAP attributes used to check for group membership
AuthLDAPGroupAttributeIsDN on|off | on | dh | E
Use the DN of the client username when checking for group membership
AuthLDAPRemoteUserAttribute uid |  | dh | E
Use the value of the attribute returned during the user query to set the REMOTE_USER environment variable
AuthLDAPRemoteUserIsDN on|off | off | dh | E
Use the DN of the client username to set the REMOTE_USER environment variable
AuthLDAPUrl url [NONE|SSL|TLS|STARTTLS] |  | dh | E
URL specifying the LDAP search parameters
AuthName auth-domain |  | dh | C
HTTP 認証の認可領域 (訳注: realm)
<AuthnProviderAlias baseProvider Alias> ... </AuthnProviderAlias> |  | s | E
Enclose a group of directives that represent an extension of a base authentication provider and referenced by the specified alias
AuthType Basic|Digest |  | dh | C
ユーザ認証の種類
AuthUserFile file-path |  | dh | B
認証に使用するユーザとパスワードの一覧が格納されている、 テキストファイルの名前を設定する
AuthzDBMAuthoritative On|Off | On | dh | E
Sets whether authorization will be passed on to lower level modules
AuthzDBMType default|SDBM|GDBM|NDBM|DB | default | dh | E
Sets the type of database file that is used to store list of user groups
AuthzDefaultAuthoritative On|Off | On | dh | B
承認が低位のモジュールに渡されるかどうかを設定する
AuthzGroupFileAuthoritative On|Off | On | dh | B
承認が下位のモジュールに渡されるかどうかを設定する
AuthzLDAPAuthoritative on|off | on | dh | E
Prevent other authentication modules from authenticating the user if this one fails
AuthzOwnerAuthoritative On|Off | On | dh | E
承認が下位承認モジュールに渡されるかどうかを設定する
AuthzUserAuthoritative On|Off | On | dh | B
承認が下位のモジュールに渡されるかどうかを設定する
BalancerMember [balancerurl] url [key=value [key=value ...]] |  | d | E
ロードバランサのグループにメンバーを追加
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 に基づいて大文字小文字を区別せずに 環境変数を設定する
BufferedLogs On|Off | Off | s | B
ディスクに書き出す前にメモリにログエントリをバッファする
CacheDefaultExpire seconds | 3600 (1時間) | sv | E
期日が指定されていないときにドキュメントをキャッシュするデフォルトの期間
CacheDirLength length | 2 | sv | E
サブディレクトリ名の文字数
CacheDirLevels levels | 3 | sv | E
キャッシュのサブディレクトリの深さの数
CacheDisable url-string |  | sv | E
特定の URL をキャッシュしない
CacheEnable cache_type url-string |  | sv | E
指定したストレージ管理方式を使ってのキャッシュを有効にする
CacheFile file-path [file-path] ... |  | s | X
Cache a list of file handles at startup time
CacheIgnoreCacheControl On|Off | Off | sv | E
キャッシュされているコンテンツを返さないようにクライアントから リクエストされても無視する
CacheIgnoreHeaders header-string [header-string] ... | None | sv | E
指定された HTTP ヘッダをキャッシュに保存しない。
CacheIgnoreNoLastMod On|Off | Off | sv | E
応答に Last Modified が無くても気にしないようにする
CacheIgnoreQueryString On|Off | Off | sv | E
Ignore query string when caching
CacheIgnoreURLSessionIdentifiers identifier [identifier] ... | None | sv | E
Ignore defined session identifiers encoded in the URL when caching
CacheLastModifiedFactor float | 0.1 | sv | E
LastModified の日付に基づいて有効期限 (expiry) を計算するための重みを指定する
CacheLock on|off | off | sv | E
Enable the thundering herd lock.
CacheLockMaxAge integer | 5 | sv | E
Set the maximum possible age of a cache lock.
CacheLockPath directory | /tmp/mod_cache-lock + | sv | E
Set the lock path directory.
CacheMaxExpire seconds | 86400 (一日) | sv | E
ドキュメントをキャッシュする最大時間を秒数で表したもの
CacheMaxFileSize bytes | 1000000 | sv | E
キャッシュに保管されるドキュメントの最大の (バイトでの) サイズ
CacheMinFileSize bytes | 1 | sv | E
キャッシュに保管されるドキュメントの最小限の (バイトでの) 大きさ
CacheNegotiatedDocs On|Off | Off | sv | B
コンテントネゴシエーションされたドキュメントをプロキシサーバが キャッシュできるようにする
CacheRoot directory |  | sv | E
キャッシュファイルが保管されるルートディレクトリ
CacheStoreNoStore On|Off | Off | sv | E
no-store と指定されているレスポンスのキャッシュを試みる。
CacheStorePrivate On|Off | Off | sv | E
private と指定されているレスポンスのキャッシュを試みる。
CGIDScriptTimeout time[s|ms] |  | svdh | B
The length of time to wait for more output from the CGI program
CGIMapExtension cgi-path .extension |  | dh | C
CGI スクリプトのインタープリタの位置を調べるための手法
CharsetDefault charset |  | svdh | E
Charset to translate into
CharsetOptions option [option] ... | DebugLevel=0 NoImpl + | svdh | E
Configures charset translation behavior
CharsetSourceEnc charset |  | svdh | E
Source charset of files
CheckCaseOnly on|off | Off | svdh | E
Limits the action of the speling module to case corrections
CheckSpelling on|off | Off | svdh | E
spelling モジュールを使用するようにする
ChrootDir /path/to/directory |  | s | M
Directory for apache to run chroot(8) after startup.
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 リクエストを許可します
DavGenericLockDB file-path |  | svd | E
DAV ロックデータベースの場所
DavLockDB file-path |  | sv | E
DAV ロックデータベースの位置
DavMinTimeout seconds | 0 | svd | E
サーバが DAV リソースのロックを維持する最小時間です。
DBDExptime time-in-seconds | 300 | sv | E
Keepalive time for idle connections
DBDKeep number | 2 | sv | E
Maximum sustained number of connections
DBDMax number | 10 | sv | E
Maximum number of connections
DBDMin number | 1 | sv | E
Minimum number of connections
DBDParams param1=value1[,param2=value2] |  | sv | E
Parameters for database connection
DBDPersist On|Off |  | sv | E
Whether to use persistent connections
DBDPrepareSQL "SQL statement" label |  | sv | E
Define an SQL prepared statement
DBDriver name |  | sv | E
Specify an SQL driver
DefaultIcon url-path |  | svdh | B
特定のアイコンが何も設定されていない時に ファイルに表示するアイコン
DefaultLanguage MIME-lang |  | svdh | B
あるスコープのすべてのファイルを指定された言語に 設定する
DefaultType MIME-type|none | text/plain | svdh | C
サーバがコンテントタイプを決定できないときに 送られる MIME コンテントタイプ
DeflateBufferSize value | 8096 | sv | E
zlib が一度に圧縮する塊の大きさ
DeflateCompressionLevel value |  | sv | E
出力に対して行なう圧縮の程度
DeflateFilterNote [type] notename |  | sv | E
ロギング用に圧縮比をメモに追加
DeflateInflateLimitRequestBodyvalue |  | svdh | E
Maximum size of inflated request bodies
DeflateInflateRatioBurst value |  | svdh | E
Maximum number of times the inflation ratio for request bodies can be crossed
DeflateInflateRatioLimit value |  | svdh | E
Maximum inflation ratio for request bodies
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
ウェブから見えるメインのドキュメントツリーになる ディレクトリ
DumpIOInput On|Off | Off | s | E
エラーログにすべての入力データをダンプ
DumpIOLogLevel level | debug | s | E
Controls the logging level of the DumpIO output
DumpIOOutput On|Off | Off | s | E
エラーログにすべての出力データをダンプ
EnableExceptionHook On|Off | Off | s | M
クラッシュの後に例外ハンドラを実行するフックを有効にする
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
外部フィルタを定義
ExtFilterOptions option [option] ... | DebugLevel=0 NoLogS + | d | E
mod_ext_filter のオプションを設定
FallbackResource disabled | local-url |  | svdh | B
Define a default URL for requests that don't map to a file
FileETag component ... | INode MTime Size | svdh | C
ETag HTTP 応答ヘッダを作成するために使用される ファイルの属性
<Files filename> ... </Files> |  | svdh | C
マッチするファイル名に適用されるディレクティブを囲む
<FilesMatch regex> ... </FilesMatch> |  | svdh | C
正規表現にマッチするファイル名に適用される ディレクティブを囲む
FilterChain [+=-@!]filter-name ... |  | svdh | B
Configure the filter chain
FilterDeclare filter-name [type] |  | svdh | B
Declare a smart filter
FilterProtocol filter-name [provider-name] proto-flags |  | svdh | B
Deal with correct HTTP protocol handling
FilterProvider filter-name provider-name [req|resp|env]=dispatch match |  | svdh | B
Register a content filter
FilterTrace filter-name level |  | svd | B
Get debug/diagnostic information from mod_filter
ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback] | Prefer | svdh | B
要求に合う単独のドキュメントが見つからなかったときに行なうことを指定
ForceType MIME-type|None |  | dh | C
すべてのマッチするファイルが指定の MIME コンテントタイプで 送られるようにする
ForensicLog filename|pipe |  | sv | E
Forensic ログのファイル名を設定する
GprofDir /tmp/gprof/|/tmp/gprof/% |  | sv | C
Directory to write gmon.out profiling data to.
GracefulShutDownTimeout seconds |  | s | M
穏やかな停止をかけた後、終了するまで待つ時間
Group unix-group | #-1 | s | M
リクエストに応答する際に所属するグループ
Header [condition] set|append|add|unset|echo header [value] [early|env=[!]variable] |  | svdh | E
HTTP 応答ヘッダの設定
HeaderName filename |  | svdh | B
インデックス一覧の先頭に挿入されるファイルの名前
HostnameLookups On|Off|Double | Off | svd | C
クライアントの IP アドレスの DNS ルックアップを 有効にする
HttpProtocolOptions [Strict|Unsafe] [RegisteredMethods|LenientMethods] [Allow0.9|Require1.0] | Strict LenientMetho + | sv | C
Modify restrictions on HTTP Request Messages
IdentityCheck On|Off | Off | svd | E
リモートユーザの RFC 1413 によるアイデンティティのロギングを 有効にする
IdentityCheckTimeout seconds | 30 | svd | E
Ident リクエストがタイムアウトするまでの期間を決める
<IfDefine [!]parameter-name> ... </IfDefine> |  | svdh | C
起動時にテストが真であるときのみに処理されるディレクティブを 囲む
<IfModule [!]module-file|module-identifier> ... </IfModule> |  | svdh | C
モジュールの存在するかしないかに応じて処理される ディレクティブを囲む
<IfVersion [[!]operator] version> ... </IfVersion> |  | svdh | E
バージョン依存の設定を入れる
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
サーバ設定ファイル中から他の設定ファイルを取り込む
IndexHeadInsert "markup ..." |  | svdh | B
Inserts text in the HEAD section of an index page.
IndexIgnore file [file] ... |  | svdh | B
ディレクトリ一覧を行なう際に無視すべき ファイルリストに追加
IndexOptions [+|-]option [[+|-]option] ... |  | svdh | B
ディレクトリインデックスの様々な設定項目
IndexOrderDefault Ascending|Descending Name|Date|Size|Description | Ascending Name | svdh | B
ディレクトリインデックスの標準の順番付けを設定
IndexStyleSheet url-path |  | svdh | B
ディレクトリインデックスに CSS スタイルシートを追加する
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 | 5 | sv | C
持続的な接続で次のリクエストが来るまでサーバが待つ時間
LanguagePriority MIME-lang [MIME-lang] ... |  | svdh | B
クライアントが優先度を示さなかったときの言語の variant の優先度を 指定
LDAPCacheEntries number | 1024 | s | E
Maximum number of entries in the primary LDAP cache
LDAPCacheTTL seconds | 600 | s | E
Time that cached items remain valid
LDAPConnectionTimeout seconds |  | s | E
Specifies the socket connection timeout in seconds
LDAPOpCacheEntries number | 1024 | s | E
Number of entries used to cache LDAP compare operations
LDAPOpCacheTTL seconds | 600 | s | E
Time that entries in the operation cache remain valid
LDAPSharedCacheFile directory-path/filename |  | s | E
Sets the shared memory cache file
LDAPSharedCacheSize bytes | 500000 | s | E
Size in bytes of the shared-memory cache
LDAPTrustedClientCert type directory-path/filename/nickname [password] |  | svdh | E
Sets the file containing or nickname referring to a per connection client certificate. Not all LDAP toolkits support per connection client certificates.
LDAPTrustedGlobalCert type directory-path/filename [password] |  | s | E
Sets the file or database containing global trusted Certificate Authority or global client certificates
LDAPTrustedMode type |  | sv | E
Specifies the SSL/TLS mode to be used when connecting to an LDAP server.
LDAPVerifyServerCert On|Off | On | s | E
Force server certificate verification
<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 | 8190 | s | C
クライアントからの HTTP リクエストのヘッダの サイズを制限する
LimitRequestLine bytes | 8190 | s | C
クライアントからの HTTP リクエスト行のサイズを制限する
LimitXMLRequestBody bytes | 1000000 | svdh | C
XML 形式のリクエストのボディのサイズを制限する
Listen [IP-address:]portnumber [protocol] |  | 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 KBytes | 0 | s | M
free() が呼ばれない限り、 主メモリアロケータが保持し続けられるメモリの最大量
MaxRanges default | unlimited | none | number-of-ranges | 200 | svd | C
Number of ranges allowed before returning the complete resource
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
MCacheMaxObjectCount value | 1009 | s | E
キャッシュに保管されるオブジェクトの最大数
MCacheMaxObjectSize bytes | 10000 | s | E
キャッシュに保管できるドキュメントの最大サイズ (バイト)
MCacheMaxStreamingBuffer size_in_bytes | of 100000 か MCacheM + | s | E
ストリームされている応答をキャッシュ不能と決定するまでに メモリにバッファする最大量
MCacheMinObjectSize bytes | 0 | s | E
キャッシュに保管されるドキュメントの最小サイズ (バイト)
MCacheRemovalAlgorithm LRU|GDSF | GDSF | s | E
キャッシュから削除するドキュメントを選ぶためのアルゴリズム
MCacheSize KBytes | 100 | s | E
キャッシュに使われるメモリの最大量をバイト単位で指定
MergeTrailers [on|off] | off | sv | C
Determines whether trailers are merged into headers
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
アイドルな子サーバプロセスの最小個数
MinSpareThreads 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 | B
path_info コンポーネントをファイル名の一部として扱うように mod_mime に通知する
MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers [Handlers|Filters] | NegotiatedOnly | svdh | B
MultiViews でのマッチングの検索に含ませる ファイルのタイプを指定する
NameVirtualHost addr[:port] |  | s | C
名前ベースのバーチャルホストのための IP アドレスを指定
NoProxy host [host] ... |  | sv | E
直接接続する ホスト、ドメイン、ネットワーク
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 をサーバが記録するためのファイル
Protocol protocol |  | sv | C
Protocol for a listening socket
ProtocolEcho On|Off | Off | sv | X
エコーサーバの有効無効を設定します。
<Proxy wildcard-url> ...</Proxy> |  | sv | E
プロキシされるリソースに適用されるコンテナ
ProxyBadHeader IsError|Ignore|StartBody | IsError | sv | E
応答におかしなヘッダがある場合の扱い方を決める
ProxyBlock *|word|host|domain [word|host|domain] ... |  | sv | E
プロキシ接続を禁止する語句、ホスト名、ドメインを指定する
ProxyDomain Domain |  | sv | E
プロキシされたリクエストのデフォルトのドメイン名
ProxyErrorOverride On|Off | Off | sv | E
プロキシされたコンテンツのエラーページを上書きする
ProxyFtpDirCharset character set | ISO-8859-1 | svd | E
プロキシされた FTP (の一覧表示) のキャラクタセットを定義
ProxyIOBufferSize bytes | 8192 | sv | E
内部データスループットバッファのサイズを決定する
<ProxyMatch regex> ...</ProxyMatch> |  | sv | E
正規表現でのマッチによるプロキシリソース用のディレクティブコンテナ
ProxyMaxForwards number | -1 | sv | E
リクエストがフォワードされるプロキシの最大数
ProxyPass [path] !|url [key=value key=value ...]] [nocanon] [interpolate] |  | svd | E
リモートサーバをローカルサーバの URL 空間にマップする
ProxyPassInterpolateEnv On|Off | Off | svd | E
リバースプロキシ設定内での環境変数の使用を有効にする
ProxyPassMatch [regex] !|url [key=value [key=value ...]] |  | svd | E
正規表現を使ってリモートサーバをローカルサーバの URL 空間にマップする
ProxyPassReverse [path] url [interpolate] |  | svd | E
リバースプロキシされたサーバから送られた HTTP レスポンスヘッダの URL を調整する
ProxyPassReverseCookieDomain internal-domain public-domain [interpolate] |  | svd | E
リバースプロキシサーバからの Set-Cookie ヘッダの Domain 文字列を 調整する
ProxyPassReverseCookiePath internal-path public-path [interpolate] |  | svd | E
リバースプロキシサーバからの Set-Cookie ヘッダの Path 文字列を 調整する
ProxyPreserveHost On|Off | Off | sv | E
プロキシリクエストに、受け付けた Host HTTP ヘッダを使う
ProxyReceiveBufferSize bytes | 0 | sv | E
プロキシされる HTTP と FTP 接続のためのネットワークバッファサイズ
ProxyRemote match remote-server |  | sv | E
特定のリクエストを扱う時に使われるリモートプロキシを指定する
ProxyRemoteMatch regex remote-server |  | sv | E
正規表現でのマッチによるリクエストを扱うリモートプロキシの指定
ProxyRequests On|Off | Off | sv | E
フォワード (標準の) プロキシリクエストを有効にする
ProxySCGIInternalRedirect On|Off | On | svd | E
バックエンドからの内部的なリダイレクトレスポンスを有効あるいは無効にする
ProxySCGISendfile On|Off|Headername | Off | svd | E
X-Sendfile 疑似レスポンスヘッダの評価を有効にする
ProxySet url key=value [key=value ...] |  | d | E
プロキシのバランサやメンバのパラメータをセット
ProxyStatus Off|On|Full | Off | sv | E
mod_status でプロキシのロードバランサの状態を表示
ProxyTimeout seconds |  | sv | E
プロキシされたリクエストのネットワークタイムアウト
ProxyVia On|Off|Full|Block | Off | sv | E
プロキシされたリクエストの Via HTTP レスポンスヘッダ により提供される情報
ReadmeName filename |  | svdh | B
インデックス一覧の最後に挿入されるファイルの名前
ReceiveBufferSize bytes | 0 | s | M
TCP 受信バッファサイズ
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 を取得するように外部への一時的な リダイレクトを送る
RegisterHttpMethod method [method [...]] |  | s | C
Register non-standard HTTP methods
RemoveCharset extension [extension] ... |  | vdh | B
ファイルの拡張子に関連付けられたすべての文字セット を解除する
RemoveEncoding extension [extension] ... |  | vdh | B
ファイルの拡張子に関連付けられたすべてのコンテントエンコーディング を解除する
RemoveHandler extension [extension] ... |  | vdh | B
ファイルの拡張子に関連付けられたすべてのハンドラを 解除する
RemoveInputFilter extension [extension] ... |  | vdh | B
ファイル拡張子に関連付けられた入力フィルタを解除する
RemoveLanguage extension [extension] ... |  | vdh | B
ファイル拡張子に関連付けられた言語を解除する
RemoveOutputFilter extension [extension] ... |  | vdh | B
ファイル拡張子に関連付けられた出力フィルタを解除する
RemoveType extension [extension] ... |  | vdh | B
ファイルの拡張子と関連付けられたコンテントタイプを 解除する
RequestHeader set|append|add|unset header [value] [early|env=[!]variable] |  | svdh | E
HTTP リクエストヘッダの設定
RequestReadTimeout [header=timeout[[-maxtimeout],MinRate=rate] [body=timeout[[-maxtimeout],MinRate=rate] |  | sv | E
Set timeout values for receiving request headers and body from client.
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|pipe |  | 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 |  | svdh | E
Sets some special options for the rewrite engine
RewriteRule Pattern Substitution [flags] |  | 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 | s | B
CGI デーモンとの通信に使われるソケットのファイル名の接頭辞
SecureListen [IP-address:]portnumber Certificate-Name [MUTUAL] |  | s | B
Enables SSL encryption for the specified port
SeeRequestTail On|Off | Off | s | B
リクエストの最初の 63 文字か最後の 63 文字 のどちらを mod_status が表示するかを決める
SendBufferSize bytes | 0 | s | M
TCP バッファサイズ
ServerAdmin email-address|URL |  | sv | C
サーバがクライアントに送るエラーメッセージに含める電子メールの アドレス
ServerAlias hostname [hostname] ... |  | v | C
リクエストを名前ベースのバーチャルホストにマッチさせているときに 使用されるホストの別名
ServerLimit number |  | s | M
設定可能なサーバプロセス数の上限
ServerName [scheme://]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
サーバの応答を処理するフィルタを設定する
SSIEnableAccess on|off | off | dh | B
Enable the -A flag during conditional flow control processing.
SSIEndTag tag | "-->" | sv | B
include 要素を終了させる文字列
SSIErrorMsg message | "[an error occurred + | svdh | B
SSI のエラーがあったときに表示されるエラーメッセージ
SSIETag on|off | off | dh | B
Controls whether ETags are generated by the server.
SSILastModified on|off | off | dh | B
Controls whether Last-Modified headers are generated by the server.
SSIStartTag tag | "<!--#" | sv | B
include 要素を開始する文字列
SSITimeFormat formatstring | "%A, %d-%b-%Y %H:%M + | svdh | B
日付けを表す文字列の書式を設定する
SSIUndefinedEcho string | "(none)" | svdh | 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
SSLCADNRequestFile file-path |  | sv | E
File of concatenated PEM-encoded CA Certificates for defining acceptable CA names
SSLCADNRequestPath directory-path |  | sv | E
Directory of PEM-encoded CA Certificates for defining acceptable CA names
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
SSLCompression on|off | off | sv | E
Enable compression on the SSL level
SSLCryptoDevice engine | builtin | s | E
Enable use of a cryptographic hardware accelerator
SSLEngine on|off|optional | off | sv | E
SSL Engine Operation Switch
SSLFIPS on|off | off | s | E
SSL FIPS mode Switch
SSLHonorCipherOrder flag |  | sv | E
Option to prefer the server's cipher preference order
SSLInsecureRenegotiation flag | off | sv | E
Option to enable support for insecure renegotiation
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
SSLProxyCheckPeerCN on|off | off | sv | E
Whether to check the remote server certificates CN field
SSLProxyCheckPeerExpire on|off | off | sv | E
Whether to check if remote server certificate is expired
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
SSLProxyMachineCertificateChainFile filename |  | s | E
File of concatenated PEM-encoded CA certificates to be used by the proxy for choosing a certificate
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 | sv | E
Type of remote server Certificate verification
SSLProxyVerifyDepth number | 1 | sv | E
Maximum depth of CA Certificates in Remote Server Certificate verification
SSLRandomSeed context source [bytes] |  | s | E
Pseudo Random Number Generator (PRNG) seeding source
SSLRenegBufferSize bytes | 131072 | dh | E
Set the size for the SSL renegotiation buffer
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
SSLSessionTicketKeyFile file-path |  | sv | E
Persistent encryption/decryption key for TLS session tickets
SSLSessionTickets on|off | on | sv | E
Enable or disable use of TLS session tickets
SSLStrictSNIVHostCheck on|off | off | sv | E
Whether to allow non SNI clients to access a name based virtual host.
SSLUserName varname |  | sdh | E
Variable name to determine user name
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 |  | s | M
起動時に生成される子サーバプロセスの数
StartThreads number |  | s | M
起動時に生成されるスレッドの数
Substitute s/pattern/substitution/[infq] |  | dh | E
Pattern to filter the response content
SubstituteInheritBefore on|off | off | dh | E
Change the merge order of inherited patterns
Suexec On|Off |  | s | C
Enable or disable the suEXEC feature
SuexecUserGroup User Group |  | sv | E
CGI プログラムのユーザパーミッション、グループパーミッション
ThreadLimit number |  | s | M
設定可能な子プロセス毎のスレッド数の上限を 設定します
ThreadsPerChild number |  | s | M
子プロセスそれぞれに生成されるスレッド数
ThreadStackSize size |  | s | M
クライアントのコネクションを受け持つスレッドが使用する スタックのバイト数
TimeOut seconds | 300 | sv | C
各イベントについて、リクエストを失敗させるまでにサーバが 待つ時間を設定
TraceEnable [on|off|extended] | on | s | C
TRACE メソッドのリクエストに対する応答方法を決める
TransferLog file|pipe |  | sv | B
ログファイルの位置を指定
TypesConfig file-path | conf/mime.types | s | B
mime.types ファイルの位置
UnsetEnv env-variable [env-variable] ... |  | svdh | B
環境から変数を取り除く
UseCanonicalName On|Off|Dns | Off | svd | C
サーバが自分自身の名前とポートを決定する方法を設定する
UseCanonicalPhysicalPort On|Off | Off | svd | C
サーバの名前とポートの解決方法を設定する
User unix-userid | #-1 | s | M
リクエストに応答する際に用いるユーザ ID
UserDir directory-filename |  | 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 ディレクティブを 解析する

Copyright 2017 The Apache Software Foundation.
この文書は Apache License, Version 2.0 のライセンスで提供されています。.


Site Map - Apache HTTP サーバ バージョン 2.2

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

Site Map

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。

このページは現時点で利用可能な Apache HTTP サーババージョン 2.2 のドキュメンテーション の一覧です。

リリースのメモ

  • 2.0 から 2.2 へのアップグレード
  • Apache 2.1/2.2 の新機能
  • 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 ファイル
  • ユーザ毎のウェブディレクトリ

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

  • 概略
  • Microsoft Windows での Apache の使用
  • Microsoft Windows での Apache のコンパイル
  • Novell NetWare で Apache を使う
  • HPUX で高性能ウェブサーバを実行する
  • EBCDIC 版 Apache

Apache HTTP サーバとサポートプログラム

  • 概略
  • マニュアルページ: httpd
  • マニュアルページ: ab
  • マニュアルページ: apachectl
  • マニュアルページ: apxs
  • マニュアルページ: configure
  • マニュアルページ: dbmmanage
  • マニュアルページ: htcacheclean
  • マニュアルページ: htdbm
  • マニュアルページ: htdigest
  • マニュアルページ: htpasswd
  • マニュアルページ: logresolve
  • マニュアルページ: rotatelogs
  • マニュアルページ: suexec
  • 他のプログラム

Apache その他

  • 概略
  • 関連する標準規格

Apache モジュール

  • Apache ディレクティブの説明に使われる用語
  • Apache ディレクティブを説明に使われる用語
  • Apache コア機能
  • Apache MPM 共通ディレクティブ
  • Apache MPM beos
  • Apache MPM event
  • Apache MPM netware
  • Apache MPM os2
  • Apache MPM prefork
  • Apache MPM winnt
  • Apache MPM worker
  • Apache モジュール mod_actions
  • Apache モジュール mod_alias
  • Apache モジュール mod_asis
  • Apache モジュール mod_auth_basic
  • Apache モジュール mod_auth_digest
  • Apache モジュール mod_authn_alias
  • Apache モジュール mod_authn_anon
  • Apache モジュール mod_authn_dbd
  • Apache モジュール mod_authn_dbm
  • Apache モジュール mod_authn_default
  • Apache モジュール mod_authn_file
  • Apache モジュール mod_authnz_ldap
  • Apache モジュール mod_authz_dbm
  • Apache モジュール mod_authz_default
  • Apache モジュール mod_authz_groupfile
  • Apache モジュール mod_authz_host
  • Apache モジュール mod_authz_owner
  • Apache モジュール mod_authz_user
  • 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_dav_lock
  • Apache モジュール mod_dbd
  • Apache モジュール mod_deflate
  • Apache モジュール mod_dir
  • Apache モジュール mod_disk_cache
  • Apache モジュール mod_dumpio
  • Apache モジュール mod_echo
  • Apache モジュール mod_env
  • Apache モジュール mod_example
  • Apache モジュール mod_expires
  • Apache モジュール mod_ext_filter
  • Apache モジュール mod_file_cache
  • Apache モジュール mod_filter
  • Apache モジュール mod_headers
  • Apache モジュール mod_ident
  • Apache モジュール mod_imagemap
  • 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_ajp
  • Apache モジュール mod_proxy_balancer
  • Apache モジュール mod_proxy_connect
  • Apache モジュール mod_proxy_ftp
  • Apache モジュール mod_proxy_http
  • Apache モジュール mod_proxy_scgi
  • Apache モジュール mod_reqtimeout
  • Apache モジュール mod_rewrite
  • Apache モジュール mod_setenvif
  • Apache モジュール mod_so
  • Apache モジュール mod_speling
  • Apache モジュール mod_ssl
  • Apache モジュール mod_status
  • Apache モジュール mod_substitute
  • Apache モジュール mod_suexec
  • Apache モジュール mod_unique_id
  • Apache モジュール mod_userdir
  • Apache モジュール mod_usertrack
  • Apache モジュール mod_version
  • 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 Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > 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.
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://dev.mysql.com/doc/mysql/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-family/pdflib/.
libpng | 1.0.x | ? |
libpng | 1.2.x | ? |
libpq (PostgreSQL) | 8.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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Access Control - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > How-To / Tutorials

Access Control

Access control refers to any means of controlling access to any resource. This is separate from authentication and authorization.

Related Modules and Directives

Access control can be done by several different modules. The most important of these is mod_authz_host. Other modules discussed in this document include mod_setenvif and mod_rewrite.

Access control by host

If you wish to restrict access to portions of your site based on the host address of your visitors, this is most easily done using mod_authz_host.

The Allow and Deny directives let you allow and deny access based on the host name, or host address, of the machine requesting a document. The Order directive goes hand-in-hand with these two, and tells Apache in which order to apply the filters.

The usage of these directives is:

Allow from address

where address is an IP address (or a partial IP address) or a fully qualified domain name (or a partial domain name); you may provide multiple addresses or domain names, if desired.

For example, if you have someone spamming your message board, and you want to keep them out, you could do the following:

Deny from 10.252.46.165

Visitors coming from that address will not be able to see the content covered by this directive. If, instead, you have a machine name, rather than an IP address, you can use that.

Deny from host.example.com

And, if you'd like to block access from an entire domain, you can specify just part of an address or domain name:

Deny from 192.168.205
Deny from phishers.example.com moreidiots.example
Deny from ke

Using Order will let you be sure that you are actually restricting things to the group that you want to let in, by combining a Deny and an Allow directive:

Order deny,allow
Deny from all
Allow from dev.example.com

Listing just the Allow directive would not do what you want, because it will let folks from that host in, in addition to letting everyone in. What you want is to let only those folks in.

Access control by environment variable

mod_authz_host, in conjunction with mod_setenvif, can be used to restrict access to your website based on the value of arbitrary environment variables. This is done with the Allow from env= and Deny from env= syntax.

SetEnvIf User-Agent BadBot GoAway=1
Order allow,deny
Allow from all
Deny from env=GoAway

Warning:

Access control by User-Agent is an unreliable technique, since the User-Agent header can be set to anything at all, at the whim of the end user.

In the above example, the environment variable GoAway is set to 1 if the User-Agent matches the string BadBot. Then we deny access for any request when this variable is set. This blocks that particular user agent from the site.

An environment variable test can be negated using the =! syntax:

Allow from env=!GoAway

Access control with mod_rewrite

The [F] RewriteRule flag causes a 403 Forbidden response to be sent. Using this, you can deny access to a resource based on arbitrary criteria.

For example, if you wish to block access to a resource between 8pm and 6am, you can do this using mod_rewrite.

RewriteEngine On
RewriteCond %{TIME_HOUR} >20 [OR]
RewriteCond %{TIME_HOUR} <07
RewriteRule ^/fridge - [F]

This will return a 403 Forbidden response for any request after 8pm or before 7am. This technique can be used for any criteria that you wish to check. You can also redirect, or otherwise rewrite these requests, if that approach is preferred.

More information

You should also read the documentation for mod_auth_basic and mod_authz_host which contain some more information about how this all works. mod_authn_alias can also help in simplifying certain authentication configurations.

See the Authentication and Authorization howto.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Password Formats - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Miscellaneous Documentation

Password Formats

Notes about the password encryption formats generated and understood by Apache.

Basic Authentication

There are four formats that Apache recognizes for basic-authentication passwords. Note that not all formats work on every platform:

PLAIN TEXT (i.e. unencrypted)
Windows, BEOS, & Netware only.
CRYPT
Unix only. Uses the traditional Unix crypt(3) function with a randomly-generated 32-bit salt (only 12 bits used) and the first 8 characters of the password.
SHA1
"{SHA}" + Base64-encoded SHA-1 digest of the password.
MD5
"$apr1$" + the result of an Apache-specific algorithm using an iterated (1,000 times) MD5 digest of various combinations of a random 32-bit salt and the password. See the APR source file apr_md5.c for the details of the algorithm.

Generating values with htpasswd

MD5

$ htpasswd -nbm myName myPassword
myName:$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/

SHA1

$ htpasswd -nbs myName myPassword
myName:{SHA}VBPuJHI7uixaa6LQGWx4s+5GKNE=

CRYPT

$ htpasswd -nbd myName myPassword
myName:rqXexS6ZhobKA

Generating CRYPT and MD5 values with the OpenSSL command-line program

OpenSSL knows the Apache-specific MD5 algorithm.

MD5

$ openssl passwd -apr1 myPassword
$apr1$qHDFfhPC$nITSVHgYbDAK1Y0acGRnY0

CRYPT

openssl passwd -crypt myPassword
qQ5vTYO3c8dsU

Validating CRYPT or MD5 passwords with the OpenSSL command line program

The salt for a CRYPT password is the first two characters (converted to a binary value). To validate myPassword against rqXexS6ZhobKA

CRYPT

$ openssl passwd -crypt -salt rq myPassword
Warning: truncating password to 8 characters
rqXexS6ZhobKA

Note that using myPasswo instead of myPassword will produce the same result because only the first 8 characters of CRYPT passwords are considered.

The salt for an MD5 password is between $apr1$ and the following $ (as a Base64-encoded binary value - max 8 chars). To validate myPassword against $apr1$r31.....$HqJZimcKQFAMYayBlzkrA/

MD5

$ openssl passwd -apr1 -salt r31..... myPassword
$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/

Database password fields for mod_dbd

The SHA1 variant is probably the most useful format for DBD authentication. Since the SHA1 and Base64 functions are commonly available, other software can populate a database with encrypted passwords that are usable by Apache basic authentication.

To create Apache SHA1-variant basic-authentication passwords in various languages:

PHP

'{SHA}' . base64_encode(sha1($password, TRUE))

Java

"{SHA}" + new sun.misc.BASE64Encoder().encode(java.security.MessageDigest.getInstance("SHA1").digest(password.getBytes()))

ColdFusion

"{SHA}" & ToBase64(BinaryDecode(Hash(password, "SHA1"), "Hex"))

Ruby

require 'digest/sha1'
require 'base64'
'{SHA}' + Base64.encode64(Digest::SHA1.digest(password))

C or C++

Use the APR function: apr_sha1_base64

PostgreSQL (with the contrib/pgcrypto functions installed)

'{SHA}'||encode(digest(password,'sha1'),'base64')

Digest Authentication

Apache recognizes one format for digest-authentication passwords - the MD5 hash of the string user:realm:password as a 32-character string of hexadecimal digits. realm is the Authorization Realm argument to the AuthName directive in httpd.conf.

Database password fields for mod_dbd

Since the MD5 function is commonly available, other software can populate a database with encrypted passwords that are usable by Apache digest authentication.

To create Apache digest-authentication passwords in various languages:

PHP

md5($user . ':' . $realm . ':' .$password)

Java

      byte b[] = java.security.MessageDigest.getInstance("MD5").digest( (user + ":" + realm + ":" + password ).getBytes());
java.math.BigInteger bi = new java.math.BigInteger(1, b);
String s = bi.toString(16);
while (s.length() < 32)
s = "0" + s;

      // String s is the encrypted password

ColdFusion

LCase(Hash( (user & ":" & realm & ":" & password) , "MD5"))

Ruby

require 'digest/md5'
Digest::MD5.hexdigest(user + ':' + realm + ':' + password)

PostgreSQL (with the contrib/pgcrypto functions installed)

encode(digest( user || ':' || realm || ':' || password , 'md5'), 'hex')

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


httxt2dbm - Generate dbm files for use with RewriteMap - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Programs

httxt2dbm - Generate dbm files for use with RewriteMap

httxt2dbm is used to generate dbm files from text input, for use in RewriteMap with the dbm map type.

See also

  • httpd
  • mod_rewrite

Synopsis

httxt2dbm [ -v ] [ -f DBM_TYPE ] -i SOURCE_TXT -o OUTPUT_DBM

Options

-v
More verbose output
-f DBM_TYPE
Specify the DBM type to be used for the output. If not specified, will use the APR Default. Available types are: GDBM for GDBM files, SDBM for SDBM files, DB for berkeley DB files, NDBM for NDBM files, default for the default DBM type.
-i SOURCE_TXT
Input file from which the dbm is to be created. The file should be formated with one record per line, of the form: key value. See the documentation for RewriteMap for further details of this file's format and meaning.
-o OUTPUT_DBM
Name of the output dbm files.

Examples

httxt2dbm -i rewritemap.txt -o rewritemap.dbm
httxt2dbm -f SDBM -i rewritemap.txt -o rewritemap.dbm

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Using mod_rewrite to control access - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Rewrite

Using mod_rewrite to control access

This document supplements the mod_rewrite reference documentation. It describes how you can use mod_rewrite to control access to various resources, and other related techniques. This includes many examples of common uses of mod_rewrite, including detailed descriptions of how each works.

Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • Advanced techniques and tricks
  • When not to use mod_rewrite

Forbidding Image "Hotlinking"

Description:

The following technique forbids the practice of other sites including your images inline in their pages. This practice is often referred to as "hotlinking", and results in your bandwidth being used to serve content for someone else's site.

Solution:

This technique relies on the value of the HTTP_REFERER variable, which is optional. As such, it's possible for some people to circumvent this limitation. However, most users will experience the failed request, which should, over time, result in the image being removed from that other site.

There are several ways that you can handle this situation.

In this first example, we simply deny the request, if it didn't initiate from a page on our site. For the purpose of this example, we assume that our site is www.example.com.

RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !www.example.com [NC]
RewriteRule \.(gif|jpg|png)$ - [F,NC]

In this second example, instead of failing the request, we display an alternate image instead.

RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !www.example.com [NC]
RewriteRule \.(gif|jpg|png)$ /images/go-away.png [R,NC]

In the third example, we redirect the request to an image on some other site.

RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !www.example.com [NC]
RewriteRule \.(gif|jpg|png)$ http://other.example.com/image.gif [R,NC]

Of these techniques, the last two tend to be the most effective in getting people to stop hotlinking your images, because they will simply not see the image that they expected to see.

Discussion:

If all you wish to do is deny access to the resource, rather than redirecting that request elsewhere, this can be accomplished without the use of mod_rewrite:

SetEnvIf Referer example\.com localreferer
<FilesMatch \.(jpg|png|gif)$>
Order deny,allow
Deny from all
Allow from env=localreferer
</FilesMatch>

Blocking of Robots

Description:

In this recipe, we discuss how to block persistent requests from a particular robot, or user agent.

The standard for robot exclusion defines a file, /robots.txt that specifies those portions of your website where you which to exclude robots. However, some robots do not honor these files.

Note that there are methods of accomplishing this which do not use mod_rewrite. Note also that any technique that relies on the clients USER_AGENT string can be circumvented very easily, since that string can be changed.

Solution:

We use a ruleset that specifies the directory to be protected, and the client USER_AGENT that identifies the malicious or persistent robot.

In this example, we are blocking a robot called NameOfBadRobot from a location /secret/files. You may also specify an IP address range, if you are trying to block that user agent only from the particular source.

RewriteCond %{HTTP_USER_AGENT} ^NameOfBadRobot
RewriteCond %{REMOTE_ADDR} =123\.45\.67\.[8-9]
RewriteRule ^/secret/files/ - [F]

Discussion:

Rather than using mod_rewrite for this, you can accomplish the same end using alternate means, as illustrated here:

SetEnvIfNoCase User-Agent ^NameOfBadRobot goaway
<Location /secret/files>
Order allow,deny
Allow from all
Deny from env=goaway
</Location>

As noted above, this technique is trivial to circumvent, by simply modifying the USER_AGENT request header. If you are experiencing a sustained attack, you should consider blocking it at a higher level, such as at your firewall.

Denying Hosts in a Blacklist

Description:

We wish to maintain a blacklist of hosts, rather like hosts.deny, and have those hosts blocked from accessing our server.

Solution:

RewriteEngine on
RewriteMap hosts-deny txt:/path/to/hosts.deny
RewriteCond ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND [OR]
RewriteCond ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND
RewriteRule ^ - [F]

##
## 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 -

Discussion:

The second RewriteCond assumes that you have HostNameLookups turned on, so that client IP addresses will be resolved. If that's not the case, you should drop the second RewriteCond, and drop the [OR] flag from the first RewriteCond.

Referer-based Deflector

Description:

Redirect requests based on the Referer from which the request came, with different targets per Referer.

Solution:

The following ruleset uses a map file to associate each Referer with a redirection target.

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]

The map file lists redirection targets for each referer, or, if we just wish to redirect back to where they came from, a "-" is placed in the map:

##
## deflector.map
##

http://badguys.example.com/bad/index.html -
http://badguys.example.com/bad/index2.html -
http://badguys.example.com/bad/index3.html http://somewhere.example.com/

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Advanced Techniques with mod_rewrite - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Rewrite

Advanced Techniques with mod_rewrite

This document supplements the mod_rewrite reference documentation. It provides a few advanced techniques and tricks using mod_rewrite.

Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • When not to use mod_rewrite

URL-based sharding accross multiple backends

Description:

A common technique for distributing the burden of server load or storage space is called "sharding". When using this method, a front-end server will use the url to consistently "shard" users or objects to separate backend servers.

Solution:

A mapping is maintained, from users to target servers, in external map files. They look like:

user1 physical_host_of_user1
user2 physical_host_of_user2
: :

We put this into a map.users-to-hosts file. The aim is to map;

/u/user1/anypath

to

http://physical_host_of_user1/u/user/anypath

thus every URL path need not be valid on every backend physical host. The following ruleset does this for us with 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 users-to-hosts txt:/path/to/map.users-to-hosts

RewriteRule ^/u/([^/]+)/?(.*) http://${users-to-hosts:$1|server0}/u/$1/$2

See the RewriteMap documentation for more discussion of the syntax of this directive.

On-the-fly Content-Regeneration

Description:

We wish to dynamically generate content, but store it statically once it is generated. This rule will check for the existence of the static file, and if it's not there, generate it. The static files can be removed periodically, if desired (say, via cron) and will be regenerated on demand.

Solution:
This is done via the following ruleset:
# This example is valid in per-directory context only
RewriteCond %{REQUEST_URI}   !-U
RewriteRule ^(.+)\.html$          /regenerate_page.cgi   [PT,L]

The -U operator determines whether the test string (in this case, REQUEST_URI) is a valid URL. It does this via a subrequest. In the event that this subrequest fails - that is, the requested resource doesn't exist - this rule invokes the CGI program /regenerate_page.cgi, which generates the requested resource and saves it into the document directory, so that the next time it is requested, a static copy can be served.

In this way, documents that are infrequently updated can be served in static form. if documents need to be refreshed, they can be deleted from the document directory, and they will then be regenerated the next time they are requested.

Load Balancing

Description:

We wish to randomly distribute load across several servers using mod_rewrite.

Solution:

We'll use RewriteMap and a list of servers to accomplish this.

RewriteEngine on
RewriteMap lb rnd:/path/to/serverlist.txt

RewriteRule ^/(.*) http://${lb:servers}/$1 [P,L]

serverlist.txt will contain a list of the servers:

## serverlist.txt

servers one.example.com|two.example.com|three.example.com

If you want one particular server to get more of the load than the others, add it more times to the list.

Discussion

Apache comes with a load-balancing module - mod_proxy_balancer - which is far more flexible and featureful than anything you can cobble together using mod_rewrite.

Document With Autorefresh

Description:

Wouldn't it be nice, while creating a complex web page, if the web browser would automatically refresh the page every time we save a new version from within our editor? Impossible?

Solution:

No! We just combine the MIME multipart feature, the web server NPH feature, and the URL manipulation power of mod_rewrite. First, we establish a new URL feature: Adding just :refresh to any URL causes the 'page' to be refreshed every time it is 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##

Structured Userdirs

Description:

Some sites with thousands of users 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, /~larry/anypath is /home/l/larry/public_html/anypath while /~waldo/anypath is /home/w/waldo/public_html/anypath.

Solution:

We use the following ruleset to expand the tilde URLs into the above layout.

RewriteEngine on
RewriteRule ^/~(([a-z])[a-z0-9]+)(.*) /home/$2/$1/public_html$3

Redirecting Anchors

Description:

By default, redirecting to an HTML anchor doesn't work, because mod_rewrite escapes the # character, turning it into %23. This, in turn, breaks the redirection.

Solution:

Use the [NE] flag on the RewriteRule. NE stands for No Escape.

Discussion:
This technique will of course also work with other special characters that mod_rewrite, by default, URL-encodes.

Time-Dependent Rewriting

Description:

We wish to use mod_rewrite to serve different content based on the time of day.

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 [L]
RewriteRule ^foo\.html$ foo.night.html

This provides the content of foo.day.html under the URL foo.html from 07:01-18:59 and at the remaining time the contents of foo.night.html.

mod_cache, intermediate proxies and browsers may each cache responses and cause the either page to be shown outside of the time-window configured. mod_expires may be used to control this effect. You are, of course, much better off simply serving the content dynamically, and customizing it based on the time of day.

Set Environment Variables Based On URL Parts

Description:

At time, we want to maintain some kind of status when we perform a rewrite. For example, you want to make a note that you've done that rewrite, so that you can check later to see if a request can via that rewrite. One way to do this is by setting an environment variable.

Solution:

Use the [E] flag to set an environment variable.

RewriteEngine on
RewriteRule ^/horse/(.*) /pony/$1 [E=rewritten:1]

Later in your ruleset you might check for this environment variable using a RewriteCond:

RewriteCond %{ENV:rewritten} =1

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


When not to use mod_rewrite - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Rewrite

When not to use mod_rewrite

This document supplements the mod_rewrite reference documentation. It describes perhaps one of the most important concepts about mod_rewrite - namely, when to avoid using it.

mod_rewrite should be considered a last resort, when other alternatives are found wanting. Using it when there are simpler alternatives leads to configurations which are confusing, fragile, and hard to maintain. Understanding what other alternatives are available is a very important step towards mod_rewrite mastery.

Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration.

The most common situation in which mod_rewrite is the right tool is when the very best solution requires access to the server configuration files, and you don't have that access. Some configuration directives are only available in the server configuration file. So if you are in a hosting situation where you only have .htaccess files to work with, you may need to resort to mod_rewrite.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • Advanced techniques and tricks

Simple Redirection

mod_alias provides the Redirect and RedirectMatch directives, which provide a means to redirect one URL to another. This kind of simple redirection of one URL, or a class of URLs, to somewhere else, should be accomplished using these directives rather than RewriteRule. RedirectMatch allows you to include a regular expression in your redirection criteria, providing many of the benefits of using RewriteRule.

A common use for RewriteRule is to redirect an entire class of URLs. For example, all URLs in the /one directory must be redirected to http://one.example.com/, or perhaps all http requests must be redirected to https.

These situations are better handled by the Redirect directive. Remember that Redirect preserves path information. That is to say, a redirect for a URL /one will also redirect all URLs under that, such as /one/two.html and /one/three/four.html.

To redirect URLs under /one to http://one.example.com, do the following:

Redirect /one/ http://one.example.com/

To redirect http URLs to https, do the following:

<VirtualHost *:80> ServerName www.example.com
Redirect / https://www.example.com/
</VirtualHost >
<VirtualHost *:443> ServerName www.example.com

# ... SSL configuration goes here
</VirtualHost >

The use of RewriteRule to perform this task may be appropriate if there are other RewriteRule directives in the same scope. This is because, when there are Redirect and RewriteRule directives in the same scope, the RewriteRule directives will run first, regardless of the order of appearance in the configuration file.

In the case of the http-to-https redirection, the use of RewriteRule would be appropriate if you don't have access to the main server configuration file, and are obliged to perform this task in a .htaccess file instead.

URL Aliasing

The Alias directive provides mapping from a URI to a directory - usually a directory outside of your DocumentRoot. Although it is possible to perform this mapping with mod_rewrite, Alias is the preferred method, for reasons of simplicity and performance.

Using Alias

Alias /cats /var/www/virtualhosts/felines/htdocs

The use of mod_rewrite to perform this mapping may be appropriate when you do not have access to the server configuration files. Alias may only be used in server or virtualhost context, and not in a .htaccess file.

Symbolic links would be another way to accomplish the same thing, if you have Options FollowSymLinks enabled on your server.

Virtual Hosting

Although it is possible to handle virtual hosts with mod_rewrite, it is seldom the right way. Creating individual <VirtualHost> blocks is almost always the right way to go. In the event that you have an enormous number of virtual hosts, consider using mod_vhost_alias to create these hosts automatically.

Third-party modules such as mod_macro are also useful for creating a large number of virtual hosts dynamically.

Using mod_rewrite for vitualhost creation may be appropriate if you are using a hosting service that does not provide you access to the server configuration files, and you are therefore restricted to configuration using .htaccess files.

See the virtual hosts with mod_rewrite document for more details on how you might accomplish this if it still seems like the right approach.

Simple Proxying

RewriteRule provides the [P] flag to pass rewritten URIs through mod_proxy.

RewriteRule ^/?images(.*) http://imageserver.local/images$1 [P]

However, in many cases, when there is no actual pattern matching needed, as in the example shown above, the ProxyPass directive is a better choice. The example here could be rendered as:

ProxyPass /images/ http://imageserver.local/images/

Note that whether you use RewriteRule or ProxyPass, you'll still need to use the ProxyPassReverse directive to catch redirects issued from the back-end server:

ProxyPassReverse /images/ http://imageserver.local/images/

You may need to use RewriteRule instead when there are other RewriteRules in effect in the same scope, as a RewriteRule will usually take effect before a ProxyPass, and so may preempt what you're trying to accomplish.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


RewriteRule Flags - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Rewrite

RewriteRule Flags

This document discusses the flags which are available to the RewriteRule directive, providing detailed explanations and examples.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • Advanced techniques
  • When not to use mod_rewrite

Introduction

A RewriteRule can have its behavior modified by one or more flags. Flags are included in square brackets at the end of the rule, and multiple flags are separated by commas.

RewriteRule pattern target [Flag1,Flag2,Flag3]

Each flag (with a few exceptions) has a short form, such as CO, as well as a longer form, such as cookie. While it is most common to use the short form, it is recommended that you familiarize yourself with the long form, so that you remember what each flag is supposed to do. Some flags take one or more arguments. Flags are not case sensitive.

Flags that alter metadata associated with the request (T=, H=, E=) have no affect in per-directory and htaccess context, when a substitution (other than '-') is performed during the same round of rewrite processing.

Presented here are each of the available flags, along with an example of how you might use them.

B (escape backreferences)

The [B] flag instructs RewriteRule to escape non-alphanumeric characters before applying the transformation.

mod_rewrite has to unescape URLs before mapping them, so backreferences will be unescaped at the time they are applied. Using the B flag, non-alphanumeric characters in backreferences will be escaped. For example, consider the rule:

RewriteRule ^search/(.*)$ /search.php?term=$1

Given a search term of 'x & y/z', a browser will encode it as 'x%20%26%20y%2Fz', making the request 'search/x%20%26%20y%2Fz'. Without the B flag, this rewrite rule will map to 'search.php?term=x & y/z', which isn't a valid URL, and so would be encoded as search.php?term=x%20&y%2Fz=, which is not what was intended.

With the B flag set on this same rule, the parameters are re-encoded before being passed on to the output URL, resulting in a correct mapping to /search.php?term=x%20%26%20y%2Fz.

Note that you may also need to set AllowEncodedSlashes to On to get this particular example to work, as httpd does not allow encoded slashes in URLs, and returns a 404 if it sees one.

This escaping is particularly necessary in a proxy situation, when the backend may break if presented with an unescaped URL.

C|chain

The [C] or [chain] flag indicates that the RewriteRule is chained to the next rule. That is, if the rule matches, then it is processed as usual and control moves on to the next rule. However, if it does not match, then the next rule, and any other rules that are chained together, will be skipped.

CO|cookie

The [CO], or [cookie] flag, allows you to set a cookie when a particular RewriteRule matches. The argument consists of three required fields and four optional fields.

The full syntax for the flag, including all attributes, is as follows:

[CO=NAME:VALUE:DOMAIN:lifetime:path:secure:httponly]

You must declare a name, a value, and a domain for the cookie to be set.

Domain
The domain for which you want the cookie to be valid. This may be a hostname, such as www.example.com, or it may be a domain, such as .example.com. It must be at least two parts separated by a dot. That is, it may not be merely .com or .net. Cookies of that kind are forbidden by the cookie security model.

You may optionally also set the following values:

Lifetime
The time for which the cookie will persist, in minutes.
A value of 0 indicates that the cookie will persist only for the current browser session. This is the default value if none is specified. Prior to 2.2.28, a value of 0 indicates immediate expiration and it was not possible to specify session lifetime if any later parameters (Path, Secure, httponly) were specified
Path
The path, on the current website, for which the cookie is valid, such as /customers/ or /files/download/.
By default, this is set to / - that is, the entire website.
Secure
If set to secure, true, or 1, the cookie will only be permitted to be translated via secure (https) connections.
httponly
If set to HttpOnly, true, or 1, the cookie will have the HttpOnly flag set, which means that the cookie will be inaccessible to JavaScript code on browsers that support this feature.

Several examples are offered here:

RewriteEngine On
RewriteRule ^/index\.html - [CO=frontdoor:yes:.example.com:1440:/]

In the example give, the rule doesn't rewrite the request. The "-" rewrite target tells mod_rewrite to pass the request through unchanged. Instead, it sets a cookie called 'frontdoor' to a value of 'yes'. The cookie is valid for any host in the .example.com domain. It will be set to expire in 1440 minutes (24 hours) and will be returned for all URIs.

DPI|discardpathinfo

The DPI flag causes the PATH_INFO portion of the rewritten URI to be discarded.

This flag is available in version 2.2.12 and later.

In per-directory context, the URI each RewriteRule compares against is the concatenation of the current values of the URI and PATH_INFO.

The current URI can be the initial URI as requested by the client, the result of a previous round of mod_rewrite processing, or the result of a prior rule in the current round of mod_rewrite processing.

In contrast, the PATH_INFO that is appended to the URI before each rule reflects only the value of PATH_INFO before this round of mod_rewrite processing. As a consequence, if large portions of the URI are matched and copied into a substitution in multiple RewriteRule directives, without regard for which parts of the URI came from the current PATH_INFO, the final URI may have multiple copies of PATH_INFO appended to it.

Use this flag on any substitution where the PATH_INFO that resulted from the previous mapping of this request to the filesystem is not of interest. This flag permanently forgets the PATH_INFO established before this round of mod_rewrite processing began. PATH_INFO will not be recalculated until the current round of mod_rewrite processing completes. Subsequent rules during this round of processing will see only the direct result of substitutions, without any PATH_INFO appended.

E|env

With the [E], or [env] flag, you can set the value of an environment variable. Note that some environment variables may be set after the rule is run, thus unsetting what you have set. See the Environment Variables document for more details on how Environment variables work.

The full syntax for this flag is:

[E=VAR:VAL] [E=!VAR]

VAL may contain backreferences ($N or %N) which will be expanded.

Using the short form

[E=VAR]

you can set the environment variable named VAR to an empty value.

The form

[E=!VAR]

allows to unset a previously set environment variable named VAR.

Environment variables can then be used in a variety of contexts, including CGI programs, other RewriteRule directives, or CustomLog directives.

The following example sets an environment variable called 'image' to a value of '1' if the requested URI is an image file. Then, that environment variable is used to exclude those requests from the access log.

RewriteRule \.(png|gif|jpg) - [E=image:1]
CustomLog logs/access_log combined env=!image

Note that this same effect can be obtained using SetEnvIf. This technique is offered as an example, not as a recommendation.

F|forbidden

Using the [F] flag causes the server to return a 403 Forbidden status code to the client. While the same behavior can be accomplished using the Deny directive, this allows more flexibility in assigning a Forbidden status.

The following rule will forbid .exe files from being downloaded from your server.

RewriteRule \.exe - [F]

This example uses the "-" syntax for the rewrite target, which means that the requested URI is not modified. There's no reason to rewrite to another URI, if you're going to forbid the request.

When using [F], an [L] is implied - that is, the response is returned immediately, and no further rules are evaluated.

G|gone

The [G] flag forces the server to return a 410 Gone status with the response. This indicates that a resource used to be available, but is no longer available.

As with the [F] flag, you will typically use the "-" syntax for the rewrite target when using the [G] flag:

RewriteRule oldproduct - [G,NC]

When using [G], an [L] is implied - that is, the response is returned immediately, and no further rules are evaluated.

H|handler

Forces the resulting request to be handled with the specified handler. For example, one might use this to force all files without a file extension to be parsed by the php handler:

RewriteRule !\. - [H=application/x-httpd-php]

The regular expression above - !\. - will match any request that does not contain the literal . character.

This can be also used to force the handler based on some conditions. For example, the following snippet used in per-server context allows .php files to be displayed by mod_php if they are requested with the .phps extension:

RewriteRule ^(/source/.+\.php)s$ $1 [H=application/x-httpd-php-source]

The regular expression above - ^(/source/.+\.php)s$ - will match any request that starts with /source/ followed by 1 or n characters followed by .phps literally. The backreference $1 referrers to the captured match within parenthesis of the regular expression.

L|last

The [L] flag causes mod_rewrite to stop processing the rule set. In most contexts, this means that if the rule matches, no further rules will be processed. This corresponds to the last command in Perl, or the break command in C. Use this flag to indicate that the current rule should be applied immediately without considering further rules.

If you are using RewriteRule in either .htaccess files or in <Directory> sections, it is important to have some understanding of how the rules are processed. The simplified form of this is that once the rules have been processed, the rewritten request is handed back to the URL parsing engine to do what it may with it. It is possible that as the rewritten request is handled, the .htaccess file or <Directory> section may be encountered again, and thus the ruleset may be run again from the start. Most commonly this will happen if one of the rules causes a redirect - either internal or external - causing the request process to start over.

It is therefore important, if you are using RewriteRule directives in one of these contexts, that you take explicit steps to avoid rules looping, and not count solely on the [L] flag to terminate execution of a series of rules, as shown below.

The example given here will rewrite any request to index.php, giving the original request as a query string argument to index.php, however, the RewriteCond ensures that if the request is already for index.php, the RewriteRule will be skipped.

RewriteBase /
RewriteCond %{REQUEST_URI} !=/index.php
RewriteRule ^(.*) /index.php?req=$1 [L,PT]

N|next

The [N] flag causes the ruleset to start over again from the top, using the result of the ruleset so far as a starting point. Use with extreme caution, as it may result in loop.

The [Next] flag could be used, for example, if you wished to replace a certain string or letter repeatedly in a request. The example shown here will replace A with B everywhere in a request, and will continue doing so until there are no more As to be replaced.

RewriteRule (.*)A(.*) $1B$2 [N]

You can think of this as a while loop: While this pattern still matches (i.e., while the URI still contains an A), perform this substitution (i.e., replace the A with a B).

NC|nocase

Use of the [NC] flag causes the RewriteRule to be matched in a case-insensitive manner. That is, it doesn't care whether letters appear as upper-case or lower-case in the matched URI.

In the example below, any request for an image file will be proxied to your dedicated image server. The match is case-insensitive, so that .jpg and .JPG files are both acceptable, for example.

RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC]

NE|noescape

By default, special characters, such as & and ?, for example, will be converted to their hexcode equivalent. Using the [NE] flag prevents that from happening.

RewriteRule ^/anchor/(.+) /bigpage.html#$1 [NE,R]

The above example will redirect /anchor/xyz to /bigpage.html#xyz. Omitting the [NE] will result in the # being converted to its hexcode equivalent, %23, which will then result in a 404 Not Found error condition.

NS|nosubreq

Use of the [NS] flag prevents the rule from being used on subrequests. For example, a page which is included using an SSI (Server Side Include) is a subrequest, and you may want to avoid rewrites happening on those subrequests. Also, when mod_dir tries to find out information about possible directory default files (such as index.html files), this is an internal subrequest, and you often want to avoid rewrites on such subrequests. On subrequests, it is not always useful, and can even cause errors, if the complete set of rules are applied. Use this flag to exclude problematic rules.

To decide whether or not to use this rule: if you prefix URLs with CGI-scripts, to force them to be processed by the CGI-script, it's likely that you will run into problems (or significant overhead) on sub-requests. In these cases, use this flag.

Images, javascript files, or css files, loaded as part of an HTML page, are not subrequests - the browser requests them as separate HTTP requests.

P|proxy

Use of the [P] flag causes the request to be handled by mod_proxy, and handled via a proxy request. For example, if you wanted all image requests to be handled by a back-end image server, you might do something like the following:

RewriteRule /(.*)\.(jpg|gif|png) http://images.example.com/$1.$2 [P]

Use of the [P] flag implies [L] - that is, the request is immediately pushed through the proxy, and any following rules will not be considered.

You must make sure that the substitution string is a valid URI (typically starting with http://hostname) which can be handled by the mod_proxy. If not, you will get an error from the proxy module. Use this flag to achieve a more powerful implementation of the ProxyPass directive, to map remote content into the namespace of the local server.

Security Warning

Take care when constructing the target URL of the rule, considering the security impact from allowing the client influence over the set of URLs to which your server will act as a proxy. Ensure that the scheme and hostname part of the URL is either fixed, or does not allow the client undue influence.

Note: mod_proxy must be enabled in order to use this flag.

PT|passthrough

The target (or substitution string) in a RewriteRule is assumed to be a file path, by default. The use of the [PT] flag causes it to be treated as a URI instead. That is to say, the use of the [PT] flag causes the result of the RewriteRule to be passed back through URL mapping, so that location-based mappings, such as Alias, Redirect, or ScriptAlias, for example, might have a chance to take effect.

If, for example, you have an Alias for /icons, and have a RewriteRule pointing there, you should use the [PT] flag to ensure that the Alias is evaluated.

Alias /icons /usr/local/apache/icons
RewriteRule /pics/(.+)\.jpg /icons/$1.gif [PT]

Omission of the [PT] flag in this case will cause the Alias to be ignored, resulting in a 'File not found' error being returned.

The PT flag implies the L flag: rewriting will be stopped in order to pass the request to the next phase of processing.

Note that the PT flag is implied in per-directory contexts such as <Directory> sections or in .htaccess files. The only way to circumvent that is to rewrite to -.

QSA|qsappend

When the replacement URI contains a query string, the default behavior of RewriteRule is to discard the existing query string, and replace it with the newly generated one. Using the [QSA] flag causes the query strings to be combined.

Consider the following rule:

RewriteRule /pages/(.+) /page.php?page=$1 [QSA]

With the [QSA] flag, a request for /pages/123?one=two will be mapped to /page.php?page=123&one=two. Without the [QSA] flag, that same request will be mapped to /page.php?page=123 - that is, the existing query string will be discarded.

R|redirect

Use of the [R] flag causes a HTTP redirect to be issued to the browser. If a fully-qualified URL is specified (that is, including http://servername/) then a redirect will be issued to that location. Otherwise, the current protocol, servername, and port number will be used to generate the URL sent with the redirect.

Any valid HTTP response status code may be specified, using the syntax [R=305], with a 302 status code being used by default if none is specified. The status code specified need not necessarily be a redirect (3xx) status code. However, if a status code is outside the redirect range (300-399) then the substitution string is dropped entirely, and rewriting is stopped as if the L were used.

In addition to response status codes, you may also specify redirect status using their symbolic names: temp (default), permanent, or seeother.

You will almost always want to use [R] in conjunction with [L] (that is, use [R,L]) because on its own, the [R] flag prepends http://thishost[:thisport] to the URI, but then passes this on to the next rule in the ruleset, which can often result in 'Invalid URI in request' warnings.

S|skip

The [S] flag is used to skip rules that you don't want to run. The syntax of the skip flag is [S=N], where N signifies the number of rules to skip (provided the RewriteRule matches). This can be thought of as a goto statement in your rewrite ruleset. In the following example, we only want to run the RewriteRule if the requested URI doesn't correspond with an actual file.

# Is the request for a non-existent file?
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
# If so, skip these two RewriteRules
RewriteRule .? - [S=2]
RewriteRule (.*\.gif) images.php?$1
RewriteRule (.*\.html) docs.php?$1

This technique is useful because a RewriteCond only applies to the RewriteRule immediately following it. Thus, if you want to make a RewriteCond apply to several RewriteRules, one possible technique is to negate those conditions and add a RewriteRule with a [Skip] flag. You can 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:

# Does the file exist?
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
# Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza.
RewriteRule .? - [S=3]

# IF the file exists, then: RewriteRule (.*\.gif) images.php?$1
RewriteRule (.*\.html) docs.php?$1
# Skip past the "else" stanza.
RewriteRule .? - [S=1]
 # ELSE... RewriteRule (.*) 404.php?file=$1
 # END

T|type

Sets the MIME type with which the resulting response will be sent. This has the same effect as the AddType directive.

For example, you might use the following technique to serve Perl source code as plain text, if requested in a particular way:

# Serve .pl files as plain text
RewriteRule \.pl$ - [T=text/plain]

Or, perhaps, if you have a camera that produces jpeg images without file extensions, you could force those images to be served with the correct MIME type by virtue of their file names:

# Files with 'IMG' in the name are jpg images.
RewriteRule IMG - [T=image/jpg]

Please note that this is a trivial example, and could be better done using <FilesMatch> instead. Always consider the alternate solutions to a problem before resorting to rewrite, which will invariably be a less efficient solution than the alternatives.

If used in per-directory context, use only - (dash) as the substitution for the entire round of mod_rewrite processing, otherwise the MIME-type set with this flag is lost due to an internal re-processing (including subsequent rounds of mod_rewrite processing). The L flag can be useful in this context to end the current round of mod_rewrite processing.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Apache mod_rewrite - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2

Apache mod_rewrite

mod_rewrite provides a way to modify incoming URL requests, dynamically, based on regular expression rules. This allows you to map arbitrary URLs onto your internal URL structure in any way you like.

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: server variables, environment variables, HTTP headers, time stamps, external database lookups, and various other external programs or handlers, can be used to achieve granular URL matching.

Rewrite rules can operate on the full URLs, including the path-info and query string portions, and may be used in per-server context (httpd.conf), per-virtualhost context (<VirtualHost> blocks), or per-directory context (.htaccess files and <Directory> blocks). The rewritten result can lead to further rules, internal sub-processing, external request redirection, or proxy passthrough, depending on what flags you attach to the rules.

Since mod_rewrite is so powerful, it can indeed be rather complex. This document supplements the reference documentation, and attempts to allay some of that complexity, and provide highly annotated examples of common scenarios that you may handle with mod_rewrite. But we also attempt to show you when you should not use mod_rewrite, and use other standard Apache features instead, thus avoiding this unnecessary complexity.

  • mod_rewrite reference documentation
  • Introduction to regular expressions and mod_rewrite
  • Using mod_rewrite for redirection and remapping of URLs
  • Using mod_rewrite to control access
  • Dynamic virtual hosts with mod_rewrite
  • Dynamic proxying with mod_rewrite
  • Using RewriteMap
  • Advanced techniques and tricks
  • When NOT to use mod_rewrite
  • RewriteRule Flags
  • Technical details

See also

  • mod_rewrite reference documentation
  • Mapping URLs to the Filesystem
  • mod_rewrite wiki
  • Glossary

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Apache mod_rewrite Introduction - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Rewrite

Apache mod_rewrite Introduction

This document supplements the mod_rewrite reference documentation. It describes the basic concepts necessary for use of mod_rewrite. Other documents go into greater detail, but this doc should help the beginner get their feet wet.

See also

  • Module documentation
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • Advanced techniques
  • When not to use mod_rewrite

Introduction

The Apache module mod_rewrite is a very powerful and sophisticated module which provides a way to do URL manipulations. With it, you can do nearly all types of URL rewriting that you may need. It is, however, somewhat complex, and may be intimidating to the beginner. There is also a tendency to treat rewrite rules as magic incantation, using them without actually understanding what they do.

This document attempts to give sufficient background so that what follows is understood, rather than just copied blindly.

Remember that many common URL-manipulation tasks don't require the full power and complexity of mod_rewrite. For simple tasks, see mod_alias and the documentation on mapping URLs to the filesystem.

Finally, before proceeding, be sure to configure mod_rewrite's log level to one of the trace levels using the LogLevel directive. Although this can give an overwhelming amount of information, it is indispensable in debugging problems with mod_rewrite configuration, since it will tell you exactly how each rule is processed.

Regular Expressions

mod_rewrite uses the Perl Compatible Regular Expression vocabulary. In this document, we do not attempt to provide a detailed reference to regular expressions. For that, we recommend the PCRE man pages, the Perl regular expression man page, and Mastering Regular Expressions, by Jeffrey Friedl.

In this document, we attempt to provide enough of a regex vocabulary to get you started, without being overwhelming, in the hope that RewriteRules will be scientific formulae, rather than magical incantations.

Regex vocabulary

The following are the minimal building blocks you will need, in order to write regular expressions and RewriteRules. They certainly do not represent a complete regular expression vocabulary, but they are a good place to start, and should help you read basic regular expressions, as well as write your own.

Character | Meaning | Example
. | Matches any single character | c.t will match cat, cot, cut, etc.
+ | Repeats the previous match one or more times | a+ matches a, aa, aaa, etc
* | Repeats the previous match zero or more times. | a* matches all the same things a+ matches, but will also match an empty string.
? | Makes the match optional. | colou?r will match color and colour.
^ | Called an anchor, matches the beginning of the string | ^a matches a string that begins with a
$ | The other anchor, this matches the end of the string. | a$ matches a string that ends with a.
( ) | Groups several characters into a single unit, and captures a match for use in a backreference. | (ab)+ matches ababab - that is, the + applies to the group. For more on backreferences see below.
[ ] | A character class - matches one of the characters | c[uoa]t matches cut, cot or cat.
[^ ] | Negative character class - matches any character not specified | c[^/]t matches cat or c=t but not c/t

In mod_rewrite the ! character can be used before a regular expression to negate it. This is, a string will be considered to have matched only if it does not match the rest of the expression.

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 as outlined in the following chapters. Figure 1 shows to which locations the back-references are transferred for expansion as well as illustrating the flow of the RewriteRule, RewriteCond matching. In the next chapters, we will be exploring how to use these back-references, so do not fret if it seems a bit alien to you at first.

Flow of RewriteRule and RewriteCond matching
Figure 1: The back-reference flow through a rule.
In this example, a request for /test/1234 would be transformed into /admin.foo?page=test&id=1234&host=admin.example.com.

RewriteRule Basics

A RewriteRule consists of three arguments separated by spaces. The arguments are

  1. Pattern: which incoming URLs should be affected by the rule;
  2. Substitution: where should the matching requests be sent;
  3. [flags]: options affecting the rewritten request.

The Pattern is a regular expression. It is initially (for the first rewrite rule or until a substitution occurs) matched against the URL-path of the incoming request (the part after the hostname but before any question mark indicating the beginning of a query string) or, in per-directory context, against the request's path relative to the directory for which the rule is defined. Once a substitution has occurred, the rules that follow are matched against the substituted value.

Syntax of the RewriteRule directive
Figure 2: Syntax of the RewriteRule directive.

The Substitution can itself be one of three things:

A full filesystem path to a resource

RewriteRule ^/games.* /usr/local/games/web

This maps a request to an arbitrary location on your filesystem, much like the Alias directive.

A web-path to a resource

RewriteRule ^/foo$ /bar

If DocumentRoot is set to /usr/local/apache2/htdocs, then this directive would map requests for http://example.com/foo to the path /usr/local/apache2/htdocs/bar.

An absolute URL

RewriteRule ^/product/view$ http://site2.example.com/seeproduct.html [R]

This tells the client to make a new request for the specified URL.

The Substitution can also contain back-references to parts of the incoming URL-path matched by the Pattern. Consider the following:

RewriteRule ^/product/(.*)/view$ /var/web/productdb/$1

The variable $1 will be replaced with whatever text was matched by the expression inside the parenthesis in the Pattern. For example, a request for http://example.com/product/r14df/view will be mapped to the path /var/web/productdb/r14df.

If there is more than one expression in parenthesis, they are available in order in the variables $1, $2, $3, and so on.

Rewrite Flags

The behavior of a RewriteRule can be modified by the application of one or more flags to the end of the rule. For example, the matching behavior of a rule can be made case-insensitive by the application of the [NC] flag:

RewriteRule ^puppy.html smalldog.html [NC]

For more details on the available flags, their meanings, and examples, see the Rewrite Flags document.

Rewrite Conditions

One or more RewriteCond directives can be used to restrict the types of requests that will be subject to the following RewriteRule. The first argument is a variable describing a characteristic of the request, the second argument is a regular expression that must match the variable, and a third optional argument is a list of flags that modify how the match is evaluated.

Syntax of the RewriteCond directive
Figure 3: Syntax of the RewriteCond directive

For example, to send all requests from a particular IP range to a different server, you could use:

RewriteCond %{REMOTE_ADDR} ^10\.2\.
RewriteRule (.*) http://intranet.example.com$1

When more than one RewriteCond is specified, they must all match for the RewriteRule to be applied. For example, to deny requests that contain the word "hack" in their query string, unless they also contain a cookie containing the word "go", you could use:

RewriteCond %{QUERY_STRING} hack
RewriteCond %{HTTP_COOKIE} !go
RewriteRule .* - [F]

Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".

Matches in the regular expressions contained in the RewriteConds can be used as part of the Substitution in the RewriteRule using the variables %1, %2, etc. For example, this will direct the request to a different directory depending on the hostname used to access the site:

RewriteCond %{HTTP_HOST} (.*)
RewriteRule ^/(.*) /sites/%1/$1

If the request was for http://example.com/foo/bar, then %1 would contain example.com and $1 would contain foo/bar.

Rewrite maps

The RewriteMap directive provides a way to call an external function, so to speak, to do your rewriting for you. This is discussed in greater detail in the RewriteMap supplementary documentation.

.htaccess files

Rewriting is typically configured in the main server configuration setting (outside any <Directory> section) or inside <VirtualHost> containers. This is the easiest way to do rewriting and is recommended. It is possible, however, to do rewriting inside <Directory> sections or .htaccess files at the expense of some additional complexity. This technique is called per-directory rewrites.

The main difference with per-server rewrites is that the path prefix of the directory containing the .htaccess file is stripped before matching in the RewriteRule. In addition, the RewriteBase should be used to assure the request is properly mapped.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Using mod_rewrite for Proxying - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Rewrite

Using mod_rewrite for Proxying

This document supplements the mod_rewrite reference documentation. It describes how to use the RewriteRule's [P] flag to proxy content to another server. A number of recipes are provided that describe common scenarios.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Using RewriteMap
  • Advanced techniques and tricks
  • When not to use mod_rewrite

Proxying Content with mod_rewrite

Description:

mod_rewrite provides the [P] flag, which allows URLs to be passed, via mod_proxy, to another server. Two examples are given here. In one example, a URL is passed directly to another server, and served as though it were a local URL. In the other example, we proxy missing content to a back-end server.

Solution:

To simply map a URL to another server, we use the [P] flag, as follows:

RewriteEngine on
RewriteBase /products/
RewriteRule ^widget/(.*)$ http://product.example.com/widget/$1 [P]
ProxyPassReverse /products/widget/ http://product.example.com/widget/

In the second example, we proxy the request only if we can't find the resource locally. This can be very useful when you're migrating from one server to another, and you're not sure if all the content has been migrated yet.

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^/(.*) http://old.example.com/$1 [P]
ProxyPassReverse / http://old.example.com/

Discussion:

In each case, we add a ProxyPassReverse directive to ensure that any redirects issued by the backend are correctly passed on to the client.

Consider using either ProxyPass or ProxyPassMatch whenever possible in preference to mod_rewrite.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Redirecting and Remapping with mod_rewrite - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Rewrite

Redirecting and Remapping with mod_rewrite

This document supplements the mod_rewrite reference documentation. It describes how you can use mod_rewrite to redirect and remap request. This includes many examples of common uses of mod_rewrite, including detailed descriptions of how each works.

Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration.

See also

  • Module documentation
  • mod_rewrite introduction
  • Controlling access
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • Advanced techniques and tricks
  • When not to use mod_rewrite

From Old to New (internal)

Description:

Assume we have recently renamed the page foo.html to bar.html and now want to provide the old URL for backward compatibility. However, we want that users of the old URL even not recognize that the pages was renamed - that is, we don't want the address to change in their browser.

Solution:

We rewrite the old URL to the new one internally via the following rule:

RewriteEngine on
RewriteRule ^/foo\.html$ /bar.html [PT]

Rewriting From Old to New (external)

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
RewriteRule ^/foo\.html$ bar.html [R]

Discussion

In this example, as contrasted to the internal example above, we can simply use the Redirect directive. mod_rewrite was used in that earlier example in order to hide the redirect from the client:

Redirect /foo.html /bar.html

Resource Moved to Another Server

Description:

If a resource has moved to another server, you may wish to have URLs continue to work for a time on the old server while people update their bookmarks.

Solution:

You can use mod_rewrite to redirect these URLs to the new server, but you might also consider using the Redirect or RedirectMatch directive.

With mod_rewrite

RewriteEngine on
RewriteRule ^/docs/(.+) http://new.example.com/docs/$1 [R,L]

With RedirectMatch

RedirectMatch ^/docs/(.*) http://new.example.com/docs/$1

With Redirect

Redirect /docs/ http://new.example.com/docs/

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 handler to be cgi-script so that it is executed as a CGI program. 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 [H=cgi-script]

Backward Compatibility for file extension change

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 .php?

Solution:

We 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.php
# when and only when document.php exists
<Directory /var/www/htdocs>
RewriteEngine on
RewriteBase /var/www/htdocs

RewriteCond $1.php -f
RewriteCond $1.html !-f
RewriteRule ^(.*).html$ $1.php
 </Directory>

Discussion

This example uses an often-overlooked feature of mod_rewrite, by taking advantage of the order of execution of the ruleset. In particular, mod_rewrite evaluates the left-hand-side of the RewriteRule before it evaluates the RewriteCond directives. Consequently, $1 is already defined by the time the RewriteCond directives are evaluated. This allows us to test for the existence of the original (document.html) and target (document.php) files using the same base filename.

This ruleset is designed to use in a per-directory context (In a <Directory> block or in a .htaccess file), so that the -f checks are looking at the correct directory path. You may need to set a RewriteBase directive to specify the directory base that you're working in.

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:

The very best way to solve this doesn't involve mod_rewrite at all, but rather uses the Redirect directive placed in a virtual host for the non-canonical hostname(s).

<VirtualHost *:80>
ServerName undesired.example.com
ServerAlias example.com notthis.example.com

Redirect / http://www.example.com/
 </VirtualHost>

<VirtualHost *:80>
ServerName www.example.com
 </VirtualHost>

If, for whatever reason, you still want to use mod_rewrite - if, for example, you need this to work with a larger set of RewriteRules - you might use one of the recipes below.

For sites running on a port other than 80:

RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
RewriteCond %{HTTP_HOST} !^$
RewriteCond %{SERVER_PORT} !^80$
RewriteRule ^/?(.*) http://www.example.com:%{SERVER_PORT}/$1 [L,R,NE]

And for a site running on port 80

RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
RewriteCond %{HTTP_HOST} !^$
RewriteRule ^/?(.*) http://www.example.com/$1 [L,R,NE]

If you wanted to do this generically for all domain names - that is, if you want to redirect example.com to www.example.com for all possible values of example.com, you could use the following recipe:

RewriteCond %{HTTP_HOST} !^www\. [NC]
RewriteCond %{HTTP_HOST} !^$
RewriteRule ^/?(.*) http://www.%{HTTP_HOST}/$1 [L,R,NE]

These rulesets will work either in your main server configuration file, or in a .htaccess file placed in the DocumentRoot of the server.

Search for pages in more than one directory

Description:

A particular resource might exist in one of several places, and we want to look in those places for the resource when it is requested. Perhaps we've recently rearranged our directory structure, dividing content into several locations.

Solution:

The following ruleset searches in two directories to find the resource, and, if not finding it in either place, will attempt to just serve it out of the location requested.

RewriteEngine on

# first try to find it in dir1/...
# ...and if found stop and be happy:
RewriteCond %{DOCUMENT_ROOT}/dir1/%{REQUEST_URI} -f
RewriteRule ^(.+) %{DOCUMENT_ROOT}/dir1/$1 [L]

# second try to find it in dir2/...
# ...and if found stop and be happy:
RewriteCond %{DOCUMENT_ROOT}/dir2/%{REQUEST_URI} -f
RewriteRule ^(.+) %{DOCUMENT_ROOT}/dir2/$1 [L]

# else go on for other Alias or ScriptAlias directives,
# etc.
RewriteRule ^ - [PT]

Redirecting to Geographically Distributed Servers

Description:

We have numerous mirrors of our website, and want to redirect people to the one that is located in the country where they are located.

Solution:

Looking at the hostname of the requesting client, we determine which country they are coming from. If we can't do a lookup on their IP address, we fall back to a default server.

We'll use a RewriteMap directive to build a list of servers that we wish to use.

HostnameLookups on
RewriteEngine on
RewriteMap multiplex txt:/path/to/map.mirrors
RewriteCond %{REMOTE_HOST} ([a-z]+)$ [NC]
RewriteRule ^/(.*)$ ${multiplex:%1|http://www.example.com/}$1 [R,L]

## map.mirrors -- Multiplexing Map

de http://www.example.de/
uk http://www.example.uk/
com http://www.example.com/
##EOF##

Discussion
This ruleset relies on HostNameLookups being set on, which can be a significant performance hit.

The RewriteCond directive captures the last portion of the hostname of the requesting client - the country code - and the following RewriteRule uses that value to look up the appropriate mirror host in the map file.

Browser Dependent Content

Description:

We wish to provide different content based on the browser, or user-agent, which is requesting the content.

Solution:

We have to decide, based on the HTTP header "User-Agent", which content to serve. The following config does the following: If the HTTP header "User-Agent" contains "Mozilla/3", the page foo.html is rewritten to foo.NS.html 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 with 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]

Canonical URLs

Description:

On some webservers there is more than one URL for a resource. Usually there are canonical URLs (which are be actually used and distributed) and those which are just shortcuts, internal ones, and so on. Independent of which URL the user supplied with the request, they should finally see the canonical one in their browser address bar.

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 /puppies and /canines by the canonical /dogs.

RewriteRule ^/(puppies|canines)/(.*) /dogs/$2 [R]

Discussion:
This should really be accomplished with Redirect or RedirectMatch directives:

RedirectMatch ^/(puppies|canines)/(.*) /dogs/$2

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. For example, you may wish for visitors, on first entering a site, to go to a particular subdirectory /about/. This may be accomplished using the following ruleset:

Solution:

We redirect the URL / to /about/:

RewriteEngine on
RewriteRule ^/$ /about/ [R]

Note that this can also be handled using the RedirectMatch directive:

RedirectMatch ^/$ http://example.com/about/

Note also that the example rewrites only the root URL. That is, it rewrites a request for http://example.com/, but not a request for http://example.com/page.html. If you have in fact changed your document root - that is, if all of your content is in fact in that subdirectory, it is greatly preferable to simply change your DocumentRoot directive, or move all of the content up one directory, rather than rewriting URLs.

Fallback Resource

Description:
You want a single resource (say, a certain file, like index.php) to handle all requests that come to a particular directory, except those that should go to an existing resource such as an image, or a css file.
Solution:

As of version 2.2.16, you should use the FallbackResource directive for this:

<Directory /var/www/my_blog>
FallbackResource index.php
 </Directory>

However, in earlier versions of Apache, or if your needs are more complicated than this, you can use a variation of the following rewrite set to accomplish the same thing:

<Directory /var/www/my_blog>
RewriteBase /my_blog

RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-f
RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [PT]
 </Directory>

If, on the other hand, you wish to pass the requested URI as a query string argument to index.php, you can replace that RewriteRule with:

RewriteRule (.*) index.php?$1 [PT,QSA]

Note that these rulesets can be uses in a .htaccess file, as well as in a <Directory> block.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Using RewriteMap - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Rewrite

Using RewriteMap

This document supplements the mod_rewrite reference documentation. It describes the use of the RewriteMap directive, and provides examples of each of the various RewriteMap types.

Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Proxying
  • Advanced techniques and tricks
  • When not to use mod_rewrite

Introduction

The RewriteMap directive defines an external function which can be called in the context of RewriteRule or RewriteCond directives to perform rewriting that is too complicated, or too specialized to be performed just by regular expressions. The source of this lookup can be any of the types listed in the sections below, and enumerated in the RewriteMap reference documentation.

The syntax of the RewriteMap directive is as follows:

RewriteMap MapName MapType:MapSource

The MapName is an arbitray name that you assign to the map, and which you will use in directives later on. Arguments are passed to the map via the following syntax:

${ 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.

For example, you might define a RewriteMap as:

RewriteMap examplemap txt:/path/to/file/map.txt

You would then be able to use this map in a RewriteRule as follows:

RewriteRule ^/ex/(.*) ${examplemap:$1}

A default value can be specified in the event that nothing is found in the map:

RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}

Per-directory and .htaccess context

The RewriteMap directive may not be used in <Directory> sections or .htaccess files. You must declare the map in server or virtualhost context. You may use the map, once created, in your RewriteRule and RewriteCond directives in those scopes. You just can't declare it in those scopes.

The sections that follow describe the various MapTypes that may be used, and give examples of each.

txt: Plain text maps

When a MapType of txt is used, the MapSource is a filesystem path to a plain-text mapping file, containing space-separated key/value pair per line. Optionally, a line may be contain a comment, starting with a '#' character.

For example, the following might be valid entries in a map file.

# Comment line
MatchingKey SubstValue
MatchingKey SubstValue # comment

When the RewriteMap is invoked the argument is looked for in the first argument of a line, and, if found, the substitution value is returned.

For example, we might use a mapfile to translate product names to product IDs for easier-to-remember URLs, using the following recipe:

Product to ID configuration

RewriteMap product2id txt:/etc/apache2/productmap.txt
RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]

We assume here that the prods.php script knows what to do when it received an argument of id=NOTFOUND when a product is not found in the lookup map.

The file /etc/apache2/productmap.txt then contains the following:

Product to ID map

##
## productmap.txt - Product to ID map file
##

television 993
stereo 198
fishingrod 043
basketball 418
telephone 328

Thus, when http://example.com/product/television is requested, the RewriteRule is applied, and the request is internally mapped to /prods.php?id=993.

Note: .htaccess files

The example given is crafted to be used in server or virtualhost scope. If you're planning to use this in a .htaccess file, you'll need to remove the leading slash from the rewrite pattern in order for it to match anything:

RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]

Cached lookups

The looked-up keys are cached by httpd until the mtime (modified time) of the mapfile changes, or the httpd server is restarted. This ensures better performance on maps that are called by many requests.

rnd: Randomized Plain Text

When a MapType of rnd is used, the MapSource is a filesystem path to a plain-text mapping file, each line of which contains a key, and one or more values separated by |. One of these values will be chosen at random if the key is matched.

For example, you might use the following map file and directives to provide a random load balancing between several back-end server, via a reverse-proxy. Images are sent to one of the servers in the 'static' pool, while everything else is sent to one of the 'dynamic' pool.

Rewrite map file

##
## map.txt -- rewriting map
##

static www1|www2|www3|www4
dynamic www5|www6

Configuration directives

RewriteMap servers rnd:/path/to/file/map.txt

RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]
RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]

So, when an image is requested and the first of these rules is matched, RewriteMap looks up the string static in the map file, which returns one of the specified hostnames at random, which is then used in the RewriteRule target.

If you wanted to have one of the servers more likely to be chosen (for example, if one of the server has more memory than the others, and so can handle more requests) simply list it more times in the map file.

static www1|www1|www2|www3|www4

dbm: DBM Hash File

When a MapType of dbm is used, the MapSource is a filesystem path to a DBM database file containing key/value pairs to be used in the mapping. This works exactly the same way as the txt map, but is much faster, because a DBM is indexed, whereas a text file is not. This allows more rapid access to the desired key.

You may optionally specify a particular dbm type:

RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm

The type can be sdbm, gdbm, ndbm or db. However, it is recommended that you just use the httxt2dbm utility that is provided with Apache HTTP Server, as it will use the correct DBM library, matching the one that was used when httpd itself was built.

To create a dbm file, first create a text map file as described in the txt section. Then run httxt2dbm:

$ httxt2dbm -i mapfile.txt -o mapfile.map

You can then reference the resulting file in your RewriteMap directive:

RewriteMap mapname dbm:/etc/apache/mapfile.map

Note that with some dbm types, more than one file is generated, with a common base name. For example, you may have two files named mapfile.map.dir and mapfiile.map.pag. This is normal, and you need only use the base name mapfile.map in your RewriteMap directive.

Cached lookups

The looked-up keys are cached by httpd until the mtime (modified time) of the mapfile changes, or the httpd server is restarted. This ensures better performance on maps that are called by many requests.

int: Internal Function

When a MapType of int is used, the MapSource is one of the available internal RewriteMap functions. Module authors can provide additional internal functions by registering them with the ap_register_rewrite_mapfunc API. The functions that are provided by default are:

  • toupper:
    Converts the key to all upper case.
  • tolower:
    Converts the key to all lower case.
  • escape:
    Translates special characters in the key to hex-encodings.
  • unescape:
    Translates hex-encodings in the key back to special characters.

To use one of these functions, create a RewriteMap referencing the int function, and then use that in your RewriteRule:

Redirect a URI to an all-lowercase version of itself

RewriteMap lc int:tolower
RewriteRule (.*[A-Z]+.*) ${lc:$1} [R]

Please note that the example offered here is for illustration purposes only, and is not a recommendation. If you want to make URLs case-insensitive, consider using mod_speling instead.

prg: External Rewriting Program

When a MapType of prg is used, the MapSource is a filesystem path to an executable program which will providing the mapping behavior. This can be a compiled binary file, or a program in an interpreted language such as Perl or Python.

This program is started once, when the Apache HTTP Server is started, and then communicates with the rewriting engine via STDIN and STDOUT. That is, for each map function lookup, it expects one argument via STDIN, and should return one new-line terminated response string on STDOUT. If there is no corresponding lookup value, the map program should return the four-character string "NULL" to indicate this.

External rewriting programs are not started if they're defined in a context that does not have RewriteEngine set to on.

A simple example is shown here which will replace all dashes with underscores in a request URI.

Rewrite configuration

RewriteMap d2u prg:/www/bin/dash2under.pl
RewriteRule - ${d2u:%{REQUEST_URI}}

dash2under.pl

#!/usr/bin/perl
$| = 1; # Turn off I/O buffering
while (<STDIN>) {
s/-/_/g; # Replace dashes with underscores
print $_;
 }

Use a RewriteLock!

When using a prg: RewriteMap, you should use a RewriteLock. Failure to do so will result in an error message in the log file, and may result in a race condition on concurrent requests.

Caution!

  • Keep your rewrite map program as simple as possible. If the program hangs, it will cause httpd to wait indefinitely for a response from the map, which will, in turn, cause httpd to stop responding to requests.
  • Be sure to turn off buffering in your program. In Perl this is done by the second line in the example script: $| = 1; This will of course vary in other languages. Buffered I/O will cause httpd to wait for the output, and so it will hang.
  • Remember that there is only one copy of the program, started at server startup. All requests will need to go through this one bottleneck. This can cause significant slowdowns if many requests must go through this process, or if the script itself is very slow.

Summary

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 (.htaccess files or <Directory> blocks) it is possible to use this map in per-directory context.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Apache mod_rewrite Technical Details - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Rewrite

Apache mod_rewrite Technical Details

This document discusses some of the technical details of mod_rewrite and URL matching.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Virtual hosts
  • Proxying
  • Using RewriteMap
  • Advanced techniques and tricks
  • When not to use mod_rewrite

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.

Flow of RewriteRule and RewriteCond matching
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.

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.


Dynamic mass virtual hosts with mod_rewrite - Apache HTTP Server Version 2.2

Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Rewrite

Dynamic mass virtual hosts with mod_rewrite

This document supplements the mod_rewrite reference documentation. It describes how you can use mod_rewrite to create dynamically configured virtual hosts.

mod_rewrite is not the best way to configure virtual hosts. You should first consider the alternatives before resorting to mod_rewrite. See also the "how to avoid mod_rewrite document.

See also

  • Module documentation
  • mod_rewrite introduction
  • Redirection and remapping
  • Controlling access
  • Proxying
  • RewriteMap
  • Advanced techniques and tricks
  • When not to use mod_rewrite

Virtual Hosts For Arbitrary Hostnames

Description:

We want to automatically create a virtual host for every hostname which resolves in our domain, without having to create new VirtualHost sections.

In this recipe, we assume that we'll be using the hostname www.SITE.example.com for each user, and serve their content out of /home/SITE/www.

Solution:

RewriteEngine on

RewriteMap lowercase int:tolower

RewriteCond %{lowercase:%{HTTP_HOST}} ^www\.([^.]+)\.example\.com$
RewriteRule ^(.*) /home/%1/www$1

Discussion
You will need to take care of the DNS resolution - Apache does not handle name resolution. You'll need either to create CNAME records for each hostname, or a DNS wildcard record. Creating DNS records is beyond the scope of this document.

The internal tolower RewriteMap directive is used to ensure that the hostnames being used are all lowercase, so that there is no ambiguity in the directory structure which must be created.

Parentheses used in a RewriteCond are captured into the backreferences %1, %2, etc, while parentheses used in RewriteRule are captured into the backreferences $1, $2, etc.

As with many techniques discussed in this document, mod_rewrite really isn't the best way to accomplish this task. You should, instead, consider using mod_vhost_alias instead, as it will much more gracefully handle anything beyond serving static files, such as any dynamic content, and Alias resolution.

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, except for some changes, required for backward compatibility and to make the mod_rewrite part work properly; the second half configures mod_rewrite to do the actual work.

Because mod_rewrite runs before other URI translation modules (e.g., mod_alias), mod_rewrite must be told to explicitly ignore any URLs that would have been handled by those modules. And, because these rules would otherwise bypass any ScriptAlias directives, we must have mod_rewrite explicitly enact those mappings.

# 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>

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 handler
RewriteCond %{REQUEST_URI} ^/cgi-bin/
RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [H=cgi-script]

Using a Separate Virtual Host Configuration File

This arrangement uses more advanced mod_rewrite features to work out 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 should look something like this:

customer-1.example.com /www/customers/1
customer-2.example.com /www/customers/2
# ...
customer-N.example.com /www/customers/N

The httpd.conf should contain the following:

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 [H=cgi-script]

Copyright 2017 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0.