Apache HTTP Server Version 2.0 문서 - Apache HTTP Server

Apache HTTP Server Version 2.0

Apache > HTTP Server > Documentation

Apache HTTP Server Version 2.0 문서

발표문

  • 버전 2.0의 새로운 기능
  • 1.3에서 2.0 버전으로 업그레이드
  • 아파치 라이선스

참조 설명서

  • 컴파일과 설치
  • 시작
  • 중단과 재시작
  • 설정 지시어
  • 지시어 빠른참조
  • 모듈
  • 다중처리모듈 (MPM)
  • 필터
  • 핸들러
  • 서버와 지원 프로그램
  • 용어

사용자 지침서

  • 주소와 포트 지정
  • 설정파일
  • 섹션 설정
  • 내용협상 (content negotiation)
  • 동적공유객체 (DSO)
  • 환경변수
  • 로그파일
  • URL을 파일시스템에 대응
  • 성능향상
  • 보안 팁
  • 서버 전역 설정
  • SSL/TLS 암호화
  • CGI의 Suexec 실행
  • URL 재작성(rewriting) 지침서
  • 가상호스트

How-To / 투토리얼

  • 인증, 권한부여, 접근제어
  • CGI: 동적 내용 생성
  • .htaccess 파일
  • Server Side Includes (SSI)
  • 사용자별 웹디렉토리 (public_html)

플래폼별 설명

  • Microsoft Windows
  • Novell NetWare
  • EBCDIC 포팅

다른 주제

  • 자주 물어보는 질문 (FAQ)
  • 사이트맵
  • 개발자를 위한 문서
  • 기타

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


1.3에서 2.0으로 업그레이드 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

1.3에서 2.0으로 업그레이드

우리는 기존 아파치 사용자가 업그레이드하는 것을 돕기위해 중요한 정보를 알려주는 문서를 제공한다. 이 문서는 간단한 요약이므로, 새로운 기능 문서나 src/CHANGES 파일에서 정보를 찾아봐야 한다.

참고

  • 아파치 2.0의 새로운 기능 요약

컴파일시 구성 변화

  • 아파치는 이제 아파치 컴파일과 설치를 위해 autoconf와 libtool 시스템을 사용한다. 이 시스템의 사용법은 Apache 1.3의 APACI 시스템과 같지는 않지만 비슷하다.
  • 컴파일 여부를 선택할 모듈외에 Apache 2.0은 요청을 처리하는 주요 부분을 다중처리 모듈 (Multi-Processing Modules) (MPM)로 옮겼다.

실행시 설정 변화

  • Apache 1.3에서 서버 핵심에 있었던 많은 지시어들이 이제는 MPM에 있다. 서버가 Apache 1.3과 최대한 비슷하게 동작하길 바란다면 prefork MPM을 선택해야 한다. 다른 MPM은 다른 지시어를 사용하여 프로세스 생성과 요청의 처리를 조절한다.
  • proxy 모듈은 HTTP/1.1에 맞추어 수정되었다. 중요한 변화중 하나는 이제 프록시 접근제어가 <Directory proxy:> 블록이 아니라 <Proxy> 블록에 위치하는 점이다.
  • 몇몇 모듈에서 PATH_INFO (진짜 경로명 뒤에 나오는 경로 정보) 처리 방식이 변경되었다. 전에 핸들러였지만 이제 필터로 구현되는 모듈은 더 이상 PATH_INFO가 있는 요청을 받아들이지 못한다. INCLUDES나 PHP와 같은 필터는 core 핸들러 위에 구현되기때문에 PATH_INFO가 있는 요청을 거부한다. core 핸들러가 PATH_INFO가 있는 요청을 받아들이고 server-side include에서 PATH_INFO를 사용하게 하려면, AcceptPathInfo 지시어를 사용해야 한다.
  • CacheNegotiatedDocs 지시어는 이제 아규먼트로 on과 off를 받는다. 기존의 CacheNegotiatedDocs는 CacheNegotiatedDocs on으로 수정해야 한다.
  • ErrorDocument 지시어는 더이상 메세지를 나타내는 아규먼트 앞에 따옴표를 사용하지 않는다. 대신 쌍따옴표로 메세지를 묶어야 한다. 예를 들어 과거

    ErrorDocument 403 "Some Message

    는 다음과 같이 수정해야 한다.

    ErrorDocument 403 "Some Message"

    두번째 아규먼트가 유효한 URL이나 경로명이 아니라면 메세지로 간주한다.
  • AccessConfig와 ResourceConfig 지시어는 사라졌다. 기존에 사용하던 지시어는 같은 기능을 하는 Include 지시어로 대체할 수 있다. 과거에 설정파일에서 이 지시어들을 사용하지않고 이 지시어들의 기본값을 사용했다면, http.conf에 Include conf/access.conf와 Include conf/srm.conf를 추가할 필요가 있다. 아파치가 이전 지시어와 같은 순서로 설정파일을 읽게하려면 Include 지시어를 httpd.conf 끝에 두고, srm.conf이 access.conf 앞에 나와야 한다.
  • BindAddress와 Port 지시어는 사라졌다. 더 유연한 Listen 지시어가 같은 기능을 한다.
  • Apache-1.3에서 Port는 자기참조 URL의 포트 번호를 설정하는 일도 했다. Apache-2.0에서 이 기능은 새로운 ServerName으로 한다. 한 지시어에 호스트명과 자기참조 URL을 위한 포트 번호를 같이 설정할 수 있다.
  • ServerType 지시어는 사라졌다. 요청을 서비스하는 방법은 이제 MPM 선택에 달렸다. 현재 inetd에서 시작하도록 설계된 MPM은 없다.
  • AgentLog, RefererLog, RefererIgnore 지시어를 제공한 mod_log_agent와 mod_log_referer 모듈이 없어졌다. agent 로그와 referer 로그는 mod_log_config의 CustomLog 지시어를 사용하여 계속 제공된다.
  • AddModule과 ClearModuleList 지시어는 사라졌다. 이 지시어들은 모듈을 올바른 순서로 활성화하려고 사용했다. 새로운 Apache 2.0 API는 모듈이 활성화되는 순서를 명시적으로 지정할 수 있어서, 이 지시어들이 필요없게 되었다.
  • FancyIndexing 지시어가 없어졌다. IndexOptions 지시어의 FancyIndexing 옵션이 같은 기능을 한다.
  • mod_negotiation의 MultiViews 내용협상이 더 엄격하게 기본파일을 찾는다. 내용협상은 협상가능한 파일 중에서만 선택한다. MultiviewsMatch 지시어를 사용하여 이전과 같이 동작하게 할 수 있다.

기타 변화

  • Apache 1.3에서 실험적이였던 mod_auth_digest 모듈이 이제 표준 모듈이 되었다.
  • Apache 1.3에서 실험적이였던 mod_mmap_static 모듈이 mod_file_cache로 대체되었다.
  • 배포본이 완전히 새로 구성되어 더이상 독립된 src 디렉토리가 없다. 대신 소스는 주 배포본 디렉토리 아래 논리적으로 구성되있고, 컴파일한 서버는 다른 디렉토리로 설치된다.

제삼자가 만든 모듈

Apache 2.0에서 서버 API가 많이 변경되었다. Apache 1.3 API에 맞춰진 기존 모듈을 수정없이 Apache 2.0에서 사용할 수 없다. 자세한 정보는 개발자 문서를 참고하라.


Apache 2.0의 새로운 기능 개요 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Apache 2.0의 새로운 기능 개요

이 문서는 아파치 웹서버 1.3 버전과 2.0버전간의 주된 차이점을 설명한다.

참고

  • 1.3에서 2.0으로 업그레이드

핵심 부분에서 나아진 점

유닉스 쓰레드
POSIX 쓰레드를 지원하는 유닉스 시스템에서 아파치를 여러 프로세스와 여러 쓰레드로 혼합해서 실행할 수 있다. 전부는 아니지만 많은 경우 확장가능성(scalability)을 높인다.
새로운 컴파일 시스템
컴파일 시스템이 autoconf와 libtool을 사용하도록 재작성되었다. 그래서 아파치 구성 시스템이 다른 패키지들과 좀더 비슷해졌다.
여러 프로토콜 지원
이제 아파치는 여러 프로토콜을 서비스할 수 있는 구조를 갖췄다. mod_echo가 그 예로 작성되었다.
비유닉스 플래폼에 대한 더 나은 지원
Apache 2.0는 BeOS, OS/2, 윈도우즈와 같은 비유닉스 플래폼에서 더 빠르고 안정화되었다. 이제 아파치는 이들 플래폼에서 버그가 많고 성능이 느렸던 POSIX 호환층 대신 자체 API로 구현된 플래폼 특유의 다중처리 모듈 (MPM)과 Apache Portable Runtime (APR)을 사용하여 구현된다.
새로운 아파치 API
모듈 API가 2.0에서 상당히 변했다. 1.3의 여러 모듈 순서와 우선순위 문제가 사라졌다. 2.0은 이를 대부분 자동으로 처리하며, 모듈 순서는 이제 더 유연한 훅(hook) 단위로 지정한다. 또, 아파치 서버 핵심 부분을 수정하지 않고 새로운 모듈 기능을 제공하는 함수가 추가되었다.
IPv6 지원
하위 Apache Portable Runtine 라이브러리가 IPv6를 지원하는 시스템에서 아파치는 기본적으로 IPv6 소켓을 기다린다. 또, Listen, NameVirtualHost, VirtualHost 지시어가 IPv6 숫자 주소를 지원한다. (예, "Listen [fe80::1]:8080").
필터링
이제 아파치 모듈을 서버로 오고가는 흐름에 대한 필터로 사용할 수 있다. 예를 들어 mod_include의 INCLUDES 필터를 사용하여 CGI 스크립트 출력에서 Server Side Include 지시어를 처리할 수 있다. mod_ext_filter 모듈은 CGI 프로그램을 핸들러로 사용하는 것과 같이 외부 프로그램을 필터로 사용할 수 있게 한다.
다국어 오류 응답
브라우저로 보내는 오류 응답문이 이제 SSI 문서를 사용하여 다국어로 제공된다. 관리자는 통일된 외관을 위해 이 문서를 수정할 수 있다.
간단해진 설정
혼란을 주던 많은 지시어들이 간단해졌다. 자주 혼란을 주던 Port와 BindAddress 지시어는 없어지고 IP 주소 연결에 Listen 지시어만을 사용한다. ServerName 지시어는 리다이렉션과 가상호스트 인식에만 사용될 서버명과 포트를 지정한다.
Windows NT 유니코드 자체 지원
Windows NT에서 Apache 2.0은 이제 모든 파일명 인코딩에 utf-8을 사용한다. 파일명은 하위 유니코드 파일시스템으로 직접 변역되어, Windows 2000과 Windows XP를 포함한 모든 Windows NT기반 시스템에 다국어 지원을 제공한다. 이 기능은 Windows 95, 98, ME에는 지원되지않고, 파일시스템 접근에 전과 같이 시스템의 지역 코드페이지를 사용한다.
정규표현식 라이브러리 Updated
Apache 2.0은 Perl호환 정규표현식 라이브러리 (Perl Compatible Regular Expression Library) (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 Basic Authentication에 사용하는 정보를 LDAP 데이터베이스에 저장한다. 관련된 mod_ldap 모듈은 연결풀(connection pool)을 제공하고, 결과를 캐싱한다.
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
이 프록시 모듈은 새로운 필터 구조를 이용하고 더 믿을만한 HTTP/1.1 프록시를 구현하기위해 완전히 재작성되었다. 추가로 새로운 <Proxy> 설정 섹션은 프록시 설정을 더 쉽게 (그리고 내부적으로 더 빠르게) 만든다. 과거 <Directory "proxy:..."> 설정은 이제 지원하지 않는다. 모듈은 proxy_connect, proxy_ftp, proxy_http와 같이 지원하는 프로토콜 별로 나눠졌다.
mod_negotiation
새로운 ForceLanguagePriority 지시어는 클라이언트가 NOT ACCEPTABLE이나 MULTIPLE CHOICES 응답 대신 모든 경우 한 문서를 받음을 보장한다. 추가로 협상 알고리즘과 MultiViews 알고리즘이 더 일관된 결과를 내도록 수정되었고, 문서 내용을 포함할 수 있는 새로운 형식의 type map이 추가되었다.
mod_autoindex
자동으로 생성된 디렉토리 목록이 이제 더 깔끔한 형식을 위해 HTML 표를 사용할 수 있게 되었고, 버전 정렬을 포함하여 정렬순서를 자세히 조절할 수 있으며, 디렉토리 목록을 와일드카드로 걸러낼 수 있다.
mod_include
새로운 지시어를 사용하여 SSI 요소의 기본 시작 태그와 마침 태그를 변경할 수 있고, 오류와 시간형식을 SSI 문서외에 주 설정파일에서도 설정할 수 있게 되었다. mod_include에서 (이제 Perl 정규표현식 문법으로) 정규표현식 파싱과 그룹의 결과를 mod_include의 $0 ... $9 변수로 얻을 수 있다.
mod_auth_dbm
이제 AuthDBMType 지시어를 사용하여 여러 DBM류 데이터베이스를 지원한다.


The Apache License, Version 2.0 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

The Apache License, Version 2.0

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

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

  1. Definitions

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

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

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

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

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

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

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

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

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

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

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

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

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

END OF TERMS AND CONDITIONS

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

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

Copyright [yyyy] [name of copyright owner]

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

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

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


컴파일과 설치 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

컴파일과 설치

이 문서는 유닉스와 유닉스류 시스템에서 아파치를 컴파일하고 설치하는 것만을 다룬다. 윈도우즈에서 컴파일하고 설치하는 방법은 마이크로소프트 윈도우즈에서 아파치 사용을 참고하라. 다른 플래폼에 대해서는 플래폼 문서를 참고하라.

아파치 2.0의 구성과 설치 환경은 1.3과 매우 다르다. 아파치 1.3은 쉬운 설치를 위해 자체 스크립트를 사용했다. 아파치 2.0은 이제 다른 여러 오픈소스 프로젝트와 비슷한 환경을 만들기위해 libtool과 autoconf를 사용한다.

참고

  • 아파치 시작
  • 아파치 중단과 재시작

성미 급한 사람을 위한 개요

다운로드 | $ lynx http://www.apache.org/dist/httpd/httpd-2_0_NN.tar.gz
압축 풀기 $ gzip -d httpd-2_0_NN.tar.gz
$ tar xvf httpd-2_0_NN.tar
구성 | $ ./configure --prefix=PREFIX
컴파일 | $ make
설치 | $ make install
설정 | $ vi PREFIX/conf/httpd.conf
검사 | $ PREFIX/bin/apachectl start

NN은 현재 작은 버전 숫자로, PREFIX는 서버가 설치될 파일시스템 경로로 대체해야 한다. PREFIX를 지정하지 않으면 기본값으로 /usr/local/apache2를 사용한다.

아래는 아파치 웹서버를 컴파일하고 설치하기위한 요구사항부터 컴파일과 설치 과정을 각각 자세히 설명한다.

요구사항

아파치를 컴파일하기위해 다음과 같은 것들이 필요하다:

디스크 공간
디스크 여유공간이 최소 50 MB 이상인지 확인하라. 설치후 아파치는 약 10 MB의 디스크 공간을 차지한다. 실제 필요한 디스크 공간은 선택한 구성 옵션과 추가 모듈에 따라 상당히 차이가 난다.
ANSI-C 컴파일러와 컴파일 시스템
ANSI-C 컴파일러가 설치되있는지 확인하라. Free Software Foundation (FSF)의 GNU C compiler (GCC)를 추천한다. (버전 2.7.2면 된다.) GCC가 없다면 최소한 사용하는 컴파일러가 ANSI 호환인지 확인하라. 추가로 PATH 환경변수는 make와 같은 기본적인 컴파일 도구를 포함해야 한다.
정확한 시간
HTTP 프로토콜에는 하루중 시간을 표현하는 부분이 있다. 그래서 이제 시스템의 시간 동기화 기능을 살펴볼 시간이다. 보통 이를 위해 Network Time Protocol (NTP)에 기반한 ntpdate나 xntpd를 사용한다. NTP 소프트웨어와 공개 시간 서버에 대한 정보는 뉴스그룹 comp.protocols.time.ntp와 NTP 홈페이지를 참고하라.
Perl 5 [선택사항]
(Perl로 쓰여진) apxs나 dbmmanage와 같은 지원 스크립트를 위해 Perl 5 인터프리터가 필요하다. (버전 5.003 이상이면 된다.) `configure' 스크립트가 이 인터프리터를 찾지 못해도 문제없이 아파치 2.0을 컴파일하고 설치할 수 있다. 다만 지원 스크립트를 사용하지 못할 뿐이다. 여러 Perl 인터프리터가 설치되있다면 (아마도 살때 포함된 Perl 4와 직접 컴파일한 Perl 5) ./configure가 올바른 것을 찾기위해 --with-perl 옵션을 (아래 참고) 사용하길 바란다.

다운로드

아파치는 여러 미러 목록이 있는 아파치 웹서버 다운로드 사이트에서 다운로드할 수 있다. 그곳에서 최신 안정판을 찾을 수 있다.

다운로드후, 특히 미러 사이트를 사용했다면, 완전하고 변경되지않은 아파치 웹서버임을 확인하는 것이 중요하다. PGP 서명을 가지고 다운로드한 타볼(tarball)을 검사하여 확인한다. 이 과정은 두 단계를 거친다. 먼저 아파치 웹서버 다운로드 사이트에서 KEYS 파일을 얻는다. (KEYS 파일 자체가 수정되지 않았음을 확인하기위해 이전 아파치 버전의 파일을 사용하거나 공개 키 서버에서 키를 가져오는 것이 좋다.) 키를 (pgp 버전에 따라 다름) 다음 명령어 중 하나로 개인 키 링에 포함한다:

$ pgp < KEYS

혹은

$ gpg --import KEYS

다음 단계는 아파치 웹사이트에서 얻은 PGP 서명을 가지고 타볼을 검사하는 일이다. 서명 파일에 대한 링크는 해당 다운로드 링크 아래나 아파치 배포본 사이트의 특정 디렉토리에서 찾을 수 있다. 서명파일 이름은 소스 타볼 파일명뒤에 .asc가 붙은 것이다. (또, pgp 버전에 따라 다름) 다음 명령어중 하나로 배포본을 확인할 수 있다:

$ pgp httpd-2_0_NN.tar.gz.asc

혹은

$ gpg --verify httpd-2_0_NN.tar.gz.asc

다음과 같은 메세지가 나와야 한다.

Good signature from user "Martin Kraemer <martin@apache.org>".

키 링에 포함된 신뢰관계에 따라 키와 키 서명자 사이의 관계를 확인할 수 없다는 문구가 나올 수도 있다. 그러나 당신이 KEYS 파일를 신뢰한다면 문제가 아니다.

압축 풀기

아파치 웹서버 타볼에서 소스를 푸는 작업은 단순히 압축과 tar를 푸는 것이다:

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

그러면 현재 디렉토리 아래에 배포본의 소스코드를 담은 새로운 디렉토리가 생긴다. 서버를 컴파일하기 전에 그 디렉토리로 cd해야 한다.

소스 트리 구성하기

다음 과정은 특정 플래폼과 개인적인 필요에 따라 아파치 소스 트리를 구성하는 일이다. 이를 위해 배포본의 최상위 디렉토리에 있는 configure 스크립트를 사용한다. (아파치 소스 트리의 CVS 버전을 다운로드한 개발자는 이미 autoconf와 libtool가 설치되있고, 다음 과정으로 넘어가기 전에 buildconf를 실행해야 한다. 이는 정식 버전에서는 필요없다.)

모두 기본 옵션을 사용하여 소스 트리를 구성하려면 간단히 ./configure를 입력하면된다. 기본 옵션을 수정하려면 ./configure에 여러 변수와 명령행 옵션을 사용한다. 다른 옵션은 ./configure 명령어 뒤에 위치하지만, 환경변수는 일반적으로 앞에 나온다. 여기서 가장 중요한 옵션은 아파치가 정상적으로 작동하기위해 구성되는 장소이자 아파치가 설치될 장소인 prefix다. 그러나 입맛에 맞는 다른 다양한 옵션들이 있다.

여러분이 선택할 수 있는 가능성을 보여주기위해 다음은 특정 컴파일러와 플래그를 사용하고 나중에 DSO로 읽어들일 두 모듈 mod_rewrite와 mod_speling을 추가하여 /sw/pkg/apache에 설치할 아파치를 컴파일하는 전형적인 예이다:

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

configure를 실행하면 몇분간 시스템의 기능을 검사하여 나중에 서버를 컴파일할때 사용할 Makefile들을 만든다.

아파치의 모든 구성 옵션들을 볼 수 있는 가장 쉬운 방법은 ./configure --help이다. 다음은 대부분의 아규먼트와 환경변수에 대한 간단한 설명이다.

환경변수

autoconf는 컴파일 환경을 구성하기위해 여러 환경변수를 사용한다. 일반적으로 이 환경변수들은 서버의 기능이 아니라 아파치를 컴파일하는 방법에 영향을 미친다. 이 변수를 configure를 실행하기 전에 환경에 넣을 수도 있지만, 위의 예와 같이 configure 명령행에 써주는 것이 더 쉽다.

CC=...
C 컴파일러 명령어 이름.
CPPFLAGS=...
기타 C 선처리기와 컴파일러 옵션.
CFLAGS=...
C 컴파일러의 디버깅과 최적화 옵션.
LDFLAGS=...
기타 링커에 넘겨줄 옵션.
LIBS=...
링커에 넘겨줄 라이브러리 위치 정보 ("-L"과 "-l" 옵션).
INCLUDES=...
헤더파일을 찾을 디렉토리들 ("-Idir").
TARGET=... [기본값: apache]
만들 실행파일 이름.
NOTEST_CPPFLAGS=...
NOTEST_CFLAGS=...
NOTEST_LDFLAGS=...
NOTEST_LIBS=...
이 변수들은 NOTEST가 안붙은 것들과 같은 기능을 한다. 단, 이 변수들은 autoconf가 기능 검사를 마친후 컴파일 과정에만 영향을 미친다. 그래서 기능 검사중에는 문제를 일으키지만 마지막 컴파일때는 사용해야할 옵션을 포함한다.
SHLIB_PATH=...
컴파일러와 링커가 사용할 공유라이브러리 경로를 지정하는 옵션.

autoconf 출력 옵션

--help
모든 옵션과 사용법을 출력한다. 실제 구성을 하지는 않는다.
--quiet
일반적인 "checking..." 문구를 출력하지 않는다.
--verbose
구성 과정중 사용하는 모든 파일명을 포함하여 매우 자세한 정보를 출력한다.

경로명

아파치가 설치될 경로명을 지정하는 방법은 현재 두가지다. 첫번째는 디렉토리를 지정하고, 아파치가 그 장소 밑에 설치하는 방법이다.

--prefix=PREFIX [기본값: /usr/local/apache2]
아파치 파일들이 설치될 디렉토리를 지정한다.

아키텍쳐 특유의 파일들을 다른 디렉토리에 설치할 수도 있다.

--exec-prefix=EPREFIX [기본값: PREFIX]
아키텍쳐 특유의 파일들이 위치할 디렉토리를 지정한다.

두번째로 아파치 설치 경로 위치를 구성하는 더 유연한 방법은 config.layout 파일을 사용하는 것이다. 이 방법을 사용하면 파일의 종류마다 위치를 따로 지정할 수 있다. config.layout 파일은 여러 구성 예를 담고있고, 이를 참고하여 자신만의 구성을 만들 수도 있다. 이 파일 내용은 <Layout FOO>...</Layout>로 구분되며 FOO와 같은 이름으로 지칭한다.

--enable-layout=LAYOUT
config.layout의 해당 레이아웃을 사용하여 설치 경로를 지정한다.

모듈

아파치는 모듈로 구성된 서버다. 서버 핵심에는 가장 기본적인 기능만이 포함되있다. 여러 모듈은 확장 기능을 제공한다. 구성 과정중에 서버에서 사용하기위해 컴파일할 모듈을 선택해야 한다. 문서에 포함된 모듈 목록을 참고하라. 상태가 "Base"인 모듈은 (예, mod_userdir) 서버에 기본적으로 포함되므로, 원하지 않는다면 명시적으로 빼줘야 한다. 다른 상태의 모듈은 (예, mod_expires) 사용하길 원한다면 명시적으로 넣어줘야 한다.

모듈을 컴파일하고 사용하는 방법은 두 가지다. 정적으로 컴파일된 모듈은 아파치 실행파일에 영구히 포함된다. 이외에 운영체제가 동적공유객체(Dynamic Shared Objects, DSO)를 지원하고 autoconf가 이 사실을 알아낸다면 모듈을 동적으로 컴파일할 수도 있다. DSO 모듈은 아파치 실행파일에 직접 포함되지는 않지만, mod_so가 제공하는 설정 지시어를 사용하여 실행중에 서버에 포함하거나 뺄 수 있다. 컴파일때 동적 모듈을 포함하면 mod_so는 자동으로 서버에 포함된다. 동적 모듈을 같이 컴파일하지 않고 서버가 DSO를 읽어들일 수 있게 하려면 --enable-so 옵션을 직접 사용해야 한다.

--enable-MODULE[=shared]
모듈 MODULE을 컴파일하여 포함한다. MODULE은 모듈 문서에서 나온 모듈명에서 "_module"을 뺀 이름이다. 모듈을 DSO로 컴파일하려면 =shared 옵션을 붙인다.
--disable-MODULE
이 옵션을 사용하지 않으면 컴파일하여 포함되었을 모듈 MODULE을 제거한다.
--enable-modules=MODULE-LIST
공백으로 구분한 MODULE-LIST에 나온 모듈들을 컴파일하여 포함한다.
--enable-mods-shared=MODULE-LIST
공백으로 구분한 MODULE-LIST에 나온 모듈들을 동적으로 읽어들일 수 있는 (DSO) 모듈로 컴파일하여 포함한다.

--enable-modules와 --enable-mods-shared 옵션에서 MODULE-LIST는 모듈명들을 공백으로 구분한 목록이다. 예를 들어 mod_dav와 mod_info를 포함하려면 아래 두 가지 모두 가능하다.

./configure --enable-dav --enable-info

나

./configure --enable-modules="dav info"

또, 특별한 키워드 all이나 most를 사용하여 한번에 모든 혹은 대부분의 모듈을 포함할 수 있다. 그런후 원하지 않는 모듈은 --disable-MODULE 옵션으로 제거한다. 예를 들어 mod_info를 제외한 모든 모듈을 DSO로 포함하려면,

./configure --enable-mods-shared=all --disable-info

표준 모듈들외에 아파치 2.0은 다중처리 모듈 (MPM)을 선택할 수 있다. 오직 한 MPM만을 컴파일 과정에 포함할 수 있다. 각 플래폼의 기본 MPM은 MPM 문서 페이지에 나와있으나, configure 명령행에서 변경할 수 있다.

--with-mpm=NAME
mpm NAME을 선택한다.

mpm_name이라는 MPM을 사용한다면, 다음과 같다.

./configure --with-mpm=mpm_name

DBM

mod_auth_dbm과 mod_rewrite의 DBM RewriteMap같은 여러 아파치 기능은 정보를 빨리 찾아보기위해 키와 값으로된 간단한 데이터베이스를 사용한다. 아파치는 소스코드에 SDBM을 포함하여, 이 데이터베이스는 항상 사용할 수 있다. 만약 다른 데이터베이스를 사용하려면 다음 configure 옵션을 사용한다:

--with-gdbm[=path]
--with-ndbm[=path]
--with-berkeley-db[=path]
path를 지정하지않으면 아파치는 일상적인 검색 경로에서 헤더파일과 라이브러리를 찾는다. 직접 path를 알려주면 아파치가 path/lib와 path/include에서 필요한 파일을 찾게 된다. 마지막으로 path에 헤더파일 경로와 라이브러리 경로를 콜론으로 구분하여 적을 수도 있다.

Suexec

아파치는 사용자 CGI 프로그램을 격리하여 실행할 수 있는 suexec라는 지원 프로그램을 포함한다. 그러나 suexec를 잘못 설정하면 심각한 보안 문제가 생길 수 있다. 그러므로 이 기능을 사용하기 전에 suexec 문서를 주의있게 읽고 고민해야 한다.

컴파일

이제 다음 명령어 하나로 아파치의 여러 부분을 컴파일할 수 있다:

$ make

여기서 좀 기다려라. 펜티엄 III/리눅스 2.2 시스템에서 기본 구성을 컴파일하는데 약 3분 정도 걸린다. 이 시간은 하드웨어와 포함한 모듈수에 따라 크게 변한다.

설치

이제 다음 명령어로 패키지를 (위의 --prefix 옵션 참고) 지정한 설치 위치 PREFIX에 설치한다:

$ make install

업그레이드한다면 이 설치 과정이 기존 설정파일이나 문서를 덮어쓰지 않는다.

설정

다음으로 PREFIX/conf/에 있는 설정파일을 편집하여 아파치 웹서버를 설정한다.

$ vi PREFIX/conf/httpd.conf

사용가능한 설정 지시어에 대한 완전한 설명과 이 문서의 가장 최근 판은 docs/manual/이나 http://httpd.apache.org/docs-2.0/에 있는 아파치 설명서를 참고하라.

검사

이제 다음과 같이 아파치 웹서버를 시작할 수 있다:

$ PREFIX/bin/apachectl start

그리고 URL http://localhost/로 첫 문서를 요청한다. 보게될 웹페이지는 아마도 PREFIX/htdocs/일 DocumentRoot 아래에 있다. 그리고 다음 명령어로 다시 서버를 중단한다:

$ PREFIX/bin/apachectl stop


아파치 시작 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

아파치 시작

보통 아파치는 Windows NT, 2000, XP에서는 서비스로, Windows 95과 ME에서는 콘솔 프로그램으로 실행된다. 자세한 내용은 서비스로 아파치를 실행하기와 콘솔 프로그램으로 아파치를 실행하기.

유닉스에서 httpd 프로그램은 백그라운드에서 계속 요청을 처리하는 데몬으로 실행된다. 이 문서는 httpd를 시작하는 방법을 설명한다.

참고

  • 아파치 중단과 재시작
  • httpd
  • apachectl

어떻게 아파치가 시작하나

설정파일에서 Listen이 기본값인 80(혹은 1024이하의 다른 포트)이라면 이 특권 포트에 연결하기위해 root 권한이 필요하다. 서버는 시작하여 로그파일을 여는 등의 몇몇 기초적인 작업을 마친후, 클라이언트의 요청을 기다리고 응답하는 자식(child) 프로세스를 여러개 띄운다. 주 httpd 프로세스는 계속 root 사용자로 실행되지만, 자식 프로세스들은 더 권한이 작은 사용자로 실행된다. 이는 선택한 다중처리 모듈로 조정한다.

apachectl 스크립트를 사용하여 httpd 실행파일을 시작하길 권장한다. 이 스크립트는 httpd가 몇몇 운영체제에서 정상적으로 동작하기위해 필요한 환경변수들을 설정하고 httpd 실행파일을 시작한다. apachectl은 명령행 아규먼트를 그대로 넘기기때문에, httpd의 어떤 옵션이라도 apachectl에 사용가능하다. 또, apachectl 스크립트의 앞부분에 나오는 HTTPD 변수를 httpd 실행파일이 있는 위치와 항상 사용할 명령행 아규먼트로 직접 수정할 수 있다.

httpd를 실행하면 먼저 설정파일 httpd.conf를 찾아서 읽는다. 이 파일의 위치는 컴파일 중에 지정하나, 실행시 다음과 같이 -f 명령행 옵션으로 지정할 수도 있다.

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

시작하는 과정에서 문제가 없다면, 서버는 터미널에서 떨어지고 명령 프롬프트가 거의 즉시 나오게된다. 이는 서버가 실행됨을 의미한다. 브라우저로 서버에 연결하여 DocumentRoot 디렉토리에 있는 테스트 페이지와 그 페이지에 링크된 (로컬카피) 설명서를 볼 수 있다.

시작중 오류

아파치가 시작하는 과정중에 심각한 문제가 발생하면, 종료하기 전에 문제를 알리는 문구를 콘솔이나 ErrorLog에 쓴다. 가장 흔한 오류문 중 하나는 "Unable to bind to Port ..."이다. 이 메세지는 보통 다음 두 경우에 발생한다:

  • root 사용자로 로그인하지 않고 특권 포트에 서버를 시작하려 한 경우. 혹은
  • 이미 아파치나 다른 웹서버가 사용중인 포트에 서버를 시작하려 한 경우.

기타 문제해결 방법은 아파치 FAQ를 참고하라.

부팅할때 시작하기

시스템이 재시작한 후에도 서버가 계속 실행되길 바란다면, 시스템 시작파일(보통 rc.local이나 rc.N 디렉토리에 있는 파일)에 apachectl을 추가해야 한다. 이 경우 아파치는 root로 시작된다. 이전에 서버의 보안이나 접근 제한(파일권한)이 올바로 설정되었는지 확인하라.

apachectl은 표준 SysV init 스크립트와 비슷하게 동작하도록 만들어졌다. 스크립트는 아규먼트로 start, restart, stop을 받으면 각각 적절한 시그널을 httpd에 보낸다. 그래서 보통은 apachectl을 적절한 init 디렉토리로 링크를 걸면된다. 그러나 사용하는 시스템의 정확한 요구사항을 확인하라.

추가 정보

httpd와 apachectl, 기타 서버에 포함된 지원 프로그램들의 명령행 옵션은 서버와 지원 프로그램 페이지를 참고하라. 또 아파치 배포본에는 모든 모듈과 그들이 제공하는 지시어에 대한 문서가 있다.


중단과 재시작 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

중단과 재시작

이 문서는 유닉스류 시스템에서 아파치를 중단하고 재시작하는 내용을 담고있다. 윈도우즈 NT, 2000, XP 사용자는 서비스로 아파치 실행하기에서, 윈도우즈 9x와 ME 사용자는 콜솔 프로그램으로 아파치 실행하기에서 플래폼별 아파치 조작법을 알 수 있다.

참고

  • httpd
  • apachectl

소개

아파치를 중단하고 재시작하려면 실행하고 있는 httpd 프로세스에 시그널을 보내야 한다. 시그널을 보내는 방법은 두가지다. 하나는 유닉스 kill 명령어를 사용하여 프로세스에 직접 시그널을 보내는 방법이다. 시스템에 많은 httpd가 실행되지만, PidFile에 pid가 기록된 부모외에 다른 프로세스에 시그널(signal)을 보내면 안된다. 즉, 부모이외에 다른 프로세스에 시그널을 보낼 필요가 없다는 말이다. 부모에게 보낼 수 있는 시그널은 세가지로, 이제 설명할 TERM, HUP, USR1이다.

다음과 같이 부모에게 시그널을 보낸다:

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

httpd 프로세스에게 시그널을 보내는 다른 방법은 명령행 옵션 -k를 사용하는 것이다. 아래서 설명할 stop, restart, graceful은 httpd 실행파일의 아규먼트들이다. 그러나 이 아규먼트들로 httpd를 실행하는, apachectl 스크립트를 사용하길 권한다.

httpd에 시그널을 보낸후, 다음 명령어로 진행상황을 알 수 있다:

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

위 예를 당신의 ServerRoot와 PidFile 설정에 알맞게 수정하라.

당장 중단

시그널: TERM
apachectl -k stop

TERM이나 stop 시그널을 부모에게 보내면 즉시 모든 자식을 죽인다. 자식을 완전히 죽이는데는 몇 초가 걸릴 수 있다. 그런후 부모가 종료한다. 처리중인 요청은 중단되고, 더 이상 요청을 받지않는다.

점잖은 재시작

시그널: USR1
apachectl -k graceful

USR1이나 graceful 시그널을 부모에게 보내면 부모 프로세스는 자식들에게 현재 요청을 처리한후 종료하라고 (혹은 현재 아무것도 처리하지 않다면 즉시 종료하라고) 조언한다. 부모는 설정파일을 다시읽고 로그파일도 다시 연다. 자식이 죽을때마다 부모는 죽은 자식대신 새로운 설정 세대에 기초한 자식을 실행하여 즉시 요청을 처리하게 한다.

점잖은 재시작(graceful restart)으로 USR1을 사용할 수 없는 플래폼에서는 대신 (WINCH와 같은) 다른 시그널을 사용할 수 있다. apachectl graceful은 플래폼에 알맞은 시그널을 보낸다.

점잖은 재시작은 항상 MPM의 프로세스 조절 지시어 설정을 고려하여, 재시작동안 클라이언트를 서비스하는 프로세스나 쓰레드가 적당한 수를 유지하도록 설계되었다. 게다가 StartServers는, 일초 후 최소한 StartServers만큼 새로운 자식이 안만들어지면 자식이 StartServers 개가 되도록 새로 만든다. 즉, 프로그램은 서버의 현재 부하에 알맞은 자식의 개수를 유지하며, StartServers 파라미터로 지정한 당신의 기대를 존중한다.

mod_status 사용자는 USR1을 받을때 서버 통계가 0이 되지 않음을 봤을 것이다. 서버는 새로운 요청을 (운영체제는 이들을 큐에 담아서 어떤 경우에도 잃어버리지 않는다) 처리하지 못하는 시간을 최소화하고 당신의 튜닝 파라미터를 존중하도록 만들어졌다. 이를 위해 세대간 모든 자식을 기록하는 scoreboard를 유지한다.

status 모듈은 또한 점잖은 재시작 전에 시작하여 아직도 요청을 처리하고 있는 자식을 G로 알려준다.

현재로는 USR1을 사용하는 로그순환 스크립트가 재시작전에 모든 자식이 로그작성을 마쳤는지 알 수 있는 방법이 없다. 우리는 USR1 시그널을 보내고 적당한 시간이 지난후 이전 로그를 다루도록 제안한다. 예를 들어 낮은 대역폭 사용자의 경우 접속 대부분이 마치는데 10분이 안걸린다면, 이전 로그를 다루기전에 15분 기다린다.

설정파일에 오류가 있다면 재시작시 부모는 재시작하지 않고 오류를 내며 종료한다. 또, 점잖은 재시작의 경우 종료할때 자식이 실행되도록 놔둔다. (자식들은 자신의 마지막 요청을 처리하고 "점잖게 종료한다".) 이는 서버를 재시작할때 문제가 된다. 서버는 자신이 기다릴 포트에 연결하지 못한다. 재시작전에 -t 명령행 옵션(httpd 참고)으로 설정파일 문법을 검사할 수 있다. 그러나 이런 검사도 서버가 올바로 재시작할지를 보장하지 못한다. 설정파일의 문법이 아닌 의미를 검사하려면 root가 아닌 사용자로 httpd를 시작해볼 수 있다. root가 아니기때문에 (아니면 현재 그 포트를 사용하는 httpd가 실행되기때문에) 오류가 없다면 소켓과 로그파일을 열려고 시도하는 과정에서 실패할 것이다. 다른 이유때문에 실패한다면 아마도 설정파일에 오류가 있을 것이다. 점잖은 재시작을 하기전에 오류를 고쳐야한다.

당장 재시작

시그널: HUP
apachectl -k restart

HUP이나 restart 시그널을 부모에게 보내면 TERM과 같이 모든 자식을 죽이지만 부모는 종료하지 않는다. 부모는 설정파일을 다시읽고 로그파일을 다시 연다. 그리고 새로운 자식들을 만들고 서비스를 계속한다.

mod_status 사용자는 HUP를 보내면 서버 통계가 0이 됨을 알 수 있다.

설정파일에 오류가 있다면 재시작을 해도 부모는 재시작하지 않고 오류를 내며 종료할 것이다. 이를 피하는 방법은 위를 참고하라.

부록: 시그널과 레이스 컨디션

Apache 1.2b9 이전에는 재시작과 종료 시그널에 관계된 레이스 컨디션(race condition)이 있었다. (레이스 컨디션은 간단한 설명하자면, 어떤 일이 잘못된때 일어나서 기대한대로 동작하지 않는 시간에 민감한 문제다.) "올바른" 기능이 있는 아키텍쳐에서 우리는 이런 문제를 최대한 해결했다. 그러나 어떤 아키텍쳐에는 아직도 레이스 컨디션이 존재함을 주의하라.

ScoreBoardFile을 디스크에 저장하는 아키텍쳐는 scoreboard를 망가트릴 가능성이 있다. 그러면 (HUP후) "bind: Address already in use" 혹은 (USR1 후) "long lost child came home!"이 발생할 수 있다. 전자는 심각한 오류이고, 후자는 단지 서버가 scoreboard slot을 잃게 만든다. 그래서 강제 재시작을 줄이고 점잖은 재시작을 사용하길 추천한다. 이 문제는 해결하기 매우 힘들다. 그러나 다행히도 대부분의 아키텍쳐는 scoreboard로 파일을 사용하지 않는다. 파일을 사용하는 아키텍쳐라면 ScoreBoardFile 문서를 참고하라.

모든 아키텍쳐에는 지속되는 HTTP 연결 (KeepAlive)에서 두번째 이후 요청을 처리하는 자식에 약간의 레이스 컨디션이 있다. 자식은 요청줄을 읽은 후 요청 헤더를 읽기전에 종료할 수 있다. 이 문제는 너무 늦게 발견하여 1.2 버전이 나온후에야 수정되었다. 그러나 네트웍 지연이나 서버 시간제한때문에 KeepAlive 클라이언트는 이런 경우를 예상해야하기 때문에 이론상 문제는 안된다. 실제로 서버를 검사하기위해 일초에 20번 재시작하는 동안 클라이언트가 깨진 그림이나 빈 문서없이 사이트를 성공적으로 읽어들이길 기대하지 않는다면 문제가 안된다.


설정파일 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

설정파일

이 문서는 아파치 웹서버를 설정하는 파일들을 설명한다.

주설정파일

관련된 모듈 관련된 지시어
  • mod_mime
  • <IfDefine>
  • Include
  • TypesConfig

일반 문서 파일인 설정파일에 지시어를 사용하여 아파치를 설정한다. 주설정파일을 보통 httpd.conf라고 부른다. 이 파일의 위치는 컴파일시 정해지나, -f 명령행 옵션으로 지정해줄 수 있다. 또 다른 설정파일을 Include 지시어를 사용하여 포함할 수 있고, 와일드카드를 사용하여 많은 설정파일을 포함할 수도 있다. 이 경우 지시어를 어떤 설정파일에나 사용해도 된다. 주설정파일을 수정하면 아파치를 시작하거나 재시작한 이후에 반영된다.

서버는 mime 문서타입을 담은 파일도 읽는다. 파일명은 TypesConfig 지시어로 설정하고, 기본값은 mime.types이다.

설정파일 문법

아파치 설정파일은 한줄에 한 지시어를 사용한다. 줄 마지막 문자가 백슬래쉬 "\"이면 지시어가 다음 줄에서 계속됨을 뜻한다. 이 경우 백슬래쉬 뒤에 어떤 문자나 공백도 나오면 안된다.

설정파일의 지시어는 대소문자를 구별하지 않지만, 지시어의 아규먼트는 대소문자를 구별하는 경우가 있다. 해쉬문자 "#"로 시작하는 줄은 주석으로 무시한다. 주석을 설정 지시어와 같은 줄에 사용할 수 없다. 빈줄과 지시어 앞에 나오는 공백은 무시하므로, 간결하게 보이도록 지시어를 줄들임할(indent) 수 있다.

apachectl configtest나 -t 명령행 옵션을 사용하여 아파치를 실행하지 않고도 설정파일의 문법 오류를 검사할 수 있다.

모듈

관련된 모듈 관련된 지시어
  • mod_so
  • <IfModule>
  • LoadModule

아파치는 모듈화된 서버다. 이는 매우 기본적인 기능만이 서버 핵심에 포함되있음을 뜻한다. 아파치는 모듈을 읽어들여서 기능을 확장한다. 기본적으로 컴파일하면 서버에 base 모듈들이 포함된다. 서버를 동적으로 읽어들이는 모듈을 사용할 수 있게 컴파일하였다면 모듈을 따로 컴파일하여 아무때나 LoadModule 지시어로 추가할 수 있다. 그렇지 않으면 모듈을 추가하거나 빼기위해 아파치를 다시 컴파일해야 한다. 설정 지시어를 IfModule 블록으로 감싸서 특정 모듈이 있는 경우에만 선택적으로 처리할 수 있다.

현재 서버에 어떤 모듈이 컴파일되있는지 보려면 -l 명령행 옵션을 사용한다.

지시어 적용범위

관련된 모듈 관련된 지시어
  • <Directory>
  • <DirectoryMatch>
  • <Files>
  • <FilesMatch>
  • <Location>
  • <LocationMatch>
  • <VirtualHost>

주설정파일에 있는 지시어는 서버 전체에 적용된다. 지시어가 서버의 일부에만 적용되게 하려면 지시어를 <Directory>, <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, <LocationMatch> 섹션 안에 두어야한다. 이 섹션들은 그들이 감싸는 지시어의 적용범위를 파일시스템이나 URL의 특정 위치로 한정한다. 또, 서로 겹쳐서 사용할 수 있기때문에 매우 세밀한 설정이 가능하다.

아파치는 여러 다른 웹사이트를 동시에 서비스하는 능력이 있다. 이를 가상호스트라고 한다. 지시어를 <VirtualHost> 섹션 안에 두어 특정 웹사이트에만 지시어를 적용할 수 있다.

지시어는 대부분 어떤 섹션에 나와도 되지만, 어떤 지시어는 특정 장소에서 의미가 없다. 예를 들어 프로세스 생성을 조절하는 지시어는 주서버설정 장소에서만 사용할 수 있다. 지시어가 어떤 섹션에 위치할 수 있는지 알려면 지시어의 사용장소를 확인하라. 더 자세한 정보는 어떻게 Directory, Location, Files 섹션이 동작하나를 참고하라.

.htaccess 파일

관련된 모듈 관련된 지시어
  • AccessFileName
  • AllowOverride

아파치는 특별한 파일을 사용하여 설정을 나눠서(분권적으로) 관리할 수 있다. 이 특별한 파일을 보통 .htaccess라고 부르지만, 이름은 AccessFileName 지시어로 지정할 수 있다. .htaccess 파일에 있는 지시어는 파일이 있는 디렉토리와 모든 하위디렉토리에 적용된다. .htaccess 파일은 주설정파일과 같은 문법을 따른다. .htaccess 파일은 매 요청때마다 읽기때문에 파일을 수정하면 즉시 효과를 볼 수 있다.

어떤 지시어를 .htaccess 파일에 사용할 수 있는지 알려면 지시어의 사용장소를 확인하라. 서버 관리자는 주설정파일의 AllowOverride 지시어로 .htaccess 파일에 어떤 지시어를 사용할 수 있는지 조절할 수 있다.

.htaccess 파일에 대한 더 자세한 정보는 .htaccess 투토리얼을 참고하라.


섹션 설정 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

섹션 설정

설정파일에 있는 지시어는 서버 전체에 적용되거나, 특정 디렉토리, 파일, 호스트, URL에만 적용될 수 있다. 이 문서는 다른 지시어의 적용범위를 제한하기위해 설정 섹션이나 .htaccess 파일을 사용하는 방법을 설명한다.

설정 섹션의 종류

관련된 모듈 관련된 지시어
  • core
  • mod_proxy
  • <Directory>
  • <DirectoryMatch>
  • <Files>
  • <FilesMatch>
  • <IfDefine>
  • <IfModule>
  • <Location>
  • <LocationMatch>
  • <Proxy>
  • <ProxyMatch>
  • <VirtualHost>

섹션에는 두가지 종류가 있다. 대부분은 매요청마다 처리된다. 해당하는 요청에만 안에 포함한 지시어를 적용한다. 반대로, <IfDefine>과 <IfModule>은 서버가 시작할때와 꺼질때만 처리한다. 시작할때 상태가 참이면 안에 있는 지시어가 모든 요청에 적용된다. 참이 아니면 안에 있는 지시어는 무시한다.

<IfDefine> 지시어는 httpd 명령행에 적절한 파라미터가 있는 경우에만 안에 포함한 지시어를 적용한다. 다음 설정을 예로 들면, 서버를 httpd -DClosedForNow로 시작할 경우에만 모든 요청이 다른 사이트로 리다이렉션된다:

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

<IfModule> 지시어도 특정 모듈이 서버에 포함된 경우에만 안에 든 지시어를 적용한다는 점을 제외하고는 매우 비슷하다. 모듈을 서버에 정적으로 컴파일하거나 동적으로 컴파일한후 설정파일 앞에 LoadModule 줄이 있어야 한다. 이 지시어는 특정 모듈의 설치유무에 따라 설정파일이 다를 필요가 있을때만 사용해야 한다. 모듈이 없는 경우 유용한 오류문이 나오지않을 수 있기 때문에 언제나 사용하길 원하는 지시어를 안에 두면 안된다.

다음 예에서 mod_mime_magic이 있을때만 MimeMagicFiles 지시어를 처리한다.

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

<IfDefine>과 <IfModule>의 검사 앞에 "!"을 붙여 조건을 역으로 할 수 있다. 또, 여러 섹션들을 겹쳐서 사용하여 더 복잡한 효과를 얻을 수 있다.

파일시스템과 웹공간

가장 자주 사용되는 설정 섹션은 파일시스템과 웹공간(webspace)의 특정 장소에 대한 설정을 변경하는 것들이다. 먼저 이 둘의 차이를 이해하는 것이 중요하다. 파일시스템은 운영체제 입장에서 디스크를 보는 관점이다. 예를 들어, 기본값으로 아파치를 설치를 하면 유닉스 파일시스템의 경우 /usr/local/apache2, 윈도우즈 파일시스템의 경우 "c:/Program Files/Apache Group/Apache2"에 설치된다. (아파치는 윈도우즈에서 조차 항상, 역슬래쉬가 아닌, 슬래쉬를 사용함을 주의하라.) 반대로 웹공간은 웹서버가 제공하고 클라이언트가 보게될 사이트의 관점이다. 그래서 유닉스에서 기본 아파치 설치를 한 경우 웹경로의 경로 /dir/은 파일시스템 경로 /usr/local/apache2/htdocs/dir/에 해당한다. 웹공간은 데이타베이스 등에서 동적으로 생성될 수 있기때문에 반드시 파일시스템에 직접 대응될 필요는 없다.

파일시스템 섹션

<Directory>와 <Files> 지시어와 정규표현식을 사용하는 지시어는 파일시스템의 특정 부분에 지시어를 적용한다. <Directory> 지시어에 포함된 지시어들은 지정한 파일시스템 디렉토리와 그 하위 디렉토리에 적용된다. .htaccess 파일을 사용해도 결과는 같다. 다음 설정을 예로 들면, 디렉토리 목록(index)이 /var/web/dir1 이하 디렉토리에서 디렉토리 목록(index)이 가능하다.

<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가 제공하는 아파치 내부 핸들러로 대응시키는지를 보여준다. 파일시스템에 server-status라는 파일은 필요없다.

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

와일드카드와 정규표현식

<Directory>, <Files>, <Location> 지시어에서 C 표준 파이브러리의 fnmatch와 같은 쉘에서 사용하는 와일드카드 문자를 사용할 수 있다. "*" 문자는 어떤 문자열이라도 나타내고, "?" 문자는 어떤 문자 한개를 나타내며, "[seq]"는 seq 중에 한 문자를 나타낸다. 어떤 와일드카드도 "/" 문자를 나타내지는 못한다. 그래서 이 문자는 직접 사용해야 한다.

더 유연한 설정이 필요하면 perl호환 정규표현식을 사용하는 <DirectoryMatch>, <FilesMatch>, <LocationMatch>를 사용할 수 있다. 그러나 아래 설정의 결합에 관한 절에서 정규표현식 섹션을 사용하면 지시어가 적용되는 방법이 어떻게 변하는지 살펴봐라.

모든 사용자 디렉토리 설정을 변경하는 비정규표현식 와일드카드 섹션은 다음과 같다:

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

정규표현식 섹션을 사용하여 한번에 여러 종류의 그림파일에 대한 접근을 거부할 수 있다:

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

안에 어떤 지시어를 사용할 수 있나?

어떤 설정 섹션안에 사용할 수 있는 지시어를 알려면 지시어의 사용장소를 확인하라. <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>를 제외하고 각 섹션들을 설정파일에 나온 순서대로 처리된다. (위의 순서 1) <Directory>는 디렉토리 내용이 가장 짧은 것에서 긴쪽으로 처리된다. 그래서 예를 들어, <Directory /var/web/dir>을 <Directory /var/web/dir/subdir> 이전에 처리한다. 같은 디렉토리를 지칭하는 여러 <Directory> 섹션이 있다면 이들을 설정파일 순서대로 처리한다. Include 지시어로 포함한 설정은 Include 지시어 위치에 포함한 파일 내용이 있는 것처럼 처리한다.

<VirtualHost> 섹션 안에 포함된 섹션은 가상호스트 정의 밖에 있는 해당 섹션 이후에 적용된다. 그래서 가상호스트 안에서 주서버의 설정사항을 수정할 수 있다.

다음에 나오는 섹션은 이전 섹션의 결과를 수정한다.

기술적 주의

실제로 <Location>/<LocationMatch>는 (Aliases와 DocumentRoot를 사용하여 URL을 파일명으로 변환하는) 이름번역 단계 이전에 처리된다. 변역이 끝난 이후에는 완전히 무시한다.

예제

다음은 겹합하는 순서를 설명하는 예다. 이들 모두 요청에 적용된다고 가정하면 지시어는 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>

더 현실적인 예는 다음과 같다. <Location> 섹션을 나중에 처리하므로 <Directory> 섹션에 있는 접근제한과 관계없이 서버에 무제한 접근을 가능하다. 즉, 결합하는 순서는 중요하므로 주의하라!

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

# 악! 이 <Directory> 섹션은 아무런 효과가 없다
<Directory />
Order allow,deny
Allow from all
Deny from badguy.example.com
</Directory>


서버 전역 설정 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

서버 전역 설정

이 문서는 core 서버가 서버의 기본 행동을 설정하기위해 제공하는 지시어중 일부를 설명한다.

서버 식별

관련된 모듈 관련된 지시어
  • ServerName
  • ServerAdmin
  • ServerSignature
  • ServerTokens
  • UseCanonicalName

ServerAdmin과 ServerTokens 지시어는 오류문 등 서버가 생성하는 문서에 나올 서버에 대한 정보를 설정한다. ServerTokens 지시어는 서버 HTTP 응답 헤더를 설정한다.

서버는 ServerName과 UseCanonicalName 지시어를 사용하여 자기참조 URL을 만든다. 예를 들어, 클라이언트가 디렉토리를 요청했지만 디렉토리명 뒤에 슬래쉬를 붙이지않은 경우 아파치는 뒤에 슬래쉬를 붙인 전체 이름을 클라이언트에게 리다이렉트하여, 클라이언트가 문서의 상대참조를 올바로 찾게 한다.

파일 위치

관련된 모듈 관련된 지시어
  • CoreDumpDirectory
  • DocumentRoot
  • ErrorLog
  • LockFile
  • PidFile
  • ScoreBoardFile
  • ServerRoot

이 지시어들은 아파치가 정상적으로 동작하기위해 필요한 여러 파일들의 위치를 설정한다. 경로명이 슬래쉬(/)로 시작하지 않으면, ServerRoot에 상대적인 파일을 찾는다. root가 아닌 사용자에게 쓰기권한이 있는 경로에 파일을 두지않도록 조심해라. 더 자세한 정보는 보안 팁 문서를 참고하라.

자원사용 제한

관련된 모듈 관련된 지시어
  • LimitRequestBody
  • LimitRequestFields
  • LimitRequestFieldsize
  • LimitRequestLine
  • RLimitCPU
  • RLimitMEM
  • RLimitNPROC
  • ThreadStackSize

LimitRequest* 지시어는 아파치가 클라이언트의 요청을 읽을 때 사용할 자원량을 제한한다. 이런 값들을 제한하여 서비스거부(denial of service)류 공격을 줄일 수 있다.

RLimit* 지시어는 아파치 자식이 생성하는 프로세스가 사용할 자원량을 제한한다. 특히 CGI 스크립트나 SSI exec 명령어가 사용할 자원을 제한한다.

ThreadStackSize 지시어는 스택 크기를 조절하기위해 Netware에서만 사용한다.


로그파일 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

로그파일

효율적으로 웹서버를 관리하려면 발생하는 문제와 함께 서버의 활동과 성능에 대해 알아야 한다. 아파치 웹서버는 매우 종합적이고 유연한 로그 기능을 제공한다. 이 문서는 로그 기능을 설정하는 방법과 로그에 들어갈 내용을 설명한다.

보안 경고

누군가에게 아파치의 로그파일이 있는 디렉토리에 쓰기권한이 있다면 (보통 root) 서버를 실행하는 uid를 거의 확실히 얻을 수 있다. 이를 고려하지않고 로그가 저장된 디렉토리에 쓰기권한을 주지 마라. 자세한 내용은 보안 팁 문서를 참고하라.

또, 클라이언트가 제공한 정보는 로그파일에 거의 그대로 기록된다. 그래서 악의가 있는 클라이언트가 로그파일에 제어문자를 넣을 수 있으므로, 로그를 다룰때는 주의해야 한다.

오류 로그 (Error Log)

관련된 모듈 관련된 지시어
  • ErrorLog
  • LogLevel

ErrorLog 지시어는 가장 중요한 로그파일인 서버 오류 로그의 이름과 위치를 지정한다. 아파치 웹서버는 이 파일에 진단정보와 요청을 처리하는 도중 발생한 오류를 기록한다. 서버가 시작하거나 동작하는데 문제가 있다면 무엇이 잘못되었고 때때로 어떻게 고치는지를 알려주는 이곳을 가장 먼저 살펴봐야 한다.

오류 로그는 보통 (전형적으로 유닉스 시스템에서는 error_log, 윈도우즈와 OS/2에서는 error.log) 파일에 기록된다. 유닉스 시스템에서 서버는 오류를 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인 접근 로그 항목이 생긴다. 접근 로그는 사용자정의할 수 있으므로 이 파일을 참고하여 오류 상황에 대한 추가정보를 얻을 수 있다.

검사할때 어떤 문제가 생기는지 오류 로그를 계속 살펴보는 것이 좋다. 유닉스 시스템에서 다음과 같이 한다:

tail -f error_log

접근 로그 (Access Log)

관련된 모듈 관련된 지시어
  • mod_log_config
  • mod_setenvif
  • CustomLog
  • LogFormat
  • SetEnvIf

서버 접근 로그는 서버가 처리하는 모든 요청을 기록한다. CustomLog 지시어는 접근 로그의 위치와 내용을 지정한다. LogFormat 지시어를 사용하여 로그에 포함할 내용을 쉽게 선택할 수 있다. 이 절은 서버가 접근 로그에 쓸 내용을 설정하는 방법을 설명한다.

물론 접근 로그에 정보를 기록하는 것은 로그 관리의 시작일 뿐이다. 다음 단계는 이 정보를 분석하여 유용한 통계를 만드는 것이다. 이 문서는 일반적인 로그 분석에 대해서 다루지 않으며, 로그 분석은 실제 웹서버가 할 일이 아니다. 로그 분석에 대한 정보와 로그를 분석하는 소프트웨어에 대해서는 Open Directory나 Yahoo를 참고하라.

아파치 웹서버는 이전부터 mod_log_referer, mod_log_agent, CustomLog 같은 모듈과 지시어를 사용하여 접근 로그를 다루었다. 지금은 CustomLog 지시어가 오래된 지시어들의 모든 기능을 이어받았다.

접근 로그의 형식은 매우 사용자정의 가능하다. 형식은 C의 printf(1) 형식문자열과 매우 유사한 형식문자열을 사용하여 지정한다. 다음 절에 예를 들었다. 형식문자열에 사용가능한 모든 내용을 알려면 mod_log_config 형식문자열을 참고하라.

Common 로그 형식

접근 로그의 전형적인 설정은 다음과 같다.

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 신원이다. 이 정보는 매우 믿을 수 없기때문에, 긴밀히 관리되는 내부 네트웍이 아니라면 절대로 이 정보를 사용하면 안된다. IdentityCheck가 On이 아니라면 아파치 웹서버는 이 정보를 알아보려고 시도하지도 않는다.
frank (%u)
이는 HTTP 인증으로 알아낸 문서를 요청한 사용자의 userid이다. 보통 이 값은 CGI 스크립트에게 REMOTE_USER 환경변수로 넘겨진다. 요청의 상태코드가 401이라면 (아래 참고) 사용자가 아직 인증을 거치지 않았으므로 이 값을 믿으면 안된다. 문서를 암호로 보호하지 않는다면 이 항목은 이전 항목과 같이 "-"이다.
[10/Oct/2000:13:55:36 -0700] (%t)
서버가 요청처리를 마친 시간. 형식은:

[day/month/year:hour:minute:second zone]
day = 숫자 2개
month = 숫자 3개
year = 숫자 4개
hour = 숫자 2개
minute = 숫자 2개
second = 숫자 2개
zone = (`+' | `-') 숫자 4개

로그 형식문자열에 %{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로 시작하는 코드) 요청이 성공하였는지, (4로 시작하는 코드) 클라이언트에 오류가 있는지, (5로 시작하는 코드) 서버에 오류가 있는지 알려주므로 매우 중요하다. 상태코드의 전체 목록은 HTTP 규약 (RFC2616 section 10)에서 찾을 수 있다.
2326 (%b)
마지막 항목은 응답 헤더를 제외하고 클라이언트에게 보내는 내용의 크기를 나타낸다. 클라이언트에게 보내는 내용이 없다면 이 값은 "-"이다. 내용이 없는 경우 "0"을 로그하려면 대신 %B를 사용한다.

Combined 로그 형식

자주 사용되는 다른 형식문자열은 결합된로그형식(Combined Log Format)이다. 다음과 같이 사용한다.

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

이 형식은 두 항목을 더 추가한 것을 제외하고는 Common 로그 형식과 완전히 같다. 추가된 항목들은 퍼센트 지시어 %{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=을 사용하여 환경변수 유무에 따라 요청을 집어넣거나 뺀다. 예를 들면:

# loop-back 인터페이스에서 요청을 표시한다
SetEnvIf Remote_Addr "127\.0\.0\.1" dontlog
# robots.txt 파일에 대한 요청을 표시한다
SetEnvIf Request_URI "^/robots\.txt$" dontlog
# 나머지를 로그에 남긴다
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

조건부 로그는 매우 강력하고 유연하지만, 이것이 로그 내용을 조절하는 유일한 방법은 아니다. 로그파일은 서버의 모든 행동을 기록할때 더 유용하다. 나중에 원하지않는 요청을 제외하고 로그파일을 분석하는 것이 더 쉽다.

로그 순환 (Log Rotation)

조금 바쁜 서버조차도 로그파일에 저장되는 정보량은 매우 많다. 접속 로그는 보통 만번 요청당 1MB 이상 증가한다. 결과적으로 기존의 로그를 옮기거나 지우는 방법으로 로그를 주기적으로 순활할 필요가 있다. 아파치는 파일을 열고있는 동안에는 계속 이전 로그파일에 쓰기때문에 서버가 실행중일때 로그를 순환할 수 없다. 대신 로그파일을 옮기거나 지운후 서버를 재시작하여, 로그파일을 새로 열어야 한다.

점잖은 재시작을 사용하면 서버는 클라이언트와 기존의 혹은 대기된 연결을 잃지않고 새 로그파일을 열 수 있다. 그러나 이를 위해 서버는 오래된 요청의 서비스를 끝내는 동안 이전 로그파일을 계속 사용해야 한다. 그러므로 재시작한후 로그파일을 처리하기 전에 얼마간 기다릴 필요가 있다. 일반적으로 다음과 같이 로그를 순환하고, 디스크공간을 절약하기위해 이전 로그를 압축한다:

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

로그를 순환하는 다른 방법은 다음 절에서 설명할 파이프 로그를 사용하는 것이다.

로그를 파이프로 보내기

아파치 웹서버는 오류 로그와 접근 로그를 파일에 직접 쓰지않고 파이프를 통해 다른 프로세스로 보낼 수 있다. 이 기능을 사용하면 서버에 코드를 추가하지않고도 매우 유연하게 로그를 처리할 수 있다. 로그를 파이프에 쓰기위해 파일명 자리에 파이프문자 "|"와 뒤에 표준입력으로 로그 항목을 읽을 실행파일명을 적으면 된다. 아파치는 서버가 시작할때 파이프로 연결할 로그 프로세스를 시작하고, 서버가 실행되는 동안 프로세스가 죽으면 다시 시작한다. (이 마지막 기능때문에 우리는 이 방법을 "믿을 수 있는 파이프 로그"라고 부른다.)

파이프로 연결된 로그 프로세스는 부모 아파치 httpd 프로세스가 띄우고, 프로세스의 userid도 같다. 즉, 파이프로 연결된 로그 프로그램은 보통 root로 실행된다. 그러므로 프로그램을 간단하고 안전하게 만드는 것이 매우 중요하다.

파이프로 부르는 전체 명령어를 따옴표로 묶음을 명심하라. 이 예는 접근 로그에 대한 것이지만, 오류 로그도 마찬가지다.

서버를 재시작하지않고 로그를 순환할 수 있는 것이 파이프 로그를 사용하는 중요한 이유다. 아파치 웹서버는 이를 위해 rotatelogs라는 간단한 프로그램을 포함한다. 예를 들어 24시간마다 로그를 순환한다면:

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

다른 사이트에 cronolog라는 비슷하지만 훨씬 더 유연한 로그 순환 프로그램이 있다.

조건부 로그와 같이 파이프 로그는 매우 강력한 도구지만, 나중에 처리하는 등의 더 간단한 방법이 가능한 경우 사용해서는 안된다.

가상호스트

많은 가상호스트가 있는 서버를 운영할때 여러가지 방법으로 로그파일을 다룰 수 있다. 먼저, 호스트가 한개인 서버와 같이 로그를 사용할 수 있다. <VirtualHost> 섹션이 아닌 주서버 설정에 로그 지시어를 두면 모든 요청이 같은 접근 로그와 오류 로그로 기록된다. 이 방법은 가상호스트별로 쉽게 통계처리를 할 수 없다.

<VirtualHost> 섹션 안에 CustomLog나 ErrorLog 지시어를 사용하면 해당 가상호스트에 대한 요청과 오류만이 지정된 파일에 기록된다. 로그 지시어가 없는 다른 가상호스트는 계속 주서버 로그에 로그를 기록한다. 이 방법은 가상호스트 개수가 적을 경우 매우 유용하지만, 호스트 수가 많다면 관리하기 힘들어진다. 또, 파일기술자가 부족한 문제가 자주 발생한다.

접근 로그의 경우 매우 좋은 해결책이 있다. 로그 형식문자열에 가상호스트에 대한 정보를 추가하면 모든 호스트가 같은 로그를 사용하고, 나중에 로그를 가상호스트별로 나눌 수 있다. 예를 들어, 다음 지시어를 봐라.

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

%v는 요청을 서비스하는 가상호스트 이름을 기록한다. 나중에 split-logfile 같은 프로그램으로 접근 로그를 가상호스별로 나눌 수 있다.

다른 로그파일

관련된 모듈 관련된 지시어
  • mod_cgi
  • mod_rewrite
  • PidFile
  • RewriteLog
  • RewriteLogLevel
  • ScriptLog
  • ScriptLogBuffer
  • ScriptLogLength

PID 파일

아파치 웹서버는 시작할때 logs/httpd.pid 파일에 부모 httpd 프로세스의 process id를 저장한다. 이 파일명은 PidFile 지시어로 변경할 수 있다. process-id는 관리자가 부모 프로세스에 시그널을 보내 서버를 재시작하거나 죽일때 사용한다. 윈도우즈에서는 대신 -k 명령행옵션을 사용한다. 더 자세한 정보는 중단과 재시작 페이지를 참고하라.

스크립트 로그

디버깅을 돕기위해 ScriptLog 지시어를 사용하여 CGI 스크립트의 입력과 출력을 기록할 수 있다. 이 지시어는 오직 테스트용으로만 사용해야 한다. 실제 사용하는 서버에서 사용하면 안된다. 더 자세한 정보는 mod_cgi 문서를 참고하라.

재작성 로그

mod_rewrite의 강력하고 복잡한 기능을 사용한다면 디버깅을 위해 거의 항상 RewriteLog를 사용할 필요가 있다. 이 로그파일은 재작성 엔진이 어떻게 요청을 변환하는지에 대해 자세히 알려준다. 자세한 정도는 RewriteLogLevel 지시어로 조절한다.


URL을 파일시스템 위치로 대응하기 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

URL을 파일시스템 위치로 대응하기

이 문서는 요청의 URL을 가지고 아파치가 어떻게 서비스할 파일의 파일시스템상 위치를 찾는지 설명한다.

관련된 모듈과 지시어들

관련된 모듈 관련된 지시어
  • mod_alias
  • mod_proxy
  • mod_rewrite
  • mod_userdir
  • mod_speling
  • mod_vhost_alias
  • Alias
  • AliasMatch
  • CheckSpelling
  • DocumentRoot
  • ErrorDocument
  • Options
  • ProxyPass
  • ProxyPassReverse
  • Redirect
  • RedirectMatch
  • RewriteCond
  • RewriteMatch
  • ScriptAlias
  • ScriptAliasMatch
  • UserDir

DocumentRoot

요청을 받은 아파치는 어떤 파일을 서비스할지 결정하기위해 기본적으로 요청의 URL-경로(URL에서 호스트명과 포트 뒤에 나오는 부분)를 설정파일에서 지정한 DocumentRoot 뒤에 붙인다. 그래서 DocumentRoot 아래있는 파일과 디렉토리들은 웹에서 보게될 기본적인 내용이다.

DocumentRoot 밖에 있는 파일들

종종 파일시스템에서 DocumentRoot 아래 있지않은 부분을 웹에서 접근할 필요가 있다. 아파치는 이 경우 여러가지 방법을 사용할 수 있다. 유닉스 시스템에서 심볼링크를 사용하여 파일시스템의 다른 부분을 DocumentRoot 아래에 둘 수 있다. 보안을 위해 아파치는 해당 디렉토리의 Options 설정에 FollowSymLinks나 SymLinksIfOwnerMatch가 있는 경우에만 심볼링크를 따라간다.

또, Alias 지시어는 파일시스템의 특정 부분을 웹공간에 대응한다. 예를 들어 다음과 같다면

Alias /docs /var/web

URL http://www.example.com/docs/dir/file.html은 /var/web/dir/file.html을 가지고 서비스한다. 지정한 경로에 있는 모든 내용을 CGI 스크립트로 취급하는 것을 제외하고는 ScriptAlias 지시어도 같은 일을 한다.

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 스크립트로 취급한다.

사용자 디렉토리

유닉스 시스템은 전통적으로 특정 사용자 user의 홈디렉토리를 ~user/로 지칭한다. mod_userdir 모듈은 이 개념을 웹에까지 확장하여, 다음과 같은 URL을 가지고 각 사용자 홈디렉토리 안에 있는 파일을 서비스한다.

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

보안상 웹에서 사용자 홈디렉토리로 직접 접근할 수 있으면 안된다. 그래서 UserDir 지시어는 사용자 홈디렉토리에서 웹용 파일들이 있을 디렉토리를 지정한다. 기본 설정 Userdir public_html을 사용하고 /home/user/가 /etc/passwd에 지정된 사용자 홈디렉토리라면, 위의 URL은 파일 /home/user/public_html/file.html에 대응한다.

또, Userdir 지시어는 /etc/passwd에 홈디렉토리의 위치가 저장되지않는 시스템을 위해 여러 다른 형태를 사용할 수 있다.

어떤 사람은 (보통 웹에서 %7e로 인코딩되는) "~" 기호가 이상하여 다른 방식으로 사용자 디렉토리를 나타내고 싶어한다. 이 기능은 mod_userdir이 제공하지않는다. 그러나 사용자 홈디렉토리가 규칙적인 방법으로 구성되있다면, AliasMatch 지시어를 사용하여 원하는 효과를 얻을 수 있다. 예를 들어, 다음의 AliasMatch 지시어를 사용하면 http://www.example.com/upages/user/file.html이 /home/user/public_html/file.html에 대응한다:

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

URL 리다이렉션(Redirection)

앞에서 설명한 설정 지시어들은 아파치가 파일시스템의 특정 장소에 있는 내용을 클라이언트에게 보내게 만든다. 그러나 때때로 요청한 내용이 다른 URL에 있다고 클라이언트에게 알려주어, 클라이언트가 새로 그 URL을 요청하도록 만드는 것이 좋을 때가 있다. 이를 리다이렉션(redirection)이라고 하며, Redirect 지시어를 사용한다. 예를 들어, DocumentRoot 아래 /foo/ 디렉토리의 내용을 새로 /bar/ 디렉토리로 옮겼다면 다음과 같이 클라이언트가 새로운 위치를 요청하도록 한다:

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

그러면 www.example.com 서버의 /foo/로 시작하는 URL-경로는 /foo/를 /bar/로 바꾼 URL로 리다이렉션된다. 클라이언트를 원래 서버외에 어떤 다른 서버로도 리다이렉션할 수 있다.

또, 아파치는 더 복잡한 재작성 문제를 위해 RedirectMatch 지시어를 제공한다. 예를 들어, 다른 요청은 그대로 두고 사이트 홈페이지에 대한 요청만을 다른 사이트로 리다이렉션하려면:

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

임시로 사이트의 모든 페이지를 다른 사이트의 특정 페이지로 리다이렉션하려면:

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

역프록시(Reverse Proxy)

아파치는 다른 서버에 있는 문서를 서버의 URL 공간으로 가져올 수 있다. 이 경우 웹서버가 원격 서버에서 문서를 가져와서 클라이언트에게 전달하는 프록시 서버와 같이 동작하기때문에 이런 방법을 역프록시(reverse proxying)라고 한다. 클라이언트의 입장에서 역프록시 서버가 문서를 보내주는 것처럼 보이므로 일반 프록시와는 다르다.

아래 설정에서 클라이언트가 /foo/에 있는 문서를 요청하면, 서버는 internal.example.com의 /bar/ 디렉토리에서 문서를 가져와서 문서가 마치 서버에 있었던 것처럼 클라이언트에게 보낸다.

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

ProxyPass는 서버가 적절한 문서를 가져오도록 설정하며, ProxyPassReverse 지시어는 internal.example.com이 보내는 리다이렉션을 재작성하여 리다이렉션이 현재 서버의 적절한 디렉토리를 가리키도록 한다. 그러나 문서 안에 있는 링크는 재작성하지 않음을 주의하라. internal.example.com에 대한 절대링크는 클라이언트가 프록시서버가 아니라 internal.example.com으로 직접 요청하게 한다.

재작성 엔진 (Rewriting Engine)

더 강력한 치환이 필요할때 mod_rewrite의 재작성 엔진이 도움이 된다. 이 모듈의 지시어는 브라우저 종류나 클라이언트의 IP 주소 등 요청의 특징을 가지고 어디에 있는 내용을 서비스할지 결정할 수 있다. 또, mod_rewrite는 요청을 어떻게 처리할지 결정하기위해 외부 데이터베이스 파일이나 프로그램을 사용할 수 있다. 재작성 엔진은 위에서 다룬 세 종류 대응, 즉, 내부 리다이렉션 (alias), 외부 리다이렉션, 프록시, 모두를 지원한다. mod_rewrite를 사용하는 실제 예는 URL 제작성 지침서에서 설명한다.

File Not Found

결국 요청한 URL에 대응하는 파일을 파일시스템에서 찾지 못한 경우이다. 여러 가지 이유가 있다. 어떤 경우 문서를 다른 곳으로 옮겼기 때문일 수 있다. 이 경우 클라이언트에게 URL 리다이렉션으로 자원의 새로운 위치를 알려주는 방법이 제일 좋다. 그러면 자원을 옮겨도 오래된 북마크나 링크가 계속 유효하다.

"File Not Found" 오류의 다른 일반적인 원인은 브라우저에 직접 혹은 HTML 링크에 URL이 잘못 입력된 경우이다. 아파치는 mod_speling (맞춤법이 틀리지 않았음) 모듈로 이와 같은 문제를 돕는다. 이 모듈을 사용하면 "File Not Found" 오류가 발생하는 경우 비슷한 파일명을 가진 자원을 찾는다. 만약 발견하면 mod_speling은 클라이언트를 올바른 위치로 HTTP 리다이렉션한다. "비슷한" 파일이 여러개 있다면 클라이언트에게 목록을 보낸다.

mod_speling의 특히 유용한 장점은 대소문자를 구별하지않고 파일명을 비교하는 기능이다. 그래서 유닉스 파일시스템과 URL의 대소문자 성질을 알지못하는 사용자가 있는 시스템에 도움이 된다. 그러나 mod_speling이 자주 URL을 고쳐야한다면, "잘못된" 요청때마다 URL 리다이렉션과 클라이언트의 새로운 요청이 일어나므로 서버에 부담이 된다.

찾는 시도가 모두 실패하면 아파치는 HTTP status code 404 (file not found) 오류페이지를 보낸다. 이 페이지의 내용은 ErrorDocument 지시어로 조절하며, 사용자정의 오류 응답과 다국어 서버 오류문 문서를 참고하여 사용자정의할 수 있다.


Security Tips - Apache HTTP Server

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

Security Tips

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

Keep up to Date

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

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

Permissions on ServerRoot Directories

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

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

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

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

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

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

Server Side Includes

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

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

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

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

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

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

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

CGI in General

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

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

Non Script Aliased CGI

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

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

Script Aliased CGI

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

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

Other sources of dynamic content

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

Protecting System Settings

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

In the server configuration file, put

<Directory />
AllowOverride None
</Directory>

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

Protect Server Files by Default

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

For instance, consider the following example:

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

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

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

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

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

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

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

UserDir disabled root

Watching Your Logs

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

A couple of examples:

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

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

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

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

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

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

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


동적공유객체 (DSO) 지원 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

동적공유객체 (DSO) 지원

아파치 웹서버는 관리자가 모듈들을 선택하여 서버에 포함할 기능을 결정할 수 있는 모듈화된 프로그램이다. 서버를 컴파할때 httpd 실행파일에 정적으로 모듈을 컴파일할 수 있다. 아니면 모듈을 httpd 실행파일과 분리하여 동적공유객체(Dynamic Shared Objects, DSO)로 컴파일할 수 있다. DSO 모듈은 서버를 컴파일할때 컴파일하거나, Apache Extension Tool (apxs)을 사용하여 나중에 컴파일하여 추가할 수 있다.

이 문서는 DSO 모듈 사용법과 배경 이론을 설명한다.

구현

관련된 모듈 관련된 지시어
  • mod_so
  • LoadModule

아파치 핵심에 정적으로 컴파일해야할 mod_so.c라는 모듈은 아파치 모듈을 읽어들이기위한 DSO를 지원한다. 이 모듈은 core를 제외하고 DSO가 될 수 없는 유일한 모듈이다. 실제로 다른 모든 아파치 모듈은 설치 문서에서 설명한 configure의 --enable-module=shared 옵션을 사용하여 DSO로 컴파일할 수 있다. 모듈을 mod_foo.so와 같이 DSO로 컴파일한후 httpd.conf 파일에 mod_so의 LoadModule 명령어를 사용하여 서버 시작시 혹은 재시작시 그 모듈을 읽어들일 수 있다.

아파치 모듈(특히 제삼자가 만든 모듈)로 사용할 DSO 파일을 쉽게 만들기위해 apxs (APache eXtenSion)라는 새로운 지원 프로그램이 있다. 이 프로그램은 아파치 소스 트리 밖에서 DSO로 사용할 모듈을 컴파일할때 사용한다. 개념은 쉽다. 아파치를 설치할때 configure와 make install이 아파치 C 헤더파일을 설치하고, DSO 파일을 컴파일하기위한 플래폼 특유의 컴파일러 옵션과 링커 옵션을 apxs 프로그램에 기록한다. 그래서 apxs를 사용하는 사용자는 아파치 배포본 소스 트리없이, 또 DSO 지원을 위한 플래폼 특유의 컴파일러 옵션와 링커 옵션에 신경을 쓰지않고 자신의 아파치 모듈 소스를 컴파일할 수 있다.

사용법 요약

Apache 2.0의 DSO 기능에 대한 짧고 간략한 요약이다:

  1. 배포본에 있는 아파치 모듈을 컴파일하고 설치하는 경우. 예를 들어 mod_foo.c를 DSO mod_foo.so로:

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

  2. 제삼자가 만든 아파치 모듈을 컴파일하고 설치하는 경우. 예를 들어 mod_foo.c를 DSO mod_foo.so로:

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

  3. 공유 모듈을 나중에 사용하기위해 아파치를 구성하는 경우:

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

  4. 제삼자가 만든 아파치 모듈을 컴파일하고 설치하는 경우. apxs를 사용하여 아파치 소스 트리 밖에서 mod_foo.c를 DSO mod_foo.so로:

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

모든 경우 일단 공유 모듈이 컴파일되면, httpd.conf에 LoadModule 지시어를 사용하여 아파치가 그 모듈을 읽어들이게 만든다.

배경지식

현대적인 유닉스류에는 동적공유객체 (DSO)의 동적 링킹/로딩(dynamic linking/loading)이라고 하여, 특별한 형식의 실행코드 조각을 만들어 실행중인 실행프로그램의 주소공간에 읽어들이는 멋진 기능이 있다.

보통 두가지 방법으로 읽어들일 수 있다. 하나는 실행프로그램이 시작할때 ld.so라는 시스템 프로그램이 자동으로 읽어들이는 경우고, 다른 하나는 실행중인 프로그램이 dlopen()/dlsym() 시스템호출로 유닉스 로더(loader)의 시스템 인터페이스을 사용하여 직접 읽어들이는 경우다.

첫번째 경우 DSO를 보통 공유라이브러리(shared libraries) 혹은 DSO 라이브러리라고 부르며, 파일은 libfoo.so나 libfoo.so.1.2 같은 이름을 가진다. 이들은 시스템 디렉토리(보통 /usr/lib)에 있고, 컴파일시 링커 명령어에 -lfoo를 주어 실행파일과 연결한다. 이렇게 직접 써준 라이브러리는 실행파일에 참조되여서, 프로그램이 시작할때 링커 옵션 -R로 직접 지정한 경로, 환경변수 LD_LIBRARY_PATH로 지정한 경로 혹은 /usr/lib에서 유닉스 로더가 libfoo.so를 찾을 수 있다. 그러면 실행프로그램의 (아직 못찾은(unresolved)) 심볼(symbol)을 DSO에서 찾게된다.

DSO는 보통 실행프로그램의 심볼을 찾지않기 때문에 (DSO가 재사용가능한 일반적인 코드 라이브러리이므로) 찾기는 여기서 끝난다. 유닉스 로더가 심볼 찾기를 완전히 담당하므로 실행프로그램이 직접 DSO에서 심볼을 찾을 필요가 없다. (사실 ld.so를 부르는 코드는 정적이 아닌 모든 실행프로그램에 링크되는 실행시 시작코드의 일부다.) 공통된 라이브러리 코드를 동적으로 읽어들이는 장점은 명확하다. 라이브러리 코드가 모든 프로그램에 중복해서 저장되는 대신 libc.so와 같은 시스템 라이브러리에 한번만 저장되기 때문에 디스크 공간이 절약된다.

두번째 경우 DSO를 보통 공유객체(shared objects) 혹은 DSO 파일이라고 부르고, (규칙상 이름은 foo.so이지만) 파일의 확장자는 자유롭다. 이 파일들은 보통 프로그램 자체 디렉토리에 위치하고 실행프로그램에 자동으로 연결되지 않는다. 대신 실행프로그램은 실행시 dlopen()을 사용하여 DSO를 주소공간에 직접 읽어들여야 한다. 이때 실행프로그램은 DSO에서 심볼을 찾지 않는다. 대신 앞에서 본 유닉스 로더는 자동으로 실행파일과 실행파일이 이미 읽어들인 DSO 라이브러리(특히 항상 존재하는 libc.so의 모든 심볼)에서 DSO의 (아직 못찾은) 심볼을 찾는다. 그래서 DSO는 마치 처음부터 실행프로그램에 정적으로 링크된것과 같이 실행파일의 심볼을 알게된다.

DSO의 API를 이용하기위해서 마지막으로 실행프로그램은 dlsym()으로 DSO에서 특정 심볼을 찾아서, 앞으로 사용하기위해 디스패치(dispatch) 표 등에 저장한다. 다른 말로 실행프로그램은 사용할 모든 실볼을 직접 찾아야한다. 이런 구조의 장점은 프로그램의 일부를 프로그램이 필요할때까지 읽어들이지 않아도 (그래서 메모리를 낭비하지 않게) 된다는 점이다. 기본 프로그램의 기능을 확장하기위해 필요한 경우 이 부분을 동적으로 읽어들일 수 있다.

이런 DSO 구조가 자연스럽게 보이지만, 최소한 어려운 점이 한가지있다. 프로그램을 확장하기위해 DSO를 사용할때 DSO가 실행프로그램의 심볼을 찾는 일이다. 왜? DSO가 실행프로그램의 심볼을 "역으로 찾는 것"은 (라이브러리는 자신을 사용하는 프로그램에 대해 모른다는) 라이브러리 설계에 반하며, 모든 플래폼에서 지원되지않고 표준화되지도 않았기 때문이다. 실제로 실행파일의 전역심볼(global symbol)은 보통 익스포트(export)되지 않기때문에 DSO가 사용할 수 없다. DSO를 사용하여 실행중 프로그램을 확장하려면 링커에게 모든 전역심볼을 익스포트하도록 강제하는 것이 주된 해결책이다.

공유라이브러리는 DSO 방식의 설계원칙대로 전형적이기때문에 운영체제가 제공하는 거의 모든 종류의 라이브러리가 사용한다. 반대로 많은 프로그램은 프로그램을 확장하기위해 공유객체를 사용하지 않는다.

1998년 실행중 실제로 기능을 확장하기위해 DSO 구조를 사용한 소프트웨어 패키지는 (XS 구조와 DynaLoader 모듈을 사용한) Perl 5, Netscape Server 등으로 드물었다. 아파치는 이미 기능을 확장하기위해 모듈 개념을 사용했고 외부 모듈을 아파치 핵심기능에 연결하기위해 내부적으로 디스패치목록을 이용한 접근방법을 사용했기때문에 1.3 버전부터 이 대열에 합류했다. 그래서 아파치는 실행중 모듈을 읽어들이는데 DSO를 사용하도록 운명지워졌다.

장단점

앞에서 말한 DSO를 사용하면 다음과 같은 장점이 있다:

  • 실제 서버 프로세스가 컴파일시 configure 옵션대신 httpd.conf의 LoadModule을 사용하여 실행중에 결합되므로 서버 패키지 실행이 더 유연하다. 예를 들어 한번의 아파치 설치만으로 다른 서버(표준 버전과 SSL 버전, 최소화 버전과 기능추가 버전 [mod_perl, PHP3] 등)를 실행할 수 있다.
  • 서버는 설치후에도 제삼자가 만든 모듈을 사용하여 쉽게 확장할 수 있다. 최소한 기업의 패키지 제작자는 아파치 핵심 패키지와 별도로 PHP3, mod_perl, mod_fastcgi 등을 추가 패키지로 만들 수 있어서 큰 이득이다.
  • DSO와 apxs를 가지고 아파치 소스 트리 밖에서 작업하고 apxs -i와 apachectl restart 명령어만으로 현재 개발한 모듈의 새 버전을 실행중인 아파치 서버에 반영할 수 있어서 더 쉽게 아파치 모듈을 개발할 수 있다.

DSO는 다음과 같은 단점이 있다:

  • 프로그램의 주소공간에 코드를 동적으로 읽어들이는 기능을 지원하지않는 운영체제가 있기 때문에 모든 플래폼에서 DSO를 사용할 수 없다.
  • 유닉스 로더가 심볼을 찾아야하기 때문에 서버 시작이 약 20% 정도 늦어진다.
  • 서버는 위치독립코드(position independent code, PIC) 때문에 절대주소지정(absolute addressing)보다 느린 상대주소지정(relative addressing)의 복잡한 어셈블러 기법이 필요하므로 어떤 플래폼에서 실행시 약 5% 정도 늦다.
  • DSO 모듈을 다른 DSO기반 라이브러리(ld -lfoo)에 링크할 수 없는 플래폼이 있기때문에 (예를 들어 ELF기반 플래폼은 지원하지만 a.out기반 플래폼은 보통 이 기능을 지원하지 않는다) 모든 종류의 모듈에 DSO를 사용할 수 없다. 다른 말로 DSO 파일로 컴파일하는 모듈은 아파치 핵심과 아파치 핵심이 사용하는 C 라이브러리(libc)와 다른 동적/정적 라이브러리, 위치독립코드를 담고 있는 정적 라이브러리 아카이브(libfoo.a)의 심볼만을 사용할 수 있다. 다른 코드를 사용하려면 아파치 핵심이 그것을 참조하던지, dlopen()으로 직접 코드를 읽어들여야 한다.


내용협상 (Content Negotiation) - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

내용협상 (Content Negotiation)

아파치는 HTTP/1.1 규약에 기술된 내용협상(content negotiation)을 지원한다. 내용협상은 media type, 언어, 문자집합, 인코딩 등에 대해 브라우저가 제공한 선호도에 따라 자원의 가장 적합한 표현을 선택한다. 또 불완전한 협상 정보를 보내는 브라우저의 요청을 지능적으로 처리하는 기능도 있다.

기본적으로 컴파일되는 mod_negotiation 모듈이 내용협상 기능을 제공한다.

내용협상에 대해

자원은 여러 다른 표현을 가질 수 있다. 예를 들어, 다른 언어나 다른 media type 혹은 둘 모두가 다른 표현들이 있을 수 있다. 가장 적당한 표현을 선택하는 한가지 방법은 사용자에게 목록 페이지를 보여주고 선택하게 하는 것이다. 그러나 서버가 자동으로 선택하는 것도 가능하다. 이는 브라우저가 요청의 일부로 그들이 선호하는 표현에 대한 정보를 보내기때문에 가능하다. 예를 들어, 브라우저는 가능한한 불어로, 그러나 없다면 영어로 정보를 보고싶다고 알려줄 수 있다. 브라우저는 요청의 헤더로 그들의 기호를 나타낸다. 오직 불어로된 표현만을 요청한다면 브라우저는 다음과 같이 보낸다.

Accept-Language: fr

이런 기호는 표현이 언어별로 다를 경우에만 고려된다.

다음은 더 복잡한 요청의 예로 브라우저가 불어와 영어를 받을 수 있지만, 불어를 더 선호하고, 여러 media type을 받을 수 있지만, 일반 텍스트 보다는 HTML, 다른 media type 보다는 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

아파치는 HTTP/1.1 규약에 정의된 '서버 주도(server driven)' 내용협상을 지원한다. 아파치는 Accept, Accept-Language, Accept-Charset, Accept-Encoding 요청 헤더를 모두 지원한다. 또, 아파치는 RFC 2295와 RFC 2296에 정의된 실험적인 내용협상인 '자연스러운(transparent)' 요청 헤더도 지원한다.

자원(resource)은 (RFC 2396) URI로 구별하는 개념적인 존재다. 아파치와 같은 웹서버는 자원의 표현(representations)을 제공한다. 표현은 지정된 media type, 문자집합, 인코딩 등을 가진 바이트들로 되있다. 자원은 여러 표현과 (때로는 없을 수도 있다) 연관된다. 자원에 여러 표현이 있다면 자원을 협상가능하다고(negotiable) 부르며, 이때 각 표현을 변형(variant)이라고 한다. 협상가능한 자원의 변형 종류를 협상의 범위(dimension)라고 한다.

아파치의 협상

자원을 협상하기위해 서버는 각 변형에 대한 정보가 필요하다. 다음 두가지 방법중 하나로 정보를 얻는다:

  • 변형을 담은 파일들을 직접 열거한 type map을 (예를 들어, *.var 파일) 사용하거나,
  • 직접 지정하지않아도 서버가 파일명에서 규칙을 찾아서 결과를 선택하는 'MultiViews'를 사용한다.

type-map 파일 사용하기

type map은 type-map이란 핸들러와 연결된 (혹은 이전 아파치 설정과 호환을 위해 mime type이 application/x-type-map인) 문서다. 이 기능을 사용하려면 설정에서 type-map 핸들러에 대한 파일 확장자를 지정해야 한다. 서버 설정파일에 다음과 같이 설정하는 것이 좋다.

AddHandler type-map .var

Type map 파일은 해당하는 자원과 이름이 같아야 하고, 각 변형에 대한 항목이 있어야 한다. 항목은 여러 HTTP형식 헤더 줄로 구성된다. 변형에 대한 각각의 항목들은 빈줄로 구분한다. 항목안에서 빈줄을 사용할 수 없다. (이렇게 할 필요가 없고, 있어도 무시하지만) 여러 항목이 공통으로 가지고 있는 내용으로 map 파일을 시작하는 것이 보통이다. 다음은 map 파일 예다. 이 파일의 이름은 foo.var로, foo라는 자원을 설명한다.

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

typemap 파일이 파일명 확장자 보다, 심지어 Multiviews를 사용하여도, 우선권을 가짐을 주의하라. 변형이 서로 다른 품질을 가진다면, 다음과 같이 (jpeg, gif, ASCII-art에 해당하는) media type에 "qs" 파라미터로 품질(source quality)을 표시할 수 있다:

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인 변형은 절대 선택되지 않음을 주의하라. 'qs' 값이 없는 변형은 1.0으로 취급된다. qs 값은 클라이언트의 능력과는 관계없이 다른 변형들과 비교하여 그 변형의 상대적인 '품질'을 나타낸다. 예를 들어, 사진을 나타내려는 경우 jpeg 파일이 ascii 파일보다는 항상 높은 품질을 가진다. 그러나 자원이 원래 ascii art였다면 ascii 표현이 jpeg 표현보다 더 높은 품질을 가질 수 있다. 그러므로 어떤 변형의 qs 값은 표현하려는 자원의 성질에 따라 다르다.

지원하는 모든 헤더 목록은 mod_negotation typemap 문서를 참고하라.

Multiviews

MultiViews는 디렉토리별 옵션이므로, httpd.conf의 <Directory>, <Location>, <Files> 섹션 혹은 (AllowOverride가 적절히 설정되었다면) .htaccess 파일의 Options 지시어에 설정할 수 있다. Options All은 MultiViews를 포함하지않음을 주의하라. 따로 직접 써줘야 한다.

MultiViews를 사용하면 다음과 같은 일이 일어난다: 서버가 /some/dir/foo에 대한 요청을 받고 /some/dir/foo에 MultiViews가 동작하며 /some/dir/foo가 존재하지 않을 경우, 서버는 디렉토리에서 이름이 foo.*인 파일들을 모든 포함하는 가상의 type map을 만든다. 클라이언트가 요청한 media type과 content-encoding을 가지고 이중에 가장 적합한 것을 선택한다.

MultiViews는 서버가 디렉토리를 참조할때 파일을 찾는 DirectoryIndex 지시어에도 적용된다. 설정파일이 다음과 같다면,

DirectoryIndex index

index.html과 index.html3이 모두 있다면 서버는 이둘 중에 하나를 결정한다. 둘 모두 없고 index.cgi가 있다면, 서버는 그것을 실행한다.

디렉토리를 읽을때 파일중 하나가 Charset, Content-Type, Language, Encoding를 판단하는 mod_mime이 모르는 확장자를 가진다면, 결과는 MultiViewsMatch 지시어 설정에 달렷다. 이 지시어는 핸들러, 필터, 다른 확장형들이 MultiViews 협상에 참여할지 여부를 결정한다.

협상방법

아파치가 type-map 파일이나 디렉토리에 있는 파일명들로 주어진 자원에 대한 변형 목록을 얻게되면 '최적의' 변형을 결정하기위해 두 방법중 하나를 사용한다. 아파치 내용협상 기능을 사용하기위해 정확히 협상이 어떻게 일어나는지 자세히 알 필요는 없다. 그러나 궁금한 사람을 위해 이 방법을 설명한다.

두가지 협상방법이 있다:

  1. 아파치 알고리즘을 사용하여 서버가 주도하는 협상은 일반적인 경우에 사용한다. 아파치 알고리즘은 아래서 자세히 설명한다. 이 알고리즘을 사용하면 아파치는 더 나은 결과를 얻기위해 종종 특정 범위의 품질계수(quality factor)를 '조작한다'. 아파치가 품질계수를 조작하는 방법은 아래서 자세히 설명한다.
  2. 자연스러운(Transparent) 내용협상은 브라우저가 RFC 2295에 정의된 방법으로 요청할 경우에만 사용한다. 이 협상방법은 '최적의' 변형을 결정할 권한을 브라우저에게 부여한다. 그래서 결과는 브라우저의 알고리즘에 달렸다. 자연스러운 협상과정중에 브라우저는 아파치에게 RFC 2296에 정의된 '원격 변형선택 알고리즘(remote variant selection algorithm)'을 요청할 수 있다.

협상의 범위

범위 | 설명
Media Type | 브라우저는 Accept 헤더로 선호를 나타낸다. 각 항목은 품질계수를 가질 수 있다. 변형의 설명도 품질계수를 ("qs" 파라미터) 가질 수 있다.
Language | 브라우저는 Accept-Language 헤더로 선호를 나타낸다. 각 항목은 품질계수를 가질 수 있다. 변형은 여러 언어를 가질 (혹은 아무 언어도 없을) 수 있다.
Encoding | 브라우저는 Accept-Encoding 헤더로 선호를 나타낸다. 각 항목은 품질계수를 가질 수 있다.
Charset | 브라우저는 Accept-Charset 헤더로 선호를 나타낸다. 각 항목은 품질계수를 가질 수 있다. 변형은 media type의 파라미터로 문자집합을 나타낼 수 있다.

아파치 협상 알고리즘

아파치는 브라우저에게 보낼 '최적의' 변형을 (있다면) 선택하기위해 아래 알고리즘을 사용한다. 이 알고리즘은 변경할 수 없다. 다음와 같이 동작한다:

  1. 먼저, 협상의 각 범위에 대해 해당하는 Accept* 헤더를 검사하고, 각 변형에 품질값을 매긴다. 어떤 범위의 Accept* 헤더가 받아들이지 않는 변형은 후보에서 제외한다. 어떤 변형도 남지않으면 4 단계로 간다.
  2. 후보에서 하나씩 제외하여 '최적의' 변형을 찾는다. 다음 각 검사는 순서대로 일어난다. 각 검사에서 선택되지않은 변형은 제외된다. 각 검사후 한 변형만 남으면 이를 최적의 변형으로 선택하고 3 단계로 간다. 여러 변형이 남으면 다음 검사를 진행한다.
    1. Accept 헤더의 품질계수와 변형의 media type에 대한 품질값을 곱하여 가장 높은 값을 가진 변형을 선택한다.
    2. 가장 높은 언어(language) 품질계수를 가진 변형을 선택한다.
    3. Accept-Language 헤더에 (있다면) 나온 언어의 순서 혹은 LanguagePriority 지시어에 (있다면) 나온 언어의 순서를 가지고 가장 적합한 언어를 가진 변형을 선택한다.
    4. 가장 높은 (text/html media type의 버전을 나타내는) 'level' media 파라미터를 가진 변형을 선택한다.
    5. Accept-Charset 헤더를 가지고 가장 적합한 charset media 파라미터를 가진 변형을 찾는다. 헤더가 없다면 ISO-8859-1 문자집합을 가장 선호한다. text/* media type을 가지지만 명시적으로 특정 문자집합과 연결되지않은 변형은 ISO-8859-1로 가정한다.
    6. ISO-8859-1이 아닌 charset media 파라미터를 가진 변형들을 선택한다. 그런 변형이 없다면, 대신 모든 변형을 선택한다.
    7. 가장 적합한 인코딩을 가진 변형을 선택한다. user-agent에 적합한 인코딩을 가진 변형이 있다면 그 변형만을 선택한다. 그렇지않고 인코딩된 변형과 인코딩안된 변형이 같이 있다면 인코딩안됨 변형만을 선택한다. 변형이 모두 인코딩되었거나 모두 인코딩안된 경우 모든 변형을 선택한다.
    8. content length가 가장 적은 변형을 선택한다.
    9. 남은 것중 첫번재 변형을 선택한다. 이는 type-map 파일의 앞에 나왔거나, 디렉토리에서 변형을 읽은 경우 파일명을 ASCII 코드 순서로 하여 앞에 나오는 것이다.
  3. 이제 알고리즘이 '최적의' 변형을 선택했다. 이것을 응답으로 보낸다. HTTP 응답 헤더 Vary는 협상의 범위를 나타내게 된다. (브라우저와 캐쉬는 자원을 캐쉬할때 이 정보를 사용할 수 있다.) 끝.
  4. 이 단계에 도달했다면 (모두 브라우저가 받지못하기 때문에) 어떤 변형도 선택이 안된 경우다. ("No acceptable representation"를 뜻하는) 상태 406과 내용으로 사용가능한 변형의 목록을 담은 HTML 문서를 응답을 보낸다. 또, HTML Vary 헤더는 변형의 범위를 나타낸다.

품질계수 조작하기

아파치는 종종 위의 아파치 협상 알고리즘을 엄격히 지키지않고 품질계수를 변경한다. 이유는 완전하고 정확한 정보를 보내지않는 브라우저에게 (알고리즘의) 더 나은 결과를 보내기 위해서다. 널리 쓰이는 브라우저중 일부는 자주 잘못된 변형을 선택하도록 Accept 헤더를 보낸다. 브라우저가 완전하고 올바른 정보를 보낸다면, 조작을 하지않는다.

Media Type과 와일드카드

Accept: 요청 헤더는 media type에 대한 선호를 나타낸다. 또, *는 어떤 문자열이라도 가능하기때문에 "image/*"나 "*/*" 같이 '와일드카드' media type을 사용할 수도 있다. 그래서 다음과 같은 요청은:

Accept: image/*, */*

"image/"로 시작하는 어떤 type과 다른 어떤 type도 가능함을 의미한다. 어떤 브라우저는 자신이 실제로 다룰 수 있는 type에 추가로 와일드카드를 보낸다. 예를 들면:

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

이유는 직접 열거한 type을 선호하지만 다른 표현이 있다면 그것도 괜찮음을 나타내기 위해서다. 브라우저가 실제로 원한 것은 다음과 같이 명시적으로 품질값을 사용한 것이다.

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

직접 열거한 type은 품질계수가 없어서 기본값인 (가장 높은) 1.0을 가진다. 와일드카드 */*는 낮은 선호도 0.01을 가지므로 직접 열거한 type에 맞는 변형이 없는 경우에만 다른 type들이 사용된다.

Accept: 헤더에 q 계수가 전혀 없고 "*/*"가 있다면, 아파치는 바람직한 행동을 위해 q 값으로 0.01을 지정한다. 또, "type/*" 형태의 와일드카드에는 ("*/*"보다는 더 선호하도록) 0.02를 지정한다. Accept: 헤더에서 q 계수를 가지는 media type이 있다면 이런 특별한 값을 추가하지 않는다. 그래서 명시적인 정보를 보내는 브라우저의 요청은 요청한데로 처리한다.

언어(language) 협상의 예외

아파치 2.0은 언어 협상이 실패한 경우 부드럽게 복구하기위해 협상 알고리즘에 새로 예외를 몇개 추가했다.

클라이언트가 서버에 페이지를 요청했을때 서버가 브라우저가 보낸 Accept-language에 맞는 페이지를 단 한개만 찾으면 문제가 없지만, 그러지 않은 경우 서버는 클라이언트에게 "No Acceptable Variant"나 "Multiple Choices" 응답을 보낸다. 이런 오류문을 피하기위해 이 경우 Accept-language를 무시하고 클라이언트의 요청에 명확히 맞지는 않지만 문서를 보내도록 아파치를 설정할 수 있다. ForceLanguagePriority 지시어는 서버가 이런 오류문중 하나 혹은 둘다를 무시하고 LanguagePriority 지시어로 판단하도록 한다.

또, 서버는 맞는 언어를 못찾은 경우 부모언어를 찾을 수도 있다. 예를 들어 클라이언트가 영국영어를 뜻하는 en-GB 언어로 문서를 요청한 경우, HTTP/1.1 표준에 따르면 서버는 en으로만 표시된 문서를 일반적으로 선택하지 못한다. (그래서 영국영어를 이해하는 독자가 일반적인 영어도 이해할 수 있으므로 Accept-Language 헤더에 en-GB만 포함하고 en을 포함하지않으면 거의 확실히 잘못된 설정임을 유의하라. 불행히도 현재 많은 클라이언트들은 이런 식으로 기본설정되있다.) 다른 언어를 찾지 못하여 서버가 "No Acceptable Variants" 오류를 보내거나 LanguagePriority로 돌아가야 한다면, 서버는 하위언어 규약을 무시하고 en-GB를 en 문서에 대응한다. 암묵적으로 아파치는 부모언어를 매우 낮은 품질값으로 클라이언트의 허용언어 목록에 추가한다. 그러나 클라이언트가 "en-GB; q=0.9, fr; q=0.8"을 요청하고 서버에 "en"과 "fr" 문서가 있다면, "fr" 문서가 선택됨을 주의하라. 이는 HTTP/1.1 표준을 지키고, 올바로 설정된 클라이언트와 효율적으로 동작하기위함이다.

자연스러운(transparent) 내용협상의 확장

아파치는 다음과 같이 자연스러운 내용확장 프로토콜을 (RFC 2295) 확장한다. 변형 목록의 새로운 {encoding ..}는 특정 content-encoding을 가진 변형만을 지칭한다. RVSA/1.0 알고리즘은 (RFC 2296) 목록에서 인코딩된 변형을 인식할 수 있고, 인코딩이 Accept-Encoding 요청 헤더에 맞는 경우 인코딩된 변형들도 후보로 사용하도록 확장되었다. RVSA/1.0 구현은 최적의 변형을 찾기 전에 계산된 품질계수를 소수점 5자리에서 반올림하지 않는다.

하이퍼링크와 이름규칙에 대하여

언어(language) 협상을 사용한다면 파일은 여러 확장자를 가지고 확장자의 순서는 보통 관계없으므로 파일명에 여러 다른 이름규칙을 사용할 수 있다. (자세한 내용은 mod_mime 문서를 참고하라.)

전형적인 파일은 MIME-type 확장자 (예를 들어, html), 경우에 따라 encoding 확장자 (예를 들어, gz), 파일에 여러 언어 변형이 있는 경우 물론 언어 확장자를 (예를 들어, 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-type을 (예를 들어, foo.html) 사용하고 싶다면 (encoding 확장자가 있다면 이것도 포함하여) 언어 확장자를 MIME-type 확장자보다 오른쪽에 (예를 들어, foo.html.en) 두어야한다.

캐쉬에 대하여

캐쉬가 표현을 저장하면 표현과 요청 URL을 연관시킨다. 다음번 그 URL을 요청하면 캐쉬는 저장된 표현을 사용한다. 그러나 서버와 협상이 가능한 자원인 경우 첫번째 요청한 변형만 캐쉬되어 이후 요청은 캐쉬된 잘못된 응답을 얻을 수 있다. 이를 막기위해 아파치는 보통 내용협상후 반환되는 모든 요청에 HTTP/1.0 클라이언트가 캐쉬를 못하도록 표시를 한다. 또, 아파치는 협상한 응답의 캐쉬를 허용하는 HTTP/1.1 프로토콜의 기능을 지원한다.

CacheNegotiatedDocs 지시어는 HTTP/1.0 호환 클라이언트(브라우저 혹은 캐쉬)가 보낸 요청에 대해 협상한 응답을 캐쉬할 수 있게 한다. 이 지시어는 서버나 가상호스트 설정에 사용하며, 아규먼트를 받지않는다. 이 지시어는 HTTP/1.1 클라이언트의 요청과는 관계가 없다.

다른 정보

내용협상에 대한 다른 정보는 Alan J. Flavell가 쓴 Language Negotiation Notes를 참고하라. 그러나 이 문서는 아직 아파치 2.0의 변화를 반영하지 않을 수 있다.


사용자정의 오류 응답 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

사용자정의 오류 응답

웹마스터는 오류나 문제가 발생했을때 아파치의 응답을 설정할 수 있다.

서버가 오류나 문제를 발견했을때 보낼 사용자정의 응답을 정의할 수 있다.

스크립트가 죽은 경우 "500 Server Error" 응답 대신 사용자에게 더 친근한 문구를 사용하거나 다른 (같은 사이트나 외부 사이트의) URL로 리다이렉션을 할 수 있다.

행동

이전 행동

NCSA httpd 1.3은 사용자에게 무의미하고 지루한 오류문을 보냈다. 문제가 발생한 이유를 로그에 남길 수도 없었다.

새로운 행동

서버는 다음과 같은 일을 할 수 있다:

  1. NCSA의 고정된 문구 대신 다른 문구를 보여주거나
  2. 같은 사이트의 URL로 리다이렉션하거나
  3. 외부 사이트의 URL로 리다이렉션한다.

다른 사이트의 URL로 리다이렉션하는 것이 유용할 수 있지만, 이 경우 문제를 설명하거나 로그하는데 필요한 정보중 일부만 전달된다.

오류에 대한 정보를 전달하기위해 아파치는 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은 (cgi-script나 cgi-include일) 새 URL로 넘겨진다. 다른 변수는 오류가 발생하기 이전에 (역주; 이름에서 REDIRECT_를 뺀 환경변수가) 존재한 경우에만 있다. ErrorDocument가 외부로 (같은 서버라도 http:와 같은 스킴(scheme)으로 시작한다면) 리다이렉션한다면 이중 어떤 것도 설정되지 않는다.

설정

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.

사용자정의 오류 응답과 리다이렉션

URL로 리다이렉션하는 아파치 행동은 스크립트/server-include에 환경변수를 더 넘겨주도록 변경되었다.

이전 행동

리다이렉션되는 스크립트에 표준 CGI 변수들이 넘어간다. 어디에서 리다이렉션이 일어났는지 알 수 없다.

새로운 행동

리다이렉션된 스크립트는 새로운 환경변수들을 사용할 수 있다. 모두 앞에 REDIRECT_가 붙어있다. REDIRECT_ 환경변수는 원래 CGI 환경변수명 앞에 REDIRECT_를 붙여서 만든다. 예를 들어, HTTP_USER_AGENT는 REDIRECT_HTTP_USER_AGENT가 되었다. 이런 변수에 추가로 스크립트가 원래 URL을 알도록 아파치는 REDIRECT_URL과 REDIRECT_STATUS를 정의한다. 원래 URL과 리다이렉션된 URL 모두 접근 로그에 기록할 수 있다.

ErrorDocument가 같은 서버에 있는 CGI 스크립트로 리다이렉션한다면, 스크립트는 클라이언트에게 오류 상황을 확실히 전달하기위해 출력에 "Status:" 헤더 필드를 포함해야 한다. 예를 들어, Perl로 작성한 ErrorDocument 스크립트는 다음과 같다:

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

404 Not Found와 같은 특정 오류 상황에 대한 스크립트라면, 대신 (역주; 고정된) 특정 상태코드와 오류문을 사용할 수 있다.

(클라이언트에게 리다이렉션을 요청하기위해) 응답에 Location: 헤더를 포함한다면, 스크립트는 반드시 (302 Found 같은) 적절한 Status: 헤더를 출력해야 함을 주의하라. 그렇지않으면 Location: 헤더가 아무 소용없게 될 수 있다.


주소와 포트 지정 (Binding) - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

주소와 포트 지정 (Binding)

아파치가 특정 주소와 포트에서 서비스하도록 설정하기.

참고

  • 가상호스트
  • DNS 문제

개요

관련된 모듈 관련된 지시어
  • core
  • mpm_common
  • <VirtualHost>
  • Listen

아파치를 시작하면 아파치는 컴퓨터의 어떤 포트와 주소에 연결하여, 들어오는 요청을 기다린다. 기본적으로 아파치는 컴퓨터의 모든 주소에서 기다린다. 그러나 아파치가 특정 포트나 선택한 주소만을 기다리게 해야할 경우가 있다. 또 이 문제는 아파치가 어떻게 다른 IP 주소, 호스트명, 포트에 반응할지를 결정하는 가상호스트 기능과도 관련되있다.

Listen 지시어는 서버가 특정 포트나 주소와 포트 조합에서만 요청을 받게 한다. Listen 지시어에 포트 번호만 지정하면, 서버는 모든 인터페이스에서 지정한 포트를 기다린다. 여러 Listen 지시어로 기다릴 여러 주소와 포트를 지정할 수도 있다. 서버는 열거한 주소와 포트로 요청이 들어오면 응답한다.

예를 들어, 서버가 80번과 8000번 포트 모두에서 연결을 받도록 하려면:

Listen 80
Listen 8000

서버가 지정한 두 인터페이스와 포트에서 연결을 기다리도록 하려면,

Listen 192.170.2.1:80
Listen 192.170.2.5:8000

IPv6 주소는 다음과 같이 대괄호로 묶어야 한다:

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

IPv6에서 특별히 고려할 점

IPv6를 구현한 플래폼이 늘고 있고 APR이 이들 플래폼 대부분에서 IPv6를 지원하기때문에, 아파치는 IPv6 소켓을 할당하여 IPv6로 받은 요청을 처리할 수 있다.

아파치 관리자에게 복잡한 부분은 IPv6 소켓이 IPv4 연결과 IPv6 연결을 모두 처리할 수 있느냐는 점이다. 대부분의 플래폼에서는 IPv4-대응(mapped) IPv6 주소를 사용하여 IPv6 소켓에서 IPv4 연결을 받지만, FreeBSD와 NetBSD와 OpenBSD은 시스템전체 정책때문에 기본적으로 허용하지 않는다. 그러나 기본적으로 허용하지않는 시스템이라도 아파치를 위해 특별한 설정 파라미터로 변경할 수 있다.

아파치가 최소한의 소켓을 사용하여 IPv4 연결과 IPv6 연결을 모두 받도록하려면 IPv4-대응 IPv6 주소를 사용해야 한다. 그러기위해서 컴파일때 구성 옵션 --enable-v4-mapped를 사용하고, 다음과 같이 일반적인 Listen 지시어를 사용한다:

Listen 80

--enable-v4-mapped를 사용할때 아파치가 만드는 기본 설정파일의 Listen 지시어는 위와 같다. --enable-v4-mapped는 FreeBSD, NetBSD, OpenBSD를 제외한 모든 플래폼에서 기본값이고, 아마도 당신의 아파치도 마찬가지일 것이다.

플래폼과 APR의 지원여부와 관계없이 아파치가 IPv4 연결만을 받도록하려면, 다음 예제와 같이 모든 Listen 지시어에 IPv4 주소를 사용한다:

Listen 0.0.0.0:80
Listen 192.170.2.1:80

IPv4 연결과 IPv6 연결을 서로 다른 소켓으로 받으려면, 컴파일때 구성 옵션 --disable-v4-mapped를 사용하고 다음과 같이 Listen 지시어를 따로 사용한다:

Listen [::]:80
Listen 0.0.0.0:80

--disable-v4-mapped를 사용할때 아파치가 만드는 기본 설정파일의 Listen 지시어는 위와 같다. --disable-v4-mapped는 FreeBSD, NetBSD, OpenBSD에서 기본값이다.

가상호스트와 어떻게 연관되나

Listen은 가상호스트를 만들지 않는다. 이는 단지 주서버가 어떤 주소와 포트를 기다릴지만 알려준다. <VirtualHost> 지시어를 사용하지 않으면, 서버는 받은 모든 요청을 똑같이 처리한다. 그러나 <VirtualHost>로 여러 주소와 포트에 대해 다른 행동을 지정할 수 있다. 가상호스트를 만들려면 먼저 서버에게 사용할 주소와 포트를 알려줘야 한다. 그리고 특정 주소와 포트에 대한 가상호스트의 행동을 지정할 <VirtualHost> 섹션이 필요하다. 주서버가 기다리지않는 주소와 포트를 사용하는 <VirtualHost>는 접근할 수 없음을 주의하라.


다중처리 모듈 (MPM) - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

다중처리 모듈 (MPM)

이 문서는 다중처리 모듈 (Multi-Processing Module)이 무엇이며, 아파치 웹서버가 이를 어떻게 사용하는지 설명한다.

소개

아파치 웹서버는 다양한 환경의 다양한 플래폼에서 동작할 수 있도록 강력하고 유연하게 설계되었다. 다른 플래폼과 다른 환경은 보통 다른 기능을 요구하며, 어떤 기능을 가장 효율적으로 구현하는 방법이 다를 수 있다. 아파치는 모듈화된 설계로 이런 다양한 환경에 항상 적응해왔다. 그래서 웹마스터는 컴파일시 혹은 실행시 어떤 모듈을 읽어들일지 선택하여 서버에 포함할 기능을 결정할 수 있다.

Apache 2.0은 이런 모듈화된 설계를 웹서버의 가장 기본적인 부분에까지 확장했다. 서버는 시스템의 네트웍 포트에 연결하고, 요청을 받아들이며, 받아들인 요청을 처리하기위해 자식들에게 분배하는 다중처리 모듈 (Multi-Processing Modules, MPMs)을 선택할 수 있다.

서버를 이 정도로 모듈화하면 두가지 중요한 장점이 있다:

  • mpm_winnt가 Apache 1.3에서 사용한 POSIX층 대신 자체 네트웍 기능을 사용할 수 있는 등, 아파치는 여러 다양한 운영체제를 더 깔끔하고 효율적으로 지원할 수 있다. 이 장점은 특화된 MPM을 구현한 다른 운영체제에도 적용된다.
  • 서버는 특정 사이트의 요구조건에 더 특화될 수 있다. 예를 들어 높은 확장가능성(scalability)이 필요한 사이트는 worker와 같은 쓰레드 MPM을 사용하고, 안정성과 오래된 소프트웨어와의 호환성이 필요한 사이트는 preforking MPM을 사용할 수 있다. 추가로 다른 사용자아이디로 여러 호스트를 서비스하는 것(perchild)과 같은 특별한 기능도 제공된다.

사용자가 보기에 MPM은 다른 아파치 모듈과 거의 비슷해 보인다. 주된 차이는 서버는 한번에 오직 한 MPM만을 사용해야 한다는 점이다. 사용가능한 MPM 목록은 모듈 목록 페이지에 있다.

MPM 선택하기

MPMs는 구성중에 선택하여 서버에 컴파일되야 한다. 쓰레드를 사용하는 것을 컴파일러가 알면 많은 함수를 최적화할 수 있다. 유닉스에서 몇몇 MPM은 쓰레드를 쓰고 나머지는 아니므로, MPM이 구성중에 선택되어 아파치에 컴파일될때 아파치는 더 빠른 속도를 낸다.

원하는 MPM을 선택하려면 ./configure 스크립트에 with-mpm= NAME 아규먼트를 사용하라. NAME은 원하는 MPM 이름이다.

서버를 컴파일한후 ./httpd -l 명령어로 선택한 MPM을 알 수 있다. 이 명령어는 MPM을 포함하여 서버에 컴파일된 모든 모듈을 알려준다.

MPM 기본값

다음 표는 여러 운영체제의 기본 MPM을 보여준다. 컴파일시 다르게 선택하지 않으면 이 MPM이 선택된다.

BeOS | beos
Netware | mpm_netware
OS/2 | mpmt_os2
유닉스 | prefork
윈도우즈 | mpm_winnt


아파치의 환경변수 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

아파치의 환경변수

아파치 웹서버는 환경변수(environment variable)라는 변수에 정보를 저장할 수 있다. 이 정보를 사용하여 로그나 접근제어 등 여러 작업을 조절한다. 또, 환경변수는 CGI 스크립트와 같은 외부 프로그램과 통신하는 수단이 된다. 이 문서는 환경변수를 다루고 사용하는 다양한 방법들을 설명한다.

이 변수들을 환경변수라고 부르지만, 운영체제에서 말하는 환경변수와 다르다. 이 변수는 아파치 내부에 저장되고 사용된다. 환경변수는 CGI 스크립트나 Server Side Include 스크립트로 넘겨질때만 실제 운영체제 환경변수가 된다. 서버를 실행하는 운영체제 환경을 수정하고 싶다면 운영체제 쉘에서 환경을 수정해야 한다.

환경변수 설정하기

관련된 모듈 관련된 지시어
  • mod_env
  • mod_rewrite
  • mod_setenvif
  • mod_unique_id
  • BrowserMatch
  • BrowserMatchNoCase
  • PassEnv
  • RewriteRule
  • SetEnv
  • SetEnvIf
  • SetEnvIfNoCase
  • UnsetEnv

기본적인 환경설정

아파치에서 환경변수를 설정하는 가장 기본적인 방법은 무조건적인 SetEnv 지시어를 사용하는 것이다. PassEnv 지시어를 사용하여 서버를 시작한 쉘에서 환경변수를 가져올 수도 있다.

요청에 따른 조건부 설정

더 유연하게, mod_setenvif가 제공하는 지시어는 요청마다 요청의 특징에 따라 환경변수를 설정한다. 예를 들어, 특정 브라우저로 (User-Agent) 요청하거나 특정 Referer (맞춤법이 틀리지 않았다) 헤더가 있는 경우에만 변수를 설정할 수 있다. 심지어 mod_rewrite에 있는 RewriteRule의 [E=...] 옵션을 사용하여 더 유연하게 환경변수를 설정할 수도 있다.

유일한 식별자

마지막으로 mod_unique_id는 각 요청에 대해 어떤 경우에도 "모든" 요청중에 확실히 유일한(겹치지않은) 값으로 UNIQUE_ID 환경변수를 설정한다.

표준 CGI 변수

CGI 스크립트와 SSI 문서는 아파치 설정에서 설정하였거나 쉘에서 가져온 환경변수 외에 추가로 CGI 규약이 규정한 요청에 대한 정보를 알려주는 환경변수들을 받는다.

주의할 점

  • 환경설정 지시어를 사용하여 표준 CGI 변수를 무시하거나 수정할 수 없다.
  • suexec가 CGI 스크립트를 실행하는 경우, 시작하기전에 CGI 스크립트의 환경은 안전한 변수들만 가지도록 청소된다. 안전한 변수 목록은 컴파일시 suexec.c에 정의된다.
  • 포팅을 위해 환경변수 이름에는 오직 문자, 숫자, 밑줄문자만 사용하는 것이 좋다. 또, 첫번째 문자로 숫자를 사용하지않는 것이 좋다. CGI 스크립트나 SSI 페이지에 넘어갈때 이외의 문자는 밑줄로 대체된다.

환경변수 사용하기

관련된 모듈 관련된 지시어
  • mod_access
  • mod_cgi
  • mod_ext_filter
  • mod_headers
  • mod_include
  • mod_log_config
  • mod_rewrite
  • Allow
  • CustomLog
  • Deny
  • ExtFilterDefine
  • Header
  • LogFormat
  • RewriteCond
  • RewriteRule

CGI 스크립트

환경변수의 주된 용도중 하나는 CGI 스크립트와 정보를 교환하는 것이다. 앞에서 설명했듯이 아파치 설정에서 설정한 변수외에 요청에 대한 표준 정보를 가진 변수가 CGI 스크립트로 넘어간다. 더 자세한 내용은 CGI 투토리얼을 참고하라.

SSI 페이지

mod_include의 INCLUDES 필터가 처리하는 서버파싱 (SSI) 문서는 echo 요소를 사용하여 환경변수를 출력할 수 있고, 환경변수를 사용하여 요청의 특징에 따라 흐름제어 요소로 페이지의 일부를 변경할 수 있다. 아파치는 또 SSI 문서에게 위에서 설명한 표준 CGI 환경변수를 제공한다. 더 자세한 내용은 SSI 투토리얼을 참고하라.

접근제어

allow from env=과 deny from env= 지시어를 사용하여 환경변수 값에 따라 서버로의 접근을 조절할 수 있다. SetEnvIf와 같이 사용하면 클라이언트의 특징에 따라 자유롭게 서버로의 접근을 제어할 수 있다. 예를 들어, 특정 브라우저의 (User-Agent) 접근을 거부할 수 있다.

조건부 로그

LogFormat의 %e 옵션을 사용하여 환경변수를 접근 로그에 기록할 수 있다. 또, CustomLog 지시어의 조건부 형식을 사용하면 환경변수의 상황에 따라 요청을 로그할지 여부를 결정할 수 있다. SetEnvIf와 같이 사용하여 어떤 요청을 로그할지 자유롭게 결정할 수 있다. 예를 들어, 파일명이 gif로 끝나는 요청은 로그하지 않거나, 외부 네트웍에 있는 클라이언트의 요청만을 로그할 수 있다.

조건부 응답 헤더

Header 지시어는 클라이언트에게 응답을 보낼때 환경변수의 유무에 따라 어떤 HTTP 헤더를 포함할지 결정할 수 있다. 예를 들어, 클라이언트의 요청에 특정 헤더가 있는 경우에만 어떤 응답 헤더를 보낼 수 있다.

외부 필터 실행하기

mod_ext_filter의 ExtFilterDefine 지시어로 설정한 외부 필터를 disableenv=와 enableenv= 옵션을 사용하여 환경변수에 따라 선택적으로 실행할 수 있다.

URL 재작성(Rewriting)

RewriteCond의 TestString에 %{ENV:...} 형식을 사용하면 mod_rewrite의 재작성 엔진이 환경변수에 따라 다르게 행동한다. mod_rewrite에서 앞에 ENV:를 붙이지않고 접근하는 변수는 실제 환경변수가 아님을 주의하라. 그들은 다른 모듈에서 읽을 수 없는 mod_rewrite에 한정된 변수다.

특별한 목적의 환경변수

클라이언트와 원활한 동작하기위해 아파치는 특별한 클라이언트에 대해 자신의 행동을 수정한다. 보통 BrowserMatch에서 환경변수를 정의하여 이런 문제를 해결한다. 그러나 SetEnv와 PassEnv로도 가능하다.

downgrade-1.0

요청이 이후 버전을 사용하더라도 HTTP/1.0 요청으로 처리한다.

force-no-vary

응답을 클라이언트에게 보내기 전에 응답 헤더에서 Vary 필드를 뺀다. 어떤 클라이언트는 이 필드를 제대로 해석하지 못한다 (클라이언트의 이미 알려진 문제점 페이지 참고). 이 변수는 이런 문제를 해결한다. 또한, 이 변수는 force-response-1.0을 가정한다.

force-response-1.0

HTTP/1.0 요청을 하는 클라이언트에게 HTTP/1.0 응답을 강제한다. 원래 AOL 프록시에 문제가 있어서 만들어졌다. 어떤 HTTP/1.0 클라이언트는 HTTP/1.1 응답을 받으면 제대로 동작하지 않으므로, 이 문제를 해결하기위해 사용한다.

gzip-only-text/html

값이 "1"이면 text/html이 아닌 content-type에 대해 mod_deflate의 DEFLATE 출력필터를 사용하지 않는다.

no-gzip

이 옵션을 설정하면 mod_deflate의 DEFLATE 필터를 사용하지 않는다.

nokeepalive

KeepAlive를 무시한다.

redirect-carefully

서버가 더 조심히 클라이언트에게 리다이렉션을 보낸다. 보통 리다이렉션을 처리하는데 문제가 있는 클라이언트을 위해 사용한다. 원래 Microsoft의 WebFolders 소프트웨어가 DAV 메써드를 통해 디렉토리 자원의 리다이렉션을 처리하는데 문제가 있어서 만들어졌다.

suppress-error-charset

2.0.40 이후 버전에 있다

아파치가 클라이언트의 요청에 대한 응답으로 리다이렉션을 보낼때 클라이언트가 자동으로 리다이렉션을 따라가지 못하는(혹은 않는) 경우에 대비하여 응답에 사용자에게 보여줄 문구를 포함한다. 아파치는 보통 이 글을 아파치가 사용하는 문자집합인 ISO-8859-1로 표시한다.

그러나 리다이렉션된 페이지가 다른 문자집합을 사용할 경우 어떤 이상한 브라우저 버전은 실제 페이지가 아니라 리다이렉션 페이지의 문자집합을 사용하려고 한다. 예를 들어, 그리스어가 이상하게 보일 수 있다.

이 환경변수는 아파치가 리다이렉션 페이지에 문자집합을 설정하지않도록 하여, 이런 브라우저가 실제 페이지의 문자집합을 올바로 사용하게 만든다.

예제

잘못 동작하는 클라이언트들을 위해 프로토콜 행동 변경하기

클라이언트들의 이미 알려진 문제를 해결하기위해 httpd.conf에 다음 내용을 포함하길 바란다.

#
# 다음 지시어들은 일반적인 HTTP 응답을 변경한다.
# 첫번째 지시어는 Netscape 2.x와 이를 가장한 브라우저에게
# keepalive를 사용하지 않는다. 이들 브라우저 구현에 문제가 있다.
# 두번째 지시어는 HTTP/1.1 구현이 잘못되었고 301이나 302
# (리다이렉션) 응답에 사용한 keepalive를 제대로 지원하지
# 못하는 Microsoft Internet Explorer 4.0b2를 위한 것이다.
#
BrowserMatch "Mozilla/2" nokeepalive
BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0

#
# 다음 지시어는 기본적인 HTTP/1.1 응답을 이해하지 못하여
# HTTP/1.0 규약을 어기는 브라우저에게 HTTP/1.1 응답을 보내지 않는다.
#
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

"이미지 도둑" 방지

이 예는 현재 서버외의 사용자가 페이지에 서버에 있는 이미지를 포함하지 못하도록 하는 방법을 설명한다. 이 설정을 권장하지는 않으며, 제한된 경우에만 동작한다. 우리는 모든 이미지가 /web/images 디렉토리 안에 있다고 가정한다.

SetEnvIf Referer "^http://www.example.com/" local_referal
# Referer 정보를 보내지 않는 브라우저를 허용한다
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 HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

아파치에서 핸들러 사용

이 문서는 아파치에서 핸들러를 사용하는 방법을 설명한다.

핸들러가 무엇인가

관련된 모듈 관련된 지시어
  • mod_actions
  • mod_asis
  • mod_cgi
  • mod_imap
  • mod_info
  • mod_mime
  • mod_negotiation
  • mod_status
  • Action
  • AddHandler
  • RemoveHandler
  • SetHandler

파일을 요청할때 아파치가 내부적으로 수행할 작업을 "핸들러(handler)"라고 한다. 일반적으로 파일은 파일 종류에 따라 암묵적인 핸들러를 가지고 있다. 모든 파일은 보통 간단히 서버가 서비스하지만, 어떤 파일 종류는 따로 "처리된다(handled)".

Apache 1.1부터 핸들러를 명시적으로 사용할 수 있게 되었다. 파일 종류와 관계없이 핸들러를 파일의 확장자나 위치에 따라 지정할 수 있다. 이는 더 훌륭한 방법이고 파일을 종류와 핸들러 둘 모두와 연계할 수 있기때문에 좋다. (여러 확장자를 가진 파일도 참고)

핸들러는 서버나 모듈로 구현하여, Action 지시어로 추가할 수 있다. 표준 배포본에 있는 기본 핸들러는 다음과 같다:

  • default-handler: 정적인 내용을 처리하기위해 기본적으로 사용하는 핸들러 default_handler()를 사용하여 파일을 보낸다. (core)
  • send-as-is: HTTP 헤더가 있는 파일을 그대로 보낸다. (mod_asis)
  • cgi-script: 파일을 CGI로 처리한다. (mod_cgi)
  • imap-file: imagemap 규칙 파일로 처리한다. (mod_imap)
  • server-info: 서버의 설정 정보를 알려준다. (mod_info)
  • server-status: 서버의 상태를 보고한다. (mod_status)
  • type-map: 내용협상에 사용할 type map으로 처리한다. (mod_negotiation)

예제

CGI 스크립트를 사용하여 정적인 내용 수정하기

다음 지시어는 확장자가 html인 파일을 요청할 경우 footer.pl CGI 스크립트를 띄운다.

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

CGI 스크립트는 (PATH_TRANSLATED 환경변수가 지칭하는) 원래 요청한 문서를 적절히 수정한 후 보낸다.

HTTP 헤더를 포함하는 파일

다음 지시어는 HTTP 헤더를 포함하는 파일에 send-as-is 핸들러를 지시한다. /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에 핸들러 이름을 지정해주기만 하면 된다. 핸들러는 content type 대신 핸들러 이름을 사용한 것을 제외하고는 전과 같이 구현되었다. 꼭 지킬 필요는 없지만 핸들러 이름에 슬래쉬를 사용하지 않고, 단어들 사이에 빼기 기호를 사용하는 것이 일반적이다. 그래서 핸들러 이름이 media type과 겹치지 않는다.


필터 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

필터

이 문서는 아파치에서 필터를 사용하는 방법을 설명한다.

필터

관련된 모듈 관련된 지시어
  • mod_deflate
  • mod_ext_filter
  • mod_include
  • AddInputFilter
  • AddOutputFilter
  • RemoveInputFilter
  • RemoveOutputFilter
  • ExtFilterDefine
  • ExtFilterOptions
  • SetInputFilter
  • SetOutputFilter

필터(filter)는 서버가 보내거나 받는 자료에 적용되는 작업이다. 클라이언트가 서버에게 보내는 자료는 입력필터(input filter)가 처리하고, 서버가 클라이언트에게 보내는 자료는 출력필터(output filter)가 처리한다. 자료에 여러 필터를 사용할 수 있고, 직접 필터의 순서를 지정할 수 있다.

아파치는 이어받기(byte-range) 요청 등을 처리하기위해 내부적으로 필터를 사용한다. 또, 설정 지시어를 사용하여 선택가능한 필터를 제공하는 모듈도 있다. SetInputFilter, SetOutputFilter, AddInputFilter, AddOutputFilter, RemoveInputFilter, RemoveOutputFilter 지시어로 자료를 처리하는 필터를 조절한다.

현재 아파치 웹서버 배포본은 사용자가 선택할 수 있는 다음과 같은 필터를 제공한다.

INCLUDES
mod_include가 처리하는 Server-Side Includes
DEFLATE
mod_deflate를 사용하여 출력을 클라이언트로 보내기 전에 압축

또, mod_ext_filter 모듈을 사용하여 외부 프로그램을 필터로 사용할 수도 있다.


suEXEC 지원 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

suEXEC 지원

suEXEC 기능은 아파치가 CGI와 SSI 프로그램을 웹서버를 실행한 사용자 ID가 아닌 다른 사용자 ID로 실행하도록 한다. 보통 CGI나 SSI 프로그램을 실행하면 웹서버를 실행한 사용자와 같은 사용자로 실행한다.

이 기능을 적절히 사용하면 사용자가 직접 CGI나 SSI 프로그램을 개발하고 실행할때 발생할 수 있는 보안위험을 상당히 줄일 수 있다. 그러나 suEXEC가 부적절하게 설정되면 많은 문제와 컴퓨터에 새로운 보안 허점을 만들 수 있다. 만약 setuid root 프로그램과 이런 프로그램의 보안 문제에 생소하다면 suEXEC를 사용하지않길 진심으로 바란다.

시작하기 전에

시작하기 전에 우선 아파치그룹과 이 문서의 가정을 밝힌다.

먼저 setuid와 setgid 기능이 가능한 유닉스류 운영체제를 사용한다고 가정한다. 모든 명령어 예들도 같은 가정을 한다. suEXEC를 지원하는 다른 플래폼을 사용하다면 설정이 다를 수 있다.

두번째, 당신이 컴퓨터 보안의 기본 개념과 관리에 익숙하다고 가정한다. 여기에는 setuid/setgid 기능과 이들이 시스템과 보안에 미치는 여러 영향에 대한 이해가 포함된다.

세번째, suEXEC 코드의 수정하지않은 버전을 사용한다고 가정한다. 개발자와 여러 베타테스터들은 suEXEC와 관련된 모든 코드를 조심스럽게 조사하고 검사했다. 코드를 간단하게 하고 확실한 안전을 보장하기위해 모든 주의를 기울였다. 이 코드를 수정하면 예상치못한 문제와 새로운 보안 위험이 발생할 수 있다. 보안 프로그래밍에 대해 매우 잘 알고 코드를 살펴보기위해 아파치그룹과 작업을 공유할 의사가 없다면 suEXEC 코드를 수정하지않길 강력히 권한다.

네번째이자 마지막으로, 아파치그룹은 suEXEC를 아파치 기본설치에 포함하지 않기로 결정했다. 결국 관리자가 주의를 기울여서 suEXEC를 설정해야 한다. suEXEC의 여러 설정을 잘 고려한후 관리자는 일반적인 설치방법을 suEXEC를 설치할 수 있다. suEXEC 기능을 사용하는 시스템의 보안을 책임지는 관리자는 이 설정값들을 주의있게 살펴보고 지정해야 한다. 이런 상세한 과정은 suEXEC를 사용할만큼 주의있고 단호한 사람만이 suEXEC를 사용하도록 아파치그룹이 원하기 때문이다.

아직도 사용하길 원하는가? 그런가? 좋다. 이제 시작하자!

suEXEC 보안모델

suEXEC를 구성하고 설치하기 전에 우리는 보안모델을 먼저 설명한다. 이를 통해 정확히 suEXEC 안에서는 무슨 일이 일어나며 시스템의 보안을 위해 무엇을 조심해야 할지 더 잘 이해할 수 있다.

suEXEC는 아파치 웹서버가 부르는 setuid "wrapper" 프로그램을 기반으로 한다. 이 wrapper는 관리자가 주서버와 다른 userid로 실행하도록 설정한 CGI나 SSI 프로그램에 HTTP 요청이 오면 불린다. 이런 요청이 오면 아파치는 suEXEC wrapper에게 프로그램명과 프로그램을 실행할 사용자와 그룹 ID를 제공한다.

그러면 wrapper는 다음 과정을 통해 성공과 실패를 결정한다. 이 조건중 하나라도 실패하면 프로그램은 실패로 기록되고 오류를 내며 종료한다. 실패하지 않으면 과정을 계속한다:

  1. 적절한 수의 아규먼트로 wrapper를 실행하는가?

    wrapper는 적절한 수의 아규먼트가 있어야만 실행된다. 아파치 웹서버가 이 개수를 안다. wrapper가 적절한 수의 아규먼트를 받지못하면 해킹되었거나 아파치의 suEXEC에 뭔가 문제가 있는 것이다.

  2. wrapper를 실행하는 사용자가 시스템의 정상적인 사용자인가?

    wrapper를 실행하는 사용자가 실제로 시스템의 사용자인지 확인한다.

  3. 이 사용자가 wrapper를 실행하도록 허용되었나?

    이 사용자가 wrapper를 실행하도록 허용되었나? 오직 한 사용자(아파치 사용자)만이 이 프로그램을 실행할 수 있다.

  4. 지정한 프로그램이 안전하지않은 계층참조를 가지는가?

    지정한 프로그램이 '/'로 시작하거나 뒷참조 '..'을 가지는가? 이들을 사용할 수 없다. 지정한 프로그램은 아파치 웹공간내에 있어야 한다.

  5. 지정한 사용자명이 유효한가?

    지정한 사용자가 존재하는가?

  6. 지정한 그룹명이 유효한가?

    지정한 그룹이 존재하는가?

  7. 지정한 사용자가 superuser가 아닌가?

    현재 suEXEC는 'root'가 CGI/SSI 프로그램을 실행할 수 없도록 한다.

  8. 지정한 userid가 최소 ID 숫자보다 큰가?

    설정에서 최소 사용자 ID 숫자를 지정한다. 그래서 CGI/SSI 프로그램을 실행할 수 있는 userid의 최소치를 지정할 수 있다. "시스템용" 계정을 제외할때 유용하다.

  9. 지정한 그룹이 superuser 그룹이 아닌가?

    현재 suEXEC는 'root' 그룹이 CGI/SSI 프로그램을 실행할 수 없도록 한다.

  10. 지정한 groupid가 최소 ID 숫자보다 큰가?

    설정에서 최소 그룹 ID 숫자를 지정한다. 그래서 CGI/SSI 프로그램을 실행할 수 있는 groupid의 최소치를 지정할 수 있다. "시스템용" 그룹을 제외할때 유용하다.

  11. wrapper가 성공적으로 지정한 사용자와 그룹이 될 수 있는가?

    이 단계에서 프로그램은 setuid와 setgid 호출을 하여 지정한 사용자와 그룹이 된다. 또, 그룹 접근목록은 사용자가 해당된 모든 그룹으로 초기화된다.

  12. 프로그램이 있는 디렉토리가 존재하나?

    존재하지 않다면 파일이 있을 수 없다.

  13. 디렉토리가 아파치 웹공간 안에 있는가?

    서버의 일반적인 부분을 요청할 경우 요청하는 디렉토리가 서버의 문서 root 아래 있는가? UserDir을 요청할 경우 요청하는 디렉토리가 사용자 문서 root 아래 있는가?

  14. 다른 누구도 디렉토리에 쓰기권한이 없는가?

    디렉토리를 다른 사람에게 열어두길 원하지않는다. 오직 소유자만이 디렉토리 내용을 변경할 수 있다.

  15. 지정한 프로그램이 존재하는가?

    존재하지않다면 실행할 수도 없다.

  16. 다른 누구도 지정한 프로그램에 쓰기권한이 없는가?

    소유자외 누구도 프로그램을 변경하길 원하지않는다.

  17. 지정한 프로그램이 setuid나 setgid가 아닌가?

    우리는 프로그램이 다시 UID/GID를 변경하길 원하지않는다.

  18. 지정한 사용자/그룹이 프로그램의 사용자/그룹과 같은가?

    사용자가 파일의 소유자인가?

  19. 안전한 동작을 위해 프로세스의 환경변수를 청소할 수 있는가?

    suEXEC는 (설정에서 정의한) 안전한 실행 PATH를 잡고, (이것도 설정에서 정의) 안전한 환경변수 목록에 열거된 변수만 남기고 프로세스의 환경변수를 지운다.

  20. 성공적으로 지정한 프로그램을 실행할 수 있는가?

    여기서 suEXEC가 끝나고 지정한 프로그램이 시작한다.

이것이 suEXEC wrapper 보안모델의 표준 동작이다. 다소 엄격하고 CGI/SSI 설계에 새로운 제한이 되지만, 보안을 염두에 두고 한단계씩 조심스럽게 만들어졌다.

이 보안 모델이 서버 설정에 어떤 제한을 주는지와 적절한 suEXEC 설정으로 어떤 보안 위험을 피할 수 있는지에 대해 이 문서의 "다시 한번 조심하라" 절을 참고하라.

suEXEC 구성과 설치

이제 재미있는 내용이 시작한다.

suEXEC 구성 옵션

--enable-suexec
이 옵션은 기본적으로 설치되거나 활성화되지않는 suEXEC 기능을 활성화한다. APACI가 suEXEC를 받아들이려면 --enable-suexec 옵션외에 --with-suexec-xxxxx 옵션이 최소한 한개 필요하다.
--with-suexec-bin=PATH
suexec 바이너리 경로는 보안상 이유로 서버에 기록되야 한다. 경로 기본값을 무시하려면 이 옵션을 사용한다. 예를 들어 --with-suexec-bin=/usr/sbin/suexec
--with-suexec-caller=UID
보통 아파치를 실행하는 사용자명. 프로그램을 실행할 수 있는 유일한 사용자다.
--with-suexec-userdir=DIR
suEXEC 접근이 허용되는 사용자 홈디렉토리의 하위디렉토리를 지정한다. 이 디렉토리에 있는 모든 실행파일을 사용자의 suEXEC로 실행므로, 모든 프로그램이 "안전해야" 한다. (예를 들어, 값에 "*"이 없는) "간단한" UserDir 지시어를 사용한다면 같은 값을 설정해야 한다. UserDir 지시어가 passwd 파일에 나온 사용자 홈디렉토리와 다르면 suEXEC는 정상적으로 작동하지 않는다. 기본값은 "public_html"이다.
가상호스트들이 각각 다른 UserDir을 사용한다면 모두 한 부모 디렉토리 안에 있도록 정의해야 하고, 그 부모 디렉토리명을 여기 적는다. 이렇게 정의하지 않으면, "~userdir" cgi 요청이 작동하지 않는다!
--with-suexec-docroot=DIR
아파치의 DocumentRoot를 정의한다. 이는 suEXEC가 사용할 수 있는 (UserDirs을 제외한) 유일한 공간이다. 기본 디렉토리는 --datadir 값에 "/htdocs"을 붙인 것이다. 예를 들어 "--datadir=/home/apache"로 구성했다면 suEXEC wrapper는 document root로 "/home/apache/htdocs" 디렉토리를 사용한다.
--with-suexec-uidmin=UID
suEXEC에서 지정가능한 사용자의 최소 UID를 정의한다. 대부분의 시스템에서 500이나 100이 적절하다. 기본값은 100이다.
--with-suexec-gidmin=GID
suEXEC에서 지정가능한 그룹의 최소 GID를 정의한다. 대부분의 시스템에서 100이 적절하므로 이 값이 기본값이다.
--with-suexec-logfile=FILE
모든 suEXEC 작동과 오류를 (감시나 디버깅 목적에 유용한) 기록할 로그파일명을 지정한다. 기본적으로 로그파일의 이름은 "suexec_log"이고 표준 로그파일 디렉토리에 (--logfiledir) 위치한다.
--with-suexec-safepath=PATH
CGI 실행파일에 넘겨질 안전한 PATH 환경변수를 정의한다. 기본값은 "/usr/local/bin:/usr/bin:/bin"이다.

suEXEC 구성을 점검하라
suEXEC wrapper를 컴파일하고 설치하기 전에 --layout 옵션을 사용하여 설정을 점검할 수 있다.
출력예:

suEXEC setup:
suexec binary: /usr/local/apache/sbin/suexec
document root: /usr/local/apache/share/htdocs
userdir suffix: public_html
logfile: /usr/local/apache/var/log/suexec_log
safe path: /usr/local/bin:/usr/bin:/bin
caller ID: www
minimum user ID: 100
minimum group ID: 100

suEXEC wrapper를 컴파일하고 설치하기
--enable-suexec 옵션으로 suEXEC 기능을 가능하게한 경우 "make" 명령어를 실행하면 suexec 실행파일이 (아파치와 함께) 자동으로 만들어진다.
모든것을 컴파일한 후 "make install" 명령어를 실행하여 설치할 수 있다. 바이너리파일 "suexec"는 --sbindir 옵션으로 지정한 디렉토리에 설치된다. 기본 위치는 "/usr/local/apache/sbin/suexec"이다.
설치 과정에 root 권한이 필요함을 주의하라. wrapper가 사용자 ID를 설정하기위해서는 소유자가 root이고 파일모드로 setuserid 실행비트가 설정되야 한다.

suEXEC 키고 끄기

아파치는 시작할때 "sbin" 디렉토리에서 "suexec" 파일을 (기본값 "/usr/local/apache/sbin/suexec") 찾는다. 아파치가 정상적으로 구성된 suEXEC wrapper를 발견하면 error log에 다음과 같이 출력한다:

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

서버 시작중에 이런 문구를 없다면 서버는 기대한 장소에서 wrapper 프로그램을 찾지 못했거나, 실행파일이 setuid root로 설치되지않았기 때문일 것이다.

처음으로 suEXEC 기능을 사용하고 싶고 이미 아파치 서버가 실행중이라면, 아파치를 죽이고 다시 시작해야 한다. 간단히 HUP이나 USR1 시그널로 재시작하는 것으로는 충분하지 않다.

suEXEC를 안사용하려면 "suexec" 파일을 지운후 아파치를 죽이고 재시작해야 한다.

suEXEC 사용하기

가상호스트:
suEXEC wrapper를 사용하는 한가지 방법은 VirtualHost 정의에 SuexecUserGroup 지시어를 사용하는 것이다. 이 지시어를 주서버 사용자 ID와 다르게 설정하면 CGI 자원의 모든 요청이 <VirtualHost>에서 지정한 User와 Group으로 실행된다. 이 지시어들이 <VirtualHost>에 없으면 주서버 userid를 사용한다.

사용자 디렉토리:
suEXEC wrapper는 CGI 프로그램을 요청을 받은 사용자가 실행하도록 할 수 있다. 이를 위해 실행하길 원하는 사용자 ID 앞에 "~" 문자를 붙이면 된다. 실행을 위해 해당 사용자는 CGI를 실행할 수 있어야 하고, 스크립트가 위의 보안 검사 항목을 만족해야 한다.

suEXEC 디버깅하기

suEXEC wrapper는 로그 정보를 위에서 다룬 --with-suexec-logfile 옵션으로 지정한 파일에 쓴다. wrapper를 올바로 구성하고 설치했다면 어디서 잘못되었는지 이 로그파일와 서버의 error_log를 살펴봐라.

다시 한번 조심하라: 경고와 예제

주의! 이 섹션은 완전하지 않을 수 있다. 아파치그룹의 온라인 문서에서 이 문서의 최신판을 참고하라.

wrapper가 서버 설정을 제약하는 몇가지 흥미로운 점이 있다. suEXEC와 관련된 "버그"를 보고하기 전에 이들을 살펴보길 바란다.

  • suEXEC 제약 사항
  • 디렉토리 구조 제한

    보안과 효율성을 위해 모든 suexec 요청은 가상호스트의 경우 최상위 document root 혹은 userdir 요청의 경우 최상위 개인 document root 안에서 발생해야 한다. 예를 들어, 가상호스트 네개를 설정했다면 가상호스트에서 suEXEC를 이용하기위해 가상호스트의 document root를 주 아파치 문서 계층구조 밖에 설정할 필요가 있다. (예제는 다음에.)

  • suEXEC의 PATH 환경변수

    변경하면 위험할 수 있다. 여기에 포함하는 모든 경로가 믿을 수 있는 디렉토리인지 확인하라. 이 지구상의 누군가가 그곳에 있는 트로이목마를 실행하길 원하지 않을 것이다.

  • suEXEC 코드 수정하기

    반복해서 말하지만, 당신이 무엇을 하는지 모르고 시도한다면 큰 문제가 발생할 수 있다. 어떤 경우에도 수정하지마라.


Apache Performance Tuning - Apache HTTP Server

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

Apache Performance Tuning

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

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

Hardware and Operating System Issues

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

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

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

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

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

Run-Time Configuration Issues

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

HostnameLookups and other DNS considerations

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

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

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

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

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

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

FollowSymLinks and SymLinksIfOwnerMatch

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

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

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

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

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

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

AllowOverride

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

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

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

Negotiation

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

DirectoryIndex index

Use a complete list of options:

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

where you list the most common choice first.

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

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

Memory-mapping

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

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

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

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

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

Sendfile

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

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

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

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

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

Process Creation

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

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

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

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

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

Compile-Time Configuration Issues

Choosing an MPM

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

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

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

Modules

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

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

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

Atomic Operations

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

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

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

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

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

mod_status and ExtendedStatus On

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

accept Serialization - multiple sockets

Warning:

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

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

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

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

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

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

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

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

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

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

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

AcceptMutex flock

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

AcceptMutex fcntl

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

AcceptMutex sysvsem

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

AcceptMutex pthread

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

AcceptMutex posixsem

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

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

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

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

accept Serialization - single socket

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

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

Lingering Close

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

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

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

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

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

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

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

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

close (s);
 }

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

Scoreboard File

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

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

DYNAMIC_MODULE_LIMIT

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

Appendix: Detailed Analysis of a Trace

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

truss -l -p httpd_child_pid.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The worker thread reads the request from the client.

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

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

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

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

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

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

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

The worker thread does a lingering close of the connection.

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

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

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

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


URL Rewriting Guide - Apache HTTP Server

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

URL Rewriting Guide

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

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

Introduction to mod_rewrite

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

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

Practical Solutions

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

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

URL Layout

Canonical URLs

Description:

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

Solution:

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

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

Canonical Hostnames

Description:
...
Solution:
RewriteCond %{HTTP_HOST}   !^fully\.qualified\.domain\.name [NC]
RewriteCond %{HTTP_HOST}   !^$
RewriteCond %{SERVER_PORT} !^80$
RewriteRule ^/(.*)         http://fully.qualified.domain.name:%{SERVER_PORT}/$1 [L,R]
RewriteCond %{HTTP_HOST}   !^fully\.qualified\.domain\.name [NC]
RewriteCond %{HTTP_HOST}   !^$
RewriteRule ^/(.*)         http://fully.qualified.domain.name/$1 [L,R]

Moved DocumentRoot

Description:

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

Solution:

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

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

Trailing Slash Problem

Description:

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

Solution:

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

So, to do this trick we write:

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

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

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

Webcluster through Homogeneous URL Layout

Description:

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

Solution:

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

user1  server_of_user1
user2  server_of_user2
:      :

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

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

to

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

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

RewriteEngine on

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

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

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

Move Homedirs to Different Webserver

Description:

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

Solution:

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

RewriteEngine on
RewriteRule   ^/~(.+)  http://newserver/~$1  [R,L]

Structured Homedirs

Description:

Some sites with thousands of users usually use a structured homedir layout, i.e. each homedir is in a subdirectory which begins for instance with the first character of the username. So, /~foo/anypath is /home/f/foo/.www/anypath while /~bar/anypath is /home/b/bar/.www/anypath.

Solution:

We use the following ruleset to expand the tilde URLs into exactly the above layout.

RewriteEngine on
RewriteRule   ^/~(([a-z])[a-z0-9]+)(.*)  /home/$2/$1/.www$3

Filesystem Reorganization

Description:

This really is a hardcore example: a killer application which heavily uses per-directory RewriteRules to get a smooth look and feel on the Web while its data structure is never touched or adjusted. Background: net.sw is my archive of freely available Unix software packages, which I started to collect in 1992. It is both my hobby and job to to this, because while I'm studying computer science I have also worked for many years as a system and network administrator in my spare time. Every week I need some sort of software so I created a deep hierarchy of directories where I stored the packages:

drwxrwxr-x   2 netsw  users    512 Aug  3 18:39 Audio/
drwxrwxr-x   2 netsw  users    512 Jul  9 14:37 Benchmark/
drwxrwxr-x  12 netsw  users    512 Jul  9 00:34 Crypto/
drwxrwxr-x   5 netsw  users    512 Jul  9 00:41 Database/
drwxrwxr-x   4 netsw  users    512 Jul 30 19:25 Dicts/
drwxrwxr-x  10 netsw  users    512 Jul  9 01:54 Graphic/
drwxrwxr-x   5 netsw  users    512 Jul  9 01:58 Hackers/
drwxrwxr-x   8 netsw  users    512 Jul  9 03:19 InfoSys/
drwxrwxr-x   3 netsw  users    512 Jul  9 03:21 Math/
drwxrwxr-x   3 netsw  users    512 Jul  9 03:24 Misc/
drwxrwxr-x   9 netsw  users    512 Aug  1 16:33 Network/
drwxrwxr-x   2 netsw  users    512 Jul  9 05:53 Office/
drwxrwxr-x   7 netsw  users    512 Jul  9 09:24 SoftEng/
drwxrwxr-x   7 netsw  users    512 Jul  9 12:17 System/
drwxrwxr-x  12 netsw  users    512 Aug  3 20:15 Typesetting/
drwxrwxr-x  10 netsw  users    512 Jul  9 14:08 X11/

In July 1996 I decided to make this archive public to the world via a nice Web interface. "Nice" means that I wanted to offer an interface where you can browse directly through the archive hierarchy. And "nice" means that I didn't wanted to change anything inside this hierarchy - not even by putting some CGI scripts at the top of it. Why? Because the above structure should be later accessible via FTP as well, and I didn't want any Web or CGI stuff to be there.

Solution:

The solution has two parts: The first is a set of CGI scripts which create all the pages at all directory levels on-the-fly. I put them under /e/netsw/.www/ as follows:

-rw-r--r--   1 netsw  users    1318 Aug  1 18:10 .wwwacl
drwxr-xr-x  18 netsw  users     512 Aug  5 15:51 DATA/
-rw-rw-rw-   1 netsw  users  372982 Aug  5 16:35 LOGFILE
-rw-r--r--   1 netsw  users     659 Aug  4 09:27 TODO
-rw-r--r--   1 netsw  users    5697 Aug  1 18:01 netsw-about.html
-rwxr-xr-x   1 netsw  users     579 Aug  2 10:33 netsw-access.pl
-rwxr-xr-x   1 netsw  users    1532 Aug  1 17:35 netsw-changes.cgi
-rwxr-xr-x   1 netsw  users    2866 Aug  5 14:49 netsw-home.cgi
drwxr-xr-x   2 netsw  users     512 Jul  8 23:47 netsw-img/
-rwxr-xr-x   1 netsw  users   24050 Aug  5 15:49 netsw-lsdir.cgi
-rwxr-xr-x   1 netsw  users    1589 Aug  3 18:43 netsw-search.cgi
-rwxr-xr-x   1 netsw  users    1885 Aug  1 17:41 netsw-tree.cgi
-rw-r--r--   1 netsw  users     234 Jul 30 16:35 netsw-unlimit.lst

The DATA/ subdirectory holds the above directory structure, i.e. the real net.sw stuff and gets automatically updated via rdist from time to time. The second part of the problem remains: how to link these two structures together into one smooth-looking URL tree? We want to hide the DATA/ directory from the user while running the appropriate CGI scripts for the various URLs. Here is the solution: first I put the following into the per-directory configuration file in the DocumentRoot of the server to rewrite the announced URL /net.sw/ to the internal path /e/netsw:

RewriteRule  ^net.sw$       net.sw/        [R]
RewriteRule  ^net.sw/(.*)$  e/netsw/$1

The first rule is for requests which miss the trailing slash! The second rule does the real thing. And then comes the killer configuration which stays in the per-directory config file /e/netsw/.www/.wwwacl:

Options       ExecCGI FollowSymLinks Includes MultiViews

RewriteEngine on

#  we are reached via /net.sw/ prefix
RewriteBase   /net.sw/

#  first we rewrite the root dir to
#  the handling cgi script
RewriteRule   ^$                       netsw-home.cgi     [L]
RewriteRule   ^index\.html$            netsw-home.cgi     [L]

#  strip out the subdirs when
#  the browser requests us from perdir pages
RewriteRule   ^.+/(netsw-[^/]+/.+)$    $1                 [L]

#  and now break the rewriting for local files
RewriteRule   ^netsw-home\.cgi.*       -                  [L]
RewriteRule   ^netsw-changes\.cgi.*    -                  [L]
RewriteRule   ^netsw-search\.cgi.*     -                  [L]
RewriteRule   ^netsw-tree\.cgi$        -                  [L]
RewriteRule   ^netsw-about\.html$      -                  [L]
RewriteRule   ^netsw-img/.*$           -                  [L]

#  anything else is a subdir which gets handled
#  by another cgi script
RewriteRule   !^netsw-lsdir\.cgi.*     -                  [C]
RewriteRule   (.*)                     netsw-lsdir.cgi/$1

Some hints for interpretation:

  1. Notice the L (last) flag and no substitution field ('-') in the forth part
  2. Notice the ! (not) character and the C (chain) flag at the first rule in the last part
  3. Notice the catch-all pattern in the last rule

NCSA imagemap to Apache mod_imap

Description:

When switching from the NCSA webserver to the more modern Apache webserver a lot of people want a smooth transition. So they want pages which use their old NCSA imagemap program to work under Apache with the modern mod_imap. The problem is that there are a lot of hyperlinks around which reference the imagemap program via /cgi-bin/imagemap/path/to/page.map. Under Apache this has to read just /path/to/page.map.

Solution:

We use a global rule to remove the prefix on-the-fly for all requests:

RewriteEngine  on
RewriteRule    ^/cgi-bin/imagemap(.*)  $1  [PT]

Search pages in more than one directory

Description:

Sometimes it is necessary to let the webserver search for pages in more than one directory. Here MultiViews or other techniques cannot help.

Solution:

We program a explicit ruleset which searches for the files in the directories.

RewriteEngine on

#   first try to find it in custom/...
#   ...and if found stop and be happy:
RewriteCond         /your/docroot/dir1/%{REQUEST_FILENAME}  -f
RewriteRule  ^(.+)  /your/docroot/dir1/$1  [L]

#   second try to find it in pub/...
#   ...and if found stop and be happy:
RewriteCond         /your/docroot/dir2/%{REQUEST_FILENAME}  -f
RewriteRule  ^(.+)  /your/docroot/dir2/$1  [L]

#   else go on for other Alias or ScriptAlias directives,
#   etc.
RewriteRule   ^(.+)  -  [PT]

Set Environment Variables According To URL Parts

Description:

Perhaps you want to keep status information between requests and use the URL to encode it. But you don't want to use a CGI wrapper for all pages just to strip out this information.

Solution:

We use a rewrite rule to strip out the status information and remember it via an environment variable which can be later dereferenced from within XSSI or CGI. This way a URL /foo/S=java/bar/ gets translated to /foo/bar/ and the environment variable named STATUS is set to the value "java".

RewriteEngine on
RewriteRule   ^(.*)/S=([^/]+)/(.*)    $1/$3 [E=STATUS:$2]

Virtual User Hosts

Description:

Assume that you want to provide www.username.host.domain.com for the homepage of username via just DNS A records to the same machine and without any virtualhosts on this machine.

Solution:

For HTTP/1.0 requests there is no solution, but for HTTP/1.1 requests which contain a Host: HTTP header we can use the following ruleset to rewrite http://www.username.host.com/anypath internally to /home/username/anypath:

RewriteEngine on
RewriteCond   %{HTTP_HOST}                 ^www\.[^.]+\.host\.com$
RewriteRule   ^(.+)                        %{HTTP_HOST}$1          [C]
RewriteRule   ^www\.([^.]+)\.host\.com(.*) /home/$1$2

Redirect Homedirs For Foreigners

Description:

We want to redirect homedir URLs to another webserver www.somewhere.com when the requesting user does not stay in the local domain ourdomain.com. This is sometimes used in virtual host contexts.

Solution:

Just a rewrite condition:

RewriteEngine on
RewriteCond   %{REMOTE_HOST}  !^.+\.ourdomain\.com$
RewriteRule   ^(/~.+)         http://www.somewhere.com/$1 [R,L]

Redirect Failing URLs To Other Webserver

Description:

A typical FAQ about URL rewriting is how to redirect failing requests on webserver A to webserver B. Usually this is done via ErrorDocument CGI-scripts in Perl, but there is also a mod_rewrite solution. But notice that this performs more poorly than using an ErrorDocument CGI-script!

Solution:

The first solution has the best performance but less flexibility, and is less error safe:

RewriteEngine on
RewriteCond   /your/docroot/%{REQUEST_FILENAME} !-f
RewriteRule   ^(.+)                             http://webserverB.dom/$1

The problem here is that this will only work for pages inside the DocumentRoot. While you can add more Conditions (for instance to also handle homedirs, etc.) there is better variant:

RewriteEngine on
RewriteCond   %{REQUEST_URI} !-U
RewriteRule   ^(.+)          http://webserverB.dom/$1

This uses the URL look-ahead feature of mod_rewrite. The result is that this will work for all types of URLs and is a safe way. But it does a performance impact on the webserver, because for every request there is one more internal subrequest. So, if your webserver runs on a powerful CPU, use this one. If it is a slow machine, use the first approach or better a ErrorDocument CGI-script.

Extended Redirection

Description:

Sometimes we need more control (concerning the character escaping mechanism) of URLs on redirects. Usually the Apache kernels URL escape function also escapes anchors, i.e. URLs like "url#anchor". You cannot use this directly on redirects with mod_rewrite because the uri_escape() function of Apache would also escape the hash character. How can we redirect to such a URL?

Solution:

We have to use a kludge by the use of a NPH-CGI script which does the redirect itself. Because here no escaping is done (NPH=non-parseable headers). First we introduce a new URL scheme xredirect: by the following per-server config-line (should be one of the last rewrite rules):

RewriteRule ^xredirect:(.+) /path/to/nph-xredirect.cgi/$1 \
            [T=application/x-httpd-cgi,L]

This forces all URLs prefixed with xredirect: to be piped through the nph-xredirect.cgi program. And this program just looks like:

#!/path/to/perl
##
##  nph-xredirect.cgi -- NPH/CGI script for extended redirects
##  Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.
##

$| = 1;
$url = $ENV{'PATH_INFO'};

print "HTTP/1.0 302 Moved Temporarily\n";
print "Server: $ENV{'SERVER_SOFTWARE'}\n";
print "Location: $url\n";
print "Content-type: text/html\n";
print "\n";
print "<html>\n";
print "<head>\n";
print "<title>302 Moved Temporarily (EXTENDED)</title>\n";
print "</head>\n";
print "<body>\n";
print "<h1>Moved Temporarily (EXTENDED)</h1>\n";
print "The document has moved <a HREF=\"$url\">here</a>.<p>\n";
print "</body>\n";
print "</html>\n";

##EOF##

This provides you with the functionality to do redirects to all URL schemes, i.e. including the one which are not directly accepted by mod_rewrite. For instance you can now also redirect to news:newsgroup via

RewriteRule ^anyurl  xredirect:news:newsgroup
Notice: You have not to put [R] or [R,L] to the above rule because the xredirect: need to be expanded later by our special "pipe through" rule above.

Archive Access Multiplexer

Description:

Do you know the great CPAN (Comprehensive Perl Archive Network) under http://www.perl.com/CPAN? This does a redirect to one of several FTP servers around the world which carry a CPAN mirror and is approximately near the location of the requesting client. Actually this can be called an FTP access multiplexing service. While CPAN runs via CGI scripts, how can a similar approach implemented via mod_rewrite?

Solution:

First we notice that from version 3.0.0 mod_rewrite can also use the "ftp:" scheme on redirects. And second, the location approximation can be done by a RewriteMap over the top-level domain of the client. With a tricky chained ruleset we can use this top-level domain as a key to our multiplexing map.

RewriteEngine on
RewriteMap    multiplex                txt:/path/to/map.cxan
RewriteRule   ^/CxAN/(.*)              %{REMOTE_HOST}::$1                 [C]
RewriteRule   ^.+\.([a-zA-Z]+)::(.*)$  ${multiplex:$1|ftp.default.dom}$2  [R,L]

##
##  map.cxan -- Multiplexing Map for CxAN
##

de        ftp://ftp.cxan.de/CxAN/
uk        ftp://ftp.cxan.uk/CxAN/
com       ftp://ftp.cxan.com/CxAN/
 :
##EOF##

Time-Dependent Rewriting

Description:

When tricks like time-dependent content should happen a lot of webmasters still use CGI scripts which do for instance redirects to specialized pages. How can it be done via mod_rewrite?

Solution:

There are a lot of variables named TIME_xxx for rewrite conditions. In conjunction with the special lexicographic comparison patterns <STRING, >STRING and =STRING we can do time-dependent redirects:

RewriteEngine on
RewriteCond   %{TIME_HOUR}%{TIME_MIN} >0700
RewriteCond   %{TIME_HOUR}%{TIME_MIN} <1900
RewriteRule   ^foo\.html$             foo.day.html
RewriteRule   ^foo\.html$             foo.night.html

This provides the content of foo.day.html under the URL foo.html from 07:00-19:00 and at the remaining time the contents of foo.night.html. Just a nice feature for a homepage...

Backward Compatibility for YYYY to XXXX migration

Description:

How can we make URLs backward compatible (still existing virtually) after migrating document.YYYY to document.XXXX, e.g. after translating a bunch of .html files to .phtml?

Solution:

We just rewrite the name to its basename and test for existence of the new extension. If it exists, we take that name, else we rewrite the URL to its original state.

#   backward compatibility ruleset for
#   rewriting document.html to document.phtml
#   when and only when document.phtml exists
#   but no longer document.html
RewriteEngine on
RewriteBase   /~quux/
#   parse out basename, but remember the fact
RewriteRule   ^(.*)\.html$              $1      [C,E=WasHTML:yes]
#   rewrite to document.phtml if exists
RewriteCond   %{REQUEST_FILENAME}.phtml -f
RewriteRule   ^(.*)$ $1.phtml                   [S=1]
#   else reverse the previous basename cutout
RewriteCond   %{ENV:WasHTML}            ^yes$
RewriteRule   ^(.*)$ $1.html

Content Handling

From Old to New (intern)

Description:

Assume we have recently renamed the page foo.html to bar.html and now want to provide the old URL for backward compatibility. Actually we want that users of the old URL even not recognize that the pages was renamed.

Solution:

We rewrite the old URL to the new one internally via the following rule:

RewriteEngine  on
RewriteBase    /~quux/
RewriteRule    ^foo\.html$  bar.html

From Old to New (extern)

Description:

Assume again that we have recently renamed the page foo.html to bar.html and now want to provide the old URL for backward compatibility. But this time we want that the users of the old URL get hinted to the new one, i.e. their browsers Location field should change, too.

Solution:

We force a HTTP redirect to the new URL which leads to a change of the browsers and thus the users view:

RewriteEngine  on
RewriteBase    /~quux/
RewriteRule    ^foo\.html$  bar.html  [R]

Browser Dependent Content

Description:

At least for important top-level pages it is sometimes necessary to provide the optimum of browser dependent content, i.e. one has to provide a maximum version for the latest Netscape variants, a minimum version for the Lynx browsers and a average feature version for all others.

Solution:

We cannot use content negotiation because the browsers do not provide their type in that form. Instead we have to act on the HTTP header "User-Agent". The following condig does the following: If the HTTP header "User-Agent" begins with "Mozilla/3", the page foo.html is rewritten to foo.NS.html and and the rewriting stops. If the browser is "Lynx" or "Mozilla" of version 1 or 2 the URL becomes foo.20.html. All other browsers receive page foo.32.html. This is done by the following ruleset:

RewriteCond %{HTTP_USER_AGENT}  ^Mozilla/3.*
RewriteRule ^foo\.html$         foo.NS.html          [L]

RewriteCond %{HTTP_USER_AGENT}  ^Lynx/.*         [OR]
RewriteCond %{HTTP_USER_AGENT}  ^Mozilla/[12].*
RewriteRule ^foo\.html$         foo.20.html          [L]

RewriteRule ^foo\.html$         foo.32.html          [L]

Dynamic Mirror

Description:

Assume there are nice webpages on remote hosts we want to bring into our namespace. For FTP servers we would use the mirror program which actually maintains an explicit up-to-date copy of the remote data on the local machine. For a webserver we could use the program webcopy which acts similar via HTTP. But both techniques have one major drawback: The local copy is always just as up-to-date as often we run the program. It would be much better if the mirror is not a static one we have to establish explicitly. Instead we want a dynamic mirror with data which gets updated automatically when there is need (updated data on the remote host).

Solution:

To provide this feature we map the remote webpage or even the complete remote webarea to our namespace by the use of the Proxy Throughput feature (flag [P]):

RewriteEngine  on
RewriteBase    /~quux/
RewriteRule    ^hotsheet/(.*)$  http://www.tstimpreso.com/hotsheet/$1  [P]

RewriteEngine  on
RewriteBase    /~quux/
RewriteRule    ^usa-news\.html$   http://www.quux-corp.com/news/index.html  [P]

Reverse Dynamic Mirror

Description:
...
Solution:
RewriteEngine on
RewriteCond   /mirror/of/remotesite/$1           -U
RewriteRule   ^http://www\.remotesite\.com/(.*)$ /mirror/of/remotesite/$1

Retrieve Missing Data from Intranet

Description:

This is a tricky way of virtually running a corporate (external) Internet webserver (www.quux-corp.dom), while actually keeping and maintaining its data on a (internal) Intranet webserver (www2.quux-corp.dom) which is protected by a firewall. The trick is that on the external webserver we retrieve the requested data on-the-fly from the internal one.

Solution:

First, we have to make sure that our firewall still protects the internal webserver and that only the external webserver is allowed to retrieve data from it. For a packet-filtering firewall we could for instance configure a firewall ruleset like the following:

ALLOW Host www.quux-corp.dom Port >1024 --> Host www2.quux-corp.dom Port 80
DENY  Host *                 Port *     --> Host www2.quux-corp.dom Port 80

Just adjust it to your actual configuration syntax. Now we can establish the mod_rewrite rules which request the missing data in the background through the proxy throughput feature:

RewriteRule ^/~([^/]+)/?(.*)          /home/$1/.www/$2
RewriteCond %{REQUEST_FILENAME}       !-f
RewriteCond %{REQUEST_FILENAME}       !-d
RewriteRule ^/home/([^/]+)/.www/?(.*) http://www2.quux-corp.dom/~$1/pub/$2 [P]

Load Balancing

Description:

Suppose we want to load balance the traffic to www.foo.com over www[0-5].foo.com (a total of 6 servers). How can this be done?

Solution:

There are a lot of possible solutions for this problem. We will discuss first a commonly known DNS-based variant and then the special one with mod_rewrite:

  1. DNS Round-Robin

    The simplest method for load-balancing is to use the DNS round-robin feature of BIND. Here you just configure www[0-9].foo.com as usual in your DNS with A(address) records, e.g.

    www0   IN  A       1.2.3.1
www1   IN  A       1.2.3.2
www2   IN  A       1.2.3.3
www3   IN  A       1.2.3.4
www4   IN  A       1.2.3.5
www5   IN  A       1.2.3.6

    Then you additionally add the following entry:

    www    IN  CNAME   www0.foo.com.
       IN  CNAME   www1.foo.com.
       IN  CNAME   www2.foo.com.
       IN  CNAME   www3.foo.com.
       IN  CNAME   www4.foo.com.
       IN  CNAME   www5.foo.com.
       IN  CNAME   www6.foo.com.

    Notice that this seems wrong, but is actually an intended feature of BIND and can be used in this way. However, now when www.foo.com gets resolved, BIND gives out www0-www6 - but in a slightly permutated/rotated order every time. This way the clients are spread over the various servers. But notice that this not a perfect load balancing scheme, because DNS resolve information gets cached by the other nameservers on the net, so once a client has resolved www.foo.com to a particular wwwN.foo.com, all subsequent requests also go to this particular name wwwN.foo.com. But the final result is ok, because the total sum of the requests are really spread over the various webservers.

  2. DNS Load-Balancing

    A sophisticated DNS-based method for load-balancing is to use the program lbnamed which can be found at http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html. It is a Perl 5 program in conjunction with auxilliary tools which provides a real load-balancing for DNS.

  3. Proxy Throughput Round-Robin

    In this variant we use mod_rewrite and its proxy throughput feature. First we dedicate www0.foo.com to be actually www.foo.com by using a single

    www    IN  CNAME   www0.foo.com.

    entry in the DNS. Then we convert www0.foo.com to a proxy-only server, i.e. we configure this machine so all arriving URLs are just pushed through the internal proxy to one of the 5 other servers (www1-www5). To accomplish this we first establish a ruleset which contacts a load balancing script lb.pl for all URLs.

    RewriteEngine on
RewriteMap    lb      prg:/path/to/lb.pl
RewriteRule   ^/(.+)$ ${lb:$1}           [P,L]

    Then we write lb.pl:

    #!/path/to/perl
##
##  lb.pl -- load balancing script
##

$| = 1;

$name   = "www";     # the hostname base
$first  = 1;         # the first server (not 0 here, because 0 is myself)
$last   = 5;         # the last server in the round-robin
$domain = "foo.dom"; # the domainname

$cnt = 0;
while (<STDIN>) {
    $cnt = (($cnt+1) % ($last+1-$first));
    $server = sprintf("%s%d.%s", $name, $cnt+$first, $domain);
    print "http://$server/$_";
}

##EOF##
    A last notice: Why is this useful? Seems like www0.foo.com still is overloaded? The answer is yes, it is overloaded, but with plain proxy throughput requests, only! All SSI, CGI, ePerl, etc. processing is completely done on the other machines. This is the essential point.
  4. Hardware/TCP Round-Robin

    There is a hardware solution available, too. Cisco has a beast called LocalDirector which does a load balancing at the TCP/IP level. Actually this is some sort of a circuit level gateway in front of a webcluster. If you have enough money and really need a solution with high performance, use this one.

New MIME-type, New Service

Description:

On the net there are a lot of nifty CGI programs. But their usage is usually boring, so a lot of webmaster don't use them. Even Apache's Action handler feature for MIME-types is only appropriate when the CGI programs don't need special URLs (actually PATH_INFO and QUERY_STRINGS) as their input. First, let us configure a new file type with extension .scgi (for secure CGI) which will be processed by the popular cgiwrap program. The problem here is that for instance we use a Homogeneous URL Layout (see above) a file inside the user homedirs has the URL /u/user/foo/bar.scgi. But cgiwrap needs the URL in the form /~user/foo/bar.scgi/. The following rule solves the problem:

RewriteRule ^/[uge]/([^/]+)/\.www/(.+)\.scgi(.*) ...
... /internal/cgi/user/cgiwrap/~$1/$2.scgi$3  [NS,T=application/x-http-cgi]

Or assume we have some more nifty programs: wwwlog (which displays the access.log for a URL subtree and wwwidx (which runs Glimpse on a URL subtree). We have to provide the URL area to these programs so they know on which area they have to act on. But usually this ugly, because they are all the times still requested from that areas, i.e. typically we would run the swwidx program from within /u/user/foo/ via hyperlink to

/internal/cgi/user/swwidx?i=/u/user/foo/

which is ugly. Because we have to hard-code both the location of the area and the location of the CGI inside the hyperlink. When we have to reorganize the area, we spend a lot of time changing the various hyperlinks.

Solution:

The solution here is to provide a special new URL format which automatically leads to the proper CGI invocation. We configure the following:

RewriteRule   ^/([uge])/([^/]+)(/?.*)/\*  /internal/cgi/user/wwwidx?i=/$1/$2$3/
RewriteRule   ^/([uge])/([^/]+)(/?.*):log /internal/cgi/user/wwwlog?f=/$1/$2$3

Now the hyperlink to search at /u/user/foo/ reads only

HREF="*"

which internally gets automatically transformed to

/internal/cgi/user/wwwidx?i=/u/user/foo/

The same approach leads to an invocation for the access log CGI program when the hyperlink :log gets used.

From Static to Dynamic

Description:

How can we transform a static page foo.html into a dynamic variant foo.cgi in a seamless way, i.e. without notice by the browser/user.

Solution:

We just rewrite the URL to the CGI-script and force the correct MIME-type so it gets really run as a CGI-script. This way a request to /~quux/foo.html internally leads to the invocation of /~quux/foo.cgi.

RewriteEngine  on
RewriteBase    /~quux/
RewriteRule    ^foo\.html$  foo.cgi  [T=application/x-httpd-cgi]

On-the-fly Content-Regeneration

Description:

Here comes a really esoteric feature: Dynamically generated but statically served pages, i.e. pages should be delivered as pure static pages (read from the filesystem and just passed through), but they have to be generated dynamically by the webserver if missing. This way you can have CGI-generated pages which are statically served unless one (or a cronjob) removes the static contents. Then the contents gets refreshed.

Solution:
This is done via the following ruleset:
RewriteCond %{REQUEST_FILENAME}   !-s
RewriteRule ^page\.html$          page.cgi   [T=application/x-httpd-cgi,L]

Here a request to page.html leads to a internal run of a corresponding page.cgi if page.html is still missing or has filesize null. The trick here is that page.cgi is a usual CGI script which (additionally to its STDOUT) writes its output to the file page.html. Once it was run, the server sends out the data of page.html. When the webmaster wants to force a refresh the contents, he just removes page.html (usually done by a cronjob).

Document With Autorefresh

Description:

Wouldn't it be nice while creating a complex webpage if the webbrowser would automatically refresh the page every time we write a new version from within our editor? Impossible?

Solution:

No! We just combine the MIME multipart feature, the webserver NPH feature and the URL manipulation power of mod_rewrite. First, we establish a new URL feature: Adding just :refresh to any URL causes this to be refreshed every time it gets updated on the filesystem.

RewriteRule   ^(/[uge]/[^/]+/?.*):refresh  /internal/cgi/apache/nph-refresh?f=$1

Now when we reference the URL

/u/foo/bar/page.html:refresh

this leads to the internal invocation of the URL

/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html

The only missing part is the NPH-CGI script. Although one would usually say "left as an exercise to the reader" ;-) I will provide this, too.

#!/sw/bin/perl
##
##  nph-refresh -- NPH/CGI script for auto refreshing pages
##  Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.
##
$| = 1;

#   split the QUERY_STRING variable
@pairs = split(/&/, $ENV{'QUERY_STRING'});
foreach $pair (@pairs) {
    ($name, $value) = split(/=/, $pair);
    $name =~ tr/A-Z/a-z/;
    $name = 'QS_' . $name;
    $value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
    eval "\$$name = \"$value\"";
}
$QS_s = 1 if ($QS_s eq '');
$QS_n = 3600 if ($QS_n eq '');
if ($QS_f eq '') {
    print "HTTP/1.0 200 OK\n";
    print "Content-type: text/html\n\n";
    print "&lt;b&gt;ERROR&lt;/b&gt;: No file given\n";
    exit(0);
}
if (! -f $QS_f) {
    print "HTTP/1.0 200 OK\n";
    print "Content-type: text/html\n\n";
    print "&lt;b&gt;ERROR&lt;/b&gt;: File $QS_f not found\n";
    exit(0);
}

sub print_http_headers_multipart_begin {
    print "HTTP/1.0 200 OK\n";
    $bound = "ThisRandomString12345";
    print "Content-type: multipart/x-mixed-replace;boundary=$bound\n";
    &print_http_headers_multipart_next;
}

sub print_http_headers_multipart_next {
    print "\n--$bound\n";
}

sub print_http_headers_multipart_end {
    print "\n--$bound--\n";
}

sub displayhtml {
    local($buffer) = @_;
    $len = length($buffer);
    print "Content-type: text/html\n";
    print "Content-length: $len\n\n";
    print $buffer;
}

sub readfile {
    local($file) = @_;
    local(*FP, $size, $buffer, $bytes);
    ($x, $x, $x, $x, $x, $x, $x, $size) = stat($file);
    $size = sprintf("%d", $size);
    open(FP, "&lt;$file");
    $bytes = sysread(FP, $buffer, $size);
    close(FP);
    return $buffer;
}

$buffer = &readfile($QS_f);
&print_http_headers_multipart_begin;
&displayhtml($buffer);

sub mystat {
    local($file) = $_[0];
    local($time);

    ($x, $x, $x, $x, $x, $x, $x, $x, $x, $mtime) = stat($file);
    return $mtime;
}

$mtimeL = &mystat($QS_f);
$mtime = $mtime;
for ($n = 0; $n &lt; $QS_n; $n++) {
    while (1) {
        $mtime = &mystat($QS_f);
        if ($mtime ne $mtimeL) {
            $mtimeL = $mtime;
            sleep(2);
            $buffer = &readfile($QS_f);
            &print_http_headers_multipart_next;
            &displayhtml($buffer);
            sleep(5);
            $mtimeL = &mystat($QS_f);
            last;
        }
        sleep($QS_s);
    }
}

&print_http_headers_multipart_end;

exit(0);

##EOF##

Mass Virtual Hosting

Description:

The <VirtualHost> feature of Apache is nice and works great when you just have a few dozens virtual hosts. But when you are an ISP and have hundreds of virtual hosts to provide this feature is not the best choice.

Solution:

To provide this feature we map the remote webpage or even the complete remote webarea to our namespace by the use of the Proxy Throughput feature (flag [P]):

##
##  vhost.map
##
www.vhost1.dom:80  /path/to/docroot/vhost1
www.vhost2.dom:80  /path/to/docroot/vhost2
     :
www.vhostN.dom:80  /path/to/docroot/vhostN

##
##  httpd.conf
##
    :
#   use the canonical hostname on redirects, etc.
UseCanonicalName on

    :
#   add the virtual host in front of the CLF-format
CustomLog  /path/to/access_log  "%{VHOST}e %h %l %u %t \"%r\" %>s %b"
    :

#   enable the rewriting engine in the main server
RewriteEngine on

#   define two maps: one for fixing the URL and one which defines
#   the available virtual hosts with their corresponding
#   DocumentRoot.
RewriteMap    lowercase    int:tolower
RewriteMap    vhost        txt:/path/to/vhost.map

#   Now do the actual virtual host mapping
#   via a huge and complicated single rule:
#
#   1. make sure we don't map for common locations
RewriteCond   %{REQUEST_URL}  !^/commonurl1/.*
RewriteCond   %{REQUEST_URL}  !^/commonurl2/.*
    :
RewriteCond   %{REQUEST_URL}  !^/commonurlN/.*
#
#   2. make sure we have a Host header, because
#      currently our approach only supports
#      virtual hosting through this header
RewriteCond   %{HTTP_HOST}  !^$
#
#   3. lowercase the hostname
RewriteCond   ${lowercase:%{HTTP_HOST}|NONE}  ^(.+)$
#
#   4. lookup this hostname in vhost.map and
#      remember it only when it is a path
#      (and not "NONE" from above)
RewriteCond   ${vhost:%1}  ^(/.*)$
#
#   5. finally we can map the URL to its docroot location
#      and remember the virtual host for logging puposes
RewriteRule   ^/(.*)$   %1/$1  [E=VHOST:${lowercase:%{HTTP_HOST}}]
    :

Access Restriction

Blocking of Robots

Description:

How can we block a really annoying robot from retrieving pages of a specific webarea? A /robots.txt file containing entries of the "Robot Exclusion Protocol" is typically not enough to get rid of such a robot.

Solution:

We use a ruleset which forbids the URLs of the webarea /~quux/foo/arc/ (perhaps a very deep directory indexed area where the robot traversal would create big server load). We have to make sure that we forbid access only to the particular robot, i.e. just forbidding the host where the robot runs is not enough. This would block users from this host, too. We accomplish this by also matching the User-Agent HTTP header information.

RewriteCond %{HTTP_USER_AGENT}   ^NameOfBadRobot.*
RewriteCond %{REMOTE_ADDR}       ^123\.45\.67\.[8-9]$
RewriteRule ^/~quux/foo/arc/.+   -   [F]

Blocked Inline-Images

Description:

Assume we have under http://www.quux-corp.de/~quux/ some pages with inlined GIF graphics. These graphics are nice, so others directly incorporate them via hyperlinks to their pages. We don't like this practice because it adds useless traffic to our server.

Solution:

While we cannot 100% protect the images from inclusion, we can at least restrict the cases where the browser sends a HTTP Referer header.

RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !^http://www.quux-corp.de/~quux/.*$ [NC]
RewriteRule .*\.gif$        -                                    [F]

RewriteCond %{HTTP_REFERER}         !^$
RewriteCond %{HTTP_REFERER}         !.*/foo-with-gif\.html$
RewriteRule ^inlined-in-foo\.gif$   -                        [F]

Host Deny

Description:

How can we forbid a list of externally configured hosts from using our server?

Solution:

For Apache >= 1.3b6:

RewriteEngine on
RewriteMap    hosts-deny  txt:/path/to/hosts.deny
RewriteCond   ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND [OR]
RewriteCond   ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND
RewriteRule   ^/.*  -  [F]

For Apache <= 1.3b6:

RewriteEngine on
RewriteMap    hosts-deny  txt:/path/to/hosts.deny
RewriteRule   ^/(.*)$ ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND}/$1
RewriteRule   !^NOT-FOUND/.* - [F]
RewriteRule   ^NOT-FOUND/(.*)$ ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND}/$1
RewriteRule   !^NOT-FOUND/.* - [F]
RewriteRule   ^NOT-FOUND/(.*)$ /$1

##
##  hosts.deny
##
##  ATTENTION! This is a map, not a list, even when we treat it as such.
##             mod_rewrite parses it for key/value pairs, so at least a
##             dummy value "-" must be present for each entry.
##

193.102.180.41 -
bsdti1.sdm.de  -
192.76.162.40  -

Proxy Deny

Description:

How can we forbid a certain host or even a user of a special host from using the Apache proxy?

Solution:

We first have to make sure mod_rewrite is below(!) mod_proxy in the Configuration file when compiling the Apache webserver. This way it gets called before mod_proxy. Then we configure the following for a host-dependent deny...

RewriteCond %{REMOTE_HOST} ^badhost\.mydomain\.com$
RewriteRule !^http://[^/.]\.mydomain.com.*  - [F]

...and this one for a user@host-dependent deny:

RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST}  ^badguy@badhost\.mydomain\.com$
RewriteRule !^http://[^/.]\.mydomain.com.*  - [F]

Special Authentication Variant

Description:

Sometimes a very special authentication is needed, for instance a authentication which checks for a set of explicitly configured users. Only these should receive access and without explicit prompting (which would occur when using the Basic Auth via mod_auth).

Solution:

We use a list of rewrite conditions to exclude all except our friends:

RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} !^friend1@client1.quux-corp\.com$
RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} !^friend2@client2.quux-corp\.com$
RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} !^friend3@client3.quux-corp\.com$
RewriteRule ^/~quux/only-for-friends/      -                                 [F]

Referer-based Deflector

Description:

How can we program a flexible URL Deflector which acts on the "Referer" HTTP header and can be configured with as many referring pages as we like?

Solution:

Use the following really tricky ruleset...

RewriteMap  deflector txt:/path/to/deflector.map

RewriteCond %{HTTP_REFERER} !=""
RewriteCond ${deflector:%{HTTP_REFERER}} ^-$
RewriteRule ^.* %{HTTP_REFERER} [R,L]

RewriteCond %{HTTP_REFERER} !=""
RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND
RewriteRule ^.* ${deflector:%{HTTP_REFERER}} [R,L]

... in conjunction with a corresponding rewrite map:

##
##  deflector.map
##

http://www.badguys.com/bad/index.html    -
http://www.badguys.com/bad/index2.html   -
http://www.badguys.com/bad/index3.html   http://somewhere.com/

This automatically redirects the request back to the referring page (when "-" is used as the value in the map) or to a specific URL (when an URL is specified in the map as the second argument).

Other

External Rewriting Engine

Description:

A FAQ: How can we solve the FOO/BAR/QUUX/etc. problem? There seems no solution by the use of mod_rewrite...

Solution:

Use an external RewriteMap, i.e. a program which acts like a RewriteMap. It is run once on startup of Apache receives the requested URLs on STDIN and has to put the resulting (usually rewritten) URL on STDOUT (same order!).

RewriteEngine on
RewriteMap    quux-map       prg:/path/to/map.quux.pl
RewriteRule   ^/~quux/(.*)$  /~quux/${quux-map:$1}

#!/path/to/perl

#   disable buffered I/O which would lead
#   to deadloops for the Apache server
$| = 1;

#   read URLs one per line from stdin and
#   generate substitution URL on stdout
while (<>) {
    s|^foo/|bar/|;
    print $_;
}

This is a demonstration-only example and just rewrites all URLs /~quux/foo/... to /~quux/bar/.... Actually you can program whatever you like. But notice that while such maps can be used also by an average user, only the system administrator can define it.


아파치 가상호스트 문서 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

아파치 가상호스트 문서

가상호스트 (Virtual Host)는 한 컴퓨터에서 여러 웹사이트를 (예를 들어, www.company1.com과 www.company2.com) 서비스함을 뜻한다. 가상호스트에는 각 웹사이트마다 다른 IP 주소를 사용하는 "IP기반 (IP-based)" 방식과 한 IP 주소당 여러 이름을 가지는 "이름기반 (name-based)" 방식이 있다. 여러 사이트들이 같은 서버에서 돌고있다는 사실을 웹사용자는 눈치채지 못한다.

아파치는 기본으로 IP기반 가상호스트를 지원한 초창기 서버들중 하나다. 아파치 버전 1.1 이상은 IP기반과 이름기반 가상호스트를 모두 지원한다. 이름기반 가상호스트를 호스트기반 (host-based) 또는 비IP 가상호스트 (non-IP virtual hosts)라고도 부른다.

다음은 아파치 버전 1.3 이상의 가상호스트 지원을 자세히 설명한 문서들이다.

참고

  • mod_vhost_alias
  • 이름기반 가상호스트
  • IP기반 가상호스트
  • 가상호스트 예
  • 파일기술자 한계
  • 대량의 가상호스트
  • 가상호스트 찾기에 대한 자세한 설명

가상호스트 지원

  • 이름기반 가상호스트 (IP 주소당 여러 웹사이트)
  • IP기반 가상호스트 (각 웹사이트마다 IP 주소)
  • 일반적인 가상호스트 예
  • 파일기술자(file descriptor) 한계 (즉, 너무 많은 로그파일)
  • 대량의 가상호스트를 동적으로 설정하기
  • 가상호스트 찾기에 대한 자세한 설명

설정 지시어

  • <VirtualHost>
  • NameVirtualHost
  • ServerName
  • ServerAlias
  • ServerPath

가상호스트 설정을 테스트할때 아파치의 -S 명령행 옵션이 유용하다. 즉, 다음과 같이 실행한다:

/usr/local/apache2/bin/httpd -S

이 명령어는 아파치가 읽은 설정파일에 대한 정보를 출력한다. IP 주소와 서버명을 자세히 살펴보면 설정에서 실수를 발견하는데 도움이 될 것이다. (다른 명령행 옵션들은 httpd 프로그램 문서를 참고하라.)


이름기반 가상호스트 지원 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 가상호스트

이름기반 가상호스트 지원

이 문서는 이름기반 가상호스트를 사용하는 경우와 방법을 설명한다.

참고

  • IP기반 가상호스트 지원
  • 가상호스트 찾기에 대한 자세한 설명
  • 대량의 가상호스트를 동적으로 설정하기
  • 일반적인 가상호스트 예
  • ServerPath 설정 예

이름기반 대 IP기반 가상호스트

IP기반 가상호스트는 연결한 IP 주소를 가지고 서비스할 가상호스트를 결정한다. 그래서 각 호스트는 서로 다른 IP 주소를 가져야 한다. 이름기반 가상호스트의 경우 서버는 클라이언트가 HTTP 헤더로 호스트명을 알려주길 바란다. 이런 방법으로 한 IP 주소로 여러 다른 호스트를 서비스할 수 있다.

이름기반 가상호스트는 DNS 서버가 각 호스트명이 올바른 IP 주소로 대응하도록 가상호스트를 설정하고, 다른 호스트명을 구별할 수 있도록 아파치 웹서버를 설정하기만 하면되므로 더 간단하다. 이름기반 가상호스트는 또 여러 IP 주소가 필요없다. 그러므로 특별히 IP기반 가상호스트를 선택할 이유가 없다면 이름기반 가상호스트를 사용해야 한다. IP기반 가상호스트를 사용해야할 이유로는:

  • 이름기반 가상호스트를 지원하지않는 오래된 클라이언트들이 있다. 이름기반 가상호스트를 사용하려면 클라이언트가 HTTP Host 헤더를 보내야 한다. 이는 HTTP/1.1에서는 필수이고, 최근 모든 HTTP/1.0 브라우저들도 확장으로 지원한다. 만약 이름기반 가상호스트를 사용하면서 오래된 클라이언트를 지원해야 한다면 이 문서 끝에 있는 방법을 살펴봐라.
  • SSL 프로토콜의 성격상 SSL 보안서버에서 이름기반 가상호스트를 사용할 수 없다.
  • 어떤 운영체제나 네트웍 장치는 다른 IP 주소를 사용하지 않으면 호스트를 구별하지 못하는 네트웍 사용량(bandwidth) 관리기술을 사용한다.

이름기반 가상호스트 사용하기

관련된 모듈 관련된 지시어
  • core
  • DocumentRoot
  • NameVirtualHost
  • ServerAlias
  • ServerName
  • ServerPath
  • VirtualHost

이름기반 가상호스트를 사용하려면 서버는 연결을 받을 IP 주소를 (아마 포트도) 정해야 한다. 이는 NameVirtualHost 지시어로 가능하다. 일반적으로 서버의 모든 IP 주소를 사용한다면 NameVirtualHost의 아규먼트로 *를 사용한다. NameVirtualHost 지시어에 IP 주소를 적어주었다고 서버가 자동으로 그 IP 주소를 기다리지 않음을 주의하라. 자세한 내용은 아파치가 사용할 주소와 포트 설정하기를 참고하라. 또, 여기서 지정한 IP 주소는 서버의 네트웍 인터페이스이어야 한다.

다음 단계는 서비스하려는 호스트별로 <VirtualHost> 블록을 만드는 일이다. <VirtualHost> 지시어의 아규먼트는 NameVirtualHost 지시어의 아규먼트(예를 들어, IP 주소나 모든 주소를 뜻하는 *)와 같아야 한다. <VirtualHost> 블록 안에는 최소한 서비스할 호스트를 지정하는 ServerName 지시어와 호스트의 내용이 파일시스템 어디에 있는지를 지정하는 DocumentRoot 지시어가 필요하다.

주 호스트가 없어진다

기존에 사용하던 웹서버에 가상호스트를 추가한다면 기존에 사용하던 호스트에 대한 <VirtualHost> 블록도 추가해야 한다. 이 블록에 포함하는 ServerName과 DocumentRoot는 전체 ServerName과 DocumentRoot와 같아야 한다. 설정파일에서 이 가상호스트를 가장 먼저 적으면 기본 호스트가 된다.

예를 들어 www.domain.tld 도메인을 서비스하고 있었는데 같은 IP 주소에 www.otherdomain.tld란 가상호스트를 추가하고 싶다고 가정하자. httpd.conf에 다음과 같이 추가하면 된다:

NameVirtualHost *

<VirtualHost *>
ServerName www.domain.tld
ServerAlias domain.tld *.domain.tld
DocumentRoot /www/domain
 </VirtualHost>

<VirtualHost *>
ServerName www.otherdomain.tld
DocumentRoot /www/otherdomain
 </VirtualHost>

NameVirtualHost와 <VirtualHost> 지시어 둘 모두 * 대신 직접 IP 주소를 지정할 수도 있다. 예를 들어, 이런식으로 한 IP 주소에 여러 이름기반 가상호스트들을 돌리고, 다른 주소에 IP기반 혹은 이름기반 가상호스트들을 돌릴 수 있다.

어떤 서버는 여러 이름으로 접속할 수 있길 바란다. 이는 <VirtualHost> 섹션 안에 ServerAlias 지시어를 사용하여 가능하다. 예를 들어 위의 첫번째 <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가 서비스한다. 즉, Host: 헤더를 보내는 클라이언트는 http://www.domain.tld/만으로도 접근할 수 있지만, http://www.domain.tld/domain/으로는 모든 클라이언트가 페이지에 접근할 수 있다.

이를 위해 최초의 가상호스트에 있는 페이지에 http://www.domain.tld/domain/으로 가는 링크를 넣는다. 그리고 가상호스트 페이지에서는 상대링크만을 사용한다. (예를 들어, "file.html", "../icons/image.gif", "http://www.domain.tld/domain/misc/file.html"이나 "/domain/misc/file.html"과 같이 앞에 /domain/이 붙은 링크)

조금 규칙이 필요하지만 이 규칙을 따르면 대부분의 경우 요즘 것이나 오래된 것이나 관계없이 모든 브라우저로 페이지를 볼 수 있다.


아파치 IP기반 가상호스트 지원 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 가상호스트

아파치 IP기반 가상호스트 지원

참고

  • 이름기반 가상호스트 지원

시스템 요구사항

IP기반이란 말이 의미하듯이 서버는 IP기반 가상호스트 각각에 대해 다른 IP 주소를 가져야한다. 이는 컴퓨터를 물리적으로 여러 네트웍에 연결하거나, 최근 운영체제에서 지원하는 가상 인터페이스를 (자세한 내용은 시스템 문서를 참고하라. 흔히 "ip aliases"라고 하며, 보통 "ifconfig" 명령어로 만든다) 사용하여 가능하다.

아파치 설정방법

여러 호스트를 지원하도록 아파치를 설정하는 방법은 두가지다. 하나는 각 호스트마다 별도의 웹서버를 실행하는 법이고, 다른 하나는 모든 가상호스트를 지원하는 서버 한개를 실행하는 방법이다.

언제 여러 서버를 사용하나:

  • 회사2의 사용자가 웹이외의 방법으로 회사1의 자료를 읽을 수 없게 하는 등 보안상 구분이 필요한 경우. 이 경우 두 서버를 각각 다른 User, Group, Listen, ServerRoot 설정으로 실행해야 한다.
  • 충분한 메모리가 있고, 컴퓨터의 모든 IP를 기다리기위한 파일기술자(file descriptor) 요구사항도 만족한다. "와일드카드"나 특정 주소를 Listen할 수만 있다. 그래서 어떤 이유에서건 특정 주소를 기다릴 필요가 있다면, (한 웹서버가 한 주소를 제외한 모든 주소를 기다리고 다른 한 웹서버가 제외한 주소를 기다릴 수 있지만) 지정한 주소 모두를 기다려야 한다.

언제 서버 한개를 사용하나:

  • 가상호스트들의 웹서버 설정을 공유할 수 있는 경우.
  • 컴퓨터가 매우 많은 요청을 서비스한다면 여러 서버를 실행하기에 속도 손실이 클 수 있다.

여러 서버를 실행하기

각 가상호스트별로 웹서버를 설치한다. 설정파일의 Listen 지시어에 서버가 서비스할 IP 주소(혹은 가상호스트)를 적어준다. 예를 들면,

Listen www.smallco.com:80

호스트명 보다는 IP 주소를 사용하길 바란다. (DNS 문제 참고)

서버 하나로 가상호스트 실행하기

이 경우 웹서버 한개로 주서버와 모든 가상호스트에 대한 요청을 서비스한다. 설정파일의 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 프로그램을 사용한다면 VirtualHost 지시어 안에 User와 Group을 사용할 수 있다.

보안: 서버를 실행하는 사용자외에 다른 사람에게 로그파일이 있는 디렉토리의 쓰기권한이 있다면 보안 문제를 조심하라. 자세한 내용은 보안 팁을 참고하라.


대량의 가상호스트를 동적으로 설정하기 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 가상호스트

대량의 가상호스트를 동적으로 설정하기

이 문서는 아파치 1.3에서 대량의 가상호스트를 효율적으로 서비스하는 방법을 설명한다.

동기

당신의 httpd.conf에 다음과 같이 서로 비슷한 <VirtualHost> 섹션들을 많이 있다면 여기서 설명하는 방법이 도움이 될 것이다:

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>
# 바보 바보 바보
<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>

기본 개념은 정적인 <VirtualHost> 설정 모두를 동적으로 처리하도록 대체하는 것이다. 그러면 많은 장점이 있다:

  1. 설정파일이 작아져서 아파치가 빨리 시작하고 메모리를 적게 사용한다.
  2. 가상호스트를 추가하기위해 파일시스템에 적당한 디렉토리를 만들고 DNS에 항목을 추가하기만 하면된다. 즉, 아파치를 재설정하고 재시작할 필요가 없다.

단점은 각 가상호스트별로 다른 로그파일을 사용할 수 없다는 점이다. 그러나 매우 많은 가상호스트를 사용한다면 파일기술자를 다 써버리기때문에 서로 다른 로그파일을 사용할 수 없다. 파이프나 fifo로 로그를 보내고, 받는 편에서 로그를 처리하여 나누는 방법이 (통계 등을 모을 수도 있다) 더 낫다.

개요

가상호스트는 IP 주소와 HTTP 요청의 Host: 헤더 정보로 정의한다. 기본적으로 대량의 동적 가상호스트 기술은 자동으로 가상호스트 정보를 요청의 파일경로에 포함한다. 이는 대부분 mod_vhost_alias를 사용하여 쉽게 해결할 수 있지만, 아파치 1.3.6 이하를 사용한다면 mod_rewrite를 사용해야 한다. 이 두 모듈 모두 기본적으로 서버에 포함되지 않는다. 이 방법을 사용하려면 아파치를 구성하고 컴파일할때 포함해야 한다.

동적 가상호스트를 일반적인 가상호스트처럼 보이게하려면 여러가지를 `속여야' 한다. 가장 중요한 것은 아파치가 자기참조 URL 등을 만들때 사용할 서버명이다. 서버명은 ServerName 지시어로 설정하며, CGI에는 SERVER_NAME 환경변수로 주어진다. 실행중 실제 서버명은 UseCanonicalName 설정에 달렸다. UseCanonicalName Off이면 요청의 Host: 헤더 내용이 서버명이 된다. UseCanonicalName DNS이면 가상호스트의 IP 주소를 역DNS 검색하여 서버명을 알아낸다. 전자는 이름기반 동적 가상호스트에서 사용하고, 후자는 IP기반 가상호스트에서 사용한다. Host: 헤더가 없거나 DNS 검색이 실패하여 아파치가 서버명을 알아내지 못하면 ServerName으로 설정한 값을 대신 사용한다.

다른 `속일' 것은 (DocumentRoot로 설정하며, CGI에는 DOCUMENT_ROOT 환경변수로 주어지는) 문서루트이다. 일반적인 경우 core 모듈이 이 설정을 사용하여 URI에 해당하는 파일명을 찾지만, 서버를 동적 가상호스팅을 할때는 다른 모듈이 (mod_vhost_alias나 mod_rewrite) 다른 방법으로 이런 작업을 한다. 두 모듈 모두 DOCUMENT_ROOT 환경변수를 사용하지 않으므로 CGI나 SSI 문서가 이 값을 사용한다면 잘못된 결과를 얻을 수 있다.

간단한 동적 가상호스트

위 동기 절의 가상호스트 설정을 mod_vhost_alias를 사용하여 더 일반적으로 구현했다.

# Host: 헤더에서 서버명을 알아낸다
UseCanonicalName Off

# 첫번째 필드를 사용하여 이 로그를 가상호스트별로 나눌 수 있다
LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
CustomLog logs/access_log vcommon

# 요청을 처리하기위해 파일명에 서버명을 포함한다
VirtualDocumentRoot /www/hosts/%0/docs
VirtualScriptAlias /www/hosts/%0/cgi-bin

이 설정에서 UseCanonicalName Off를 UseCanonicalName DNS로 변경하기만 하면 IP기반 가상호스트가 된다. 가상호스트의 IP 주소를 가지고 파일명에 추가할 서버명을 알 수 있다.

가상으로 호스트하는 홈페이지 시스템

ISP 홈페이지 서버를 위해 위의 설정을 수정했다. 조금 더 복잡한 설정을 사용하면 www.user.isp.com의 문서를 /home/user/에 두는 식으로 서버명의 일부를 가지고 파일명을 만들 수 있다. 이 설정은 cgi-bin을 각 가상호스트가 따로 가지지않고 모든 가상호스트가 같이 사용한다.

# 기본적인 내용은 위와 같다. 그리고

# 파일명에 서버명의 일부를 포함한다
VirtualDocumentRoot /www/hosts/%2/docs

# 하나의 cgi-bin 디렉토리
ScriptAlias /cgi-bin/ /www/std-cgi/

mod_vhost_alias 문서에는 더 복잡한 VirtualDocumentRoot 설정의 예가 있다.

한 서버에 여러 가상호스트 시스템 사용하기

더 복잡한 설정의 예로 아파치의 일반적인 <VirtualHost> 지시어를 사용하여 여러 가상호스트 설정의 범위를 조절할 수 있다. 예를 들어, 다음과 같은 설정은 홈페이지 고객에 IP 주소 한개, 상업적인 고객에게 다른 IP 주소 한개를 부여한다. 물론 이전처럼 <VirtualHost> 설정 섹션에 모두 묶을 수도 있다.

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>

더 효율적인 IP기반 가상호스트

첫번째 예에서 나는 설정을 간단히 IP기반 가상호스트로 바꿀 수 있다고 말했다. 불행히도 그런 설정은 매 요청마다 DNS를 찾아야하므로 매우 비효율적이다. 이름대신 IP 주소로 파일시스템을 구성하고 같은 방식으로 로그를 수정하면 문제를 해결할 수 있다. 아파치는 서버명을 다룰 필요가 없어지고, DNS 검색도 하지 않게 된다.

# IP 주소를 역DNS 검색하여 서버명을 알아낸다
UseCanonicalName DNS

# 로그를 나눌 수 있도록 IP 주소를 포함한다
LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon
CustomLog logs/access_log vcommon

# 파일명에 IP 주소를 포함한다
VirtualDocumentRootIP /www/hosts/%0/docs
VirtualScriptAliasIP /www/hosts/%0/cgi-bin

아파치 이전 버전 사용하기

위 예들은 아파치 버전 1.3.6 이후에 포함된 mod_vhost_alias을 사용한다. mod_vhost_alias가 없는 아파치 버전을 사용한다면 이미 말했듯이 mod_rewrite를 사용하여, 단 Host:-헤더기반 가상호스트만을, 구현할 수 있다.

또 로그에 관하여 주의할 점이 있다. 아파치 1.3.6에서 로그형식 지시어 %V가 포함되었고, 버전 1.3.0 - 1.3.3에서 이 기능을 %v 옵션이 대신 했다. 그러나 버전 1.3.4에는 이런 기능이 없다. 어떤 아파치 버전에서도 .htaccess 파일에서 UseCanonicalName 지시어를 사용할 수 있으므로 로그에 이상한 내용이 기록될 수 있다. 그러므로 가장 좋은 방법은 %{Host}i 지시어를 사용하여 Host: 헤더를 직접 로그에 남기는 것이다. 또, 이 방법은 %V는 포함하지않는 :port를 뒤에 추가할 수 있다.

mod_rewrite를 사용한 간단한 동적 가상호스트

다음은 첫번째 예와 같은 일을 하는 httpd.conf 예이다. 처음 절반은 첫번째 예와 거의 비슷하지만, 이전 버전과의 호환성과 mod_rewrite의 적절한 동작을 위해 수정되었다. 나머지 절반은 실제 작업을 하는 mod_rewrite를 설정한다.

특별히 주의해야 할 사항이 있다. 기본적으로 mod_rewrite는 (mod_alias 등) 다른 URI 번역 모듈 이전에 실행된다. 그래서 다른 URI 번역 모듈들과 같이 동작할 것을 고려하여 mod_rewrite를 설정해야 한다. 또, 동적 가상호스트에서 ScriptAlias과 같은 기능을 위해서는 특별한 작업이 필요하다.

# Host: 헤더에서 서버명을 얻는다
UseCanonicalName Off

# splittable logs
LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon
CustomLog logs/access_log vcommon

<Directory /www/hosts>
# ScriptAlias 식으로 CGI 실행을 강제할 수 없기때문에
# 여기에 ExecCGI를 사용한다
Options FollowSymLinks ExecCGI
 </Directory>

# 이제 어려운 부분이다

RewriteEngine On

# Host: 헤더에서 가져온 서버명에는 대소문자가 뒤섞여있을 수 있다
RewriteMap lowercase int:tolower

## 일반 문서를 먼저 처리한다:
# Alias /icons/ 가 동작하도록 - 다른 alias에 대해서도 반복
RewriteCond %{REQUEST_URI} !^/icons/
# CGI가 동작하도록
RewriteCond %{REQUEST_URI} !^/cgi-bin/
# 특별한 작업
RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1

## 이제 CGI를 처리한다 - MIME type을 강제해야 한다
RewriteCond %{REQUEST_URI} ^/cgi-bin/
RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi]

# 끝!

mod_rewrite를 사용한 홈페이지 시스템

다음은 두번째 예와 같은 일을 한다.

RewriteEngine on

RewriteMap lowercase int:tolower

# CGI가 동작하도록
RewriteCond %{REQUEST_URI} !^/cgi-bin/

# RewriteRule이 동작하도록 호스트명이 올바른지 검사한다
RewriteCond ${lowercase:%{SERVER_NAME}} ^www\.[a-z-]+\.isp\.com$

# 가상호스트명을 URI 앞에 붙인다
# [C]는 이 결과를 가지고 다음 재작성을 수행함을 뜻한다
RewriteRule ^(.+) ${lowercase:%{SERVER_NAME}}$1 [C]

# 이제 실제 파일명을 만든다
RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /home/$1/$2

# 전체 CGI 디렉토리를 정의한다
ScriptAlias /cgi-bin/ /www/std-cgi/

별도의 가상호스트 설정파일 사용하기

다음은 mod_rewrite의 고급 기능을 사용하여 별도의 설정파일을 가지고 가상호스트의 문서루트를 알아낸다. 더 유연하지만 더 복잡한 설정이 필요하다.

vhost.map 파일은 다음과 같다:

www.customer-1.com /www/customers/1
www.customer-2.com /www/customers/2
# ...
www.customer-N.com /www/customers/N

http.conf는 다음과 같다:

RewriteEngine on

RewriteMap lowercase int:tolower

# 대응파일을 정의한다
RewriteMap vhost txt:/www/conf/vhost.map

# 위와 같이 alias들을 처리한다
RewriteCond %{REQUEST_URI} !^/icons/
RewriteCond %{REQUEST_URI} !^/cgi-bin/
RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$
# 파일 내용을 가지고 찾는다
RewriteCond ${vhost:%1} ^(/.*)$
RewriteRule ^/(.*)$ %1/docs/$1

RewriteCond %{REQUEST_URI} ^/cgi-bin/
RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$
RewriteCond ${vhost:%1} ^(/.*)$
RewriteRule ^/(.*)$ %1/cgi-bin/$1


가상호스트 예 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 가상호스트

가상호스트 예

이 문서는 자주 문의되는 가상호스트 질문에 답을 하려고 쓰여졌다. 상황은 이름기반이나 IP기반 가상호스트를 통해 한 서버에서 여러 웹사이트를 서비스하려는 경우이다. 한 프록시 서버 뒤에서 여러 서버를 사용하여 사이트를 운영하는 경우를 다룬 문서도 곧 나올 것이다.

IP 주소 한개에 여러 이름기반 웹사이트 운영하기.

서버에 IP 주소가 한개 있고, DNS에서 여러 주소(CNAMES)가 이 컴퓨터를 가리킨다. 이 컴퓨터에서 www.example1.com과 www.example2.org의 웹서버를 실행하고 싶다.

Note

아파치 서버에 가상호스트 설정을 한다고 그 호스트명에 대한 DNS 항목이 자동이로 생성되지 않는다. 반드시 DNS에 IP 주소를 가리키는 이름이 있어야 한다. 안그러면 아무도 웹사이트를 볼 수 없다. 검사해보기 위해 hosts 파일에 항목을 추가할 수 있지만, 이는 hosts 항목을 가진 컴퓨터에만 반영된다.

서버 설정

# 아파치가 포트 80을 기다린다
Listen 80

# 모든 IP 주소에서 가상호스트 요청을 기다린다
NameVirtualHost *

<VirtualHost *>
DocumentRoot /www/example1
ServerName www.example1.com

# 다른 지시어들도 있다

 </VirtualHost>

<VirtualHost *>
DocumentRoot /www/example2
ServerName www.example2.org

# 다른 지시어들도 있다

 </VirtualHost>

별표는 모든 주소를 가리키므로, 주서버는 어떤 요청도 서비스하지 않는다. www.example1.com이 설정파일에 처음으로 나오므로 가장 높은 우선순위를 가지며, 기본혹은 초기 서버가 된다. 어떤 ServerName 지시어에도 해당되지않는 요청은 첫번째 VirtualHost가 서비스한다.

주의

원한다면 * 대신 시스템의 실제 IP 주소를 사용할 수 있다. 이 경우 VirtualHost의 아규먼트는 NameVirtualHost의 아규먼트와 일치해야 한다:

NameVirtualHost 172.20.30.40

<VirtualHost 172.20.30.40>
# 생략 ...

그러나 ISP에서 동적으로 IP 주소를 가져오는 등 IP 주소를 모르는 경우에는 *를 사용하는 것이 유용하다. *는 모든 IP 주소에 해당하므로, IP 주소가 변경되어도 설정을 변경할 필요가 없다.

거의 대부분의 이름기반 가상호스트 설정은 위와 같다. 예외는 다른 IP 주소나 포트로 다른 내용을 서비스하려는 경우이다.

여러 IP 주소에서 이름기반 호스트.

주의

여기서 설명한 방법은 IP 주소가 몇개라도 적용가능하다.

서버는 IP 주소가 두개있다. 하나에서 (172.20.30.40) "주" 서버 server.domain.com을 서비스하고, 다른 하나에서 (172.20.30.50) 여러 가상호스트를 서비스할 것이다.

서버 설정

Listen 80

# 172.20.30.40에서 실행하는 "주"서버이다
ServerName server.domain.com
DocumentRoot /www/mainserver

# 다른 주소다
NameVirtualHost 172.20.30.50

<VirtualHost 172.20.30.50>
DocumentRoot /www/example1
ServerName www.example1.com

# 다른 지시어들도 있다 ...

 </VirtualHost>

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

# 다른 지시어들도 있다 ...

 </VirtualHost>

172.20.30.50이 아닌 주소에 대한 요청은 주서버가 서비스한다. 호스트명 없이, 즉 Host: 헤더없이 172.20.30.50로 요청하면 www.example1.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없이 <VirtualHost name:port>만 혹은 Listen 지시어만 사용하면 안된다.

서버 설정

Listen 80
Listen 8080

NameVirtualHost 172.20.30.40:80
NameVirtualHost 172.20.30.40:8080

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

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

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

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

IP기반 가상호스트

서버는 각각 www.example1.com과 www.example2.org에 해당하는 두 IP 주소를 (172.20.30.40과 172.20.30.50) 가진다.

서버 설정

Listen 80

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

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

<VirtualHost> 지시어로 지정한 주소에 해당하지않는 주소로 (예를 들어, localhost) 요청이 들어오면 주서버가 있는 경우 주서버가 서비스한다.

포트기반과 ip기반이 혼합된 가상호스트

서버는 각각 www.example1.com과 www.example2.org에 해당하는 두 IP 주소를 (172.20.30.40과 172.20.30.50) 가진다. 각 IP의 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.example1.com
 </VirtualHost>

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

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

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

이름기반과 IP기반이 혼합된 가상호스트

주소중 몇몇은 이름기반 가상호스트로, 다른 것은 IP기반 가상호스트로 서비스하고 싶다.

서버 설정

Listen 80

NameVirtualHost 172.20.30.40

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

<VirtualHost 172.20.30.40>
DocumentRoot /www/example2
ServerName www.example2.org
 </VirtualHost>

<VirtualHost 172.20.30.40>
DocumentRoot /www/example3
ServerName www.example3.net
 </VirtualHost>

# IP-기반
<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>

_default_ 가상호스트 사용하기

모든 포트에 대한 _default_ 가상호스트

어떤 가상호스트에도 해당하지않은 IP 주소와 포트에 대한 모든 요청을 처리하기.

서버 설정

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

default(기본) 가상호스트의 포트로 와일드카드를 사용하여 어떤 요청도 주서버로 못가도록 만든다.

default 가상호스트는 절대로 이름기반 가상호스트가 사용하는 주소/포트로의 요청을 서비스하지 않는다. 알 수 없거나 Host: 헤더가 생략된 요청은 항상 최초의 이름기반 가상호스트(설정파일에서 주소/포트가 처음으로 나온 가상호스트)가 서비스한다.

AliasMatch나 RewriteRule을 사용하여 어떤 요청을 특정 페이지(혹은 스크립트)로 재작성할(rewrite) 수 있다.

여러 포트에 대한 _default_ 가상호스트

위의 경우와 같지만, 서버는 여러 포트를 기다리고 80번 포트에 대해서 추가로 _default_ 가상호스트를 사용하고 싶다.

서버 설정

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

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

80번 포트에 대한 default 가상호스트는 (반드시 와일드카드 포트를 가진 기본 가상호스트 이전에 나와야 한다) 지정하지않은 IP 주소로 보내진 모든 요청을 서비스한다. 주서버는 절대로 요청을 서비스하지 못한다.

한 포트에 대한 _default_ 가상호스트

80번 포트에 대해서만 default 가상호스트를 만들고 싶다.

서버 설정

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

포트 80번에 지정하지않은 주소에 대한 요청은 기본 가상호스트가 서비스하고, 다른 지정하지않은 주소와 포트를 가진 요청은 주 서버가 서비스한다.

이름기반 가상호스트를 IP기반 가상호스트로 옮기기

(이름기반의 첫번째 예에서) 호스트명 www.example2.org에 대한 이름기반 가상호스트는 자신의 IP 주소를 가져야 한다. 이름기반 가상호스트의 이전 IP 주소를 캐싱하는 네임서버나 프록시와의 문제를 피하기위해 옮기는 동안 둘 모두를 서비스하고 싶다.
방법은 VirtualHost 지시어에 새 IP 주소만을 (172.20.30.50) 추가하면되므로 쉽다.

서버 설정

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

NameVirtualHost 172.20.30.40

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

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

이제 (IP기반 가상호스트를 통한) 새로운 주소와 (이름기반 가상호스트를 통한) 이전 주소 모두 가상호스트에 접근할 수 있다.

ServerPath 지시어 사용하기

두 이름기반 가상호스트를 가진 서버가 있다. 올바른 가상호스트를 선택하기위해 클라이언트는 올바른 Host: 헤더를 보내야 한다. 오래된 HTTP/1.0 클라이언트가 이 헤더를 보내지 못하면 아파치는 클라이언트가 어떤 가상호스트를 보려고하는지 알 수 없다 (그래서 최초의 가상호스트가 요청을 서비스한다). 오래된 브라우저와 가능한 호환을 유지하기위해 최초의 가상호스트를 만들고, 여기에 이름기반 가상호스트의 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/에 대한 요청은 항상 subl-가상호스트가 서비스한다.
클라이언트가 올바른 Host: 헤더를 보낸다면, URL http://www.sub1.domain.tld/에 대한 요청은 subl-가상호스트에서만 서비스한다. 만약 Host: 헤더를 보내지않으면 클라이언트는 최초의 호스트에 있는 정보페이지를 보게된다.
여기에 문제가 있음을 주의하라: 클라이언트가 Host: 헤더를 보내지않으면 http://www.sub2.domain.tld/sub1/에 대한 요청도 subl-가상호스트가 서비스한다.
RewriteRule 지시어를 사용하여 올바른 Host: 헤더를 보내는 클라이언트는 (예를 들어, URL 전치사가 있거나 없는) 두 URL을 모두 사용할 수 있다.


가상호스트 찾기에 대한 자세한 설명 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 가상호스트

가상호스트 찾기에 대한 자세한 설명

가상호스트 코드는 아파치 1.3에서 거의 다시 작성되었다. 이 문서는 아파치가 요청을 받으면 어떤 가상호스트가 서비스할지 결정하는 방법을 설명한다. 새로운 NameVirtualHost 지시어를 사용하여 가상호스트 설정이 1.3 버전 이전보다 더 쉽고 안전해졌다.

어떻게 동작하는지 이해하지않고 단지 동작하게만 하고 싶다면, 예제들을 참고하라.

설정파일 읽기

<VirtualHost> 설정을 제외한 설정이 주서버를 만든다. <VirtualHost> 섹션으로 정의한 부분을 가상호스트라고 부른다.

Listen, ServerName, ServerPath, ServerAlias 지시어는 서버 정의 어느곳에서도 사용할 수 있다. 그러나 같은 지시어가 여러번 나오면 (그 서버에서) 마지막 지시어만이 유효하다.

주서버 Listen의 기본값은 80이다. 주서버의 ServerPath나 ServerAlias에는 기본값은 없다. ServerName의 기본값은 서버의 IP 주소이다.

주서버의 Listen 지시어는 두가지 기능을 한다. 첫째는 아파치가 연결할 기본 네트웍 포트를 지정하는 일이다. 둘째는 리다이렉션할 절대 URI에 사용할 포트 번호를 지정하는 일이다.

주서버와 달리 가상호스트의 포트는 아파치가 연결을 기다리는 포트에 영향을 주지 않는다.

VirtualHost 지시어에 포트를 지정할 수 있다. 포트를 지정하지않으면 주서버의 가장 최근 Listen 값을 사용한다. 특별한 포트 *는 어떤 포트라도 지칭하는 와일드카드이다. (DNS 검색 결과의 여러 A 레코드를 포함하여) 가상호스트의 주소를 모두 총칭하여 가상호스트의 주소집합(address set)이라고 부른다.

특정 IP 주소에 대한 NameVirtualHost 지시어가 없다면 그 주소를 포함하는 첫번째 가상호스트를 IP기반 가상호스트로 취급한다. IP 주소에 와일드카드 *를 사용할 수도 있다.

이름기반 가상호스트를 사용한다면 이름기반 가상호스트에 사용할 IP 주소를 NameVirtualHost 지시어에 사용해야 한다. 즉, 설정파일의 NameVirtualHost 지시어에 이름기반 가상호스트의 호스트별명(CNAME)에 해당하는 IP 주소를 지정해야 한다.

특정 IP:포트 쌍에 대해 오직 한 NameVirtualHost 지시어만을 사용한다면, 여러 NameVirtualHost 지시어와 VirtualHost 지시어를 섞어서 사용할 수 있다.

NameVirtualHost와 VirtualHost 지시어의 순서는 중요하지 않기때문에 다음 두 예는 같다 (오직 한 주소집합에 대한 VirtualHost의 순서가 중요하다. 아래 참고):

NameVirtualHost 111.22.33.44
<VirtualHost 111.22.33.44>
# 서버 A
...
</VirtualHost>
<VirtualHost 111.22.33.44>
# 서버 B
...
</VirtualHost>

NameVirtualHost 111.22.33.55
<VirtualHost 111.22.33.55>
# 서버 C
...
</VirtualHost>
<VirtualHost 111.22.33.55>
# 서버 D
...
</VirtualHost>

<VirtualHost 111.22.33.44>
# 서버 A
</VirtualHost>
<VirtualHost 111.22.33.55>
# 서버 C
...
</VirtualHost>
<VirtualHost 111.22.33.44>
# 서버 B
...
</VirtualHost>
<VirtualHost 111.22.33.55>
# 서버 D
...
</VirtualHost>

NameVirtualHost 111.22.33.44
NameVirtualHost 111.22.33.55

(왼쪽 설정이 더 읽기 편하다.)

VirtualHost 지시어를 읽을 다음, 가상호스트 서버는 VirtualHost 지시어에 지정한 포트를 기본 Listen으로 한다.

VirtualHost 지시어의 이름이 모두 같은 주소집합에 속한다면 ServerAlias와 같이 취급한다 (그러나 다른 ServerAlias의 영향을 받지 않는다). 가상호스트에 추가로 사용한 Listen은 주소집합이 지정한 포트에 영향을 주지 않음을 주의하라.

시작할때 IP 주소 목록을 만들어 해쉬테이블에 추가한다. NameVirtualHost 지시어에 IP 주소를 사용하면 목록은 그 IP 주소에 대한 모든 이름기반 가상호스트를 포함한다. 그 주소에 대한 가상호스트가 없다면 NameVirtualHost 지시어를 무시하고 로그에 오류를 기록한다. IP기반 가상호스트는 해쉬테이블에 목록을 추가하지 않는다.

빠른 해쉬함수를 사용하기때문에 요청시 IP 주소를 해싱하는 부담은 거의 없다. 또 해쉬테이블은 IP 주소의 마지막 부분의 차이에 최적화되있다.

가상호스트에 여러 기본값이 설정된다. 특히:

  1. 가상호스트에 ServerAdmin, ResourceConfig, AccessConfig, Timeout, KeepAliveTimeout, KeepAlive, MaxKeepAliveRequests, SendBufferSize 지시어가 없다면 주서버에서 해당 값을 가져온다. (즉, 주서버의 설정값을 사용한다.)
  2. 가상호스트의 디렉토리 기본권한을 정의하는 "참조 기본값(lookup defaults)"은 주서버의 설정과 합쳐진다. 모듈의 디렉토리당 설정(per-directory configuration)도 여기에 해당된다.
  3. 각 모듈의 서버당 설정(per-server config)은 주서버의 설정과 가상호스트의 설정을 합친다.

기본적으로 주서버는 가상호스트를 만드는 "기본" 혹은 "기반"이 된다. 그러나 설정파일에서 주서버를 정의하는 위치는 관계없다. 마지막으로 설정을 합치기 전에 주서버의 모든 설정을 읽어들인다. 그래서 주서버 정의가 가상호스트 정의 뒤에 나와도 가상호스트 정의에 영향을 준다.

주서버에 ServerName이 없다면 웹서버를 실행하는 컴퓨터의 호스트명을 대신 사용한다. 주서버의 ServerName을 DNS 겁색하여 얻은 IP 주소들을 주서버 주소집합이라고 부른다.

이름기반 가상호스트의 ServerName을 정의하지 않으면 가상호스트를 정의하는 VirtualHost에서 처음으로 나온 주소를 기본값으로 사용한다.

특별한 _default_ 와일트카드를 포함하는 가상호스트는 주서버와 같은 ServerName을 가진다.

가상호스트 찾기

서버는 아래와 같은 방법으로 어떤 가상호스트가 요청을 처리할지 결정한다:

해쉬테이블 찾기

클라이언트가 처음 연결하면 연결한 IP 주소를 내부 IP 해쉬테이블에서 찾는다.

IP 주소를 찾을 수 없고 클라이언트가 요청을 보낸 포트에 해당하는 가상호스트가 있다면, _default_ 가상호스트가 요청을 서비스한다. _default_ 가상호스트가 없다면 주서버가 요청을 서비스한다.

해쉬테이블에 IP 주소가 없지만 포트 번호가 NameVirtualHost *에 해당할 수 있다. 이 경우 이름기반 가상호스트처럼 처리한다.

찾았다면 (목록에서 IP 주소에 해당하는 항목을 찾으면), IP기반 가상호스트인지 이름기반 가상호스트인지 결정한다.

IP기반 가상호스트

찾은 항목에 이름 목록이 없다면 IP기반 가상호스트이다. 더 이상 작업이 필요없고, 그 가상호스트가 요청을 처리한다.

이름기반 가상호스트

이름 목록에 한개 이상의 가상호스트 구조가 포함되면 이름기반 가상호스트이다. 이 목록에서 가상호스트들은 설정파일의 VirtualHost 순서대로 위치한다.

목록에서 첫번째 가상호스트(설정파일에서 해당 IP 주소를 포함하는 첫번째 가상호스트)는 가장 높은 우선순위를 가지며, 서버명을 알 수 없거나 Host: 헤더가 없는 요청을 처리한다.

클라이언트가 Host: 헤더를 주면, 목록에서 첫번째로 ServerName이나 ServerAlias가 대응하는 가상호스트가 요청을 서비스한다. Host: 헤더에 포트 번호가 나올 수 있지만, 아파치는 항상 클라이언트가 요청을 보낸 실제 포트를 찾는다.

클라이언트가 Host: 헤더없이 HTTP/1.0 요청을 하면 클라이언트가 어떤 서버에 연결하려는지 알 수 없기때문에 요청의 URI에 해당하는 ServerPath가 있는지 찾는다. 목록에서 제일 먼저 찾은 경로를 사용하고, 그 가상호스트가 요청을 서비스한다.

대응하는 가상호스트를 찾을 수 없다면, (이미 앞에 말했듯이) 클라이언트가 연결한 IP에 대한 목록에서 일치하는 포트 번호를 포함하는 첫번째 가상호스트가 요청을 서비스한다.

지속 연결

IP는 위에서 설명한데로 특정 TCP/IP 세션당 한번만 찾지만, 이름은 KeepAlive/지속 연결동안 매 요청때마다 찾는다. 즉, 클라이언트는 지속 연결동안 여러 이름기반 가상호스트의 페이지를 요청할 수 있다.

절대 URI

요청의 URI가 절대 URI이고 클라이언트가 보낸 요청의 호스트명과 포트가 주서버나 특정 가상호스트에 해당하면, 그 주서버 혹은 가상호스트는 URI 앞의 스킴/호스트명/포트 부분을 제외한 나머지 상대 URI를 서비스한다. 해당하는 주서버나 가상호스트가 없다면 URI를 그대로 두고 요청을 프록시 요청으로 처리한다.

주의

  • 이름기반 가상호스트와 IP기반 가상호스트는 서로에게 영향을 주지 않는다. IP기반 가상호스트를 자신의 이름집합 IP 주소외에 어떤 주소로도 접근할 수 없다. 이름기반 가상호스트도 마찬가지다. 이름기반 가상호스트는 NameVirtualHost 지시어로 정의한 주소집합의 IP 주소를 통해서만 접근할 수 있다.
  • IP기반 가상호스트는 ServerAlias와 ServerPath를 절대로 검사하지 않는다.
  • 설정파일에서 이름기반 가상호스트, IP기반 가상호스트, _default_ 가상호스트, NameVirtualHost 지시어의 순서는 중요하지 않다. 특정 주소집합에 대한 이름기반 가상호스트들의 순서만이 중요하다. 설정파일에서 앞에 나오는 이름기반 가상호스트는 자신이 속한 주소집합에서 가장 높은 우선순위를 가진다.
  • 보안을 위해 Host: 헤더에 포함된 포트 번호는 절대로 사용하지 않는다. 아파치는 항상 클라이언트가 요청을 보낸 실제 포트를 사용한다.
  • (둘 사이를 구별할 Host: 헤더가 없다고 가정하면,) ServerPath 지시어가 설정파일에서 뒤에 나오는 다른 ServerPath 지시어의 앞부분을 지칭하는 경우 항상 앞에 나온 지시어를 사용한다.
  • 두 IP기반 가상호스트가 같은 주소를 가지면, 항상 설정파일에서 앞에 나오는 가상호스트를 사용한다. 이런 일은 아무도 모르게 일어날 수 있다. 서버가 이런 상황을 발견하면 오류 로그파일에 경고를 기록한다.
  • _default_ 가상호스트는 요청의 IP 주소와 포트 번호에 해당하는 가상호스트가 없을때만 요청을 처리한다. 클라이언트가 요청을 보낸 포트 번호가 _default_ 가상호스트의 포트 번호(기본값은 Listen)와 같을때만 요청을 처리한다. 어떤 포트의 요청이라도 잡기위해 (예를 들어, _default_:*) 와일드카드 포트를 사용할 수 있다. NameVirtualHost * 가상호스트도 마찬가지다.
  • 주서버는 클라이언트가 연결한 IP 주소와 포트 번호에 해당하는 (_default_ 가상호스트를 포함하여) 가상호스트가 없을때만 요청을 서비스한다. 즉, 주서버는 (그 포트에 해당하는 _default_ 가상호스트가 없다면) 지정하지않은 주소/포트 쌍에 대한 요청만을 처리한다.
  • 클라이언트가 (예를 들어, NameVirtualHost 지시어에서) 이름기반 가상호스트 주소(와 포트)에 연결한 경우 Host: 헤더를 알 수 없거나 헤더가 없는 요청을 보내면 요청은 절대로 _default_ 가상호스트나 주서버에서 처리하지 않는다.
  • 시작할때 서버가 DNS를 의존하지 않으려면 절대로 VirtualHost 지시어에 DNS 이름을 사용하지마라. 게다가 열거한 모든 도메인의 DNS를 통제하지 않는다면 보안상 위험도 있다. 이에 대한 정보가 있다.
  • 각 가상호스트마다 ServerName를 항상 정의해야 한다. 안그러면 가상호스트마다 DNS를 찾게 된다.

팁

DNS 문제 페이지의 팁에 추가로 아래에 팁이 있다:

  • 모든 주서버 정의를 VirtualHost 정의 앞에 두어라. (그러면 설정을 읽기 편하다. 안그러면 나중에 설정이 합쳐질때 가상호스트들 사이에 섞인 정의가 모든 가상호스트에 영향을 줄 수 있기때문에 혼란스럽다.)
  • 읽기 편하도록 설정에서 해당하는 NameVirtualHost과 VirtualHost 정의들을 묶어라.
  • ServerPath가 다른 ServerPath의 앞부분을 지칭하는 경우를 피하라. 피할 수 없다면 설정파일에서 앞부분이 더 긴 (더 자세한) 가상호스트를 짧은 (덜 자세한) 가상호스트보다 앞에 두어라. (예를 들어, "ServerPath /abc"는 "ServerPath /abc/def" 다음에 두어야 한다.


파일기술자(file descriptor) 한계 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 가상호스트

파일기술자(file descriptor) 한계

가상호스트를 많이 사용하고 각 가상호스트에 서로 다른 로그파일을 지정하면, 아파치가 사용가능한 파일기술자(file descriptor, 흔히 파일핸들(file handle)이라고 부름)를 다 써버릴 수 있다. 아파치가 사용하는 파일기술자의 총 개수는 오류 로그파일당 한개, 다른 로그파일 지시어당 한개, 추가로 내부용도로 10-20개를 더한 수다. 유닉스 운영체제는 프로세스가 사용할 수 있는 파일기술자 개수를 제한한다. 이 한계는 보통 64개로, 보통 이보다 큰 hard-limit까지 늘릴 수 있다.

아파치는 이 한계를 필요한만큼 늘리려고 하지만, 실패하는 경우가 있다:

  1. 시스템이 setrlimit() 시스템호출을 제공하지 않는다.
  2. (Solaris 2.3과 같이) 시스템에서 setrlimit(RLIMIT_NOFILE) 함수가 동작하지 않는다.
  3. 필요한 파일기술자 개수가 hard limit 보다 많다.
  4. (Solaris 2) 시스템이 stdio 스트림을 256이하의 파일기술자만을 사용하도록 제한하는 등 파일기술자에 제약을 가한다.

이 경우 해결책은:

  • 로그파일 개수를 줄인다. <VirtualHost> 섹션에서 로그파일을 지정하지 않고 주 로그파일을 사용한다. (더 자세한 방법은 아래 로그파일 나누기를 참고하라.)
  • 사용하는 시스템이 (위의) 1번째나 2번째 경우에 해당한다면, 다음과 같은 스크립트로 아파치를 시작하기 전에 파일기술자 한계를 늘린다.

    #!/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 로그형식 앞에 (ServerName 지시어에 나오는) 정규 가상호스트를 포함하여 로그파일을 기록한다. (로그파일 사용자정의에 관한 내용은 사용자정의 로그형식을 참고하라.)

로그파일을 (가상호스트당 한 파일씩) 나누고 싶다면 split-logfile 프로그램을 사용한다. 이 프로그램은 아파치 배포본의 support 디렉토리에 있다.

다음과 같이 프로그램을 실행한다:

split-logfile < /logs/multiple_vhost_log

가상호스트 로그파일을 가지고 이 프로그램을 실행하면 로그파일에 나오는 각 가상호스트당 파일을 하나씩 만든다. 각각의 파일명은 hostname.log이다.


DNS와 아파치와 관련된 사항 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

DNS와 아파치와 관련된 사항

이 문서를 한 문장으로 요약할 수 있다. 아파치가 설정파일을 읽을때 DNS를 사용하지않도록 하라. 아파치가 설정파일을 읽는데 DNS가 필요하다면 서버는 신뢰성 문제 (시작이 안될 수도 있다) 혹은 서비스거부 공격과 (사용자가 다른 사용자에 대한 접근을 가로채는 것을 포함하여) 서비스도둑(theft of service) 공격에 시달릴 수 있다.

간단한 예제

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

아파치가 정상적으로 동작하기위해서는 각 가상호스트에 대해 두가지 정보가 절대적으로 필요하다. 이 정보는 ServerName과 서버가 응답할 최소 한개의 IP 주소이다. 이 예는 IP 주소가 없기때문에, 아파치는 DNS를 사용하여 www.abc.dom의 주소를 찾아야 한다. 서버가 설정파일을 읽을때 어떤 이유에서건 DNS를 사용할 수 없다면 가상호스트를 만들 수 없다. 이 가상호스트는 요청에 응답할 수 없다. (아파치 1.2 이전 버전에서는 심지어 서버가 부팅도 안한다.)

www.abc.dom의 주소가 10.0.0.1이라고 가정하자. 그리고 다음 설정을 보라:

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

이제 아파치는 이 가상호스트의 ServerName을 찾기위해 역DNS를 사용해야 한다. 역찾기가 실패하면 아파치는 가상호스트를 부분적으로 끈다. (아파치 1.2 이전 버전에서는 심지어 서버가 부팅도 안한다.) 즉, 이 경우 이름기반 가상호스트라면 가상호스트는 완전히 동작하지않고, ip기반이라면 대부분 동작한다. 그러나 아파치가 서버명을 포함하여 서버의 전체 URL을 만들어야 한다면 정상적인 URL을 만들지 못한다.

아래 경우 이 두가지 문제가 없다.

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

서비스거부 (Denial of Service)

(최소한) 두가지 종류의 서비스거부가 발생할 수 있다. 아파치 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>

당신이 www.abc.dom에 10.0.0.1, www.def.dom에 10.0.0.2를 할당했다고 하자. 또, def.dom은 자체 DNS를 사용한다고 가정하자. 이 설정과 함께 def.dom을 abc.dom으로 가는 모든 통신을 가로챌 수 있는 장소에 두었다. 그렇다면 그들은 www.def.dom을 10.0.0.1로 설정하기만 하면 된다. 그들이 자체 DNS를 사용하기때문에 당신은 그들이 원하는데로 www.def.dom 레코드를 설정하는 것을 막을 수 없다.

(사용자가 http://www.abc.dom/whatever 형식의 URL을 입력하는 경우를 포함하여) 10.0.0.1로 오는 모든 요청을 def.dom 가상호스트가 서비스하게 된다. 왜 이런 일이 일어나는지 이해하려면 아파치가 어떻게 가상호스트로 오는 요청을 처리하는지에 대한 설명이 필요하다. 여기에 대강 설명되있다.

"주서버" 주소

아파치 1.1에서 이름기반 가상호스트 지원이 포함되었기때문에 아파치는 웹서버를 실행하는 호스트의 IP 주소(들)를 알 필요가 생겼다. 이 주소는 (있다면) 전역 ServerName 혹은 C 함수 gethostname으로 (명령프롬프트에 "hostname"을 입력했을때와 같은 결과) 얻는다. 그러면 이 주소로 DNS 검색을 한다. 현재 이 검색은 피할 수 없다.

DNS 서버가 죽어서 이 검색이 실패할 것 같다면 /etc/hosts에 호스트명을 집어넣을 수 있다. (컴퓨터가 정상적으로 부팅되었다면 아마 이미 들어있을 것이다.) 그리고 DNS가 실패하면 서버가 /etc/hosts를 사용하는지 확인하라. 사용하는 운영체제에 따라 /etc/resolv.conf 혹은 /etc/nsswitch.conf를 수정하면 될 것이다.

서버가 어떤 이유에서건 DNS를 검색하면 안된다면 HOSTRESORDER 환경변수를 "local"로 설정하고 아파치를 실행할 수 있다. mod_env를 사용하여 환경을 변경하지 않는다면 이 환경변수는 CGI에도 영향을 준다. 운영체제의 manpage나 FAQ를 참고하는 것이 좋다.

이 문제를 피하기위한 팁

  • VirtualHost에 IP 주소를 사용하라
  • Listen에 IP 주소를 사용하라
  • 모든 가상호스트는 명시적으로 ServerName을 가지게 하라
  • 어떤 페이지도 서비스하지않는 <VirtualHost _default_:*> 서버를 만들어라

부록: 앞으로는

DNS와 관련된 상황은 매우 바람직하지 못하다. 아파치 1.2에서 우리는 DNS가 실패한 경우에도 최소한 서버가 켜지도록 노력했지만 결과는 나빴다. 어쨌든 설정파일에 직접 IP 주소를 요구하는 것은 번호를 다시 설정해야할 요즘 인터넷에 매우 바람직하지 못하다.

위에서 설명한 서비스도둑 공격을 막는 한가지 방법은 검색한 ip 주소에 다시 역DNS 검색을 하여 두 이름을 비교하는 것이다. 서로 다른 경우 가상호스트를 가동하지 않을 수 있다. 이 방법은 역DNS가 올바로 설정되야 한다. (FTP 서버나 TCP wrapper가 "중복-역" DNS 검색을 자주 사용하기때문에 대부분의 관리자에게 익숙할 것이다.)

어쨌든 IP 주소를 사용하지않으면 DNS가 실패한 경우 가상호스트 웹서버를 믿을 수 있게 시작할 수 없다. 설정의 일부를 무시하는 것과 같은 부분적인 해결책은 웹서버 전체를 시작하지않는 것보다 더 나쁠 수도 있다.

HTTP/1.1이 나왔고 브라우저와 프록시가 Host 헤더를 보내기 시작했으므로 IP기반 가상호스트를 완전히 사용하지않는 것이 가능해질 것이다. 그러면 웹서버는 설정중에서 DNS 검색을 할 필요가 없어진다. 그러나 1997년 3월에는 중요한 웹서버에 포함할 정도로 이름기반 가상호스트가 널리 사용되지 않았다.


Frequently Asked Questions - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Frequently Asked Questions

The latest version of this FAQ is always available from the main Apache web site, at <http://httpd.apache.org/docs-2.0/faq/>. In addition, you can view this FAQ all in one page for easy searching and printing.

Since Apache 2.0 is quite new, we don't yet know what the Frequently Asked Questions will be. While this section fills up, you should also consult the Apache 1.3 FAQ to see if your question is answered there.

Topics

Support
What do I do when I have problems?
Error Messages
What does this error message mean?


Frequently Asked Questions - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > FAQ

Frequently Asked Questions

The latest version of this FAQ is always available from the main Apache web site, at <http://httpd.apache.org/docs-2.0/faq/>.

Since Apache 2.0 is quite new, we don't yet know what the Frequently Asked Questions will be. While this section fills up, you should also consult the Apache 1.3 FAQ to see if your question is answered there.

Topics

Support
What do I do when I have problems?
Error Messages
What does this error message mean?

Support

  • "Why can't I ...? Why won't ... work?" What to do in case of problems
  • Whom do I contact for support?

"Why can't I ...? Why won't ... work?" What to do in case of problems

If you are having trouble with your Apache server software, you should take the following steps:

Check the errorlog!
Apache tries to be helpful when it encounters a problem. In many cases, it will provide some details by writing one or messages to the server error log. Sometimes this is enough for you to diagnose & fix the problem yourself (such as file permissions or the like). The default location of the error log is /usr/local/apache2/logs/error_log, but see the ErrorLog directive in your config files for the location on your server.
Check the FAQ!
The latest version of the Apache Frequently-Asked Questions list can always be found at the main Apache web site.
Check the Apache bug database
Most problems that get reported to The Apache Group are recorded in the bug database. Please check the existing reports, open and closed, before adding one. If you find that your issue has already been reported, please don't add a "me, too" report. If the original report isn't closed yet, we suggest that you check it periodically. You might also consider contacting the original submitter, because there may be an email exchange going on about the issue that isn't getting recorded in the database.
Ask in a user support forum

Apache has an active community of users who are willing to share their knowledge. Participating in this community is usually the best and fastest way to get answers to your questions and problems.

Users mailing list

USENET newsgroups:

  • comp.infosystems.www.servers.unix [news] [google]
  • comp.infosystems.www.servers.ms-windows [news] [google]
  • comp.infosystems.www.authoring.cgi [news] [google]
If all else fails, report the problem in the bug database

If you've gone through those steps above that are appropriate and have obtained no relief, then please do let the httpd developers know about the problem by logging a bug report.

If your problem involves the server crashing and generating a core dump, please include a backtrace (if possible). As an example,

# cd ServerRoot
# dbx httpd core
(dbx) where

(Substitute the appropriate locations for your ServerRoot and your httpd and core files. You may have to use gdb instead of dbx.)

Whom do I contact for support?

With several million users and fewer than forty volunteer developers, we cannot provide personal support for Apache. For free support, we suggest participating in a user forum.

Professional, commercial support for Apache is available from a number of companies.

Error Messages

  • Invalid argument: core_output_filter: writing data to the network

Invalid argument: core_output_filter: writing data to the network

Apache uses the sendfile syscall on platforms where it is available in order to speed sending of responses. Unfortunately, on some systems, Apache will detect the presence of sendfile at compile-time, even when it does not work properly. This happens most frequently when using network or other non-standard file-system.

Symptoms of this problem include the above message in the error log and zero-length responses to non-zero-sized files. The problem generally occurs only for static files, since dynamic content usually does not make use of sendfile.

To fix this problem, simply use the EnableSendfile directive to disable sendfile for all or part of your server. Also see the EnableMMAP, which can help with similar problems.


Support - Frequently Asked Questions - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > FAQ

Support - Frequently Asked Questions

Support

  • "Why can't I ...? Why won't ... work?" What to do in case of problems
  • Whom do I contact for support?

"Why can't I ...? Why won't ... work?" What to do in case of problems

If you are having trouble with your Apache server software, you should take the following steps:

Check the errorlog!
Apache tries to be helpful when it encounters a problem. In many cases, it will provide some details by writing one or messages to the server error log. Sometimes this is enough for you to diagnose & fix the problem yourself (such as file permissions or the like). The default location of the error log is /usr/local/apache2/logs/error_log, but see the ErrorLog directive in your config files for the location on your server.
Check the FAQ!
The latest version of the Apache Frequently-Asked Questions list can always be found at the main Apache web site.
Check the Apache bug database
Most problems that get reported to The Apache Group are recorded in the bug database. Please check the existing reports, open and closed, before adding one. If you find that your issue has already been reported, please don't add a "me, too" report. If the original report isn't closed yet, we suggest that you check it periodically. You might also consider contacting the original submitter, because there may be an email exchange going on about the issue that isn't getting recorded in the database.
Ask in a user support forum

Apache has an active community of users who are willing to share their knowledge. Participating in this community is usually the best and fastest way to get answers to your questions and problems.

Users mailing list

USENET newsgroups:

  • comp.infosystems.www.servers.unix [news] [google]
  • comp.infosystems.www.servers.ms-windows [news] [google]
  • comp.infosystems.www.authoring.cgi [news] [google]
If all else fails, report the problem in the bug database

If you've gone through those steps above that are appropriate and have obtained no relief, then please do let the httpd developers know about the problem by logging a bug report.

If your problem involves the server crashing and generating a core dump, please include a backtrace (if possible). As an example,

# cd ServerRoot
# dbx httpd core
(dbx) where

(Substitute the appropriate locations for your ServerRoot and your httpd and core files. You may have to use gdb instead of dbx.)

Whom do I contact for support?

With several million users and fewer than forty volunteer developers, we cannot provide personal support for Apache. For free support, we suggest participating in a user forum.

Professional, commercial support for Apache is available from a number of companies.


Apache SSL/TLS Encryption - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Apache SSL/TLS Encryption

The Apache HTTP Server module mod_ssl provides an interface to the OpenSSL library, which provides Strong Encryption using the Secure Sockets Layer and Transport Layer Security protocols. The module and this documentation are based on Ralf S. Engelschall's mod_ssl project.

Documentation

  • Introduction
  • Compatibility
  • How-To
  • Frequently Asked Questions
  • Glossary

mod_ssl

Extensive documentation on the directives and environment variables provided by this module is provided in the mod_ssl reference documentation.


SSL/TLS Strong Encryption: An Introduction - Apache HTTP Server

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

SSL/TLS Strong Encryption: An Introduction

The nice thing about standards is that there are so many to choose from. And if you really don't like all the standards you just have to wait another year until the one arises you are looking for.

-- A. Tanenbaum, "Introduction to Computer Networks"

As an introduction this chapter is aimed at readers who are familiar with the Web, HTTP, and Apache, but are not security experts. It is not intended to be a definitive guide to the SSL protocol, nor does it discuss specific techniques for managing certificates in an organization, or the important legal issues of patents and import and export restrictions. Rather, it is intended to provide a common background to mod_ssl users by pulling together various concepts, definitions, and examples as a starting point for further exploration.

The presented content is mainly derived, with permission by the author, from the article Introducing SSL and Certificates using SSLeay from Frederick J. Hirsch, of The Open Group Research Institute, which was published in Web Security: A Matter of Trust, World Wide Web Journal, Volume 2, Issue 3, Summer 1997. Please send any positive feedback to Frederick Hirsch (the original article author) and all negative feedback to Ralf S. Engelschall (the mod_ssl author).

Cryptographic Techniques

Understanding SSL requires an understanding of cryptographic algorithms, message digest functions (aka. one-way or hash functions), and digital signatures. These techniques are the subject of entire books (see for instance [AC96]) and provide the basis for privacy, integrity, and authentication.

Cryptographic Algorithms

Suppose Alice wants to send a message to her bank to transfer some money. Alice would like the message to be private, since it will include information such as her account number and transfer amount. One solution is to use a cryptographic algorithm, a technique that would transform her message into an encrypted form, unreadable except by those it is intended for. Once in this form, the message may only be interpreted through the use of a secret key. Without the key the message is useless: good cryptographic algorithms make it so difficult for intruders to decode the original text that it isn't worth their effort.

There are two categories of cryptographic algorithms: conventional and public key.

Conventional cryptography
also known as symmetric cryptography, requires the sender and receiver to share a key: a secret piece of information that may be used to encrypt or decrypt a message. If this key is secret, then nobody other than the sender or receiver may read the message. If Alice and the bank know a secret key, then they may send each other private messages. The task of privately choosing a key before communicating, however, can be problematic.
Public key cryptography
also known as asymmetric cryptography, solves the key exchange problem by defining an algorithm which uses two keys, each of which may be used to encrypt a message. If one key is used to encrypt a message then the other must be used to decrypt it. This makes it possible to receive secure messages by simply publishing one key (the public key) and keeping the other secret (the private key).

Anyone may encrypt a message using the public key, but only the owner of the private key will be able to read it. In this way, Alice may send private messages to the owner of a key-pair (the bank), by encrypting it using their public key. Only the bank will be able to decrypt it.

Message Digests

Although Alice may encrypt her message to make it private, there is still a concern that someone might modify her original message or substitute it with a different one, in order to transfer the money to themselves, for instance. One way of guaranteeing the integrity of Alice's message is to create a concise summary of her message and send this to the bank as well. Upon receipt of the message, the bank creates its own summary and compares it with the one Alice sent. If they agree then the message was received intact.

A summary such as this is called a message digest, one-way function or hash function. Message digests are used to create short, fixed-length representations of longer, variable-length messages. Digest algorithms are designed to produce unique digests for different messages. Message digests are designed to make it too difficult to determine the message from the digest, and also impossible to find two different messages which create the same digest -- thus eliminating the possibility of substituting one message for another while maintaining the same digest.

Another challenge that Alice faces is finding a way to send the digest to the bank securely; when this is achieved, the integrity of the associated message is assured. One way to do this is to include the digest in a digital signature.

Digital Signatures

When Alice sends a message to the bank, the bank needs to ensure that the message is really from her, so an intruder does not request a transaction involving her account. A digital signature, created by Alice and included with the message, serves this purpose.

Digital signatures are created by encrypting a digest of the message, and other information (such as a sequence number) with the sender's private key. Though anyone may decrypt the signature using the public key, only the signer knows the private key. This means that only they may have signed it. Including the digest in the signature means the signature is only good for that message; it also ensures the integrity of the message since no one can change the digest and still sign it.

To guard against interception and reuse of the signature by an intruder at a later date, the signature contains a unique sequence number. This protects the bank from a fraudulent claim from Alice that she did not send the message -- only she could have signed it (non-repudiation).

Certificates

Although Alice could have sent a private message to the bank, signed it, and ensured the integrity of the message, she still needs to be sure that she is really communicating with the bank. This means that she needs to be sure that the public key she is using corresponds to the bank's private key. Similarly, the bank also needs to verify that the message signature really corresponds to Alice's signature.

If each party has a certificate which validates the other's identity, confirms the public key, and is signed by a trusted agency, then they both will be assured that they are communicating with whom they think they are. Such a trusted agency is called a Certificate Authority, and certificates are used for authentication.

Certificate Contents

A certificate associates a public key with the real identity of an individual, server, or other entity, known as the subject. As shown in Table 1, information about the subject includes identifying information (the distinguished name), and the public key. It also includes the identification and signature of the Certificate Authority that issued the certificate, and the period of time during which the certificate is valid. It may have additional information (or extensions) as well as administrative information for the Certificate Authority's use, such as a serial number.

Table 1: Certificate Information

Subject | Distinguished Name, Public Key
Issuer | Distinguished Name, Signature
Period of Validity | Not Before Date, Not After Date
Administrative Information | Version, Serial Number
Extended Information | Basic Constraints, Netscape Flags, etc.

A distinguished name is used to provide an identity in a specific context -- for instance, an individual might have a personal certificate as well as one for their identity as an employee. Distinguished names are defined by the X.509 standard [X509], which defines the fields, field names, and abbreviations used to refer to the fields (see Table 2).

Table 2: Distinguished Name Information

DN Field | Abbrev. | Description | Example
Common Name | CN | Name being certified | CN=Joe Average
Organization or Company | O | Name is associated with this organization | O=Snake Oil, Ltd.
Organizational Unit | OU | Name is associated with this organization unit, such as a department | OU=Research Institute
City/Locality | L | Name is located in this City | L=Snake City
State/Province | ST | Name is located in this State/Province | ST=Desert
Country | C | Name is located in this Country (ISO code) | C=XZ

A Certificate Authority may define a policy specifying which distinguished field names are optional, and which are required. It may also place requirements upon the field contents, as may users of certificates. As an example, a Netscape browser requires that the Common Name for a certificate representing a server has a name which matches a wildcard pattern for the domain name of that server, such as *.snakeoil.com.

The binary format of a certificate is defined using the ASN.1 notation [X208] [PKCS]. This notation defines how to specify the contents, and encoding rules define how this information is translated into binary form. The binary encoding of the certificate is defined using Distinguished Encoding Rules (DER), which are based on the more general Basic Encoding Rules (BER). For those transmissions which cannot handle binary, the binary form may be translated into an ASCII form by using Base64 encoding [MIME]. This encoded version is called PEM encoded (the name comes from "Privacy Enhanced Mail"), when placed between begin and end delimiter lines as illustrated in the following example.

Example of a PEM-encoded certificate (snakeoil.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-----

Certificate Authorities

By first verifying the information in a certificate request before granting the certificate, the Certificate Authority assures the identity of the private key owner of a key-pair. For instance, if Alice requests a personal certificate, the Certificate Authority must first make sure that Alice really is the person the certificate request claims.

Certificate Chains

A Certificate Authority may also issue a certificate for another Certificate Authority. When examining a certificate, Alice may need to examine the certificate of the issuer, for each parent Certificate Authority, until reaching one which she has confidence in. She may decide to trust only certificates with a limited chain of issuers, to reduce her risk of a "bad" certificate in the chain.

Creating a Root-Level CA

As noted earlier, each certificate requires an issuer to assert the validity of the identity of the certificate subject, up to the top-level Certificate Authority (CA). This presents a problem: Since this is who vouches for the certificate of the top-level authority, which has no issuer? In this unique case, the certificate is "self-signed", so the issuer of the certificate is the same as the subject. As a result, one must exercise extra care in trusting a self-signed certificate. The wide publication of a public key by the root authority reduces the risk in trusting this key -- it would be obvious if someone else publicized a key claiming to be the authority. Browsers are preconfigured to trust well-known certificate authorities.

A number of companies, such as Thawte and VeriSign have established themselves as Certificate Authorities. These companies provide the following services:

  • Verifying certificate requests
  • Processing certificate requests
  • Issuing and managing certificates

It is also possible to create your own Certificate Authority. Although risky in the Internet environment, it may be useful within an Intranet where the organization can easily verify the identities of individuals and servers.

Certificate Management

Establishing a Certificate Authority is a responsibility which requires a solid administrative, technical, and management framework. Certificate Authorities not only issue certificates, they also manage them -- that is, they determine how long certificates are valid, they renew them, and they keep lists of certificates that have already been issued but are no longer valid (Certificate Revocation Lists, or CRLs). Say Alice is entitled to a certificate as an employee of a company. Say too, that the certificate needs to be revoked when Alice leaves the company. Since certificates are objects that get passed around, it is impossible to tell from the certificate alone that it has been revoked. When examining certificates for validity, therefore, it is necessary to contact the issuing Certificate Authority to check CRLs -- this is not usually an automated part of the process.

Note

If you use a Certificate Authority that is not configured into browsers by default, it is necessary to load the Certificate Authority certificate into the browser, enabling the browser to validate server certificates signed by that Certificate Authority. Doing so may be dangerous, since once loaded, the browser will accept all certificates signed by that Certificate Authority.

Secure Sockets Layer (SSL)

The Secure Sockets Layer protocol is a protocol layer which may be placed between a reliable connection-oriented network layer protocol (e.g. TCP/IP) and the application protocol layer (e.g. HTTP). SSL provides for secure communication between client and server by allowing mutual authentication, the use of digital signatures for integrity, and encryption for privacy.

The protocol is designed to support a range of choices for specific algorithms used for cryptography, digests, and signatures. This allows algorithm selection for specific servers to be made based on legal, export or other concerns, and also enables the protocol to take advantage of new algorithms. Choices are negotiated between client and server at the start of establishing a protocol session.

Table 4: Versions of the SSL protocol

Version | Source | Description | Browser Support
SSL v2.0 | Vendor Standard (from Netscape Corp.) [SSL2] | First SSL protocol for which implementations exists | - NS Navigator 1.x/2.x - MS IE 3.x - Lynx/2.8+OpenSSL
SSL v3.0 | Expired Internet Draft (from Netscape Corp.) [SSL3] | Revisions to prevent specific security attacks, add non-RSA ciphers, and support for certificate chains | - NS Navigator 2.x/3.x/4.x - MS IE 3.x/4.x - Lynx/2.8+OpenSSL
TLS v1.0 | Proposed Internet Standard (from IETF) [TLS1] | Revision of SSL 3.0 to update the MAC layer to HMAC, add block padding for block ciphers, message order standardization and more alert messages. | - Lynx/2.8+OpenSSL

There are a number of versions of the SSL protocol, as shown in Table 4. As noted there, one of the benefits in SSL 3.0 is that it adds support of certificate chain loading. This feature allows a server to pass a server certificate along with issuer certificates to the browser. Chain loading also permits the browser to validate the server certificate, even if Certificate Authority certificates are not installed for the intermediate issuers, since they are included in the certificate chain. SSL 3.0 is the basis for the Transport Layer Security [TLS] protocol standard, currently in development by the Internet Engineering Task Force (IETF).

Session Establishment

The SSL session is established by following a handshake sequence between client and server, as shown in Figure 1. This sequence may vary, depending on whether the server is configured to provide a server certificate or request a client certificate. Though cases exist where additional handshake steps are required for management of cipher information, this article summarizes one common scenario: see the SSL specification for the full range of possibilities.

Note

Once an SSL session has been established it may be reused, thus avoiding the performance penalty of repeating the many steps needed to start a session. For this the server assigns each SSL session a unique session identifier which is cached in the server and which the client can use on forthcoming connections to reduce the handshake (until the session identifer expires in the cache of the server).

Figure 1: Simplified SSL Handshake Sequence

The elements of the handshake sequence, as used by the client and server, are listed below:

  1. Negotiate the Cipher Suite to be used during data transfer
  2. Establish and share a session key between client and server
  3. Optionally authenticate the server to the client
  4. Optionally authenticate the client to the server

The first step, Cipher Suite Negotiation, allows the client and server to choose a Cipher Suite supportable by both of them. The SSL3.0 protocol specification defines 31 Cipher Suites. A Cipher Suite is defined by the following components:

  • Key Exchange Method
  • Cipher for Data Transfer
  • Message Digest for creating the Message Authentication Code (MAC)

These three elements are described in the sections that follow.

Key Exchange Method

The key exchange method defines how the shared secret symmetric cryptography key used for application data transfer will be agreed upon by client and server. SSL 2.0 uses RSA key exchange only, while SSL 3.0 supports a choice of key exchange algorithms including the RSA key exchange when certificates are used, and Diffie-Hellman key exchange for exchanging keys without certificates and without prior communication between client and server.

One variable in the choice of key exchange methods is digital signatures -- whether or not to use them, and if so, what kind of signatures to use. Signing with a private key provides assurance against a man-in-the-middle-attack during the information exchange used in generating the shared key [AC96, p516].

Cipher for Data Transfer

SSL uses the conventional cryptography algorithm (symmetric cryptography) described earlier for encrypting messages in a session. There are nine choices, including the choice to perform no encryption:

  • No encryption
  • Stream Ciphers
    • RC4 with 40-bit keys
    • RC4 with 128-bit keys
  • CBC Block Ciphers
    • RC2 with 40 bit key
    • DES with 40 bit key
    • DES with 56 bit key
    • Triple-DES with 168 bit key
    • Idea (128 bit key)
    • Fortezza (96 bit key)

Here "CBC" refers to Cipher Block Chaining, which means that a portion of the previously encrypted cipher text is used in the encryption of the current block. "DES" refers to the Data Encryption Standard [AC96, ch12], which has a number of variants (including DES40 and 3DES_EDE). "Idea" is one of the best and cryptographically strongest available algorithms, and "RC2" is a proprietary algorithm from RSA DSI [AC96, ch13].

Digest Function

The choice of digest function determines how a digest is created from a record unit. SSL supports the following:

  • No digest (Null choice)
  • MD5, a 128-bit hash
  • Secure Hash Algorithm (SHA-1), a 160-bit hash

The message digest is used to create a Message Authentication Code (MAC) which is encrypted with the message to provide integrity and to prevent against replay attacks.

Handshake Sequence Protocol

The handshake sequence uses three protocols:

  • The SSL Handshake Protocol for performing the client and server SSL session establishment.
  • The SSL Change Cipher Spec Protocol for actually establishing agreement on the Cipher Suite for the session.
  • The SSL Alert Protocol for conveying SSL error messages between client and server.

These protocols, as well as application protocol data, are encapsulated in the SSL Record Protocol, as shown in Figure 2. An encapsulated protocol is transferred as data by the lower layer protocol, which does not examine the data. The encapsulated protocol has no knowledge of the underlying protocol.

Figure 2: SSL Protocol Stack

The encapsulation of SSL control protocols by the record protocol means that if an active session is renegotiated the control protocols will be transmitted securely. If there were no session before, then the Null cipher suite is used, which means there is no encryption and messages have no integrity digests until the session has been established.

Data Transfer

The SSL Record Protocol, shown in Figure 3, is used to transfer application and SSL Control data between the client and server, possibly fragmenting this data into smaller units, or combining multiple higher level protocol data messages into single units. It may compress, attach digest signatures, and encrypt these units before transmitting them using the underlying reliable transport protocol (Note: currently all major SSL implementations lack support for compression).

Figure 3: SSL Record Protocol

Securing HTTP Communication

One common use of SSL is to secure Web HTTP communication between a browser and a webserver. This case does not preclude the use of non-secured HTTP. The secure version is mainly plain HTTP over SSL (named HTTPS), but with one major difference: it uses the URL scheme https rather than http and a different server port (by default 443). This mainly is what mod_ssl provides to you for the Apache webserver...

References

[AC96]
Bruce Schneier, Applied Cryptography, 2nd Edition, Wiley, 1996. See http://www.counterpane.com/ for various other materials by Bruce Schneier.
[X208]
ITU-T Recommendation X.208, Specification of Abstract Syntax Notation One (ASN.1), 1988. See for instance http://www.itu.int/rec/recommendation.asp?type=items&lang=e&parent=T-REC-X.208-198811-I.
[X509]
ITU-T Recommendation X.509, The Directory - Authentication Framework. See for instance http://www.itu.int/rec/recommendation.asp?type=folders&lang=e&parent=T-REC-X.509.
[PKCS]
Public Key Cryptography Standards (PKCS), RSA Laboratories Technical Notes, See http://www.rsasecurity.com/rsalabs/pkcs/.
[MIME]
N. Freed, N. Borenstein, Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies, RFC2045. See for instance http://ietf.org/rfc/rfc2045.txt.
[SSL2]
Kipp E.B. Hickman, The SSL Protocol, 1995. See http://www.netscape.com/eng/security/SSL_2.html.
[SSL3]
Alan O. Freier, Philip Karlton, Paul C. Kocher, The SSL Protocol Version 3.0, 1996. See http://www.netscape.com/eng/ssl3/draft302.txt.
[TLS1]
Tim Dierks, Christopher Allen, The TLS Protocol Version 1.0, 1999. See http://ietf.org/rfc/rfc2246.txt.


SSL/TLS Strong Encryption: Compatibility - Apache HTTP Server

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

SSL/TLS Strong Encryption: Compatibility

All PCs are compatible. But some of them are more compatible than others.

-- Unknown

Here we talk about backward compatibility to other SSL solutions. As you perhaps know, mod_ssl is not the only existing SSL solution for Apache. Actually there are four additional major products available on the market: Ben Laurie's freely available Apache-SSL (from where mod_ssl were originally derived in 1998), Red Hat's commercial Secure Web Server (which is based on mod_ssl), Covalent's commercial Raven SSL Module (also based on mod_ssl) and finally C2Net's commercial product Stronghold (based on a different evolution branch named Sioux up to Stronghold 2.x and based on mod_ssl since Stronghold 3.x).

The idea in mod_ssl is mainly the following: because mod_ssl provides mostly a superset of the functionality of all other solutions we can easily provide backward compatibility for most of the cases. Actually there are three compatibility areas we currently address: configuration directives, environment variables and custom log functions.

Configuration Directives

For backward compatibility to the configuration directives of other SSL solutions we do an on-the-fly mapping: directives which have a direct counterpart in mod_ssl are mapped silently while other directives lead to a warning message in the logfiles. The currently implemented directive mapping is listed in Table 1. Currently full backward compatibility is provided only for Apache-SSL 1.x and mod_ssl 2.0.x. Compatibility to Sioux 1.x and Stronghold 2.x is only partial because of special functionality in these interfaces which mod_ssl (still) doesn't provide.

Table 1: Configuration Directive Mapping

Old Directive | mod_ssl Directive | Comment
Apache-SSL 1.x & mod_ssl 2.0.x compatibility:
SSLEnable | SSLEngine on | compactified
SSLDisable | SSLEngine off | compactified
SSLLogFile file | SSLLog file | compactified
SSLRequiredCiphers spec | SSLCipherSuite spec | renamed
SSLRequireCipher c1 ... | SSLRequire %{SSL_CIPHER} in {"c1", ...} | generalized
SSLBanCipher c1 ... | SSLRequire not (%{SSL_CIPHER} in {"c1", ...}) | generalized
SSLFakeBasicAuth | SSLOptions +FakeBasicAuth | merged
SSLCacheServerPath dir | - | functionality removed
SSLCacheServerPort integer | - | functionality removed
Apache-SSL 1.x compatibility:
SSLExportClientCertificates | SSLOptions +ExportCertData | merged
SSLCacheServerRunDir dir | - | functionality not supported
Sioux 1.x compatibility:
SSL_CertFile file | SSLCertificateFile file | renamed
SSL_KeyFile file | SSLCertificateKeyFile file | renamed
SSL_CipherSuite arg | SSLCipherSuite arg | renamed
SSL_X509VerifyDir arg | SSLCACertificatePath arg | renamed
SSL_Log file | SSLLogFile file | renamed
SSL_Connect flag | SSLEngine flag | renamed
SSL_ClientAuth arg | SSLVerifyClient arg | renamed
SSL_X509VerifyDepth arg | SSLVerifyDepth arg | renamed
SSL_FetchKeyPhraseFrom arg | - | not directly mappable; use SSLPassPhraseDialog
SSL_SessionDir dir | - | not directly mappable; use SSLSessionCache
SSL_Require expr | - | not directly mappable; use SSLRequire
SSL_CertFileType arg | - | functionality not supported
SSL_KeyFileType arg | - | functionality not supported
SSL_X509VerifyPolicy arg | - | functionality not supported
SSL_LogX509Attributes arg | - | functionality not supported
Stronghold 2.x compatibility:
StrongholdAccelerator dir | - | functionality not supported
StrongholdKey dir | - | functionality not supported
StrongholdLicenseFile dir | - | functionality not supported
SSLFlag flag | SSLEngine flag | renamed
SSLSessionLockFile file | SSLMutex file | renamed
SSLCipherList spec | SSLCipherSuite spec | renamed
RequireSSL | SSLRequireSSL | renamed
SSLErrorFile file | - | functionality not supported
SSLRoot dir | - | functionality not supported
SSL_CertificateLogDir dir | - | functionality not supported
AuthCertDir dir | - | functionality not supported
SSL_Group name | - | functionality not supported
SSLProxyMachineCertPath dir | - | functionality not supported
SSLProxyMachineCertFile file | - | functionality not supported
SSLProxyCACertificatePath dir | - | functionality not supported
SSLProxyCACertificateFile file | - | functionality not supported
SSLProxyVerifyDepth number | - | functionality not supported
SSLProxyCipherList spec | - | functionality not supported

Environment Variables

When you use ``SSLOptions +CompatEnvVars'' additional environment variables are generated. They all correspond to existing official mod_ssl variables. The currently implemented variable derivation is listed in Table 2.

Table 2: Environment Variable Derivation

Old Variable | mod_ssl Variable | Comment
SSL_PROTOCOL_VERSION | SSL_PROTOCOL | renamed
SSLEAY_VERSION | SSL_VERSION_LIBRARY | renamed
HTTPS_SECRETKEYSIZE | SSL_CIPHER_USEKEYSIZE | renamed
HTTPS_KEYSIZE | SSL_CIPHER_ALGKEYSIZE | renamed
HTTPS_CIPHER | SSL_CIPHER | renamed
HTTPS_EXPORT | SSL_CIPHER_EXPORT | renamed
SSL_SERVER_KEY_SIZE | SSL_CIPHER_ALGKEYSIZE | renamed
SSL_SERVER_CERTIFICATE | SSL_SERVER_CERT | renamed
SSL_SERVER_CERT_START | SSL_SERVER_V_START | renamed
SSL_SERVER_CERT_END | SSL_SERVER_V_END | renamed
SSL_SERVER_CERT_SERIAL | SSL_SERVER_M_SERIAL | renamed
SSL_SERVER_SIGNATURE_ALGORITHM | SSL_SERVER_A_SIG | renamed
SSL_SERVER_DN | SSL_SERVER_S_DN | renamed
SSL_SERVER_CN | SSL_SERVER_S_DN_CN | renamed
SSL_SERVER_EMAIL | SSL_SERVER_S_DN_Email | renamed
SSL_SERVER_O | SSL_SERVER_S_DN_O | renamed
SSL_SERVER_OU | SSL_SERVER_S_DN_OU | renamed
SSL_SERVER_C | SSL_SERVER_S_DN_C | renamed
SSL_SERVER_SP | SSL_SERVER_S_DN_SP | renamed
SSL_SERVER_L | SSL_SERVER_S_DN_L | renamed
SSL_SERVER_IDN | SSL_SERVER_I_DN | renamed
SSL_SERVER_ICN | SSL_SERVER_I_DN_CN | renamed
SSL_SERVER_IEMAIL | SSL_SERVER_I_DN_Email | renamed
SSL_SERVER_IO | SSL_SERVER_I_DN_O | renamed
SSL_SERVER_IOU | SSL_SERVER_I_DN_OU | renamed
SSL_SERVER_IC | SSL_SERVER_I_DN_C | renamed
SSL_SERVER_ISP | SSL_SERVER_I_DN_SP | renamed
SSL_SERVER_IL | SSL_SERVER_I_DN_L | renamed
SSL_CLIENT_CERTIFICATE | SSL_CLIENT_CERT | renamed
SSL_CLIENT_CERT_START | SSL_CLIENT_V_START | renamed
SSL_CLIENT_CERT_END | SSL_CLIENT_V_END | renamed
SSL_CLIENT_CERT_SERIAL | SSL_CLIENT_M_SERIAL | renamed
SSL_CLIENT_SIGNATURE_ALGORITHM | SSL_CLIENT_A_SIG | renamed
SSL_CLIENT_DN | SSL_CLIENT_S_DN | renamed
SSL_CLIENT_CN | SSL_CLIENT_S_DN_CN | renamed
SSL_CLIENT_EMAIL | SSL_CLIENT_S_DN_Email | renamed
SSL_CLIENT_O | SSL_CLIENT_S_DN_O | renamed
SSL_CLIENT_OU | SSL_CLIENT_S_DN_OU | renamed
SSL_CLIENT_C | SSL_CLIENT_S_DN_C | renamed
SSL_CLIENT_SP | SSL_CLIENT_S_DN_SP | renamed
SSL_CLIENT_L | SSL_CLIENT_S_DN_L | renamed
SSL_CLIENT_IDN | SSL_CLIENT_I_DN | renamed
SSL_CLIENT_ICN | SSL_CLIENT_I_DN_CN | renamed
SSL_CLIENT_IEMAIL | SSL_CLIENT_I_DN_Email | renamed
SSL_CLIENT_IO | SSL_CLIENT_I_DN_O | renamed
SSL_CLIENT_IOU | SSL_CLIENT_I_DN_OU | renamed
SSL_CLIENT_IC | SSL_CLIENT_I_DN_C | renamed
SSL_CLIENT_ISP | SSL_CLIENT_I_DN_SP | renamed
SSL_CLIENT_IL | SSL_CLIENT_I_DN_L | renamed
SSL_EXPORT | SSL_CIPHER_EXPORT | renamed
SSL_KEYSIZE | SSL_CIPHER_ALGKEYSIZE | renamed
SSL_SECKEYSIZE | SSL_CIPHER_USEKEYSIZE | renamed
SSL_SSLEAY_VERSION | SSL_VERSION_LIBRARY | renamed
SSL_STRONG_CRYPTO | - | Not supported by mod_ssl
SSL_SERVER_KEY_EXP | - | Not supported by mod_ssl
SSL_SERVER_KEY_ALGORITHM | - | Not supported by mod_ssl
SSL_SERVER_KEY_SIZE | - | Not supported by mod_ssl
SSL_SERVER_SESSIONDIR | - | Not supported by mod_ssl
SSL_SERVER_CERTIFICATELOGDIR | - | Not supported by mod_ssl
SSL_SERVER_CERTFILE | - | Not supported by mod_ssl
SSL_SERVER_KEYFILE | - | Not supported by mod_ssl
SSL_SERVER_KEYFILETYPE | - | Not supported by mod_ssl
SSL_CLIENT_KEY_EXP | - | Not supported by mod_ssl
SSL_CLIENT_KEY_ALGORITHM | - | Not supported by mod_ssl
SSL_CLIENT_KEY_SIZE | - | Not supported by mod_ssl

Custom Log Functions

When mod_ssl is built into Apache or at least loaded (under DSO situation) additional functions exist for the Custom Log Format of mod_log_config as documented in the Reference Chapter. Beside the ``%{varname}x'' eXtension format function which can be used to expand any variables provided by any module, an additional Cryptography ``%{name}c'' cryptography format function exists for backward compatibility. The currently implemented function calls are listed in Table 3.

Table 3: Custom Log Cryptography Function

Function Call | Description
%...{version}c | SSL protocol version
%...{cipher}c | SSL cipher
%...{subjectdn}c | Client Certificate Subject Distinguished Name
%...{issuerdn}c | Client Certificate Issuer Distinguished Name
%...{errcode}c | Certificate Verification Error (numerical)
%...{errstr}c | Certificate Verification Error (string)


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

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

SSL/TLS Strong Encryption: How-To

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

-- Standard textbook cookie

How to solve particular security constraints for an SSL-aware webserver is not always obvious because of the coherences between SSL, HTTP and Apache's way of processing requests. This chapter gives instructions on how to solve such typical situations. Treat is as a first step to find out the final solution, but always try to understand the stuff before you use it. Nothing is worse than using a security solution without knowing its restrictions and coherences.

Cipher Suites and Enforced Strong Security

  • SSLv2 only server
  • strong encryption only server
  • server gated cryptography
  • stronger per-directory requirements

How can I create a real SSLv2-only server?

The following creates an SSL server which speaks only the SSLv2 protocol and its ciphers.

httpd.conf

SSLProtocol -all +SSLv2
SSLCipherSuite SSLv2:+HIGH:+MEDIUM:+LOW:+EXP

How can I create an SSL server which accepts strong encryption only?

The following enables only the seven strongest ciphers:

httpd.conf

SSLProtocol all
SSLCipherSuite HIGH:MEDIUM

How can I create an SSL server which accepts strong encryption only, but allows export browsers to upgrade to stronger encryption?

This facility is called Server Gated Cryptography (SGC) and details you can find in the README.GlobalID document in the mod_ssl distribution. In short: The server has a Global ID server certificate, signed by a special CA certificate from Verisign which enables strong encryption in export browsers. This works as following: The browser connects with an export cipher, the server sends its Global ID certificate, the browser verifies it and subsequently upgrades the cipher suite before any HTTP communication takes place. The question now is: How can we allow this upgrade, but enforce strong encryption. Or in other words: Browser either have to initially connect with strong encryption or have to upgrade to strong encryption, but are not allowed to keep the export ciphers. The following does the trick:

httpd.conf

# allow all ciphers for the initial handshake,
# so export browsers can upgrade via SGC facility
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL

<Directory /usr/local/apache2/htdocs>
# but finally deny all browsers which haven't upgraded
SSLRequire %{SSL_CIPHER_USEKEYSIZE} >= 128
</Directory>

How can I create an SSL server which accepts all types of ciphers in general, but requires a strong ciphers for access to a particular URL?

Obviously you cannot just use a server-wide SSLCipherSuite which restricts the ciphers to the strong variants. But mod_ssl allows you to reconfigure the cipher suite in per-directory context and automatically forces a renegotiation of the SSL parameters to meet the new configuration. So, the solution is:

# be liberal in general
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL

<Location /strong/area>
# but https://hostname/strong/area/ and below
# requires strong ciphers
SSLCipherSuite HIGH:MEDIUM
</Location>

Client Authentication and Access Control

  • simple certificate-based client authentication
  • selective certificate-based client authentication
  • particular certificate-based client authentication
  • intranet vs. internet authentication

How can I authenticate clients based on certificates when I know all my clients?

When you know your user community (i.e. a closed user group situation), as it's the case for instance in an Intranet, you can use plain certificate authentication. All you have to do is to create client certificates signed by your own CA certificate ca.crt and then verify the clients against this certificate.

httpd.conf

# require a client certificate which has to be directly
# signed by our CA certificate in ca.crt
SSLVerifyClient require
SSLVerifyDepth 1
SSLCACertificateFile conf/ssl.crt/ca.crt

How can I authenticate my clients for a particular URL based on certificates but still allow arbitrary clients to access the remaining parts of the server?

For this we again use the per-directory reconfiguration feature of mod_ssl:

httpd.conf

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

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

How can I authenticate only particular clients for a some URLs based on certificates but still allow arbitrary clients to access the remaining parts of the server?

The key is to check for various ingredients of the client certificate. Usually this means to check the whole or part of the Distinguished Name (DN) of the Subject. For this two methods exists: The mod_auth based variant and the SSLRequire variant. The first method is good when the clients are of totally different type, i.e. when their DNs have no common fields (usually the organisation, etc.). In this case you've to establish a password database containing all clients. The second method is better when your clients are all part of a common hierarchy which is encoded into the DN. Then you can match them more easily.

The first method:

httpd.conf

SSLVerifyClient      none
<Directory /usr/local/apache2/htdocs/secure/area>

SSLVerifyClient      require
SSLVerifyDepth       5
SSLCACertificateFile conf/ssl.crt/ca.crt
SSLCACertificatePath conf/ssl.crt
SSLOptions           +FakeBasicAuth
SSLRequireSSL
AuthName             "Snake Oil Authentication"
AuthType             Basic
AuthUserFile         /usr/local/apache2/conf/httpd.passwd
require              valid-user
</Directory>

httpd.passwd

/C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
/C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
/C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA

The second method:

httpd.conf

SSLVerifyClient      none
<Directory /usr/local/apache2/htdocs/secure/area>

  SSLVerifyClient      require
  SSLVerifyDepth       5
  SSLCACertificateFile conf/ssl.crt/ca.crt
  SSLCACertificatePath conf/ssl.crt
  SSLOptions           +FakeBasicAuth
  SSLRequireSSL
  SSLRequire       %{SSL_CLIENT_S_DN_O}  eq "Snake Oil, Ltd." \
               and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}
</Directory>

How can I require HTTPS with strong ciphers and either basic authentication or client certificates for access to a subarea on the Intranet website for clients coming from the Internet but still allow plain HTTP access for clients on the Intranet?

Let us assume the Intranet can be distinguished through the IP network 192.160.1.0/24 and the subarea on the Intranet website has the URL /subarea. Then configure the following outside your HTTPS virtual host (so it applies to both HTTPS and HTTP):

httpd.conf

SSLCACertificateFile conf/ssl.crt/company-ca.crt

<Directory /usr/local/apache2/htdocs>
#   Outside the subarea only Intranet access is granted
Order                deny,allow
Deny                 from all
Allow                from 192.168.1.0/24
</Directory>

<Directory /usr/local/apache2/htdocs/subarea>
#   Inside the subarea any Intranet access is allowed
#   but from the Internet only HTTPS + Strong-Cipher + Password
#   or the alternative HTTPS + Strong-Cipher + Client-Certificate

#   If HTTPS is used, make sure a strong cipher is used.
#   Additionally allow client certs as alternative to basic auth.
SSLVerifyClient      optional
SSLVerifyDepth       1
SSLOptions           +FakeBasicAuth +StrictRequire
SSLRequire           %{SSL_CIPHER_USEKEYSIZE} >= 128

#   Force clients from the Internet to use HTTPS
RewriteEngine        on
RewriteCond          %{REMOTE_ADDR} !^192\.168\.1\.[0-9]+$
RewriteCond          %{HTTPS} !=on
RewriteRule          .* - [F]

#   Allow Network Access and/or Basic Auth
Satisfy              any

#   Network Access Control
Order                deny,allow
Deny                 from all
Allow                192.168.1.0/24

#   HTTP Basic Authentication
AuthType             basic
AuthName             "Protected Intranet Area"
AuthUserFile         conf/protected.passwd
Require              valid-user
</Directory>


SSL/TLS Strong Encryption: FAQ - Apache HTTP Server

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

SSL/TLS Strong Encryption: FAQ

The wise man doesn't give the right answers, he poses the right questions.

-- Claude Levi-Strauss

This chapter is a collection of frequently asked questions (FAQ) and corresponding answers following the popular USENET tradition. Most of these questions occurred on the Newsgroup comp.infosystems.www.servers.unix or the mod_ssl Support Mailing List modssl-users@modssl.org. They are collected at this place to avoid answering the same questions over and over.

Please read this chapter at least once when installing mod_ssl or at least search for your problem here before submitting a problem report to the author.

About The Module

  • What is the history of mod_ssl?
  • mod_ssl and Year 2000?
  • mod_ssl and Wassenaar Arrangement?

What is the history of mod_ssl?

The mod_ssl v1 package was initially created in April 1998 by Ralf S. Engelschall via porting Ben Laurie's Apache-SSL 1.17 source patches for Apache 1.2.6 to Apache 1.3b6. Because of conflicts with Ben Laurie's development cycle it then was re-assembled from scratch for Apache 1.3.0 by merging the old mod_ssl 1.x with the newer Apache-SSL 1.18. From this point on mod_ssl lived its own life as mod_ssl v2. The first publicly released version was mod_ssl 2.0.0 from August 10th, 1998. As of this writing (August 1999) the current mod_ssl version is 2.4.0.

After one year of very active development with over 1000 working hours and over 40 releases mod_ssl reached its current state. The result is an already very clean source base implementing a very rich functionality. The code size increased by a factor of 4 to currently a total of over 10.000 lines of ANSI C consisting of approx. 70% code and 30% code documentation. From the original Apache-SSL code currently approx. 5% is remaining only.

After the US export restrictions for cryptographic software were opened, mod_ssl was integrated into the code base of Apache V2 in 2001.

Is mod_ssl Year 2000 compliant?

Yes, mod_ssl is Year 2000 compliant.

Because first mod_ssl internally never stores years as two digits. Instead it always uses the ANSI C & POSIX numerical data type time_t type, which on almost all Unix platforms at the moment is a signed long (usually 32-bits) representing seconds since epoch of January 1st, 1970, 00:00 UTC. This signed value overflows in early January 2038 and not in the year 2000. Second, date and time presentations (for instance the variable ``%{TIME_YEAR}'') are done with full year value instead of abbreviating to two digits.

Additionally according to a Year 2000 statement from the Apache Group, the Apache webserver is Year 2000 compliant, too. But whether OpenSSL or the underlying Operating System (either a Unix or Win32 platform) is Year 2000 compliant is a different question which cannot be answered here.

What about mod_ssl and the Wassenaar Arrangement?

First, let us explain what Wassenaar and its Arrangement on Export Controls for Conventional Arms and Dual-Use Goods and Technologies is: This is a international regime, established 1995, to control trade in conventional arms and dual-use goods and technology. It replaced the previous CoCom regime. 33 countries are signatories: Argentina, Australia, Austria, Belgium, Bulgaria, Canada, Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan, Luxembourg, the Netherlands, New Zealand, Norway, Poland, Portugal, Republic of Korea, Romania, Russian Federation, Slovak Republic, Spain, Sweden, Switzerland, Turkey, Ukraine, the United Kingdom and the United States. For more details look at http://www.wassenaar.org/.

In short: The aim of the Wassenaar Arrangement is to prevent the build up of military capabilities that threaten regional and international security and stability. The Wassenaar Arrangement controls the export of cryptography as a dual-use good, i.e., one that has both military and civilian applications. However, the Wassenaar Arrangement also provides an exemption from export controls for mass-market software and free software.

In the current Wassenaar List of Dual Use Goods and Technologies And Munitions, under GENERAL SOFTWARE NOTE (GSN) it says The Lists do not control "software" which is either: 1. [...] 2. "in the public domain". And under DEFINITIONS OF TERMS USED IN THESE LISTS one can find the definition: In the public domain": This means "technology" or "software" which has been made available without restrictions upon its further dissemination. N.B. Copyright restrictions do not remove "technology" or "software" from being "in the public domain".

So, both mod_ssl and OpenSSL are in the public domain for the purposes of the Wassenaar Agreement and its List of Dual Use Goods and Technologies And Munitions List.

So, mod_ssl and OpenSSL are not affected by the Wassenaar Agreement.

About Installation

  • Core dumps for HTTPS requests?
  • Permission problem on SSLMutex
  • Shared memory and process size?
  • PRNG and not enough entropy?

When I access my website the first time via HTTPS I get a core dump?

There can be a lot of reasons why a core dump can occur, of course. Ranging from buggy third-party modules, over buggy vendor libraries up to a buggy mod_ssl version. But the above situation is often caused by old or broken vendor DBM libraries. To solve it either build mod_ssl with the built-in SDBM library (specify --enable-rule=SSL_SDBM at the APACI command line) or switch from SSLSessionCache dbm: to the newer SSLSessionCache shm:'' variant (after you have rebuilt Apache with MM, of course).

When I startup Apache I get permission errors related to SSLMutex?

When you receive entries like ``mod_ssl: Child could not open SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows) [...] System: Permission denied (errno: 13)'' this is usually caused by to restrictive permissions on the parent directories. Make sure that all parent directories (here /opt, /opt/apache and /opt/apache/logs) have the x-bit set at least for the UID under which Apache's children are running (see the User directive of Apache).

When I use the MM library and the shared memory cache each process grows 1.5MB according to `top' although I specified 512000 as the cache size?

The additional 1MB are caused by the global shared memory pool Apache allocates for all modules and which is not used by mod_ssl for various reasons. So the actually allocated shared memory is always 1MB more than what you specify on SSLSessionCache. But don't be confused by the display of `top': although is indicates that each process grow, this is not reality, of course. Instead the additional memory consumption is shared by all processes, i.e. the 1.5MB are allocated only once per Apache instance and not once per Apache server process.

When I fire up the server, mod_ssl stops with the error "Failed to generate temporary 512 bit RSA private key", why?

Cryptographic software needs a source of unpredictable data to work correctly. Many open source operating systems provide a "randomness device" that serves this purpose (usually named /dev/random). On other systems, applications have to seed the OpenSSL Pseudo Random Number Generator (PRNG) manually with appropriate data before generating keys or performing public key encryption. As of version 0.9.5, the OpenSSL functions that need randomness report an error if the PRNG has not been seeded with at least 128 bits of randomness. So mod_ssl has to provide enough entropy to the PRNG to work correctly. For this one has to use the SSLRandomSeed directives.

About Configuration

  • HTTP and HTTPS with a single server?
  • Where is the HTTPS port?
  • How to test HTTPS manually?
  • Why does my connection hang?
  • Why do I get connection refused?
  • Why are the SSL_XXX variables missing?
  • How to switch with relative hyperlinks?

Is it possible to provide HTTP and HTTPS with a single server?

Yes, HTTP and HTTPS use different server ports, so there is no direct conflict between them. Either run two separate server instances (one binds to port 80, the other to port 443) or even use Apache's elegant virtual hosting facility where you can easily create two virtual servers which Apache dispatches: one responding to port 80 and speaking HTTP and one responding to port 443 speaking HTTPS.

I know that HTTP is on port 80, but where is HTTPS?

You can run HTTPS on any port, but the standards specify port 443, which is where any HTTPS compliant browser will look by default. You can force your browser to look on a different port by specifying it in the URL like this (for port 666): https://secure.server.dom:666/

How can I speak HTTPS manually for testing purposes?

While you usually just use

$ telnet localhost 80
GET / HTTP/1.0

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

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

Before the actual HTTP response you receive detailed information about the SSL handshake. For a more general command line client which directly understands both the HTTP and HTTPS scheme, can perform GET and POST methods, can use a proxy, supports byte ranges, etc. you should have a look at nifty cURL tool. With it you can directly check if your Apache is running fine on Port 80 and 443 as following:

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

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

Because you connected with HTTP to the HTTPS port, i.e. you used an URL of the form ``http://'' instead of ``https://''. This also happens the other way round when you connect via HTTPS to a HTTP port, i.e. when you try to use ``https://'' on a server that doesn't support SSL (on this port). Make sure you are connecting to a virtual server that supports SSL, which is probably the IP associated with your hostname, not localhost (127.0.0.1).

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

There can be various reasons. Some of the common mistakes is that people start Apache with just ``apachectl start'' (or ``httpd'') instead of ``apachectl startssl'' (or ``httpd -DSSL''. Or you're configuration is not correct. At least make sure that your Listen directives match your <VirtualHost> directives. And if all fails, please do yourself a favor and start over with the default configuration mod_ssl provides you.

In my CGI programs and SSI scripts the various documented SSL_XXX variables do not exist. Why?

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

How can I use relative hyperlinks to switch between HTTP and HTTPS?

Usually you have to use fully-qualified hyperlinks because you have to change the URL scheme. But with the help of some URL manipulations through mod_rewrite you can achieve the same effect while you still can use relative URLs:

RewriteEngine on
RewriteRule ^/(.*):SSL$ https://%{SERVER_NAME}/$1 [R,L]
RewriteRule ^/(.*):NOSSL$ http://%{SERVER_NAME}/$1 [R,L]

This rewrite ruleset lets you use hyperlinks of the form <a href="document.html:SSL">

About Certificates

  • What are Keys, CSRs and Certs?
  • Difference on startup?
  • How to create a real cert?
  • How to create my own CA?
  • How to change a pass phrase?
  • How to remove a pass phrase?
  • How to verify a key/cert pair?
  • Bad Certificate Error?
  • Why does a 2048-bit key not work?
  • Why is client auth broken?
  • How to convert from PEM to DER?
  • Verisign and the magic getca program?
  • Global IDs or SGC?
  • Global IDs and Cert Chain?

What are RSA Private Keys, CSRs and Certificates?

The RSA private key file is a digital file that you can use to decrypt messages sent to you. It has a public component which you distribute (via your Certificate file) which allows people to encrypt those messages to you. A Certificate Signing Request (CSR) is a digital file which contains your public key and your name. You send the CSR to a Certifying Authority (CA) to be converted into a real Certificate. A Certificate contains your RSA public key, your name, the name of the CA, and is digitally signed by your CA. Browsers that know the CA can verify the signature on that Certificate, thereby obtaining your RSA public key. That enables them to send messages which only you can decrypt. See the Introduction chapter for a general description of the SSL protocol.

Seems like there is a difference on startup between the original Apache and an SSL-aware Apache?

Yes, in general, starting Apache with a built-in mod_ssl is just like starting an unencumbered Apache, except for the fact that when you have a pass phrase on your SSL private key file. Then a startup dialog pops up asking you to enter the pass phrase.

To type in the pass phrase manually when starting the server can be problematic, for instance when starting the server from the system boot scripts. As an alternative to this situation you can follow the steps below under ``How can I get rid of the pass-phrase dialog at Apache startup time?''.

Ok, I've got my server installed and want to create a real SSL server Certificate for it. How do I do it?

Here is a step-by-step description:

  1. Make sure OpenSSL is really installed and in your PATH. But some commands even work ok when you just run the ``openssl'' program from within the OpenSSL source tree as ``./apps/openssl''.

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

    $ openssl genrsa -des3 -out server.key 1024

    Please backup this server.key file and remember the pass-phrase you had to enter at a secure location. You can see the details of this RSA private key via the command:

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

    And you could create a decrypted PEM version (not recommended) of this RSA private key via:

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

  3. Create a Certificate Signing Request (CSR) with the server RSA private key (output will be PEM formatted):

    $ openssl req -new -key server.key -out server.csr

    Make sure you enter the FQDN ("Fully Qualified Domain Name") of the server when OpenSSL prompts you for the "CommonName", i.e. when you generate a CSR for a website which will be later accessed via https://www.foo.dom/, enter "www.foo.dom" here. You can see the details of this CSR via the command

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

  4. You now have to send this Certificate Signing Request (CSR) to a Certifying Authority (CA) for signing. The result is then a real Certificate which can be used for Apache. Here you have two options: First you can let the CSR sign by a commercial CA like Verisign or Thawte. Then you usually have to post the CSR into a web form, pay for the signing and await the signed Certificate you then can store into a server.crt file. For more information about commercial CAs have a look at the following locations:

    1. Verisign
      http://digitalid.verisign.com/server/apacheNotice.htm
    2. Thawte Consulting
      http://www.thawte.com/certs/server/request.html
    3. CertiSign Certificadora Digital Ltda.
      http://www.certisign.com.br
    4. IKS GmbH
      http://www.iks-jena.de/produkte/ca/
    5. Uptime Commerce Ltd.
      http://www.uptimecommerce.com
    6. BelSign NV/SA
      http://www.belsign.be
    Second you can use your own CA and now have to sign the CSR yourself by this CA. Read the next answer in this FAQ on how to sign a CSR with your CA yourself. You can see the details of the received Certificate via the command:

    $ openssl x509 -noout -text -in server.crt
  5. Now you have two files: server.key and server.crt. These now can be used as following inside your Apache's httpd.conf file:
           SSLCertificateFile    /path/to/this/server.crt
       SSLCertificateKeyFile /path/to/this/server.key
    The server.csr file is no longer needed.

How can I create and use my own Certificate Authority (CA)?

The short answer is to use the CA.sh or CA.pl script provided by OpenSSL. The long and manual answer is this:

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

    $ openssl genrsa -des3 -out ca.key 1024

    Please backup this ca.key file and remember the pass-phrase you currently entered at a secure location. You can see the details of this RSA private key via the command

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

    And you can create a decrypted PEM version (not recommended) of this private key via:

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

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

    $ openssl req -new -x509 -days 365 -key ca.key -out ca.crt

    You can see the details of this Certificate via the command:

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

  3. Prepare a script for signing which is needed because the ``openssl ca'' command has some strange requirements and the default OpenSSL config doesn't allow one easily to use ``openssl ca'' directly. So a script named sign.sh is distributed with the mod_ssl distribution (subdir pkg.contrib/). Use this script for signing.
  4. Now you can use this CA to sign server CSR's in order to create real SSL Certificates for use inside an Apache webserver (assuming you already have a server.csr at hand):

    $ ./sign.sh server.csr

    This signs the server CSR and results in a server.crt file.

How can I change the pass-phrase on my private key file?

You simply have to read it with the old pass-phrase and write it again by specifying the new pass-phrase. You can accomplish this with the following commands:

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

Here you're asked two times for a PEM pass-phrase. At the first prompt enter the old pass-phrase and at the second prompt enter the new pass-phrase.

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

The reason why this dialog pops up at startup and every re-start is that the RSA private key inside your server.key file is stored in encrypted format for security reasons. The pass-phrase is needed to be able to read and parse this file. When you can be sure that your server is secure enough you perform two steps:

  1. Remove the encryption from the RSA private key (while preserving the original file):

    $ cp server.key server.key.org
    $ openssl rsa -in server.key.org -out server.key

  2. Make sure the server.key file is now only readable by root:

    $ chmod 400 server.key

Now server.key will contain an unencrypted copy of the key. If you point your server at this file it will not prompt you for a pass-phrase. HOWEVER, if anyone gets this key they will be able to impersonate you on the net. PLEASE make sure that the permissions on that file are really such that only root or the web server user can read it (preferably get your web server to start as root but run as another server, and have the key readable only by root).

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

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

The private key contains a series of numbers. Two of those numbers form the "public key", the others are part of your "private key". The "public key" bits are also embedded in your Certificate (we get them from your CSR). To check that the public key in your cert matches the public portion of your private key, you need to view the cert and the key and compare the numbers. To view the Certificate and the key run the commands:

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

The `modulus' and the `public exponent' portions in the key and the Certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach:

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

And then compare these really shorter numbers. With overwhelming probability they will differ if the keys are different. BTW, if I want to check to which key or certificate a particular CSR belongs you can compute

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

What does it mean when my connections fail with an "alert bad certificate" error?

Usually when you see errors like OpenSSL: error:14094412: SSL routines:SSL3_READ_BYTES:sslv3 alert bad certificate in the SSL logfile, this means that the browser was unable to handle the server certificate/private-key which perhaps contain a RSA-key not equal to 1024 bits. For instance Netscape Navigator 3.x is one of those browsers.

Why does my 2048-bit private key not work?

The private key sizes for SSL must be either 512 or 1024 for compatibility with certain web browsers. A keysize of 1024 bits is recommended because keys larger than 1024 bits are incompatible with some versions of Netscape Navigator and Microsoft Internet Explorer, and with other browsers that use RSA's BSAFE cryptography toolkit.

Why is client authentication broken after upgrading from SSLeay version 0.8 to 0.9?

The CA certificates under the path you configured with SSLCACertificatePath are found by SSLeay through hash symlinks. These hash values are generated by the `openssl x509 -noout -hash' command. But the algorithm used to calculate the hash for a certificate has changed between SSLeay 0.8 and 0.9. So you have to remove all old hash symlinks and re-create new ones after upgrading. Use the Makefile mod_ssl placed into this directory.

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

The default certificate format for SSLeay/OpenSSL is PEM, which actually is Base64 encoded DER with header and footer lines. For some applications (e.g. Microsoft Internet Explorer) you need the certificate in plain DER format. You can convert a PEM file cert.pem into the corresponding DER file cert.der with the following command: $ openssl x509 -in cert.pem -out cert.der -outform DER

I try to install a Verisign certificate. Why can't I find neither the getca nor getverisign programs Verisign mentions?

This is because Verisign has never provided specific instructions for Apache+mod_ssl. Rather they tell you what you should do if you were using C2Net's Stronghold (a commercial Apache based server with SSL support). The only thing you have to do is to save the certificate into a file and give the name of that file to the SSLCertificateFile directive. Remember that you need to give the key file in as well (see SSLCertificateKeyFile directive). For a better CA-related overview on SSL certificate fiddling you can look at Thawte's mod_ssl instructions.

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

Yes, mod_ssl since version 2.1 supports the SGC facility. You don't have to configure anything special for this, just use a Global ID as your server certificate. The step up of the clients are then automatically handled by mod_ssl under run-time. For details please read the README.GlobalID document in the mod_ssl distribution.

After I have installed my new Verisign Global ID server certificate, the browsers complain that they cannot verify the server certificate?

That is because Verisign uses an intermediate CA certificate between the root CA certificate (which is installed in the browsers) and the server certificate (which you installed in the server). You should have received this additional CA certificate from Verisign. If not, complain to them. Then configure this certificate with the SSLCertificateChainFile directive in the server. This makes sure the intermediate CA certificate is send to the browser and this way fills the gap in the certificate chain.

About SSL Protocol

  • Random SSL errors under heavy load?
  • Why has the server a higher load?
  • Why are connections horribly slow?
  • Which ciphers are supported?
  • How to use Anonymous-DH ciphers
  • Why do I get 'no shared ciphers'?
  • HTTPS and name-based vhosts
  • Why is it not possible to use Name-Based Virtual Hosting to identify different SSL virtual hosts?
  • The lock icon in Netscape locks very late
  • Why do I get I/O errors with MSIE clients?
  • Why do I get I/O errors with NS clients?

Why do I get lots of random SSL protocol errors under heavy server load?

There can be a number of reasons for this, but the main one is problems with the SSL session Cache specified by the SSLSessionCache directive. The DBM session cache is most likely the source of the problem, so trying the SHM session cache or no cache at all may help.

Why has my webserver a higher load now that I run SSL there?

Because SSL uses strong cryptographic encryption and this needs a lot of number crunching. And because when you request a webpage via HTTPS even the images are transferred encrypted. So, when you have a lot of HTTPS traffic the load increases.

Often HTTPS connections to my server require up to 30 seconds for establishing the connection, although sometimes it works faster?

Usually this is caused by using a /dev/random device for SSLRandomSeed which is blocking in read(2) calls if not enough entropy is available. Read more about this problem in the reference chapter under SSLRandomSeed.

What SSL Ciphers are supported by mod_ssl?

Usually just all SSL ciphers which are supported by the version of OpenSSL in use (can depend on the way you built OpenSSL). Typically this at least includes the following:

  1. RC4 with MD5
  2. RC4 with MD5 (export version restricted to 40-bit key)
  3. RC2 with MD5
  4. RC2 with MD5 (export version restricted to 40-bit key)
  5. IDEA with MD5
  6. DES with MD5
  7. Triple-DES with MD5

To determine the actual list of supported ciphers you can run the following command:

$ openssl ciphers -v

I want to use Anonymous Diffie-Hellman (ADH) ciphers, but I always get ``no shared cipher'' errors?

In order to use Anonymous Diffie-Hellman (ADH) ciphers, it is not enough to just put ``ADH'' into your SSLCipherSuite. Additionally you have to build OpenSSL with ``-DSSL_ALLOW_ADH''. Because per default OpenSSL does not allow ADH ciphers for security reasons. So if you are actually enabling these ciphers make sure you are informed about the side-effects.

I always just get a 'no shared ciphers' error if I try to connect to my freshly installed server?

Either you have messed up your SSLCipherSuite directive (compare it with the pre-configured example in httpd.conf-dist) or you have chosen the DSA/DH algorithms instead of RSA when you generated your private key and ignored or overlooked the warnings. If you have chosen DSA/DH, then your server no longer speaks RSA-based SSL ciphers (at least not until you also configure an additional RSA-based certificate/key pair). But current browsers like NS or IE only speak RSA ciphers. The result is the "no shared ciphers" error. To fix this, regenerate your server certificate/key pair and this time choose the RSA algorithm.

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

The reason is very technical. Actually it's some sort of a chicken and egg problem: The SSL protocol layer stays below the HTTP protocol layer and encapsulates HTTP. When an SSL connection (HTTPS) is established Apache/mod_ssl has to negotiate the SSL protocol parameters with the client. For this mod_ssl has to consult the configuration of the virtual server (for instance it has to look for the cipher suite, the server certificate, etc.). But in order to dispatch to the correct virtual server Apache has to know the Host HTTP header field. For this the HTTP request header has to be read. This cannot be done before the SSL handshake is finished. But the information is already needed at the SSL handshake phase. Bingo!

Why is it not possible to use Name-Based Virtual Hosting to identify different SSL virtual hosts?

Name-Based Virtual Hosting is a very popular method of identifying different virtual hosts. It allows you to use the same IP address and the same port number for many different sites. When people move on to SSL, it seems natural to assume that the same method can be used to have lots of different SSL virtual hosts on the same server.

It comes as rather a shock to learn that it is impossible.

The reason is that the SSL protocol is a separate layer which encapsulates the HTTP protocol. So the problem is that the SSL session is a separate transaction that takes place before the HTTP session even starts. Therefore all the server receives is an SSL request on IP address X and port Y (usually 443). Since the SSL request does not contain any Host: field, the server has no way to decide which SSL virtual host to use. Usually, it will just use the first one it finds that matches the port and IP address.

You can, of course, use Name-Based Virtual Hosting to identify many non-SSL virtual hosts (all on port 80, for example) and then you can have no more than 1 SSL virtual host (on port 443). But if you do this, you must make sure to put the non-SSL port number on the NameVirtualHost directive, e.g.

NameVirtualHost 192.168.1.1:80

Other workaround solutions are:

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

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

No, the username/password is already transmitted encrypted. The icon in Netscape browsers is just not really synchronized with the SSL/TLS layer (it toggles to the locked state when the first part of the actual webpage data is transferred which is not quite correct) and this way confuses people. The Basic Authentication facility is part of the HTTP layer and this layer is above the SSL/TLS layer in HTTPS. And before any HTTP data communication takes place in HTTPS the SSL/TLS layer has already done the handshake phase and switched to encrypted communication. So, don't get confused by this icon.

When I connect via HTTPS to an Apache+mod_ssl+OpenSSL server with Microsoft Internet Explorer (MSIE) I get various I/O errors. What is the reason?

The first reason is that the SSL implementation in some MSIE versions has some subtle bugs related to the HTTP keep-alive facility and the SSL close notify alerts on socket connection close. Additionally the interaction between SSL and HTTP/1.1 features are problematic with some MSIE versions, too. You've to work-around these problems by forcing Apache+mod_ssl+OpenSSL to not use HTTP/1.1, keep-alive connections or sending the SSL close notify messages to MSIE clients. This can be done by using the following directive in your SSL-aware virtual host section:

SetEnvIf User-Agent ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0

Additionally it is known some MSIE versions have also problems with particular ciphers. Unfortunately one cannot workaround these bugs only for those MSIE particular clients, because the ciphers are already used in the SSL handshake phase. So a MSIE-specific SetEnvIf doesn't work to solve these problems. Instead one has to do more drastic adjustments to the global parameters. But before you decide to do this, make sure your clients really have problems. If not, do not do this, because it affects all(!) your clients, i.e., also your non-MSIE clients.

The next problem is that 56bit export versions of MSIE 5.x browsers have a broken SSLv3 implementation which badly interacts with OpenSSL versions greater than 0.9.4. You can either accept this and force your clients to upgrade their browsers, or you downgrade to OpenSSL 0.9.4 (hmmm), or you can decide to workaround it by accepting the drawback that your workaround will horribly affect also other browsers:

SSLProtocol all -SSLv3

This completely disables the SSLv3 protocol and lets those browsers work. But usually this is an even less acceptable workaround. A more reasonable workaround is to address the problem more closely and disable only the ciphers which cause trouble.

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

This also lets the broken MSIE versions work, but only removes the newer 56bit TLS ciphers.

Another problem with MSIE 5.x clients is that they refuse to connect to URLs of the form https://12.34.56.78/ (IP-addresses are used instead of the hostname), if the server is using the Server Gated Cryptography (SGC) facility. This can only be avoided by using the fully qualified domain name (FQDN) of the website in hyperlinks instead, because MSIE 5.x has an error in the way it handles the SGC negotiation.

And finally there are versions of MSIE which seem to require that an SSL session can be reused (a totally non standard-conforming behaviour, of course). Connection with those MSIE versions only work if a SSL session cache is used. So, as a work-around, make sure you are using a session cache (see SSLSessionCache directive).

When I connect via HTTPS to an Apache+mod_ssl server with Netscape Navigator I get I/O errors and the message "Netscape has encountered bad data from the server" What's the reason?

The problem usually is that you had created a new server certificate with the same DN, but you had told your browser to accept forever the old server certificate. Once you clear the entry in your browser for the old certificate, everything usually will work fine. Netscape's SSL implementation is correct, so when you encounter I/O errors with Netscape Navigator it is most of the time caused by the configured certificates.

About Support

  • Resources in case of problems?
  • Support in case of problems?
  • How to write a problem report?
  • I got a core dump, can you help me?
  • How to get a backtrace?

What information resources are available in case of mod_ssl problems?

The following information resources are available. In case of problems you should search here first.

Answers in the User Manual's F.A.Q. List (this)
http://httpd.apache.org/docs-2.0/ssl/ssl_faq.html
First look inside the F.A.Q. (this text), perhaps your problem is such popular that it was already answered a lot of times in the past.
Postings from the modssl-users Support Mailing List http://www.modssl.org/support/
Second search for your problem in one of the existing archives of the modssl-users mailing list. Perhaps your problem popped up at least once for another user, too.

What support contacts are available in case of mod_ssl problems?

The following lists all support possibilities for mod_ssl, in order of preference, i.e. start in this order and do not pick the support possibility you just like most, please.

  1. Write a Problem Report into the Bug Database
    http://www.modssl.org/support/bugdb/
    This is the preferred way of submitting your problem report, because this way it gets filed into the bug database (it cannot be lost) and send to the modssl-users mailing list (others see the current problems and learn from answers).
  2. Write a Problem Report to the modssl-users Support Mailing List
    modssl-users@modssl.org
    This is the second way of submitting your problem report. You have to subscribe to the list first, but then you can easily discuss your problem with both the author and the whole mod_ssl user community.

What information and details should I provide when writing a bug report?

You have to at least always provide the following information:

Apache and OpenSSL version information
The Apache version can be determined by running ``httpd -v''. The OpenSSL version can be determined by running ``openssl version''. Alternatively when you have Lynx installed you can run the command ``lynx -mime_header http://localhost/ | grep Server'' to determine all information in a single step.
The details on how you built and installed Apache+mod_ssl+OpenSSL
For this you can provide a logfile of your terminal session which shows the configuration and install steps. Alternatively you can at least provide the configure command line you used.
In case of core dumps please include a Backtrace
In case your Apache+mod_ssl+OpenSSL should really dump core please attach a stack-frame ``backtrace'' (see the next question on how to get it). Without this information the reason for your core dump cannot be found. So you have to provide the backtrace, please.
A detailed description of your problem
Don't laugh, I'm totally serious. I already got a lot of problem reports where the people not really said what's the actual problem is. So, in your own interest (you want the problem be solved, don't you?) include as much details as possible, please. But start with the essentials first, of course.

I got a core dump, can you help me?

In general no, at least not unless you provide more details about the code location where Apache dumped core. What is usually always required in order to help you is a backtrace (see next question). Without this information it is mostly impossible to find the problem and help you in fixing it.

Ok, I got a core dump but how do I get a backtrace to find out the reason for it?

Follow the following steps:

  1. Make sure you have debugging symbols available in at least Apache. On platforms where you use GCC/GDB you have to build Apache+mod_ssl with ``OPTIM="-g -ggdb3"'' to achieve this. On other platforms at least ``OPTIM="-g"'' is needed.
  2. Startup the server and try to produce the core-dump. For this you perhaps want to use a directive like ``CoreDumpDirectory /tmp'' to make sure that the core-dump file can be written. You then should get a /tmp/core or /tmp/httpd.core file. When you don't get this, try to run your server under an UID != 0 (root), because most "current" kernels do not allow a process to dump core after it has done a setuid() (unless it does an exec()) for security reasons (there can be privileged information left over in memory). Additionally you can run ``/path/to/httpd -X'' manually to force Apache to not fork.
  3. Analyze the core-dump. For this run gdb /path/to/httpd /tmp/httpd.core or a similar command has to run. In GDB you then just have to enter the bt command and, voila, you get the backtrace. For other debuggers consult your local debugger manual. Send this backtrace to the author.


How-To / Tutorials - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

How-To / Tutorials

How-To / Tutorials

Authentication

Authentication is any process by which you verify that someone is who they claim they are. Authorization is any process by which someone is allowed to be where they want to go, or to have information that they want to have.

See: Authentication, Authorization, and Access Control

Dynamic Content with CGI

The CGI (Common Gateway Interface) defines a way for a web server to interact with external content-generating programs, which are often referred to as CGI programs or CGI scripts. It is the simplest, and most common, way to put dynamic content on your web site. This document will be an introduction to setting up CGI on your Apache web server, and getting started writing CGI programs.

See: CGI: Dynamic Content

.htaccess files

.htaccess files provide a way to make configuration changes on a per-directory basis. A file, containing one or more configuration directives, is placed in a particular document directory, and the directives apply to that directory, and all subdirectories thereof.

See: .htaccess files

Introduction to Server Side Includes

SSI (Server Side Includes) are directives that are placed in HTML pages, and evaluated on the server while the pages are being served. They let you add dynamically generated content to an existing HTML page, without having to serve the entire page via a CGI program, or other dynamic technology.

See: Server Side Includes (SSI)

Per-user web directories

On systems with multiple users, each user can be permitted to have a web site in their home directory using the UserDir directive. Visitors to a URL http://example.com/~username/ will get content out of the home directory of the user "username", out of the subdirectory specified by the UserDir directive.

See: User web directories (public_html)


Authentication, Authorization and Access Control - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > How-To / Tutorials

Authentication, Authorization and Access Control

Authentication is any process by which you verify that someone is who they claim they are. Authorization is any process by which someone is allowed to be where they want to go, or to have information that they want to have.

Related Modules and Directives

Related Modules Related Directives
  • mod_auth
  • mod_access
  • Allow
  • AuthGroupFile
  • AuthName
  • AuthType
  • AuthUserFile
  • Deny
  • Options
  • Require

Introduction

If you have information on your web site that is sensitive or intended for only a small group of people, the techniques in this article will help you make sure that the people that see those pages are the people that you wanted to see them.

This article covers the "standard" way of protecting parts of your web site that most of you are going to use.

The Prerequisites

The directives discussed in this article will need to go either in your main server configuration file (typically in a <Directory> section), or in per-directory configuration files (.htaccess files).

If you plan to use .htaccess files, you will need to have a server configuration that permits putting authentication directives in these files. This is done with the AllowOverride directive, which specifies which directives, if any, may be put in per-directory configuration files.

Since we're talking here about authentication, you will need an AllowOverride directive like the following:

AllowOverride AuthConfig

Or, if you are just going to put the directives directly in your main server configuration file, you will of course need to have write permission to that file.

And you'll need to know a little bit about the directory structure of your server, in order to know where some files are kept. This should not be terribly difficult, and I'll try to make this clear when we come to that point.

Getting it working

Here's the basics of password protecting a directory on your server.

You'll need to create a password file. This file should be placed somewhere not accessible from the web. This is so that folks cannot download the password file. For example, if your documents are served out of /usr/local/apache/htdocs you might want to put the password file(s) in /usr/local/apache/passwd.

To create the file, use the htpasswd utility that came with Apache. This will be located in the bin directory of wherever you installed Apache. To create the file, type:

htpasswd -c /usr/local/apache/passwd/passwords rbowen

htpasswd will ask you for the password, and then ask you to type it again to confirm it:

# htpasswd -c /usr/local/apache/passwd/passwords rbowen
New password: mypassword
Re-type new password: mypassword
Adding password for user rbowen

If htpasswd is not in your path, of course you'll have to type the full path to the file to get it to run. On my server, it's located at /usr/local/apache/bin/htpasswd

Next, you'll need to configure the server to request a password and tell the server which users are allowed access. You can do this either by editing the httpd.conf file or using an .htaccess file. For example, if you wish to protect the directory /usr/local/apache/htdocs/secret, you can use the following directives, either placed in the file /usr/local/apache/htdocs/secret/.htaccess, or placed in httpd.conf inside a <Directory /usr/local/apache/apache/htdocs/secret> section.

AuthType Basic
AuthName "Restricted Files"
AuthUserFile /usr/local/apache/passwd/passwords
Require user rbowen

Let's examine each of those directives individually. The AuthType directive selects that method that is used to authenticate the user. The most common method is Basic, and this is the method implemented by mod_auth. It is important to be aware, however, that Basic authentication sends the password from the client to the browser unencrypted. This method should therefore not be used for highly sensitive data. Apache supports one other authentication method: AuthType Digest. This method is implemented by mod_auth_digest and is much more secure. Only the most recent versions of clients are known to support Digest authentication.

The AuthName directive sets the Realm to be used in the authentication. The realm serves two major functions. First, the client often presents this information to the user as part of the password dialog box. Second, it is used by the client to determine what password to send for a given authenticated area.

So, for example, once a client has authenticated in the "Restricted Files" area, it will automatically retry the same password for any area on the same server that is marked with the "Restricted Files" Realm. Therefore, you can prevent a user from being prompted more than once for a password by letting multiple restricted areas share the same realm. Of course, for security reasons, the client will always need to ask again for the password whenever the hostname of the server changes.

The AuthUserFile directive sets the path to the password file that we just created with htpasswd. If you have a large number of users, it can be quite slow to search through a plain text file to authenticate the user on each request. Apache also has the ability to store user information in fast database files. The mod_auth_dbm module provides the AuthDBMUserFile directive. These files can be created and manipulated with the dbmmanage program. Many other types of authentication options are available from third party modules in the Apache Modules Database.

Finally, the Require directive provides the authorization part of the process by setting the user that is allowed to access this region of the server. In the next section, we discuss various ways to use the Require directive.

Letting more than one person in

The directives above only let one person (specifically someone with a username of rbowen) into the directory. In most cases, you'll want to let more than one person in. This is where the AuthGroupFile comes in.

If you want to let more than one person in, you'll need to create a group file that associates group names with a list of users in that group. The format of this file is pretty simple, and you can create it with your favorite editor. The contents of the file will look like this:

GroupName: rbowen dpitts sungo rshersey

That's just a list of the members of the group in a long line separated by spaces.

To add a user to your already existing password file, type:

htpasswd /usr/local/apache/passwd/password dpitts

You'll get the same response as before, but it will be appended to the existing file, rather than creating a new file. (It's the -c that makes it create a new password file).

Now, you need to modify your .htaccess file to look like the following:

AuthType Basic
AuthName "By Invitation Only"
AuthUserFile /usr/local/apache/passwd/passwords
AuthGroupFile /usr/local/apache/passwd/groups
Require group GroupName

Now, anyone that is listed in the group GroupName, and has an entry in the password file, will be let in, if they type the correct password.

There's another way to let multiple users in that is less specific. Rather than creating a group file, you can just use the following directive:

Require valid-user

Using that rather than the Require user rbowen line will allow anyone in that is listed in the password file, and who correctly enters their password. You can even emulate the group behavior here, by just keeping a separate password file for each group. The advantage of this approach is that Apache only has to check one file, rather than two. The disadvantage is that you have to maintain a bunch of password files, and remember to reference the right one in the AuthUserFile directive.

Possible problems

Because of the way that Basic authentication is specified, your username and password must be verified every time you request a document from the server. This is even if you're reloading the same page, and for every image on the page (if they come from a protected directory). As you can imagine, this slows things down a little. The amount that it slows things down is proportional to the size of the password file, because it has to open up that file, and go down the list of users until it gets to your name. And it has to do this every time a page is loaded.

A consequence of this is that there's a practical limit to how many users you can put in one password file. This limit will vary depending on the performance of your particular server machine, but you can expect to see slowdowns once you get above a few hundred entries, and may wish to consider a different authentication method at that time.

What other neat stuff can I do?

Authentication by username and password is only part of the story. Frequently you want to let people in based on something other than who they are. Something such as where they are coming from.

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 205.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.101.205
Deny from cyberthugs.com moreidiots.com
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.

More information

You should also read the documentation for mod_auth and mod_access which contain some more information about how this all works.


Apache Tutorial: Dynamic Content with CGI - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > How-To / Tutorials

Apache Tutorial: Dynamic Content with CGI

Introduction

Related Modules Related Directives
  • mod_alias
  • mod_cgi
  • AddHandler
  • Options
  • ScriptAlias

The CGI (Common Gateway Interface) defines a way for a web server to interact with external content-generating programs, which are often referred to as CGI programs or CGI scripts. It is the simplest, and most common, way to put dynamic content on your web site. This document will be an introduction to setting up CGI on your Apache web server, and getting started writing CGI programs.

Configuring Apache to permit CGI

In order to get your CGI programs to work properly, you'll need to have Apache configured to permit CGI execution. There are several ways to do this.

ScriptAlias

The ScriptAlias directive tells Apache that a particular directory is set aside for CGI programs. Apache will assume that every file in this directory is a CGI program, and will attempt to execute it, when that particular resource is requested by a client.

The ScriptAlias directive looks like:

ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/

The example shown is from your default httpd.conf configuration file, if you installed Apache in the default location. The ScriptAlias directive is much like the Alias directive, which defines a URL prefix that is to mapped to a particular directory. Alias and ScriptAlias are usually used for directories that are outside of the DocumentRoot directory. The difference between Alias and ScriptAlias is that ScriptAlias has the added meaning that everything under that URL prefix will be considered a CGI program. So, the example above tells Apache that any request for a resource beginning with /cgi-bin/ should be served from the directory /usr/local/apache/cgi-bin/, and should be treated as a CGI program.

For example, if the URL http://www.example.com/cgi-bin/test.pl is requested, Apache will attempt to execute the file /usr/local/apache/cgi-bin/test.pl and return the output. Of course, the file will have to exist, and be executable, and return output in a particular way, or Apache will return an error message.

CGI outside of ScriptAlias directories

CGI programs are often restricted to ScriptAlias'ed directories for security reasons. In this way, administrators can tightly control who is allowed to use CGI programs. However, if the proper security precautions are taken, there is no reason why CGI programs cannot be run from arbitrary directories. For example, you may wish to let users have web content in their home directories with the UserDir directive. If they want to have their own CGI programs, but don't have access to the main cgi-bin directory, they will need to be able to run CGI programs elsewhere.

Explicitly using Options to permit CGI execution

You could explicitly use the Options directive, inside your main server configuration file, to specify that CGI execution was permitted in a particular directory:

<Directory /usr/local/apache/htdocs/somedir>
Options +ExecCGI
 </Directory>

The above directive tells Apache to permit the execution of CGI files. You will also need to tell the server what files are CGI files. The following AddHandler directive tells the server to treat all files with the cgi or pl extension as CGI programs:

AddHandler cgi-script cgi pl

.htaccess files

A .htaccess file is a way to set configuration directives on a per-directory basis. When Apache serves a resource, it looks in the directory from which it is serving a file for a file called .htaccess, and, if it finds it, it will apply directives found therein. .htaccess files can be permitted with the AllowOverride directive, which specifies what types of directives can appear in these files, or if they are not allowed at all. To permit the directive we will need for this purpose, the following configuration will be needed in your main server configuration:

AllowOverride Options

In the .htaccess file, you'll need the following directive:

Options +ExecCGI

which tells Apache that execution of CGI programs is permitted in this directory.

Writing a CGI program

There are two main differences between ``regular'' programming, and CGI programming.

First, all output from your CGI program must be preceded by a MIME-type header. This is HTTP header that tells the client what sort of content it is receiving. Most of the time, this will look like:

Content-type: text/html

Secondly, your output needs to be in HTML, or some other format that a browser will be able to display. Most of the time, this will be HTML, but occasionally you might write a CGI program that outputs a gif image, or other non-HTML content.

Apart from those two things, writing a CGI program will look a lot like any other program that you might write.

Your first CGI program

The following is an example CGI program that prints one line to your browser. Type in the following, save it to a file called first.pl, and put it in your cgi-bin directory.

#!/usr/bin/perl
print "Content-type: text/html\n\n";
print "Hello, World.";

Even if you are not familiar with Perl, you should be able to see what is happening here. The first line tells Apache (or whatever shell you happen to be running under) that this program can be executed by feeding the file to the interpreter found at the location /usr/bin/perl. The second line prints the content-type declaration we talked about, followed by two carriage-return newline pairs. This puts a blank line after the header, to indicate the end of the HTTP headers, and the beginning of the body. The third line prints the string "Hello, World.". And that's the end of it.

If you open your favorite browser and tell it to get the address

http://www.example.com/cgi-bin/first.pl

or wherever you put your file, you will see the one line Hello, World. appear in your browser window. It's not very exciting, but once you get that working, you'll have a good chance of getting just about anything working.

But it's still not working!

There are four basic things that you may see in your browser when you try to access your CGI program from the web:

The output of your CGI program
Great! That means everything worked fine.
The source code of your CGI program or a "POST Method Not Allowed" message
That means that you have not properly configured Apache to process your CGI program. Reread the section on configuring Apache and try to find what you missed.
A message starting with "Forbidden"
That means that there is a permissions problem. Check the Apache error log and the section below on file permissions.
A message saying "Internal Server Error"
If you check the Apache error log, you will probably find that it says "Premature end of script headers", possibly along with an error message generated by your CGI program. In this case, you will want to check each of the below sections to see what might be preventing your CGI program from emitting the proper HTTP headers.

File permissions

Remember that the server does not run as you. That is, when the server starts up, it is running with the permissions of an unprivileged user - usually nobody, or www - and so it will need extra permissions to execute files that are owned by you. Usually, the way to give a file sufficient permissions to be executed by nobody is to give everyone execute permission on the file:

chmod a+x first.pl

Also, if your program reads from, or writes to, any other files, those files will need to have the correct permissions to permit this.

The exception to this is when the server is configured to use suexec. This program allows CGI programs to be run under different user permissions, depending on which virtual host or user home directory they are located in. Suexec has very strict permission checking, and any failure in that checking will result in your CGI programs failing with an "Internal Server Error". In this case, you will need to check the suexec log file to see what specific security check is failing.

Path information

When you run a program from your command line, you have certain information that is passed to the shell without you thinking about it. For example, you have a path, which tells the shell where it can look for files that you reference.

When a program runs through the web server as a CGI program, it does not have that path. Any programs that you invoke in your CGI program (like 'sendmail', for example) will need to be specified by a full path, so that the shell can find them when it attempts to execute your CGI program.

A common manifestation of this is the path to the script interpreter (often perl) indicated in the first line of your CGI program, which will look something like:

#!/usr/bin/perl

Make sure that this is in fact the path to the interpreter.

Syntax errors

Most of the time when a CGI program fails, it's because of a problem with the program itself. This is particularly true once you get the hang of this CGI stuff, and no longer make the above two mistakes. Always attempt to run your program from the command line before you test if via a browser. This will eliminate most of your problems.

Error logs

The error logs are your friend. Anything that goes wrong generates message in the error log. You should always look there first. If the place where you are hosting your web site does not permit you access to the error log, you should probably host your site somewhere else. Learn to read the error logs, and you'll find that almost all of your problems are quickly identified, and quickly solved.

What's going on behind the scenes?

As you become more advanced in CGI programming, it will become useful to understand more about what's happening behind the scenes. Specifically, how the browser and server communicate with one another. Because although it's all very well to write a program that prints "Hello, World.", it's not particularly useful.

Environment variables

Environment variables are values that float around you as you use your computer. They are useful things like your path (where the computer searches for a the actual file implementing a command when you type it), your username, your terminal type, and so on. For a full list of your normal, every day environment variables, type env at a command prompt.

During the CGI transaction, the server and the browser also set environment variables, so that they can communicate with one another. These are things like the browser type (Netscape, IE, Lynx), the server type (Apache, IIS, WebSite), the name of the CGI program that is being run, and so on.

These variables are available to the CGI programmer, and are half of the story of the client-server communication. The complete list of required variables is at http://hoohoo.ncsa.uiuc.edu/cgi/env.html.

This simple Perl CGI program will display all of the environment variables that are being passed around. Two similar programs are included in the cgi-bin directory of the Apache distribution. Note that some variables are required, while others are optional, so you may see some variables listed that were not in the official list. In addition, Apache provides many different ways for you to add your own environment variables to the basic ones provided by default.

#!/usr/bin/perl
print "Content-type: text/html\n\n";
foreach $key (keys %ENV) {
print "$key --> $ENV{$key}<br>";
 }

STDIN and STDOUT

Other communication between the server and the client happens over standard input (STDIN) and standard output (STDOUT). In normal everyday context, STDIN means the keyboard, or a file that a program is given to act on, and STDOUT usually means the console or screen.

When you POST a web form to a CGI program, the data in that form is bundled up into a special format and gets delivered to your CGI program over STDIN. The program then can process that data as though it was coming in from the keyboard, or from a file

The "special format" is very simple. A field name and its value are joined together with an equals (=) sign, and pairs of values are joined together with an ampersand (&). Inconvenient characters like spaces, ampersands, and equals signs, are converted into their hex equivalent so that they don't gum up the works. The whole data string might look something like:

name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey

You'll sometimes also see this type of string appended to the a URL. When that is done, the server puts that string into the environment variable called QUERY_STRING. That's called a GET request. Your HTML form specifies whether a GET or a POST is used to deliver the data, by setting the METHOD attribute in the FORM tag.

Your program is then responsible for splitting that string up into useful information. Fortunately, there are libraries and modules available to help you process this data, as well as handle other of the aspects of your CGI program.

CGI modules/libraries

When you write CGI programs, you should consider using a code library, or module, to do most of the grunt work for you. This leads to fewer errors, and faster development.

If you're writing CGI programs in Perl, modules are available on CPAN. The most popular module for this purpose is CGI.pm. You might also consider CGI::Lite, which implements a minimal set of functionality, which is all you need in most programs.

If you're writing CGI programs in C, there are a variety of options. One of these is the CGIC library, from http://www.boutell.com/cgic/.

For more information

There are a large number of CGI resources on the web. You can discuss CGI problems with other users on the Usenet group comp.infosystems.www.authoring.cgi. And the -servers mailing list from the HTML Writers Guild is a great source of answers to your questions. You can find out more at http://www.hwg.org/lists/hwg-servers/.

And, of course, you should probably read the CGI specification, which has all the details on the operation of CGI programs. You can find the original version at the NCSA and there is an updated draft at the Common Gateway Interface RFC project.

When you post a question about a CGI problem that you're having, whether to a mailing list, or to a newsgroup, make sure you provide enough information about what happened, what you expected to happen, and how what actually happened was different, what server you're running, what language your CGI program was in, and, if possible, the offending code. This will make finding your problem much simpler.

Note that questions about CGI problems should never be posted to the Apache bug database unless you are sure you have found a problem in the Apache source code.


Apache Tutorial: Introduction to Server Side Includes - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > How-To / Tutorials

Apache Tutorial: Introduction to Server Side Includes

Server-side includes provide a means to add dynamic content to existing HTML documents.

Introduction

Related Modules Related Directives
  • mod_include
  • mod_cgi
  • mod_expires
  • Options
  • XBitHack
  • AddType
  • SetOutputFilter
  • BrowserMatchNoCase

This article deals with Server Side Includes, usually called simply SSI. In this article, I'll talk about configuring your server to permit SSI, and introduce some basic SSI techniques for adding dynamic content to your existing HTML pages.

In the latter part of the article, we'll talk about some of the somewhat more advanced things that can be done with SSI, such as conditional statements in your SSI directives.

What are SSI?

SSI (Server Side Includes) are directives that are placed in HTML pages, and evaluated on the server while the pages are being served. They let you add dynamically generated content to an existing HTML page, without having to serve the entire page via a CGI program, or other dynamic technology.

The decision of when to use SSI, and when to have your page entirely generated by some program, is usually a matter of how much of the page is static, and how much needs to be recalculated every time the page is served. SSI is a great way to add small pieces of information, such as the current time. But if a majority of your page is being generated at the time that it is served, you need to look for some other solution.

Configuring your server to permit SSI

To permit SSI on your server, you must have the following directive either in your httpd.conf file, or in a .htaccess file:

Options +Includes

This tells Apache that you want to permit files to be parsed for SSI directives. Note that most configurations contain multiple Options directives that can override each other. You will probably need to apply the Options to the specific directory where you want SSI enabled in order to assure that it gets evaluated last.

Not just any file is parsed for SSI directives. You have to tell Apache which files should be parsed. There are two ways to do this. You can tell Apache to parse any file with a particular file extension, such as .shtml, with the following directives:

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

One disadvantage to this approach is that if you wanted to add SSI directives to an existing page, you would have to change the name of that page, and all links to that page, in order to give it a .shtml extension, so that those directives would be executed.

The other method is to use the XBitHack directive:

XBitHack on

XBitHack tells Apache to parse files for SSI directives if they have the execute bit set. So, to add SSI directives to an existing page, rather than having to change the file name, you would just need to make the file executable using chmod.

chmod +x pagename.html

A brief comment about what not to do. You'll occasionally see people recommending that you just tell Apache to parse all .html files for SSI, so that you don't have to mess with .shtml file names. These folks have perhaps not heard about XBitHack. The thing to keep in mind is that, by doing this, you're requiring that Apache read through every single file that it sends out to clients, even if they don't contain any SSI directives. This can slow things down quite a bit, and is not a good idea.

Of course, on Windows, there is no such thing as an execute bit to set, so that limits your options a little.

In its default configuration, Apache does not send the last modified date or content length HTTP headers on SSI pages, because these values are difficult to calculate for dynamic content. This can prevent your document from being cached, and result in slower perceived client performance. There are two ways to solve this:

  1. Use the XBitHack Full configuration. This tells Apache to determine the last modified date by looking only at the date of the originally requested file, ignoring the modification date of any included files.
  2. Use the directives provided by mod_expires to set an explicit expiration time on your files, thereby letting browsers and proxies know that it is acceptable to cache them.

Basic SSI directives

SSI directives have the following syntax:

<!--#element attribute=value attribute=value ... -->

It is formatted like an HTML comment, so if you don't have SSI correctly enabled, the browser will ignore it, but it will still be visible in the HTML source. If you have SSI correctly configured, the directive will be replaced with its results.

The element can be one of a number of things, and we'll talk some more about most of these in the next installment of this series. For now, here are some examples of what you can do with SSI

Today's date

<!--#echo var="DATE_LOCAL" -->

The echo element just spits out the value of a variable. There are a number of standard variables, which include the whole set of environment variables that are available to CGI programs. Also, you can define your own variables with the set element.

If you don't like the format in which the date gets printed, you can use the config element, with a timefmt attribute, to modify that formatting.

<!--#config timefmt="%A %B %d, %Y" -->
Today is <!--#echo var="DATE_LOCAL" -->

Modification date of the file

This document last modified <!--#flastmod file="index.html" -->

This element is also subject to timefmt format configurations.

Including the results of a CGI program

This is one of the more common uses of SSI - to output the results of a CGI program, such as everybody's favorite, a ``hit counter.''

<!--#include virtual="/cgi-bin/counter.pl" -->

Additional examples

Following are some specific examples of things you can do in your HTML documents with SSI.

When was this document modified?

Earlier, we mentioned that you could use SSI to inform the user when the document was most recently modified. However, the actual method for doing that was left somewhat in question. The following code, placed in your HTML document, will put such a time stamp on your page. Of course, you will have to have SSI correctly enabled, as discussed above.

<!--#config timefmt="%A %B %d, %Y" -->
This file last modified <!--#flastmod file="ssi.shtml" -->

Of course, you will need to replace the ssi.shtml with the actual name of the file that you're referring to. This can be inconvenient if you're just looking for a generic piece of code that you can paste into any file, so you probably want to use the LAST_MODIFIED variable instead:

<!--#config timefmt="%D" -->
This file last modified <!--#echo var="LAST_MODIFIED" -->

For more details on the timefmt format, go to your favorite search site and look for strftime. The syntax is the same.

Including a standard footer

If you are managing any site that is more than a few pages, you may find that making changes to all those pages can be a real pain, particularly if you are trying to maintain some kind of standard look across all those pages.

Using an include file for a header and/or a footer can reduce the burden of these updates. You just have to make one footer file, and then include it into each page with the include SSI command. The include element can determine what file to include with either the file attribute, or the virtual attribute. The file attribute is a file path, relative to the current directory. That means that it cannot be an absolute file path (starting with /), nor can it contain ../ as part of that path. The virtual attribute is probably more useful, and should specify a URL relative to the document being served. It can start with a /, but must be on the same server as the file being served.

<!--#include virtual="/footer.html" -->

I'll frequently combine the last two things, putting a LAST_MODIFIED directive inside a footer file to be included. SSI directives can be contained in the included file, and includes can be nested - that is, the included file can include another file, and so on.

What else can I config?

In addition to being able to config the time format, you can also config two other things.

Usually, when something goes wrong with your SSI directive, you get the message

[an error occurred while processing this directive]

If you want to change that message to something else, you can do so with the errmsg attribute to the config element:

<!--#config errmsg="[It appears that you don't know how to use SSI]" -->

Hopefully, end users will never see this message, because you will have resolved all the problems with your SSI directives before your site goes live. (Right?)

And you can config the format in which file sizes are returned with the sizefmt attribute. You can specify bytes for a full count in bytes, or abbrev for an abbreviated number in Kb or Mb, as appropriate.

Executing commands

I expect that I'll have an article some time in the coming months about using SSI with small CGI programs. For now, here's something else that you can do with the exec element. You can actually have SSI execute a command using the shell (/bin/sh, to be precise - or the DOS shell, if you're on Win32). The following, for example, will give you a directory listing.

<pre>
<!--#exec cmd="ls" -->
</pre>

or, on Windows

<pre>
<!--#exec cmd="dir" -->
</pre>

You might notice some strange formatting with this directive on Windows, because the output from dir contains the string ``<dir>'' in it, which confuses browsers.

Note that this feature is exceedingly dangerous, as it will execute whatever code happens to be embedded in the exec tag. If you have any situation where users can edit content on your web pages, such as with a ``guestbook'', for example, make sure that you have this feature disabled. You can allow SSI, but not the exec feature, with the IncludesNOEXEC argument to the Options directive.

Advanced SSI techniques

In addition to spitting out content, Apache SSI gives you the option of setting variables, and using those variables in comparisons and conditionals.

Caveat

Most of the features discussed in this article are only available to you if you are running Apache 1.2 or later. Of course, if you are not running Apache 1.2 or later, you need to upgrade immediately, if not sooner. Go on. Do it now. We'll wait.

Setting variables

Using the set directive, you can set variables for later use. We'll need this later in the discussion, so we'll talk about it here. The syntax of this is as follows:

<!--#set var="name" value="Rich" -->

In addition to merely setting values literally like that, you can use any other variable, including, for example, environment variables, or some of the variables we discussed in the last article (like LAST_MODIFIED, for example) to give values to your variables. You will specify that something is a variable, rather than a literal string, by using the dollar sign ($) before the name of the variable.

<!--#set var="modified" value="$LAST_MODIFIED" -->

To put a literal dollar sign into the value of your variable, you need to escape the dollar sign with a backslash.

<!--#set var="cost" value="\$100" -->

Finally, if you want to put a variable in the midst of a longer string, and there's a chance that the name of the variable will run up against some other characters, and thus be confused with those characters, you can place the name of the variable in braces, to remove this confusion. (It's hard to come up with a really good example of this, but hopefully you'll get the point.)

<!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->

Conditional expressions

Now that we have variables, and are able to set and compare their values, we can use them to express conditionals. This lets SSI be a tiny programming language of sorts. mod_include provides an if, elif, else, endif structure for building conditional statements. This allows you to effectively generate multiple logical pages out of one actual page.

The structure of this conditional construct is:

<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->

A test_condition can be any sort of logical comparison - either comparing values to one another, or testing the ``truth'' of a particular value. (A given string is true if it is nonempty.) For a full list of the comparison operators available to you, see the mod_include documentation. Here are some examples of how one might use this construct.

In your configuration file, you could put the following line:

BrowserMatchNoCase macintosh Mac
BrowserMatchNoCase MSIE InternetExplorer

This will set environment variables ``Mac'' and ``InternetExplorer'' to true, if the client is running Internet Explorer on a Macintosh.

Then, in your SSI-enabled document, you might do the following:

<!--#if expr="${Mac} && ${InternetExplorer}" -->
Apologetic text goes here
<!--#else -->
Cool JavaScript code goes here
<!--#endif -->

Not that I have anything against IE on Macs - I just struggled for a few hours last week trying to get some JavaScript working on IE on a Mac, when it was working everywhere else. The above was the interim workaround.

Any other variable (either ones that you define, or normal environment variables) can be used in conditional statements. With Apache's ability to set environment variables with the SetEnvIf directives, and other related directives, this functionality can let you do some pretty involved dynamic stuff without ever resorting to CGI.

Conclusion

SSI is certainly not a replacement for CGI, or other technologies used for generating dynamic web pages. But it is a great way to add small amounts of dynamic content to pages, without doing a lot of extra work.


Apache Tutorial: .htaccess files - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > How-To / Tutorials

Apache Tutorial: .htaccess files

.htaccess files provide a way to make configuration changes on a per-directory basis.

.htaccess files

Related Modules Related Directives
  • core
  • mod_auth
  • mod_cgi
  • mod_include
  • mod_mime
  • AccessFileName
  • AllowOverride
  • Options
  • AddHandler
  • SetHandler
  • AuthType
  • AuthName
  • AuthUserFile
  • AuthGroupFile
  • Require

What they are/How to use them

.htaccess files (or "distributed configuration files") provide a way to make configuration changes on a per-directory basis. A file, containing one or more configuration directives, is placed in a particular document directory, and the directives apply to that directory, and all subdirectories thereof.

Note:

If you want to call your .htaccess file something else, you can change the name of the file using the AccessFileName directive. For example, if you would rather call the file .config then you can put the following in your server configuration file:

AccessFileName .config

What you can put in these files is determined by the AllowOverride directive. This directive specifies, in categories, what directives will be honored if they are found in a .htaccess file. If a directive is permitted in a .htaccess file, the documentation for that directive will contain an Override section, specifying what value must be in AllowOverride in order for that directive to be permitted.

For example, if you look at the documentation for the AddDefaultCharset directive, you will find that it is permitted in .htaccess files. (See the Context line in the directive summary.) The Override line reads FileInfo. Thus, you must have at least AllowOverride FileInfo in order for this directive to be honored in .htaccess files.

Example:

Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo

If you are unsure whether a particular directive is permitted in a .htaccess file, look at the documentation for that directive, and check the Context line for ".htaccess".

When (not) to use .htaccess files

In general, you should never use .htaccess files unless you don't have access to the main server configuration file. There is, for example, a prevailing misconception that user authentication should always be done in .htaccess files. This is simply not the case. You can put user authentication configurations in the main server configuration, and this is, in fact, the preferred way to do things.

.htaccess files should be used in a case where the content providers need to make configuration changes to the server on a per-directory basis, but do not have root access on the server system. In the event that the server administrator is not willing to make frequent configuration changes, it might be desirable to permit individual users to make these changes in .htaccess files for themselves. This is particularly true, for example, in cases where ISPs are hosting multiple user sites on a single machine, and want their users to be able to alter their configuration.

However, in general, use of .htaccess files should be avoided when possible. Any configuration that you would consider putting in a .htaccess file, can just as effectively be made in a <Directory> section in your main server configuration file.

There are two main reasons to avoid the use of .htaccess files.

The first of these is performance. When AllowOverride is set to allow the use of .htaccess files, Apache will look in every directory for .htaccess files. Thus, permitting .htaccess files causes a performance hit, whether or not you actually even use them! Also, the .htaccess file is loaded every time a document is requested.

Further note that Apache must look for .htaccess files in all higher-level directories, in order to have a full complement of directives that it must apply. (See section on how directives are applied.) Thus, if a file is requested out of a directory /www/htdocs/example, Apache must look for the following files:

/.htaccess
/www/.htaccess
/www/htdocs/.htaccess
/www/htdocs/example/.htaccess

And so, for each file access out of that directory, there are 4 additional file-system accesses, even if none of those files are present. (Note that this would only be the case if .htaccess files were enabled for /, which is not usually the case.)

The second consideration is one of security. You are permitting users to modify server configuration, which may result in changes over which you have no control. Carefully consider whether you want to give your users this privilege. Note also that giving users less privileges than they need will lead to additional technical support requests. Make sure you clearly tell your users what level of privileges you have given them. Specifying exactly what you have set AllowOverride to, and pointing them to the relevant documentation, will save yourself a lot of confusion later.

Note that it is completely equivalent to put a .htaccess file in a directory /www/htdocs/example containing a directive, and to put that same directive in a Directory section <Directory /www/htdocs/example> in your main server configuration:

.htaccess file in /www/htdocs/example:

Contents of .htaccess file in /www/htdocs/example

AddType text/example .exm

Section from your httpd.conf file

<Directory /www/htdocs/example>
AddType text/example .exm
 </Directory>

However, putting this configuration in your server configuration file will result in less of a performance hit, as the configuration is loaded once when Apache starts, rather than every time a file is requested.

The use of .htaccess files can be disabled completely by setting the AllowOverride directive to none:

AllowOverride None

How directives are applied

The configuration directives found in a .htaccess file are applied to the directory in which the .htaccess file is found, and to all subdirectories thereof. However, it is important to also remember that there may have been .htaccess files in directories higher up. Directives are applied in the order that they are found. Therefore, a .htaccess file in a particular directory may override directives found in .htaccess files found higher up in the directory tree. And those, in turn, may have overridden directives found yet higher up, or in the main server configuration file itself.

Example:

In the directory /www/htdocs/example1 we have a .htaccess file containing the following:

Options +ExecCGI

(Note: you must have "AllowOverride Options" in effect to permit the use of the "Options" directive in .htaccess files.)

In the directory /www/htdocs/example1/example2 we have a .htaccess file containing:

Options Includes

Because of this second .htaccess file, in the directory /www/htdocs/example1/example2, CGI execution is not permitted, as only Options Includes is in effect, which completely overrides any earlier setting that may have been in place.

Authentication example

If you jumped directly to this part of the document to find out how to do authentication, it is important to note one thing. There is a common misconception that you are required to use .htaccess files in order to implement password authentication. This is not the case. Putting authentication directives in a <Directory> section, in your main server configuration file, is the preferred way to implement this, and .htaccess files should be used only if you don't have access to the main server configuration file. See above for a discussion of when you should and should not use .htaccess files.

Having said that, if you still think you need to use a .htaccess file, you may find that a configuration such as what follows may work for you.

You must have "AllowOverride AuthConfig" in effect for these directives to be honored.

.htaccess file contents:

AuthType Basic
AuthName "Password Required"
AuthUserFile /www/passwords/password.file
AuthGroupFile /www/passwords/group.file
Require Group admins

Note that AllowOverride AuthConfig must be in effect for these directives to have any effect.

Please see the authentication tutorial for a more complete discussion of authentication and authorization.

Server Side Includes example

Another common use of .htaccess files is to enable Server Side Includes for a particular directory. This may be done with the following configuration directives, placed in a .htaccess file in the desired directory:

Options +Includes
AddType text/html shtml
AddHandler server-parsed shtml

Note that AllowOverride Options and AllowOverride FileInfo must both be in effect for these directives to have any effect.

Please see the SSI tutorial for a more complete discussion of server-side includes.

CGI example

Finally, you may wish to use a .htaccess file to permit the execution of CGI programs in a particular directory. This may be implemented with the following configuration:

Options +ExecCGI
AddHandler cgi-script cgi pl

Alternately, if you wish to have all files in the given directory be considered to be CGI programs, this may be done with the following configuration:

Options +ExecCGI
SetHandler cgi-script

Note that AllowOverride Options and AllowOverride FileInfo must both be in effect for these directives to have any effect.

Please see the CGI tutorial for a more complete discussion of CGI programming and configuration.

Troubleshooting

When you put configuration directives in a .htaccess file, and you don't get the desired effect, there are a number of things that may be going wrong.

Most commonly, the problem is that AllowOverride is not set such that your configuration directives are being honored. Make sure that you don't have a AllowOverride None in effect for the file scope in question. A good test for this is to put garbage in your .htaccess file and reload. If a server error is not generated, then you almost certainly have AllowOverride None in effect.

If, on the other hand, you are getting server errors when trying to access documents, check your Apache error log. It will likely tell you that the directive used in your .htaccess file is not permitted. Alternately, it may tell you that you had a syntax error, which you will then need to fix.


Per-user web directories - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > How-To / Tutorials

Per-user web directories

On systems with multiple users, each user can be permitted to have a web site in their home directory using the UserDir directive. Visitors to a URL http://example.com/~username/ will get content out of the home directory of the user "username", out of the subdirectory specified by the UserDir directive.

See also

  • Mapping URLs to the Filesystem

Per-user web directories

Related Modules Related Directives
  • mod_userdir
  • UserDir
  • DirectoryMatch
  • AllowOverride

Setting the file path with UserDir

The UserDir directive specifies a directory out of which per-user content is loaded. This directive may take several different forms.

If a path is given which does not start with a leading slash, it is assumed to be a directory path relative to the home directory of the specified user. Given this configuration:

UserDir public_html

the URL http://example.com/~rbowen/file.html will be translated to the file path /home/rbowen/public_html/file.html

If a path is given starting with a slash, a directory path will be constructed using that path, plus the username specified. Given this configuration:

UserDir /var/html

the URL http://example.com/~rbowen/file.html will be translated to the file path /var/html/rbowen/file.html

If a path is provided which contains an asterisk (*), a path is used in which the asterisk is replaced with the username. Given this configuration:

UserDir /var/www/*/docs

the URL http://example.com/~rbowen/file.html will be translated to the file path /var/www/rbowen/docs/file.html

Restricting what users are permitted to use this feature

Using the syntax show in the UserDir documentation, you can restrict what users are permitted to use this functionality:

UserDir enabled
UserDir disabled root jro fish

The configuration above will enable the feature for all users except for those listed in the disabled statement. You can, likewise, disable the feature for all but a few users by using a configuration like the following:

UserDir disabled
UserDir enabled rbowen krietz

See UserDir documentation for additional examples.

Enabling a cgi directory for each user

In order to give each user their own cgi-bin directory, you can use a <Directory> directive to make a particular subdirectory of a user's home directory cgi-enabled.

<Directory /home/*/public_html/cgi-bin/>
Options ExecCGI
SetHandler cgi-script
</Directory>

Then, presuming that UserDir is set to public_html, a cgi program example.cgi could be loaded from that directory as:

http://example.com/~rbowen/cgi-bin/example.cgi

Allowing users to alter configuration

If you want to allows users to modify the server configuration in their web space, they will need to use .htaccess files to make these changed. Ensure that you have set AllowOverride to a value sufficient for the directives that you want to permit the users to modify. See the .htaccess tutorial for additional details on how this works.


Apache Tutorials - Apache HTTP Server

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

Apache Tutorials

Warning:

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

The following documents give you step-by-step instructions on how to accomplish common tasks with the Apache HTTP server. Many of these documents are located at external sites and are not the work of the Apache Software Foundation. Copyright to documents on external sites is owned by the authors or their assignees. Please consult the official Apache Server documentation to verify what you read on external sites.

Installation & Getting Started

  • Getting Started with Apache 1.3 (ApacheToday)
  • Configuring Your Apache Server Installation (ApacheToday)
  • Getting, Installing, and Running Apache (on Unix) (O'Reilly Network Apache DevCenter)
  • Maximum Apache: Getting Started (CNET Builder.com)
  • How to Build the Apache of Your Dreams (Developer Shed)

Basic Configuration

  • An Amble Through Apache Configuration (O'Reilly Network Apache DevCenter)
  • Using .htaccess Files with Apache (ApacheToday)
  • Setting Up Virtual Hosts (ApacheToday)
  • Maximum Apache: Configure Apache (CNET Builder.com)
  • Getting More Out of Apache (Developer Shed)

Security

  • Security and Apache: An Essential Primer (LinuxPlanet)
  • Using User Authentication (Apacheweek)
  • DBM User Authentication (Apacheweek)
  • An Introduction to Securing Apache (Linux.com)
  • Securing Apache - Access Control (Linux.com)
  • Apache Authentication Part 1 - Part 2 - Part 3 - Part 4 (ApacheToday)
  • mod_access: Restricting Access by Host (ApacheToday)

Logging

  • Log Rhythms (O'Reilly Network Apache DevCenter)
  • Gathering Visitor Information: Customising Your Logfiles (Apacheweek)
  • Apache Guide: Logging Part 1 - Part 2 - Part 3 - Part 4 - Part 5 (ApacheToday)

CGI and SSI

  • Dynamic Content with CGI (ApacheToday)
  • The Idiot's Guide to Solving Perl CGI Problems (CPAN)
  • Executing CGI Scripts as Other Users (LinuxPlanet)
  • CGI Programming FAQ (Web Design Group)
  • Introduction to Server Side Includes Part 1 - Part 2 (ApacheToday)
  • Advanced SSI Techniques (ApacheToday)
  • Setting up CGI and SSI with Apache (CNET Builder.com)

Other Features

  • Content Negotiation Explained (Apacheweek)
  • Using Apache Imagemaps (Apacheweek)
  • Keeping Your Images from Adorning Other Sites (ApacheToday)
  • Language Negotiation Notes (Alan J. Flavell)

If you have a pointer to an accurate and well-written tutorial not included here, please let us know by submitting it to the Apache Bug Database.


Platform Specific Notes - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Platform Specific Notes

Microsoft Windows

Using Apache

This document explains how to install, configure and run Apache 2.0 under Microsoft Windows.

See: Using Apache with Microsoft Windows

Compiling Apache

There are many important points before you begin compiling Apache. This document explain them.

See: Compiling Apache for Microsoft Windows

Other Platforms

Novell NetWare

This document explains how to install, configure and run Apache 2.0 under Novell NetWare 5.1 and above.

See: Using Apache With Novell NetWare

EBCDIC

Version 1.3 of the Apache HTTP Server is the first version which includes a port to a (non-ASCII) mainframe machine which uses the EBCDIC character set as its native codeset.

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

See: The Apache EBCDIC Port


Using Apache with Microsoft Windows - Apache HTTP Server

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

Using Apache with Microsoft Windows

This document explains how to install, configure and run Apache 2.0 under Microsoft Windows. If you find any bugs, or wish to contribute in other ways, please use our bug reporting page.

This document assumes that you are installing a binary distribution of Apache. If you want to compile Apache yourself (possibly to help with development or tracking down bugs), see Compiling Apache for Microsoft Windows.

Because of the current versioning policies on Microsoft Windows operating system families, this document assumes the following:

  • Windows NT: This means all versions of Windows that are based on the Windows NT kernel. Includes Windows NT, Windows 2000, Windows XP and Windows .Net Server 2003.
  • Windows 9x: This means older, consumer-oriented versions of Windows. Includes Windows 95 (also OSR2), Windows 98 and Windows ME.

Operating System Requirements

The primary Windows platform for running Apache 2.0 is Windows NT. The binary installer only works with the x86 family of processors, such as Intel and AMD processors. Running Apache on Windows 9x is not thoroughly tested, and it is never recommended on production systems.

On all operating systems, TCP/IP networking must be installed and working. If running on Windows 95, the Winsock 2 upgrade must be installed. Winsock 2 for Windows 95 can be downloaded from here.

On Windows NT 4.0, installing Service Pack 6 is strongly recommended, as Service Pack 4 created known issues with TCP/IP and Winsock integrity that were resolved in later Service Packs.

Downloading Apache for Windows

Information on the latest versions of Apache can be found on the web site of the Apache web server at http://httpd.apache.org/download.cgi. There you will find the current release, as well as more recent alpha or beta test versions, and a list of HTTP and FTP mirrors from which you can download the Apache web server. Please use a mirror near to you for a fast and reliable download.

For Windows installations you should download the version of Apache for Windows with the .msi extension. This is a single Microsoft Installer file, which contains a ready-to-run version of Apache. There is a separate .zip file, which contains only the source code. You can compile Apache yourself with the Microsoft Visual C++ (Visual Studio) tools.

Installing Apache for Windows

You need Microsoft Installer 1.2 or above for the installation to work. On Windows 9x you can update your Microsoft Installer to version 2.0 here and on Windows NT 4.0 and 2000 the version 2.0 update can be found here. Windows XP does not need this update.

Note that you cannot install two versions of Apache 2.0 on the same computer with the binary installer. You can, however, install a version of the 1.3 series and a version of the 2.0 series on the same computer without problems. If you need to have two different 2.0 versions on the same computer, you have to compile and install Apache from the source.

Run the Apache .msi file you downloaded above. The installation will ask you for these things:

  1. Network Domain. Enter the DNS domain in which your server is or will be registered in. For example, if your server's full DNS name is server.mydomain.net, you would type mydomain.net here.

  2. Server Name. Your server's full DNS name. From the example above, you would type server.mydomain.net here.

  3. Administrator's Email Address. Enter the server administrator's or webmaster's email address here. This address will be displayed along with error messages to the client by default.

  4. For whom to install Apache Select for All Users, on Port 80, as a Service - Recommended if you'd like your new Apache to listen at port 80 for incoming traffic. It will run as a service (that is, Apache will run even if no one is logged in on the server at the moment) Select only for the Current User, on Port 8080, when started Manually if you'd like to install Apache for your personal experimenting or if you already have another WWW server running on port 80.

  5. The installation type. Select Typical for everything except the source code and libraries for module development. With Custom you can specify what to install. A full install will require about 13 megabytes of free disk space. This does not include the size of your web site(s).

  6. Where to install. The default path is C:\Program Files\Apache Group under which a directory called Apache2 will be created by default.

During the installation, Apache will configure the files in the conf subdirectory to reflect the chosen installation directory. However, if any of the configuration files in this directory already exist, they will not be overwritten. Instead, the new copy of the corresponding file will be left with the extension .default. So, for example, if conf\httpd.conf already exists, it will be renamed as conf\httpd.conf.default. After the installation you should manually check to see what new settings are in the .default file, and if necessary, update your existing configuration file.

Also, if you already have a file called htdocs\index.html, it will not be overwritten (and no index.html.default will be installed either). This means it should be safe to install Apache over an existing installation, although you would have to stop the existing running server before doing the installation, and then start the new one after the installation is finished.

After installing Apache, you must edit the configuration files in the conf subdirectory as required. These files will be configured during the installation so that Apache is ready to be run from the directory it was installed into, with the documents server from the subdirectory htdocs. There are lots of other options which you should set before you really start using Apache. However, to get started quickly, the files should work as installed.

Customizing Apache for Windows

Apache is configured by the files in the conf subdirectory. These are the same files used to configure the Unix version, but there are a few different directives for Apache on Windows. See the directive index for all the available directives.

The main differences in Apache for Windows are:

  • Because Apache for Windows is multithreaded, it does not use a separate process for each request, as Apache does on Unix. Instead there are usually only two Apache processes running: a parent process, and a child which handles the requests. Within the child process each request is handled by a separate thread.

    The process management directives are also different:

    MaxRequestsPerChild: Like the Unix directive, this controls how many requests a single child process will serve before exiting. However, unlike on Unix, a single process serves all the requests at once, not just one. If this is set, it is recommended that a very high number is used. The recommended default, MaxRequestsPerChild 0, causes the child process to never exit.

    Warning: The server configuration file is reread when a new child process is started. If you have modified httpd.conf, the new child may not start or you may receive unexpected results.

    ThreadsPerChild: This directive is new. It tells the server how many threads it should use. This is the maximum number of connections the server can handle at once, so be sure to set this number high enough for your site if you get a lot of hits. The recommended default is ThreadsPerChild 50.

  • The directives that accept filenames as arguments must use Windows filenames instead of Unix ones. However, because Apache uses Unix-style names internally, you must use forward slashes, not backslashes. Drive letters can be used; if omitted, the drive with the Apache executable will be assumed.

  • Apache for Windows contains the ability to load modules at runtime, without recompiling the server. If Apache is compiled normally, it will install a number of optional modules in the \Apache2\modules directory. To activate these or other modules, the new LoadModule directive must be used. For example, to activate the status module, use the following (in addition to the status-activating directives in access.conf):

    LoadModule status_module modules/mod_status.so

    Information on creating loadable modules is also available.

  • Apache can also load ISAPI (Internet Server Application Programming Interface) extensions (i.e. internet server applications), such as those used by Microsoft IIS and other Windows servers. More information is available. Note that Apache cannot load ISAPI Filters.

  • When running CGI scripts, the method Apache uses to find the interpreter for the script is configurable using the ScriptInterpreterSource directive.

  • Since it is often difficult to manage files with names like .htaccess in Windows, you may find it useful to change the name of this per-directory configuration file using the AccessFilename directive.

  • Any errors during Apache startup are logged into the Windows event log when running on Windows NT. This mechanism acts as a backup for those situations where Apache cannot even access the normally used error.log file. You can view the Windows event log by using the Event Viewer application on Windows NT 4.0, and the Event Viewer MMC snap-in on newer versions of Windows.

    Note that there is no startup error logging on Windows 9x because no Windows event log exists on those operating systems.

Running Apache as a Service

Apache can be run as a service on Windows NT. There is some highly experimental support for similar behavior on Windows 9x.

You can install Apache as a service automatically during the installation. If you chose to install for all users, the installation will create an Apache service for you. If you specify to install for yourself only, you can manually register Apache as a service after the installation. You have to be a member of the Administrators group for the service installation to succeed.

Apache comes with a utility called the Apache Service Monitor. With it you can see and manage the state of all installed Apache services on any machine on your network. To be able to manage an Apache service with the monitor, you have to first install the service (either automatically via the installation or manually).

You can install Apache as a Windows NT service as follows from the command prompt at the Apache bin subdirectory:

apache -k install

If you need to specify the name of the service you want to install, use the following command. You have to do this if you have several different service installations of Apache on your computer.

apache -k install -n "MyServiceName"

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

apache -k install -n "MyServiceName" -f "c:\files\my.conf"

If you use the first command without any special parameters except -k install, the service will be called Apache2 and the configuration will be assumed to be conf\httpd.conf.

Removing an Apache service is easy. Just use:

apache -k uninstall

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

apache -k uninstall -n "MyServiceName"

Normal starting, restarting and shutting down of an Apache service is usually done via the Apache Service Monitor, by using commands like NET START Apache2 and NET STOP Apache2 or via normal Windows service management. Before starting Apache as a service by any means, you should test the service's configuration file by using:

apache -n "MyServiceName" -t

You can control an Apache service by its command line switches, too. To start an installed Apache service you'll use this:

apache -k start

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

apache -k stop

or

apache -k shutdown

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

apache -k restart

By default, all Apache services are registered to run as the system user (the LocalSystem account). The LocalSystem account has no privileges to your network via any Windows-secured mechanism, including the file system, named pipes, DCOM, or secure RPC. It has, however, wide privileges locally.

Never grant any network privileges to the LocalSystem account! If you need Apache to be able to access network resources, create a separate account for Apache as noted below.

You may want to create a separate account for running Apache service(s). Especially, if you have to access network resources via Apache, this is strongly recommended.

  1. Create a normal domain user account, and be sure to memorize its password.
  2. Grant the newly-created user a privilege of Log on as a service and Act as part of the operating system. On Windows NT 4.0 these privileges are granted via User Manager for Domains, but on Windows 2000 and XP you probably want to use Group Policy for propagating these settings. You can also manually set these via the Local Security Policy MMC snap-in.
  3. Confirm that the created account is a member of the Users group.
  4. Grant the account read and execute (RX) rights to all document and script folders (htdocs and cgi-bin for example).
  5. Grant the account change (RWXD) rights to the Apache logs directory.
  6. Grant the account read and execute (RX) rights to the Apache.exe binary executable.
It is usually a good practice to grant the user the Apache service runs as read and execute (RX) access to the whole Apache2 directory, except the logs subdirectory, where the user has to have at least change (RWXD) rights.

If you allow the account to log in as a user and as a service, then you can log on with that account and test that the account has the privileges to execute the scripts, read the web pages, and that you can start Apache in a console window. If this works, and you have followed the steps above, Apache should execute as a service with no problems.

Error code 2186 is a good indication that you need to review the "Log On As" configuration for the service, since Apache cannot access a required network resource. Also, pay close attention to the privileges of the user Apache is configured to run as.

When starting Apache as a service you may encounter an error message from the Windows Service Control Manager. For example, if you try to start Apache by using the Services applet in the Windows Control Panel, you may get the following message:

Could not start the Apache2 service on \\COMPUTER
Error 1067; The process terminated unexpectedly.

You will get this generic error if there is any problem with starting the Apache service. In order to see what is really causing the problem you should follow the instructions for Running Apache for Windows from the Command Prompt.

There is some support for Apache on Windows 9x to behave in a similar manner as a service on Windows NT. It is highly experimental. It is not of production-class reliability, and its future is not guaranteed. It can be mostly regarded as a risky thing to play with - proceed with caution!

There are some differences between the two kinds of services you should be aware of:

  • Apache will attempt to start and if successful it will run in the background. If you run the command

    apache -n "MyServiceName" -k start

    via a shortcut on your desktop, for example, then if the service starts successfully, a console window will flash up but it immediately disappears. If Apache detects any errors on startup such as incorrect entries in the httpd.conf configuration file, the console window will remain visible. This will display an error message which will be useful in tracking down the cause of the problem.

  • Windows 9x does not support NET START or NET STOP commands. You must control the Apache service on the command prompt via the -k switches.

  • Apache and Windows 9x offer no support for running Apache as a specific user with network privileges. In fact, Windows 9x offers no security on the local machine, either. This is the simple reason because of which the Apache Software Foundation never endorses use of a Windows 9x -based system as a public Apache server. The primitive support for Windows 9x exists only to assist the user in developing web content and learning the Apache server, and perhaps as an intranet server on a secured, private network.

Once you have confirmed that Apache runs correctly as a console application you can install, control and uninstall the pseudo-service with the same commands as on Windows NT. You can also use the Apache Service Monitor to manage Windows 9x pseudo-services.

Running Apache as a Console Application

Running Apache as a service is usually the recommended way to use it, but it is sometimes easier to work from the command line (on Windows 9x running Apache from the command line is the recommended way due to the lack of reliable service support.)

To run Apache from the command line as a console application, use the following command:

apache

Apache will execute, and will remain running until it is stopped by pressing Control-C.

You can also run Apache via the shortcut Start Apache in Console placed to Start Menu --> Programs --> Apache HTTP Server 2.0.xx --> Control Apache Server during the installation. This will open a console window and start Apache inside it. If you don't have Apache installed as a service, the window will remain visible until you stop Apache by pressing Control-C in the console window where Apache is running in. The server will exit in a few seconds. However, if you do have Apache installed as a service, the shortcut starts the service. If the Apache service is running already, the shortcut doesn't do anything.

You can tell a running Apache to stop by opening another console window and entering:

apache -k shutdown

This should be preferred over pressing Control-C because this lets Apache end any current operations and clean up gracefully.

You can also tell Apache to restart. This forces it to reread the configuration file. Any operations in progress are allowed to complete without interruption. To restart Apache, use:

apache -k restart

Note for people familiar with the Unix version of Apache: these commands provide a Windows equivalent to kill -TERM pid and kill -USR1 pid. The command line option used, -k, was chosen as a reminder of the kill command used on Unix.

If the Apache console window closes immediately or unexpectedly after startup, open the Command Prompt from the Start Menu --> Programs. Change to the folder to which you installed Apache, type the command apache, and read the error message. Then change to the logs folder, and review the error.log file for configuration mistakes. If you accepted the defaults when you installed Apache, the commands would be:

c:
cd "\Program Files\Apache Group\Apache2\bin"
apache

Then wait for Apache to stop, or press Control-C. Then enter the following:

cd ..\logs
more < error.log

When working with Apache it is important to know how it will find the configuration file. You can specify a configuration file on the command line in two ways:

  • -f specifies an absolute or relative path to a particular configuration file:

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

    or

    apache -f files\anotherconfig.conf

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

    apache -n "MyServiceName"

In both of these cases, the proper ServerRoot should be set in the configuration file.

If you don't specify a configuration file with -f or -n, Apache will use the file name compiled into the server, such as conf\httpd.conf. This built-in path is relative to the installation directory. You can verify the compiled file name from a value labelled as SERVER_CONFIG_FILE when invoking Apache with the -V switch, like this:

apache -V

Apache will then try to determine its ServerRoot by trying the following, in this order:

  1. A ServerRoot directive via the -C command line switch.
  2. The -d switch on the command line.
  3. Current working directory.
  4. A registry entry which was created if you did a binary installation.
  5. The server root compiled into the server. This is /apache by default, you can verify it by using apache -V and looking for a value labelled as HTTPD_ROOT.

During the installation, a version-specific registry key is created in the Windows registry. The location of this key depends on the type of the installation. If you chose to install Apache for all users, the key is located under the HKEY_LOCAL_MACHINE hive, like this (the version numbers will of course vary between different versions of Apache:

HKEY_LOCAL_MACHINE\SOFTWARE\Apache Group\Apache\2.0.43

Correspondingly, if you chose to install Apache for the current user only, the key is located under the HKEY_CURRENT_USER hive, the contents of which are dependent of the user currently logged on:

HKEY_CURRENT_USER\SOFTWARE\Apache Group\Apache\2.0.43

This key is compiled into the server and can enable you to test new versions without affecting the current version. Of course, you must take care not to install the new version in the same directory as another version.

If you did not do a binary install, Apache will in some scenarios complain about the missing registry key. This warning can be ignored if the server was otherwise able to find its configuration file.

The value of this key is the ServerRoot directory which contains the conf subdirectory. When Apache starts it reads the httpd.conf file from that directory. If this file contains a ServerRoot directive which contains a different directory from the one obtained from the registry key above, Apache will forget the registry key and use the directory from the configuration file. If you copy the Apache directory or configuration files to a new location it is vital that you update the ServerRoot directive in the httpd.conf file to reflect the new location.

Testing the Installation

After starting Apache (either in a console window or as a service) it will be listening on port 80 (unless you changed the Listen directive in the configuration files or installed Apache only for the current user). To connect to the server and access the default page, launch a browser and enter this URL:

http://localhost/

Apache should respond with a welcome page and a link to the Apache manual. If nothing happens or you get an error, look in the error.log file in the logs subdirectory. If your host is not connected to the net, or if you have serious problems with your DNS (Domain Name Service) configuration, you may have to use this URL:

http://127.0.0.1/

Once your basic installation is working, you should configure it properly by editing the files in the conf subdirectory. Again, if you change the configuration of the Windows NT service for Apache, first attempt to start it from the command line to make sure that the service starts with no errors.

Because Apache cannot share the same port with another TCP/IP application, you may need to stop, uninstall or reconfigure certain other services before running Apache. These conflicting services include other WWW servers and some firewall implementations.


Compiling Apache for Microsoft Windows - Apache HTTP Server

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

Compiling Apache for Microsoft Windows

There are many important points before you begin compiling Apache. See Using Apache with Microsoft Windows before you begin.

Requirements

Compiling Apache requires the following environment to be properly installed:

  • Disk Space

    Make sure you have at least 50 MB of free disk space available. After installation Apache requires approximately 10 MB of disk space, plus space for log and cache files, which can grow rapidly. The actual disk space requirements will vary considerably based on your chosen configuration and any third-party modules or libraries.

  • Microsoft Visual C++ 5.0 or higher.

    Apache can be built using the command line tools, or from within the Visual Studio IDE Workbench. The command line build requires the environment to reflect the PATH, INCLUDE, LIB and other variables that can be configured with the vcvars32 batch file:

    "c:\Program Files\DevStudio\VC\Bin\vcvars32.bat"

  • The Windows Platform SDK.

    Visual C++ 5.0 builds require an updated Microsoft Windows Platform SDK to enable some Apache features. For command line builds, the Platform SDK environment is prepared by the setenv batch file:

    "c:\Program Files\Platform SDK\setenv.bat"

    The Platform SDK files distributed with Visual C++ 6.0 and later are sufficient, so users of later version may skip this requirement.

    Note that the Windows Platform SDK update is required to enable all supported mod_isapi features. Without a recent update, Apache will issue warnings under MSVC++ 5.0 that some mod_isapi features will be disabled. Look for the update at http://msdn.microsoft.com/downloads/sdks/platform/platform.asp.

  • The awk utility (awk, gawk or similar).

    To install Apache within the build system, several files are modified using the awk.exe utility. awk was chosen since it is a very small download (compared with Perl or WSH/VB) and accomplishes the task of generating files. Brian Kernighan's http://cm.bell-labs.com/cm/cs/who/bwk/ site has a compiled native Win32 binary, http://cm.bell-labs.com/cm/cs/who/bwk/awk95.exe which you must save with the name awk.exe rather than awk95.exe.

    Note that Developer Studio IDE will only find awk.exe from the Tools menu Options... Directories tab (the Projects - VC++ Directories pane in Developer Studio 7.0) listing Executable file paths. Add the path for awk.exe to this list, and your system PATH environment variable, as needed.
    Also note that if you are using Cygwin (http://www.cygwin.com/) the awk utility is named gawk.exe and that the file awk.exe is really a symlink to the gawk.exe file. The Windows command shell does not recognize symlinks, and because of that building InstallBin will fail. A workaround is to delete awk.exe from the cygwin installation and rename gawk.exe to awk.exe.

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

    Caution: there are significant restrictions and prohibitions on the use and distribution of strong cryptography and patented intellectual property throughout the world. OpenSSL includes strong cryptography controlled by both export regulations and domestic law, as well as intellectual property protected by patent, in the United States and elsewhere. Neither the Apache Software Foundation nor the OpenSSL project can provide legal advise regarding possession, use, or distribution of the code provided by the OpenSSL project. Consult your own legal counsel, you are responsible for your own actions.

    OpenSSL must be installed into a srclib subdirectory named openssl, obtained from http://www.openssl.org/source/, in order to compile mod_ssl or the abs project (ab.exe with SSL support.) To prepare OpenSSL for both release and debug builds of Apache, and disable the patent protected features in 0.9.7, you might use the following build commands:

    perl Configure VC-WIN32
    perl util\mkfiles.pl >MINFO
    perl util\mk1mf.pl dll no-asm no-mdc2 no-rc5 no-idea VC-WIN32 >makefile
    perl util\mk1mf.pl dll debug no-asm no-mdc2 no-rc5 no-idea VC-WIN32 >makefile.dbg
    perl util\mkdef.pl 32 libeay no-asm no-mdc2 no-rc5 no-idea >ms\libeay32.def
    perl util\mkdef.pl 32 ssleay no-asm no-mdc2 no-rc5 no-idea >ms\ssleay32.def
    nmake
    nmake -f makefile.dbg

  • [Optional] zlib sources (for mod_deflate)

    Zlib must be installed into a srclib subdirectory named zlib, however those sources need not be compiled. The build system will compile the compression sources directly into the mod_deflate module. Zlib can be obtained from http://www.gzip.org/zlib/ -- mod_deflate is confirmed to build correctly with version 1.1.4.

Command-Line Build

First, unpack the Apache distribution into an appropriate directory. Open a command-line prompt and cd to that directory.

The master Apache makefile instructions are contained in the Makefile.win file. To compile Apache on Windows NT, simply use one of the following commands to compiled the release or debug build, respectively:

nmake /f Makefile.win _apacher

nmake /f Makefile.win _apached

Either command will compile Apache. The latter will include debugging information in the resulting files, making it easier to find bugs and track down problems.

Developer Studio Workspace IDE Build

Apache can also be compiled using VC++'s Visual Studio development environment. To simplify this process, a Visual Studio workspace, Apache.dsw, is provided. This workspace exposes the entire list of working .dsp projects that are required for the complete Apache binary release. It includes dependencies between the projects to assure that they are built in the appropriate order.

Open the Apache.dsw workspace, and select InstallBin (Release or Debug build, as desired) as the Active Project. InstallBin causes all related project to be built, and then invokes Makefile.win to move the compiled executables and dlls. You may personalize the INSTDIR= choice by changing InstallBin's Settings, General tab, Build command line entry. INSTDIR defaults to the /Apache2 directory. If you only want a test compile (without installing) you may build the BuildBin project instead.

The .dsp project files are distributed in Visual C++ 6.0 format. Visual C++ 5.0 (97) will recognize them. Visual C++ 7.0 (.net) must convert Apache.dsw plus the .dsp files into an Apache.sln plus .msproj files, be sure you reconvert the .msproj file if any of the source .dsp files change! This is really trivial, just open Apache.dsw in the VC++ 7.0 IDE once again.

Visual C++ 7.0 (.net) users should also use the Build menu, Configuration Manager dialog to uncheck both the Debug and Release Solution modules abs, mod_ssl and mod_deflate. These modules are built by invoking nmake or the IDE directly with the BinBuild target to build those modules explicitly, only if the srclib directories openssl and/or zlib exist.

Exported .mak files pose a greater hassle, but they are required for Visual C++ 5.0 users to build mod_ssl, abs (ab with SSL support) and/or mod_deflate. VC++ 7.0 (.net) users also benefit, nmake builds are faster than binenv builds. Build the entire project from within the VC++ 5.0 or 6.0 IDE, then use the Project Menu Export for all makefiles. You must build the projects first in order to create all dynamic auto-generated targets, so that dependencies can be parsed correctly. Run the following command to fix the paths so they will build anywhere:

perl srclib\apr\build\fixwin32mak.pl

You must type this command from the top level directory of the httpd source tree. Every .mak and .dep project file within the current directory and below will be corrected, and the timestamps adjusted to reflect the .dsp.

If you contribute back a patch that revises project files, we must commit project files in Visual Studio 6.0 format. Changes should be simple, with minimal compilation and linkage flags that will be recognized by all VC++ 5.0 through 7.0 environments.

Project Components

The Apache.dsw workspace and makefile.win nmake script both build the .dsp projects of the Apache server in the following sequence:

  1. srclib\apr\apr.dsp
  2. srclib\apr\libapr.dsp
  3. srclib\apr-util\uri\gen_uri_delims.dsp
  4. srclib\apr-util\xml\expat\lib\xml.dsp
  5. srclib\apr-util\aprutil.dsp
  6. srclib\apr-util\libaprutil.dsp
  7. srclib\pcre\dftables.dsp
  8. srclib\pcre\pcre.dsp
  9. srclib\pcre\pcreposix.dsp
  10. server\gen_test_char.dsp
  11. libhttpd.dsp
  12. Apache.dsp

In addition, the modules\ subdirectory tree contains project files for the majority of the modules.

The support\ directory contains project files for additional programs that are not part of the Apache runtime, but are used by the administrator to test Apache and maintain password and log files. Windows-specific support projects are broken out in the support\win32\ directory.

  1. support\ab.dsp
  2. support\htdigest.dsp
  3. support\htpasswd.dsp
  4. support\logresolve.dsp
  5. support\rotatelogs.dsp
  6. support\win32\ApacheMonitor.dsp
  7. support\win32\wintty.dsp

Once Apache has been compiled, it needs to be installed in its server root directory. The default is the \Apache2 directory, of the same drive.

To build and install all the files into the desired folder dir automatically, use one of the following nmake commands:

nmake /f Makefile.win installr INSTDIR=dir

nmake /f Makefile.win installd INSTDIR=dir

The dir argument to INSTDIR gives the installation directory; it can be omitted if Apache is to be installed into \Apache2.

This will install the following:

  • dir\bin\Apache.exe - Apache executable
  • dir\bin\ApacheMonitor.exe - Service monitor taskbar icon utility
  • dir\bin\htdigest.exe - Digest auth password file utility
  • dir\bin\htdbm.exe - SDBM auth database password file utility
  • dir\bin\htpasswd.exe - Basic auth password file utility
  • dir\bin\logresolve.exe - Log file dns name lookup utility
  • dir\bin\rotatelogs.exe - Log file cycling utility
  • dir\bin\wintty.exe - Console window utility
  • dir\bin\libapr.dll - Apache Portable Runtime shared library
  • dir\bin\libaprutil.dll - Apache Utility Runtime shared library
  • dir\bin\libhttpd.dll - Apache Core library
  • dir\modules\mod_*.so - Loadable Apache modules
  • dir\conf - Configuration directory
  • dir\logs - Empty logging directory
  • dir\include - C language header files
  • dir\lib - Link library files

Warning about building Apache from the development tree

Note only the .dsp files are maintained between release builds. The .mak files are NOT regenerated, due to the tremendous waste of reviewer's time. Therefore, you cannot rely on the NMAKE commands above to build revised .dsp project files unless you then export all .mak files yourself from the project. This is unnecessary if you build from within the Microsoft Developer Studio environment.
Also note it is very worthwhile to build the BuildBin target project (or the command line _apacher or _apached target) prior to exporting the make files. Many files are autogenerated in the build process. Only a full build provides all of the dependent files required to build proper dependency trees for correct build behavior.

In order to create distribution .mak files, always review the generated .mak (or .dep) dependencies for Platform SDK or other garbage includes. The DevStudio\SharedIDE\bin\ (VC5) or DevStudio\Common\MSDev98\bin\ (VC6) directory contains the sysincl.dat file, which must list all exceptions. Update this file (including both forward and backslashed paths, such as both sys/time.h and sys\time.h) to include such dependencies. Including local-install paths in a distributed .mak file will cause the build to fail completely. And don't forget to run srclib/apr/build/fixwin32mak.pl in order to fix absolute paths within the .mak files.


Using Apache With Novell NetWare - Apache HTTP Server

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

Using Apache With Novell NetWare

This document explains how to install, configure and run Apache 2.0 under Novell NetWare 6.0 and above. If you find any bugs, or wish to contribute in other ways, please use our bug reporting page.

The bug reporting page and dev-httpd mailing list are not provided to answer questions about configuration or running Apache. Before you submit a bug report or request, first consult this document, the Frequently Asked Questions page and the other relevant documentation topics. If you still have a question or problem, post it to the novell.devsup.webserver newsgroup, where many Apache users are more than willing to answer new and obscure questions about using Apache on NetWare.

Most of this document assumes that you are installing Apache from a binary distribution. If you want to compile Apache yourself (possibly to help with development, or to track down bugs), see the section on Compiling Apache for NetWare below.

Requirements

Apache 2.0 is designed to run on NetWare 6.0 service pack 3 and above. If you are running a service pack less than SP3, you must install the latest NetWare Libraries for C (LibC).

NetWare service packs are available here.

Apache 2.0 for NetWare can also be run in a NetWare 5.1 environment as long as the latest service pack or the latest version of the NetWare Libraries for C (LibC) has been installed . WARNING: Apache 2.0 for NetWare has not been targeted for or tested in this environment.

Downloading Apache for NetWare

Information on the latest version of Apache can be found on the Apache web server at http://www.apache.org/. This will list the current release, any more recent alpha or beta-test releases, together with details of mirror web and anonymous ftp sites. Binary builds of the latest releases of Apache 2.0 for NetWare can be downloaded from here.

Installing Apache for NetWare

There is no Apache install program for NetWare currently. If you are building Apache 2.0 for NetWare from source, you will need to copy the files over to the server manually.

Follow these steps to install Apache on NetWare from the binary download (assuming you will install to sys:/apache2):

  • Unzip the binary download file to the root of the SYS: volume (may be installed to any volume)
  • Edit the httpd.conf file setting ServerRoot and ServerName along with any file path values to reflect your correct server settings
  • Add SYS:/APACHE2 to the search path, for example:

    SEARCH ADD SYS:\APACHE2

Follow these steps to install Apache on NetWare manually from your own build source (assuming you will install to sys:/apache2):

  • Create a directory called Apache2 on a NetWare volume
  • Copy APACHE2.NLM, APRLIB.NLM to SYS:/APACHE2
  • Create a directory under SYS:/APACHE2 called BIN
  • Copy HTDIGEST.NLM, HTPASSWD.NLM, HTDBM.NLM, LOGRES.NLM, ROTLOGS.NLM to SYS:/APACHE2/BIN
  • Create a directory under SYS:/APACHE2 called CONF
  • Copy the HTTPD-STD.CONF file to the SYS:/APACHE2/CONF directory and rename to HTTPD.CONF
  • Copy the MIME.TYPES, CHARSET.CONV and MAGIC files to SYS:/APACHE2/CONF directory
  • Copy all files and subdirectories in \HTTPD-2.0\DOCS\ICONS to SYS:/APACHE2/ICONS
  • Copy all files and subdirectories in \HTTPD-2.0\DOCS\MANUAL to SYS:/APACHE2/MANUAL
  • Copy all files and subdirectories in \HTTPD-2.0\DOCS\ERROR to SYS:/APACHE2/ERROR
  • Copy all files and subdirectories in \HTTPD-2.0\DOCS\DOCROOT to SYS:/APACHE2/HTDOCS
  • Create the directory SYS:/APACHE2/LOGS on the server
  • Create the directory SYS:/APACHE2/CGI-BIN on the server
  • Create the directory SYS:/APACHE2/MODULES and copy all nlm modules into the modules directory
  • Edit the HTTPD.CONF file searching for all @@Value@@ markers and replacing them with the appropriate setting
  • Add SYS:/APACHE2 to the search path, for example:

    SEARCH ADD SYS:\APACHE2

Apache may be installed to other volumes besides the default SYS volume.

During the build process, adding the keyword "install" to the makefile command line will automatically produce a complete distribution package under the subdirectory DIST. Install Apache by simply copying the distribution that was produced by the makfiles to the root of a NetWare volume (see: Compiling Apache for NetWare below).

Running Apache for NetWare

To start Apache just type apache at the console. This will load apache in the OS address space. If you prefer to load Apache in a protected address space you may specify the address space with the load statement as follows:

load address space = apache2 apache2

This will load Apache into an address space called apache2. Running multiple instances of Apache concurrently on NetWare is possible by loading each instance into its own protected address space.

After starting Apache, it will be listening to port 80 (unless you changed the Listen directive in the configuration files). To connect to the server and access the default page, launch a browser and enter the server's name or address. This should respond with a welcome page, and a link to the Apache manual. If nothing happens or you get an error, look in the error_log file in the logs directory.

Once your basic installation is working, you should configure it properly by editing the files in the conf directory.

To unload Apache running in the OS address space just type the following at the console:

unload apache2

or

apache2 shutdown

If apache is running in a protected address space specify the address space in the unload statement:

unload address space = apache2 apache2

When working with Apache it is important to know how it will find the configuration files. You can specify a configuration file on the command line in two ways:

  • -f specifies a path to a particular configuration file

apache2 -f "vol:/my server/conf/my.conf"

apache -f test/test.conf

In these cases, the proper ServerRoot should be set in the configuration file.

If you don't specify a configuration file name with -f, Apache will use the file name compiled into the server, usually conf/httpd.conf. Invoking Apache with the -V switch will display this value labeled as SERVER_CONFIG_FILE. Apache will then determine its ServerRoot by trying the following, in this order:

  • A ServerRoot directive via a -C switch.
  • The -d switch on the command line.
  • Current working directory
  • The server root compiled into the server.

The server root compiled into the server is usually sys:/apache2. invoking apache with the -V switch will display this value labeled as HTTPD_ROOT.

Apache 2.0 for NetWare includes a set of command line directives that can be used to modify or display information about the running instance of the web server. These directives are only available while Apache is running. Each of these directives must be preceded by the keyword APACHE2.

RESTART
Instructs Apache to terminate all running worker threads as they become idle, reread the configuration file and restart each worker thread based on the new configuration.
VERSION
Displays version information about the currently running instance of Apache.
MODULES
Displays a list of loaded modules both built-in and external.
DIRECTIVES
Displays a list of all available directives.
SETTINGS
Enables or disables the thread status display on the console. When enabled, the state of each running threads is displayed on the Apache console screen.
SHUTDOWN
Terminates the running instance of the Apache web server.
HELP
Describes each of the runtime directives.

By default these directives are issued against the instance of Apache running in the OS address space. To issue a directive against a specific instance running in a protected address space, include the -p parameter along with the name of the address space. For more information type "apache2 Help" on the command line.

Configuring Apache for NetWare

Apache is configured by reading configuration files usually stored in the conf directory. These are the same as files used to configure the Unix version, but there are a few different directives for Apache on NetWare. See the Apache documentation for all the available directives.

The main differences in Apache for NetWare are:

  • Because Apache for NetWare is multithreaded, it does not use a separate process for each request, as Apache does on some Unix implementations. Instead there are only threads running: a parent thread, and multiple child or worker threads which handle the requests.

    Therefore the "process"-management directives are different:

    MaxRequestsPerChild - Like the Unix directive, this controls how many requests a worker thread will serve before exiting. The recommended default, MaxRequestsPerChild 0, causes the thread to continue servicing request indefinitely. It is recommended on NetWare, unless there is some specific reason, that this directive always remain set to 0.

    StartThreads - This directive tells the server how many threads it should start initially. The recommended default is StartThreads 50.

    MinSpareThreads - This directive instructs the server to spawn additional worker threads if the number of idle threads ever falls below this value. The recommended default is MinSpareThreads 10.

    MaxSpareThreads - This directive instructs the server to begin terminating worker threads if the number of idle threads ever exceeds this value. The recommended default is MaxSpareThreads 100.

    MaxThreads - This directive limits the total number of work threads to a maximum value. The recommended default is ThreadsPerChild 250.

    ThreadStackSize - This directive tells the server what size of stack to use for the individual worker thread. The recommended default is ThreadStackSize 65536.

  • The directives that accept filenames as arguments must use NetWare filenames instead of Unix names. However, because Apache uses Unix-style names internally, forward slashes must be used rather than backslashes. It is recommended that all rooted file paths begin with a volume name. If omitted, Apache will assume the SYS: volume which may not be correct.

  • Apache for NetWare has the ability to load modules at runtime, without recompiling the server. If Apache is compiled normally, it will install a number of optional modules in the \Apache2\modules directory. To activate these, or other modules, the LoadModule directive must be used. For example, to active the status module, use the following:

    LoadModule status_module modules/status.nlm

    Information on creating loadable modules is also available.

Additional NetWare specific directives:

  • CGIMapExtension - This directive maps a CGI file extension to a script interpreter.
  • SecureListen - Enables SSL encryption for a specified port.
  • NWSSLTrustedCerts - Adds trusted certificates that are used to create secure connections to proxied servers.

Compiling Apache for NetWare

Compiling Apache requires MetroWerks CodeWarrior 6.x or higher. Once Apache has been built, it can be installed to the root of any NetWare volume. The default is the sys:/Apache2 directory.

Before running the server you must fill out the conf directory. Copy the file HTTPD-STD.CONF from the distribution conf directory and rename it to HTTPD.CONF. Edit the HTTPD.CONF file searching for all @@Value@@ markers and replacing them with the appropriate setting. Copy over the conf/magic and conf/mime.types files as well. Alternatively, a complete distribution can be built by including the keyword install when invoking the makefiles.

Requirements:

The following development tools are required to build Apache 2.0 for NetWare:

  • Metrowerks CodeWarrior 6.0 or higher with the NetWare PDK 3.0 or higher.
  • NetWare Libraries for C (LibC)
  • LDAP Libraries for C
  • ZLIB Compression Library source code
  • AWK utility (awk, gawk or similar). AWK can be downloaded from http://developer.novell.com/ndk/apache.htm. The utility must be found in your windows path and must be named awk.exe.
  • To build using the makefiles, you will need GNU make version 3.78.1 (GMake) available at http://developer.novell.com/ndk/apache.htm.

Building Apache using the NetWare makefiles:

  • Set the environment variable NOVELLLIBC to the location of the NetWare Libraries for C SDK, for example:

    Set NOVELLLIBC=c:\novell\ndk\libc

  • Set the environment variable METROWERKS to the location where you installed the Metrowerks CodeWarrior compiler, for example:

    Set METROWERKS=C:\Program Files\Metrowerks\CodeWarrior

    If you installed to the default location C:\Program Files\Metrowerks\CodeWarrior, you don't need to set this.
  • Set the environment variable LDAPSDK to the location where you installed the LDAP Libraries for C, for example:

    Set LDAPSDK=c:\Novell\NDK\cldapsdk\NetWare\libc

  • Set the environment variable ZLIBSDK to the location where you installed the source code for the ZLib Library, for example:

    Set ZLIBSDK=D:\NOVELL\zlib

  • Set the environment variable AP_WORK to the full path of the \httpd-2.0 directory.
  • Set the environment variable APR_WORK to the full path of the \httpd-2.0\srclib\apr directory.
  • Make sure that the path to the AWK utility and the GNU make utility (gmake.exe) have been included in the system's PATH environment variable.
  • Download the source code and unzip to an appropriate directory on your workstation.
  • Change directory to \httpd-2.0\srclib\apr-util\uri and build GENURI.nlm by running "gmake -f nwgnumakefile".
  • Copy the file GENURI.nlm to the SYS: volume of a NetWare server and run using the following command:

    SYS:\genuri > sys:\uri_delims.h

  • Copy the file uri_delims.h to the directory \httpd-2.0\srclib\apr-util\uri on the build machine.
  • Change directory to \httpd-2.0\srclib\apr and build APR by running "gmake -f nwgnumakefile"
  • Change directory to \httpd-2.0\srclib\pcre and build DFTABLES.nlm by running "gmake -f nwgnumakefile"
  • Change directory to \httpd-2.0\server and build GENCHARS.nlm by running "gmake -f nwgnumakefile"
  • Copy the files GENCHARS.nlm and DFTABLES.nlm from their respective directories to the SYS: volume of a NetWare server and run them using the following commands:

    SYS:\genchars > sys:\test_char.h
    SYS:\dftables > sys:\chartables.c

  • Copy the files test_char.h and chartables.c to the directory \httpd-2.0\os\netware on the build machine.
  • Change directory to \httpd-2.0 and build Apache by running "gmake -f nwgnumakefile". You can create a distribution directory by adding an install parameter to the command, for example:

    gmake -f nwgnumakefile install

Additional make options

  • gmake -f nwgnumakefile

    Builds release versions of all of the binaries and copies them to a \release destination directory.

  • gmake -f nwgnumakefile DEBUG=1

    Builds debug versions of all of the binaries and copies them to a \debug destination directory.

  • gmake -f nwgnumakefile install

    Creates a complete Apache distribution with binaries, docs and additional support files in a \dist\Apache2 directory.

  • gmake -f nwgnumakefile installdev

    Same as install but also creates a \lib and \include directory in the destination directory and copies headers and import files.

  • gmake -f nwgnumakefile clean

    Cleans all object files and binaries from the \release or \debug build areas depending on whether DEBUG has been defined.

  • gmake -f nwgnumakefile clobber_all

    Same as clean and also deletes the distribution directory if it exists.


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

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

Running a High-Performance Web Server on HPUX

Date: Wed, 05 Nov 1997 16:59:34 -0800
From: Rick Jones <raj@cup.hp.com>
Reply-To: raj@cup.hp.com
Organization: Network Performance
Subject: HP-UX tuning tips

Here are some tuning tips for HP-UX to add to the tuning page.

For HP-UX 9.X: Upgrade to 10.20
For HP-UX 10.[00|01|10]: Upgrade to 10.20

For HP-UX 10.20:

Install the latest cumulative ARPA Transport Patch. This will allow you to configure the size of the TCP connection lookup hash table. The default is 256 buckets and must be set to a power of two. This is accomplished with adb against the *disc* image of the kernel. The variable name is tcp_hash_size. Notice that it's critically important that you use "W" to write a 32 bit quantity, not "w" to write a 16 bit value when patching the disc image because the tcp_hash_size variable is a 32 bit quantity.

How to pick the value? Examine the output of ftp://ftp.cup.hp.com/dist/networking/tools/connhist and see how many total TCP connections exist on the system. You probably want that number divided by the hash table size to be reasonably small, say less than 10. Folks can look at HP's SPECweb96 disclosures for some common settings. These can be found at http://www.specbench.org/. If an HP-UX system was performing at 1000 SPECweb96 connections per second, the TIME_WAIT time of 60 seconds would mean 60,000 TCP "connections" being tracked.

Folks can check their listen queue depths with ftp://ftp.cup.hp.com/dist/networking/misc/listenq.

If folks are running Apache on a PA-8000 based system, they should consider "chatr'ing" the Apache executable to have a large page size. This would be "chatr +pi L <BINARY>". The GID of the running executable must have MLOCK privileges. Setprivgrp(1m) should be consulted for assigning MLOCK. The change can be validated by running Glance and examining the memory regions of the server(s) to make sure that they show a non-trivial fraction of the text segment being locked.

If folks are running Apache on MP systems, they might consider writing a small program that uses mpctl() to bind processes to processors. A simple pid % numcpu algorithm is probably sufficient. This might even go into the source code.

If folks are concerned about the number of FIN_WAIT_2 connections, they can use nettune to shrink the value of tcp_keepstart. However, they should be careful there - certainly do not make it less than oh two to four minutes. If tcp_hash_size has been set well, it is probably OK to let the FIN_WAIT_2's take longer to timeout (perhaps even the default two hours) - they will not on average have a big impact on performance.

There are other things that could go into the code base, but that might be left for another email. Feel free to drop me a message if you or others are interested.

sincerely,

rick jones

http://www.cup.hp.com/netperf/NetperfPage.html


The Apache EBCDIC Port - Apache HTTP Server

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

The Apache EBCDIC Port

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

Overview of the Apache EBCDIC Port

Version 1.3 of the Apache HTTP Server is the first version which includes a port to a (non-ASCII) mainframe machine which uses the EBCDIC character set as its native codeset.

(It is the SIEMENS family of mainframes running the BS2000/OSD operating system. This mainframe OS nowadays features a SVR4-derived POSIX subsystem).

The port was started initially to

  • prove the feasibility of porting the Apache HTTP server to this platform
  • find a "worthy and capable" successor for the venerable CERN-3.0 daemon (which was ported a couple of years ago), and to
  • prove that Apache's preforking process model can on this platform easily outperform the accept-fork-serve model used by CERN by a factor of 5 or more.

This document serves as a rationale to describe some of the design decisions of the port to this machine.

Design Goals

One objective of the EBCDIC port was to maintain enough backwards compatibility with the (EBCDIC) CERN server to make the transition to the new server attractive and easy. This required the addition of a configurable method to define whether a HTML document was stored in ASCII (the only format accepted by the old server) or in EBCDIC (the native document format in the POSIX subsystem, and therefore the only realistic format in which the other POSIX tools like grep or sed could operate on the documents). The current solution to this is a "pseudo-MIME-format" which is intercepted and interpreted by the Apache server (see below). Future versions might solve the problem by defining an "ebcdic-handler" for all documents which must be converted.

Technical Solution

Since all Apache input and output is based upon the BUFF data type and its methods, the easiest solution was to add the conversion to the BUFF handling routines. The conversion must be settable at any time, so a BUFF flag was added which defines whether a BUFF object has currently enabled conversion or not. This flag is modified at several points in the HTTP protocol:

  • set before a request is received (because the request and the request header lines are always in ASCII format)
  • set/unset when the request body is received - depending on the content type of the request body (because the request body may contain ASCII text or a binary file)
  • set before a reply header is sent (because the response header lines are always in ASCII format)
  • set/unset when the response body is sent - depending on the content type of the response body (because the response body may contain text or a binary file)

Porting Notes

  1. The relevant changes in the source are #ifdef'ed into two categories:

    #ifdef CHARSET_EBCDIC

    Code which is needed for any EBCDIC based machine. This includes character translations, differences in contiguity of the two character sets, flags which indicate which part of the HTTP protocol has to be converted and which part doesn't etc.

    #ifdef _OSD_POSIX

    Code which is needed for the SIEMENS BS2000/OSD mainframe platform only. This deals with include file differences and socket implementation topics which are only required on the BS2000/OSD platform.

  2. The possibility to translate between ASCII and EBCDIC at the socket level (on BS2000 POSIX, there is a socket option which supports this) was intentionally not chosen, because the byte stream at the HTTP protocol level consists of a mixture of protocol related strings and non-protocol related raw file data. HTTP protocol strings are always encoded in ASCII (the GET request, any Header: lines, the chunking information etc.) whereas the file transfer parts (i.e., GIF images, CGI output etc.) should usually be just "passed through" by the server. This separation between "protocol string" and "raw data" is reflected in the server code by functions like bgets() or rvputs() for strings, and functions like bwrite() for binary data. A global translation of everything would therefore be inadequate.

    (In the case of text files of course, provisions must be made so that EBCDIC documents are always served in ASCII)

  3. This port therefore features a built-in protocol level conversion for the server-internal strings (which the compiler translated to EBCDIC strings) and thus for all server-generated documents. The hard coded ASCII escapes \012 and \015 which are ubiquitous in the server code are an exception: they are already the binary encoding of the ASCII \n and \r and must not be converted to ASCII a second time. This exception is only relevant for server-generated strings; and external EBCDIC documents are not expected to contain ASCII newline characters.

  4. By examining the call hierarchy for the BUFF management routines, I added an "ebcdic/ascii conversion layer" which would be crossed on every puts/write/get/gets, and a conversion flag which allowed enabling/disabling the conversions on-the-fly. Usually, a document crosses this layer twice from its origin source (a file or CGI output) to its destination (the requesting client): file -> Apache, and Apache -> client.

    The server can now read the header lines of a CGI-script output in EBCDIC format, and then find out that the remainder of the script's output is in ASCII (like in the case of the output of a WWW Counter program: the document body contains a GIF image). All header processing is done in the native EBCDIC format; the server then determines, based on the type of document being served, whether the document body (except for the chunking information, of course) is in ASCII already or must be converted from EBCDIC.

  5. For Text documents (MIME types text/plain, text/html etc.), an implicit translation to ASCII can be used, or (if the users prefer to store some documents in raw ASCII form for faster serving, or because the files reside on a NFS-mounted directory tree) can be served without conversion.

    Example:

    to serve files with the suffix .ahtml as a raw ASCII text/html document without implicit conversion (and suffix .ascii as ASCII text/plain), use the directives:

    AddType text/x-ascii-html .ahtml
    AddType text/x-ascii-plain .ascii

    Similarly, any text/foo MIME type can be served as "raw ASCII" by configuring a MIME type "text/x-ascii-foo" for it using AddType.

  6. Non-text documents are always served "binary" without conversion. This seems to be the most sensible choice for, .e.g., GIF/ZIP/AU file types. This of course requires the user to copy them to the mainframe host using the "rcp -b" binary switch.

  7. Server parsed files are always assumed to be in native (i.e., EBCDIC) format as used on the machine, and are converted after processing.

  8. For CGI output, the CGI script determines whether a conversion is needed or not: by setting the appropriate Content-Type, text files can be converted, or GIF output can be passed through unmodified. An example for the latter case is the wwwcount program which we ported as well.

Document Storage Notes

Binary Files

All files with a Content-Type: which does not start with text/ are regarded as binary files by the server and are not subject to any conversion. Examples for binary files are GIF images, gzip-compressed files and the like.

When exchanging binary files between the mainframe host and a Unix machine or Windows PC, be sure to use the ftp "binary" (TYPE I) command, or use the rcp -b command from the mainframe host (the -b switch is not supported in unix rcp's).

Text Documents

The default assumption of the server is that Text Files (i.e., all files whose Content-Type: starts with text/) are stored in the native character set of the host, EBCDIC.

Server Side Included Documents

SSI documents must currently be stored in EBCDIC only. No provision is made to convert it from ASCII before processing.

Apache Modules' Status

Module | Status | Notes
core | + |
mod_access | + |
mod_actions | + |
mod_alias | + |
mod_asis | + |
mod_auth | + |
mod_auth_anon | + |
mod_auth_dbm | ? | with own libdb.a
mod_autoindex | + |
mod_cern_meta | ? |
mod_cgi | + |
mod_digest | + |
mod_dir | + |
mod_so | - | no shared libs
mod_env | + |
mod_example | - | (test bed only)
mod_expires | + |
mod_headers | + |
mod_imap | + |
mod_include | + |
mod_info | + |
mod_log_agent | + |
mod_log_config | + |
mod_log_referer | + |
mod_mime | + |
mod_mime_magic | ? | not ported yet
mod_negotiation | + |
mod_proxy | + |
mod_rewrite | + | untested
mod_setenvif | + |
mod_speling | + |
mod_status | + |
mod_unique_id | + |
mod_userdir | + |
mod_usertrack | ? | untested

Third Party Modules' Status

Module | Status | Notes
mod_jserv | - | JAVA still being ported.
mod_php3 | + | mod_php3 runs fine, with LDAP and GD and FreeType libraries.
mod_put | ? | untested
mod_session | - | untested


Server and Supporting Programs - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Server and Supporting Programs

This page documents all the executable programs included with the Apache HTTP Server.

Index

httpd
Apache hypertext transfer protocol server
apachectl
Apache HTTP server control interface
ab
Apache HTTP server benchmarking tool
apxs
APache eXtenSion tool
dbmmanage
Create and update user authentication files in DBM format for basic authentication
htdigest
Create and update user authentication files for digest authentication
htpasswd
Create and update user authentication files for basic authentication
logresolve
Resolve hostnames for IP-addresses in Apache logfiles
rotatelogs
Rotate Apache logs without having to kill the server
suexec
Switch User For Exec
Other Programs
Support tools with no own manual page.


httpd - Apache Hypertext Transfer Protocol Server - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

httpd - Apache Hypertext Transfer Protocol Server

httpd is the Apache HyperText Transfer Protocol (HTTP) server program. It is designed to be run as a standalone daemon process. When used like this it will create a pool of child processes or threads to handle requests.

In general, httpd should not be invoked directly, but rather should be invoked via apachectl on Unix-based systems or as a service on Windows NT, 2000 and XP and as a console application on Windows 9x and ME.

See also

  • Starting Apache
  • Stopping Apache
  • Configuration Files
  • Platform-specific Documentation
  • apachectl

Synopsis

httpd [ -d serverroot ] [ -f config ] [ -C directive ] [ -c directive ] [ -D parameter ] [ -e level ] [ -E file ] [ -k start|restart|graceful|stop ] [ -R directory ] [ -h ] [ -l ] [ -L ] [ -S ] [ -t ] [ -v ] [ -V ] [ -X ]

On Windows systems, the following additional arguments are available:

httpd [ -k install|config|uninstall ] [ -n name ] [ -w ]

Options

-d serverroot
Set the initial value for the ServerRoot directive to serverroot. This can be overridden by the ServerRoot directive in the configuration file. The default is /usr/local/apache2.
-f config
Uses the directives in the file config on startup. If config does not begin with a /, then it is taken to be a path relative to the ServerRoot. The default is conf/httpd.conf.
-k start|restart|graceful|stop
Signals httpd to start, restart, or stop. See Stopping Apache for more information.
-C directive
Process the configuration directive before reading config files.
-c directive
Process the configuration directive after reading config files.
-D parameter
Sets a configuration parameter which can be used with <IfDefine> sections in the configuration files to conditionally skip or process commands at server startup and restart.
-e level
Sets the LogLevel to level during server startup. This is useful for temporarily increasing the verbosity of the error messages to find problems during startup.
-E file
Send error messages during server startup to file.
-R directory
When the server is compiled using the SHARED_CORE rule, this specifies the directory for the shared object files.
-h
Output a short summary of available command line options.
-l
Output a list of modules compiled into the server. This will not list dynamically loaded modules included using the LoadModule directive.
-L
Output a list of directives together with expected arguments and places where the directive is valid.
-S
Show the settings as parsed from the config file (currently only shows the virtualhost settings).
-t
Run syntax tests for configuration files only. The program immediately exits after these syntax parsing tests with either a return code of 0 (Syntax OK) or return code not equal to 0 (Syntax Error). If -D DUMP_VHOSTS is also set, details of the virtual host configuration will be printed.
-v
Print the version of httpd, and then exit.
-V
Print the version and build parameters of httpd, and then exit.
-X
Run httpd in debug mode. Only one worker will be started and the server will not detach from the console.

The following arguments are available only on the Windows platform:

-k install|config|uninstall
Install Apache as a Windows NT service; change startup options for the Apache service; and uninstall the Apache service.
-n name
The name of the Apache service to signal.
-w
Keep the console window open on error so that the error message can be read.


ab - Apache HTTP server benchmarking tool - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

ab - Apache HTTP server benchmarking tool

ab is a tool for benchmarking your Apache Hypertext Transfer Protocol (HTTP) server. It is designed to give you an impression of how your current Apache installation performs. This especially shows you how many requests per second your Apache installation is capable of serving.

See also

  • httpd

Synopsis

ab
    [ -A auth-username:password ]
    [ -c concurrency ]
    [ -C cookie-name=value ]
    [ -d ]
    [ -e csv-file ]
    [ -g gnuplot-file ]
    [ -h ]
    [ -H custom-header ]
    [ -i ]
    [ -k ]
    [ -n requests ]
    [ -p POST-file ]
    [ -P proxy-auth-username:password ]
    [ -q ]
    [ -s ]
    [ -S ]
    [ -t timelimit ]
    [ -T content-type ]
    [ -v verbosity]
    [ -V ]
    [ -w ]
    [ -x <table>-attributes ]
    [ -X proxy[:port] ]
    [ -y <tr>-attributes ]
    [ -z <td>-attributes ]
    [http://]hostname[:port]/path

Options

-A auth-username:password
Supply BASIC Authentication credentials to the server. The username and password are separated by a single : and sent on the wire base64 encoded. The string is sent regardless of whether the server needs it (i.e., has sent an 401 authentication needed).
-c concurrency
Number of multiple requests to perform at a time. Default is one request at a time.
-C cookie-name=value
Add a Cookie: line to the request. The argument is typically in the form of a name=value pair. This field is repeatable.
-d
Do not display the "percentage served within XX [ms] table". (legacy support).
-e csv-file
Write a Comma separated value (CSV) file which contains for each percentage (from 1% to 100%) the time (in milliseconds) it took to serve that percentage of the requests. This is usually more useful than the 'gnuplot' file; as the results are already 'binned'.
-g gnuplot-file
Write all measured values out as a 'gnuplot' or TSV (Tab separate values) file. This file can easily be imported into packages like Gnuplot, IDL, Mathematica, Igor or even Excell. The labels are on the first line of the file.
-h
Display usage information.
-H custom-header
Append extra headers to the request. The argument is typically in the form of a valid header line, containing a colon-separated field-value pair (i.e., "Accept-Encoding: zip/zop;8bit").
-i
Do HEAD requests instead of GET.
-k
Enable the HTTP KeepAlive feature, i.e., perform multiple requests within one HTTP session. Default is no KeepAlive.
-n requests
Number of requests to perform for the benchmarking session. The default is to just perform a single request which usually leads to non-representative benchmarking results.
-p POST-file
File containing data to POST.
-P proxy-auth-username:password
Supply BASIC Authentication credentials to a proxy en-route. The username and password are separated by a single : and sent on the wire base64 encoded. The string is sent regardless of whether the proxy needs it (i.e., has sent an 407 proxy authentication needed).
-q
When processing more than 150 requests, ab outputs a progress count on stderr every 10% or 100 requests or so. The -q flag will suppress these messages.
-s
When compiled in (ab -h will show you) use the SSL protected https rather than the http protocol. This feature is experimental and very rudimentary. You probably do not want to use it.
-S
Do not display the median and standard deviation values, nor display the warning/error messages when the average and median are more than one or two times the standard deviation apart. And default to the min/avg/max values. (legacy support).
-t timelimit
Maximum number of seconds to spend for benchmarking. This implies a -n 50000 internally. Use this to benchmark the server within a fixed total amount of time. Per default there is no timelimit.
-T content-type
Content-type header to use for POST data.
-v verbosity
Set verbosity level - 4 and above prints information on headers, 3 and above prints response codes (404, 200, etc.), 2 and above prints warnings and info.
-V
Display version number and exit.
-w
Print out results in HTML tables. Default table is two columns wide, with a white background.
-x <table>-attributes
String to use as attributes for <table>. Attributes are inserted <table here >.
-X proxy[:port]
Use a proxy server for the requests.
-y <tr>-attributes
String to use as attributes for <tr>.
-z <td>-attributes
String to use as attributes for <td>.

Bugs

There are various statically declared buffers of fixed length. Combined with the lazy parsing of the command line arguments, the response headers from the server and other external inputs, this might bite you.

It does not implement HTTP/1.x fully; only accepts some 'expected' forms of responses. The rather heavy use of strstr(3) shows up top in profile, which might indicate a performance problem; i.e., you would measure the ab performance rather than the server's.


apachectl - Apache HTTP Server Control Interface - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

apachectl - Apache HTTP Server Control Interface

apachectl is a front end to the Apache HyperText Transfer Protocol (HTTP) server. It is designed to help the administrator control the functioning of the Apache httpd daemon.

The apachectl script can operate in two modes. First, it can act as a simple front-end to the httpd command that simply sets any necessary environment variables and then invokes httpd, passing through any command line arguments. Second, apachectl can act as a SysV init script, taking simple one-word arguments like start, restart, and stop, and translating them into appropriate signals to httpd.

If your Apache installation uses non-standard paths, you will need to edit the apachectl script to set the appropriate paths to the httpd binary. You can also specify any necessary httpd command line arguments. See the comments in the script for details.

The apachectl script returns a 0 exit value on success, and >0 if an error occurs. For more details, view the comments in the script.

See also

  • Starting Apache
  • Stopping Apache
  • Configuration Files
  • Platform Docs
  • httpd

Synopsis

When acting in pass-through mode, apachectl can take all the arguments available for the httpd binary.

apachectl [ httpd-argument ]

When acting in SysV init mode, apachectl takes simple, one-word commands, defined below.

apachectl command

Options

Only the SysV init-style options are defined here. Other arguments are defined on the httpd manual page.

start
Start the Apache httpd daemon. Gives an error if it is already running. This is equivalent to apachectl -k start.
stop
Stops the Apache httpd daemon. This is equivalent to apachectl -k stop.
restart
Restarts the Apache httpd daemon. If the daemon is not running, it is started. This command automatically checks the configuration files as in configtest before initiating the restart to make sure the daemon doesn't die. This is equivalent to apachectl -k restart.
fullstatus
Displays a full status report from mod_status. For this to work, you need to have mod_status enabled on your server and a text-based browser such as lynx available on your system. The URL used to access the status report can be set by editing the STATUSURL variable in the script.
status
Displays a brief status report. Similar to the fullstatus option, except that the list of requests currently being served is omitted.
graceful
Gracefully restarts the Apache httpd daemon. If the daemon is not running, it is started. This differs from a normal restart in that currently open connections are not aborted. A side effect is that old log files will not be closed immediately. This means that if used in a log rotation script, a substantial delay may be necessary to ensure that the old log files are closed before processing them. This command automatically checks the configuration files as in configtest before initiating the restart to make sure Apache doesn't die. This is equivalent to apachectl -k graceful.
configtest
Run a configuration file syntax test. It parses the configuration files and either reports Syntax Ok or detailed information about the particular syntax error. This is equivalent to apachectl -t.

The following additional option is available, but deprecated.

startssl
This is equivalent to apachectl -k start -DSSL. We recommend that you use that command explicitly, or you adjust your httpd.conf to remove the <IfDefine> section so that SSL will always be available.


apxs - APache eXtenSion tool - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

apxs - APache eXtenSion tool

apxs is a tool for building and installing extension modules for the Apache HyperText Transfer Protocol (HTTP) server. This is achieved by building a dynamic shared object (DSO) from one or more source or object files which then can be loaded into the Apache server under runtime via the LoadModule directive from mod_so.

So to use this extension mechanism your platform has to support the DSO feature and your Apache httpd binary has to be built with the mod_so module. The apxs tool automatically complains if this is not the case. You can check this yourself by manually running the command

$ httpd -l

The module mod_so should be part of the displayed list. If these requirements are fulfilled you can easily extend your Apache server's functionality by installing your own modules with the DSO mechanism by the help of this apxs tool:

$ apxs -i -a -c mod_foo.c
gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
ld -Bshareable -o mod_foo.so mod_foo.o
cp mod_foo.so /path/to/apache/modules/mod_foo.so
chmod 755 /path/to/apache/modules/mod_foo.so
[activating module `foo' in /path/to/apache/etc/httpd.conf]
$ apachectl restart
/path/to/apache/sbin/apachectl restart: httpd not running, trying to start
[Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
/path/to/apache/sbin/apachectl restart: httpd started
$ _

The arguments files can be any C source file (.c), a object file (.o) or even a library archive (.a). The apxs tool automatically recognizes these extensions and automatically used the C source files for compilation while just using the object and archive files for the linking phase. But when using such pre-compiled objects make sure they are compiled for position independent code (PIC) to be able to use them for a dynamically loaded shared object. For instance with GCC you always just have to use -fpic. For other C compilers consult its manual page or at watch for the flags apxs uses to compile the object files.

For more details about DSO support in Apache read the documentation of mod_so or perhaps even read the src/modules/standard/mod_so.c source file.

See also

  • apachectl
  • httpd

Synopsis

apxs -g [ -S name=value ] -n modname

apxs -q [ -S name=value ] query ...

apxs -c
    [ -S name=value ]
    [ -o dsofile ]
    [ -I incdir ]
    [ -D name=value ]
    [ -L libdir ]
    [ -l libname ]
    [ -Wc,compiler-flags ]
    [ -Wl,linker-flags ]
    files ...

apxs -i
    [ -S name=value ]
    [ -n modname ]
    [ -a ]
    [ -A ]
    dso-file ...

apxs -e
    [ -S name=value ]
    [ -n modname ]
    [ -a ]
    [ -A ]
    dso-file ...

Options

Common Options

-n modname
This explicitly sets the module name for the -i (install) and -g (template generation) option. Use this to explicitly specify the module name. For option -g this is required, for option -i the apxs tool tries to determine the name from the source or (as a fallback) at least by guessing it from the filename.

Query Options

-q
Performs a query for apxs's knowledge about certain settings. The query parameters can be one or more of the following strings: CC, CFLAGS, CFLAGS_SHLIB, INCLUDEDIR, LD_SHLIB, LDFLAGS_SHLIB, LIBEXECDIR, LIBS_SHLIB, SBINDIR, SYSCONFDIR, TARGET.

Use this for manually determining settings. For instance use

INC=-I`apxs -q INCLUDEDIR`

inside your own Makefiles if you need manual access to Apache's C header files.

Configuration Options

-S name=value
This option changes the apxs settings described above.

Template Generation Options

-g
This generates a subdirectory name (see option -n) and there two files: A sample module source file named mod_name.c which can be used as a template for creating your own modules or as a quick start for playing with the apxs mechanism. And a corresponding Makefile for even easier build and installing of this module.

DSO Compilation Options

-c
This indicates the compilation operation. It first compiles the C source files (.c) of files into corresponding object files (.o) and then builds a dynamically shared object in dsofile by linking these object files plus the remaining object files (.o and .a) of files. If no -o option is specified the output file is guessed from the first filename in files and thus usually defaults to mod_name.so.
-o dsofile
Explicitly specifies the filename of the created dynamically shared object. If not specified and the name cannot be guessed from the files list, the fallback name mod_unknown.so is used.
-D name=value
This option is directly passed through to the compilation command(s). Use this to add your own defines to the build process.
-I incdir
This option is directly passed through to the compilation command(s). Use this to add your own include directories to search to the build process.
-L libdir
This option is directly passed through to the linker command. Use this to add your own library directories to search to the build process.
-l libname
This option is directly passed through to the linker command. Use this to add your own libraries to search to the build process.
-Wc,compiler-flags
This option passes compiler-flags as additional flags to the compiler command. Use this to add local compiler-specific options.
-Wl,linker-flags
This option passes linker-flags as additional flags to the linker command. Use this to add local linker-specific options.

DSO Installation and Configuration Options

-i
This indicates the installation operation and installs one or more dynamically shared objects into the server's modules directory.
-a
This activates the module by automatically adding a corresponding LoadModule line to Apache's httpd.conf configuration file, or by enabling it if it already exists.
-A
Same as option -a but the created LoadModule directive is prefixed with a hash sign (#), i.e., the module is just prepared for later activation but initially disabled.
-e
This indicates the editing operation, which can be used with the -a and -A options similarly to the -i operation to edit Apache's httpd.conf configuration file without attempting to install the module.

Examples

Assume you have an Apache module named mod_foo.c available which should extend Apache's server functionality. To accomplish this you first have to compile the C source into a shared object suitable for loading into the Apache server under runtime via the following command:

$ apxs -c mod_foo.c
gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
ld -Bshareable -o mod_foo.so mod_foo.o
$ _

Then you have to update the Apache configuration by making sure a LoadModule directive is present to load this shared object. To simplify this step apxs provides an automatic way to install the shared object in its "modules" directory and updating the httpd.conf file accordingly. This can be achieved by running:

$ apxs -i -a mod_foo.c
cp mod_foo.so /path/to/apache/modules/mod_foo.so
chmod 755 /path/to/apache/modules/mod_foo.so
[activating module `foo' in /path/to/apache/etc/httpd.conf]
$ _

This way a line named

LoadModule foo_module modules/mod_foo.so

is added to the configuration file if still not present. If you want to have this disabled per default use the -A option, i.e.

$ apxs -i -A mod_foo.c

For a quick test of the apxs mechanism you can create a sample Apache module template plus a corresponding Makefile via:

$ apxs -g -n foo
Creating [DIR] foo
Creating [FILE] foo/Makefile
Creating [FILE] foo/mod_foo.c
$ _

Then you can immediately compile this sample module into a shared object and load it into the Apache server:

$ cd foo
$ make all reload
apxs -c mod_foo.c
gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
ld -Bshareable -o mod_foo.so mod_foo.o
apxs -i -a -n "foo" mod_foo.so
cp mod_foo.so /path/to/apache/modules/mod_foo.so
chmod 755 /path/to/apache/modules/mod_foo.so
[activating module `foo' in /path/to/apache/etc/httpd.conf]
apachectl restart
/path/to/apache/sbin/apachectl restart: httpd not running, trying to start
[Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
/path/to/apache/sbin/apachectl restart: httpd started
$ _

You can even use apxs to compile complex modules outside the Apache source tree, like PHP3:

$ cd php3
$ ./configure --with-shared-apache=../apache-1.3
$ apxs -c -o libphp3.so mod_php3.c libmodphp3-so.a
gcc -fpic -DSHARED_MODULE -I/tmp/apache/include -c mod_php3.c
ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a
$ _

because apxs automatically recognized C source files and object files. Only C source files are compiled while remaining object files are used for the linking phase.


dbmmanage - Manage user authentication files in DBM format - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

dbmmanage - Manage user authentication files in DBM format

dbmmanage is used to create and update the DBM format files used to store usernames and password for basic authentication of HTTP users. Resources available from the Apache HTTP server can be restricted to just the users listed in the files created by dbmmanage. This program can only be used when the usernames are stored in a DBM file. To use a flat-file database see htpasswd.

This manual page only lists the command line arguments. For details of the directives necessary to configure user authentication in httpd see the httpd manual, which is part of the Apache distribution or can be found at http://httpd.apache.org/.

See also

  • httpd
  • mod_auth_dbm

Synopsis

dbmmanage [ encoding ] filename add|adduser|check|delete|update username [ encpasswd [ group[,group...] [ comment ] ] ]

dbmmanage filename view [ username ]

dbmmanage filename import

Options

filename
The filename of the DBM format file. Usually without the extension .db, .pag, or .dir.
username
The user for which the operations are performed. The username may not contain a colon (:).
encpasswd
This is the already encrypted password to use for the update and add commands. You may use a hyphen (-) if you want to get prompted for the password, but fill in the fields afterwards. Additionally when using the update command, a period (.) keeps the original password untouched.
group
A group, which the user is member of. A groupname may not contain a colon (:). You may use a hyphen (-) if you don't want to assign the user to a group, but fill in the comment field. Additionally when using the update command, a period (.) keeps the original groups untouched.
comment
This is the place for your opaque comments about the user, like realname, mailaddress or such things. The server will ignore this field.

Encodings

-d
crypt encryption (default, except on Win32, Netware)
-m
MD5 encryption (default on Win32, Netware)
-s
SHA1 encryption
-p
plaintext (not recommended)

Commands

add
Adds an entry for username to filename using the encrypted password encpasswd.
adduser
Asks for a password and then adds an entry for username to filename.
check
Asks for a password and then checks if username is in filename and if it's password matches the specified one.
delete
Deletes the username entry from filename.
import
Reads username:password entries (one per line) from STDIN and adds them to filename. The passwords already have to be crypted.
update
Same as the adduser command, except that it makes sure username already exists in filename.
view
Just displays the contents of the DBM file. If you specify a username, it displays the particular record only.

Bugs

One should be aware that there are a number of different DBM file formats in existence, and with all likelihood, libraries for more than one format may exist on your system. The three primary examples are SDBM, NDBM, the GNU project's GDBM, and Berkeley DB 2. Unfortunately, all these libraries use different file formats, and you must make sure that the file format used by filename is the same format that dbmmanage expects to see. dbmmanage currently has no way of determining what type of DBM file it is looking at. If used against the wrong format, will simply return nothing, or may create a different DBM file with a different name, or at worst, it may corrupt the DBM file if you were attempting to write to it.

dbmmanage has a list of DBM format preferences, defined by the @AnyDBM::ISA array near the beginning of the program. Since we prefer the Berkeley DB 2 file format, the order in which dbmmanage will look for system libraries is Berkeley DB 2, then NDBM, then GDBM and then SDBM. The first library found will be the library dbmmanage will attempt to use for all DBM file transactions. This ordering is slightly different than the standard @AnyDBM::ISA ordering in Perl, as well as the ordering used by the simple dbmopen() call in Perl, so if you use any other utilities to manage your DBM files, they must also follow this preference ordering. Similar care must be taken if using programs in other languages, like C, to access these files.

One can usually use the file program supplied with most Unix systems to see what format a DBM file is in.


htdigest - manage user files for digest authentication - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

htdigest - manage user files for digest authentication

htdigest is used to create and update the flat-files used to store usernames, realm and password for digest authentication of HTTP users. Resources available from the Apache HTTP server can be restricted to just the users listed in the files created by htdigest.

This manual page only lists the command line arguments. For details of the directives necessary to configure digest authentication in httpd see the Apache manual, which is part of the Apache distribution or can be found at http://httpd.apache.org/.

See also

  • httpd
  • mod_auth_digest

Synopsis

htdigest [ -c ] passwdfile realm username

Options

-c
Create the passwdfile. If passwdfile already exists, it is deleted first.
passwdfile
Name of the file to contain the username, realm and password. If -c is given, this file is created if it does not already exist, or deleted and recreated if it does exist.
realm
The realm name to which the user name belongs.
username
The user name to create or update in passwdfile. If username does not exist is this file, an entry is added. If it does exist, the password is changed.


htpasswd - Manage user files for basic authentication - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

htpasswd - Manage user files for basic authentication

htpasswd is used to create and update the flat-files used to store usernames and password for basic authentication of HTTP users. If htpasswd cannot access a file, such as not being able to write to the output file or not being able to read the file in order to update it, it returns an error status and makes no changes.

Resources available from the Apache HTTP server can be restricted to just the users listed in the files created by htpasswd. This program can only manage usernames and passwords stored in a flat-file. It can encrypt and display password information for use in other types of data stores, though. To use a DBM database see dbmmanage.

htpasswd encrypts passwords using either a version of MD5 modified for Apache, or the system's crypt() routine. Files managed by htpasswd may contain both types of passwords; some user records may have MD5-encrypted passwords while others in the same file may have passwords encrypted with crypt().

This manual page only lists the command line arguments. For details of the directives necessary to configure user authentication in httpd see the Apache manual, which is part of the Apache distribution or can be found at http://httpd.apache.org/.

See also

  • httpd
  • The scripts in support/SHA1 which come with the distribution.

Synopsis

htpasswd [ -c ] [ -m ] [ -D ] passwdfile username

htpasswd -b [ -c ] [ -m | -d | -p | -s ] [ -D ] passwdfile username password

htpasswd -n [ -m | -d | -s | -p ] username

htpasswd -nb [ -m | -d | -s | -p ] username password

Options

-b
Use batch mode; i.e., get the password from the command line rather than prompting for it. This option should be used with extreme care, since the password is clearly visible on the command line.
-c
Create the passwdfile. If passwdfile already exists, it is rewritten and truncated. This option cannot be combined with the -n option.
-n
Display the results on standard output rather than updating a file. This is useful for generating password records acceptable to Apache for inclusion in non-text data stores. This option changes the syntax of the command line, since the passwdfile argument (usually the first one) is omitted. It cannot be combined with the -c option.
-m
Use MD5 encryption for passwords. On Windows, Netware and TPF, this is the default.
-d
Use crypt() encryption for passwords. The default on all platforms but Windows, Netware and TPF. Though possibly supported by htpasswd on all platforms, it is not supported by the httpd server on Windows, Netware and TPF.
-s
Use SHA encryption for passwords. Facilitates migration from/to Netscape servers using the LDAP Directory Interchange Format (ldif).
-p
Use plaintext passwords. Though htpasswd will support creation on all platforms, the httpd daemon will only accept plain text passwords on Windows, Netware and TPF.
-D
Delete user. If the username exists in the specified htpasswd file, it will be deleted.
passwdfile
Name of the file to contain the user name and password. If -c is given, this file is created if it does not already exist, or rewritten and truncated if it does exist.
username
The username to create or update in passwdfile. If username does not exist in this file, an entry is added. If it does exist, the password is changed.
password
The plaintext password to be encrypted and stored in the file. Only used with the -b flag.

Exit Status

htpasswd returns a zero status ("true") if the username and password have been successfully added or updated in the passwdfile. htpasswd returns 1 if it encounters some problem accessing files, 2 if there was a syntax problem with the command line, 3 if the password was entered interactively and the verification entry didn't match, 4 if its operation was interrupted, 5 if a value is too long (username, filename, password, or final computed record), 6 if the username contains illegal characters (see the Restrictions section), and 7 if the file is not a valid password file.

Examples

htpasswd /usr/local/etc/apache/.htpasswd-users jsmith

Adds or modifies the password for user jsmith. The user is prompted for the password. If executed on a Windows system, the password will be encrypted using the modified Apache MD5 algorithm; otherwise, the system's crypt() routine will be used. If the file does not exist, htpasswd will do nothing except return an error.

htpasswd -c /home/doe/public_html/.htpasswd jane

Creates a new file and stores a record in it for user jane. The user is prompted for the password. If the file exists and cannot be read, or cannot be written, it is not altered and htpasswd will display a message and return an error status.

htpasswd -mb /usr/web/.htpasswd-all jones Pwd4Steve

Encrypts the password from the command line (Pwd4Steve) using the MD5 algorithm, and stores it in the specified file.

Security Considerations

Web password files such as those managed by htpasswd should not be within the Web server's URI space -- that is, they should not be fetchable with a browser.

The use of the -b option is discouraged, since when it is used the unencrypted password appears on the command line.

Restrictions

On the Windows and MPE platforms, passwords encrypted with htpasswd are limited to no more than 255 characters in length. Longer passwords will be truncated to 255 characters.

The MD5 algorithm used by htpasswd is specific to the Apache software; passwords encrypted using it will not be usable with other Web servers.

Usernames are limited to 255 bytes and may not include the character :.


logresolve - Resolve IP-addresses to hostnames in Apache log files - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

logresolve - Resolve IP-addresses to hostnames in Apache log files

logresolve is a post-processing program to resolve IP-addresses in Apache's access logfiles. To minimize impact on your nameserver, logresolve has its very own internal hash-table cache. This means that each IP number will only be looked up the first time it is found in the log file.

Takes an Apache log file on standard input. The IP addresses must be the first thing on each line and must be seperated from the remainder of the line by a space.

Synopsis

logresolve [ -s filename ] [ -c ] < access_log > access_log.new

Options

-s filename
Specifies a filename to record statistics.
-c
This causes logresolve to apply some DNS checks: after finding the hostname from the IP address, it looks up the IP addresses for the hostname and checks that one of these matches the original address.


rotatelogs - Piped logging program to rotate Apache logs - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

rotatelogs - Piped logging program to rotate Apache logs

rotatelogs is a simple program for use in conjunction with Apache's piped logfile feature. For example:

CustomLog "|bin/rotatelogs /var/logs/logfile 86400" common

This creates the files /var/logs/logfile.nnnn where nnnn is the system time at which the log nominally starts (this time will always be a multiple of the rotation time, so you can synchronize cron scripts with it). At the end of each rotation time (here after 24 hours) a new log is started.

CustomLog "|bin/rotatelogs /var/logs/logfile 5M" common

This configuration will rotate the logfile whenever it reaches a size of 5 megabytes.

Synopsis

rotatelogs logfile [ rotationtime [ offset ]] | [ filesizeM ]

Options

logfile
The path plus basename of the logfile. If logfile includes any '%' characters, it is treated as a format string for strftime(3). Otherwise, the suffix .nnnnnnnnnn is automatically added and is the time in seconds. Both formats compute the start time from the beginning of the current period.
rotationtime
The time between log file rotations in seconds.
offset
The number of minutes offset from UTC. If omitted, zero is assumed and UTC is used. For example, to use local time in the zone UTC -5 hours, specify a value of -300 for this argument.
filesizeM
The maximum file size in megabytes followed by the letter M to specify size rather than time. Use this parameter in place of both rotationtime and offset.

Portability

The following logfile format string substitutions should be supported by all strftime(3) implementations, see the strftime(3) man page for library-specific extensions.

%A | full weekday name (localized)
%a | 3-character weekday name (localized)
%B | full month name (localized)
%b | 3-character month name (localized)
%c | date and time (localized)
%d | 2-digit day of month
%H | 2-digit hour (24 hour clock)
%I | 2-digit hour (12 hour clock)
%j | 3-digit day of year
%M | 2-digit minute
%m | 2-digit month
%p | am/pm of 12 hour clock (localized)
%S | 2-digit second
%U | 2-digit week of year (Sunday first day of week)
%W | 2-digit week of year (Monday first day of week)
%w | 1-digit weekday (Sunday first day of week)
%X | time (localized)
%x | date (localized)
%Y | 4-digit year
%y | 2-digit year
%Z | time zone name
%% | literal `%'


suexec - Switch user before executing external programs - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

suexec - Switch user before executing external programs

suexec is used by the Apache HTTP Server to switch to another user before executing CGI programs. In order to achieve this, it must run as root. Since the HTTP daemon normally doesn't run as root, the suexec executable needs the setuid bit set and must be owned by root. It should never be writable for any other person than root.

For further information about the concepts and and the security model of suexec please refer to the suexec documentation (http://httpd.apache.org/docs-2.0/suexec.html).

Synopsis

suexec -V

Options

-V
If you are root, this option displays the compile options of suexec. For security reasons all configuration options are changeable only at compile time.


Other Programs - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Programs

Other Programs

The following programs are simple support programs included with the Apache HTTP Server which do not have their own manual pages. They are not installed automatically. You can find them after the configuration process in the support/ directory.

log_server_status

This perl script is designed to be run at a frequent interval by something like cron. It connects to the server and downloads the status information. It reformats the information to a single line and logs it to a file. Adjust the variables at the top of the script to specify the location of the resulting logfile.

split-logfile

This perl script will take a combined Web server access log file and break its contents into separate files. It assumes that the first field of each line is the virtual host identity (put there by "%v"), and that the logfiles should be named that + ".log" in the current directory.

The combined log file is read from stdin. Records read will be appended to any existing log files.


Apache Miscellaneous Documentation - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Apache Miscellaneous Documentation

Below is a list of additional documentation pages that apply to the Apache web server development project.

Warning

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

How to use XSSI and Negotiation for custom ErrorDocuments

Describes a solution which uses XSSI and negotiation to custom-tailor the Apache ErrorDocuments to taste, adding the advantage of returning internationalized versions of the error messages depending on the client's language preferences.

File Descriptor use in Apache

Describes how Apache uses file descriptors and talks about various limits imposed on the number of descriptors available by various operating systems.

FIN_WAIT_2

A description of the causes of Apache processes going into the FIN_WAIT_2 state, and what you can do about it.

Known Client Problems

A list of problems in HTTP clients which can be mitigated by Apache.

Performance Notes - Apache Tuning

Notes about how to (run-time and compile-time) configure Apache for highest performance. Notes explaining why Apache does some things, and why it doesn't do other things (which make it slower/faster).

Security Tips

Some "do"s - and "don't"s - for keeping your Apache web site secure.

URL Rewriting Guide

This document supplements the mod_rewrite reference documentation. It describes how one can use Apache's mod_rewrite to solve typical URL-based problems webmasters are usually confronted with in practice.

Apache Tutorials

A list of external resources which help to accomplish common tasks with the Apache HTTP server.

Relevant Standards

This document acts as a reference page for most of the relevant standards that Apache follows.


International Customized Server Error Messages - Apache HTTP Server

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

International Customized Server Error Messages

Warning:

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

This document describes an easy way to provide your Apache HTTP Server with a set of customized error messages which take advantage of Content Negotiation and mod_include to return error messages generated by the server in the client's native language.

Introduction

By using SSI, all ErrorDocument messages can share a homogenous and consistent style and layout, and maintenance work (changing images, changing links) is kept to a minimum because all layout information can be kept in a single file.

Error documents can be shared across different servers, or even hosts, because all varying information is inserted at the time the error document is returned on behalf of a failed request.

Content Negotiation then selects the appropriate language version of a particular error message text, honoring the language preferences passed in the client's request. (Users usually select their favorite languages in the preferences options menu of today's browsers). When an error document in the client's primary language version is unavailable, the secondary languages are tried or a default (fallback) version is used.

You have full flexibility in designing your error documents to your personal taste (or your company's conventions). For demonstration purposes, we present a simple generic error document scheme. For this hypothetic server, we assume that all error messages...

  • possibly are served by different virtual hosts (different host name, different IP address, or different port) on the server machine,
  • show a predefined company logo in the right top of the message (selectable by virtual host),
  • print the error title first, followed by an explanatory text and (depending on the error context) help on how to resolve the error,
  • have some kind of standardized background image,
  • display an apache logo and a feedback email address at the bottom of the error message.

An example of a "document not found" message for a german client might look like this:

[Needs graphics capability to display]

All links in the document as well as links to the server's administrator mail address, and even the name and port of the serving virtual host are inserted in the error document at "run-time", i.e., when the error actually occurs.

Creating an ErrorDocument directory

For this concept to work as easily as possible, we must take advantage of as much server support as we can get:

  1. By defining the MultiViews Options, we enable the language selection of the most appropriate language alternative (content negotiation).
  2. By setting the LanguagePriority directive we define a set of default fallback languages in the situation where the client's browser did not express any preference at all.
  3. By enabling mod_include (and disallowing execution of cgi scripts for security reasons), we allow the server to include building blocks of the error message, and to substitute the value of certain environment variables into the generated document (dynamic HTML) or even to conditionally include or omit parts of the text.
  4. The AddHandler and AddType directives are useful for automatically SSI-expanding all files with a .shtml suffix to text/html.
  5. By using the Alias directive, we keep the error document directory outside of the document tree because it can be regarded more as a server part than part of the document tree.
  6. The <Directory> block restricts these "special" settings to the error document directory and avoids an impact on any of the settings for the regular document tree.
  7. For each of the error codes to be handled (see RFC2068 for an exact description of each error code, or look at src/main/http_protocol.c if you wish to see apache's standard messages), an ErrorDocument in the aliased /errordocs directory is defined. Note that we only define the basename of the document here because the MultiViews option will select the best candidate based on the language suffixes and the client's preferences. Any error situation with an error code not handled by a custom document will be dealt with by the server in the standard way (i.e., a plain error message in english).
  8. Finally, the AllowOverride directive tells apache that it is not necessary to look for a .htaccess file in the /errordocs directory: a minor speed optimization.

The resulting httpd.conf configuration would then look similar to this:

Note

Note that you can define your own error messages using this method for only part of the document tree, e.g., a /~user/ subtree. In this case, the configuration could as well be put into the .htaccess file at the root of the subtree, and the <Directory> and </Directory> directives -but not the contained directives- must be omitted.

LanguagePriority en fr de
Alias /errordocs /usr/local/apache/errordocs

<Directory /usr/local/apache/errordocs>
AllowOverride none
Options MultiViews IncludesNoExec FollowSymLinks
AddType text/html .shtml
<FilesMatch "\.shtml[.$]">
SetOutputFilter INCLUDES
</FilesMatch>
</Directory>

# "400 Bad Request",
ErrorDocument 400 /errordocs/400
# "401 Authorization Required",
ErrorDocument 401 /errordocs/401
# "403 Forbidden",
ErrorDocument 403 /errordocs/403
# "404 Not Found",
ErrorDocument 404 /errordocs/404
# "500 Internal Server Error",
ErrorDocument 500 /errordocs/500

The directory for the error messages (here: /usr/local/apache/errordocs/) must then be created with the appropriate permissions (readable and executable by the server uid or gid, only writable for the administrator).

Naming the Individual Error Document files

By defining the MultiViews option, the server was told to automatically scan the directory for matching variants (looking at language and content type suffixes) when a requested document was not found. In the configuration, we defined the names for the error documents to be just their error number (without any suffix).

The names of the individual error documents are now determined like this (I'm using 403 as an example, think of it as a placeholder for any of the configured error documents):

  • No file errordocs/403 should exist. Otherwise, it would be found and served (with the DefaultType, usually text/plain), all negotiation would be bypassed.
  • For each language for which we have an internationalized version (note that this need not be the same set of languages for each error code - you can get by with a single language version until you actually have translated versions), a document errordocs/403.shtml.lang is created and filled with the error text in that language (see below).
  • One fallback document called errordocs/403.shtml is created, usually by creating a symlink to the default language variant (see below).

The Common Header and Footer Files

By putting as much layout information in two special "include files", the error documents can be reduced to a bare minimum.

One of these layout files defines the HTML document header and a configurable list of paths to the icons to be shown in the resulting error document. These paths are exported as a set of SSI environment variables and are later evaluated by the "footer" special file. The title of the current error (which is put into the TITLE tag and an H1 header) is simply passed in from the main error document in a variable called title.

By changing this file, the layout of all generated error messages can be changed in a second. (By exploiting the features of SSI, you can easily define different layouts based on the current virtual host, or even based on the client's domain name).

The second layout file describes the footer to be displayed at the bottom of every error message. In this example, it shows an apache logo, the current server time, the server version string and adds a mail reference to the site's webmaster.

For simplicity, the header file is simply called head.shtml because it contains server-parsed content but no language specific information. The footer file exists once for each language translation, plus a symlink for the default language.

for English, French and German versions (default english)

foot.shtml.en,
foot.shtml.fr,
foot.shtml.de,
foot.shtml symlink to
foot.shtml.en

Both files are included into the error document by using the directives <!--#include virtual="head" --> and <!--#include virtual="foot" --> respectively: the rest of the magic occurs in mod_negotiation and in mod_include.

See the listings below to see an actual HTML implementation of the discussed example.

Creating ErrorDocuments in Different Languages

After all this preparation work, little remains to be said about the actual documents. They all share a simple common structure:

<!--#set var="title" value="error description title" -->
<!--#include virtual="head" -->
explanatory error text
<!--#include virtual="foot" -->

In the listings section, you can see an example of a [400 Bad Request] error document. Documents as simple as that certainly cause no problems to translate or expand.

The Fallback Language

Do we need a special handling for languages other than those we have translations for? We did set the LanguagePriority, didn't we?!

Well, the LanguagePriority directive is for the case where the client does not express any language priority at all. But what happens in the situation where the client wants one of the languages we do not have, and none of those we do have?

Without doing anything, the Apache server will usually return a [406 no acceptable variant] error, listing the choices from which the client may select. But we're in an error message already, and important error information might get lost when the client had to choose a language representation first.

So, in this situation it appears to be easier to define a fallback language (by copying or linking, e.g., the english version to a language-less version). Because the negotiation algorithm prefers "more specialized" variants over "more generic" variants, these generic alternatives will only be chosen when the normal negotiation did not succeed.

A simple shell script to do it (execute within the errordocs/ dir):

for f in *.shtml.en
do
ln -s $f `basename $f .en`
done

Customizing Proxy Error Messages

As of Apache-1.3, it is possible to use the ErrorDocument mechanism for proxy error messages as well (previous versions always returned fixed predefined error messages).

Most proxy errors return an error code of [500 Internal Server Error]. To find out whether a particular error document was invoked on behalf of a proxy error or because of some other server error, and what the reason for the failure was, you can check the contents of the new ERROR_NOTES CGI environment variable: if invoked for a proxy error, this variable will contain the actual proxy error message text in HTML form.

The following excerpt demonstrates how to exploit the ERROR_NOTES variable within an error document:

<!--#if expr="$REDIRECT_ERROR_NOTES = ''" -->

<p>
The server encountered an unexpected condition
which prevented it from fulfilling the request.
</p>

<p>
<a href="mailto:<!--#echo var="SERVER_ADMIN" -->"
SUBJECT="Error message [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> for <!--#echo var="REQUEST_URI" -->">
Please forward this error screen to <!--#echo var="SERVER_NAME" -->'s
WebMaster</a>; it includes useful debugging information about
the Request which caused the error.

<pre><!--#printenv --></pre>
</p>

<!--#else -->
<!--#echo var="REDIRECT_ERROR_NOTES" -->
<!--#endif -->

HTML Listing of the Discussed Example

So, to summarize our example, here's the complete listing of the 400.shtml.en document. You will notice that it contains almost nothing but the error text (with conditional additions). Starting with this example, you will find it easy to add more error documents, or to translate the error documents to different languages.

<!--#set var="title" value="Bad Request"-->
<!--#include virtual="head" -->

<p>
Your browser sent a request that this server could not understand:
<blockquote>
<strong><!--#echo var="REQUEST_URI" --></strong>
 </blockquote>

The request could not be understood by the server due to malformed
syntax. The client should not repeat the request without
modifications.
</p>

<p>
<!--#if expr="$HTTP_REFERER != ''" -->
Please inform the owner of
<a href="<!--#echo var="HTTP_REFERER" -->">the referring page</a> about
the malformed link.

<!--#else -->
Please check your request for typing errors and retry.

<!--#endif -->
</p>

<!--#include virtual="foot" -->

Here is the complete head.shtml.en file (the funny line breaks avoid empty lines in the document after SSI processing). Note the configuration section at top. That's where you configure the images and logos as well as the apache documentation directory. Look how this file displays two different logos depending on the content of the virtual host name ($SERVER_NAME), and that an animated apache logo is shown if the browser appears to support it (the latter requires server configuration lines of the form

BrowserMatch "^Mozilla/[2-4]" anigif

for browser types which support animated GIFs).

<!--#if expr="$SERVER_NAME = /.*\.mycompany\.com/" -->
<!--#set var="IMG_CorpLogo" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif" -->
<!--#set var="ALT_CorpLogo" value="Powered by Linux!" -->
<!--#else -->
<!--#set var="IMG_CorpLogo" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/PrivLogo.gif" -->
<!--#set var="ALT_CorpLogo" value="Powered by Linux!" -->
<!--#endif-->

<!--#set var="IMG_BgImage" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/BgImage.gif" -->
<!--#set var="DOC_Apache" value="http://$SERVER_NAME:$SERVER_PORT/Apache/" -->

<!--#if expr="$anigif" -->
<!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_anim.gif" -->
<!--#else-->
<!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_pb.gif" -->
 <!--#endif-->

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>
[<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" -->
</title>
</head>

<body bgcolor="white" background="<!--#echo var="IMG_BgImage" -->">
<h1 align="center">
[<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" -->
<img src="<!--#echo var="IMG_CorpLogo" -->"
  alt="<!--#echo var="ALT_CorpLogo" -->" align="right">
</h1>

<hr /> <!-- ======================================================== -->
<div>

and this is the foot.shtml.en file:

</div>
<hr />

<div align="right">
<small>Local Server time: <!--#echo var="DATE_LOCAL" --></small>
</div>

<div align="center">
<a href="<!--#echo var="DOC_Apache" -->">
<img src="<!--#echo var="IMG_Apache" -->" border="0" align="bottom"
  alt="Powered by <!--#echo var="SERVER_SOFTWARE" -->"></a>
<br />
<small><!--#set var="var" value="Powered by $SERVER_SOFTWARE --
File last modified on $LAST_MODIFIED" -->
<!--#echo var="var" --></small>
</div>

<p>If the indicated error looks like a misconfiguration, please inform
<a href="mailto:<!--#echo var="SERVER_ADMIN" -->"
subject="Feedback about Error message [<!--#echo var="REDIRECT_STATUS" -->]
<!--#echo var="title" -->, req=<!--#echo var="REQUEST_URI" -->">
<!--#echo var="SERVER_NAME" -->'s WebMaster</a>.
</p>
</body>
</html>

If you have tips to contribute, send mail to martin@apache.org


Connections in the FIN_WAIT_2 state and Apache - Apache HTTP Server

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

Connections in the FIN_WAIT_2 state and Apache

Warning:

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

Starting with the Apache 1.2 betas, people are reporting many more connections in the FIN_WAIT_2 state (as reported by netstat) than they saw using older versions. When the server closes a TCP connection, it sends a packet with the FIN bit set to the client, which then responds with a packet with the ACK bit set. The client then sends a packet with the FIN bit set to the server, which responds with an ACK and the connection is closed. The state that the connection is in during the period between when the server gets the ACK from the client and the server gets the FIN from the client is known as FIN_WAIT_2. See the TCP RFC for the technical details of the state transitions.

The FIN_WAIT_2 state is somewhat unusual in that there is no timeout defined in the standard for it. This means that on many operating systems, a connection in the FIN_WAIT_2 state will stay around until the system is rebooted. If the system does not have a timeout and too many FIN_WAIT_2 connections build up, it can fill up the space allocated for storing information about the connections and crash the kernel. The connections in FIN_WAIT_2 do not tie up an httpd process.

Why Does It Happen?

There are numerous reasons for it happening, some of them may not yet be fully clear. What is known follows.

Buggy Clients and Persistent Connections

Several clients have a bug which pops up when dealing with persistent connections (aka keepalives). When the connection is idle and the server closes the connection (based on the KeepAliveTimeout), the client is programmed so that the client does not send back a FIN and ACK to the server. This means that the connection stays in the FIN_WAIT_2 state until one of the following happens:

  • The client opens a new connection to the same or a different site, which causes it to fully close the older connection on that socket.
  • The user exits the client, which on some (most?) clients causes the OS to fully shutdown the connection.
  • The FIN_WAIT_2 times out, on servers that have a timeout for this state.

If you are lucky, this means that the buggy client will fully close the connection and release the resources on your server. However, there are some cases where the socket is never fully closed, such as a dialup client disconnecting from their provider before closing the client. In addition, a client might sit idle for days without making another connection, and thus may hold its end of the socket open for days even though it has no further use for it. This is a bug in the browser or in its operating system's TCP implementation.

The clients on which this problem has been verified to exist:

  • Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE i386)
  • Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE i386)
  • Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m)
  • MSIE 3.01 on the Macintosh
  • MSIE 3.01 on Windows 95

This does not appear to be a problem on:

  • Mozilla/3.01 (Win95; I)

It is expected that many other clients have the same problem. What a client should do is periodically check its open socket(s) to see if they have been closed by the server, and close their side of the connection if the server has closed. This check need only occur once every few seconds, and may even be detected by a OS signal on some systems (e.g., Win95 and NT clients have this capability, but they seem to be ignoring it).

Apache cannot avoid these FIN_WAIT_2 states unless it disables persistent connections for the buggy clients, just like we recommend doing for Navigator 2.x clients due to other bugs. However, non-persistent connections increase the total number of connections needed per client and slow retrieval of an image-laden web page. Since non-persistent connections have their own resource consumptions and a short waiting period after each closure, a busy server may need persistence in order to best serve its clients.

As far as we know, the client-caused FIN_WAIT_2 problem is present for all servers that support persistent connections, including Apache 1.1.x and 1.2.

A necessary bit of code introduced in 1.2

While the above bug is a problem, it is not the whole problem. Some users have observed no FIN_WAIT_2 problems with Apache 1.1.x, but with 1.2b enough connections build up in the FIN_WAIT_2 state to crash their server. The most likely source for additional FIN_WAIT_2 states is a function called lingering_close() which was added between 1.1 and 1.2. This function is necessary for the proper handling of persistent connections and any request which includes content in the message body (e.g., PUTs and POSTs). What it does is read any data sent by the client for a certain time after the server closes the connection. The exact reasons for doing this are somewhat complicated, but involve what happens if the client is making a request at the same time the server sends a response and closes the connection. Without lingering, the client might be forced to reset its TCP input buffer before it has a chance to read the server's response, and thus understand why the connection has closed. See the appendix for more details.

The code in lingering_close() appears to cause problems for a number of factors, including the change in traffic patterns that it causes. The code has been thoroughly reviewed and we are not aware of any bugs in it. It is possible that there is some problem in the BSD TCP stack, aside from the lack of a timeout for the FIN_WAIT_2 state, exposed by the lingering_close code that causes the observed problems.

What Can I Do About it?

There are several possible workarounds to the problem, some of which work better than others.

Add a timeout for FIN_WAIT_2

The obvious workaround is to simply have a timeout for the FIN_WAIT_2 state. This is not specified by the RFC, and could be claimed to be a violation of the RFC, but it is widely recognized as being necessary. The following systems are known to have a timeout:

  • FreeBSD versions starting at 2.0 or possibly earlier.
  • NetBSD version 1.2(?)
  • OpenBSD all versions(?)
  • BSD/OS 2.1, with the K210-027 patch installed.
  • Solaris as of around version 2.2. The timeout can be tuned by using ndd to modify tcp_fin_wait_2_flush_interval, but the default should be appropriate for most servers and improper tuning can have negative impacts.
  • Linux 2.0.x and earlier(?)
  • HP-UX 10.x defaults to terminating connections in the FIN_WAIT_2 state after the normal keepalive timeouts. This does not refer to the persistent connection or HTTP keepalive timeouts, but the SO_LINGER socket option which is enabled by Apache. This parameter can be adjusted by using nettune to modify parameters such as tcp_keepstart and tcp_keepstop. In later revisions, there is an explicit timer for connections in FIN_WAIT_2 that can be modified; contact HP support for details.
  • SGI IRIX can be patched to support a timeout. For IRIX 5.3, 6.2, and 6.3, use patches 1654, 1703 and 1778 respectively. If you have trouble locating these patches, please contact your SGI support channel for help.
  • NCR's MP RAS Unix 2.xx and 3.xx both have FIN_WAIT_2 timeouts. In 2.xx it is non-tunable at 600 seconds, while in 3.xx it defaults to 600 seconds and is calculated based on the tunable "max keep alive probes" (default of 8) multiplied by the "keep alive interval" (default 75 seconds).
  • Sequent's ptx/TCP/IP for DYNIX/ptx has had a FIN_WAIT_2 timeout since around release 4.1 in mid-1994.

The following systems are known to not have a timeout:

  • SunOS 4.x does not and almost certainly never will have one because it as at the very end of its development cycle for Sun. If you have kernel source should be easy to patch.

There is a patch available for adding a timeout to the FIN_WAIT_2 state; it was originally intended for BSD/OS, but should be adaptable to most systems using BSD networking code. You need kernel source code to be able to use it.

Compile without using lingering_close()

It is possible to compile Apache 1.2 without using the lingering_close() function. This will result in that section of code being similar to that which was in 1.1. If you do this, be aware that it can cause problems with PUTs, POSTs and persistent connections, especially if the client uses pipelining. That said, it is no worse than on 1.1, and we understand that keeping your server running is quite important.

To compile without the lingering_close() function, add -DNO_LINGCLOSE to the end of the EXTRA_CFLAGS line in your Configuration file, rerun Configure and rebuild the server.

Use SO_LINGER as an alternative to lingering_close()

On most systems, there is an option called SO_LINGER that can be set with setsockopt(2). It does something very similar to lingering_close(), except that it is broken on many systems so that it causes far more problems than lingering_close. On some systems, it could possibly work better so it may be worth a try if you have no other alternatives.

To try it, add -DUSE_SO_LINGER -DNO_LINGCLOSE to the end of the EXTRA_CFLAGS line in your Configuration file, rerun Configure and rebuild the server.

NOTE

Attempting to use SO_LINGER and lingering_close() at the same time is very likely to do very bad things, so don't.

Increase the amount of memory used for storing connection state

BSD based networking code:
BSD stores network data, such as connection states, in something called an mbuf. When you get so many connections that the kernel does not have enough mbufs to put them all in, your kernel will likely crash. You can reduce the effects of the problem by increasing the number of mbufs that are available; this will not prevent the problem, it will just make the server go longer before crashing.

The exact way to increase them may depend on your OS; look for some reference to the number of "mbufs" or "mbuf clusters". On many systems, this can be done by adding the line NMBCLUSTERS="n", where n is the number of mbuf clusters you want to your kernel config file and rebuilding your kernel.

Disable KeepAlive

If you are unable to do any of the above then you should, as a last resort, disable KeepAlive. Edit your httpd.conf and change "KeepAlive On" to "KeepAlive Off".

Appendix

Below is a message from Roy Fielding, one of the authors of HTTP/1.1.

Why the lingering close functionality is necessary with HTTP

The need for a server to linger on a socket after a close is noted a couple times in the HTTP specs, but not explained. This explanation is based on discussions between myself, Henrik Frystyk, Robert S. Thau, Dave Raggett, and John C. Mallery in the hallways of MIT while I was at W3C.

If a server closes the input side of the connection while the client is sending data (or is planning to send data), then the server's TCP stack will signal an RST (reset) back to the client. Upon receipt of the RST, the client will flush its own incoming TCP buffer back to the un-ACKed packet indicated by the RST packet argument. If the server has sent a message, usually an error response, to the client just before the close, and the client receives the RST packet before its application code has read the error message from its incoming TCP buffer and before the server has received the ACK sent by the client upon receipt of that buffer, then the RST will flush the error message before the client application has a chance to see it. The result is that the client is left thinking that the connection failed for no apparent reason.

There are two conditions under which this is likely to occur:

  1. sending POST or PUT data without proper authorization
  2. sending multiple requests before each response (pipelining) and one of the middle requests resulting in an error or other break-the-connection result.

The solution in all cases is to send the response, close only the write half of the connection (what shutdown is supposed to do), and continue reading on the socket until it is either closed by the client (signifying it has finally read the response) or a timeout occurs. That is what the kernel is supposed to do if SO_LINGER is set. Unfortunately, SO_LINGER has no effect on some systems; on some other systems, it does not have its own timeout and thus the TCP memory segments just pile-up until the next reboot (planned or not).

Please note that simply removing the linger code will not solve the problem -- it only moves it to a different and much harder one to detect.


Known Problems in Clients - Apache HTTP Server

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

Known Problems in Clients

Warning:

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

Over time the Apache Group has discovered or been notified of problems with various clients which we have had to work around, or explain. This document describes these problems and the workarounds available. It's not arranged in any particular order. Some familiarity with the standards is assumed, but not necessary.

For brevity, Navigator will refer to Netscape's Navigator product (which in later versions was renamed "Communicator" and various other names), and MSIE will refer to Microsoft's Internet Explorer product. All trademarks and copyrights belong to their respective companies. We welcome input from the various client authors to correct inconsistencies in this paper, or to provide us with exact version numbers where things are broken/fixed.

For reference, RFC1945 defines HTTP/1.0, and RFC2068 defines HTTP/1.1. Apache as of version 1.2 is an HTTP/1.1 server (with an optional HTTP/1.0 proxy).

Various of these workarounds are triggered by environment variables. The admin typically controls which are set, and for which clients, by using mod_browser. Unless otherwise noted all of these workarounds exist in versions 1.2 and later.

Trailing CRLF on POSTs

This is a legacy issue. The CERN webserver required POST data to have an extra CRLF following it. Thus many clients send an extra CRLF that is not included in the Content-Length of the request. Apache works around this problem by eating any empty lines which appear before a request.

Broken KeepAlive

Various clients have had broken implementations of keepalive (persistent connections). In particular the Windows versions of Navigator 2.0 get very confused when the server times out an idle connection. The workaround is present in the default config files:

BrowserMatch Mozilla/2 nokeepalive

Note that this matches some earlier versions of MSIE, which began the practice of calling themselves Mozilla in their user-agent strings just like Navigator.

MSIE 4.0b2, which claims to support HTTP/1.1, does not properly support keepalive when it is used on 301 or 302 (redirect) responses. Unfortunately Apache's nokeepalive code prior to 1.2.2 would not work with HTTP/1.1 clients. You must apply this patch to version 1.2.1. Then add this to your config:

BrowserMatch "MSIE 4\.0b2;" nokeepalive

Incorrect interpretation of HTTP/1.1 in response

To quote from section 3.1 of RFC1945:

HTTP uses a "<MAJOR>.<MINOR>" numbering scheme to indicate versions of the protocol. The protocol versioning policy is intended to allow the sender to indicate the format of a message and its capacity for understanding further HTTP communication, rather than the features obtained via that communication.

Since Apache is an HTTP/1.1 server, it indicates so as part of its response. Many client authors mistakenly treat this part of the response as an indication of the protocol that the response is in, and then refuse to accept the response.

The first major indication of this problem was with AOL's proxy servers. When Apache 1.2 went into beta it was the first wide-spread HTTP/1.1 server. After some discussion, AOL fixed their proxies. In anticipation of similar problems, the force-response-1.0 environment variable was added to Apache. When present Apache will indicate "HTTP/1.0" in response to an HTTP/1.0 client, but will not in any other way change the response.

The pre-1.1 Java Development Kit (JDK) that is used in many clients (including Navigator 3.x and MSIE 3.x) exhibits this problem. As do some of the early pre-releases of the 1.1 JDK. We think it is fixed in the 1.1 JDK release. In any event the workaround:

BrowserMatch Java/1.0 force-response-1.0
BrowserMatch JDK/1.0 force-response-1.0

RealPlayer 4.0 from Progressive Networks also exhibits this problem. However they have fixed it in version 4.01 of the player, but version 4.01 uses the same User-Agent as version 4.0. The workaround is still:

BrowserMatch "RealPlayer 4.0" force-response-1.0

Requests use HTTP/1.1 but responses must be in HTTP/1.0

MSIE 4.0b2 has this problem. Its Java VM makes requests in HTTP/1.1 format but the responses must be in HTTP/1.0 format (in particular, it does not understand chunked responses). The workaround is to fool Apache into believing the request came in HTTP/1.0 format.

BrowserMatch "MSIE 4\.0b2;" downgrade-1.0 force-response-1.0

This workaround is available in 1.2.2, and in a patch against 1.2.1.

Boundary problems with header parsing

All versions of Navigator from 2.0 through 4.0b2 (and possibly later) have a problem if the trailing CRLF of the response header starts at offset 256, 257 or 258 of the response. A BrowserMatch for this would match on nearly every hit, so the workaround is enabled automatically on all responses. The workaround implemented detects when this condition would occur in a response and adds extra padding to the header to push the trailing CRLF past offset 258 of the response.

Multipart responses and Quoted Boundary Strings

On multipart responses some clients will not accept quotes (") around the boundary string. The MIME standard recommends that such quotes be used. But the clients were probably written based on one of the examples in RFC2068, which does not include quotes. Apache does not include quotes on its boundary strings to workaround this problem.

Byterange Requests

A byterange request is used when the client wishes to retrieve a portion of an object, not necessarily the entire object. There was a very old draft which included these byteranges in the URL. Old clients such as Navigator 2.0b1 and MSIE 3.0 for the MAC exhibit this behaviour, and it will appear in the servers' access logs as (failed) attempts to retrieve a URL with a trailing ";xxx-yyy". Apache does not attempt to implement this at all.

A subsequent draft of this standard defines a header Request-Range, and a response type multipart/x-byteranges. The HTTP/1.1 standard includes this draft with a few fixes, and it defines the header Range and type multipart/byteranges.

Navigator (versions 2 and 3) sends both Range and Request-Range headers (with the same value), but does not accept a multipart/byteranges response. The response must be multipart/x-byteranges. As a workaround, if Apache receives a Request-Range header it considers it "higher priority" than a Range header and in response uses multipart/x-byteranges.

The Adobe Acrobat Reader plugin makes extensive use of byteranges and prior to version 3.01 supports only the multipart/x-byterange response. Unfortunately there is no clue that it is the plugin making the request. If the plugin is used with Navigator, the above workaround works fine. But if the plugin is used with MSIE 3 (on Windows) the workaround won't work because MSIE 3 doesn't give the Range-Request clue that Navigator does. To workaround this, Apache special cases "MSIE 3" in the User-Agent and serves multipart/x-byteranges. Note that the necessity for this with MSIE 3 is actually due to the Acrobat plugin, not due to the browser.

Netscape Communicator appears to not issue the non-standard Request-Range header. When an Acrobat plugin prior to version 3.01 is used with it, it will not properly understand byteranges. The user must upgrade their Acrobat reader to 3.01.

Set-Cookie header is unmergeable

The HTTP specifications say that it is legal to merge headers with duplicate names into one (separated by commas). Some browsers that support Cookies don't like merged headers and prefer that each Set-Cookie header is sent separately. When parsing the headers returned by a CGI, Apache will explicitly avoid merging any Set-Cookie headers.

Expires headers and GIF89A animations

Navigator versions 2 through 4 will erroneously re-request GIF89A animations on each loop of the animation if the first response included an Expires header. This happens regardless of how far in the future the expiry time is set. There is no workaround supplied with Apache, however there are hacks for 1.2 and for 1.3.

POST without Content-Length

In certain situations Navigator 3.01 through 3.03 appear to incorrectly issue a POST without the request body. There is no known workaround. It has been fixed in Navigator 3.04, Netscapes provides some information. There's also some information about the actual problem.

JDK 1.2 betas lose parts of responses.

The http client in the JDK1.2beta2 and beta3 will throw away the first part of the response body when both the headers and the first part of the body are sent in the same network packet AND keep-alive's are being used. If either condition is not met then it works fine.

See also Bug-ID's 4124329 and 4125538 at the java developer connection.

If you are seeing this bug yourself, you can add the following BrowserMatch directive to work around it:

BrowserMatch "Java1\.2beta[23]" nokeepalive

We don't advocate this though since bending over backwards for beta software is usually not a good idea; ideally it gets fixed, new betas or a final release comes out, and no one uses the broken old software anymore. In theory.

Content-Type change is not noticed after reload

Navigator (all versions?) will cache the content-type for an object "forever". Using reload or shift-reload will not cause Navigator to notice a content-type change. The only work-around is for the user to flush their caches (memory and disk). By way of an example, some folks may be using an old mime.types file which does not map .htm to text/html, in this case Apache will default to sending text/plain. If the user requests the page and it is served as text/plain. After the admin fixes the server, the user will have to flush their caches before the object will be shown with the correct text/html type.

MSIE Cookie problem with expiry date in the year 2000

MSIE versions 3.00 and 3.02 (without the Y2K patch) do not handle cookie expiry dates in the year 2000 properly. Years after 2000 and before 2000 work fine. This is fixed in IE4.01 service pack 1, and in the Y2K patch for IE3.02. Users should avoid using expiry dates in the year 2000.

Lynx incorrectly asking for transparent content negotiation

The Lynx browser versions 2.7 and 2.8 send a "negotiate: trans" header in their requests, which is an indication the browser supports transparent content negotiation (TCN). However the browser does not support TCN. As of version 1.3.4, Apache supports TCN, and this causes problems with these versions of Lynx. As a workaround future versions of Apache will ignore this header when sent by the Lynx client.

MSIE 4.0 mishandles Vary response header

MSIE 4.0 does not handle a Vary header properly. The Vary header is generated by mod_rewrite in apache 1.3. The result is an error from MSIE saying it cannot download the requested file. There are more details in PR#4118.

A workaround is to add the following to your server's configuration files:

BrowserMatch "MSIE 4\.0" force-no-vary

(This workaround is only available with releases after 1.3.6 of the Apache Web server.)


Descriptors and Apache - Apache HTTP Server

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

Descriptors and Apache

Warning:

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

A descriptor, also commonly called a file handle is an object that a program uses to read or write an open file, or open network socket, or a variety of other devices. It is represented by an integer, and you may be familiar with stdin, stdout, and stderr which are descriptors 0, 1, and 2 respectively. Apache needs a descriptor for each log file, plus one for each network socket that it listens on, plus a handful of others. Libraries that Apache uses may also require descriptors. Normal programs don't open up many descriptors at all, and so there are some latent problems that you may experience should you start running Apache with many descriptors (i.e., with many virtual hosts).

The operating system enforces a limit on the number of descriptors that a program can have open at a time. There are typically three limits involved here. One is a kernel limitation, depending on your operating system you will either be able to tune the number of descriptors available to higher numbers (this is frequently called FD_SETSIZE). Or you may be stuck with a (relatively) low amount. The second limit is called the hard resource limit, and it is sometimes set by root in an obscure operating system file, but frequently is the same as the kernel limit. The third limit is called the soft resource limit. The soft limit is always less than or equal to the hard limit. For example, the hard limit may be 1024, but the soft limit only 64. Any user can raise their soft limit up to the hard limit. Root can raise the hard limit up to the system maximum limit. The soft limit is the actual limit that is used when enforcing the maximum number of files a process can have open.

To summarize:

#open files <= soft limit <= hard limit <= kernel limit

You control the hard and soft limits using the limit (csh) or ulimit (sh) directives. See the respective man pages for more information. For example you can probably use ulimit -n unlimited to raise your soft limit up to the hard limit. You should include this command in a shell script which starts your webserver.

Unfortunately, it's not always this simple. As mentioned above, you will probably run into some system limitations that will need to be worked around somehow. Work was done in version 1.2.1 to improve the situation somewhat. Here is a partial list of systems and workarounds (assuming you are using 1.2.1 or later).

BSDI 2.0

Under BSDI 2.0 you can build Apache to support more descriptors by adding -DFD_SETSIZE=nnn to EXTRA_CFLAGS (where nnn is the number of descriptors you wish to support, keep it less than the hard limit). But it will run into trouble if more than approximately 240 Listen directives are used. This may be cured by rebuilding your kernel with a higher FD_SETSIZE.

FreeBSD 2.2, BSDI 2.1+

Similar to the BSDI 2.0 case, you should define FD_SETSIZE and rebuild. But the extra Listen limitation doesn't exist.

Linux

By default Linux has a kernel maximum of 256 open descriptors per process. There are several patches available for the 2.0.x series which raise this to 1024 and beyond, and you can find them in the "unofficial patches" section of the Linux Information HQ. None of these patches are perfect, and an entirely different approach is likely to be taken during the 2.1.x development. Applying these patches will raise the FD_SETSIZE used to compile all programs, and unless you rebuild all your libraries you should avoid running any other program with a soft descriptor limit above 256. As of this writing the patches available for increasing the number of descriptors do not take this into account. On a dedicated webserver you probably won't run into trouble.

Solaris through 2.5.1

Solaris has a kernel hard limit of 1024 (may be lower in earlier versions). But it has a limitation that files using the stdio library cannot have a descriptor above 255. Apache uses the stdio library for the ErrorLog directive. When you have more than approximately 110 virtual hosts (with an error log and an access log each) you will need to build Apache with -DHIGH_SLACK_LINE=256 added to EXTRA_CFLAGS. You will be limited to approximately 240 error logs if you do this.

AIX

AIX version 3.2?? appears to have a hard limit of 128 descriptors. End of story. Version 4.1.5 has a hard limit of 2000.

SCO OpenServer

Edit the /etc/conf/cf.d/stune file or use /etc/conf/cf.d/configure choice 7 (User and Group configuration) and modify the NOFILES kernel parameter to a suitably higher value. SCO recommends a number between 60 and 11000, the default is 110. Relink and reboot, and the new number of descriptors will be available.

Compaq Tru64 UNIX/Digital UNIX/OSF

  1. Raise open_max_soft and open_max_hard to 4096 in the proc subsystem. Do a man on sysconfig, sysconfigdb, and sysconfigtab.
  2. Raise max-vnodes to a large number which is greater than the number of apache processes * 4096 (Setting it to 250,000 should be good for most people). Do a man on sysconfig, sysconfigdb, and sysconfigtab.
  3. If you are using Tru64 5.0, 5.0A, or 5.1, define NO_SLACK to work around a bug in the OS. CFLAGS="-DNO_SLACK" ./configure

Others

If you have details on another operating system, please submit it through our Bug Report Page.

In addition to the problems described above there are problems with many libraries that Apache uses. The most common example is the bind DNS resolver library that is used by pretty much every unix, which fails if it ends up with a descriptor above 256. We suspect there are other libraries that similar limitations. So the code as of 1.2.1 takes a defensive stance and tries to save descriptors less than 16 for use while processing each request. This is called the low slack line.

Note that this shouldn't waste descriptors. If you really are pushing the limits and Apache can't get a descriptor above 16 when it wants it, it will settle for one below 16.

In extreme situations you may want to lower the low slack line, but you shouldn't ever need to. For example, lowering it can increase the limits 240 described above under Solaris and BSDI 2.0. But you'll play a delicate balancing game with the descriptors needed to serve a request. Should you want to play this game, the compile time parameter is LOW_SLACK_LINE and there's a tiny bit of documentation in the header file httpd.h.

Finally, if you suspect that all this slack stuff is causing you problems, you can disable it. Add -DNO_SLACK to EXTRA_CFLAGS and rebuild. But please report it to our Bug Report Page so that we can investigate.


CGI 환경에서 PATH_INFO의 변화 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

CGI 환경에서 PATH_INFO의 변화

아파치 1.1.1과 그 이전 버전의 경우 CGI 환경에서 PATH_INFO를 만드는 방법이 직관적이지 않고 어떤 경우 서버를 죽이기도 했다. 아파치 1.2 이후 이 방법이 변했다. 기존의 어떤 CGI 프로그램들과 약간의 호환문제가 있지만 아파치 1.2의 행동은 아직도 CGI/1.1 규약을 벋어나지않으며, 쉽게 CGI 스크립트를 수정할 수 있다. (아래 참고)

문제점

아파치 1.1.1과 그 이전 버전은 URL 대신 파일명을 가지고 PATH_INFO와 SCRIPT_NAME 환경변수를 구현했다. 많은 경우 올바른 결과를 얻지만, 파일시스템 경로가 path 정보를 포함한다면 잘못된 결과가 나올 수 있다. 예를 들어, 설정파일에 다음과 같은 내용이 있다면:

Alias /cgi-ralph /usr/local/httpd/cgi-bin/user.cgi/ralph

이 경우 user.cgi는 CGI 스크립트이고, "/ralph"는 CGI에 넘겨지는 정보다. 이 경우 "/cgi-ralph/script/"로 요청이 들어오면 PATH는 "/ralph/script"가 되고, SCRIPT_NAME은 "/cgi-"가 된다. 후자는 분명히 잘못되었다. 심지어 어떤 경우 서버가 죽기도 한다.

해결책

아파치 1.2 이후에서는 URL에서 클라이언트가 조절가능한 부분을 판단하여 SCRIPT_NAME과 PATH_INFO를 설정한다. 위의 예에서 PATH_INFO는 "/script"가 되고, SCRIPT_NAME은 "/cgi-ralph"가 된다. 이는 합리적이며 서버에 문제를 일으키지 않는다. 또, 이전 버전과 달리 스크립트에서 "http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO"가 현재 스크립트를 가리키는 URL임을 보장할 수 있다.

그러나 불행히도 Alias 지시어의 "/ralph" 정보는 사라진다. 그러나 우리는 파일시스템을 사용하여 이런 정보를 넘겨주는 것이 바람직한 방법이 아니며, 이를 사용하는 스크립트는 작동할"만하지" 않다고 생각한다. 그러나 아파치 1.2b3 이후에는 이에 대한 해결책이 있다.

이전 서버와 호환성

아파치 이전 버전이나 다른 서버용으로 설계된 스크립트는 이전 PATH_INFO 변수가 제공했던 정보가 필요할 수 있다. 그래서 아파치 1.2 (1.2b3 이후)는 FILEPATH_INFO라는 변수를 더 설정한다. 이 환경변수는 아파치 1.1.1의 PATH_INFO 값을 가진다.

스크립트가 아파치 1.2와 이전 버전 모두에서 동작하게하려면, 먼저 FILEPATH_INFO가 있는지 검사하고 있다면 그것을 사용한다. 없다면 PATH_INFO를 사용한다. 예를 들어, Perl로는 다음과 같다:

$path_info = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'};

이렇게 하면 모든 아파치를 포함하여 CGI/1.1 규정을 따르는 모든 서버에서 스크립트가 동작할 수 있다.


모듈 목록 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

모듈 목록

다음은 아파치 배포본에 포함된 모든 모듈 목록이다. 모든 아파치 지시어 목록도 참고하라.

참고

  • 다중처리모듈 (MPM)
  • 지시어 빠른참고

핵심 기능과 다중처리 모듈

core
Core Apache HTTP Server features that are always available
mpm_common
A collection of directives that are implemented by more than one multi-processing module (MPM)
beos
BeOS에 최적화된 다중처리 모듈.
leader
표준 worker MPM의 실험적인 변형
mpm_netware
Multi-Processing Module implementing an exclusively threaded web server optimized for Novell NetWare
mpmt_os2
Hybrid multi-process, multi-threaded MPM for OS/2
perchild
Multi-Processing Module allowing for daemon processes serving requests to be assigned a variety of different userids
prefork
Implements a non-threaded, pre-forking web server
threadpool
Yet another experimental variant of the standard worker MPM
mpm_winnt
This Multi-Processing Module is optimized for Windows NT.
worker
Multi-Processing Module implementing a hybrid multi-threaded multi-process web server

다른 모듈

A | C | D | E | F | H | I | L | M | N | P | R | S | U | V

mod_access
Provides access control based on client hostname, IP address, or other characteristics of the client request.
mod_actions
이 모듈은 미디어종류나 요청메서드에 따라 CGI 스크립트를 실행한다.
mod_alias
Provides for mapping different parts of the host filesystem in the document tree and for URL redirection
mod_asis
HTTP 헤더를 포함한 파일을 보낸다
mod_auth
User authentication using text files
mod_auth_anon
Allows "anonymous" user access to authenticated areas
mod_auth_dbm
Provides for user authentication using DBM files
mod_auth_digest
User authentication using MD5 Digest Authentication.
mod_auth_ldap
Allows an LDAP directory to be used to store the database for HTTP Basic authentication.
mod_autoindex
자동으로 유닉스의 ls 명령어나 Win32의 dir 쉘명령어와 유사한 디렉토리 목록을 만든다
mod_cache
Content cache keyed to URIs.
mod_cern_meta
CERN 웹서버 메타파일 지원
mod_cgi
CGI 스크립트 실행
mod_cgid
외부 CGI 데몬을 사용하여 CGI 스크립트를 실행
mod_charset_lite
문자집합 변환을 지정
mod_dav
Distributed Authoring and Versioning (WebDAV) 기능
mod_dav_fs
mod_dav을 위한 파일시스템 제공자
mod_deflate
내용을 클라이언트로 보내기 전에 압축한다
mod_dir
"마지막 슬래쉬" 리다이렉션을 제공하고 디렉토리 index 파일을 서비스한다
mod_disk_cache
Content cache storage manager keyed to URIs
mod_echo
프로토콜 모듈을 설명하기위한 간단한 echo 서버
mod_env
CGI 스크립트나 SSI 페이지에 전달할 환경변수를 수정한다
mod_example
Illustrates the Apache module API
mod_expires
Generation of Expires HTTP headers according to user-specified criteria
mod_ext_filter
Pass the response body through an external program before delivery to the client
mod_file_cache
Caches a static list of files in memory
mod_headers
Customization of HTTP request and response headers
mod_imap
Server-side imagemap processing
mod_include
Server-parsed html documents (Server Side Includes)
mod_info
Provides a comprehensive overview of the server configuration
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
Logging of the requests made to the server
mod_logio
Logging of input and output bytes per request
mod_mem_cache
Content cache keyed to URIs
mod_mime
Associates the requested filename's extensions with the file's behavior (handlers and filters) and content (mime-type, language, character set and encoding)
mod_mime_magic
Determines the MIME type of a file by looking at a few bytes of its contents
mod_negotiation
Provides for content negotiation
mod_nw_ssl
Enable SSL encryption for NetWare
mod_proxy
HTTP/1.1 proxy/gateway server
mod_proxy_connect
mod_proxy extension for CONNECT request handling
mod_proxy_ftp
FTP support module for mod_proxy
mod_proxy_http
HTTP support module for mod_proxy
mod_rewrite
Provides a rule-based rewriting engine to rewrite requested URLs on the fly
mod_setenvif
Allows the setting of environment variables based on characteristics of the request
mod_so
Loading of executable code and modules into the server at start-up or restart time
mod_speling
Attempts to correct mistaken URLs that users might have entered by ignoring capitalization and by allowing up to one misspelling
mod_ssl
Strong cryptography using the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols
mod_status
Provides information on server activity and performance
mod_suexec
Allows CGI scripts to run as a specified user and Group
mod_unique_id
Provides an environment variable with a unique identifier for each request
mod_userdir
User-specific directories
mod_usertrack
Clickstream logging of user activity on a site
mod_vhost_alias
Provides for dynamically configured mass virtual hosting


지시어 목록 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

지시어 목록

다음은 표준 아파치 배포본에서 사용가능한 지시어 목록이다. 이들을 동일한 형식으로 설명하였고, 설명에 사용한 용어 사전도 있다.

각 지시어를 요약하여 설명한 지시어 빠른참조도 있다.

A | B | C | D | E | F | G | H | I | K | L | M | N | O | P | R | S | T | U | V | W | X

  • 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_Authoritative
  • Anonymous_LogEmail
  • Anonymous_MustGiveEmail
  • Anonymous_NoUserID
  • Anonymous_VerifyEmail
  • AssignUserID
  • AuthAuthoritative
  • AuthDBMAuthoritative
  • AuthDBMGroupFile
  • AuthDBMType
  • AuthDBMUserFile
  • AuthDigestAlgorithm
  • AuthDigestDomain
  • AuthDigestFile
  • AuthDigestGroupFile
  • AuthDigestNcCheck
  • AuthDigestNonceFormat
  • AuthDigestNonceLifetime
  • AuthDigestQop
  • AuthDigestShmemSize
  • AuthGroupFile
  • AuthLDAPAuthoritative
  • AuthLDAPBindDN
  • AuthLDAPBindPassword
  • AuthLDAPCharsetConfig
  • AuthLDAPCompareDNOnServer
  • AuthLDAPDereferenceAliases
  • AuthLDAPEnabled
  • AuthLDAPFrontPageHack
  • AuthLDAPGroupAttribute
  • AuthLDAPGroupAttributeIsDN
  • AuthLDAPRemoteUserIsDN
  • AuthLDAPUrl
  • AuthName
  • AuthType
  • AuthUserFile
  • BrowserMatch
  • BrowserMatchNoCase
  • BS2000Account
  • CacheDefaultExpire
  • CacheDirLength
  • CacheDirLevels
  • CacheDisable
  • CacheEnable
  • CacheExpiryCheck
  • CacheFile
  • CacheForceCompletion
  • CacheGcClean
  • CacheGcDaily
  • CacheGcInterval
  • CacheGcMemUsage
  • CacheGcUnused
  • CacheIgnoreCacheControl
  • CacheIgnoreNoLastMod
  • CacheLastModifiedFactor
  • CacheMaxExpire
  • CacheMaxFileSize
  • CacheMinFileSize
  • CacheNegotiatedDocs
  • CacheRoot
  • CacheSize
  • CacheTimeMargin
  • CGIMapExtension
  • CharsetDefault
  • CharsetOptions
  • CharsetSourceEnc
  • CheckSpelling
  • ChildPerUserID
  • ContentDigest
  • CookieDomain
  • CookieExpires
  • CookieLog
  • CookieName
  • CookieStyle
  • CookieTracking
  • CoreDumpDirectory
  • CustomLog
  • Dav
  • DavDepthInfinity
  • DavLockDB
  • DavMinTimeout
  • DefaultIcon
  • DefaultLanguage
  • DefaultType
  • DeflateBufferSize
  • DeflateCompressionLevel
  • DeflateFilterNote
  • DeflateMemLevel
  • DeflateWindowSize
  • Deny
  • <Directory>
  • DirectoryIndex
  • <DirectoryMatch>
  • DocumentRoot
  • EnableExceptionHook
  • EnableMMAP
  • EnableSendfile
  • ErrorDocument
  • ErrorLog
  • Example
  • ExpiresActive
  • ExpiresByType
  • ExpiresDefault
  • ExtendedStatus
  • ExtFilterDefine
  • ExtFilterOptions
  • FileETag
  • <Files>
  • <FilesMatch>
  • ForceLanguagePriority
  • ForceType
  • Group
  • Header
  • HeaderName
  • HostnameLookups
  • IdentityCheck
  • <IfDefine>
  • <IfModule>
  • ImapBase
  • ImapDefault
  • ImapMenu
  • Include
  • IndexIgnore
  • IndexOptions
  • IndexOrderDefault
  • ISAPIAppendLogToErrors
  • ISAPIAppendLogToQuery
  • ISAPICacheFile
  • ISAPIFakeAsync
  • ISAPILogNotSupported
  • ISAPIReadAheadBuffer
  • KeepAlive
  • KeepAliveTimeout
  • LanguagePriority
  • LDAPCacheEntries
  • LDAPCacheTTL
  • LDAPOpCacheEntries
  • LDAPOpCacheTTL
  • LDAPSharedCacheFile
  • LDAPSharedCacheSize
  • LDAPTrustedCA
  • LDAPTrustedCAType
  • <Limit>
  • <LimitExcept>
  • LimitInternalRecursion
  • LimitRequestBody
  • LimitRequestFields
  • LimitRequestFieldSize
  • LimitRequestLine
  • LimitXMLRequestBody
  • Listen
  • ListenBackLog
  • LoadFile
  • LoadModule
  • <Location>
  • <LocationMatch>
  • LockFile
  • LogFormat
  • LogLevel
  • MaxClients
  • MaxKeepAliveRequests
  • MaxMemFree
  • MaxRequestsPerChild
  • MaxRequestsPerThread
  • MaxSpareServers
  • MaxSpareThreads
  • MaxThreads
  • MaxThreadsPerChild
  • MCacheMaxObjectCount
  • MCacheMaxObjectSize
  • MCacheMaxStreamingBuffer
  • MCacheMinObjectSize
  • MCacheRemovalAlgorithm
  • MCacheSize
  • MetaDir
  • MetaFiles
  • MetaSuffix
  • MimeMagicFile
  • MinSpareServers
  • MinSpareThreads
  • MMapFile
  • ModMimeUsePathInfo
  • MultiviewsMatch
  • NameVirtualHost
  • NoProxy
  • NumServers
  • NWSSLTrustedCerts
  • Options
  • Order
  • PassEnv
  • PidFile
  • ProtocolEcho
  • <Proxy>
  • ProxyBadHeader
  • ProxyBlock
  • ProxyDomain
  • ProxyErrorOverride
  • ProxyIOBufferSize
  • <ProxyMatch>
  • ProxyMaxForwards
  • ProxyPass
  • ProxyPassReverse
  • ProxyPreserveHost
  • ProxyReceiveBufferSize
  • ProxyRemote
  • ProxyRemoteMatch
  • ProxyRequests
  • ProxyTimeout
  • ProxyVia
  • ReadmeName
  • Redirect
  • RedirectMatch
  • RedirectPermanent
  • RedirectTemp
  • RemoveCharset
  • RemoveEncoding
  • RemoveHandler
  • RemoveInputFilter
  • RemoveLanguage
  • RemoveOutputFilter
  • RemoveType
  • RequestHeader
  • Require
  • RewriteBase
  • RewriteCond
  • RewriteEngine
  • RewriteLock
  • RewriteLog
  • RewriteLogLevel
  • RewriteMap
  • RewriteOptions
  • RewriteRule
  • RLimitCPU
  • RLimitMEM
  • RLimitNPROC
  • Satisfy
  • ScoreBoardFile
  • Script
  • ScriptAlias
  • ScriptAliasMatch
  • ScriptInterpreterSource
  • ScriptLog
  • ScriptLogBuffer
  • ScriptLogLength
  • ScriptSock
  • SecureListen
  • SendBufferSize
  • ServerAdmin
  • ServerAlias
  • ServerLimit
  • ServerName
  • ServerPath
  • ServerRoot
  • ServerSignature
  • ServerTokens
  • SetEnv
  • SetEnvIf
  • SetEnvIfNoCase
  • SetHandler
  • SetInputFilter
  • SetOutputFilter
  • SSIEndTag
  • SSIErrorMsg
  • SSIStartTag
  • SSITimeFormat
  • SSIUndefinedEcho
  • SSLCACertificateFile
  • SSLCACertificatePath
  • SSLCARevocationFile
  • SSLCARevocationPath
  • SSLCertificateChainFile
  • SSLCertificateFile
  • SSLCertificateKeyFile
  • SSLCipherSuite
  • SSLEngine
  • SSLMutex
  • SSLOptions
  • SSLPassPhraseDialog
  • SSLProtocol
  • SSLProxyCACertificateFile
  • SSLProxyCACertificatePath
  • SSLProxyCARevocationFile
  • SSLProxyCARevocationPath
  • SSLProxyCipherSuite
  • SSLProxyEngine
  • SSLProxyMachineCertificateFile
  • SSLProxyMachineCertificatePath
  • SSLProxyProtocol
  • SSLProxyVerify
  • SSLProxyVerifyDepth
  • SSLRandomSeed
  • SSLRequire
  • SSLRequireSSL
  • SSLSessionCache
  • SSLSessionCacheTimeout
  • SSLVerifyClient
  • SSLVerifyDepth
  • StartServers
  • StartThreads
  • SuexecUserGroup
  • ThreadLimit
  • ThreadsPerChild
  • ThreadStackSize
  • TimeOut
  • TransferLog
  • TypesConfig
  • UnsetEnv
  • UseCanonicalName
  • User
  • UserDir
  • VirtualDocumentRoot
  • VirtualDocumentRootIP
  • <VirtualHost>
  • VirtualScriptAlias
  • VirtualScriptAliasIP
  • Win32DisableAcceptEx
  • XBitHack


Directive Quick Reference - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Directive Quick Reference

The directive quick reference shows the usage, default, status, and context of each Apache configuration directive. For more information about each of these, see the Directive Dictionary.

The first column gives the directive name and usage. The second columns shows the default value of the directive, if a default exists. If the default is too large to display, the first characters will be followed by "+".

The third and fourth columns list the contexts where the directive is allowed and the status of the directive according to the legend tables below.

A | B | C | D | E | F | G | H | I | K | L | M | N | O | P | R | S | T | U | V | W | X
s | server config
v | virtual host
d | directory
h | .htaccess

C | Core
M | MPM
B | Base
E | Extension
X | Experimental
AcceptMutex Default|method | Default | s | M
Method that Apache uses to serialize multiple children accepting requests on network sockets
AcceptPathInfo On|Off|Default | Default | svdh | C
Resources accept trailing pathname information
AccessFileName filename [filename] ... | .htaccess | sv | C
Name of the distributed configuration file
Action action-type cgi-script |  | svdh | B
Activates a CGI script for a particular handler or content-type
AddAlt string file [file] ... |  | svdh | B
Alternate text to display for a file, instead of an icon selected by filename
AddAltByEncoding string MIME-encoding [MIME-encoding] ... |  | svdh | B
Alternate text to display for a file instead of an icon selected by MIME-encoding
AddAltByType string MIME-type [MIME-type] ... |  | svdh | B
Alternate text to display for a file, instead of an icon selected by MIME content-type
AddCharset charset extension [extension] ... |  | svdh | B
Maps the given filename extensions to the specified content charset
AddDefaultCharset On|Off|charset | Off | svdh | C
Default character set to be added for a response without an explicit character set
AddDescription string file [file] ... |  | svdh | B
Description to display for a file
AddEncoding MIME-enc extension [extension] ... |  | svdh | B
Maps the given filename extensions to the specified encoding type
AddHandler handler-name extension [extension] ... |  | svdh | B
Maps the filename extensions to the specified handler
AddIcon icon name [name] ... |  | svdh | B
Icon to display for a file selected by name
AddIconByEncoding icon MIME-encoding [MIME-encoding] ... |  | svdh | B
Icon to display next to files selected by MIME content-encoding
AddIconByType icon MIME-type [MIME-type] ... |  | svdh | B
Icon to display next to files selected by MIME content-type
AddInputFilter filter[;filter...] extension [extension] ... |  | svdh | B
Maps filename extensions to the filters that will process client requests
AddLanguage MIME-lang extension [extension] ... |  | svdh | B
Maps the given filename extension to the specified content language
AddModuleInfo module-name string |  | sv | E
Adds additional information to the module information displayed by the server-info handler
AddOutputFilter filter[;filter...] extension [extension] ... |  | svdh | B
Maps filename extensions to the filters that will process responses from the server
AddOutputFilterByType filter[;filter...] MIME-type [MIME-type] ... |  | svdh | C
assigns an output filter to a particular MIME-type
AddType MIME-type extension [extension] ... |  | svdh | B
Maps the given filename extensions onto the specified content type
Alias URL-path file-path|directory-path |  | sv | B
Maps URLs to filesystem locations
AliasMatch regex file-path|directory-path |  | sv | B
Maps URLs to filesystem locations using regular expressions
Allow from all|host|env=env-variable [host|env=env-variable] ... |  | dh | B
Controls which hosts can access an area of the server
AllowCONNECT port [port] ... | 443 563 | sv | E
Ports that are allowed to CONNECT through the proxy
AllowEncodedSlashes On|Off | Off | sv | C
Determines whether encoded path separators in URLs are allowed to be passed through
AllowOverride All|None|directive-type [directive-type] ... | All | d | C
Types of directives that are allowed in .htaccess files
Anonymous user [user] ... |  | dh | E
Specifies userIDs that are allowed access without password verification
Anonymous_Authoritative On|Off | Off | dh | E
Configures if authorization will fall-through to other methods
Anonymous_LogEmail On|Off | On | dh | E
Sets whether the password entered will be logged in the error log
Anonymous_MustGiveEmail On|Off | On | dh | E
Specifies whether blank passwords are allowed
Anonymous_NoUserID On|Off | Off | dh | E
Sets whether the userID field may be empty
Anonymous_VerifyEmail On|Off | Off | dh | E
Sets whether to check the password field for a correctly formatted email address
AssignUserID user-id group-id |  | v | M
Tie a virtual host to a user and group ID
AuthAuthoritative On|Off | On | dh | B
Sets whether authorization and authentication are passed to lower level modules
AuthDBMAuthoritative On|Off | On | dh | E
Sets whether authentication and authorization will be passwed on to lower level modules
AuthDBMGroupFile file-path |  | dh | E
Sets the name of the database file containing the list of user groups for authentication
AuthDBMType default|SDBM|GDBM|NDBM|DB | default | dh | E
Sets the type of database file that is used to store passwords
AuthDBMUserFile file-path |  | dh | E
Sets thename of a database file containing the list of users and passwords for authentication
AuthDigestAlgorithm MD5|MD5-sess | MD5 | dh | X
Selects the algorithm used to calculate the challenge and response hases in digest authentication
AuthDigestDomain URI [URI] ... |  | dh | X
URIs that are in the same protection space for digest authentication
AuthDigestFile file-path |  | dh | X
Location of the text file containing the list of users and encoded passwords for digest authentication
AuthDigestGroupFile file-path |  | dh | X
Name of the text file containing the list of groups for digest authentication
AuthDigestNcCheck On|Off | Off | s | X
Enables or disables checking of the nonce-count sent by the server
AuthDigestNonceFormat format |  | dh | X
Determines how the nonce is generated
AuthDigestNonceLifetime seconds | 300 | dh | X
How long the server nonce is valid
AuthDigestQop none|auth|auth-int [auth|auth-int] | auth | dh | X
Determines the quality-of-protection to use in digest authentication
AuthDigestShmemSize size | 1000 | s | X
The amount of shared memory to allocate for keeping track of clients
AuthGroupFile file-path |  | dh | B
Sets the name of a text file containing the list of user groups for authentication
AuthLDAPAuthoritative on|off | on | dh | X
Prevent other authentication modules from authenticating the user if this one fails
AuthLDAPBindDN distinguished-name |  | dh | X
Optional DN to use in binding to the LDAP server
AuthLDAPBindPassword password |  | dh | X
Password used in conjuction with the bind DN
AuthLDAPCharsetConfig file-path |  | s | X
Language to charset conversion configuration file
AuthLDAPCompareDNOnServer on|off | on | dh | X
Use the LDAP server to compare the DNs
AuthLDAPDereferenceAliases never|searching|finding|always | Always | dh | X
When will the module de-reference aliases
AuthLDAPEnabled on|off | on | dh | X
Turn on or off LDAP authentication
AuthLDAPFrontPageHack on|off | off | dh | X
Allow LDAP authentication to work with MS FrontPage
AuthLDAPGroupAttribute attribute |  | dh | X
LDAP attributes used to check for group membership
AuthLDAPGroupAttributeIsDN on|off | on | dh | X
Use the DN of the client username when checking for group membership
AuthLDAPRemoteUserIsDN on|off | off | dh | X
Use the DN of the client username to set the REMOTE_USER environment variable
AuthLDAPUrl url |  | dh | X
URL specifying the LDAP search parameters
AuthName auth-domain |  | dh | C
Authorization realm for use in HTTP authentication
AuthType Basic|Digest |  | dh | C
Type of user authentication
AuthUserFile file-path |  | dh | B
Sets the name of a text file containing the list of users and passwords for authentication
BrowserMatch regex [!]env-variable[=value] [[!]env-variable[=value]] ... |  | svdh | B
Sets environment variables conditional on HTTP User-Agent
BrowserMatchNoCase regex [!]env-variable[=value] [[!]env-variable[=value]] ... |  | svdh | B
Sets environment variables conditional on User-Agent without respect to case
BS2000Account account |  | s | M
Define the non-privileged account on BS2000 machines
CacheDefaultExpire seconds | 3600 (one hour) | sv | X
The default duration to cache a document when no expiry date is specified.
CacheDirLength length | 2 | sv | X
The number of characters in subdirectory names
CacheDirLevels levels | 3 | sv | X
The number of levels of subdirectories in the cache.
CacheDisable url-string |  | sv | X
Disable caching of specified URLs
CacheEnable cache_type url-string |  | sv | X
Enable caching of specified URLs using a specified storage manager
CacheExpiryCheck On|Off | On | sv | X
Indicates if the cache observes Expires dates when seeking files
CacheFile file-path [file-path] ... |  | s | X
Cache a list of file handles at startup time
CacheForceCompletion Percentage | 60 | sv | X
Percentage of document served, after which the server will complete caching the file even if the request is cancelled.
CacheGcClean hours url-string | ? | sv | X
The time to retain unchanged cached files that match a URL
CacheGcDaily time | ? | sv | X
The recurring time each day for garbage collection to be run. (24 hour clock)
CacheGcInterval hours |  | sv | X
The interval between garbage collection attempts.
CacheGcMemUsage KBytes | ? | sv | X
The maximum kilobytes of memory used for garbage collection
CacheGcUnused hours url-string | ? | sv | X
The time to retain unreferenced cached files that match a URL.
CacheIgnoreCacheControl On|Off | Off | sv | X
Ignore the fact that the client requested the content not be cached.
CacheIgnoreNoLastMod On|Off | Off | sv | X
Ignore the fact that a response has no Last Modified header.
CacheLastModifiedFactor float | 0.1 | sv | X
The factor used to compute an expiry date based on the LastModified date.
CacheMaxExpire seconds | 86400 (one day) | sv | X
The maximum time in seconds to cache a document
CacheMaxFileSize bytes | 1000000 | sv | X
The maximum size (in bytes) of a document to be placed in the cache
CacheMinFileSize bytes | 1 | sv | X
The minimum size (in bytes) of a document to be placed in the cache
CacheNegotiatedDocs On|Off | Off | sv | B
Allows content-negotiated documents to be cached by proxy servers
CacheRoot directory |  | sv | X
The directory root under which cache files are stored
CacheSize KBytes | 1000000 | sv | X
The maximum amount of disk space that will be used by the cache in KBytes
CacheTimeMargin ? | ? | sv | X
The minimum time margin to cache a document
CGIMapExtension cgi-path .extension |  | dh | C
Technique for locating the interpreter for CGI scripts
CharsetDefault charset |  | svdh | X
Charset to translate into
CharsetOptions option [option] ... | DebugLevel=0 NoImpl + | svdh | X
Configures charset translation behavior
CharsetSourceEnc charset |  | svdh | X
Source charset of files
CheckSpelling on|off | Off | svdh | E
Enables the spelling module
ChildPerUserID user-id group-id num-children |  | s | M
Specify user ID and group ID for a number of child processes
ContentDigest On|Off | Off | svdh | C
Enables the generation of Content-MD5 HTTP Response headers
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
Sets filename for the logging of cookies
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
Directory where Apache attempts to switch before dumping core
CustomLog file|pipe format|nickname [env=[!]environment-variable] |  | sv | B
Sets filename and format of log file
Dav On|Off|provider-name | Off | d | E
Enable WebDAV HTTP methods
DavDepthInfinity on|off | off | svd | E
Allow PROPFIND, Depth: Infinity requests
DavLockDB file-path |  | sv | E
Location of the DAV lock database
DavMinTimeout seconds | 0 | svd | E
Minimum amount of time the server holds a lock on a DAV resource
DefaultIcon url-path |  | svdh | B
Icon to display for files when no specific icon is configured
DefaultLanguage MIME-lang |  | svdh | B
Sets all files in the given scope to the specified language
DefaultType MIME-type | text/plain | svdh | C
MIME content-type that will be sent if the server cannot determine a type in any other way
DeflateBufferSize value | 8096 | sv | E
Fragment size to be compressed at one time by zlib
DeflateCompressionLevel value |  | sv | E
How much compression do we apply to the output
DeflateFilterNote [type] notename |  | sv | E
Places the compression ratio in a note for logging
DeflateMemLevel value | 9 | sv | E
How much memory should be used by zlib for compression
DeflateWindowSize value | 15 | sv | E
Zlib compression window size
Deny from all|host|env=env-variable [host|env=env-variable] ... |  | dh | B
Controls which hosts are denied access to the server
<Directory directory-path> ... </Directory> |  | sv | C
Enclose a group of directives that apply only to the named file-system directory and sub-directories
DirectoryIndex local-url [local-url] ... | index.html | svdh | B
List of resources to look for when the client requests a directory
<DirectoryMatch regex> ... </DirectoryMatch> |  | sv | C
Enclose directives that apply to file-system directories matching a regular expression and their subdirectories
DocumentRoot directory-path | /usr/local/apache/h + | sv | C
Directory that forms the main document tree visible from the web
EnableExceptionHook On|Off | Off | s | M
Enables a hook that runs exception handlers after a crash
EnableMMAP On|Off | On | svdh | C
Use memory-mapping to read files during delivery
EnableSendfile On|Off | On | svdh | C
Use the kernel sendfile support to deliver files to the client
ErrorDocument error-code document |  | svdh | C
What the server will return to the client in case of an error
ErrorLog file-path|syslog[:facility] | logs/error_log (Uni + | sv | C
Location where the server will log errors
Example |  | svdh | X
Demonstration directive to illustrate the Apache module API
ExpiresActive On|Off |  | svdh | E
Enables generation of Expires headers
ExpiresByType MIME-type <code>seconds |  | svdh | E
Value of the Expires header configured by MIME type
ExpiresDefault <code>seconds |  | svdh | E
Default algorithm for calculating expiration time
ExtendedStatus On|Off | Off | s | B
Keep track of extended status information for each request
ExtFilterDefine filtername parameters |  | s | E
Define an external filter
ExtFilterOptions option [option] ... | DebugLevel=0 NoLogS + | d | E
Configure mod_ext_filter options
FileETag component ... | INode MTime Size | svdh | C
File attributes used to create the ETag HTTP response header
<Files filename> ... </Files> |  | svdh | C
Contains directives that apply to matched filenames
<FilesMatch regex> ... </FilesMatch> |  | svdh | C
Contains directives that apply to regular-expression matched filenames
ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback] | Prefer | svdh | B
Action to take if a single acceptable document is not found
ForceType MIME-type|None |  | dh | C
Forces all matching files to be served with the specified MIME content-type
Group unix-group | #-1 | s | M
Group under which the server will answer requests
Header set|append|add|unset|echo header [value [env=[!]variable]] |  | svdh | E
Configure HTTP response headers
HeaderName filename |  | svdh | B
Name of the file that will be inserted at the top of the index listing
HostnameLookups On|Off|Double | Off | svd | C
Enables DNS lookups on client IP addresses
IdentityCheck On|Off | Off | svd | C
Enables logging of the RFC1413 identity of the remote user
<IfDefine [!]parameter-name> ... </IfDefine> |  | svdh | C
Encloses directives that will be processed only if a test is true at startup
<IfModule [!]module-name> ... </IfModule> |  | svdh | C
Encloses directives that are processed conditional on the presence or absence of a specific module
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
Includes other configuration files from within the server configuration files
IndexIgnore file [file] ... |  | svdh | B
Adds to the list of files to hide when listing a directory
IndexOptions [+|-]option [[+|-]option] ... |  | svdh | B
Various configuration settings for directory indexing
IndexOrderDefault Ascending|Descending Name|Date|Size|Description | Ascending Name | svdh | B
Sets the default ordering of the directory index
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
Enables HTTP persistent connections
KeepAliveTimeout seconds | 15 | sv | C
Amount of time the server will wait for subsequent requests on a persistent connection
LanguagePriority MIME-lang [MIME-lang] ... |  | svdh | B
The precendence of language variants for cases where the client does not express a preference
LDAPCacheEntries number | 1024 | s | X
Maximum number of entries in the primary LDAP cache
LDAPCacheTTL seconds | 600 | s | X
Time that cached items remain valid
LDAPOpCacheEntries number | 1024 | s | X
Number of entries used to cache LDAP compare operations
LDAPOpCacheTTL seconds | 600 | s | X
Time that entries in the operation cache remain valid
LDAPSharedCacheFile directory-path/filename |  | s | X
Sets the shared memory chache file
LDAPSharedCacheSize bytes | 102400 | s | X
Size in bytes of the shared-memory cache
LDAPTrustedCA directory-path/filename |  | s | X
Sets the file containing the trusted Certificate Authority certificate or database
LDAPTrustedCAType type |  | s | X
Specifies the type of the Certificate Authority file
<Limit method [method] ... > ... </Limit> |  | svdh | C
Restrict enclosed access controls to only certain HTTP methods
<LimitExcept method [method] ... > ... </LimitExcept> |  | svdh | C
Restrict access controls to all HTTP methods except the named ones
LimitInternalRecursion number [number] | 10 | sv | C
Determine maximum number of internal redirects and nested subrequests
LimitRequestBody bytes | 0 | svdh | C
Restricts the total size of the HTTP request body sent from the client
LimitRequestFields number | 100 | s | C
Limits the number of HTTP request header fields that will be accepted from the client
LimitRequestFieldsize bytes |  | s | C
Limits the size of the HTTP request header allowed from the client
LimitRequestLine bytes | 8190 | s | C
Limit the size of the HTTP request line that will be accepted from the client
LimitXMLRequestBody bytes | 1000000 | svdh | C
Limits the size of an XML-based request body
Listen [IP-address:]portnumber |  | s | M
IP addresses and ports that the server listens to
ListenBacklog backlog |  | s | M
Maximum length of the queue of pending connections
LoadFile filename [filename] ... |  | s | E
Link in the named object file or library
LoadModule module filename |  | s | E
Links in the object file or library, and adds to the list of active modules
<Location URL-path|URL> ... </Location> |  | sv | C
Applies the enclosed directives only to matching URLs
<LocationMatch regex> ... </LocationMatch> |  | sv | C
Applies the enclosed directives only to regular-expression matching URLs
LockFile filename | logs/accept.lock | s | M
Location of the accept serialization lock file
LogFormat format|nickname [nickname] | "%h %l %u %t \"%r\" + | sv | B
Describes a format for use in a log file
LogLevel level | warn | sv | C
Controls the verbosity of the ErrorLog
MaxClients number |  | s | M
Maximum number of child processes that will be created to serve requests
MaxKeepAliveRequests number | 100 | sv | C
Number of requests allowed on a persistent connection
MaxMemFree KBytes | 0 | s | M
Maximum amount of memory that the main allocator is allowed to hold without calling free()
MaxRequestsPerChild number | 10000 | s | M
Limit on the number of requests that an individual child server will handle during its life
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
Maximum number of idle child server processes
MaxSpareThreads number |  | s | M
Maximum number of idle threads
MaxThreads number | 2048 | s | M
Set the maximum number of worker threads
MaxThreadsPerChild number | 64 | s | M
Maximum number of threads per child process
MCacheMaxObjectCount value | 1009 | s | X
The maximum number of objects allowed to be placed in the cache
MCacheMaxObjectSize bytes | 10000 | s | X
The maximum size (in bytes) of a document allowed in the cache
MCacheMaxStreamingBuffer size_in_bytes | the smaller of 1000 + | s | X
Maximum amount of a streamed response to buffer in memory before declaring the response uncacheable
MCacheMinObjectSize bytes | 0 | s | X
The minimum size (in bytes) of a document to be allowed in the cache
MCacheRemovalAlgorithm LRU|GDSF | GDSF | s | X
The algorithm used to select documents for removal from the cache
MCacheSize KBytes | 100 | s | X
The maximum amount of memory used by the cache in KBytes
MetaDir directory | .web | svdh | E
Name of the directory to find CERN-style meta information files
MetaFiles on|off | off | svdh | E
Activates CERN meta-file processing
MetaSuffix suffix | .meta | svdh | E
File name suffix for the file containg CERN-style meta information
MimeMagicFile file-path |  | sv | E
Enable MIME-type determination based on file contents using the specified magic file
MinSpareServers number | 5 | s | M
Minimum number of idle child server processes
MinSpareThreads number |  | s | M
Minimum number of idle threads available to handle request spikes
MMapFile file-path [file-path] ... |  | s | X
Map a list of files into memory at startup time
ModMimeUsePathInfo On|Off | Off | d | B
Tells mod_mime to treat path_info components as part of the filename
MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers [Handlers|Filters] | NegotiatedOnly | svdh | B
The types of files that will be included when searching for a matching file with MultiViews
NameVirtualHost addr[:port] |  | s | C
Designates an IP address for name-virtual hosting
NoProxy host [host] ... |  | sv | E
Hosts, domains, or networks that will be connected to directly
NumServers number | 2 | s | M
Total number of children alive at the same time
NWSSLTrustedCerts filename [filename] ... |  | s | B
List of additional client certificates
Options [+|-]option [[+|-]option] ... | All | svdh | C
Configures what features are available in a particular directory
Order ordering | Deny,Allow | dh | B
Controls the default access state and the order in which Allow and Deny are evaluated.
PassEnv env-variable [env-variable] ... |  | svdh | B
Passes environment variables from the shell
PidFile filename | logs/httpd.pid | s | M
File where the server records the process ID of the daemon
ProtocolEcho On|Off |  | sv | X
Turn the echo server on or off
<Proxy wildcard-url> ...</Proxy> |  | sv | E
Container for directives applied to proxied resources
ProxyBadHeader IsError|Ignore|StartBody | IsError | sv | E
Determines how to handle bad header lines in a response
ProxyBlock *|word|host|domain [word|host|domain] ... |  | sv | E
Words, hosts, or domains that are banned from being proxied
ProxyDomain Domain |  | sv | E
Default domain name for proxied requests
ProxyErrorOverride On|Off | Off | sv | E
Override error pages for proxied content
ProxyIOBufferSize bytes | 8192 | sv | E
Determine size of internal data throughput buffer
<ProxyMatch regex> ...</ProxyMatch> |  | sv | E
Container for directives applied to regular-expression-matched proxied resources
ProxyMaxForwards number | 10 | sv | E
Maximium number of proxies that a request can be forwarded through
ProxyPass [path] !|url |  | svd | E
Maps remote servers into the local server URL-space
ProxyPassReverse [path] url |  | svd | E
Adjusts the URL in HTTP response headers sent from a reverse proxied server
ProxyPreserveHost On|Off | Off | sv | E
Use incoming Host HTTP request header for proxy request
ProxyReceiveBufferSize bytes | 0 | sv | E
Network buffer size for proxied HTTP and FTP connections
ProxyRemote match remote-server |  | sv | E
Remote proxy used to handle certain requests
ProxyRemoteMatch regex remote-server |  | sv | E
Remote proxy used to handle requests matched by regular expressions
ProxyRequests On|Off | Off | sv | E
Enables forward (standard) proxy requests
ProxyTimeout seconds | 300 | sv | E
Network timeout for proxied requests
ProxyVia On|Off|Full|Block | Off | sv | E
Information provided in the Via HTTP response header for proxied requests
ReadmeName filename |  | svdh | B
Name of the file that will be inserted at the end of the index listing
Redirect [status] URL-path URL |  | svdh | B
Sends an external redirect asking the client to fetch a different URL
RedirectMatch [status] regex URL |  | svdh | B
Sends an external redirect based on a regular expression match of the current URL
RedirectPermanent URL-path URL |  | svdh | B
Sends an external permanent redirect asking the client to fetch a different URL
RedirectTemp URL-path URL |  | svdh | B
Sends an external temporary redirect asking the client to fetch a different URL
RemoveCharset extension [extension] ... |  | vdh | B
Removes any character set associations for a set of file extensions
RemoveEncoding extension [extension] ... |  | vdh | B
Removes any content encoding associations for a set of file extensions
RemoveHandler extension [extension] ... |  | vdh | B
Removes any handler associations for a set of file extensions
RemoveInputFilter extension [extension] ... |  | vdh | B
Removes any input filter associations for a set of file extensions
RemoveLanguage extension [extension] ... |  | vdh | B
Removes any language associations for a set of file extensions
RemoveOutputFilter extension [extension] ... |  | vdh | B
Removes any output filter associations for a set of file extensions
RemoveType extension [extension] ... |  | vdh | B
Removes any content type associations for a set of file extensions
RequestHeader set|append|add|unset header [value] |  | svdh | E
Configure HTTP request headers
Require entity-name [entity-name] ... |  | dh | C
Selects which authenticated users can access a resource
RewriteBase URL-path |  | dh | E
Sets the base URL for per-directory rewrites
RewriteCond TestString CondPattern |  | svdh | E
Defines a condition under which rewriting will take place
RewriteEngine on|off | off | svdh | E
Enables or disables runtime rewriting engine
RewriteLock file-path |  | s | E
Sets the name of the lock file used for RewriteMap synchronization
RewriteLog file-path |  | sv | E
Sets the name of the file used for logging rewrite engine processing
RewriteLogLevel Level | 0 | sv | E
Sets the verbosity of the log file used by the rewrite engine
RewriteMap MapName MapType:MapSource |  | sv | E
Defines a mapping function for key-lookup
RewriteOptions Options | MaxRedirects=10 | svdh | E
Sets some special options for the rewrite engine
RewriteRule Pattern Substitution |  | svdh | E
Defines rules for the rewriting engine
RLimitCPU seconds|max [seconds|max] |  | svdh | C
Limits the CPU consumption of processes launched by Apache children
RLimitMEM bytes|max [bytes|max] |  | svdh | C
Limits the memory consumption of processes launched by Apache children
RLimitNPROC number|max [number|max] |  | svdh | C
Limits the number of processes that can be launched by processes launched by Apache children
Satisfy Any|All | All | dh | C
Interaction between host-level access control and user authentication
ScoreBoardFile file-path | logs/apache_status | s | M
Location of the file used to store coordination data for the child processes
Script method cgi-script |  | svd | B
Activates a CGI script for a particular request method.
ScriptAlias URL-path file-path|directory-path |  | sv | B
Maps a URL to a filesystem location and designates the target as a CGI script
ScriptAliasMatch regex file-path|directory-path |  | sv | B
Maps a URL to a filesystem location using a regular expression and designates the target as a CGI script
ScriptInterpreterSource Registry|Registry-Strict|Script | Script | svdh | C
Technique for locating the interpreter for CGI scripts
ScriptLog file-path |  | sv | B
Location of the CGI script error logfile
ScriptLogBuffer bytes | 1024 | sv | B
Maximum amount of PUT or POST requests that will be recorded in the scriptlog
ScriptLogLength bytes | 10385760 | sv | B
Size limit of the CGI script logfile
ScriptSock file-path | logs/cgisock | sv | B
The name of the socket to use for communication with the cgi daemon
SecureListen [IP-address:]portnumber Certificate-Name [MUTUAL] |  | s | B
Enables SSL encryption for the specified port
SendBufferSize bytes | 0 | s | M
TCP buffer size
ServerAdmin email-address |  | sv | C
Email address that the server includes in error messages sent to the client
ServerAlias hostname [hostname] ... |  | v | C
Alternate names for a host used when matching requests to name-virtual hosts
ServerLimit number |  | s | M
Upper limit on configurable number of processes
ServerName fully-qualified-domain-name[:port] |  | sv | C
Hostname and port that the server uses to identify itself
ServerPath URL-path |  | v | C
Legacy URL pathname for a name-based virtual host that is accessed by an incompatible browser
ServerRoot directory-path | /usr/local/apache | s | C
Base directory for the server installation
ServerSignature On|Off|EMail | Off | svdh | C
Configures the footer on server-generated documents
ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full | Full | s | C
Configures the Server HTTP response header
SetEnv env-variable value |  | svdh | B
Sets environment variables
SetEnvIf attribute regex [!]env-variable[=value] [[!]env-variable[=value]] ... |  | svdh | B
Sets environment variables based on attributes of the request
SetEnvIfNoCase attribute regex [!]env-variable[=value] [[!]env-variable[=value]] ... |  | svdh | B
Sets environment variables based on attributes of the request without respect to case
SetHandler handler-name|None |  | svdh | C
Forces all matching files to be processed by a handler
SetInputFilter filter[;filter...] |  | svdh | C
Sets the filters that will process client requests and POST input
SetOutputFilter filter[;filter...] |  | svdh | C
Sets the filters that will process responses from the server
SSIEndTag tag | "-->" | sv | B
String that ends an include element
SSIErrorMsg message | "[an error occurred + | svdh | B
Error message displayed when there is an SSI error
SSIStartTag tag | "<!--#" | sv | B
String that starts an include element
SSITimeFormat formatstring | "%A, %d-%b-%Y %H:%M + | svdh | B
Configures the format in which date strings are displayed
SSIUndefinedEcho string | "(none)" | sv | B
String displayed when an unset variable is echoed
SSLCACertificateFile file-path |  | sv | E
File of concatenated PEM-encoded CA Certificates for Client Auth
SSLCACertificatePath directory-path |  | sv | E
Directory of PEM-encoded CA Certificates for Client Auth
SSLCARevocationFile file-path |  | sv | E
File of concatenated PEM-encoded CA CRLs for Client Auth
SSLCARevocationPath directory-path |  | sv | E
Directory of PEM-encoded CA CRLs for Client Auth
SSLCertificateChainFile file-path |  | sv | E
File of PEM-encoded Server CA Certificates
SSLCertificateFile file-path |  | sv | E
Server PEM-encoded X.509 Certificate file
SSLCertificateKeyFile file-path |  | sv | E
Server PEM-encoded Private Key file
SSLCipherSuite cipher-spec | ALL:!ADH:RC4+RSA:+H + | svdh | E
Cipher Suite available for negotiation in SSL handshake
SSLEngine on|off | off | sv | E
SSL Engine Operation Switch
SSLMutex type | none | s | E
Semaphore for internal mutual exclusion of operations
SSLOptions [+|-]option ... |  | svdh | E
Configure various SSL engine run-time options
SSLPassPhraseDialog type | builtin | s | E
Type of pass phrase dialog for encrypted private keys
SSLProtocol [+|-]protocol ... | all | sv | E
Configure usable SSL protocol flavors
SSLProxyCACertificateFile file-path |  | sv | E
File of concatenated PEM-encoded CA Certificates for Remote Server Auth
SSLProxyCACertificatePath directory-path |  | sv | E
Directory of PEM-encoded CA Certificates for Remote Server Auth
SSLProxyCARevocationFile file-path |  | sv | E
File of concatenated PEM-encoded CA CRLs for Remote Server Auth
SSLProxyCARevocationPath directory-path |  | sv | E
Directory of PEM-encoded CA CRLs for Remote Server Auth
SSLProxyCipherSuite cipher-spec | ALL:!ADH:RC4+RSA:+H + | svdh | E
Cipher Suite available for negotiation in SSL proxy handshake
SSLProxyEngine on|off | off | sv | E
SSL Proxy Engine Operation Switch
SSLProxyMachineCertificateFile filename |  | s | E
File of concatenated PEM-encoded client certificates and keys to be used by the proxy
SSLProxyMachineCertificatePath directory |  | s | E
Directory of PEM-encoded client certificates and keys to be used by the proxy
SSLProxyProtocol [+|-]protocol ... | all | sv | E
Configure usable SSL protocol flavors for proxy usage
SSLProxyVerify level | none | svdh | E
Type of remote server Certificate verification
SSLProxyVerifyDepth number | 1 | svdh | E
Maximum depth of CA Certificates in Remote Server Certificate verification
SSLRandomSeed context source [bytes] |  | s | E
Pseudo Random Number Generator (PRNG) seeding source
SSLRequire expression |  | dh | E
Allow access only when an arbitrarily complex boolean expression is true
SSLRequireSSL |  | dh | E
Deny access when SSL is not used for the HTTP request
SSLSessionCache type | none | s | E
Type of the global/inter-process SSL Session Cache
SSLSessionCacheTimeout seconds | 300 | sv | E
Number of seconds before an SSL session expires in the Session Cache
SSLVerifyClient level | none | svdh | E
Type of Client Certificate verification
SSLVerifyDepth number | 1 | svdh | E
Maximum depth of CA Certificates in Client Certificate verification
StartServers number |  | s | M
Number of child server processes created at startup
StartThreads number |  | s | M
Number of threads created on startup
SuexecUserGroup User Group |  | sv | E
User and group permissions for CGI programs
ThreadLimit number |  | s | M
Sets the upper limit on the configurable number of threads per child process
ThreadsPerChild number |  | s | M
Number of threads created by each child process
ThreadStackSize number | 65536 | s | M
Determine the stack size for each thread
TimeOut seconds | 300 | s | C
Amount of time the server will wait for certain events before failing a request
TransferLog file|pipe |  | sv | B
Specify location of a log file
TypesConfig file-path | conf/mime.types | s | B
The location of the mime.types file
UnsetEnv env-variable [env-variable] ... |  | svdh | B
Removes variables from the environment
UseCanonicalName On|Off|DNS | On | svd | C
Configures how the server determines its own name and port
User unix-userid | #-1 | s | M
The userid under which the server will answer requests
UserDir directory-filename | public_html | sv | B
Location of the user-specific directories
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
Contains directives that apply only to a specific hostname or IP address
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
Use accept() rather than AcceptEx() to accept network connections
XBitHack on|off|full | off | svdh | B
Parse SSI directives in files with the execute bit set


core - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Core Features

Description: | Core Apache HTTP Server features that are always available
Status: | Core

AcceptPathInfo Directive

Description: | Resources accept trailing pathname information
Syntax: | AcceptPathInfo On|Off|Default
Default: | AcceptPathInfo Default
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core
Compatibility: | Available in Apache 2.0.30 and later

This directive controls whether requests that contain trailing pathname information that follows an actual filename (or non-existent file in an existing directory) will be accepted or rejected. The trailing pathname information can be made available to scripts in the PATH_INFO environment variable.

For example, assume the location /test/ points to a directory that contains only the single file here.html. Then requests for /test/here.html/more and /test/nothere.html/more both collect /more as PATH_INFO.

The three possible arguments for the AcceptPathInfo directive are:

Off
A request will only be accepted if it maps to a literal path that exists. Therefore a request with trailing pathname information after the true filename such as /test/here.html/more in the above example will return a 404 NOT FOUND error.
On
A request will be accepted if a leading path component maps to a file that exists. The above example /test/here.html/more will be accepted if /test/here.html maps to a valid file.
Default
The treatment of requests with trailing pathname information is determined by the handler responsible for the request. The core handler for normal files defaults to rejecting PATH_INFO requests. Handlers that serve scripts, such as cgi-script and isapi-isa, generally accept PATH_INFO by default.

The primary purpose of the AcceptPathInfo directive is to allow you to override the handler's choice of accepting or rejecting PATH_INFO. This override is required, for example, when you use a filter, such as INCLUDES, to generate content based on PATH_INFO. The core handler would usually reject the request, so you can use the following configuration to enable such a script:

<Files "mypaths.shtml">
Options +Includes
SetOutputFilter INCLUDES
AcceptPathInfo On
 </Files>

AccessFileName Directive

Description: | Name of the distributed configuration file
Syntax: | AccessFileName filename [filename] ...
Default: | AccessFileName .htaccess
Context: | server config, virtual host
Status: | Core
Module: | core

While processing a request the server looks for the first existing configuration file from this list of names in every directory of the path to the document, if distributed configuration files are enabled for that directory. For example:

AccessFileName .acl

before returning the document /usr/local/web/index.html, the server will read /.acl, /usr/.acl, /usr/local/.acl and /usr/local/web/.acl for directives, unless they have been disabled with

<Directory />
AllowOverride None
 </Directory>

See also

  • AllowOverride
  • Configuration Files
  • .htaccess Files

AddDefaultCharset Directive

Description: | Default character set to be added for a response without an explicit character set
Syntax: | AddDefaultCharset On|Off|charset
Default: | AddDefaultCharset Off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core

This directive specifies the name of the character set that will be added to any response that does not have any parameter on the content type in the HTTP headers. This will override any character set specified in the body of the document via a META tag. A setting of AddDefaultCharset Off disables this functionality. AddDefaultCharset On enables Apache's internal default charset of iso-8859-1 as required by the directive. You can also specify an alternate charset to be used. For example:

AddDefaultCharset utf-8

AddOutputFilterByType Directive

Description: | assigns an output filter to a particular MIME-type
Syntax: | AddOutputFilterByType filter[;filter...] MIME-type [MIME-type] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core
Compatibility: | Available in Apache 2.0.33 and later

This directive activates a particular output filter for a request depending on the response MIME-type.

The following example uses the DEFLATE filter, which is provided by mod_deflate. It will compress all output (either static or dynamic) which is labeled as text/html or text/plain before it is sent to the client.

AddOutputFilterByType DEFLATE text/html text/plain

If you want the content to be processed by more than one filter, their names have to be separated by semicolons. It's also possible to use one AddOutputFilterByType directive for each of these filters.

The configuration below causes all script output labeled as text/html to be processed at first by the INCLUDES filter and then by the DEFLATE filter.

<Location /cgi-bin/>
Options Includes
AddOutputFilterByType INCLUDES;DEFLATE text/html
 </Location>

Note

Enabling filters with AddOutputFilterByType may fail partially or completely in some cases. For expample, no filters are applied if the MIME-type could not be determined and falls back to the DefaultType setting, even if the DefaultType is the same.

However, if you want to make sure, that the filters will be applied, assign the content type to a resource explicitely, for example with AddType or ForceType. Setting the content type within a (non-nph) CGI script is also safe.

The by-type output filters are never applied on proxy requests.

See also

  • AddOutputFilter
  • SetOutputFilter
  • filters

AllowEncodedSlashes Directive

Description: | Determines whether encoded path separators in URLs are allowed to be passed through
Syntax: | AllowEncodedSlashes On|Off
Default: | AllowEncodedSlashes Off
Context: | server config, virtual host
Status: | Core
Module: | core
Compatibility: | Available in Apache 2.0.46 and later

The AllowEncodedSlashes directive allows URLs which contain encoded path separators (%2F for / and additionally %5C for \ on according systems) to be used. Normally such URLs are refused with a 404 (Not found) error.

Turning AllowEncodedSlashes On is mostly useful when used in conjunction with PATH_INFO.

Note

Allowing encoded slashes does not imply decoding. Occurences of %2F or %5C (only on according systems) will be left as such in the otherwise decoded URL string.

See also

  • AcceptPathInfo

AllowOverride Directive

Description: | Types of directives that are allowed in .htaccess files
Syntax: | AllowOverride All|None|directive-type [directive-type] ...
Default: | AllowOverride All
Context: | directory
Status: | Core
Module: | core

When the server finds an .htaccess file (as specified by AccessFileName) it needs to know which directives declared in that file can override earlier configuration directives.

Only available in <Directory> sections

AllowOverride is valid only in <Directory> sections, not in <Location> or <Files> sections.

When this directive is set to None, then .htaccess files are completely ignored. In this case, the server will not even attempt to read .htaccess files in the filesystem.

When this directive is set to All, then any directive which has the .htaccess Context is allowed in .htaccess files.

The directive-type can be one of the following groupings of directives.

AuthConfig
Allow use of the authorization directives (AuthDBMGroupFile, AuthDBMUserFile, AuthGroupFile, AuthName, AuthType, AuthUserFile, Require, etc.).
FileInfo
Allow use of the directives controlling document types (DefaultType, ErrorDocument, ForceType, LanguagePriority, SetHandler, SetInputFilter, SetOutputFilter, and mod_mime Add* and Remove* directives, etc.).
Indexes
Allow use of the directives controlling directory indexing (AddDescription, AddIcon, AddIconByEncoding, AddIconByType, DefaultIcon, DirectoryIndex, FancyIndexing, HeaderName, IndexIgnore, IndexOptions, ReadmeName, etc.).
Limit
Allow use of the directives controlling host access (Allow, Deny and Order).
Options
Allow use of the directives controlling specific directory features (Options and XBitHack).

Example:

AllowOverride AuthConfig Indexes

See also

  • AccessFileName
  • Configuration Files
  • .htaccess Files

AuthName Directive

Description: | Authorization realm for use in HTTP authentication
Syntax: | AuthName auth-domain
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Core
Module: | core

This directive sets the name of the authorization realm for a directory. This realm is given to the client so that the user knows which username and password to send. AuthName takes a single argument; if the realm name contains spaces, it must be enclosed in quotation marks. It must be accompanied by AuthType and Require directives, and directives such as AuthUserFile and AuthGroupFile to work.

For example:

AuthName "Top Secret"

The string provided for the AuthName is what will appear in the password dialog provided by most browsers.

See also

  • Authentication, Authorization, and Access Control

AuthType Directive

Description: | Type of user authentication
Syntax: | AuthType Basic|Digest
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Core
Module: | core

This directive selects the type of user authentication for a directory. Only Basic and Digest are currently implemented. It must be accompanied by AuthName and Require directives, and directives such as AuthUserFile and AuthGroupFile to work.

See also

  • Authentication, Authorization, and Access Control

CGIMapExtension Directive

Description: | Technique for locating the interpreter for CGI scripts
Syntax: | CGIMapExtension cgi-path .extension
Context: | directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core
Compatibility: | NetWare only

This directive is used to control how Apache finds the interpreter used to run CGI scripts. For example, setting CGIMapExtension sys:\foo.nlm .foo will cause all CGI script files with a .foo extension to be passed to the FOO interpreter.

ContentDigest Directive

Description: | Enables the generation of Content-MD5 HTTP Response headers
Syntax: | ContentDigest On|Off
Default: | ContentDigest Off
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Core
Module: | core

This directive enables the generation of Content-MD5 headers as defined in RFC1864 respectively RFC2068.

MD5 is an algorithm for computing a "message digest" (sometimes called "fingerprint") of arbitrary-length data, with a high degree of confidence that any alterations in the data will be reflected in alterations in the message digest.

The Content-MD5 header provides an end-to-end message integrity check (MIC) of the entity-body. A proxy or client may check this header for detecting accidental modification of the entity-body in transit. Example header:

Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==

Note that this can cause performance problems on your server since the message digest is computed on every request (the values are not cached).

Content-MD5 is only sent for documents served by the core, and not by any module. For example, SSI documents, output from CGI scripts, and byte range responses do not have this header.

DefaultType Directive

Description: | MIME content-type that will be sent if the server cannot determine a type in any other way
Syntax: | DefaultType MIME-type
Default: | DefaultType text/plain
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core

There will be times when the server is asked to provide a document whose type cannot be determined by its MIME types mappings.

The server must inform the client of the content-type of the document, so in the event of an unknown type it uses the DefaultType. For example:

DefaultType image/gif

would be appropriate for a directory which contained many GIF images with filenames missing the .gif extension.

Note that unlike ForceType, this directive only provides the default mime-type. All other mime-type definitions, including filename extensions, that might identify the media type will override this default.

<Directory> Directive

Description: | Enclose a group of directives that apply only to the named file-system directory and sub-directories
Syntax: | <Directory directory-path> ... </Directory>
Context: | server config, virtual host
Status: | Core
Module: | core

<Directory> and </Directory> are used to enclose a group of directives that will apply only to the named directory and sub-directories of that directory. Any directive that is allowed in a directory context may be used. Directory-path is either the full path to a directory, or a wild-card string using Unix shell-style matching. In a wild-card string, ? matches any single character, and * matches any sequences of characters. You may also use [] character ranges. None of the wildcards match a `/' character, so <Directory /*/public_html> will not match /home/user/public_html, but <Directory /home/*/public_html> will match. Example:

<Directory /usr/local/httpd/htdocs>
Options Indexes FollowSymLinks
 </Directory>

Be careful with the directory-path arguments: They have to literally match the filesystem path which Apache uses to access the files. Directives applied to a particular <Directory> will not apply to files accessed from that same directory via a different path, such as via different symbolic links.

Extended regular expressions can also be used, with the addition of the ~ character. For example:

<Directory ~ "^/www/.*/[0-9]{3}">

would match directories in /www/ that consisted of three numbers.

If multiple (non-regular expression) <Directory> sections match the directory (or one of its parents) containing a document, then the directives are applied in the order of shortest match first, interspersed with the directives from the .htaccess files. For example, with

<Directory />
AllowOverride None
 </Directory>

<Directory /home/>
AllowOverride FileInfo
 </Directory>

for access to the document /home/web/dir/doc.html the steps are:

  • Apply directive AllowOverride None (disabling .htaccess files).
  • Apply directive AllowOverride FileInfo (for directory /home).
  • Apply any FileInfo directives in /home/.htaccess, /home/web/.htaccess and /home/web/dir/.htaccess in that order.

Regular expressions are not considered until after all of the normal sections have been applied. Then all of the regular expressions are tested in the order they appeared in the configuration file. For example, with

<Directory ~ abc$>
# ... directives here ...
 </Directory>

the regular expression section won't be considered until after all normal <Directory>s and .htaccess files have been applied. Then the regular expression will match on /home/abc/public_html/abc and the corresponding <Directory> will be applied.

Note that the default Apache access for <Directory /> is Allow from All. This means that Apache will serve any file mapped from an URL. It is recommended that you change this with a block such as

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

and then override this for directories you want accessible. See the Security Tips page for more details.

The directory sections occur in the httpd.conf file. <Directory> directives cannot nest, and cannot appear in a <Limit> or <LimitExcept> section.

See also

  • How <Directory>, <Location> and <Files> sections work for an explanation of how these different sections are combined when a request is received

<DirectoryMatch> Directive

Description: | Enclose directives that apply to file-system directories matching a regular expression and their subdirectories
Syntax: | <DirectoryMatch regex> ... </DirectoryMatch>
Context: | server config, virtual host
Status: | Core
Module: | core

<DirectoryMatch> and </DirectoryMatch> are used to enclose a group of directives which will apply only to the named directory and sub-directories of that directory, the same as <Directory>. However, it takes as an argument a regular expression. For example:

<DirectoryMatch "^/www/.*/[0-9]{3}">

would match directories in /www/ that consisted of three numbers.

See also

  • <Directory> for a description of how regular expressions are mixed in with normal <Directory>s
  • How <Directory>, <Location> and <Files> sections work for an explanation of how these different sections are combined when a request is received

DocumentRoot Directive

Description: | Directory that forms the main document tree visible from the web
Syntax: | DocumentRoot directory-path
Default: | DocumentRoot /usr/local/apache/htdocs
Context: | server config, virtual host
Status: | Core
Module: | core

This directive sets the directory from which httpd will serve files. Unless matched by a directive like Alias, the server appends the path from the requested URL to the document root to make the path to the document. Example:

DocumentRoot /usr/web

then an access to http://www.my.host.com/index.html refers to /usr/web/index.html.

The DocumentRoot should be specified without a trailing slash.

See also

  • Mapping URLs to Filesystem Location

EnableMMAP Directive

Description: | Use memory-mapping to read files during delivery
Syntax: | EnableMMAP On|Off
Default: | EnableMMAP On
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core

This directive controls whether the httpd may use memory-mapping if it needs to read the contents of a file during delivery. By default, when the handling of a request requires access to the data within a file -- for example, when delivering a server-parsed file using mod_include -- Apache memory-maps the file if the OS supports it.

This memory-mapping sometimes yields a performance improvement. But in some environments, it is better to disable the memory-mapping to prevent operational problems:

  • On some multiprocessor systems, memory-mapping can reduce the performance of the httpd.
  • With an NFS-mounted DocumentRoot, the httpd may crash due to a segmentation fault if a file is deleted or truncated while the httpd has it memory-mapped.

For server configurations that are vulnerable to these problems, you should disable memory-mapping of delivered files by specifying:

EnableMMAP Off

For NFS mounted files, this feature may be disabled explicitly for the offending files by specifying:

<Directory "/path-to-nfs-files"> EnableMMAP Off </Directory>

EnableSendfile Directive

Description: | Use the kernel sendfile support to deliver files to the client
Syntax: | EnableSendfile On|Off
Default: | EnableSendfile On
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core
Compatibility: | Available in version 2.0.44 and later

This directive controls whether httpd may use the sendfile support from the kernel to transmit file contents to the client. By default, when the handling of a request requires no access to the data within a file -- for example, when delivering a static file -- Apache uses sendfile to deliver the file contents without ever reading the file if the OS supports it.

This sendfile mechanism avoids seperate read and send operations, and buffer allocations. But on some platforms or within some filesystems, it is better to disable this feature to avoid operational problems:

  • 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.
  • On Linux the use of sendfile triggers TCP-checksum offloading bugs on certain networking cards when using IPv6.
  • With a network-mounted DocumentRoot (e.g., NFS or SMB), the kernel may be unable to serve the network file through its own cache.

For server configurations that are vulnerable to these problems, you should disable this feature by specifying:

EnableSendfile Off

For NFS or SMB mounted files, this feature may be disabled explicitly for the offending files by specifying:

<Directory "/path-to-nfs-files"> EnableSendfile Off </Directory>

ErrorDocument Directive

Description: | What the server will return to the client in case of an error
Syntax: | ErrorDocument error-code document
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core
Compatibility: | Quoting syntax for text messages is different in Apache 2.0

In the event of a problem or error, Apache can be configured to do one of four things,

  1. output a simple hardcoded error message
  2. output a customized message
  3. redirect to a local URL-path to handle the problem/error
  4. redirect to an external URL to handle the problem/error

The first option is the default, while options 2-4 are configured using the ErrorDocument directive, which is followed by the HTTP response code and a URL or a message. Apache will sometimes offer additional information regarding the problem/error.

URLs can begin with a slash (/) for local URLs, or be a full URL which the client can resolve. Alternatively, a message can be provided to be displayed by the browser. Examples:

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"

Note that when you specify an ErrorDocument that points to a remote URL (ie. anything with a method such as http in front of it), Apache will send a redirect to the client to tell it where to find the document, even if the document ends up being on the same server. This has several implications, the most important being that the client will not receive the original error status code, but instead will receive a redirect status code. This in turn can confuse web robots and other clients which try to determine if a URL is valid using the status code. In addition, if you use a remote URL in an ErrorDocument 401, the client will not know to prompt the user for a password since it will not receive the 401 status code. Therefore, if you use an ErrorDocument 401 directive then it must refer to a local document.

Microsoft Internet Explorer (MSIE) will by default ignore server-generated error messages when they are "too small" and substitute its own "friendly" error messages. The size threshold varies depending on the type of error, but in general, if you make your error document greater than 512 bytes, then MSIE will show the server-generated error rather than masking it. More information is available in Microsoft Knowledgebase article Q294807.

Prior to version 2.0, messages were indicated by prefixing them with a single unmatched double quote character.

See also

  • documentation of customizable responses

ErrorLog Directive

Description: | Location where the server will log errors
Syntax: | ErrorLog file-path|syslog[:facility]
Default: | ErrorLog logs/error_log (Unix) ErrorLog logs/error.log (Windows and OS/2)
Context: | server config, virtual host
Status: | Core
Module: | core

The ErrorLog directive sets the name of the file to which the server will log any errors it encounters. If the file-path is not absolute (in general: does not begin with a slash (/)) then it is assumed to be relative to the ServerRoot.

Example

ErrorLog /var/log/httpd/error_log

If the file-path begins with a pipe (|) then it is assumed to be a command to spawn to handle the error log.

Example

ErrorLog "|/usr/local/bin/httpd_errors"

Using syslog instead of a filename enables logging via syslogd(8) if the system supports it. The default is to use syslog facility local7, but you can override this by using the syslog:facility syntax where facility can be one of the names usually documented in syslog(1).

Example

ErrorLog syslog:user

SECURITY: See the security tips document for details on why your security could be compromised if the directory where logfiles are stored is writable by anyone other than the user that starts the server.

Note

When entering a file path on non-Unix platforms, care should be taken to make sure that only forward slashed are used even though the platform may allow the use of back slashes. In general it is a good idea to always use forward slashes throughout the configuration files.

See also

  • LogLevel
  • Apache Log Files

FileETag Directive

Description: | File attributes used to create the ETag HTTP response header
Syntax: | FileETag component ...
Default: | FileETag INode MTime Size
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core

The FileETag directive configures the file attributes that are used to create the ETag (entity tag) response header field when the document is based on a file. (The ETag value is used in cache management to save network bandwidth.) In Apache 1.3.22 and earlier, the ETag value was always formed from the file's inode, size, and last-modified time (mtime). The FileETag directive allows you to choose which of these -- if any -- should be used. The recognized keywords are:

INode
The file's i-node number will be included in the calculation
MTime
The date and time the file was last modified will be included
Size
The number of bytes in the file will be included
All
All available fields will be used. This is equivalent to:

FileETag INode MTime Size

None
If a document is file-based, no ETag field will be included in the response

The INode, MTime, and Size keywords may be prefixed with either + or -, which allow changes to be made to the default setting inherited from a broader scope. Any keyword appearing without such a prefix immediately and completely cancels the inherited setting.

If a directory's configuration includes FileETag INode MTime Size, and a subdirectory's includes FileETag -INode, the setting for that subdirectory (which will be inherited by any sub-subdirectories that don't override it) will be equivalent to FileETag MTime Size.

<Files> Directive

Description: | Contains directives that apply to matched filenames
Syntax: | <Files filename> ... </Files>
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Core
Module: | core

The <Files> directive limits the scope of the enclosed directives by filename. It is comparable to the <Directory> and <Location> directives. It should be matched with a </Files> directive. The directives given within this section will be applied to any object with a basename (last component of filename) matching the specified filename. <Files> sections are processed in the order they appear in the configuration file, after the <Directory> sections and .htaccess files are read, but before <Location> sections. Note that <Files> can be nested inside <Directory> sections to restrict the portion of the filesystem they apply to.

The filename argument should include a filename, or a wild-card string, where ? matches any single character, and * matches any sequences of characters. Extended regular expressions can also be used, with the addition of the ~ character. For example:

<Files ~ "\.(gif|jpe?g|png)$">

would match most common Internet graphics formats. <FilesMatch> is preferred, however.

Note that unlike <Directory> and <Location> sections, <Files> sections can be used inside .htaccess files. This allows users to control access to their own files, at a file-by-file level.

See also

  • How <Directory>, <Location> and <Files> sections work for an explanation of how these different sections are combined when a request is received

<FilesMatch> Directive

Description: | Contains directives that apply to regular-expression matched filenames
Syntax: | <FilesMatch regex> ... </FilesMatch>
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Core
Module: | core

The <FilesMatch> directive limits the scope of the enclosed directives by filename, just as the <Files> directive does. However, it accepts a regular expression. For example:

<FilesMatch "\.(gif|jpe?g|png)$">

would match most common Internet graphics formats.

See also

  • How <Directory>, <Location> and <Files> sections work for an explanation of how these different sections are combined when a request is received

ForceType Directive

Description: | Forces all matching files to be served with the specified MIME content-type
Syntax: | ForceType MIME-type|None
Context: | directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core
Compatibility: | Moved to the core in Apache 2.0

When placed into an .htaccess file or a <Directory>, or <Location> or <Files> section, this directive forces all matching files to be served with the content type identification given by MIME-type. For example, if you had a directory full of GIF files, but did not want to label them all with .gif, you might want to use:

ForceType image/gif

Note that unlike DefaultType, this directive overrides all mime-type associations, including filename extensions, that might identify the media type.

You can override any ForceType setting by using the value of None:

# force all files to be image/gif:
<Location /images>
ForceType image/gif
 </Location>

# but normal mime-type associations here:
<Location /images/mixed>
ForceType None
 </Location>

HostnameLookups Directive

Description: | Enables DNS lookups on client IP addresses
Syntax: | HostnameLookups On|Off|Double
Default: | HostnameLookups Off
Context: | server config, virtual host, directory
Status: | Core
Module: | core

This directive enables DNS lookups so that host names can be logged (and passed to CGIs/SSIs in REMOTE_HOST). The value Double refers to doing double-reverse DNS lookup. That is, after a reverse lookup is performed, a forward lookup is then performed on that result. At least one of the ip addresses in the forward lookup must match the original address. (In "tcpwrappers" terminology this is called PARANOID.)

Regardless of the setting, when mod_access is used for controlling access by hostname, a double reverse lookup will be performed. This is necessary for security. Note that the result of this double-reverse isn't generally available unless you set HostnameLookups Double. For example, if only HostnameLookups On and a request is made to an object that is protected by hostname restrictions, regardless of whether the double-reverse fails or not, CGIs will still be passed the single-reverse result in REMOTE_HOST.

The default is Off in order to save the network traffic for those sites that don't truly need the reverse lookups done. It is also better for the end users because they don't have to suffer the extra latency that a lookup entails. Heavily loaded sites should leave this directive Off, since DNS lookups can take considerable amounts of time. The utility logresolve, compiled by default to the bin subdirectory of your installation directory, can be used to look up host names from logged IP addresses offline.

IdentityCheck Directive

Description: | Enables logging of the RFC1413 identity of the remote user
Syntax: | IdentityCheck On|Off
Default: | IdentityCheck Off
Context: | server config, virtual host, directory
Status: | Core
Module: | core

This directive enables RFC1413-compliant logging of the remote user name for each connection, where the client machine runs identd or something similar. This information is logged in the access log.

The information should not be trusted in any way except for rudimentary usage tracking.

Note that this can cause serious latency problems accessing your server since every request requires one of these lookups to be performed. When firewalls are involved each lookup might possibly fail and add 30 seconds of latency to each hit. So in general this is not very useful on public servers accessible from the Internet.

<IfDefine> Directive

Description: | Encloses directives that will be processed only if a test is true at startup
Syntax: | <IfDefine [!]parameter-name> ... </IfDefine>
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Core
Module: | core

The <IfDefine test>...</IfDefine> section is used to mark directives that are conditional. The directives within an <IfDefine> section are only processed if the test is true. If test is false, everything between the start and end markers is ignored.

The test in the <IfDefine> section directive can be one of two forms:

  • parameter-name
  • !parameter-name

In the former case, the directives between the start and end markers are only processed if the parameter named parameter-name is defined. The second format reverses the test, and only processes the directives if parameter-name is not defined.

The parameter-name argument is a define as given on the httpd command line via -Dparameter- , at the time the server was started.

<IfDefine> sections are nest-able, which can be used to implement simple multiple-parameter tests. Example:

httpd -DReverseProxy ...

# httpd.conf
<IfDefine ReverseProxy>
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule proxy_module modules/libproxy.so
 </IfDefine>

<IfModule> Directive

Description: | Encloses directives that are processed conditional on the presence or absence of a specific module
Syntax: | <IfModule [!]module-name> ... </IfModule>
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Core
Module: | core

The <IfModule test>...</IfModule> section is used to mark directives that are conditional on the presence of a specific module. The directives within an <IfModule> section are only processed if the test is true. If test is false, everything between the start and end markers is ignored.

The test in the <IfModule> section directive can be one of two forms:

  • module name
  • !module name

In the former case, the directives between the start and end markers are only processed if the module named module name is included in Apache -- either compiled in or dynamically loaded using LoadModule. The second format reverses the test, and only processes the directives if module name is not included.

The module name argument is the file name of the module, at the time it was compiled. For example, mod_rewrite.c. If a module consists of several source files, use the name of the file containing the string STANDARD20_MODULE_STUFF.

<IfModule> sections are nest-able, which can be used to implement simple multiple-module tests.

This section should only be used if you need to have one configuration file that works whether or not a specific module is available. In normal operation, directives need not be placed in <IfModule> sections.

Include Directive

Description: | Includes other configuration files from within the server configuration files
Syntax: | Include file-path|directory-path
Context: | server config, virtual host, directory
Status: | Core
Module: | core
Compatibility: | Wildcard matching available in 2.0.41 and later

This directive allows inclusion of other configuration files from within the server configuration files.

Shell-style (fnmatch()) wildcard characters can be used to include several files at once, in alphabetical order. In addition, if Include points to a directory, rather than a file, Apache will read all files in that directory and any subdirectory. But including entire directories is not recommended, because it is easy to accidentally leave temporary files in a directory that can cause httpd to fail.

The file path specified may be an absolute path (i.e. starting with a slash), or may be relative to the ServerRoot directory.

Examples:

Include /usr/local/apache2/conf/ssl.conf
Include /usr/local/apache2/conf/vhosts/*.conf

Or, providing paths relative to your ServerRoot directory:

Include conf/ssl.conf
Include conf/vhosts/*.conf

Running apachectl configtest will give you a list of the files that are being processed during the configuration check:

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

See also

  • apachectl

KeepAlive Directive

Description: | Enables HTTP persistent connections
Syntax: | KeepAlive On|Off
Default: | KeepAlive On
Context: | server config, virtual host
Status: | Core
Module: | core

The Keep-Alive extension to HTTP/1.0 and the persistent connection feature of HTTP/1.1 provide long-lived HTTP sessions which allow multiple requests to be sent over the same TCP connection. In some cases this has been shown to result in an almost 50% speedup in latency times for HTML documents with many images. To enable Keep-Alive connections, set KeepAlive On.

For HTTP/1.0 clients, Keep-Alive connections will only be used if they are specifically requested by a client. In addition, a Keep-Alive connection with an HTTP/1.0 client can only be used when the length of the content is known in advance. This implies that dynamic content such as CGI output, SSI pages, and server-generated directory listings will generally not use Keep-Alive connections to HTTP/1.0 clients. For HTTP/1.1 clients, persistent connections are the default unless otherwise specified. If the client requests it, chunked encoding will be used in order to send content of unknown length over persistent connections.

See also

  • MaxKeepAliveRequests

KeepAliveTimeout Directive

Description: | Amount of time the server will wait for subsequent requests on a persistent connection
Syntax: | KeepAliveTimeout seconds
Default: | KeepAliveTimeout 15
Context: | server config, virtual host
Status: | Core
Module: | core

The number of seconds Apache will wait for a subsequent request before closing the connection. Once a request has been received, the timeout value specified by the Timeout directive applies.

Setting KeepAliveTimeout to a high value may cause performance problems in heavily loaded servers. The higher the timeout, the more server processes will be kept occupied waiting on connections with idle clients.

<Limit> Directive

Description: | Restrict enclosed access controls to only certain HTTP methods
Syntax: | <Limit method [method] ... > ... </Limit>
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Core
Module: | core

Access controls are normally effective for all access methods, and this is the usual desired behavior. In the general case, access control directives should not be placed within a <Limit> section.

The purpose of the <Limit> directive is to restrict the effect of the access controls to the nominated HTTP methods. For all other methods, the access restrictions that are enclosed in the <Limit> bracket will have no effect. The following example applies the access control only to the methods POST, PUT, and DELETE, leaving all other methods unprotected:

<Limit POST PUT DELETE>
Require valid-user
 </Limit>

The method names listed can be one or more of: GET, POST, PUT, DELETE, CONNECT, OPTIONS, PATCH, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, and UNLOCK. The method name is case-sensitive. If GET is used it will also restrict HEAD requests. The TRACE method cannot be limited.

A <LimitExcept> section should always be used in preference to a <Limit> section when restricting access, since a <LimitExcept> section provides protection against arbitrary methods.

<LimitExcept> Directive

Description: | Restrict access controls to all HTTP methods except the named ones
Syntax: | <LimitExcept method [method] ... > ... </LimitExcept>
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Core
Module: | core

<LimitExcept> and </LimitExcept> are used to enclose a group of access control directives which will then apply to any HTTP access method not listed in the arguments; i.e., it is the opposite of a <Limit> section and can be used to control both standard and nonstandard/unrecognized methods. See the documentation for <Limit> for more details.

For example:

<LimitExcept POST GET>
Require valid-user
 </LimitExcept>

LimitInternalRecursion Directive

Description: | Determine maximum number of internal redirects and nested subrequests
Syntax: | LimitInternalRecursion number [number]
Default: | LimitInternalRecursion 10
Context: | server config, virtual host
Status: | Core
Module: | core
Compatibility: | Available in Apache 2.0.47 and later

An internal redirect happens, for example, when using the Action directive, which internally redirects the original request to a CGI script. A subrequest is Apache's mechanism to find out what would happen for some URI if it were requested. For example, mod_dir uses subrequests to look for the files listed in the DirectoryIndex directive.

LimitInternalRecursion prevents the server from crashing when entering an infinite loop of internal redirects or subrequests. Such loops are usually caused by misconfigurations.

The directive stores two different limits, which are evaluated on per-request basis. The first number is the maximum number of internal redirects, that may follow each other. The second number determines, how deep subrequests may be nested. If you specify only one number, it will be assigned to both limits.

Example

LimitInternalRecursion 5

LimitRequestBody Directive

Description: | Restricts the total size of the HTTP request body sent from the client
Syntax: | LimitRequestBody bytes
Default: | LimitRequestBody 0
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Core
Module: | core

This directive specifies the number of bytes from 0 (meaning unlimited) to 2147483647 (2GB) that are allowed in a request body.

The LimitRequestBody directive allows the user to set a limit on the allowed size of an HTTP request message body within the context in which the directive is given (server, per-directory, per-file or per-location). If the client request exceeds that limit, the server will return an error response instead of servicing the request. The size of a normal request message body will vary greatly depending on the nature of the resource and the methods allowed on that resource. CGI scripts typically use the message body for retrieving form information. Implementations of the PUT method will require a value at least as large as any representation that the server wishes to accept for that resource.

This directive gives the server administrator greater control over abnormal client request behavior, which may be useful for avoiding some forms of denial-of-service attacks.

If, for example, you are permitting file upload to a particular location, and wish to limit the size of the uploaded file to 100K, you might use the following directive:

LimitRequestBody 102400

LimitRequestFields Directive

Description: | Limits the number of HTTP request header fields that will be accepted from the client
Syntax: | LimitRequestFields number
Default: | LimitRequestFields 100
Context: | server config
Status: | Core
Module: | core

Number is an integer from 0 (meaning unlimited) to 32767. The default value is defined by the compile-time constant DEFAULT_LIMIT_REQUEST_FIELDS (100 as distributed).

The LimitRequestFields directive allows the server administrator to modify the limit on the number of request header fields allowed in an HTTP request. A server needs this value to be larger than the number of fields that a normal client request might include. The number of request header fields used by a client rarely exceeds 20, but this may vary among different client implementations, often depending upon the extent to which a user has configured their browser to support detailed content negotiation. Optional HTTP extensions are often expressed using request header fields.

This directive gives the server administrator greater control over abnormal client request behavior, which may be useful for avoiding some forms of denial-of-service attacks. The value should be increased if normal clients see an error response from the server that indicates too many fields were sent in the request.

For example:

LimitRequestFields 50

LimitRequestFieldSize Directive

Description: | Limits the size of the HTTP request header allowed from the client
Syntax: | LimitRequestFieldsize bytes
Default: | LimitRequestFieldsize 8190
Context: | server config
Status: | Core
Module: | core

This directive specifies the number of bytes from 0 to the value of the compile-time constant DEFAULT_LIMIT_REQUEST_FIELDSIZE (8190 as distributed) that will be allowed in an HTTP request header.

The LimitRequestFieldSize directive allows the server administrator to reduce the limit on the allowed size of an HTTP request header field below the normal input buffer size compiled with the server. A server needs this value to be large enough to hold any one header field from a normal client request. The size of a normal request header field will vary greatly among different client implementations, often depending upon the extent to which a user has configured their browser to support detailed content negotiation.

This directive gives the server administrator greater control over abnormal client request behavior, which may be useful for avoiding some forms of denial-of-service attacks.

For example:

LimitRequestFieldSize 4094

Under normal conditions, the value should not be changed from the default.

LimitRequestLine Directive

Description: | Limit the size of the HTTP request line that will be accepted from the client
Syntax: | LimitRequestLine bytes
Default: | LimitRequestLine 8190
Context: | server config
Status: | Core
Module: | core

This directive sets the number of bytes from 0 to the value of the compile-time constant DEFAULT_LIMIT_REQUEST_LINE (8190 as distributed) that will be allowed on the HTTP request-line.

The LimitRequestLine directive allows the server administrator to reduce the limit on the allowed size of a client's HTTP request-line below the normal input buffer size compiled with the server. Since the request-line consists of the HTTP method, URI, and protocol version, the LimitRequestLine directive places a restriction on the length of a request-URI allowed for a request on the server. A server needs this value to be large enough to hold any of its resource names, including any information that might be passed in the query part of a GET request.

This directive gives the server administrator greater control over abnormal client request behavior, which may be useful for avoiding some forms of denial-of-service attacks.

For example:

LimitRequestLine 4094

Under normal conditions, the value should not be changed from the default.

LimitXMLRequestBody Directive

Description: | Limits the size of an XML-based request body
Syntax: | LimitXMLRequestBody bytes
Default: | LimitXMLRequestBody 1000000
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Core
Module: | core

Limit (in bytes) on maximum size of an XML-based request body. A value of 0 will disable any checking.

Example:

LimitXMLRequestBody 0

<Location> Directive

Description: | Applies the enclosed directives only to matching URLs
Syntax: | <Location URL-path|URL> ... </Location>
Context: | server config, virtual host
Status: | Core
Module: | core

The <Location> directive limits the scope of the enclosed directives by URL. It is similar to the <Directory> directive, and starts a subsection which is terminated with a </Location> directive. <Location> sections are processed in the order they appear in the configuration file, after the <Directory> sections and .htaccess files are read, and after the <Files> sections.

<Location> sections operate completely outside the filesystem. This has several consequences. Most importantly, <Location> directives should not be used to control access to filesystem locations. Since several different URLs may map to the same filesystem location, such access controls may by circumvented.

When to use <Location>

Use <Location> to apply directives to content that lives outside the filesystem. For content that lives in the filesystem, use <Directory> and <Files>. An exception is <Location />, which is an easy way to apply a configuration to the entire server.

For all origin (non-proxy) requests, the URL to be matched is a URL-path of the form /path/. No scheme, hostname, port, or query string may be included. For proxy requests, the URL to be matched is of the form scheme://servername/path, and you must include the prefix.

The URL may use wildcards. In a wild-card string, ? matches any single character, and * matches any sequences of characters.

Extended regular expressions can also be used, with the addition of the ~ character. For example:

<Location ~ "/(extra|special)/data">

would match URLs that contained the substring /extra/data or /special/data. The directive <LocationMatch> behaves identical to the regex version of <Location>.

The <Location> functionality is especially useful when combined with the SetHandler directive. For example, to enable status requests, but allow them only from browsers at foo.com, you might use:

<Location /status>
SetHandler server-status
Order Deny,Allow
Deny from all
Allow from .foo.com
 </Location>

Note about / (slash)

The slash character has special meaning depending on where in a URL it appears. People may be used to its behavior in the filesystem where multiple adjacent slashes are frequently collapsed to a single slash (i.e., /home///foo is the same as /home/foo). In URL-space this is not necessarily true. The <LocationMatch> directive and the regex version of <Location> require you to explicitly specify multiple slashes if that is your intention.

For example, <LocationMatch ^/abc> would match the request URL /abc but not the request URL //abc. The (non-regex) <Location> directive behaves similarly when used for proxy requests. But when (non-regex) <Location> is used for non-proxy requests it will implicitly match multiple slashes with a single slash. For example, if you specify <Location /abc/def> and the request is to /abc//def then it will match.

See also

  • How <Directory>, <Location> and <Files> sections work for an explanation of how these different sections are combined when a request is received

<LocationMatch> Directive

Description: | Applies the enclosed directives only to regular-expression matching URLs
Syntax: | <LocationMatch regex> ... </LocationMatch>
Context: | server config, virtual host
Status: | Core
Module: | core

The <LocationMatch> directive limits the scope of the enclosed directives by URL, in an identical manner to <Location>. However, it takes a regular expression as an argument instead of a simple string. For example:

<LocationMatch "/(extra|special)/data">

would match URLs that contained the substring /extra/data or /special/data.

See also

  • How <Directory>, <Location> and <Files> sections work for an explanation of how these different sections are combined when a request is received

LogLevel Directive

Description: | Controls the verbosity of the ErrorLog
Syntax: | LogLevel level
Default: | LogLevel warn
Context: | server config, virtual host
Status: | Core
Module: | core

LogLevel adjusts the verbosity of the messages recorded in the error logs (see ErrorLog directive). The following levels are available, in order of decreasing significance:

Level | Description | Example
emerg | Emergencies - system is unusable. | "Child cannot open lock file. Exiting"
alert | Action must be taken immediately. | "getpwuid: couldn't determine user name from uid"
crit | Critical Conditions. | "socket: Failed to get a socket, exiting child"
error | Error conditions. | "Premature end of script headers"
warn | Warning conditions. | "child process 1234 did not exit, sending another SIGHUP"
notice | Normal but significant condition. | "httpd: caught SIGBUS, attempting to dump core in ..."
info | Informational. | "Server seems busy, (you may need to increase StartServers, or Min/MaxSpareServers)..."
debug | Debug-level messages | "Opening config file ..."

When a particular level is specified, messages from all other levels of higher significance will be reported as well. E.g., when LogLevel info is specified, then messages with log levels of notice and warn will also be posted.

Using a level of at least crit is recommended.

For example:

LogLevel notice

Note

When logging to a regular file messages of the level notice cannot be suppressed and thus are always logged. However, this doesn't apply when logging is done using syslog.

MaxKeepAliveRequests Directive

Description: | Number of requests allowed on a persistent connection
Syntax: | MaxKeepAliveRequests number
Default: | MaxKeepAliveRequests 100
Context: | server config, virtual host
Status: | Core
Module: | core

The MaxKeepAliveRequests directive limits the number of requests allowed per connection when KeepAlive is on. If it is set to 0, unlimited requests will be allowed. We recommend that this setting be kept to a high value for maximum server performance.

For example:

MaxKeepAliveRequests 500

NameVirtualHost Directive

Description: | Designates an IP address for name-virtual hosting
Syntax: | NameVirtualHost addr[:port]
Context: | server config
Status: | Core
Module: | core

The NameVirtualHost directive is a required directive if you want to configure name-based virtual hosts.

Although addr can be hostname it is recommended that you always use an IP address, e.g.

NameVirtualHost 111.22.33.44

With the NameVirtualHost directive you specify the IP address on which the server will receive requests for the name-based virtual hosts. This will usually be the address to which your name-based virtual host names resolve. In cases where a firewall or other proxy receives the requests and forwards them on a different IP address to the server, you must specify the IP address of the physical interface on the machine which will be servicing the requests. If you have multiple name-based hosts on multiple addresses, repeat the directive for each address.

Note

Note, that the "main server" and any _default_ servers will never be served for a request to a NameVirtualHost IP Address (unless for some reason you specify NameVirtualHost but then don't define any VirtualHosts for that address).

Optionally you can specify a port number on which the name-based virtual hosts should be used, e.g.

NameVirtualHost 111.22.33.44:8080

IPv6 addresses must be enclosed in square brackets, as shown in the following example:

NameVirtualHost [fe80::a00:20ff:fea7:ccea]:8080

To receive requests on all interfaces, you can use an argument of *

NameVirtualHost *

Argument to <VirtualHost> directive

Note that the argument to the <VirtualHost> directive must exactly match the argument to the NameVirtualHost directive.

NameVirtualHost 1.2.3.4
<VirtualHost 1.2.3.4>
# ...
</VirtualHost>

See also

  • Virtual Hosts documentation

Options Directive

Description: | Configures what features are available in a particular directory
Syntax: | Options [+|-]option [[+|-]option] ...
Default: | Options All
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Core
Module: | core

The Options directive controls which server features are available in a particular directory.

option can be set to None, in which case none of the extra features are enabled, or one or more of the following:

All
All options except for MultiViews. This is the default setting.
ExecCGI
Execution of CGI scripts using mod_cgi is permitted.
FollowSymLinks
The server will follow symbolic links in this directory.

Even though the server follows the symlink it does not change the pathname used to match against <Directory> sections.

Note also, that this option gets ignored if set inside a <Location> section.

Includes
Server-side includes provided by mod_include are permitted.
IncludesNOEXEC
Server-side includes are permitted, but the #exec cmd and #exec cgi are disabled. It is still possible to #include virtual CGI scripts from ScriptAliased directories.
Indexes
If a URL which maps to a directory is requested, and there is no DirectoryIndex (e.g., index.html) in that directory, then mod_autoindex will return a formatted listing of the directory.
MultiViews
Content negotiated "MultiViews" are allowed using mod_negotiation.
SymLinksIfOwnerMatch
The server will only follow symbolic links for which the target file or directory is owned by the same user id as the link.

Note

This option gets ignored if set inside a <Location> section.

Normally, if multiple Options could apply to a directory, then the most specific one is used and others are ignored; the options are not merged. (See how sections are merged.) However if all the options on the Options directive are preceded by a + or - 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.

For example, without any + and - symbols:

<Directory /web/docs>
Options Indexes FollowSymLinks
 </Directory>

<Directory /web/docs/spec>
Options Includes
 </Directory>

then only Includes will be set for the /web/docs/spec directory. However if the second Options directive uses the + and - symbols:

<Directory /web/docs>
Options Indexes FollowSymLinks
 </Directory>

<Directory /web/docs/spec>
Options +Includes -Indexes
 </Directory>

then the options FollowSymLinks and Includes are set for the /web/docs/spec directory.

Note

Using -IncludesNOEXEC or -Includes disables server-side includes completely regardless of the previous setting.

The default in the absence of any other settings is All.

Require Directive

Description: | Selects which authenticated users can access a resource
Syntax: | Require entity-name [entity-name] ...
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Core
Module: | core

This directive selects which authenticated users can access a directory. The allowed syntaxes are:

Require user userid [userid] ...
Only the named users can access the resource.
Require group group-name [group-name] ...
Only users in the named groups can access the resource.
Require valid-user
All valid users can access the resource.

Require must be accompanied by AuthName and AuthType directives, and directives such as AuthUserFile and AuthGroupFile (to define users and groups) in order to work correctly. Example:

AuthType Basic
AuthName "Restricted Directory"
AuthUserFile /web/users
AuthGroupFile /web/groups
Require group admin

Access controls which are applied in this way are effective for all methods. This is what is normally desired. If you wish to apply access controls only to specific methods, while leaving other methods unprotected, then place the Require statement into a <Limit> section.

See also

  • Satisfy
  • mod_access

RLimitCPU Directive

Description: | Limits the CPU consumption of processes launched by Apache children
Syntax: | RLimitCPU seconds|max [seconds|max]
Default: | Unset; uses operating system defaults
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Core
Module: | core

Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all processes and the second parameter sets the maximum resource limit. Either parameter can be a number, or max to indicate to the server that the limit should be set to the maximum allowed by the operating system configuration. Raising the maximum resource limit requires that the server is running as root, or in the initial startup phase.

This applies to processes forked off from Apache children servicing requests, not the Apache children themselves. This includes CGI scripts and SSI exec commands, but not any processes forked off from the Apache parent such as piped logs.

CPU resource limits are expressed in seconds per process.

See also

  • RLimitMEM
  • RLimitNPROC

RLimitMEM Directive

Description: | Limits the memory consumption of processes launched by Apache children
Syntax: | RLimitMEM bytes|max [bytes|max]
Default: | Unset; uses operating system defaults
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Core
Module: | core

Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all processes and the second parameter sets the maximum resource limit. Either parameter can be a number, or max to indicate to the server that the limit should be set to the maximum allowed by the operating system configuration. Raising the maximum resource limit requires that the server is running as root, or in the initial startup phase.

This applies to processes forked off from Apache children servicing requests, not the Apache children themselves. This includes CGI scripts and SSI exec commands, but not any processes forked off from the Apache parent such as piped logs.

Memory resource limits are expressed in bytes per process.

See also

  • RLimitCPU
  • RLimitNPROC

RLimitNPROC Directive

Description: | Limits the number of processes that can be launched by processes launched by Apache children
Syntax: | RLimitNPROC number|max [number|max]
Default: | Unset; uses operating system defaults
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Core
Module: | core

Takes 1 or 2 parameters. The first parameter sets the soft resource limit for all processes and the second parameter sets the maximum resource limit. Either parameter can be a number, or max to indicate to the server that the limit should be set to the maximum allowed by the operating system configuration. Raising the maximum resource limit requires that the server is running as root, or in the initial startup phase.

This applies to processes forked off from Apache children servicing requests, not the Apache children themselves. This includes CGI scripts and SSI exec commands, but not any processes forked off from the Apache parent such as piped logs.

Process limits control the number of processes per user.

Note

If CGI processes are not running under userids other than the web server userid, this directive will limit the number of processes that the server itself can create. Evidence of this situation will be indicated by cannot fork messages in the error_log.

See also

  • RLimitMEM
  • RLimitCPU

Satisfy Directive

Description: | Interaction between host-level access control and user authentication
Syntax: | Satisfy Any|All
Default: | Satisfy All
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Core
Module: | core

Access policy if both Allow and Require used. The parameter can be either All or Any. This directive is only useful if access to a particular area is being restricted by both username/password and client host address. In this case the default behavior (All) is to require that the client passes the address access restriction and enters a valid username and password. With the Any option the client will be granted access if they either pass the host restriction or enter a valid username and password. This can be used to password restrict an area, but to let clients from particular addresses in without prompting for a password.

For example, if you wanted to let people on your network have unrestricted access to a portion of your website, but require that people outside of your network provide a password, you could use a configuration similar to the following:

Require valid-user
Allow from 192.168.1
Satisfy Any

See also

  • Allow
  • Require

ScriptInterpreterSource Directive

Description: | Technique for locating the interpreter for CGI scripts
Syntax: | ScriptInterpreterSource Registry|Registry-Strict|Script
Default: | ScriptInterpreterSource Script
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core
Compatibility: | Win32 only; option Registry-Strict is available in Apache 2.0 and later

This directive is used to control how Apache finds the interpreter used to run CGI scripts. The default setting is Script. This causes Apache to use the interpreter pointed to by the shebang line (first line, starting with #!) in the script. On Win32 systems this line usually looks like:

#!C:/Perl/bin/perl.exe

or, if perl is in the PATH, simply:

#!perl

Setting ScriptInterpreterSource Registry will cause the Windows Registry tree HKEY_CLASSES_ROOT to be searched using the script file extension (e.g., .pl) as a search key. The command defined by the registry subkey Shell\ExecCGI\Command or, if it does not exist, by the subkey Shell\Open\Command is used to open the script file. If the registry keys cannot be found, Apache falls back to the behavior of the Script option.

Security

Be careful when using ScriptInterpreterSource Registry with ScriptAlias'ed directories, because Apache will try to execute every file within this directory. The Registry setting may cause undesired program calls on files which are typically not executed. For example, the default open command on .htm files on most Windows systems will execute Microsoft Internet Explorer, so any HTTP request for an .htm file existing within the script directory would start the browser in the background on the server. This is a good way to crash your system within a minute or so.

The option Registry-Strict which is new in Apache 2.0 does the same thing as Registry but uses only the subkey Shell\ExecCGI\Command. The ExecCGI key is not a common one. It must be configured manually in the windows registry and hence prevents accidental program calls on your system.

ServerAdmin Directive

Description: | Email address that the server includes in error messages sent to the client
Syntax: | ServerAdmin email-address
Context: | server config, virtual host
Status: | Core
Module: | core

The ServerAdmin sets the e-mail address that the server includes in any error messages it returns to the client.

It may be worth setting up a dedicated address for this, e.g.

ServerAdmin www-admin@foo.example.com

as users do not always mention that they are talking about the server!

ServerAlias Directive

Description: | Alternate names for a host used when matching requests to name-virtual hosts
Syntax: | ServerAlias hostname [hostname] ...
Context: | virtual host
Status: | Core
Module: | core

The ServerAlias directive sets the alternate names for a host, for use with name-based virtual hosts.

<VirtualHost *>
ServerName server.domain.com
ServerAlias server server2.domain.com server2
# ...
</VirtualHost>

See also

  • Apache Virtual Host documentation

ServerName Directive

Description: | Hostname and port that the server uses to identify itself
Syntax: | ServerName fully-qualified-domain-name[:port]
Context: | server config, virtual host
Status: | Core
Module: | core
Compatibility: | In version 2.0, this directive supersedes the functionality of the Port directive from version 1.3.

The ServerName directive sets the hostname and port that the server uses to identify itself. This is used when creating redirection URLs. For example, if the name of the machine hosting the webserver is simple.example.com, but the machine also has the DNS alias www.example.com and you wish the webserver to be so identified, the following directive should be used:

ServerName www.example.com:80

If no ServerName is specified, then the server attempts to deduce the hostname by performing a reverse lookup on the IP address. If no port is specified in the servername, then the server will use the port from the incoming request. For optimal reliability and predictability, you should specify an explicit hostname and port using the ServerName directive.

If you are using name-based virtual hosts, the ServerName inside a <VirtualHost> section specifies what hostname must appear in the request's Host: header to match this virtual host.

See the description of the UseCanonicalName directive for settings which determine whether self-referential URL's (e.g., by the mod_dir module) will refer to the specified port, or to the port number given in the client's request.

See also

  • Issues Regarding DNS and Apache
  • Apache virtual host documentation
  • UseCanonicalName
  • NameVirtualHost
  • ServerAlias

ServerPath Directive

Description: | Legacy URL pathname for a name-based virtual host that is accessed by an incompatible browser
Syntax: | ServerPath URL-path
Context: | virtual host
Status: | Core
Module: | core

The ServerPath directive sets the legacy URL pathname for a host, for use with name-based virtual hosts.

See also

  • Apache Virtual Host documentation

ServerRoot Directive

Description: | Base directory for the server installation
Syntax: | ServerRoot directory-path
Default: | ServerRoot /usr/local/apache
Context: | server config
Status: | Core
Module: | core

The ServerRoot directive sets the directory in which the server lives. Typically it will contain the subdirectories conf/ and logs/. Relative paths for other configuration files are taken as relative to this directory.

Example

ServerRoot /home/httpd

See also

  • the -d option to httpd
  • the security tips for information on how to properly set permissions on the ServerRoot

ServerSignature Directive

Description: | Configures the footer on server-generated documents
Syntax: | ServerSignature On|Off|EMail
Default: | ServerSignature Off
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Core
Module: | core

The ServerSignature directive allows the configuration of a trailing footer line under server-generated documents (error messages, mod_proxy ftp directory listings, mod_info output, ...). The reason why you would want to enable such a footer line is that in a chain of proxies, the user often has no possibility to tell which of the chained servers actually produced a returned error message.

The Off setting, which is the default, suppresses the footer line (and is therefore compatible with the behavior of Apache-1.2 and below). The On setting simply adds a line with the server version number and ServerName of the serving virtual host, and the EMail setting additionally creates a "mailto:" reference to the ServerAdmin of the referenced document.

After version 2.0.44, the details of the server version number presented are controlled by the ServerTokens directive.

See also

  • ServerTokens

ServerTokens Directive

Description: | Configures the Server HTTP response header
Syntax: | ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full
Default: | ServerTokens Full
Context: | server config
Status: | Core
Module: | core

This directive controls whether Server response header field which is sent back to clients includes a description of the generic OS-type of the server as well as information about compiled-in modules.

ServerTokens Prod[uctOnly]
Server sends (e.g.): 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 sends (e.g.): Server: Apache/2.0.41
ServerTokens OS
Server sends (e.g.): Server: Apache/2.0.41 (Unix)
ServerTokens Full (or not specified)
Server sends (e.g.): Server: Apache/2.0.41 (Unix) PHP/4.2.2 MyMod/1.2

This setting applies to the entire server, and cannot be enabled or disabled on a virtualhost-by-virtualhost basis.

After version 2.0.44, this directive also controls the information presented by the ServerSignature directive.

See also

  • ServerSignature

SetHandler Directive

Description: | Forces all matching files to be processed by a handler
Syntax: | SetHandler handler-name|None
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core
Compatibility: | Moved into the core in Apache 2.0

When placed into an .htaccess file or a <Directory> or <Location> section, this directive forces all matching files to be parsed through the handler given by handler-name. For example, if you had a directory you wanted to be parsed entirely as imagemap rule files, regardless of extension, you might put the following into an .htaccess file in that directory:

SetHandler imap-file

Another example: if you wanted to have the server display a status report whenever a URL of http://servername/status was called, you might put the following into httpd.conf:

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

You can override an earlier defined SetHandler directive by using the value None.

See also

  • AddHandler

SetInputFilter Directive

Description: | Sets the filters that will process client requests and POST input
Syntax: | SetInputFilter filter[;filter...]
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core

The SetInputFilter directive sets the filter or filters which will process client requests and POST input when they are received by the server. This is in addition to any filters defined elsewhere, including the AddInputFilter directive.

If more than one filter is specified, they must be separated by semicolons in the order in which they should process the content.

See also

  • Filters documentation

SetOutputFilter Directive

Description: | Sets the filters that will process responses from the server
Syntax: | SetOutputFilter filter[;filter...]
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Core
Module: | core

The SetOutputFilter directive sets the filters which will process responses from the server before they are sent to the client. This is in addition to any filters defined elsewhere, including the AddOutputFilter directive.

For example, the following configuration will process all files in the /www/data/ directory for server-side includes.

<Directory /www/data/>
SetOutputFilter INCLUDES
 </Directory>

If more than one filter is specified, they must be separated by semicolons in the order in which they should process the content.

See also

  • Filters documentation

TimeOut Directive

Description: | Amount of time the server will wait for certain events before failing a request
Syntax: | TimeOut seconds
Default: | TimeOut 300
Context: | server config
Status: | Core
Module: | core

The TimeOut directive currently defines the amount of time Apache will wait for three things:

  1. The total amount of time it takes to receive a GET request.
  2. The amount of time between receipt of TCP packets on a POST or PUT request.
  3. The amount of time between ACKs on transmissions of TCP packets in responses.

We plan on making these separately configurable at some point down the road. The timer used to default to 1200 before 1.2, but has been lowered to 300 which is still far more than necessary in most situations. It is not set any lower by default because there may still be odd places in the code where the timer is not reset when a packet is sent.

UseCanonicalName Directive

Description: | Configures how the server determines its own name and port
Syntax: | UseCanonicalName On|Off|DNS
Default: | UseCanonicalName On
Context: | server config, virtual host, directory
Status: | Core
Module: | core

In many situations Apache must construct a self-referential URL -- that is, a URL that refers back to the same server. With UseCanonicalName On Apache will use the hostname and port specified in the ServerName directive to construct the canonical name for the server. This name is used in all self-referential URLs, and for the values of SERVER_NAME and SERVER_PORT in CGIs.

With UseCanonicalName Off Apache will form self-referential URLs using the hostname and port supplied by the client if any are supplied (otherwise it will use the canonical name, as defined above). These values are the same that are used to implement name based virtual hosts, and are available with the same clients. The CGI variables SERVER_NAME and SERVER_PORT will be constructed from the client supplied values as well.

An example where this may be useful is on an intranet server where you have users connecting to the machine using short names such as www. You'll notice that if the users type a shortname, and a URL which is a directory, such as http://www/splat, without the trailing slash then Apache will redirect them to http://www.domain.com/splat/. If you have authentication enabled, this will cause the user to have to authenticate twice (once for www and once again for www.domain.com -- see the FAQ on this subject for more information). But if UseCanonicalName is set Off, then Apache will redirect to http://www/splat/.

There is a third option, UseCanonicalName DNS, which is intended for use with mass IP-based virtual hosting to support ancient clients that do not provide a Host: header. With this option Apache does a reverse DNS lookup on the server IP address that the client connected to in order to work out self-referential URLs.

Warning

If CGIs make assumptions about the values of SERVER_NAME they may be broken by this option. The client is essentially free to give whatever value they want as a hostname. But if the CGI is only using SERVER_NAME to construct self-referential URLs then it should be just fine.

See also

  • ServerName
  • Listen

<VirtualHost> Directive

Description: | Contains directives that apply only to a specific hostname or IP address
Syntax: | <VirtualHost addr[:port] [addr[:port]] ...> ... </VirtualHost>
Context: | server config
Status: | Core
Module: | core

<VirtualHost> and </VirtualHost> are used to enclose a group of directives that will apply only to a particular virtual host. Any directive that is allowed in a virtual host context may be used. When the server receives a request for a document on a particular virtual host, it uses the configuration directives enclosed in the <VirtualHost> section. Addr can be:

  • The IP address of the virtual host;
  • A fully qualified domain name for the IP address of the virtual host;
  • The character *, which is used only in combination with NameVirtualHost * to match all IP addresses; or
  • The string _default_, which is used only with IP virtual hosting to catch unmatched IP addresses.

Example

<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 addresses must be specified in square brackets because the optional port number could not be determined otherwise. An IPv6 example is shown below:

<VirtualHost [fe80::a00:20ff:fea7:ccea]>
ServerAdmin webmaster@host.example.com
DocumentRoot /www/docs/host.example.com
ServerName host.example.com
ErrorLog logs/host.example.com-error_log
TransferLog logs/host.example.com-access_log
 </VirtualHost>

Each Virtual Host must correspond to a different IP address, different port number or a different host name for the server, in the former case the server machine must be configured to accept IP packets for multiple addresses. (If the machine does not have multiple network interfaces, then this can be accomplished with the ifconfig alias command -- if your OS supports it).

Note

The use of <VirtualHost> does not affect what addresses Apache listens on. You may need to ensure that Apache is listening on the correct addresses using Listen.

When using IP-based virtual hosting, the special name _default_ can be specified in which case this virtual host will match any IP address that is not explicitly listed in another virtual host. In the absence of any _default_ virtual host the "main" server config, consisting of all those definitions outside any VirtualHost section, is used when no IP-match occurs. (But note that any IP address that matches a NameVirtualHost directive will use neither the "main" server config nor the _default_ virtual host. See the name-based virtual hosting documentation for further details.)

You can specify a :port to change the port that is matched. If unspecified then it defaults to the same port as the most recent Listen statement of the main server. You may also specify :* to match all ports on that address. (This is recommended when used with _default_.)

Security

See the security tips document for details on why your security could be compromised if the directory where logfiles are stored is writable by anyone other than the user that starts the server.

See also

  • Apache Virtual Host documentation
  • Issues Regarding DNS and Apache
  • Setting which addresses and ports Apache uses
  • How <Directory>, <Location> and <Files> sections work for an explanation of how these different sections are combined when a request is received


mpm_common - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM Common Directives

Description: | A collection of directives that are implemented by more than one multi-processing module (MPM)
Status: | MPM

AcceptMutex Directive

Description: | Method that Apache uses to serialize multiple children accepting requests on network sockets
Syntax: | AcceptMutex Default|method
Default: | AcceptMutex Default
Context: | server config
Status: | MPM
Module: | leader, perchild, prefork, threadpool, worker

The AcceptMutex directives sets the method that Apache uses to serialize multiple children accepting requests on network sockets. Prior to Apache 2.0, the method was selectable only at compile time. The optimal method to use is highly architecture and platform dependent. For further details, see the performance tuning documentation.

If this directive is set to Default, then the compile-time selected default will be used. Other possible methods are listed below. Note that not all methods are available on all platforms. If a method is specified which is not available, a message will be written to the error log listing the available methods.

flock
uses the flock(2) system call to lock the file defined by the LockFile directive.
fcntl
uses the fcntl(2) system call to lock the file defined by the LockFile directive.
posixsem
uses POSIX compatible semaphores to implement the mutex.
pthread
uses POSIX mutexes as implemented by the POSIX Threads (PThreads) specification.
sysvsem
uses SySV-style semaphores to implement the mutex.

If you want to find out the compile time chosen default for your system, you may set your LogLevel to debug. Then the default AcceptMutex will be written into the ErrorLog.

BS2000Account Directive

Description: | Define the non-privileged account on BS2000 machines
Syntax: | BS2000Account account
Context: | server config
Status: | MPM
Module: | perchild, prefork
Compatibility: | Only available for BS2000 machines

The BS2000Account directive is available for BS2000 hosts only. It must be used to define the account number for the non-privileged apache server user (which was configured using the User directive). This is required by the BS2000 POSIX subsystem (to change the underlying BS2000 task environment by performing a sub-LOGON) to prevent CGI scripts from accessing resources of the privileged account which started the server, usually SYSROOT.

Note

Only one BS2000Account directive can be used.

See also

  • Apache EBCDIC port

CoreDumpDirectory Directive

Description: | Directory where Apache attempts to switch before dumping core
Syntax: | CoreDumpDirectory directory
Default: | See usage for the default setting
Context: | server config
Status: | MPM
Module: | beos, leader, mpm_winnt, perchild, prefork, threadpool, worker

This controls the directory to which Apache attempts to switch before dumping core. The default is in the ServerRoot directory, however since this should not be writable by the user the server runs as, core dumps won't normally get written. If you want a core dump for debugging, you can use this directive to place it in a different location.

Core Dumps on Linux

If Apache starts as root and switches to another user, the Linux kernel disables core dumps even if the directory is writable for the process. Apache (2.0.46 and later) reenables core dumps on Linux 2.4 and beyond, but only if you explicitly configure a CoreDumpDirectory.

EnableExceptionHook Directive

Description: | Enables a hook that runs exception handlers after a crash
Syntax: | EnableExceptionHook On|Off
Default: | EnableExceptionHook Off
Context: | server config
Status: | MPM
Module: | leader, perchild, prefork, threadpool, worker
Compatibility: | Available in version 2.0.49 and later

For safety reasons this directive is only available if the server was configured with the --enable-exception-hook option. It enables a hook that allows external modules to plug in and do something after a child crashed.

There are already two modules, mod_whatkilledus and mod_backtrace that make use of this hook. Please have a look at Jeff Trawick's EnableExceptionHook site for more information about these.

Group Directive

Description: | Group under which the server will answer requests
Syntax: | Group unix-group
Default: | Group #-1
Context: | server config
Status: | MPM
Module: | beos, leader, mpmt_os2, perchild, prefork, threadpool, worker
Compatibility: | Only valid in global server config since Apache 2.0

The Group directive sets the group under which the server will answer requests. In order to use this directive, the server must be run initially as root. If you start the server as a non-root user, it will fail to change to the specified group, and will instead continue to run as the group of the original user. Unix-group is one of:

A group name
Refers to the given group by name.
# followed by a group number.
Refers to a group by its number.

Example

Group www-group

It is recommended that you set up a new group specifically for running the server. Some admins use user nobody, but this is not always possible or desirable.

Security

Don't set Group (or User) to root unless you know exactly what you are doing, and what the dangers are.

Special note: Use of this directive in <VirtualHost> is no longer supported. To configure your server for suexec use SuexecUserGroup.

Note

Although the Group directive is present in the beos and mpmt_os2 MPMs, it is actually a no-op there and only exists for compatibility reasons.

Listen Directive

Description: | IP addresses and ports that the server listens to
Syntax: | Listen [IP-address:]portnumber
Context: | server config
Status: | MPM
Module: | beos, leader, mpm_netware, mpm_winnt, mpmt_os2, perchild, prefork, threadpool, worker
Compatibility: | Required directive since Apache 2.0

The Listen directive instructs Apache to listen to only specific IP addresses or ports; by default it responds to requests on all IP interfaces. Listen is now a required directive. If it is not in the config file, the server will fail to start. This is a change from previous versions of Apache.

The Listen directive tells the server to accept incoming requests on the specified port or address-and-port combination. If only a port number is specified, the server listens to the given port on all interfaces. If an IP address is given as well as a port, the server will listen on the given port and interface.

Multiple Listen directives may be used to specify a number of addresses and ports to listen to. The server will respond to requests from any of the listed addresses and ports.

For example, to make the server accept connections on both port 80 and port 8000, use:

Listen 80
Listen 8000

To make the server accept connections on two specified interfaces and port numbers, use

Listen 192.170.2.1:80
Listen 192.170.2.5:8000

IPv6 addresses must be surrounded in square brackets, as in the following example:

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

See also

  • DNS Issues
  • Setting which addresses and ports Apache uses

ListenBackLog Directive

Description: | Maximum length of the queue of pending connections
Syntax: | ListenBacklog backlog
Default: | ListenBacklog 511
Context: | server config
Status: | MPM
Module: | beos, leader, mpm_netware, mpm_winnt, mpmt_os2, perchild, prefork, threadpool, worker

The maximum length of the queue of pending connections. Generally no tuning is needed or desired, however on some systems it is desirable to increase this when under a TCP SYN flood attack. See the backlog parameter to the listen(2) system call.

This will often be limited to a smaller number by the operating system. This varies from OS to OS. Also note that many OSes do not use exactly what is specified as the backlog, but use a number based on (but normally larger than) what is set.

LockFile Directive

Description: | Location of the accept serialization lock file
Syntax: | LockFile filename
Default: | LockFile logs/accept.lock
Context: | server config
Status: | MPM
Module: | leader, perchild, prefork, threadpool, worker

The LockFile directive sets the path to the lockfile used when Apache is used with an AcceptMutex value of either fcntl or flock. This directive should normally be left at its default value. The main reason for changing it is if the logs directory is NFS mounted, since the lockfile must be stored on a local disk. The PID of the main server process is automatically appended to the filename.

Security

It is best to avoid putting this file in a world writable directory such as /var/tmp because someone could create a denial of service attack and prevent the server from starting by creating a lockfile with the same name as the one the server will try to create.

See also

  • AcceptMutex

MaxClients Directive

Description: | Maximum number of child processes that will be created to serve requests
Syntax: | MaxClients number
Default: | See usage for details
Context: | server config
Status: | MPM
Module: | beos, leader, prefork, threadpool, worker

The MaxClients directive sets the limit on the number of simultaneous requests that will be served. Any connection attempts over the MaxClients limit will normally be queued, up to a number based on the ListenBacklog directive. Once a child process is freed at the end of a different request, the connection will then be serviced.

For non-threaded servers (i.e., prefork), MaxClients translates into the maximum number of child processes that will be launched to serve requests. The default value is 256; to increase it, you must also raise ServerLimit.

For threaded and hybrid servers (e.g. beos or worker) MaxClients restricts the total number of threads that will be available to serve clients. The default value for beos is 50. For hybrid MPMs the default value is 16 (ServerLimit) multiplied by the value of 25 (ThreadsPerChild). Therefore, to increase MaxClients to a value that requires more than 16 processes, you must also raise ServerLimit.

MaxMemFree Directive

Description: | Maximum amount of memory that the main allocator is allowed to hold without calling free()
Syntax: | MaxMemFree KBytes
Default: | MaxMemFree 0
Context: | server config
Status: | MPM
Module: | beos, leader, mpm_netware, prefork, threadpool, worker, mpm_winnt

The MaxMemFree directive sets the maximum number of free Kbytes that the main allocator is allowed to hold without calling free(). When not set, or when set to zero, the threshold will be set to unlimited.

MaxRequestsPerChild Directive

Description: | Limit on the number of requests that an individual child server will handle during its life
Syntax: | MaxRequestsPerChild number
Default: | MaxRequestsPerChild 10000
Context: | server config
Status: | MPM
Module: | leader, mpm_netware, mpm_winnt, mpmt_os2, perchild, prefork, threadpool, worker

The MaxRequestsPerChild directive sets the limit on the number of requests that an individual child server process will handle. After MaxRequestsPerChild requests, the child process will die. If MaxRequestsPerChild is 0, then the process will never expire.

Different default values

The default value for mpm_netware and mpm_winnt is 0.

Setting MaxRequestsPerChild to a non-zero limit has two beneficial effects:

  • it limits the amount of memory that process can consume by (accidental) memory leakage;
  • by giving processes a finite lifetime, it helps reduce the number of processes 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 child.

MaxSpareThreads Directive

Description: | Maximum number of idle threads
Syntax: | MaxSpareThreads number
Default: | See usage for details
Context: | server config
Status: | MPM
Module: | beos, leader, mpm_netware, mpmt_os2, perchild, threadpool, worker

Maximum number of idle threads. Different MPMs deal with this directive differently.

For perchild the default is MaxSpareThreads 10. This MPM monitors the number of idle threads on a per-child basis. If there are too many idle threads in that child, the server will begin to kill threads within that child.

For worker, leader and threadpool the default is MaxSpareThreads 250. These MPMs deal with idle threads on a server-wide basis. If there are too many idle threads in the server then child processes are killed until the number of idle threads is less than this number.

For mpm_netware the default is MaxSpareThreads 100. Since this MPM runs a single-process, the spare thread count is also server-wide.

beos and mpmt_os2 work similar to mpm_netware. The default for beos is MaxSpareThreads 50. For mpmt_os2 the default value is 10.

Restrictions

The range of the MaxSpareThreads value is restricted. Apache will correct the given value automatically according to the following rules:

  • perchild requires MaxSpareThreads to be less or equal than ThreadLimit.
  • mpm_netware wants the value to be greater than MinSpareThreads.
  • For leader, threadpool and worker the value must be greater or equal than the sum of MinSpareThreads and ThreadsPerChild.

See also

  • MinSpareThreads
  • StartServers

MinSpareThreads Directive

Description: | Minimum number of idle threads available to handle request spikes
Syntax: | MinSpareThreads number
Default: | See usage for details
Context: | server config
Status: | MPM
Module: | beos, leader, mpm_netware, mpmt_os2, perchild, threadpool, worker

Minimum number of idle threads to handle request spikes. Different MPMs deal with this directive differently.

perchild uses a default of MinSpareThreads 5 and monitors the number of idle threads on a per-child basis. If there aren't enough idle threads in that child, the server will begin to create new threads within that child. Thus, if you set NumServers to 10 and a MinSpareThreads value of 5, you'll have at least 50 idle threads on your system.

worker, leader and threadpool use a default of MinSpareThreads 75 and deal with idle threads on a server-wide basis. If there aren't enough idle threads in the server then child processes are created until the number of idle threads is greater than number.

mpm_netware uses a default of MinSpareThreads 10 and, since it is a single-process MPM, tracks this on a server-wide bases.

beos and mpmt_os2 work similar to mpm_netware. The default for beos is MinSpareThreads 1. For mpmt_os2 the default value is 5.

See also

  • MaxSpareThreads
  • StartServers

PidFile Directive

Description: | File where the server records the process ID of the daemon
Syntax: | PidFile filename
Default: | PidFile logs/httpd.pid
Context: | server config
Status: | MPM
Module: | beos, leader, mpm_winnt, mpmt_os2, perchild, prefork, threadpool, worker

The PidFile directive sets the file to which the server records the process id of the daemon. If the filename is not absolute then it is assumed to be relative to the ServerRoot.

Example

PidFile /var/run/apache.pid

It is often useful to be able to send the server a signal, so that it closes and then re-opens its ErrorLog and TransferLog, and re-reads its configuration files. This is done by sending a SIGHUP (kill -1) signal to the process id listed in the PidFile.

The PidFile is subject to the same warnings about log file placement and security.

Note

As of Apache 2 it is recommended to use only the apachectl script for (re-)starting or stopping the server.

ScoreBoardFile Directive

Description: | Location of the file used to store coordination data for the child processes
Syntax: | ScoreBoardFile file-path
Default: | ScoreBoardFile logs/apache_status
Context: | server config
Status: | MPM
Module: | beos, leader, mpm_winnt, perchild, prefork, threadpool, worker

Apache uses a scoreboard to communicate between its parent and child processes. Some architectures require a file to facilitate this communication. If the file is left unspecified, Apache first attempts to create the scoreboard entirely in memory (using anonymous shared memory) and, failing that, will attempt to create the file on disk (using file-based shared memory). Specifying this directive causes Apache to always create the file on the disk.

Example

ScoreBoardFile /var/run/apache_status

File-based shared memory is useful for third-party applications that require direct access to the scoreboard.

If you use a ScoreBoardFile then you may see improved speed by placing it on a RAM disk. But be careful that you heed the same warnings about log file placement and security.

See also

  • Stopping and Restarting Apache

SendBufferSize Directive

Description: | TCP buffer size
Syntax: | SendBufferSize bytes
Default: | SendBufferSize 0
Context: | server config
Status: | MPM
Module: | beos, leader, mpm_netware, mpm_winnt, mpmt_os2, perchild, prefork, threadpool, worker

The server will set the TCP buffer size to the number of bytes specified. Very useful to increase past standard OS defaults on high speed high latency (i.e., 100ms or so, such as transcontinental fast pipes).

If set to the value of 0, the server will use the OS deault.

ServerLimit Directive

Description: | Upper limit on configurable number of processes
Syntax: | ServerLimit number
Default: | See usage for details
Context: | server config
Status: | MPM
Module: | leader, perchild, prefork, threadpool, worker

For the prefork MPM, this directive sets the maximum configured value for MaxClients for the lifetime of the Apache process. For the worker MPM, this directive in combination with ThreadLimit sets the maximum configured value for MaxClients for the lifetime of the Apache process. Any attempts to change this directive during a restart will be ignored, but MaxClients can be modified during a restart.

Special care must be taken when using this directive. If ServerLimit is set to a value much higher than necessary, extra, unused shared memory will be allocated. If both ServerLimit and MaxClients are set to values higher than the system can handle, Apache may not start or the system may become unstable.

With the prefork MPM, use this directive only if you need to set MaxClients higher than 256 (default). Do not set the value of this directive any higher than what you might want to set MaxClients to.

With worker, leader and threadpool use this directive only if your MaxClients and ThreadsPerChild settings require more than 16 server processes (default). Do not set the value of this directive any higher than the number of server processes required by what you may want for MaxClients and ThreadsPerChild.

With the perchild MPM, use this directive only if you need to set NumServers higher than 8 (default).

Note

There is a hard limit of ServerLimit 20000 compiled into the server. This is intended to avoid nasty effects caused by typos.

See also

  • Stopping and Restarting Apache

StartServers Directive

Description: | Number of child server processes created at startup
Syntax: | StartServers number
Default: | See usage for details
Context: | server config
Status: | MPM
Module: | leader, mpmt_os2, prefork, threadpool, worker

The StartServers directive sets the number of child server processes created on startup. As the number of processes is dynamically controlled depending on the load, there is usually little reason to adjust this parameter.

The default value differs from MPM to MPM. For leader, threadpool and worker the default is StartServers 3. For prefork defaults to 5 and for mpmt_os2 to 2.

StartThreads Directive

Description: | Number of threads created on startup
Syntax: | StartThreads number
Default: | See usage for details
Context: | server config
Status: | MPM
Module: | beos, mpm_netware, perchild

Number of threads created on startup. As the number of threads is dynamically controlled depending on the load, there is usually little reason to adjust this parameter.

For perchild the default is StartThreads 5 and this directive tracks the number of threads per process at startup.

For mpm_netware the default is StartThreads 50 and, since there is only a single process, this is the total number of threads created at startup to serve requests.

For beos the default is StartThreads 10. It also reflects the total number of threads created at startup to serve requests.

ThreadLimit Directive

Description: | Sets the upper limit on the configurable number of threads per child process
Syntax: | ThreadLimit number
Default: | See usage for details
Context: | server config
Status: | MPM
Module: | leader, mpm_winnt, perchild, threadpool, worker
Compatibility: | Available for mpm_winnt in Apache 2.0.41 and later

This directive sets the maximum configured value for ThreadsPerChild for the lifetime of the Apache process. Any attempts to change this directive during a restart will be ignored, but ThreadsPerChild can be modified during a restart up to the value of this directive.

Special care must be taken when using this directive. If ThreadLimit is set to a value much higher than ThreadsPerChild, extra unused shared memory will be allocated. If both ThreadLimit and ThreadsPerChild are set to values higher than the system can handle, Apache may not start or the system may become unstable. Do not set the value of this directive any higher than your greatest predicted setting of ThreadsPerChild for the current run of Apache.

The default value for ThreadLimit is 1920 when used with mpm_winnt and 64 when used with the others.

Note

There is a hard limit of ThreadLimit 20000 (or ThreadLimit 15000 with mpm_winnt) compiled into the server. This is intended to avoid nasty effects caused by typos.

ThreadsPerChild Directive

Description: | Number of threads created by each child process
Syntax: | ThreadsPerChild number
Default: | See usage for details
Context: | server config
Status: | MPM
Module: | leader, mpm_winnt, threadpool, worker

This directive sets the number of threads created by each child process. The child creates these threads at startup and never creates more. If using an MPM like mpm_winnt, where there is only one child process, this number should be high enough to handle the entire load of the server. If using an MPM like worker, where there are multiple child processes, the total number of threads should be high enough to handle the common load on the server.

The default value for ThreadsPerChild is 64 when used with mpm_winnt and 25 when used with the others.

User Directive

Description: | The userid under which the server will answer requests
Syntax: | User unix-userid
Default: | User #-1
Context: | server config
Status: | MPM
Module: | leader, perchild, prefork, threadpool, worker
Compatibility: | Only valid in global server config since Apache 2.0

The User directive sets the user ID as which the server will answer requests. In order to use this directive, the server must be run initially as root. If you start the server as a non-root user, it will fail to change to the lesser privileged user, and will instead continue to run as that original user. If you do start the server as root, then it is normal for the parent process to remain running as root. Unix-userid is one of:

A username
Refers to the given user by name.
# followed by a user number.
Refers to a user by its number.

The user should have no privileges that result in it being able to access files that are not intended to be visible to the outside world, and similarly, the user should not be able to execute code that is not meant for HTTP requests. It is recommended that you set up a new user and group specifically for running the server. Some admins use user nobody, but this is not always desirable, since the nobody user can have other uses on the system.

Security

Don't set User (or Group) to root unless you know exactly what you are doing, and what the dangers are.

With the perchild MPM, which is intended to server virtual hosts run under different user IDs, the User directive defines the user ID for the main server and the fallback for <VirtualHost> sections without an AssignUserID directive.

Special note: Use of this directive in <VirtualHost> is no longer supported. To configure your server for suexec use SuexecUserGroup.

Note

Although the User directive is present in the beos and mpmt_os2 MPMs, it is actually a no-op there and only exists for compatibility reasons.


beos - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 MPM beos

설명: | BeOS에 최적화된 다중처리 모듈.
상태: | MPM
모듈명: | mpm_beos_module
소스파일: | beos.c

요약

이 다중처리 모듈(MPM)은 BeOS에서 기본적으로 사용한다. 한 조절 프로세스가 요청을 처리할 쓰레드들을 만든다.

참고

  • 아파치가 사용할 주소와 포트 지정

MaxRequestsPerThread 지시어

설명: | 한 쓰레드가 실행하는 동안 처리할 요청개수 한계
문법: | MaxRequestsPerThread number
기본값: | MaxRequestsPerThread 0
사용장소: | 주서버설정
상태: | MPM
모듈: | beos

MaxRequestsPerThread 지시어는 한 서버 쓰레드가 처리할 요청개수를 제한한다. MaxRequestsPerThread개 요청을 처리한후 쓰레드는 죽는다. MaxRequestsPerThread가 0이면 절대로 쓰레드를 죽이지 않는다.

MaxRequestsPerThread를 0이 아닌 값으로 설정하면 두가지 장점이 있다:

  • (우연히 발생한) 메모리 유출(memory leakage)때문에 쓰레드가 낭비할 메모리량을 제한한다;
  • 쓰레드의 수명을 제한하여 서버 부하가 감소할때 쓰레드 수를 줄인다.

주의:

KeepAlive 요청의 경우 오직 첫번째 요청만을 센다. 그래서 이 지시어는 쓰레드당 연결 개수를 제한하게 된다.


leader - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 MPM leader

설명: | 표준 worker MPM의 실험적인 변형
상태: | MPM
모듈명: | mpm_leader_module
소스파일: | leader.c

요약

주의

이 MPM은 실험적인 상태로, 기대한대로 동작하지않을 수 있다.

이 모듈은 표준 worker MPM의 실험적인 변형이다. 이 모듈은 쓰레드간의 협동을 위해 Leader/Followers 디자인패턴을 사용한다. 더 자세한 정보는 http://deuce.doc.wustl.edu/doc/pspdfs/lf.pdf를 참고하라.

leader MPM을 사용하려면, httpd를 컴파일할때 구성스크립트 아규먼트에 --with-mpm=leader를 사용한다.

이 MPM은 쓰레드 동기를 위해 APR의 atomic compare-and-swap 명령을 사용한다. x86용으로 컴파일하지만 386을 지원할 필요가 없거나, SPARC용으로 컴파일하지만 UltraSPARC 칩 이전에서 실행하지 않는다면, 구성스크립트 아규먼트에 --enable-nonportable-atomics=yes를 사용하라. 그러면 APR이 오래된 CPU에는 없는 더 효율적인 명령어를 사용하여 atomic 명령을 구현한다.


mpm_netware - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM netware

Description: | Multi-Processing Module implementing an exclusively threaded web server optimized for Novell NetWare
Status: | MPM
Module 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

ThreadStackSize Directive

Description: | Determine the stack size for each thread
Syntax: | ThreadStackSize number
Default: | ThreadStackSize 65536
Context: | server config
Status: | MPM
Module: | mpm_netware

This directive tells the server what stack size to use for each of the running threads. If you ever get a stack overflow you will need to bump this number to a higher setting.


mpmt_os2 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM os2

Description: | Hybrid multi-process, multi-threaded MPM for OS/2
Status: | MPM
Module 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


perchild - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM perchild

Description: | Multi-Processing Module allowing for daemon processes serving requests to be assigned a variety of different userids
Status: | MPM
Module Identifier: | mpm_perchild_module
Source File: | perchild.c

Summary

This MPM does not currently work on most platforms. Work is ongoing to make it functional.

This Multi-Processing Module (MPM) implements a hybrid multi-process, multi-threaded web server. A fixed number of processes create threads to handle requests. Fluctuations in load are handled by increasing or decreasing the number of threads in each process.

See also

  • Setting which addresses and ports Apache uses

How it works

A single control process launches the number of child processes indicated by the NumServers directive at server startup. Each child process creates threads as specified in the StartThreads directive. The individual threads then listen for connections and serve them when they arrive.

Apache always tries to maintain a pool of spare or idle server threads, which stand ready to serve incoming requests. In this way, clients do not need to wait for new threads to be created. For each child process, Apache assesses the number of idle threads and creates or destroys threads to keep this number within the boundaries specified by MinSpareThreads and MaxSpareThreads. Since this process is very self-regulating, it is rarely necessary to modify these directives from their default values. The maximum number of clients that may be served simultaneously is determined by multiplying the number of server processes that will be created (NumServers) by the maximum number of threads created in each process (MaxThreadsPerChild).

While the parent process is usually started as root under Unix in order to bind to port 80, the child processes and threads are launched by Apache as a less-privileged user. The User and Group directives are used to set the privileges of the Apache child processes. The child processes must be able to read all the content that will be served, but should have as few privileges beyond that as possible. In addition, unless suexec is used, these directives also set the privileges which will be inherited by CGI scripts.

MaxRequestsPerChild controls how frequently the server recycles processes by killing old ones and launching new ones.

Working with different user-IDs

The perchild MPM adds the extra ability to specify that particular processes should serve requests under different user-IDs. These user-IDs can then be associated with specific virtual hosts. You have to use one ChildPerUserID directive for every user/group combination you want to be run. Then you can tie particular virtual hosts to that user and group IDs.

The following example runs 7 child processes. Two of them are run under user1/group1. The next four are run under user2/group2 and the remaining process uses the User and Group of the main server:

Global config

NumServers 7
ChildPerUserID user1 group1 2
ChildPerUserID user2 group2 4

Using unbalanced numbers of processes as above is useful, if the particular virtual hosts produce different load. The assignment to the virtual hosts is easily done as in the example below. In conclusion with the example above the following assumes, that server2 has to serve about twice of the hits of server1.

Example

NameVirtualHost *

<VirtualHost *>
ServerName fallbackhost
# no assignment; use fallback
 </VirtualHost>

<VirtualHost *>
ServerName server1
AssignUserID user1 group1
 </VirtualHost>

<VirtualHost *>
ServerName server2
AssignUserID user2 group2
 </VirtualHost>

AssignUserID Directive

Description: | Tie a virtual host to a user and group ID
Syntax: | AssignUserID user-id group-id
Context: | virtual host
Status: | MPM
Module: | perchild

Tie a virtual host to a specific user/group combination. Requests addressed to the virtual host where this directive appears will be served by a process running with the specified user and group ID.

The user and group ID has to be assigned to a number of children in the global server config using the ChildPerUserID directive. See the section above for a configuration example.

ChildPerUserID Directive

Description: | Specify user ID and group ID for a number of child processes
Syntax: | ChildPerUserID user-id group-id num-children
Context: | server config
Status: | MPM
Module: | perchild

Specify a user ID and group ID for a number of child processes. The third argument, num-children, is the number of child processes to start with the specified user and group. It does not represent a specific child number. In order to use this directive, the server must be run initially as root. If you start the server as a non-root user, it will fail to change to the lesser privileged user.

If the total number of child processes, found by totaling all of the third arguments to all ChildPerUserID directives in the config file, is less than NumServers, then all remaining children will inherit the User and Group settings from the main server. See the section above for a configuration example.

Security

Don't set user-id (or group-id) to root unless you know exactly what you are doing, and what the dangers are.

MaxThreadsPerChild Directive

Description: | Maximum number of threads per child process
Syntax: | MaxThreadsPerChild number
Default: | MaxThreadsPerChild 64
Context: | server config
Status: | MPM
Module: | perchild

This directive sets the maximum number of threads that will be created in each child process. To increase this value beyond its default, it is necessary to change the value of the ThreadLimit directive and stop and re-start the server.

NumServers Directive

Description: | Total number of children alive at the same time
Syntax: | NumServers number
Default: | NumServers 2
Context: | server config
Status: | MPM
Module: | perchild

The NumServers directive determines the number of children alive at the same time. This number should be large enough to handle the requests for the entire site. To increase this value beyond the value of 8, it is necessary to change the value of the ServerLimit directive and stop and re-start the server. See the section above for a configuration example.


prefork - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM prefork

Description: | Implements a non-threaded, pre-forking web server
Status: | MPM
Module Identifier: | mpm_prefork_module
Source File: | prefork.c

Summary

This Multi-Processing Module (MPM) implements a non-threaded, pre-forking web server that handles requests in a manner similar to Apache 1.3. It is appropriate for sites that need to avoid threading for compatibility with non-thread-safe libraries. It is also the best MPM for isolating each request, so that a problem with a single request will not affect any other.

This MPM is very self-regulating, so it is rarely necessary to adjust its configuration directives. Most important is that MaxClients be big enough to handle as many simultaneous requests as you expect to receive, but small enough to assure that there is enough physical RAM for all processes.

See also

  • Setting which addresses and ports Apache uses

How it Works

A single control process is responsible for launching child processes which listen for connections and serve them when they arrive. Apache always tries to maintain several spare or idle server processes, which stand ready to serve incoming requests. In this way, clients do not need to wait for a new child processes to be forked before their requests can be served.

The StartServers, MinSpareServers, MaxSpareServers, and MaxClients regulate how the parent process creates children 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 which need to serve more than 256 simultaneous requests may need to increase MaxClients, while sites with limited memory may need to decrease MaxClients to keep the server from thrashing (swapping memory to disk and back). More information about tuning process creation is provided in the performance hints documentation.

While the parent process is usually started as root under Unix in order to bind to port 80, the child processes are launched by Apache as a less-privileged user. The User and Group directives are used to set the privileges of the Apache child processes. The child processes must be able to read all the content that will be served, but should have as few privileges beyond that as possible.

MaxRequestsPerChild controls how frequently the server recycles processes by killing old ones and launching new ones.

MaxSpareServers Directive

Description: | Maximum number of idle child server processes
Syntax: | MaxSpareServers number
Default: | MaxSpareServers 10
Context: | server config
Status: | MPM
Module: | prefork

The MaxSpareServers directive sets the desired maximum number of idle child server processes. An idle process is one which is not handling a request. If there are more than MaxSpareServers idle, then the parent process will kill off the excess processes.

Tuning of this parameter should only be necessary on very busy sites. Setting this parameter to a large number is almost always a bad idea. If you are trying to set the value lower than MinSpareServers, Apache will automatically adjust it to MinSpareServers + 1.

See also

  • MinSpareServers
  • StartServers

MinSpareServers Directive

Description: | Minimum number of idle child server processes
Syntax: | MinSpareServers number
Default: | MinSpareServers 5
Context: | server config
Status: | MPM
Module: | prefork

The MinSpareServers directive sets the desired minimum number of idle child server processes. An idle process is one which is not handling a request. If there are fewer than MinSpareServers idle, then the parent process creates new children at a maximum rate of 1 per second.

Tuning of this parameter should only be necessary on very busy sites. Setting this parameter to a large number is almost always a bad idea.

See also

  • MaxSpareServers
  • StartServers


threadpool - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM threadpool

Description: | Yet another experimental variant of the standard worker MPM
Status: | MPM
Module Identifier: | mpm_threadpool_module
Source File: | threadpool.c

Summary

Warning

This MPM is a developer playground and highly experimental, so it may or may not work as expected.

This is an experimental variant of the standard worker MPM. Rather than queuing connections like the worker MPM, the threadpool MPM queues idle worker threads and hands each accepted connection to the next available worker.

The threadpool MPM can't match the performance of the worker MPM in benchmark testing. As of 2.0.39, some of the key load-throtting concepts from the threadpool MPM have been incorporated into the worker MPM. The threadpool code is useful primarily as a research platform. For general-purpose use and for any production environments, use worker instead.


mpm_winnt - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM winnt

Description: | This Multi-Processing Module is optimized for Windows NT.
Status: | MPM
Module Identifier: | mpm_winnt_module
Source File: | mpm_winnt.c

Summary

This Multi-Processing Module (MPM) is the default for the Windows NT operating systems. It uses a single control process which launches a single child process which in turn creates threads to handle requests

Win32DisableAcceptEx Directive

Description: | Use accept() rather than AcceptEx() to accept network connections
Syntax: | Win32DisableAcceptEx
Default: | AcceptEx() is enabled by default. Use this directive to disable use of AcceptEx()
Context: | server config
Status: | MPM
Module: | mpm_winnt
Compatibility: | Available in Version 2.0.49 and later

AcceptEx() is a Microsoft WinSock v2 API that provides some performance improvements over the use of the BSD style accept() API in certain circumstances. Some popular Windows products, typically virus scanning or virtual private network packages, have bugs that interfere with the proper operation of AcceptEx(). If you encounter an error condition like:

[error] (730038)An operation was attempted on something that is not a socket.: winnt_accept: AcceptEx failed. Attempting to recover.

you should use this directive to disable the use of AcceptEx().


worker - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache MPM worker

Description: | Multi-Processing Module implementing a hybrid multi-threaded multi-process web server
Status: | MPM
Module Identifier: | mpm_worker_module
Source File: | worker.c

Summary

This Multi-Processing Module (MPM) implements a hybrid multi-process multi-threaded server. By using threads to serve requests, it is able to serve a large number of requests with less system resources than a process-based server. Yet it retains much of the stability of a process-based server by keeping multiple processes available, each with many threads.

The most important directives used to control this MPM are ThreadsPerChild, which controls the number of threads deployed by each child process and MaxClients, which controls the maximum total number of threads that may be launched.

See also

  • Setting which addresses and ports Apache uses

How it Works

A single control process (the parent) is responsible for launching child processes. Each child process creates a fixed number of server threads as specified in the ThreadsPerChild directive, as well as a listener thread which listens for connections and passes them to a server thread for processing when they arrive.

Apache always tries to maintain a pool of spare or idle server threads, which stand ready to serve incoming requests. In this way, clients do not need to wait for a new threads or processes to be created before their requests can be served. The number of processes that will initially launched is set by the StartServers directive. Then during operation, Apache assesses the total number of idle threads in all processes, and forks or kills processes to keep this number within the boundaries specified by MinSpareThreads and MaxSpareThreads. Since this process is very self-regulating, it is rarely necessary to modify these directives from their default values. The maximum number of clients that may be served simultaneously (i.e., the maximum total number of threads in all processes) is determined by the MaxClients directive. The maximum number of active child processes is determined by the MaxClients directive divided by the ThreadsPerChild directive.

Two directives set hard limits on the number of active child processes and the number of server threads in a child process, and can only be changed by fully stopping the server and then starting it again. ServerLimit is a hard limit on the number of active child processes, and must be greater than or equal to the MaxClients directive divided by the ThreadsPerChild directive. ThreadLimit is a hard limit of the number of server threads, and must be greater than or equal to the ThreadsPerChild directive. If non-default values are specified for these directives, they should appear before other worker directives.

In addition to a the set of active child processes, there may be additional child processes which are terminating but where at least one server thread is still handling an existing client connection. Up to MaxClient terminating processes may be present, though the actual number can be expected to be much smaller. This behavior can be avoided by disabling the termination of individual child processes, which is achieved by the following:

  • set the value of MaxRequestsPerChild to zero
  • set the value of MaxSpareThreads to the same value as MaxClients

A typical configuration of the process-thread controls in the worker MPM could look as follows:

ServerLimit 16
StartServers 2
MaxClients 150
MinSpareThreads 25
MaxSpareThreads 75
ThreadsPerChild 25

While the parent process is usually started as root under Unix in order to bind to port 80, the child processes and threads are launched by Apache as a less-privileged user. The User and Group directives are used to set the privileges of the Apache child processes. The child processes must be able to read all the content that will be served, but should have as few privileges beyond that as possible. In addition, unless suexec is used, these directives also set the privileges which will be inherited by CGI scripts.

MaxRequestsPerChild controls how frequently the server recycles processes by killing old ones and launching new ones.


mod_access - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_access

Description: | Provides access control based on client hostname, IP address, or other characteristics of the client request.
Status: | Base
Module Identifier: | access_module
Source File: | mod_access.c
Compatibility: | Available only in versions prior to 2.1

Summary

The directives provided by mod_access are used in <Directory>, <Files>, and <Location> sections as well as .htaccess files to control access to particular parts of the server. Access can be controlled based on the client hostname, IP address, or other characteristics of the client request, as captured in environment variables. The Allow and Deny directives are used to specify which clients are or are not allowed access to the server, while the Order directive sets the default access state, and configures how the Allow and Deny directives interact with each other.

Both host-based access restrictions and password-based authentication may be implemented simultaneously. In that case, the Satisfy directive is used to determine how the two sets of restrictions interact.

In general, access restriction directives apply to all access methods (GET, PUT, POST, etc). This is the desired behavior in most cases. However, it is possible to restrict some methods, while leaving other methods unrestricted, by enclosing the directives in a <Limit> section.

See also

  • Satisfy
  • Require

Allow Directive

Description: | Controls which hosts can access an area of the server
Syntax: | Allow from all|host|env=env-variable [host|env=env-variable] ...
Context: | directory, .htaccess
Override: | Limit
Status: | Base
Module: | mod_access

The Allow directive affects which hosts can access an area of the server. Access can be controlled by hostname, IP Address, IP Address range, or by other characteristics of the client request captured in environment variables.

The first argument to this directive is always from. The subsequent arguments can take three different forms. If Allow from all is specified, then all hosts are allowed access, subject to the configuration of the Deny and Order directives as discussed below. To allow only particular hosts or groups of hosts to access the server, the host can be specified in any of the following formats:

A (partial) domain-name

Example:

Allow from apache.org

Hosts whose names match, or end in, this string are allowed access. Only complete components are matched, so the above example will match foo.apache.org but it will not match fooapache.org. This configuration will cause Apache to perform a double reverse DNS lookup on the client IP address, regardless of the setting of the HostnameLookups directive. It will do a reverse DNS lookup on the IP address to find the associated hostname, and then do a forward lookup on the hostname to assure that it matches the original IP address. Only if the forward and reverse DNS are consistent and the hostname matches will access be allowed.

A full IP address

Example:

Allow from 10.1.2.3

An IP address of a host allowed access

A partial IP address

Example:

Allow from 10.1

The first 1 to 3 bytes of an IP address, for subnet restriction.

A network/netmask pair

Example:

Allow from 10.1.0.0/255.255.0.0

A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet restriction.

A network/nnn CIDR specification

Example:

Allow from 10.1.0.0/16

Similar to the previous case, except the netmask consists of nnn high-order 1 bits.

Note that the last three examples above match exactly the same set of hosts.

IPv6 addresses and IPv6 subnets can be specified as shown below:

Allow from fe80::a00:20ff:fea7:ccea
Allow from fe80::a00:20ff:fea7:ccea/10

The third format of the arguments to the Allow directive allows access to the server to be controlled based on the existence of an environment variable. When Allow from env=env-variable is specified, then the request is allowed access if the environment variable env-variable exists. The server provides the ability to set environment variables in a flexible way based on characteristics of the client request using the directives provided by mod_setenvif. Therefore, this directive can be used to allow access based on such factors as the clients User-Agent (browser type), Referer, or other HTTP request header fields.

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>

In this case, browsers with a user-agent string beginning with KnockKnock/2.0 will be allowed access, and all others will be denied.

Deny Directive

Description: | Controls which hosts are denied access to the server
Syntax: | Deny from all|host|env=env-variable [host|env=env-variable] ...
Context: | directory, .htaccess
Override: | Limit
Status: | Base
Module: | mod_access

This directive allows access to the server to be restricted based on hostname, IP address, or environment variables. The arguments for the Deny directive are identical to the arguments for the Allow directive.

Order Directive

Description: | Controls the default access state and the order in which Allow and Deny are evaluated.
Syntax: | Order ordering
Default: | Order Deny,Allow
Context: | directory, .htaccess
Override: | Limit
Status: | Base
Module: | mod_access

The Order directive controls the default access state and the order in which Allow and Deny directives are evaluated. Ordering is one of

Deny,Allow
The Deny directives are evaluated before the Allow directives. Access is allowed by default. Any client which does not match a Deny directive or does match an Allow directive will be allowed access to the server.
Allow,Deny
The Allow directives are evaluated before the Deny directives. Access is denied by default. Any client which does not match an Allow directive or does match a Deny directive will be denied access to the server.
Mutual-failure
Only those hosts which appear on the Allow list and do not appear on the Deny list are granted access. This ordering has the same effect as Order Allow,Deny and is deprecated in favor of that configuration.

Keywords may only be separated by a comma; no whitespace is allowed between them. Note that in all cases every Allow and Deny statement is evaluated.

In the following example, all hosts in the apache.org domain are allowed access; all other hosts are denied access.

Order Deny,Allow
Deny from all
Allow from apache.org

In the next example, all hosts in the apache.org domain are allowed access, except for the hosts which are in the foo.apache.org subdomain, who are denied access. All hosts not in the apache.org domain are denied access because the default state is to deny access to the server.

Order Allow,Deny
Allow from apache.org
Deny from foo.apache.org

On the other hand, if the Order in the last example is changed to Deny,Allow, all hosts will be allowed access. This happens because, regardless of the actual ordering of the directives in the configuration file, the Allow from apache.org will be evaluated last and will override the Deny from foo.apache.org. All hosts not in the apache.org domain will also be allowed access because the default state will change to allow.

The presence of an Order directive can affect access to a part of the server even in the absence of accompanying Allow and Deny directives because of its effect on the default access state. For example,

<Directory /www>
Order Allow,Deny
 </Directory>

will deny all access to the /www directory because the default access state will be set to deny.

The Order directive controls the order of access directive processing only within each phase of the server's configuration processing. This implies, for example, that an Allow or Deny directive occurring in a <Location> section will always be evaluated after an Allow or Deny directive occurring in a <Directory> section or .htaccess file, regardless of the setting of the Order directive. For details on the merging of configuration sections, see the documentation on How Directory, Location and Files sections work.


mod_actions - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_actions

설명: | 이 모듈은 미디어종류나 요청메서드에 따라 CGI 스크립트를 실행한다.
상태: | Base
모듈명: | actions_module
소스파일: | mod_actions.c

요약

이 모듈에는 두가지 지시어가 있다. Action 지시어는 요청하는 파일의 종류에 따라 CGI 스크립트를 실행한다. Script 지시어는 요청이 특정 메서드를 사용할 경우 CGI 스크립트를 실행한다. 그래서 파일을 처리하는 스크립트를 매우 쉽게 실행할 수 있다.

참고

  • mod_cgi
  • CGI로 동적 내용
  • 아파치에서 핸들러 사용

Action 지시어

설명: | 특정 핸들러나 content-type에 대해 CGI 스크립트를 사용한다
문법: | Action action-type cgi-script
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | FileInfo
상태: | Base
모듈: | mod_actions

이 지시어는 요청이 action-type이면 cgi-script를 실행하는 행동을 서버에 추가한다. cgi-script는 ScriptAlias나 AddHandler를 사용하여 CGI 스크립트로 지정한 리소스의 URL경로이다. action-type에는 핸들러나 MIME content type을 사용할 수 있다. 이 지시어는 PATH_INFO와 PATH_TRANSLATED CGI 표준 환경변수로 요청한 문서의 URL과 파일경로를 전달한다.

예제

# 특정 종류의 파일 요청:
Action image/gif /cgi-bin/images.cgi

# 특정한 확장자를 가진 파일
AddHandler my-file-type .xyz
Action my-file-type /cgi-bin/program.cgi

첫번째 예에서 MIME content type이 image/gif인 파일을 요청하면 지정한 cgi 스크립트 /cgi-bin/images.cgi가 대신 처리한다.

두번째 예에서 확장자가 .xyz인 파일을 요청하면 지정한 cgi 스크립트 /cgi-bin/program.cgi가 대신 처리한다.

참고

  • AddHandler

Script 지시어

설명: | 특정 요청메서드에 대해 CGI 스크립트를 사용한다.
문법: | Script method cgi-script
사용장소: | 주서버설정, 가상호스트, directory
상태: | Base
모듈: | mod_actions

이 지시어는 파일을 method 메서드를 사용하여 요청하면 cgi-script를 실행하는 행동을 서버에 추가한다. cgi-script는 ScriptAlias나 AddHandler를 사용하여 CGI 스크립트로 지정한 리소스의 URL경로이다. 이 지시어는 PATH_INFO와 PATH_TRANSLATED CGI 표준 환경변수로 요청한 문서의 URL과 파일경로를 전달한다.

어떤 메서드 이름이라도 사용할 수 있다. 메서드 이름은 대소문자를 구별한다. 그래서 Script PUT과 Script put은 완전히 다르다.

Script 명령어는 기본적인 행동만을 처리함을 주의하라. CGI 스크립트가 불리거나, 요청한 메서드를 알아서 처리할 수 있는 리소스의 경우 그대로 처리한다. GET 메서드의 Script는 질의아규먼트가 있을때만 (예, foo.html?hi) 사용함을 주의하라. 질의아규먼트가 없다면 정상적으로 요청을 처리한다.

예제

# <ISINDEX>식 검색을 위해
Script GET /cgi-bin/search

# CGI PUT 핸들러
Script PUT /~bob/put.cgi


mod_alias - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_alias

Description: | Provides for mapping different parts of the host filesystem in the document tree and for URL redirection
Status: | Base
Module Identifier: | alias_module
Source File: | mod_alias.c

Summary

The directives contained in this module allow for manipulation and control of URLs as requests arrive at the server. The Alias and ScriptAlias directives are used to map between URLs and filesystem paths. This allows for content which is not directly under the DocumentRoot served as part of the web document tree. The ScriptAlias directive has the additional effect of marking the target directory as containing only CGI scripts.

The Redirect directives are used to instruct clients to make a new request with a different URL. They are often used when a resource has moved to a new location.

See also

  • mod_rewrite
  • Mapping URLs to the filesystem

Alias Directive

Description: | Maps URLs to filesystem locations
Syntax: | Alias URL-path file-path|directory-path
Context: | server config, virtual host
Status: | Base
Module: | mod_alias

The Alias directive allows documents to be stored in the local filesystem other than under the DocumentRoot. URLs with a (%-decoded) path beginning with url-path will be mapped to local files beginning with directory-path.

Example:

Alias /image /ftp/pub/image

A request for http://myserver/image/foo.gif would cause the server to return the file /ftp/pub/image/foo.gif.

Note that if you include a trailing / on the url-path then the server will require a trailing / in order to expand the alias. That is, if you use Alias /icons/ /usr/local/apache/icons/ then the url /icons will not be aliased.

Note that you may need to specify additional <Directory> sections which cover the destination of aliases. Aliasing occurs before <Directory> sections are checked, so only the destination of aliases are affected. (Note however <Location> sections are run through once before aliases are performed, so they will apply.)

In particular, if you are creating an Alias to a directory outside of your DocumentRoot, you may need to explicitly permit access to the target directory.

Example:

Alias /image /ftp/pub/image
<Directory /ftp/pub/image>
Order allow,deny
Allow from all
 </Directory>

AliasMatch Directive

Description: | Maps URLs to filesystem locations using regular expressions
Syntax: | AliasMatch regex file-path|directory-path
Context: | server config, virtual host
Status: | Base
Module: | mod_alias

This directive is equivalent to Alias, but makes use of standard regular expressions, instead of simple prefix matching. The supplied regular expression is matched against the URL-path, and if it matches, the server will substitute any parenthesized matches into the given string and use it as a filename. For example, to activate the /icons directory, one might use:

AliasMatch ^/icons(.*) /usr/local/apache/icons$1

Redirect Directive

Description: | Sends an external redirect asking the client to fetch a different URL
Syntax: | Redirect [status] URL-path URL
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_alias

The Redirect directive maps an old URL into a new one. The new URL is returned to the client which attempts to fetch it again with the new address. URL-path a (%-decoded) path; any requests for documents beginning with this path will be returned a redirect error to a new (%-encoded) URL beginning with URL.

Example:

Redirect /service http://foo2.bar.com/service

If the client requests http://myserver/service/foo.txt, it will be told to access http://foo2.bar.com/service/foo.txt instead.

Note

Redirect directives take precedence over Alias and ScriptAlias directives, irrespective of their ordering in the configuration file. Also, URL-path must be a fully qualified URL, not a relative path, even when used with .htaccess files or inside of <Directory> sections.

If no status argument is given, the redirect will be "temporary" (HTTP status 302). This indicates to the client that the resource has moved temporarily. The status argument can be used to return other HTTP status codes:

permanent
Returns a permanent redirect status (301) indicating that the resource has moved permanently.
temp
Returns a temporary redirect status (302). This is the default.
seeother
Returns a "See Other" status (303) indicating that the resource has been replaced.
gone
Returns a "Gone" status (410) indicating that the resource has been permanently removed. When this status is used the URL argument should be omitted.

Other status codes can be returned by giving the numeric status code as the value of status. If the status is between 300 and 399, the URL argument must be present, otherwise it must be omitted. Note that the status must be known to the Apache code (see the function send_error_response in http_protocol.c).

Example:

Redirect permanent /one http://example.com/two
Redirect 303 /three http://example.com/other

RedirectMatch Directive

Description: | Sends an external redirect based on a regular expression match of the current URL
Syntax: | RedirectMatch [status] regex URL
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_alias

This directive is equivalent to Redirect, but makes use of standard regular expressions, instead of simple prefix matching. The supplied regular expression is matched against the URL-path, and if it matches, the server will substitute any parenthesized matches into the given string and use it as a filename. For example, to redirect all GIF files to like-named JPEG files on another server, one might use:

RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg

RedirectPermanent Directive

Description: | Sends an external permanent redirect asking the client to fetch a different URL
Syntax: | RedirectPermanent URL-path URL
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_alias

This directive makes the client know that the Redirect is permanent (status 301). Exactly equivalent to Redirect permanent.

RedirectTemp Directive

Description: | Sends an external temporary redirect asking the client to fetch a different URL
Syntax: | RedirectTemp URL-path URL
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_alias

This directive makes the client know that the Redirect is only temporary (status 302). Exactly equivalent to Redirect temp.

ScriptAlias Directive

Description: | Maps a URL to a filesystem location and designates the target as a CGI script
Syntax: | ScriptAlias URL-path file-path|directory-path
Context: | server config, virtual host
Status: | Base
Module: | mod_alias

The ScriptAlias directive has the same behavior as the Alias directive, except that in addition it marks the target directory as containing CGI scripts that will be processed by mod_cgi's cgi-script handler. URLs with a (%-decoded) path beginning with URL-path will be mapped to scripts beginning with the second argument which is a full pathname in the local filesystem.

Example:

ScriptAlias /cgi-bin/ /web/cgi-bin/

A request for http://myserver/cgi-bin/foo would cause the server to run the script /web/cgi-bin/foo.

ScriptAliasMatch Directive

Description: | Maps a URL to a filesystem location using a regular expression and designates the target as a CGI script
Syntax: | ScriptAliasMatch regex file-path|directory-path
Context: | server config, virtual host
Status: | Base
Module: | mod_alias

This directive is equivalent to ScriptAlias, but makes use of standard regular expressions, instead of simple prefix matching. The supplied regular expression is matched against the URL-path, and if it matches, the server will substitute any parenthesized matches into the given string and use it as a filename. For example, to activate the standard /cgi-bin, one might use:

ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1


mod_asis - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_asis

설명: | HTTP 헤더를 포함한 파일을 보낸다
상태: | Base
모듈명: | asis_module
소스파일: | mod_asis.c

요약

이 모듈은 아파치가 일반적인 HTTP 헤더의 대부분을 추가하지않고 문서를 보내도록 만드는 send-as-is 핸들러를 제공한다.

그래서 서버는 cgi 스크립트나 nph 스크립트를 사용하지않고도 리다이렉션과 다른 특별한 HTTP 응답 등 어떤 자료도 보낼 수 있다.

과거에 이 모듈은 mime type이 httpd/send-as-is인 파일도 처리했다.

참고

  • mod_headers
  • mod_cern_meta
  • 아파치에서 핸들러 사용

사용법

서버 설정파일에서 파일과 send-as-is 핸들러를 예를 들어 다음과 같이 연결한다.

AddHandler send-as-is asis

아파치는 .asis 확장자를 가진 파일의 내용을 거의 수정하지않고 클라이언트에게 보낸다. 클라이언트는 HTTP 헤더가 필요하므로 빼먹지마라. Status: 헤더도 필요하다. 이 헤더의 내용은 세자리 숫자인 HTTP 응답코드와 그 뒤의 문구이다.

다음은 내용 그대로 클라이언트에게 파일이 리다이력션되었다고 알리는 파일의 예이다.

Status: 301 Now where did I leave that URL
Location: http://xyz.abc.com/foo/bar.html
Content-type: text/html

<html>
<head>
<title>Lame excuses'R'us</title>
</head>
<body>
<h1>Fred's exceptionally wonderful page has moved to
<a href="http://xyz.abc.com/foo/bar.html">Joe's</a> site.
</h1>
</body>
</html>

주의:

서버는 자료를 클라이언트에게 보낼때 항상 Date:와 Server: 헤더를 추가하므로, 파일에 이 헤더가 있으면 안된다. 서버는 Last-Modified 헤더를 추가하지 않는다. 그래서 아마도 이 헤더는 포함해야 한다.


mod_auth - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_auth

Description: | User authentication using text files
Status: | Base
Module Identifier: | auth_module
Source File: | mod_auth.c
Compatibility: | Available only in versions prior to 2.1

Summary

This module allows the use of HTTP Basic Authentication to restrict access by looking up users in plain text password and group files. Similar functionality and greater scalability is provided by mod_auth_dbm. HTTP Digest Authentication is provided by mod_auth_digest.

See also

  • Require
  • Satisfy
  • AuthName
  • AuthType

AuthAuthoritative Directive

Description: | Sets whether authorization and authentication are passed to lower level modules
Syntax: | AuthAuthoritative On|Off
Default: | AuthAuthoritative On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_auth

Setting the AuthAuthoritative directive explicitly to Off allows for both authentication and authorization to be passed on to lower level modules (as defined in the modules.c files) if there is no userID or rule matching the supplied userID. If there is a userID and/or rule specified; the usual password and access checks will be applied and a failure will give an "Authentication Required" reply.

So if a userID appears in the database of more than one module; or if a valid Require directive applies to more than one module; then the first module will verify the credentials; and no access is passed on; regardless of the AuthAuthoritative setting.

A common use for this is in conjunction with one of the database modules; such as mod_auth_dbm, mod_auth_msql, and mod_auth_anon. These modules supply the bulk of the user credential checking; but a few (administrator) related accesses fall through to a lower level with a well protected AuthUserFile.

By default control is not passed on and an unknown userID or rule will result in an "Authentication Required" reply. Not setting it thus keeps the system secure and forces an NCSA compliant behaviour.

Security

Do consider the implications of allowing a user to allow fall-through in his .htaccess file; and verify that this is really what you want; Generally it is easier to just secure a single .htpasswd file, than it is to secure a database such as mSQL. Make sure that the AuthUserFile and the AuthGroupFile are stored outside the document tree of the web-server; do not put them in the directory that they protect. Otherwise, clients will be able to download the AuthUserFile and the AuthGroupFile.

AuthGroupFile Directive

Description: | Sets the name of a text file containing the list of user groups for authentication
Syntax: | AuthGroupFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_auth

The AuthGroupFile directive sets the name of a textual file containing the list of user groups for user authentication. File-path is the path to the group file. If it is not absolute, it is treated as relative to the ServerRoot.

Each line of the group file contains a groupname followed by a colon, followed by the member usernames separated by spaces.

Example:

mygroup: bob joe anne

Note that searching large text files is very inefficient; AuthDBMGroupFile provides a much better performance.

Security

Make sure that the AuthGroupFile is stored outside the document tree of the web-server; do not put it in the directory that it protects. Otherwise, clients may be able to download the AuthGroupFile.

AuthUserFile Directive

Description: | Sets the name of a text file containing the list of users and passwords for authentication
Syntax: | AuthUserFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Base
Module: | mod_auth

The AuthUserFile directive sets the name of a textual file containing the list of users and passwords for user authentication. File-path is the path to the user file. If it is not absolute (i.e., if it doesn't begin with a slash), it is treated as relative to the ServerRoot.

Each line of the user file contains a username followed by a colon, followed by the encrypted password. If the same user ID is defined multiple times, mod_auth will use the first occurrence to verify the password.

The utility htpasswd which is installed as part of the binary distribution, or which can be found in src/support, is used to maintain this password file. See the man page for more details. In short:

Create a password file Filename with username as the initial ID. It will prompt for the password:

htpasswd -c Filename username

Add or modify username2 in the password file Filename:

htpasswd Filename username2

Note that searching large text files is very inefficient; AuthDBMUserFile should be used instead.

Security

Make sure that the AuthUserFile is stored outside the document tree of the web-server. Do not put it in the directory that it protects. Otherwise, clients may be able to download the AuthUserFile.


mod_auth_anon - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_auth_anon

Description: | Allows "anonymous" user access to authenticated areas
Status: | Extension
Module Identifier: | auth_anon_module
Source File: | mod_auth_anon.c
Compatibility: | Available only in versions prior to 2.1

Summary

This module does access control in a manner similar to anonymous-ftp sites; i.e. have a 'magic' user id 'anonymous' and the email address as a password. These email addresses can be logged.

Combined with other (database) access control methods, this allows for effective user tracking and customization according to a user profile while still keeping the site open for 'unregistered' users. One advantage of using Auth-based user tracking is that, unlike magic-cookies and funny URL pre/postfixes, it is completely browser independent and it allows users to share URLs.

Example

The example below (when combined with the Auth directives of a htpasswd-file based (or GDM, mSQL etc.) base access control system allows users in as 'guests' with the following properties:

  • It insists that the user enters a userID. (Anonymous_NoUserID)
  • It insists that the user enters a password. (Anonymous_MustGiveEmail)
  • The password entered must be a valid email address, ie. contain at least one '@' and a '.'. (Anonymous_VerifyEmail)
  • The userID must be one of anonymous guest www test welcome and comparison is not case sensitive. (Anonymous)
  • And the Email addresses entered in the passwd field are logged to the error log file. (Anonymous_LogEmail)

Excerpt of httpd.conf:

Anonymous_NoUserID off
Anonymous_MustGiveEmail on
Anonymous_VerifyEmail on
Anonymous_LogEmail on
Anonymous anonymous guest www test welcome

AuthName "Use 'anonymous' & Email address for guest entry"
AuthType basic

# An AuthUserFile/AuthDBUserFile/AuthDBMUserFile
# directive must be specified, or use
# Anonymous_Authoritative for public access.
# In the .htaccess for the public directory, add:
<Files *>
Order Deny,Allow
Allow from all

Require valid-user
 </Files>

Anonymous Directive

Description: | Specifies userIDs that are allowed access without password verification
Syntax: | Anonymous user [user] ...
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_anon

A list of one or more 'magic' userIDs which are allowed access without password verification. The userIDs are space separated. It is possible to use the ' and " quotes to allow a space in a userID as well as the \ escape character.

Please note that the comparison is case-IN-sensitive.
I strongly suggest that the magic username 'anonymous' is always one of the allowed userIDs.

Example:

Anonymous anonymous "Not Registered" "I don't know"

This would allow the user to enter without password verification by using the userIDs "anonymous", "AnonyMous", "Not Registered" and "I Don't Know".

Anonymous_Authoritative Directive

Description: | Configures if authorization will fall-through to other methods
Syntax: | Anonymous_Authoritative On|Off
Default: | Anonymous_Authoritative Off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_anon

When set On, there is no fall-through to other authentication methods. So if a userID does not match the values specified in the Anonymous directive, access is denied.

Be sure you know what you are doing when you decide to switch it on. And remember that the order in which the Authentication modules are queried is defined in the modules.c files at compile time.

Anonymous_LogEmail Directive

Description: | Sets whether the password entered will be logged in the error log
Syntax: | Anonymous_LogEmail On|Off
Default: | Anonymous_LogEmail On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_anon

When set On, the default, the 'password' entered (which hopefully contains a sensible email address) is logged in the error log.

Anonymous_MustGiveEmail Directive

Description: | Specifies whether blank passwords are allowed
Syntax: | Anonymous_MustGiveEmail On|Off
Default: | Anonymous_MustGiveEmail On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_anon

Specifies whether the user must specify an email address as the password. This prohibits blank passwords.

Anonymous_NoUserID Directive

Description: | Sets whether the userID field may be empty
Syntax: | Anonymous_NoUserID On|Off
Default: | Anonymous_NoUserID Off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_anon

When set On, users can leave the userID (and perhaps the password field) empty. This can be very convenient for MS-Explorer users who can just hit return or click directly on the OK button; which seems a natural reaction.

Anonymous_VerifyEmail Directive

Description: | Sets whether to check the password field for a correctly formatted email address
Syntax: | Anonymous_VerifyEmail On|Off
Default: | Anonymous_VerifyEmail Off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_anon

When set On the 'password' entered is checked for at least one '@' and a '.' to encourage users to enter valid email addresses (see the above Anonymous_LogEmail).


mod_auth_dbm - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_auth_dbm

Description: | Provides for user authentication using DBM files
Status: | Extension
Module Identifier: | auth_dbm_module
Source File: | mod_auth_dbm.c
Compatibility: | Available only in versions prior to 2.1

Summary

This module provides for HTTP Basic Authentication, where the usernames and passwords are stored in DBM type database files. It is an alternative to the plain text password files provided by mod_auth.

See also

  • AuthName
  • AuthType
  • Require
  • Satisfy

AuthDBMAuthoritative Directive

Description: | Sets whether authentication and authorization will be passwed on to lower level modules
Syntax: | AuthDBMAuthoritative On|Off
Default: | AuthDBMAuthoritative On
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_dbm

Setting the AuthDBMAuthoritative directive explicitly to Off allows for both authentication and authorization to be passed on to lower level modules (as defined in the modules.c files) if there is no userID or rule matching the supplied userID. If there is a userID and/or rule specified; the usual password and access checks will be applied and a failure will give an "Authentication Required" reply.

So if a userID appears in the database of more than one module; or if a valid Require directive applies to more than one module; then the first module will verify the credentials; and no access is passed on; regardless of the AuthDBMAuthoritative setting.

A common use for this is in conjunction with one of the basic auth modules; such as mod_auth. Whereas this DBM module supplies the bulk of the user credential checking; a few (administrator) related accesses fall through to a lower level with a well protected .htpasswd file.

By default, control is not passed on and an unknown userID or rule will result in an "Authentication Required" reply. Not setting it thus keeps the system secure and forces an NCSA compliant behaviour.

Security:

Do consider the implications of allowing a user to allow fall-through in his .htaccess file; and verify that this is really what you want; Generally it is easier to just secure a single .htpasswd file, than it is to secure a database which might have more access interfaces.

AuthDBMGroupFile Directive

Description: | Sets the name of the database file containing the list of user groups for authentication
Syntax: | AuthDBMGroupFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_dbm

The AuthDBMGroupFile directive sets the name of a DBM file containing the list of user groups for user authentication. File-path is the absolute path to the group file.

The group file is keyed on the username. The value for a user is a comma-separated list of the groups to which the users belongs. There must be no whitespace within the value, and it must never contain any colons.

Security: make sure that the AuthDBMGroupFile is stored outside the document tree of the web-server; do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthDBMGroupFile unless otherwise protected.

Combining Group and Password DBM files: In some cases it is easier to manage a single database which contains both the password and group details for each user. This simplifies any support programs that need to be written: they now only have to deal with writing to and locking a single DBM file. This can be accomplished by first setting the group and password files to point to the same DBM:

AuthDBMGroupFile /www/userbase
AuthDBMUserFile /www/userbase

The key for the single DBM is the username. The value consists of

Unix Crypt-ed Password:List of Groups[:(ignored)]

The password section contains the encrypted password as before. This is followed by a colon and the comma separated list of groups. Other data may optionally be left in the DBM file after another colon; it is ignored by the authentication module. This is what www.telescope.org uses for its combined password and group database.

AuthDBMType Directive

Description: | Sets the type of database file that is used to store passwords
Syntax: | AuthDBMType default|SDBM|GDBM|NDBM|DB
Default: | AuthDBMType default
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_dbm
Compatibility: | Available in version 2.0.30 and later.

Sets the type of database file that is used to store the passwords. The default database type is determined at compile time. The availability of other types of database files also depends on compile-time settings.

It is crucial that whatever program you use to create your password files is configured to use the same type of database.

AuthDBMUserFile Directive

Description: | Sets thename of a database file containing the list of users and passwords for authentication
Syntax: | AuthDBMUserFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_auth_dbm

The AuthDBMUserFile directive sets the name of a DBM file containing the list of users and passwords for user authentication. File-path is the absolute path to the user file.

The user file is keyed on the username. The value for a user is the encrypted password, optionally followed by a colon and arbitrary data. The colon and the data following it will be ignored by the server.

Security:

Make sure that the AuthDBMUserFile is stored outside the document tree of the web-server; do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthDBMUserFile.

Important compatibility note: The implementation of "dbmopen" in the apache modules reads the string length of the hashed values from the DBM data structures, rather than relying upon the string being NULL-appended. Some applications, such as the Netscape web server, rely upon the string being NULL-appended, so if you are having trouble using DBM files interchangeably between applications this may be a part of the problem.

A perl script called dbmmanage is included with Apache. This program can be used to create and update DBM format password files for use with this module.


mod_auth_digest - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_auth_digest

Description: | User authentication using MD5 Digest Authentication.
Status: | Experimental
Module Identifier: | auth_digest_module
Source File: | mod_auth_digest.c

Summary

This module implements HTTP Digest Authentication. However, it has not been extensively tested and is therefore marked experimental.

See also

  • AuthName
  • AuthType
  • Require
  • Satisfy

Using Digest Authentication

Using MD5 Digest authentication is very simple. Simply set up authentication normally, using AuthType Digest and AuthDigestFile instead of the normal AuthType Basic and AuthUserFile; also, replace any AuthGroupFile with AuthDigestGroupFile. Then add a AuthDigestDomain directive containing at least the root URI(s) for this protection space.

Appropriate user (text) files can be created using the htdigest tool.

Example:

<Location /private/>
AuthType Digest
AuthName "private area"
AuthDigestDomain /private/ http://mirror.my.dom/private2/
AuthDigestFile /web/auth/.digest_pw
Require valid-user
 </Location>

Note

Digest authentication provides a more secure password system than Basic authentication, but only works with supporting browsers. As of November 2002, the major browsers that support digest authentication are Opera, MS Internet Explorer (fails when used with a query string), Amaya, Mozilla and Netscape since version 7. Since digest authentication is not as widely implemented as basic authentication, you should use it only in controlled environments.

AuthDigestAlgorithm Directive

Description: | Selects the algorithm used to calculate the challenge and response hases in digest authentication
Syntax: | AuthDigestAlgorithm MD5|MD5-sess
Default: | AuthDigestAlgorithm MD5
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestAlgorithm directive selects the algorithm used to calculate the challenge and response hashes.

MD5-sess is not correctly implemented yet.

AuthDigestDomain Directive

Description: | URIs that are in the same protection space for digest authentication
Syntax: | AuthDigestDomain URI [URI] ...
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestDomain directive allows you to specify one or more URIs which are in the same protection space (i.e. use the same realm and username/password info). The specified URIs are prefixes, i.e. the client will assume that all URIs "below" these are also protected by the same username/password. The URIs may be either absolute URIs (i.e. inluding a scheme, host, port, etc) or relative URIs.

This directive should always be specified and contain at least the (set of) root URI(s) for this space. Omitting to do so will cause the client to send the Authorization header for every request sent to this server. Apart from increasing the size of the request, it may also have a detrimental effect on performance if AuthDigestNcCheck is on.

The URIs specified can also point to different servers, in which case clients (which understand this) will then share username/password info across multiple servers without prompting the user each time.

AuthDigestFile Directive

Description: | Location of the text file containing the list of users and encoded passwords for digest authentication
Syntax: | AuthDigestFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestFile directive sets the name of a textual file containing the list of users and encoded passwords for digest authentication. File-path is the absolute path to the user file.

The digest file uses a special format. Files in this format can be created using the htdigest utility found in the support/ subdirectory of the Apache distribution.

AuthDigestGroupFile Directive

Description: | Name of the text file containing the list of groups for digest authentication
Syntax: | AuthDigestGroupFile file-path
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestGroupFile directive sets the name of a textual file containing the list of groups and their members (user names). File-path is the absolute path to the group file.

Each line of the group file contains a groupname followed by a colon, followed by the member usernames separated by spaces. Example:

mygroup: bob joe anne

Note that searching large text files is very inefficient.

Security:

Make sure that the AuthGroupFile is stored outside the document tree of the web-server; do not put it in the directory that it protects. Otherwise, clients may be able to download the AuthGroupFile.

AuthDigestNcCheck Directive

Description: | Enables or disables checking of the nonce-count sent by the server
Syntax: | AuthDigestNcCheck On|Off
Default: | AuthDigestNcCheck Off
Context: | server config
Status: | Experimental
Module: | mod_auth_digest
Not implemented yet.

AuthDigestNonceFormat Directive

Description: | Determines how the nonce is generated
Syntax: | AuthDigestNonceFormat format
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest
Not implemented yet.

AuthDigestNonceLifetime Directive

Description: | How long the server nonce is valid
Syntax: | AuthDigestNonceLifetime seconds
Default: | AuthDigestNonceLifetime 300
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestNonceLifetime directive controls how long the server nonce is valid. When the client contacts the server using an expired nonce the server will send back a 401 with stale=true. If seconds is greater than 0 then it specifies the amount of time for which the nonce is valid; this should probably never be set to less than 10 seconds. If seconds is less than 0 then the nonce never expires.

AuthDigestQop Directive

Description: | Determines the quality-of-protection to use in digest authentication
Syntax: | AuthDigestQop none|auth|auth-int [auth|auth-int]
Default: | AuthDigestQop auth
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestQop directive determines the quality-of-protection to use. auth will only do authentication (username/password); auth-int is authentication plus integrity checking (an MD5 hash of the entity is also computed and checked); none will cause the module to use the old RFC-2069 digest algorithm (which does not include integrity checking). Both auth and auth-int may be specified, in which the case the browser will choose which of these to use. none should only be used if the browser for some reason does not like the challenge it receives otherwise.

auth-int is not implemented yet.

AuthDigestShmemSize Directive

Description: | The amount of shared memory to allocate for keeping track of clients
Syntax: | AuthDigestShmemSize size
Default: | AuthDigestShmemSize 1000
Context: | server config
Status: | Experimental
Module: | mod_auth_digest

The AuthDigestShmemSize directive defines the amount of shared memory, that will be allocated at the server startup for keeping track of clients. Note that the shared memory segment cannot be set less than the space that is neccessary for tracking at least one client. This value is dependant on your system. If you want to find out the exact value, you may simply set AuthDigestShmemSize to the value of 0 and read the error message after trying to start the server.

The size is normally expressed in Bytes, but you may let the number follow a K or an M to express your value as KBytes or MBytes. For example, the following directives are all equivalent:

AuthDigestShmemSize 1048576
AuthDigestShmemSize 1024K
AuthDigestShmemSize 1M


mod_auth_ldap - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_auth_ldap

Description: | Allows an LDAP directory to be used to store the database for HTTP Basic authentication.
Status: | Experimental
Module Identifier: | auth_ldap_module
Source File: | mod_auth_ldap.c
Compatibility: | Available in version 2.0.41 and later

Summary

mod_auth_ldap supports the following features:

  • Known to support the OpenLDAP SDK (both 1.x and 2.x), Novell LDAP SDK and the iPlanet (Netscape) SDK.
  • Complex authorization policies can be implemented by representing the policy with LDAP filters.
  • Support for Microsoft FrontPage allows FrontPage users to control access to their webs, while retaining LDAP for user authentication.
  • Uses extensive caching of LDAP operations via mod_ldap.
  • Support for LDAP over SSL (requires the Netscape SDK) or TLS (requires the OpenLDAP 2.x SDK or Novell LDAP SDK).

See also

  • mod_ldap

Contents

  • Operation
    • The Authentication Phase
    • The Authorization Phase
  • The require Directives
    • require valid-user
    • require user
    • require group
    • require dn
  • Examples
  • Using TLS
  • Using SSL
  • Using Microsoft FrontPage with mod_auth_ldap
    • How It Works
    • Caveats

Operation

There are two phases in granting access to a user. The first phase is authentication, in which mod_auth_ldap verifies that the user's credentials are valid. This also called the search/bind phase. The second phase is authorization, in which mod_auth_ldap determines if the authenticated user is allowed access to the resource in question. This is also known as the compare phase.

The Authentication Phase

During the authentication phase, mod_auth_ldap searches for an entry in the directory that matches the username that the HTTP client passes. If a single unique match is found, then mod_auth_ldap attempts to bind to the directory server using the DN of the entry plus the password provided by the HTTP client. Because it does a search, then a bind, it is often referred to as the search/bind phase. Here are the steps taken during the search/bind phase.

  1. Generate a search filter by combining the attribute and filter provided in the AuthLDAPURL directive with the username passed by the HTTP client.
  2. Search the directory using the generated filter. If the search does not return exactly one entry, deny or decline access.
  3. Fetch the distinguished name of the entry retrieved from the search and attempt to bind to the LDAP server using the DN and the password passed by the HTTP client. If the bind is unsuccessful, deny or decline access.

The following directives are used during the search/bind phase

AuthLDAPURL | Specifies the LDAP server, the base DN, the attribute to use in the search, as well as the extra search filter to use.
AuthLDAPBindDN | An optional DN to bind with during the search phase.
AuthLDAPBindPassword | An optional password to bind with during the search phase.

The Authorization Phase

During the authorization phase, mod_auth_ldap attempts to determine if the user is authorized to access the resource. Many of these checks require mod_auth_ldap to do a compare operation on the LDAP server. This is why this phase is often referred to as the compare phase. mod_auth_ldap accepts the following Require directives to determine if the credentials are acceptable:

  • Grant access if there is a require valid-user directive.
  • Grant access if there is a require user directive, and the username in the directive matches the username passed by the client.
  • Grant access if there is a require dn directive, and the DN in the directive matches the DN fetched from the LDAP directory.
  • Grant access if there is a require group directive, and the DN fetched from the LDAP directory (or the username passed by the client) occurs in the LDAP group.
  • otherwise, deny or decline access

mod_auth_ldap uses the following directives during the compare phase:

AuthLDAPURL | The attribute specified in the URL is used in compare operations for the require user operation.
AuthLDAPCompareDNOnServer | Determines the behavior of the require dn directive.
AuthLDAPGroupAttribute | Determines the attribute to use for comparisons in the require group directive.
AuthLDAPGroupAttributeIsDN | Specifies whether to use the user DN or the username when doing comparisons for the require group directive.

The require Directives

Apache's Require directives are used during the authorization phase to ensure that a user is allowed to access a resource.

require valid-user

If this directive exists, mod_auth_ldap grants access to any user that has successfully authenticated during the search/bind phase.

require user

The require user directive specifies what usernames can access the resource. Once mod_auth_ldap has retrieved a unique DN from the directory, it does an LDAP compare operation using the username specified in the require user to see if that username is part of the just-fetched LDAP entry. Multiple users can be granted access by putting multiple usernames on the line, separated with spaces. If a username has a space in it, then it must be surrounded with double quotes. Multiple users can also be granted access by using multiple require user directives, with one user per line. For example, with a AuthLDAPURL of ldap://ldap/o=Airius?cn (i.e., cn is used for searches), the following require directives could be used to restrict access:

require user "Barbara Jenson"
require user "Fred User"
require user "Joe Manager"

Because of the way that mod_auth_ldap handles this directive, Barbara Jenson could sign on as Barbara Jenson, Babs Jenson or any other cn that she has in her LDAP entry. Only the single require user line is needed to support all values of the attribute in the user's entry.

If the uid attribute was used instead of the cn attribute in the URL above, the above three lines could be condensed to

require user bjenson fuser jmanager

require group

This directive specifies an LDAP group whose members are allowed access. It takes the distinguished name of the LDAP group. For example, assume that the following entry existed in the LDAP directory:

dn: cn=Administrators, o=Airius
objectClass: groupOfUniqueNames
uniqueMember: cn=Barbara Jenson, o=Airius
uniqueMember: cn=Fred User, o=Airius

The following directive would grant access to both Fred and Barbara:

require group "cn=Administrators, o=Airius"

Behavior of this directive is modified by the AuthLDAPGroupAttribute and AuthLDAPGroupAttributeIsDN directives.

require dn

The require dn directive allows the administrator to grant access based on distinguished names. It specifies a DN that must match for access to be granted. If the distinguished name that was retrieved from the directory server matches the distinguished name in the require dn, then authorization is granted.

The following directive would grant access to a specific DN:

require dn "cn=Barbara Jenson, o=Airius"

Behavior of this directive is modified by the AuthLDAPCompareDNOnServer directive.

Examples

  • Grant access to anyone who exists in the LDAP directory, using their UID for searches.

    AuthLDAPURL "ldap://ldap1.airius.com:389/ou=People, o=Airius?uid?sub?(objectClass=*)"
    require valid-user

  • The next example is the same as above; but with the fields that have useful defaults omitted. Also, note the use of a redundant LDAP server.

    AuthLDAPURL "ldap://ldap1.airius.com ldap2.airius.com/ou=People, o=Airius"
    require valid-user

  • The next example is similar to the previous one, but is uses the common name instead of the UID. Note that this could be problematical if multiple people in the directory share the same cn, because a search on cn must return exactly one entry. That's why this approach is not recommended: it's a better idea to choose an attribute that is guaranteed unique in your directory, such as uid.

    AuthLDAPURL "ldap://ldap.airius.com/ou=People, o=Airius?cn"
    require valid-user

  • Grant access to anybody in the Administrators group. The users must authenticate using their UID.

    AuthLDAPURL "ldap://ldap.airius.com/o=Airius?uid"
    require group cn=Administrators, o=Airius

  • The next example assumes that everyone at Airius who carries an alphanumeric pager will have an LDAP attribute of qpagePagerID. The example will grant access only to people (authenticated via their UID) who have alphanumeric pagers:

    AuthLDAPURL "ldap://ldap.airius.com/o=Airius?uid??(qpagePagerID=*)"
    require valid-user

  • The next example demonstrates the power of using filters to accomplish complicated administrative requirements. Without filters, it would have been necessary to create a new LDAP group and ensure that the group's members remain synchronized with the pager users. This becomes trivial with filters. The goal is to grant access to anyone who has a filter, plus grant access to Joe Manager, who doesn't have a pager, but does need to access the same resource:

    AuthLDAPURL "ldap://ldap.airius.com/o=Airius?uid??(|(qpagePagerID=*)(uid=jmanager))"
    require valid-user

    This last may look confusing at first, so it helps to evaluate what the search filter will look like based on who connects, as shown below. The text in blue is the part that is filled in using the attribute specified in the URL. The text in red is the part that is filled in using the filter specified in the URL. The text in green is filled in using the information that is retrieved from the HTTP client. If Fred User connects as fuser, the filter would look like

    (&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))

    The above search will only succeed if fuser has a pager. When Joe Manager connects as jmanager, the filter looks like

    (&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))

    The above search will succeed whether jmanager has a pager or not.

Using TLS

To use TLS, see the mod_ldap directives LDAPTrustedCA and LDAPTrustedCAType.

Using SSL

To use SSL, see the mod_ldap directives LDAPTrustedCA and LDAPTrustedCAType.

To specify a secure LDAP server, use ldaps:// in the AuthLDAPURL directive, instead of ldap://.

Using Microsoft FrontPage with mod_auth_ldap

Normally, FrontPage uses FrontPage-web-specific user/group files (i.e., the mod_auth module) to handle all authentication. Unfortunately, it is not possible to just change to LDAP authentication by adding the proper directives, because it will break the Permissions forms in the FrontPage client, which attempt to modify the standard text-based authorization files.

Once a FrontPage web has been created, adding LDAP authentication to it is a matter of adding the following directives to every .htaccess file that gets created in the web

AuthLDAPURL            "the url"
AuthLDAPAuthoritative  off
AuthLDAPFrontPageHack  on

AuthLDAPAuthoritative must be off to allow mod_auth_ldap to decline group authentication so that Apache will fall back to file authentication for checking group membership. This allows the FrontPage-managed group file to be used.

How It Works

FrontPage restricts access to a web by adding the require valid-user directive to the .htaccess files. If AuthLDAPFrontPageHack is not on, the require valid-user directive will succeed for any user who is valid as far as LDAP is concerned. This means that anybody who has an entry in the LDAP directory is considered a valid user, whereas FrontPage considers only those people in the local user file to be valid. The purpose of the hack is to force Apache to consult the local user file (which is managed by FrontPage) - instead of LDAP - when handling the require valid-user directive.

Once directives have been added as specified above, FrontPage users will be able to perform all management operations from the FrontPage client.

Caveats

  • When choosing the LDAP URL, the attribute to use for authentication should be something that will also be valid for putting into a mod_auth user file. The user ID is ideal for this.
  • When adding users via FrontPage, FrontPage administrators should choose usernames that already exist in the LDAP directory (for obvious reasons). Also, the password that the administrator enters into the form is ignored, since Apache will actually be authenticating against the password in the LDAP database, and not against the password in the local user file. This could cause confusion for web administrators.
  • Apache must be compiled with mod_auth in order to use FrontPage support. This is because Apache will still use the mod_auth group file for determine the extent of a user's access to the FrontPage web.
  • The directives must be put in the .htaccess files. Attempting to put them inside <Location> or <Directory> directives won't work. This is because mod_auth_ldap has to be able to grab the AuthUserFile directive that is found in FrontPage .htaccess files so that it knows where to look for the valid user list. If the mod_auth_ldap directives aren't in the same .htaccess file as the FrontPage directives, then the hack won't work, because mod_auth_ldap will never get a chance to process the .htaccess file, and won't be able to find the FrontPage-managed user file.

AuthLDAPAuthoritative Directive

Description: | Prevent other authentication modules from authenticating the user if this one fails
Syntax: | AuthLDAPAuthoritative on|off
Default: | AuthLDAPAuthoritative on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

Set to off if this module should let other authentication modules attempt to authenticate the user, should authentication with this module fail. Control is only passed on to lower modules if there is no DN or rule that matches the supplied user name (as passed by the client).

AuthLDAPBindDN Directive

Description: | Optional DN to use in binding to the LDAP server
Syntax: | AuthLDAPBindDN distinguished-name
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

An optional DN used to bind to the server when searching for entries. If not provided, mod_auth_ldap will use an anonymous bind.

AuthLDAPBindPassword Directive

Description: | Password used in conjuction with the bind DN
Syntax: | AuthLDAPBindPassword password
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

A bind password to use in conjunction with the bind DN. Note that the bind password is probably sensitive data, and should be properly protected. You should only use the AuthLDAPBindDN and AuthLDAPBindPassword if you absolutely need them to search the directory.

AuthLDAPCharsetConfig Directive

Description: | Language to charset conversion configuration file
Syntax: | AuthLDAPCharsetConfig file-path
Context: | server config
Status: | Experimental
Module: | mod_auth_ldap

The AuthLDAPCharsetConfig directive sets the location of the language to charset conversion configuration file. File-path is relative to the ServerRoot. This file specifies the list of language extensions to character sets. Most administrators use the provided charset.conv file, which associates common language extensions to character sets.

The file contains lines in the following format:

Language-Extension charset [Language-String] ...

The case of the extension does not matter. Blank lines, and lines beginning with a hash character (#) are ignored.

AuthLDAPCompareDNOnServer Directive

Description: | Use the LDAP server to compare the DNs
Syntax: | AuthLDAPCompareDNOnServer on|off
Default: | AuthLDAPCompareDNOnServer on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

When set, mod_auth_ldap will use the LDAP server to compare the DNs. This is the only foolproof way to compare DNs. mod_auth_ldap will search the directory for the DN specified with the require dn directive, then, retrieve the DN and compare it with the DN retrieved from the user entry. If this directive is not set, mod_auth_ldap simply does a string comparison. It is possible to get false negatives with this approach, but it is much faster. Note the mod_ldap cache can speed up DN comparison in most situations.

AuthLDAPDereferenceAliases Directive

Description: | When will the module de-reference aliases
Syntax: | AuthLDAPDereferenceAliases never|searching|finding|always
Default: | AuthLDAPDereferenceAliases Always
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

This directive specifies when mod_auth_ldap will de-reference aliases during LDAP operations. The default is always.

AuthLDAPEnabled Directive

Description: | Turn on or off LDAP authentication
Syntax: | AuthLDAPEnabled on|off
Default: | AuthLDAPEnabled on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

Set to off to disable mod_auth_ldap in certain directories. This is useful if you have mod_auth_ldap enabled at or near the top of your tree, but want to disable it completely in certain locations.

AuthLDAPFrontPageHack Directive

Description: | Allow LDAP authentication to work with MS FrontPage
Syntax: | AuthLDAPFrontPageHack on|off
Default: | AuthLDAPFrontPageHack off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

See the section on using Microsoft FrontPage with mod_auth_ldap.

AuthLDAPGroupAttribute Directive

Description: | LDAP attributes used to check for group membership
Syntax: | AuthLDAPGroupAttribute attribute
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

This directive specifies which LDAP attributes are used to check for group membership. Multiple attributes can be used by specifying this directive multiple times. If not specified, then mod_auth_ldap uses the member and uniquemember attributes.

AuthLDAPGroupAttributeIsDN Directive

Description: | Use the DN of the client username when checking for group membership
Syntax: | AuthLDAPGroupAttributeIsDN on|off
Default: | AuthLDAPGroupAttributeIsDN on
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

When set on, this directive says to use the distinguished name of the client username when checking for group membership. Otherwise, the username will be used. For example, assume that the client sent the username bjenson, which corresponds to the LDAP DN cn=Babs Jenson, o=Airius. If this directive is set, mod_auth_ldap will check if the group has cn=Babs Jenson, o=Airius as a member. If this directive is not set, then mod_auth_ldap will check if the group has bjenson as a member.

AuthLDAPRemoteUserIsDN Directive

Description: | Use the DN of the client username to set the REMOTE_USER environment variable
Syntax: | AuthLDAPRemoteUserIsDN on|off
Default: | AuthLDAPRemoteUserIsDN off
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

If this directive is set to on, the value of the REMOTE_USER environment variable will be set to the full distinguished name of the authenticated user, rather than just the username that was passed by the client. It is turned off by default.

AuthLDAPUrl Directive

Description: | URL specifying the LDAP search parameters
Syntax: | AuthLDAPUrl url
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Experimental
Module: | mod_auth_ldap

An RFC 2255 URL which specifies the LDAP search parameters to use. The syntax of the URL is

ldap://host:port/basedn?attribute?scope?filter

ldap
For regular ldap, use the string ldap. For secure LDAP, use ldaps instead. Secure LDAP is only available if Apache was linked to an LDAP library with SSL support.
host:port

The name/port of the ldap server (defaults to localhost:389 for ldap, and localhost:636 for ldaps). To specify multiple, redundant LDAP servers, just list all servers, separated by spaces. mod_auth_ldap will try connecting to each server in turn, until it makes a successful connection.

Once a connection has been made to a server, that connection remains active for the life of the httpd process, or until the LDAP server goes down.

If the LDAP server goes down and breaks an existing connection, mod_auth_ldap will attempt to re-connect, starting with the primary server, and trying each redundant server in turn. Note that this is different than a true round-robin search.

basedn
The DN of the branch of the directory where all searches should start from. At the very least, this must be the top of your directory tree, but could also specify a subtree in the directory.
attribute
The attribute to search for. Although RFC 2255 allows a comma-separated list of attributes, only the first attribute will be used, no matter how many are provided. If no attributes are provided, the default is to use uid. It's a good idea to choose an attribute that will be unique across all entries in the subtree you will be using.
scope
The scope of the search. Can be either one or sub. Note that a scope of base is also supported by RFC 2255, but is not supported by this module. If the scope is not provided, or if base scope is specified, the default is to use a scope of sub.
filter
A valid LDAP search filter. If not provided, defaults to (objectClass=*), which will search for all objects in the tree. Filters are limited to approximately 8000 characters (the definition of MAX_STRING_LEN in the Apache source code). This should be than sufficient for any application.

When doing searches, the attribute, filter and username passed by the HTTP client are combined to create a search filter that looks like (&(filter)(attribute=username)).

For example, consider an URL of ldap://ldap.airius.com/o=Airius?cn?sub?(posixid=*). When a client attempts to connect using a username of Babs Jenson, the resulting search filter will be (&(posixid=*)(cn=Babs Jenson)).

See above for examples of AuthLDAPURL URLs.


mod_autoindex - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_autoindex

설명: | 자동으로 유닉스의 ls 명령어나 Win32의 dir 쉘명령어와 유사한 디렉토리 목록을 만든다
상태: | Base
모듈명: | autoindex_module
소스파일: | mod_autoindex.c

요약

디렉토리 목록은 얻는 방법은 두가지다:

  • 보통 index.html이란 이름으로 사용자가 작성한 파일. 이 파일의 이름은 DirectoryIndex 지시어로 지정한다. 이 작업은 mod_dir이 한다.
  • 아니면 서버가 목록을 만든다. 이 목록의 형식을 지정하는 지시어들이 있다. AddIcon, AddIconByEncoding, AddIconByType은 여러 파일종류마다 보여줄 아이콘들을 지정한다. 각 파일에 대응하는 첫번째 아이콘을 보인다. 이 작업을 mod_autoindex가 한다.

이 두 기능은 서로 별개로, 원한다면 자동 목록 생성을 완전히 제외할 (혹은 대체할) 수 있다.

자동 목록 생성은 Options +Indexes로 가능하다. 자세한 내용은 Options 지시어를 참고하라.

IndexOptions 지시어에 FancyIndexing 옵션을 주면, 열 이름을 출력할 순서를 바꾸는 링크로 만든다. 이름 링크를 선택하면 그 열의 값 순서로 목록을 다시 만든다. 같은 이름을 반복해서 선택하면 오름차순과 내림차순 사이를 오간다. IndexOptions 지시어의 SuppressColumnSorting 옵션은 이런 열 이름 링크를 만들지 않는다.

"Size(크기)" 순으로 볼때 출력되는 값 순서가 아니라 실제 파일크기 순서임을 주의하라. 즉, 1010 바이트 파일과 1011 바이트 파일은 둘다 "1K"로 보이더라도 항상 1010 바이트 파일이 앞에 나온다.

Autoindex 요청 아규먼트

아파치 2.0.23는 열순서에 대한 요청 아규먼트를 정리하고, 새로운 옵션들을 추가했다. 출력을 클라이언트가 조절할 수 없도록 만드는 IndexOptions IgnoreClient 옵션이 추가되었다.

열순서 이름은 아래 나온 순서 요청 옵션을 더한 자기참조 링크다. 아래 옵션은 디렉토리 자원에 대한 어떤 요청에도 사용할 수 있다.

  • C=N은 파일명 순이다
  • C=M은 최근 수정일 순, 그리고 파일명 순이다
  • C=S는 크기 순, 그리고 파일명 순이다
  • C=D는 설명 순, 그리고 파일명 순이다
  • O=A는 오름차순으로 목록을 정렬한다
  • O=D는 내림차순으로 목록을 정렬한다
  • F=0은 (FancyIndexed가 아닌) 간단한 목록 형식이다
  • F=1은 FancyIndexed 목록 형식이다
  • F=2는 HTMLTable FancyIndexed 목록 형식이다
  • V=0은 버전 순으로 정렬하지 않는다
  • V=1은 버전 순으로 정렬한다
  • P=pattern은 주어진 pattern에 해당하는 파일만을 목록으로 만든다

'P'attern 아규먼트는 일반적인 IndexIgnore 지시어를 처리한 후에 검사하기때문에, 목록은 다른 autoindex 조건을 따름을 주의하라. mod_autoindex의 요청 아규먼트를 읽어들일때 알 수 없는 옵션을 발견하면 더 이상 읽지않는다. 요청 아규먼트는 위의 표에 따라 만들어야 한다.

header.html 파일에 사용할 수 있는 아래 간단한 예제는 이 옵션들을 설명한다. submit 버턴의 알 수 없는 "X" 아규먼트는 mod_autoindex가 X=Go 전까지 모든 아규먼트를 읽어들임을 확인하기위해 마지막에 사용했다.

<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] ...
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_autoindex

AddAlt는 FancyIndexing에서 파일에 대한 아이콘대신 보일 글을 지정한다. File에는 설명할 파일의 파일 확장자, 파일명 일부, 와일드카드 표현, 전체 파일명을 사용할 수 있다. String에 공백이 들어간다면 따옴표(" 혹은 ')로 묶어야 한다. 클라이언트가 이미지를 볼 수 없거나, 이미지를 읽지않거나, 아이콘을 못 얻은 경우 이 추가 글이 보이게 된다.

예제

AddAlt "PDF file" *.pdf
AddAlt Compressed *.gz *.zip *.Z

AddAltByEncoding 지시어

설명: | MIME-encoding으로 선택한 아이콘대신 사용할 파일 설명글
문법: | AddAltByEncoding string MIME-encoding [MIME-encoding] ...
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_autoindex

AddAltByEncoding은 FancyIndexing에서 파일에 대한 아이콘대신 보일 글을 지정한다. MIME-encoding은 x-compress와 같은 유효한 content-encoding이다. String에 공백이 들어간다면 따옴표(" 혹은 ')로 묶어야 한다. 클라이언트가 이미지를 볼 수 없거나, 이미지를 읽지않거나, 아이콘을 못 얻은 경우 이 추가 글이 보이게 된다.

예제

AddAltByEncoding gzip x-gzip

AddAltByType 지시어

설명: | MIME content-type으로 선택한 아이콘대신 사용할 파일 설명글
문법: | AddAltByType string MIME-type [MIME-type] ...
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_autoindex

AddAltByType은 FancyIndexing에서 파일에 대한 아이콘대신 보일 글을 지정한다. MIME-type은 text/html과 같은 유효한 content-type이다. String에 공백이 들어간다면 따옴표(" 혹은 ')로 묶어야 한다. 클라이언트가 이미지를 볼 수 없거나, 이미지를 읽지않거나, 아이콘을 못 얻은 경우 이 추가 글이 보이게 된다.

예제

AddAltByType 'plain text' text/plain

AddDescription 지시어

설명: | 파일에 대한 설명
문법: | AddDescription string file [file] ...
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | 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으로 지정한 설명글에 태그나 character entity(역주; &lt;, &amp; 등을 지칭)같은 HTML을 사용할 수 있다. 그러나 폭때문에 태그가 있는 부분이 짤리게되면 (예를 들어 굵은체 부분 끝이 짤리면) 나머지 디렉토리 목록에 영향을 줄 수 있다.

AddIcon 지시어

설명: | 이름으로 선택한 파일에 사용할 아이콘
문법: | AddIcon icon name [name] ...
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_autoindex

이 지시어는 FancyIndexing에서 name으로 끝나는 파일 옆에 보여줄 아이콘을 지정한다. Icon은 아이콘의 (%-escaped) 상대 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 content-encoding으로 선택한 파일에 사용할 아이콘
문법: | AddIconByEncoding icon MIME-encoding [MIME-encoding] ...
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_autoindex

이 지시어는 FancyIndexing에서 파일 옆에 보여줄 아이콘을 지정한다. Icon은 아이콘의 (%-escaped) 상대 URL 혹은 (alttext,url) 형식이다. 여기서 alttext는 그림을 보여줄 수 없는 브라우저가 아이콘대신 사용할 문구이다.

MIME-encoding는 content-encoding에 해당하는 와일드카드 표현이다.

예제

AddIconByEncoding /icons/compress.xbm x-compress

AddIconByType 지시어

설명: | MIME content-type으로 선택한 파일에 사용할 아이콘
문법: | AddIconByType icon MIME-type [MIME-type] ...
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_autoindex

이 지시어는 FancyIndexing에서 MIME-type의 파일 옆에 보여줄 아이콘을 지정한다. Icon은 아이콘의 (%-escaped) 상대 URL 혹은 (alttext,url) 형식이다. 여기서 alttext는 그림을 보여줄 수 없는 브라우저가 아이콘대신 사용할 문구이다.

MIME-type은 mime type에 해당하는 와일드카드 표현이다.

예제

AddIconByType (IMG,/icons/image.xbm) image/*

DefaultIcon 지시어

설명: | 특정 아이콘을 설정하지않은 파일에 사용할 아이콘
문법: | DefaultIcon url-path
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_autoindex

DefaultIcon 지시어는 FancyIndexing에서 특정 아이콘을 설정하지않은 파일 옆에 나올 아이콘이다. Icon은 아이콘의 (%-escaped) 상대 URL이다.

예제

DefaultIcon /icon/unknown.xbm

HeaderName 지시어

설명: | 파일목록 위에 삽입할 파일의 이름
문법: | HeaderName filename
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_autoindex

HeaderName 지시어는 파일목록 앞에 삽입할 파일의 이름을 지정한다. Filename은 삽입할 파일명이다.

예제

HeaderName HEADER.html

현재 HeaderName과 ReadmeName 둘 모두 Filename을 접근하려는 디렉토리의 상대 URI 경로로 받아들인다. Filename이 슬래쉬로 시작하면 DocumentRoot에 상대적인 경로로 받아들인다.

예제

HeaderName /include/HEADER.html

Filename에는 major content type이 text/*인 (예를 들어, text/html, text/plain, 등) 문서를 사용해야 한다. 즉, 스크립트의 (출력이 아닌) 실제 파일 type을 다음과 같이 text/html로 지정한다면 filename으로 CGI 스크립트를 지정할 수도 있다:

AddType text/html .cgi

Options MultiViews을 사용하면 내용협상을 한다. filename이 (CGI 스크립트가 아닌) 고정된 text/html 문서이고 options Includes나 IncludesNOEXEC 중 하나를 사용한다면 파일을 server-side includes로 처리한다. (mod_include 문서 참고)

HeaderName으로 지정한 파일에 (<html>, <head>, 등) HTML 문서 시작부분이 포함되있다면 IndexOptions +SuppressHTMLPreamble을 사용하여 이 부분을 추가하지않는 것이 좋다.

IndexIgnore 지시어

설명: | 디렉토리 목록에서 숨길 파일목록을 추가한다
문법: | IndexIgnore file [file] ...
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_autoindex

IndexIgnore 지시어는 디렉토리 목록에서 감출 파일목록을 추가한다. File에는 감출 파일의 확장자, 파일명 일부, 화일드카드 표현, 전체 파일명을 사용할 수 있다. 여러 IndexIgnore 지시어를 사용하면 기존의 감출 파일목록을 대체하지않고 목록에 지정한 파일들을 추가한다. 기본적으로 목록은 .을 (현재 디렉토리) 포함한다.

IndexIgnore README .htaccess *~

IndexOptions 지시어

설명: | 디렉토리 목록의 여러 설정들
문법: | IndexOptions [+|-]option [[+|-]option] ...
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_autoindex

IndexOptions 지시어는 디렉토리 목록을 설정한다. Option은 다음 중 하나이다

DescriptionWidth=[n | *] (아파치 2.0.23 이후)
DescriptionWidth 키워드를 사용하여 문자단위로 설명열의 폭을 지정할 수 있다.
-DescriptionWidth를 지정하면 (혹은 아무것도 지정하지않으면) mod_autoindex가 최적의 폭을 계산한다.
DescriptionWidth=n은 열의 폭을 n 바이트로 고정한다.
DescriptionWidth=*은 열의 폭을 가장 긴 설명글을 담을 수 있는만큼 늘린다.
설정이 짤릴 수 있는 문제는 AddDescription 절을 참고하라.
FancyIndexing
디렉토리의 fancy 목록을 만든다.
FoldersFirst (아파치 2.0.23 이후)
이 옵션을 사용하면 하위디렉토리 목록이 항상 먼저 나오고, 디렉토리에 있는 일반 파일이 뒤에 나온다. 기본적으로 목록은 파일과 하위디렉토리로 나뉘고, 따로 각각의 순서를 정리하여 하위디렉토리들을 먼저 보인다. 예를 들어, 이름 역순으로 정렬하고 FoldersFirst를 사용한다면 하위디렉토리 Zed가 하위디렉토리 Beta 앞에 나오고, 하위디렉토리 Beta는 일반 파일 Gamma와 Alpha 앞에 나온다. 이 옵션은 FancyIndexing을 함께 사용할때만 효과가 있다.
HTMLTable (실험적, 아파치 2.0.23 이후)
이 실험적인 FancyIndexing 옵션은 간단한 HTML 표로 fancy 디렉토리 목록을 만든다. 이 옵션은 오래된 브라우저를 혼란스럽게 할 수 있음을 주의하라. 이 옵션은 WinNT나 다른 utf-8 사용 플래폼에서 파일명이나 설명문의 읽기 순서(왼쪽에서 오른쪽 혹은 오른쪽에서 왼쪽으로)가 다를때 특별히 유용하다.
IconsAreLinks
fancy 목록에서 파일명 링크에 아이콘을 포함한다.
IconHeight[=pixels]
이 옵션을 IconWidth와 같이 사용하면 서버는 파일 아이콘의 img 태그에 height와 width 속성을 포함한다. 그러면 브라우저는 모든 이미지를 받지않은 상황에서도 페이지 구성을 미리 계산할 수 있다. 옵션에 값을 주지않으면 아파치가 제공하는 아이콘의 표준 높이를 사용한다.
IconWidth[=pixels]
이 옵션을 IconHeight와 같이 사용하면 서버는 파일 아이콘의 img 태그에 height와 width 속성을 포함한다. 그러면 브라우저는 모든 이미지를 박지않은 상황에서도 페이지 구성을 미리 계산할 수 있다. 옵션에 값을 주지않으면 아파치가 제공하는 아이콘의 표준 폭을 사용한다.
IgnoreCase
이 옵션을 사용하면 대소문자 구별하지않고 이름을 정렬한다. 예를 들어, 이름으로 오름차순이고 IgnoreCase를 사용하면 파일 Zeta는 파일 alfa 뒤에 나온다 (주의: 파일 GAMMA는 항상 파일 gamma 앞에 나온다).
IgnoreClient
이 옵션을 사용하면 mod_autoindex는 순서를 포함하여 클라이언트가 보내는 모든 질의변수를 무시한다. (SuppressColumnSorting을 가정한다.)
NameWidth=[n | *]
NameWidth 키워드는 바이트단위로 파일명 열의 폭을 지정한다.
-NameWidth을 지정하면 (혹은 아무것도 지정하지않으면) mod_autoindex가 최적의 폭을 계산한다.
NameWidth=n는 열의 폭을 n 바이트로 고정한다.
NameWidth=*은 열의 폭을 필요한만큼 늘린다.
ScanHTMLTitles
fancy 목록에서 HTML 문서의 title을 뽑는다. 파일에 AddDescription로 지정한 설명이 없다면 웹서버는 문서의 title 요소값을 읽어들인다. 이 작업은 CPU와 디스크를 많이 사용한다.
SuppressColumnSorting
이 옵션을 사용하면 아파치는 FancyIndexed 디렉토리 목록에서 열 이름을 순서를 바꾸는 링크로 만들지 않는다. 보통은 열 이름을 링크로 만들어서, 열 이름을 선택하면 그 열에 있는 값순서로 디렉토리 목록을 만든다. 아파치 2.0.23 이전에는 순서 아규먼트도 읽지 않았다. 아파치 2.0.23에서는 IndexOptions IgnoreClient를 사용하여 순서 아규먼트를 읽지 않는다.
SuppressDescription
fancy 목록에서 파일 설명을 포함하지 않는다. 기본적으로 어떤 파일 설명도 정의되있지않고, 이 옵션을 사용하면 23 문자 공간을 다른 용도로 사용한다. 파일 설명을 지정하는 방법은 AddDescription을 참고하라. 설명열의 크기를 지정하는 DescriptionWidth 옵션도 참고하라.
SuppressHTMLPreamble
디렉토리에 HeaderName 지시어로 지정한 파일이 있는 경우 모듈은 보통 표준 HTML 시작부분 (<html>, <head>, et cetera) 뒤에 파일 내용을 첨가한다. 그러나 SuppressHTMLPreamble 옵션을 사용하면 처음부터 header 파일 내용을 포함한다. 이 경우 header 파일에는 적절한 HTML 명령이 있어야 한다. header 파일이 없다면 일반적인 시작부분이 만들어진다.
SuppressIcon (아파치 2.0.23 이후)
fancy 목록에서 아이콘을 뺀다. SuppressIcon과 SuppressRules를 같이 사용하면, (FancyIndexed 목록이 사용한) pre 안에 img와 hr 요소 사용을 금지한 마지막 표준인 HTML 3.2에 알맞은 출력이 된다.
SuppressLastModified
fancy 목록에서 마지막 수정일을 표시하지 않는다.
SuppressRules (아파치 2.0.23 이후)
디렉토리 목록에서 수평줄을 (hr 요소) 사용하지 않는다. SuppressIcon과 SuppressRules를 같이 사용하면, (FancyIndexed 목록이 사용한) pre 안에 img와 hr 요소 사용을 금지한 마지막 표준인 HTML 3.2에 알맞은 출력이 된다.
SuppressSize
fancy 목록에서 파일크기를 표시하지 않는다.
TrackModified (아파치 2.0.23 이후)
디렉토리 목록의 HTTP 헤더에 Last-Modified와 ETag 값을 포함한다. 이 옵션은 운영체제와 파일시스템에서 적절한 stat() 결과를 얻을 수 있을때만 유효하다. 유닉스 시스템과 OS2의 JFS, Win32의 NTFS에서는 가능하다. 예를 들어, OS2와 Win32의 FAT은 불가능하다. 이 기능을 사용하면 클라이언트나 프록시는 HEAD 요청을 사용하여 파일목록의 변화를 추적할 수 있다. 어떤 운영체제는 새로운 파일과 삭제한 파일을 올바로 추적하지만, 디렉토리에 있는 파일의 크기나 날짜 변화를 추적하지 못함을 주의하라. 모든 유닉스 플래폼에서 기존 파일의 크기나 날짜 변화시 Last-Modified 헤더가 바뀌지않는다. 이런 변화가 중요하다면 이 옵션을 사용하지 마라.
VersionSort (아파치 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

점진적인 IndexOptions

아파치 1.3.3에서 IndexOptions 지시어 처리방식이 크게 변화되었다. 특별히:

  • 이제 한 디렉토리에 대한 여러 IndexOptions 지시어들을 서로 결합한다. 다음의 결과는:

    <Directory /foo> IndexOptions HTMLTable
    IndexOptions SuppressColumnsorting     </Directory>

    다음과 같다

    IndexOptions HTMLTable SuppressColumnsorting

  • (예를 들어, 키워드 앞에 +나 -를 붙이는) 점진적인 문법이 추가되었다.

키워드 앞에 '+'나 '-'가 붙을때마다 해당 키워드가 현재 (상위 디렉토리에서 상속되었을) IndexOptions 설정에 반영된다. 그러나 앞에 아무것도 없는 키워드를 만나면 아직까지 상속되거나 점진적으로 변경된 설정을 모두 지운다. 다음 예제를 살펴보자:

IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing
IndexOptions +SuppressSize

앞에 아무것도 없는 FancyIndexing이 이전의 점진적인 설정을 지워버렸지만 설정이 다시 추가되여 결과는 IndexOptions FancyIndexing +SuppressSize와 같다.

특정 디렉토리에 대해 무조건적인 IndexOptions를 설정하려면 키워드 앞에 +나 -를 사용하지말고 상속된 설정을 지운다.

IndexOrderDefault 지시어

설명: | 디렉토리 목록의 기본 순서를 설정한다
문법: | IndexOrderDefault Ascending|Descending Name|Date|Size|Description
기본값: | IndexOrderDefault Ascending Name
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_autoindex

IndexOrderDefault 지시어는 FancyIndexing 목록 옵션과 함께 사용한다. 기본적으로 fancyindexed 디렉토리 목록은 파일명 오름차순이다. IndexOrderDefault는 이 초기 순서를 변경할 수 있다.

IndexOrderDefault는 두 아규먼트를 받는다. 첫번째는 순서의 방향을 지시하는 Ascending (오른차순) 이나 Descending (내림차순) 중 하나다. 두번째 아규먼트는 일차 순서를 나타내는 키워드 Name, Date, Size, Description 중 하나다. 이차 순서는 항상 파일명 오름차순이다.

이 지시어와 SuppressColumnSorting 목록 옵션을 같이 사용하면 특정 순서로만 디렉토리 목록을 만든다. 이 경우 클라이언트는 다른 순서로 디렉토리 목록을 요청하지 못한다.

ReadmeName 지시어

설명: | 파일목록 마지막에 삽입할 파일의 이름
문법: | ReadmeName filename
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_autoindex

ReadmeName 지시어는 파일목록 끝에 삽입할 파일의 이름을 지정한다. Filename은 포함할 파일명이고, 목록을 만들려는 위치의 상대경로로 받아들인다. Filename이 슬래쉬로 시작하면 DocumentRoot에 상대경로로 받아들인다.

예제

ReadmeName FOOTER.html

예제 2

ReadmeName /include/FOOTER.html

이 동작을 자세히 설명한 HeaderName도 참고하라.


mod_cache - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_cache

설명: | Content cache keyed to URIs.
상태: | Experimental
모듈명: | cache_module
소스파일: | mod_cache.c

요약

이 모듈은 실험적인 상태이다. 문서는 아직 작업중이다...

mod_cache는 같은 컴퓨터에 있는 내용이나 프록시된 내용을 캐쉬할 수 있는 RFC 2616 호환 HTTP 내용캐쉬를 구현한다. mod_cache를 사용하려면 저장관리모듈(storage management module)이 필요하다. 기본 아파치 배포본에는 두가지 저장관리모듈이 있다:

mod_disk_cache
는 디스크기반 저장관리자를 구현한다.
mod_mem_cache
는 메모리기반 저장관리자를 구현한다. mod_mem_cache는 파일기술자를 캐쉬하거나 힙(heap) 공간에 객체를 캐쉬하는 두가지 방식중 한가지 방법으로 동작하도록 설정할 수 있다. mod_mem_cache는 자신이 생성한 내용을 캐쉬하거나, (역프록시(reverse proxy)로 알려진) ProxyPass를 사용하여 mod_proxy를 위해 뒷단 서버내용을 캐쉬할 수 있다.

내용을 URI를 토대로 만든 키로 캐쉬에 저장하고 가져온다. 접근보호가 된 내용은 캐쉬하지않는다.

관련된 모듈과 지시어

관련된 모듈 관련된 지시어
  • mod_disk_cache
  • mod_mem_cache
  • CacheRoot
  • CacheSize
  • CacheGcInterval
  • CacheDirLevels
  • CacheDirLength
  • CacheExpiryCheck
  • CacheMinFileSize
  • CacheMaxFileSize
  • CacheTimeMargin
  • CacheGcDaily
  • CacheGcUnused
  • CacheGcClean
  • CacheGcMemUsage
  • MCacheSize
  • MCacheMaxObjectCount
  • MCacheMinObjectSize
  • MCacheMaxObjectSize
  • MCacheRemovalAlgorithm
  • MCacheMaxStreamingBuffer

설정예

Sample httpd.conf

#
# 예제 캐쉬 설정
#
LoadModule cache_module modules/mod_cache.so

<IfModule mod_cache.c>
#LoadModule disk_cache_module modules/mod_disk_cache.so
<IfModule mod_disk_cache.c>
CacheRoot c:/cacheroot
CacheSize 256
CacheEnable disk /
CacheDirLevels 5
CacheDirLength 3
 </IfModule>

LoadModule mem_cache_module modules/mod_mem_cache.so
<IfModule mod_mem_cache.c>
CacheEnable mem /
MCacheSize 4096
MCacheMaxObjectCount 100
MCacheMinObjectSize 1
MCacheMaxObjectSize 2048
 </IfModule>
 </IfModule>

CacheDefaultExpire 지시어

설명: | 만기시간을 지정하지않은 문서를 캐쉬할 기본 기간.
문법: | CacheDefaultExpire seconds
기본값: | CacheDefaultExpire 3600 (one hour)
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_cache

CacheDefaultExpire 지시어는 문서의 만기시간과 최근수정시간이 없는 경우 문서를 캐쉬할 초단위 기본 시간을 지정한다. CacheMaxExpire로 지정한 값이 이 설정을 무시하지 않는다.

CacheDefaultExpire 86400

CacheDisable 지시어

설명: | 특정 URL을 캐쉬하지 않는다
문법: | CacheDisable url-string
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_cache

CacheDisable 지시어를 사용하면 mod_cache가 url-string 이하의 url들을 캐쉬하지 않는다.

예제

CacheDisable /local_files

CacheEnable 지시어

설명: | 지정한 저장관리자를 사용하여 지정한 URL을 캐쉬한다
문법: | CacheEnable cache_type url-string
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_cache

CacheEnable 지시어를 사용하면 mod_cache가 url-string 이하 url들을 캐쉬한다. 캐쉬 저장관리자는 cache_type 아규먼트로 지정한다. cache_type mem은 mod_mem_cache가 구현하는 메모리기반 저장관리자를 사용한다. cache_type disk는 mod_disk_cache가 구현하는 디스크기반 저장관리자를 사용한다. cache_type fd는 mod_mem_cache가 구현하는 파일기술자 캐쉬를 사용한다.

(아래 예와 같이) URL 공간이 다른 CacheEnable 지시어와 겹치면 실제로 한 저장관리자가 요청을 처리할때까지 두 저장관리자를 모두 실행한다. 설정파일에서 CacheEnable 지시어의 순서대로 저장관리자가 실행된다.

CacheEnable mem /manual
CacheEnable fd /images
CacheEnable disk /

CacheForceCompletion 지시어

설명: | 요청이 취소되더라도 서버가 파일을 계속 캐쉬하기위해 필요한 문서의 서비스률.
문법: | CacheForceCompletion Percentage
기본값: | CacheForceCompletion 60
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_cache

보통 응답을 캐쉬하고 클라이언트로 보내는 도중에 요청이 취소되면 응답 처리를 중단되고 캐쉬 항목을 지운다. CacheForceCompletion 지시어는 요청이 취소되더라도 문서를 계속 캐쉬할 정도를 지정한다.

정도는 백분율로 나타내며 1과 100 사이의 값이다. 0 값을 지정하면 기본값을 사용한다. 100은 내용을 모두 서비스한 문서만을 캐쉬한다. 60과 90 사이의 값을 추천한다.

CacheForceCompletion 80

주의:

이 기능은 현재 구현되지 않았다.

CacheIgnoreCacheControl 지시어

설명: | 클라이언트가 캐쉬하지않는 내용을 요청함을 무시한다.
문법: | CacheIgnoreCacheControl On|Off
기본값: | CacheIgnoreCacheControl Off
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_cache

보통 no-cache나 no-store 헤더값을 가진 문서는 캐쉬에 저장하지않는다. CacheIgnoreCacheControl 지시어는 이런 행동을 변경한다. CacheIgnoreCacheControl On을 사용하면 서버는 문서에 no-cache나 no-store 헤더값이 있어도 문서를 캐쉬한다. 인증이 필요한 문서는 절대로 캐쉬하지 않는다.

CacheIgnoreCacheControl On

CacheIgnoreNoLastMod 지시어

설명: | 응답에 Last Modified 헤더가 없다는 사실을 무시한다.
문법: | CacheIgnoreNoLastMod On|Off
기본값: | CacheIgnoreNoLastMod Off
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_cache

보통 최근수정일이 없는 문서는 캐쉬하지 않는다. 어떤 경우 최근수정일을 (예를 들어 mod_include 처리중에) 빼거나 처음부터 없었을 수가 있다. CacheIgnoreNoLastMod 지시어는 최근수정일이 없는 문서도 반드시 캐쉬하도록 만든다. 문서에 최근수정일과 만기시간이 없는 경우 CacheDefaultExpire 지시어로 지정한 값을 만기시간으로 사용한다.

CacheIgnoreNoLastMod On

CacheLastModifiedFactor 지시어

설명: | LastModified 시간으로 만기시간을 계산하는데 사용하는 계수.
문법: | CacheLastModifiedFactor float
기본값: | CacheLastModifiedFactor 0.1
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_cache

문서에 만기시간은 없지만 최근수정일이 있는 경우 최근수정일 이후 지난 시간으로 만기시간을 계산한다. CacheLastModifiedFactor 지시어는 만기시간을 계산하는 다음 공식에서 사용할 factor를 지정한다: expiry-period = time-since-last-modified-date * factor expiry-date = current-date + expiry-period 예를 들어, 문서가 10 시간 전에 마지막으로 수정되었고 factor가 0.1이라면 만기기간은 10*01 = 1 시간이 된다. 현재 시간이 3:00pm이라면 만기시간은 3:00pm + 1시간 = 4:00pm이다. 만기기간이 CacheMaxExpire 보다 길다면 CacheMaxExpire를 사용한다.

CacheLastModifiedFactor 0.5

CacheMaxExpire 지시어

설명: | 문서를 캐쉬하는 초단위 최대시간
문법: | CacheMaxExpire seconds
기본값: | CacheMaxExpire 86400 (하루)
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_cache

CacheMaxExpire 지시어는 실제 서버를 검사하지않고 캐쉬가능한 HTTP 문서를 유지할 수 있는 초단위 최대시간을 지정한다. 즉, 문서는 최대한 이 설정값만큼 오래되었다. 문서가 만기시간을 지정하여도 이 최대값을 지킨다.

CacheMaxExpire 604800


mod_cern_meta - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_cern_meta

설명: | CERN 웹서버 메타파일 지원
상태: | Extension
모듈명: | cern_meta_module
소스파일: | mod_cern_meta.c

요약

CERN 웹서버 메타파일을 흉내낸다. 메타파일은 접근하는 파일에 대해 일반적인 헤더외에 추가로 출력할 HTTP 헤더를 담고있다. 아파치 .asis 파일과 비슷하고, Expires: 헤더를 수정하거나 다른 신기한 일들을 할 수 있다. 메타 정보를 다루는 방법은 다양하지만, 이미 이 모듈을 사용하는 많은 CERN 사용자들을 위해 이 방법을 선택했다.

더 자세한 정보는 CERN metafile semantics를 참고하라.

참고

  • mod_headers
  • mod_asis

MetaDir 지시어

설명: | CERN 메타정보를 찾을 디렉토리 이름
문법: | MetaDir directory
기본값: | MetaDir .web
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Extension
모듈: | mod_cern_meta

아파치가 메타정보 파일을 찾을 디렉토리명을 지정한다. 디렉토리는 보통 접근할 파일이 있는 디렉토리의 '감춰진' 하위디렉토리다. "."으로 지정하면 같은 디렉토리에서 파일을 찾는다:

MetaDir .

아니면 파일이 있는 하위디렉토리를 지정한다:

MetaDir .meta

MetaFiles 지시어

설명: | CERN 메타파일을 처리한다
문법: | MetaFiles on|off
기본값: | MetaFiles off
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Extension
모듈: | mod_cern_meta

디렉토리별로 메타파일 처리여부를 결정한다.

MetaSuffix 지시어

설명: | CERN 메타정보를 저장하는 파일의 접미사
문법: | MetaSuffix suffix
기본값: | MetaSuffix .meta
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Extension
모듈: | mod_cern_meta

메타정보를 저장하는 파일의 접미사를 지정한다. 예를 들어, 두 지시어의 기본값을 사용할 경우 DOCUMENT_ROOT/somedir/index.html을 요청하면 DOCUMENT_ROOT/somedir/.web/index.html.meta의 내용을 참고하여 MIME 헤더 정보를 추가한다.

예제:

MetaSuffix .meta


mod_cgi - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_cgi

설명: | CGI 스크립트 실행
상태: | Base
모듈명: | cgi_module
소스파일: | mod_cgi.c

요약

서버는 mime type이 application/x-httpd-cgi이거나 (아파치 1.1 이후) 핸들러가 cgi-script인 모든 파일을 CGI 스크립트로 인식하여, 실행하고, 그 결과를 클라이언트에게 보낸다. 파일이 AddType 지시어로 지정한 확장자를 가지거나, ScriptAlias 디렉토리 안에 있으면 CGI로 처리된다.

서버는 CGI 스크립트를 부를때 DOCUMENT_ROOT라는 환경변수를 추가한다. 이 변수는 DocumentRoot 설정값을 가진다.

아파치에서 CGI 스크립트를 사용하는 방법에 대한 소개는 CGI로 동적내용 투토리얼을 참고하라.

유닉스에서 다중쓰레드 MPM을 사용한다면 이 모듈대신 mod_cgid 모듈을 사용해야 한다. 사용자 입장에서 이 두 모듈은 기본적으로 동일하다.

참고

  • AcceptPathInfo
  • Options
  • ScriptAlias
  • AddHandler
  • 다른 사용자 ID로 CGI 프로그램 실행하기
  • CGI 표준

CGI 환경변수

서버는 다음과 같은 방법으로 CGI 표준이 설명하는 CGI 환경변수를 설정한다:

PATH_INFO
이 변수는 AcceptPathInfo 지시어를 직접 off로 지정한 경우에만 설정한다. AcceptPathInfo가 없는 경우 서버는 기본적으로 경로 정보가 있는 요청에 대해 404 NOT FOUND 오류를 내지만, mod_cgi는 경로 정보를 (URI에서 스크립트 파일명 뒤에 나오는 /more/path/info) 받는다. AcceptPathInfo 지시어를 생략하면 mod_cgi 요청에 대해서 AcceptPathInfo를 On으로 설정한 것과 같다.
REMOTE_HOST
이 변수는 HostnameLookups가 on이고 (기본값은 off), 접속한 호스트 주소를 역DNS 검색하여 실제 호스트명을 찾은 경우에만 설정한다.
REMOTE_IDENT
이 변수는 IdentityCheck가 on이고, 접속한 호스트가 ident 프로토콜을 지원하는 경우에만 설정한다. 쉽게 이 값을 속일 수 있기때문에 이 변수의 내용을 믿으면 안되고, 클라이언트와 서버 사이에 프록시가 있다면 변수 내용이 완전히 무의미함을 주의하라.
REMOTE_USER
CGI 스크립트가 인증을 거쳐야하는 경우에만 설정한다.

CGI 디버깅

어디에서 잘못 실행되는지 스크립트의 출력을 (표준출력과 표준오류) 볼 수 없기때문에 CGI 스크립트는 전통적으로 디버깅하기 어려웠다. 아파치 1.2 이후에 추가된 지시어를 사용하면 발생한 오류를 자세히 로그에 남길 수 있다.

CGI 로그파일 형식

CGI 오류로그는 정상적으로 실행하지 못한 CGI를 기록한다. 오류가 발생한 CGI 스크립트는 로그에 여러 줄의 정보를 남긴다. 첫번째 두 줄은 항상 아래와 같은 형식이다:

%% [시간] 요청줄
%% HTTP-상태 CGI-스크립트-파일명

CGI 스크립트를 실행할 수 없는 오류인 경우 로그파일에 추가로 두 줄을 더 기록한다:

%%error
오류문

스크립트가 (보통 스크립트의 버그때문에) 잘못된 헤더 정보를 반환하는 경우, 다음 내용을 로그에 기록한다:

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

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_cgid

설명: | 외부 CGI 데몬을 사용하여 CGI 스크립트를 실행
상태: | Base
모듈명: | cgid_module
소스파일: | mod_cgid.c
지원: | 유닉스에서 쓰레드를 사용하는 MPMs 전용

요약

아래에서 설명하는 추가된 ScriptSock 지시어를 제외하고 mod_cgid는 mod_cgi와 비슷하게 동작한다. 아파치와 CGI에 대한 자세한 설명은 mod_cgi를 참고하라.

어떤 유닉스 운영체제의 경우 다중쓰레드 서버에서 프로세스를 포크(fork)하면 새로운 프로세스가 부모 프로세스의 모든 쓰레드를 복제해야 하므로 부담이 된다. CGI 실행마다 이런 부담을 주지 않기위해 mod_cgid는 CGI 스크립트를 실행하는 자식 프로세스를 포크하는 외부 데몬을 만든다. 주서버는 이 데몬과 유닉스소켓(unix domain socket)을 사용하여 통신한다.

컴파일할때 다중쓰레드 MPM을 선택하면 기본적으로 mod_cgi 대신 이 모듈을 사용한다. 사용자 입장에서 이 모듈의 설정과 동작은 mod_cgi와 동일하다. 유일한 차이점은 cgi 데몬과 통신을 위해 사용할 소켓의 이름을 설정하는 ScriptSock 지시어가 추가된 점이다.

참고

  • mod_cgi
  • 다른 사용자 ID로 CGI 프로그램 실행하기

ScriptSock 지시어

설명: | cgi 데몬과 통신을 위해 사용할 소켓의 이름
문법: | ScriptSock file-path
기본값: | ScriptSock logs/cgisock
사용장소: | 주서버설정, 가상호스트
상태: | Base
모듈: | mod_cgid

이 지시어는 CGI 데몬과 통신을 위해 사용할 소켓의 이름을 지정한다. 아파치를 시작한 사용자 (보통 root) 권한으로 소켓을 연다. CGI 스크립트와 통신의 보안을 위해 다른 사용자가 소켓이 있는 디렉토리에 쓰기권한을 가지지않는 것이 중요하다.

예제

ScriptSock /var/run/cgid.sock


mod_charset_lite - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_charset_lite

설명: | 문자집합 변환을 지정
상태: | Experimental
모듈명: | charset_lite_module
소스파일: | mod_charset_lite.c

요약

이 모듈은 실험적인 모듈이고, 주의있게 사용해야 한다. 원하는 동작을 하는지 mod_charset_lite 설정을 시험해봐라.

mod_charset_lite를 사용하여 문서 원본의 문자집합과 문서를 클라이언트로 보내기 전에 변환할 문자집합을 지정할 수 있다. mod_charset_lite는 직접 자료를 변환하지않고 대신 아파치에게 변환하라고 요청한다. mod_charset_lite는 EBCDIC과 ASCII 환경에서 사용할 수 있다. EBCDIC 환경에서 아파치는 보통 아파치 프로세스의 코드페이지에서 ISO-8859-1 문자집합으로 문서를 변환한다. mod_charset_lite를 사용하여 다른 변환을 지시할 수 있다. ASCII 환경에서 아파치는 기본적으로 변환을 하지 않기때문에, 어떤 변환을 위해서는 mod_charset_lite가 필요하다.

이 모듈은 러시아판 아파치의 mod_charset이 제공하는 설정의 일부를 제공한다.

일반적인 문제점

잘못된 문자집합 이름

mod_charset_lite를 사용하는 시스템의 ARP 번역기능이 CharsetSourceEnc와 CharsetDefault의 파라미터인 문자집합 이름을 처리할 수 있어야 한다. 문자집합 이름은 표준화되지 않았고, http 헤더에 사용하는 값과 항상 같지는 않다. 현재 APR은 iconv(3)만을 사용하기때문에, 다음과 같이 iconv(1) 프로그램을 사용하여 특정 문자집합 이름을 사용할 수 있는지 쉽게 알 수 있다:

iconv -f charsetsourceenc-value -t charsetdefault-value

내용과 변환규칙의 문자집합이 서로 다름

변환규칙이 상황에 맞지않으면 다음과 같은 여러 방식으로 변환이 실패할 수 있다:

  • 변환기능이 실패 반환코드를 반환하고 연결이 끊어질 수 있다.
  • 입력버퍼를 변환하지 못할때 출력버퍼에 대신 특별한 문자를 (예, 물음표) 적을 수 있다.

CharsetDefault 지시어

설명: | 변환할 문자집합
문법: | CharsetDefault charset
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | FileInfo
상태: | Experimental
모듈: | mod_charset_lite

CharsetDefault 지시어는 지시어를 사용한 위치에 있는 원본을 변환할 문자집합을 지정한다.

charset 아규먼트에는 APR이 지원하는 문자집합 이름을 사용해야 한다. 일반적으로 iconv가 지원하는 문자집합을 의미한다.

예제

<Directory /export/home/trawick/apacheinst/htdocs/convert>
CharsetSourceEnc UTF-16BE
CharsetDefault ISO-8859-1
 </Directory>

CharsetOptions 지시어

설명: | 문자집합 변환 기능을 설정
문법: | CharsetOptions option [option] ...
기본값: | CharsetOptions DebugLevel=0 NoImplicitAdd
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | FileInfo
상태: | Experimental
모듈: | mod_charset_lite

CharsetOptions 지시어는 mod_charset_lite의 기능을 설정한다. Option에는 아래 항목들을 사용할 수 있다

DebugLevel=n
DebugLevel 키워드는 mod_charset_lite가 기록하는 디버그문구의 수준을 설정한다. 기본적으로 어떤 것도 기록하지 않는다. 이는 DebugLevel=0과 같다. 높은 숫자를 사용할수록 더 많은 디버그문구를 기록하게되어 서버 성능이 떨어진다. 숫자값의 실제 의미는 mod_charset_lite.c 앞부분의 DBGLVL_ 상수 정의를 참고하라.
ImplicitAdd | NoImplicitAdd
ImplicitAdd 키워드는 내용을 변환할 문자집합을 지정하면 자동으로 mod_charset_lite를 필터에 추가한다. AddOutputFilter 지시어로 필터순서를 직접 지정한다면, NoImplicitAdd를 사용하여 mod_charset_lite가 자동으로 필터에 추가되지않도록 해야 한다.

CharsetSourceEnc 지시어

설명: | 파일 원본의 문자집합
문법: | CharsetSourceEnc charset
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | FileInfo
상태: | Experimental
모듈: | mod_charset_lite

CharsetSourceEnc 지시어는 지시어를 사용한 위치에 있는 파일들 원본의 문자집합을 지정한다.

charset 아규먼트에는 APR이 지원하는 문자집합 이름을 사용해야 한다. 일반적으로 iconv가 지원하는 문자집합을 의미한다.

예제

<Directory /export/home/trawick/apacheinst/htdocs/convert>
CharsetSourceEnc UTF-16BE
CharsetDefault ISO-8859-1
 </Directory>

Solaris 8의 iconv가 이 예제의 문자집합을 지원한다.


mod_dav - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_dav

설명: | Distributed Authoring and Versioning (WebDAV) 기능
상태: | Extension
모듈명: | dav_module
소스파일: | mod_dav.c

요약

이 모듈은 아파치에 WebDAV ('Web-based Distributed Authoring and Versioning') class 1과 class 2 기능을 추가한다. WebDAV는 원격 웹서버의 자원과 콜렉션(collection)을 (역주; 콜렉션은 파일시스템의 디렉토리와 같은 개념이다) 만들고, 옮기고, 복사하고, 지울 수 있도록 HTTP 프로토콜을 확장한 것이다.

참고

  • DavLockDB
  • LimitXMLRequestBody
  • WebDAV 정보

WebDAV 사용하기

mod_dav를 사용하려면 httpd.conf 파일에 아래과 같이 추가한다:

Dav On

그러면 mod_dav_fs 모듈이 구현하는 DAV 파일시스템 제공자(provider)를 사용한다. 그러므로 이 모듈도 서버에 같이 컴파일되있거나 LoadModule 지시어로 실행중에 읽어들여야 한다.

또, DAV 잠금(lock) 데이터베이스의 위치를 httpd.conf 파일의 전역 부분에 DavLockDB 지시어를 사용하여 지정해야 한다:

DavLockDB /usr/local/apache2/var/DavLock

아파치를 실행하는 User와 Group은 잠금 데이터베이스가 있는 디렉토리에 쓰기 권한을 가져야 한다.

DAV를 사용하는 위치에 접근을 제한하기위해 <Location> 지시어 안에 <Limit> 지시어를 사용할 수 있다. DAV 클라이언트가 한번의 요청에 보낼 수 있는 최대 바이트수를 제한하려면 LimitXMLRequestBody 지시어를 사용한다. "일반적인" LimitRequestBody 지시어는 DAV 요청과 관계없다.

전체 예제

DavLockDB /usr/local/apache2/var/DavLock

<Location /foo>
Dav On

AuthType Basic
AuthName DAV
AuthUserFile user.passwd

<LimitExcept GET OPTIONS>
require user admin
 </LimitExcept>
 </Location>

mod_dav는 Greg Stein이 만든 Apache 1.3용 mod_dav를 기반으로 만들었다. 모듈에 대한 더 자세한 정보는 그 사이트를 참고하라.

보안 문제

DAV를 사용하면 원격 클라이언트가 서버의 파일을 조작할 수 있기때문에, mod_dav를 사용하기 전에 서버가 안전한지 특별히 관심을 가져야 한다.

서버에서 DAV가 가능한 위치는 인증으로 보호해야 한다. HTTP Basic Authentication는 추천하지 않는다. 최소한 mod_auth_digest 모듈이 제공하는 HTTP Digest Authentication을 사용해야 한다. 거의 모든 WebDAV 클라이언트는 이 인증 방식을 지원한다. 아니면 SSL 연결에서 Basic Authentication을 사용할 수도 있다.

mod_dav가 파일을 조작하려면, 아파치를 실행하는 User와 Group은 해당 디렉토리와 파일에 쓰기 권한을 가져야 한다. 또, 새로 생성한 파일은 User와 Group이 소유하게 된다. 그래서 아무나 이 계정에 접근할 수 없도록 하라. DAV 저장소는 아파치만 접근할 수 있다고 가정한다. 아파치를 통하지않고 (예를 들어 FTP나 파일시스템 도구를 사용하여) 파일을 수정함을 허용하면 안된다.

mod_dav는 여러 서비스거부 공격의 대상이 될 수 있다. LimitXMLRequestBody 지시어를 사용하여 큰 DAV 요청을 읽을때 메모리량을 제한할 수 있다. DavDepthInfinity 지시어를 사용하여 많은 메모리를 소모하기위한 매우 큰 저장소의 PROPFIND 요청을 막을 수 있다. 단순히 클라이언트가 여러 큰 파일들로 디스크공간을 채우는 서비스거부 공격도 가능하다. 아파치에서 이를 막을 직접적인 방법은 없다. 그러므로 신뢰하지않는 사용자에게 DAV 접근을 허용하지 않도록하라.

복잡한 설정

일반적인 질문중 하나는 (PHP 스크립트, CGI 스크립트 등) 동적파일 작업을 위해 mod_dav를 사용하는 방법이다. 이는 GET 요청이 파일 내용을 다운로드하지 않고 항상 스크립트를 실행하므로 어렵다. 해결방법중 하나는 내용에 두개의 URL을 대응하는 것이다. 한 URL은 스크립트를 실행하고, 다른 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
사용장소: | directory
상태: | Extension
모듈: | mod_dav

지정한 위치에서 WebDAV HTTP 메써드를 사용하려면 Dav 지시어를 사용한다:

<Location /foo>
Dav On
 </Location>

On 값은 실제로 mod_dav_fs 모듈이 제공하는 기본 제공자인 filesystem의 별칭이다. 어떤 위치에서 DAV를 시작하면 하위공간에서 DAV를 사용안하도록 설정할 수 없음을 주의하라. 완전한 설정예는 위의 절을 참고하라.

서버를 안전하게 구성할때까지 WebDAV을 사용하지 마라. 그렇지 않으면 누구라도 서버를 통해 파일을 분배할 수 있게 된다.

DavDepthInfinity 지시어

설명: | PROPFIND의 Depth: Infinity 요청을 허가한다
문법: | DavDepthInfinity on|off
기본값: | DavDepthInfinity off
사용장소: | 주서버설정, 가상호스트, directory
상태: | Extension
모듈: | mod_dav

DavDepthInfinity 지시어를 사용하면 'Depth: Infinity' 헤더를 가진 PROPFIND 요청을 허가한다. 이런 요청을 사용하여 서비스거부 공격이 가능하기 때문에 기본적으로 허용하지 않는다.

DavMinTimeout 지시어

설명: | 서버가 DAV 자원에 대해 유지할 잠금의 최소시간
문법: | DavMinTimeout seconds
기본값: | DavMinTimeout 0
사용장소: | 주서버설정, 가상호스트, directory
상태: | Extension
모듈: | mod_dav

클라이언트가 DAV 자원에 잠금(lock)을 요청할때 서버가 알아서 잠금을 제거할 수 있는 시간을 같이 알려줄 수 있다. 이 값은 단지 요청일뿐이며, 서버는 클라이언트가 요청한 값을 무시하고 클라이언트에게 임의의 시간을 알려줄 수 있다.

DavMinTimeout 지시어는 클라이언트에게 보낼 최소 잠금 시간을 (초단위) 지정한다. Microsoft Web Folders는 기본값으로 120 초를 사용한다. DavMinTimeout에 (600 초와 같이) 더 높은 값을 사용하면 클라이언트가 네트웍 지연때문에 잠금을 잃게되는 경우를 줄일 수 있다.

예제

<Location /MSWord>
DavMinTimeout 600
 </Location>


mod_dav_fs - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_dav_fs

설명: | mod_dav을 위한 파일시스템 제공자
상태: | Extension
모듈명: | dav_fs_module
소스파일: | mod_dav_fs.c

요약

이 모듈은 mod_dav 서비스에 필요하다. mod_dav를 지원하는 모듈로 서버의 파일시스템에 있는 자원을 접근할 수 있도록 한다. 이 제공자(provider)의 정식명칭은 filesystem이다. Dav 지시어를 지정하여 mod_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 var/DavLock

아파치를 실행하는 User와 Group은 잠금 데이터베이스가 있는 디렉토리에 쓰기 권한을 가져야 한다. 보안상 이유로 기존 디렉토리의 권한을 바꾸기보다는 잠금 데이터베이스용 디렉토리를 만들어야 한다. 위의 경우 아파치는 ServerRoot 아래 var/ 디렉토리에 서버가 선택한 확장명을 가진 DavLock 파일을 만든다.


mod_deflate - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_deflate

설명: | 내용을 클라이언트로 보내기 전에 압축한다
상태: | Extension
모듈명: | deflate_module
소스파일: | mod_deflate.c

요약

mod_deflate 모듈은 서버의 출력을 네트웍으로 클라이언트에 보내기 전에 압축하는 DEFLATE 출력필터를 제공한다.

참고

  • 필터

권장하는 설정

급한 사람을 위한 견본 설정이다. 그러나 시간을 가지고 아래 자세한 설명을 읽길 바란다!

일부 type만 압축

AddOutputFilterByType DEFLATE text/html text/plain text/xml

이미지를 제외한 모든 것을 압축

<Location />
# 필터를 추가한다
SetOutputFilter DEFLATE

# Netscape 4.x에 문제가 있다...
BrowserMatch ^Mozilla/4 gzip-only-text/html

# Netscape 4.06-4.08에 더 문제가 있다
BrowserMatch ^Mozilla/4\.0[678] no-gzip

# MSIE은 Netscape라고 자신을 알리지만, 문제가 없다
BrowserMatch \bMSIE !no-gzip !gzip-only-text/html

# 이미지를 압축하지 않는다
SetEnvIfNoCase Request_URI \
\.(?:gif|jpe?g|png)$ no-gzip dont-vary
# 프록시가 잘못된 내용을 전달하지않도록 한다
Header append Vary User-Agent env=!dont-vary
 </Location>

압축하기

출력 압축

DEFLATE 필터가 압축을 한다. 다음 지시어는 지시어가 있는 위치의 문서를 압축한다:

SetOutputFilter DEFLATE

모든 내용을 압축하면 처리하지 못하는 브라우저가 있기때문에 html 파일만을 압축하기위해 (아래 참고) gzip-only-text/html을 1로 설정할지도 모른다. 이를 1이 아닌 값으로 설정하면 무시한다.

보통 특별한 MIME type만 압축하려면 AddOutputFilterByType 지시어를 사용한다. 다음 설정은 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이 아닌 type의 압축을 처리하지 못한다. 버전 4.06, 4.07, 4.08은 html 파일 압축을 처리하는대도 문제가 있다. 그래서 우리는 이 경우 deflate 필터를 완전히 사용하지않는다.

세번째 BrowserMatch 지시어는 Microsoft Internet Explorer가 자신을 "Mozilla/4"로 알리지만 압축된 요청을 처리할 수 있기때문에 user agent 추측을 수정한다. User-Agent 헤더에서 "MSIE" (\b는 "단어 경계"를 뜻한다) 문자열을 발견하면 앞에서 설정한 제약을 푼다.

주의

DEFLATE 필터는 항상 PHP나 SSI와 같은 RESOURCE 필터 뒤에 들어간다. 또, 내부 하위요청(subrequest)에 영향을 주지 않는다.

입력 압축풀기

mod_deflate 모듈은 요청의 gzip 압축된 내용을 푸는 필터도 제공한다. 이 기능을 사용하려면 다음과 같이 SetInputFilter나 AddInputFilter를 사용하여 입력필터순서에 DEFLATE 필터를 추가해야한다:

<Location /dav-area>
SetInputFilter DEFLATE
 </Location>

요청에 Content-Encoding: gzip 헤더가 있다면 자동으로 압축된 내용을 푼다. gzip 요청을 할 수 있는 브라우저는 드물다. 그러나 어떤 WebDAV 클라이언트와 같은 특별한 프로그램은 요청 압축을 지원한다.

Content-Length에 대한 주의

요청 내용을 직접 살펴본다면, Content-Length 헤더를 믿지마라! Content-Length 헤더는 클라이언트가 보낸 내용의 길이이지, 압축을 푼 결과의 바이트수가 아니다.

프록시 서버 다루기

mod_deflate 모듈은 프록시가 자신이 캐쉬한 응답을 적절한 Accept-Encoding 요청 헤더를 보낸 클라이언트에게만 보내도록 Vary: Accept-Encoding HTTP 응답 헤더를 추가한다. 그래서 압축된 내용을 이해할 수 없는 클라이언트에 압축된 내용을 보내지않도록 한다.

예를 들어, 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's default
사용장소: | 주서버설정, 가상호스트
상태: | 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 지시어는 요청의 압축률을 로그에 기록하는 기호를 지정한다. 기호 이름은 지시어로 지정한 값이다. 통계를 위해 접근 로그에서 기호를 사용할 수 있다.

예제

DeflateFilterNote ratio

LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
CustomLog logs/deflate_log deflate

로그에서 더 정확한 값을 추출하려면 type 아규먼트로 기록할 자료를 선택한다. type는 다음중 하나이다:

Input
필터 입력스트림의 바이트수를 저장한다.
Output
필터 출력스트림의 바이트수를 저장한다..
Ratio
압축률을 (output/input * 100) 저장한다. type 아규먼트를 생략하면 사용하는 기본값이다.

그래서 이렇게 로그에 기록할 수 있다:

정밀한 로그

DeflateFilterNote Input instream
DeflateFilterNote Output outstream
DeflateFilterNote Ratio ratio

LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
CustomLog logs/deflate_log deflate

참고

  • mod_log_config

DeflateMemLevel 지시어

설명: | zlib이 압축할때 사용하는 메모리량
문법: | DeflateMemLevel value
기본값: | DeflateMemLevel 9
사용장소: | 주서버설정, 가상호스트
상태: | Extension
모듈: | mod_deflate

DeflateMemLevel 지시어는 zlib이 압축할때 얼마만큼 메모리를 사용할지 결정한다. (1과 9 사이의 값)

DeflateWindowSize 지시어

설명: | Zlib 압축 window size
문법: | DeflateWindowSize value
기본값: | DeflateWindowSize 15
사용장소: | 주서버설정, 가상호스트
상태: | Extension
모듈: | mod_deflate

DeflateWindowSize 지시어는 zlib 압축 window size를 (1과 15 사이의 값) 지정한다. 일반적으로 window size가 클수록 압축률이 증가한다.


mod_dir - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_dir

설명: | "마지막 슬래쉬" 리다이렉션을 제공하고 디렉토리 index 파일을 서비스한다
상태: | Base
모듈명: | dir_module
소스파일: | mod_dir.c

요약

디렉토리의 index는 다음 둘중 한가지 방법으로 제공된다:

  • 사용자가 작성한 보통 index.html이라는 파일. DirectoryIndex 지시어는 이 파일의 이름을 지정한다. mod_dir가 이 지시어를 제공한다.
  • 아니라면 서버가 만든 목록. mod_autoindex가 이 기능을 제공한다.

두 기능은 서로 별개로 원한다면 자동 index 생성을 완전히 없앨 (혹은 교체할) 수 있다.

dirname이 디렉토리라면 서버는 URL http://servername/foo/dirname 요청을 받으면 "마지막 슬래쉬" 리다이렉션을 보낸다. 디렉토리에는 마지막 슬래쉬가 필요하다. 그래서 mod_dir은 http://servername/foo/dirname/로 리다이렉션을 보낸다.

DirectoryIndex 지시어

설명: | 클라이언트가 디렉토리를 요청할때 찾아볼 자원 목록
문법: | DirectoryIndex local-url [local-url] ...
기본값: | DirectoryIndex index.html
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | Indexes
상태: | Base
모듈: | mod_dir

DirectoryIndex 지시어는 클라이언트가 디렉토리명 끝에 /를 붙여서 디렉토리의 index를 요청할때 찾아볼 자원 목록을 지정한다. Local-url은 요청한 디렉토리에 상대적인 문서의 (%로 인코딩된) URL이다. 보통은 디렉토리에 있는 파일명이다. 여러 URL을 지정할 수 있고, 이 경우 서버는 첫번째로 찾은 파일을 보낸다. 자원을 찾을 수 없고 Indexes 옵션을 설정하였다면 서버는 직접 디렉토리 목록을 만든다.

예제

DirectoryIndex index.html

이 경우 http://myserver/docs/를 요청할때 http://myserver/docs/index.html이 있으면 이를 보내고, 없다면 디렉토리 목록을 보낸다.

문서가 반드시 디렉토리에 상대적일 필요는 없다.

DirectoryIndex index.html index.txt /cgi-bin/index.pl

이 경우 디렉토리에 index.html이나 index.txt가 없으면 CGI 스크립트 /cgi-bin/index.pl을 실행한다.


mod_disk_cache - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_disk_cache

설명: | Content cache storage manager keyed to URIs
상태: | Experimental
모듈명: | disk_cache_module
소스파일: | mod_disk_cache.c

요약

이 모듈은 실험적인 상태이다. 문서는 아직 작업중이다...

mod_disk_cache는 디스크기반 저장관리자를 구현한다. 이 모듈은 기본적으로 mod_proxy와 같이 사용한다.

내용을 URI를 토대로 만든 키로 캐쉬에 저장하고 가져온다. 접근보호가 된 내용은 캐쉬하지않는다.

주의:

mod_disk_cache는 mod_cache가 필요하다.

CacheDirLength 지시어

설명: | 하위디렉토리명의 문자개수
문법: | CacheDirLength length
기본값: | CacheDirLength 2
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

CacheDirLength 지시어는 캐쉬 계층구조에서 각 하위디렉토리명의 문자수를 지정한다.

CacheDirLevels와 CacheDirLength를 곱하여 20 보다 크면 안된다.

CacheDirLength 4

CacheDirLevels 지시어

설명: | 캐쉬의 하위디렉토리 깊이.
문법: | CacheDirLevels levels
기본값: | CacheDirLevels 3
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

CacheDirLevels 지시어는 캐쉬의 하위디렉토리 깊이를 지정한다. 캐쉬된 자료를 CacheRoot 디렉토리 아래 이 깊이까지 저장한다.

CacheDirLevels와 CacheDirLength를 곱하여 20 보다 크면 안된다.

CacheDirLevels 5

CacheExpiryCheck 지시어

설명: | 캐쉬에서 파일을 찾을때 만기시간을 고려할지 여부
문법: | CacheExpiryCheck On|Off
기본값: | CacheExpiryCheck On
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

함수가 구현되면 더 자세한 내용이 여기 나온다.

CacheExpiryCheck Off

CacheExpiryCheck 지시어는 현재 구현되지 않았다.

CacheGcClean 지시어

설명: | URL에 해당하는 변하지않은 캐쉬파일을 유지할 시간
문법: | CacheGcClean hours url-string
기본값: | CacheGcClean ?
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

함수가 구현되면 더 자세한 내용이 여기 나온다.

CacheGcClean 12 /daily_scripts

CacheGcClean 지시어는 현재 구현되지 않았다.

CacheGcDaily 지시어

설명: | 매일 가비지컬랙터를 실행할 반복 시간 (24시 시계)
문법: | CacheGcDaily time
기본값: | CacheGcDaily ?
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

함수가 구현되면 더 자세한 내용이 여기 나온다.

CacheGcDaily 23:59

CacheGcDaily 지시어는 현재 구현되지 않았다.

CacheGcInterval 지시어

설명: | 가비지컬랙터를 실행하는 간격.
문법: | CacheGcInterval hours
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

CacheGcInterval 지시어는 카비지컬랙터가 디스크공간을 비우는 시간 간격을 시간단위로 지정한다.

함수가 구현되면 더 자세한 내용이 여기 나온다.

CacheGcInterval 24

CacheGcInterval 지시어는 현재 구현되지 않았다.

CacheGcMemUsage 지시어

설명: | 가비지컬랙터가 사용할 최대 메모리량 (kilobyte 단위)
문법: | CacheGcMemUsage KBytes
기본값: | CacheGcMemUsage ?
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

함수가 구현되면 더 자세한 내용이 여기 나온다.

CacheGcMemUsage 16

CacheGcMemUsage 지시어는 현재 구현되지 않았다.

CacheGcUnused 지시어

설명: | URL에 해당하는 참조되지않은 캐쉬파일을 유지할 기간.
문법: | CacheGcUnused hours url-string
기본값: | CacheGcUnused ?
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

함수가 구현되면 더 자세한 내용이 여기 나온다.

CacheGcUnused 12 /local_images

CacheGcUnused 지시어는 현재 구현되지 않았다.

CacheMaxFileSize 지시어

설명: | 캐쉬에 저장할 문서의 최대크기 (바이트 단위)
문법: | CacheMaxFileSize bytes
기본값: | CacheMaxFileSize 1000000
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

CacheMaxFileSize 지시어는 캐쉬에 저장할 문서의 최대크기를 바이트 단위로 지정한다.

CacheMaxFileSize 64000

CacheMinFileSize 지시어

설명: | 캐쉬에 저장할 문서의 최소크기 (바이트 단위)
문법: | CacheMinFileSize bytes
기본값: | CacheMinFileSize 1
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

CacheMinFileSize 지시어는 캐쉬에 저장할 문서의 최소크기를 바이트 단위로 지정한다.

CacheMinFileSize 64

CacheRoot 지시어

설명: | 캐쉬 파일을 저장할 디렉토리 root
문법: | CacheRoot directory
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

CacheRoot 지시어는 디스크에서 캐쉬 파일을 저장할 디렉토리를 지정한다. mod_disk_cache 모듈을 아파치 서버와 같이 컴파일하였거나 읽어들인 경우 반드시 이 지시어를 정의해야 한다. CacheRoot에 값이 없으면 설정파일을 처리하지 않는다. CacheDirLevels와 CacheDirLength 지시어는 이 지시어로 지정한 root 디렉토리의 하위디렉토리 구조를 지시한다.

CacheRoot c:/cacheroot

CacheSize 지시어

설명: | 캐쉬로 사용할 최대 디스크공간 (KByte 단위)
문법: | CacheSize KBytes
기본값: | CacheSize 1000000
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

CacheSize 지시어는 캐쉬로 사용할 디스크공간 크기를 KByte (1024 바이트) 단위로 지정한다. 이 지시어는 캐쉬 크기를 제한하지 않는다. 가비지컬랙터가 캐쉬 사용량이 설정한 값보다 작게될때까지 파일을 지운다. 항상 사용가능한 디스크공간 보다 작은 값을 사용하라.

CacheSize 5000000

CacheTimeMargin 지시어

설명: | 문서를 캐쉬할 최소시간 한계
문법: | CacheTimeMargin ?
기본값: | CacheTimeMargin ?
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_disk_cache

함수가 구현되면 더 자세한 내용이 여기 나온다.

CacheTimeMargin X

CacheTimeMargin 지시어는 현재 구현되지 않았다.


mod_echo - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_echo

설명: | 프로토콜 모듈을 설명하기위한 간단한 echo 서버
상태: | Experimental
모듈명: | echo_module
소스파일: | mod_echo.c
지원: | Apache 2.0 이후부터

요약

이 모듈은 프로토콜 모듈의 개념을 설명하기위한 예제이다. 이 모듈은 간단한 echo 서버를 구현한다. 이 서버로 telnet하여 무언가를 입력하면, 서버는 입력한 내용이 그대로 반환한다.

ProtocolEcho 지시어

설명: | echo 서버를 키고 끈다
문법: | ProtocolEcho On|Off
사용장소: | 주서버설정, 가상호스트
상태: | Experimental
모듈: | mod_echo
지원: | ProtocolEcho는 2.0 이후에만 있다.

ProtocolEcho 지시어는 echo 서버를 키고 끈다.

예제

ProtocolEcho On


mod_env - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > 모듈

아파치 모듈 mod_env

설명: | CGI 스크립트나 SSI 페이지에 전달할 환경변수를 수정한다
상태: | Base
모듈명: | env_module
소스파일: | mod_env.c

요약

이 모듈은 CGI 스크립트나 SSI 페이지에 전달할 환경변수를 조절한다. 웹서버를 시작한 쉘에서 환경변수를 가져올 수 있다. 아니면 설정과정중에 환경변수를 설정하고 제거할 수 있다.

참고

  • 환경변수

PassEnv 지시어

설명: | 쉘에서 환경변수를 가져온다
문법: | PassEnv env-variable [env-variable] ...
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | FileInfo
상태: | Base
모듈: | mod_env

웹서버를 실행한 쉘의 특정 환경변수를 CGI 스크립트나 SSI 페이지로 전달한다.

예제

PassEnv LD_LIBRARY_PATH

SetEnv 지시어

설명: | 환경변수를 설정한다
문법: | SetEnv env-variable value
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | FileInfo
상태: | Base
모듈: | mod_env

CGI 스크립트나 SSI 페이지에 전달할 환경변수를 설정한다.

예제

SetEnv SPECIAL_PATH /foo/bin

UnsetEnv 지시어

설명: | 환경변수를 제거한다
문법: | UnsetEnv env-variable [env-variable] ...
사용장소: | 주서버설정, 가상호스트, directory, .htaccess
Override 옵션: | FileInfo
상태: | Base
모듈: | mod_env

CGI 스크립트나 SSI 페이지에 환경변수를 전달하지 않는다.

예제

UnsetEnv LD_LIBRARY_PATH


mod_example - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_example

Description: | Illustrates the Apache module API
Status: | Experimental
Module Identifier: | example_module
Source File: | mod_example.c

Summary

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

The files in the src/modules/example directory under the Apache distribution directory tree are provided as an example to those that wish to write modules that use the Apache API.

The main file is mod_example.c, which illustrates all the different callback mechanisms and call syntaxes. By no means does an add-on module need to include routines for all of the callbacks - quite the contrary!

The example module is an actual working module. If you link it into your server, enable the "example-handler" handler for a location, and then browse to that location, you will see a display of some of the tracing the example module did as the various callbacks were made.

Compiling the example module

To include the example module in your server, follow the steps below:

  1. Uncomment the "AddModule modules/example/mod_example" line near the bottom of the src/Configuration file. If there isn't one, add it; it should look like this:

    AddModule modules/example/mod_example.o

  2. Run the src/Configure script ("cd src; ./Configure"). This will build the Makefile for the server itself, and update the src/modules/Makefile for any additional modules you have requested from beneath that subdirectory.
  3. Make the server (run "make" in the src directory).

To add another module of your own:

  1. mkdir src/modules/mymodule
  2. cp src/modules/example/* src/modules/mymodule
  3. Modify the files in the new directory.
  4. Follow steps [1] through [3] above, with appropriate changes.

Using the mod_example Module

To activate the example module, include a block similar to the following in your srm.conf file:

<Location /example-info>
SetHandler example-handler
</Location>

As an alternative, you can put the following into a .htaccess file and then request the file "test.example" from that location:

AddHandler example-handler .example

After reloading/restarting your server, you should be able to browse to this location and see the brief display mentioned earlier.

Example Directive

Description: | Demonstration directive to illustrate the Apache module API
Syntax: | Example
Context: | server config, virtual host, directory, .htaccess
Status: | Experimental
Module: | mod_example

The Example directive just sets a demonstration flag which the example module's content handler displays. It takes no arguments. If you browse to an URL to which the example content-handler applies, you will get a display of the routines within the module and how and in what order they were called to service the document request. The effect of this directive one can observe under the point "Example directive declared here: YES/NO".


mod_expires - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_expires

Description: | Generation of Expires HTTP headers according to user-specified criteria
Status: | Extension
Module Identifier: | expires_module
Source File: | mod_expires.c

Summary

This module controls the setting of the Expires HTTP header in server responses. The expiration date can set to be relative to either the time the source file was last modified, or to the time of the client access.

The Expires HTTP header is an instruction to the client about the document's validity and persistence. If cached, the document may be fetched from the cache rather than from the source until this time has passed. After that, the cache copy is considered "expired" and invalid, and a new copy must be obtained from the source.

Alternate Interval Syntax

The ExpiresDefault and ExpiresByType directives can also be defined in a more readable syntax of the form:

ExpiresDefault "<base> [plus] {<num> <type>}*"
ExpiresByType type/encoding "<base> [plus] {<num> <type>}*"

where <base> is one of:

  • access
  • now (equivalent to 'access')
  • modification

The plus keyword is optional. <num> should be an integer value [acceptable to atoi()], and <type> is one of:

  • years
  • months
  • weeks
  • days
  • hours
  • minutes
  • seconds

For example, any of the following directives can be used to make documents expire 1 month after being accessed, by default:

ExpiresDefault "access plus 1 month"
ExpiresDefault "access plus 4 weeks"
ExpiresDefault "access plus 30 days"

The expiry time can be fine-tuned by adding several '<num> <type>' clauses:

ExpiresByType text/html "access plus 1 month 15 days 2 hours"
ExpiresByType image/gif "modification plus 5 hours 3 minutes"

Note that if you use a modification date based setting, the Expires header will not be added to content that does not come from a file on disk. This is due to the fact that there is no modification time for such content.

ExpiresActive Directive

Description: | Enables generation of Expires headers
Syntax: | ExpiresActive On|Off
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Extension
Module: | mod_expires

This directive enables or disables the generation of the Expires header for the document realm in question. (That is, if found in an .htaccess file, for instance, it applies only to documents generated from that directory.) If set to Off, no Expires header will be generated for any document in the realm (unless overridden at a lower level, such as an .htaccess file overriding a server config file). If set to On, the header will be added to served documents according to the criteria defined by the ExpiresByType and ExpiresDefault directives (q.v.).

Note that this directive does not guarantee that an Expires header will be generated. If the criteria aren't met, no header will be sent, and the effect will be as though this directive wasn't even specified.

ExpiresByType Directive

Description: | Value of the Expires header configured by MIME type
Syntax: | ExpiresByType MIME-type <code>seconds
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Extension
Module: | mod_expires

This directive defines the value of the Expires header generated for documents of the specified type (e.g., text/html). The second argument sets the number of seconds that will be added to a base time to construct the expiration date.

The base time is either the last modification time of the file, or the time of the client's access to the document. Which should be used is specified by the <code> field; M means that the file's last modification time should be used as the base time, and A means the client's access time should be used.

The difference in effect is subtle. If M is used, all current copies of the document in all caches will expire at the same time, which can be good for something like a weekly notice that's always found at the same URL. If A is used, the date of expiration is different for each client; this can be good for image files that don't change very often, particularly for a set of related documents that all refer to the same images (i.e., the images will be accessed repeatedly within a relatively short timespan).

Example:

# 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

Note that this directive only has effect if ExpiresActive On has been specified. It overrides, for the specified MIME type only, any expiration date set by the ExpiresDefault directive.

You can also specify the expiration time calculation using an alternate syntax, described earlier in this document.

ExpiresDefault Directive

Description: | Default algorithm for calculating expiration time
Syntax: | ExpiresDefault <code>seconds
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Extension
Module: | mod_expires

This directive sets the default algorithm for calculating the expiration time for all documents in the affected realm. It can be overridden on a type-by-type basis by the ExpiresByType directive. See the description of that directive for details about the syntax of the argument, and the alternate syntax description as well.


mod_ext_filter - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_ext_filter

Description: | Pass the response body through an external program before delivery to the client
Status: | Extension
Module Identifier: | ext_filter_module
Source File: | mod_ext_filter.c

Summary

mod_ext_filter presents a simple and familiar programming model for filters. With this module, a program which reads from stdin and writes to stdout (i.e., a Unix-style filter command) can be a filter for Apache. This filtering mechanism is much slower than using a filter which is specially written for the Apache API and runs inside of the Apache server process, but it does have the following benefits:

  • the programming model is much simpler
  • any programming/scripting language can be used, provided that it allows the program to read from standard input and write to standard output
  • existing programs can be used unmodified as Apache filters

Even when the performance characteristics are not suitable for production use, mod_ext_filter can be used as a prototype environment for filters.

See also

  • Filters

Examples

Generating HTML from some other type of response

# mod_ext_filter directive to define a filter
# to HTML-ize text/c files using the external
# program /usr/bin/enscript, with the type of
# the result set to text/html
ExtFilterDefine c-to-html mode=output \
intype=text/c outtype=text/html \
cmd="/usr/bin/enscript --color -W html -Ec -o - -"
<Directory "/export/home/trawick/apacheinst/htdocs/c">
# core directive to cause the new filter to
# be run on output
SetOutputFilter c-to-html

# mod_mime directive to set the type of .c
# files to text/c
AddType text/c .c

# mod_ext_filter directive to set the debug
# level just high enough to see a log message
# per request showing the configuration in force
ExtFilterOptions DebugLevel=1
 </Directory>

Implementing a content encoding filter

Note: this gzip example is just for the purposes of illustration. Please refer to mod_deflate for a practical implementation.

# mod_ext_filter directive to define the external filter
ExtFilterDefine gzip mode=output cmd=/bin/gzip

<Location /gzipped>
# core directive to cause the gzip filter to be
# run on output
SetOutputFilter gzip

# mod_header directive to add
# "Content-Encoding: gzip" header field
Header set Content-Encoding gzip
 </Location>

Slowing down the server

# mod_ext_filter directive to define a filter
# which runs everything through cat; cat doesn't
# modify anything; it just introduces extra pathlength
# and consumes more resources
ExtFilterDefine slowdown mode=output cmd=/bin/cat \
preservescontentlength
<Location />
# core directive to cause the slowdown filter to
# be run several times on output
#
SetOutputFilter slowdown;slowdown;slowdown
 </Location>

Using sed to replace text in the response

# mod_ext_filter directive to define a filter which
# replaces text in the response
#
ExtFilterDefine fixtext mode=output intype=text/html \
cmd="/bin/sed s/verdana/arial/g"
<Location />
# core directive to cause the fixtext filter to
# be run on output
SetOutputFilter fixtext
 </Location>

Tracing another filter

# Trace the data read and written by mod_deflate
# for a particular client (IP 192.168.1.31)
# experiencing compression problems.
# This filter will trace what goes into mod_deflate.
ExtFilterDefine tracebefore \
cmd="/bin/tracefilter.pl /tmp/tracebefore" \
EnableEnv=trace_this_client
# This filter will trace what goes after mod_deflate.
# Note that without the ftype parameter, the default
# filter type of AP_FTYPE_RESOURCE would cause the
# filter to be placed *before* mod_deflate in the filter
# chain. Giving it a numeric value slightly higher than
# AP_FTYPE_CONTENT_SET will ensure that it is placed
# after mod_deflate.
ExtFilterDefine traceafter \
cmd="/bin/tracefilter.pl /tmp/traceafter" \
EnableEnv=trace_this_client ftype=21
<Directory /usr/local/docs>
SetEnvIf Remote_Addr 192.168.1.31 trace_this_client
SetOutputFilter tracebefore;deflate;traceafter
 </Directory>

Here is the filter which traces the data:

#!/usr/local/bin/perl -w
use strict;

open(SAVE, ">$ARGV[0]")
or die "can't open $ARGV[0]: $?";
while (<STDIN>) {
print SAVE $_;
print $_;
 }

close(SAVE);

ExtFilterDefine Directive

Description: | Define an external filter
Syntax: | ExtFilterDefine filtername parameters
Context: | server config
Status: | Extension
Module: | mod_ext_filter

The ExtFilterDefine directive defines the characteristics of an external filter, including the program to run and its arguments.

filtername specifies the name of the filter being defined. This name can then be used in SetOutputFilter directives. It must be unique among all registered filters. At the present time, no error is reported by the register-filter API, so a problem with duplicate names isn't reported to the user.

Subsequent parameters can appear in any order and define the external command to run and certain other characteristics. The only required parameter is cmd=. These parameters are:

cmd=cmdline
The cmd= keyword allows you to specify the external command to run. If there are arguments after the program name, the command line should be surrounded in quotation marks (e.g., cmd="/bin/mypgm arg1 arg2". Normal shell quoting is not necessary since the program is run directly, bypassing the shell. Program arguments are blank-delimited. A backslash can be used to escape blanks which should be part of a program argument. Any backslashes which are part of the argument must be escaped with backslash themselves. In addition to the standard CGI environment variables, DOCUMENT_URI, DOCUMENT_PATH_INFO, and QUERY_STRING_UNESCAPED will also be set for the program.
mode=mode
mode should be output for now (the default). In the future, mode=input will be used to specify a filter for request bodies.
intype=imt
This parameter specifies the internet media type (i.e., MIME type) of documents which should be filtered. By default, all documents are filtered. If intype= is specified, the filter will be disabled for documents of other types.
outtype=imt
This parameter specifies the internet media type (i.e., MIME type) of filtered documents. It is useful when the filter changes the internet media type as part of the filtering operation. By default, the internet media type is unchanged.
PreservesContentLength
The PreservesContentLength keyword specifies that the filter preserves the content length. This is not the default, as most filters change the content length. In the event that the filter doesn't modify the length, this keyword should be specified.
ftype=filtertype
This parameter specifies the numeric value for filter type that the filter should be registered as. The default value, AP_FTYPE_RESOURCE, is sufficient in most cases. If the filter needs to operate at a different point in the filter chain than resource filters, then this parameter will be necessary. See the AP_FTYPE_foo definitions in util_filter.h for appropriate values.
disableenv=env
This parameter specifies the name of an environment variable which, if set, will disable the filter.
enableenv=env
This parameter specifies the name of an environment variable which must be set, or the filter will be disabled.

ExtFilterOptions Directive

Description: | Configure mod_ext_filter options
Syntax: | ExtFilterOptions option [option] ...
Default: | ExtFilterOptions DebugLevel=0 NoLogStderr
Context: | directory
Status: | Extension
Module: | mod_ext_filter

The ExtFilterOptions directive specifies special processing options for mod_ext_filter. Option can be one of

DebugLevel=n
The DebugLevel keyword allows you to specify the level of debug messages generated by mod_ext_filter. By default, no debug messages are generated. This is equivalent to DebugLevel=0. With higher numbers, more debug messages are generated, and server performance will be degraded. The actual meanings of the numeric values are described with the definitions of the DBGLVL_ constants near the beginning of mod_ext_filter.c.

Note: The core directive LogLevel should be used to cause debug messages to be stored in the Apache error log.

LogStderr | NoLogStderr
The LogStderr keyword specifies that messages written to standard error by the external filter program will be saved in the Apache error log. NoLogStderr disables this feature.

Example

ExtFilterOptions LogStderr DebugLevel=0

Messages written to the filter's standard error will be stored in the Apache error log. No debug messages will be generated by mod_ext_filter.


mod_file_cache - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_file_cache

Description: | Caches a static list of files in memory
Status: | Experimental
Module 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. For example, Apache on Windows does not currently support the MMapStatic directive, while other platforms, like AIX, support both. You will receive an error message in the server error log if you attempt to use an unsupported directive. If given an unsupported directive, the server will start but the file will not be cached. On platforms that support both directives, you should experiment with both to see which works best for you.

MMapFile Directive

The MMapFile directive of mod_file_cache maps a list of statically configured files into memory through the system call mmap(). This system call is available on most modern Unix derivates, but not on all. There are sometimes system-specific limits on the size and number of files that can be mmap()ed, experimentation is probably the easiest way to find out.

This mmap()ing is done once at server start or restart, only. So whenever one of the mapped files changes on the filesystem you have to restart the server (see the Stopping and Restarting documentation). To reiterate that point: if the files are modified in place without restarting the server you may end up serving requests that are completely bogus. You should update files by unlinking the old copy and putting a new copy in place. Most tools such as rdist and mv do this. The reason why this modules doesn't take care of changes to the files is that this check would need an extra stat() every time which is a waste and against the intent of I/O reduction.

CacheFile Directive

The CacheFile directive of mod_file_cache opens an active handle or file descriptor to the file (or files) listed in the configuration directive and places these open file handles in the cache. When the file is requested, the server retrieves the handle from the cache and passes it to the sendfile() (or TransmitFile() on Windows), socket API.

This file handle caching is done once at server start or restart, only. So whenever one of the cached files changes on the filesystem you have to restart the server (see the Stopping and Restarting documentation). To reiterate that point: if the files are modified in place without restarting the server you may end up serving requests that are completely bogus. You should update files by unlinking the old copy and putting a new copy in place. Most tools such as rdist and mv do this.

Note

Don't bother asking for a for a directive which recursively caches all the files in a directory. Try this instead... See the Include directive, and consider this command:

find /www/htdocs -type f -print \
| sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf

CacheFile Directive

Description: | Cache a list of file handles at startup time
Syntax: | CacheFile file-path [file-path] ...
Context: | server config
Status: | Experimental
Module: | mod_file_cache

The CacheFile directive opens handles to one or more files (given as whitespace separated arguments) and places these handles into the cache at server startup time. Handles to cached files are automatically closed on a server shutdown. When the files have changed on the filesystem, the server should be restarted to to re-cache them.

Be careful with the file-path arguments: They have to literally match the filesystem path Apache's URL-to-filename translation handlers create. We cannot compare inodes or other stuff to match paths through symbolic links etc. because that again would cost extra stat() system calls which is not acceptable. This module may or may not work with filenames rewritten by mod_alias or mod_rewrite.

Example

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

MMapFile Directive

Description: | Map a list of files into memory at startup time
Syntax: | MMapFile file-path [file-path] ...
Context: | server config
Status: | Experimental
Module: | mod_file_cache

The MMapFile directive maps one or more files (given as whitespace separated arguments) into memory at server startup time. They are automatically unmapped on a server shutdown. When the files have changed on the filesystem at least a HUP or USR1 signal should be send to the server to re-mmap() them.

Be careful with the file-path arguments: They have to literally match the filesystem path Apache's URL-to-filename translation handlers create. We cannot compare inodes or other stuff to match paths through symbolic links etc. because that again would cost extra stat() system calls which is not acceptable. This module may or may not work with filenames rewritten by mod_alias or mod_rewrite.

Example

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


mod_headers - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_headers

Description: | Customization of HTTP request and response headers
Status: | Extension
Module Identifier: | headers_module
Source File: | mod_headers.c
Compatibility: | RequestHeader is available only in Apache 2.0

Summary

This module provides directives to control and modify HTTP request and response headers. Headers can be merged, replaced or removed.

Order of Processing

The directives provided by mod_headers can occur almost anywhere within the server configuration. They are valid in the main server config and virtual host sections, inside <Directory>, <Location> and <Files> sections, and within .htaccess files.

The directives are processed in the following order:

  1. main server
  2. virtual host
  3. <Directory> sections and .htaccess
  4. <Files>
  5. <Location>

Order is important. These two headers have a different effect if reversed:

RequestHeader append MirrorID "mirror 12"
RequestHeader unset MirrorID

This way round, the MirrorID header is not set. If reversed, the MirrorID header is set to "mirror 12".

Examples

  1. Copy all request headers that begin with "TS" to the response headers:

    Header echo ^TS

  2. Add a header, MyHeader, to the response including a timestamp for when the request was received and how long it took to begin serving the request. This header can be used by the client to intuit load on the server or in isolating bottlenecks between the client and the server.

    Header add MyHeader "%D %t"

    results in this header being added to the response:

    MyHeader: D=3775428 t=991424704447256

  3. Say hello to Joe

    Header add MyHeader "Hello Joe. It took %D microseconds \
    for Apache to serve this request."

    results in this header being added to the response:

    MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.

  4. Conditionally send MyHeader on the response if and only if header "MyRequestHeader" is present on the request. This is useful for constructing headers in response to some client stimulus. Note that this example requires the services of the mod_setenvif module.

    SetEnvIf MyRequestHeader value HAVE_MyRequestHeader
    Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader

    If the header MyRequestHeader: value is present on the HTTP request, the response will contain the following header:

    MyHeader: D=3775428 t=991424704447256 mytext

Header Directive

Description: | Configure HTTP response headers
Syntax: | Header set|append|add|unset|echo header [value [env=[!]variable]]
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_headers

This directive can replace, merge or remove HTTP response headers. The header is modified just after the content handler and output filters are run, allowing outgoing headers to be modified. The action it performs is determined by the first argument. This can be one of the following values:

set
The response header is set, replacing any previous header with this name. The value may be a format string.
append
The response header is appended to any existing header of the same name. When a new value is merged onto an existing header it is separated from the existing header with a comma. This is the HTTP standard way of giving a header multiple values.
add
The response header is added to the existing set of headers, even if this header already exists. This can result in two (or more) headers having the same name. This can lead to unforeseen consequences, and in general "append" should be used instead.
unset
The response header of this name is removed, if it exists. If there are multiple headers of the same name, all will be removed.
echo
Request headers with this name are echoed back in the response headers. header may be a regular expression.

This argument is followed by a header name, which can include the final colon, but it is not required. Case is ignored for set, append, add and unset. The header name for echo is case sensitive and may be a regular expression.

For add, append and set a value is specified as the third argument. If value contains spaces, it should be surrounded by doublequotes. value may be a character string, a string containing format specifiers or a combination of both. The following format specifiers are supported in value:

%t | The time the request was received in Universal Coordinated Time since the epoch (Jan. 1, 1970) measured in microseconds. The value is preceded by t=.
%D | The time from when the request was received to the time the headers are sent on the wire. This is a measure of the duration of the request. The value is preceded by D=.
%{FOOBAR}e | The contents of the environment variable FOOBAR.

When the Header directive is used with the add, append, or set argument, a fourth argument may be used to specify conditions under which the action will be taken. If the environment variable specified in the env=... argument exists (or if the environment variable does not exist and env=!... is specified) then the action specified by the Header directive will take effect. Otherwise, the directive will have no effect on the request.

The Header directives are processed just before the response is sent to the network. These means that it is possible to set and/or override most headers, except for those headers added by the header filter.

RequestHeader Directive

Description: | Configure HTTP request headers
Syntax: | RequestHeader set|append|add|unset header [value]
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_headers

This directive can replace, merge or remove HTTP request headers. The header is modified just before the content handler is run, allowing incoming headers to be modified. The action it performs is determined by the first argument. This can be one of the following values:

set
The request header is set, replacing any previous header with this name
append
The request header is appended to any existing header of the same name. When a new value is merged onto an existing header it is separated from the existing header with a comma. This is the HTTP standard way of giving a header multiple values.
add
The request header is added to the existing set of headers, even if this header already exists. This can result in two (or more) headers having the same name. This can lead to unforeseen consequences, and in general append should be used instead.
unset
The request header of this name is removed, if it exists. If there are multiple headers of the same name, all will be removed.

This argument is followed by a header name, which can include the final colon, but it is not required. Case is ignored. For add, append and set a value is given as the third argument. If value contains spaces, it should be surrounded by double quotes. For unset, no value should be given.

The RequestHeader directive is processed just before the request is run by its handler in the fixup phase. This should allow headers generated by the browser, or by Apache input filters to be overridden or modified.


mod_imap - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_imap

Description: | Server-side imagemap processing
Status: | Base
Module Identifier: | imap_module
Source File: | mod_imap.c

Summary

This module processes .map files, thereby replacing the functionality of the imagemap CGI program. Any directory or document type configured to use the handler imap-file (using either AddHandler or SetHandler) will be processed by this module.

The following directive will activate files ending with .map as imagemap files:

AddHandler imap-file map

Note that the following is still supported:

AddType application/x-httpd-imap map

However, we are trying to phase out "magic MIME types" so we are deprecating this method.

New Features

The imagemap module adds some new features that were not possible with previously distributed imagemap programs.

  • URL references relative to the Referer: information.
  • Default <base> assignment through a new map directive base.
  • No need for imagemap.conf file.
  • Point references.
  • Configurable generation of imagemap menus.

Imagemap File

The lines in the imagemap files can have one of several formats:

directive value [x,y ...]
directive value "Menu text" [x,y ...]
directive value x,y ... "Menu text"

The directive is one of base, default, poly, circle, rect, or point. The value is an absolute or relative URL, or one of the special values listed below. The coordinates are x,y pairs separated by whitespace. The quoted text is used as the text of the link if a imagemap menu is generated. Lines beginning with '#' are comments.

Imagemap File Directives

There are six directives allowed in the imagemap file. The directives can come in any order, but are processed in the order they are found in the imagemap file.

base Directive

Has the effect of <base href="value"> . The non-absolute URLs of the map-file are taken relative to this value. The base directive overrides ImapBase as set in a .htaccess file or in the server configuration files. In the absence of an ImapBase configuration directive, base defaults to http://server_name/.

base_uri is synonymous with base. Note that a trailing slash on the URL is significant.

default Directive
The action taken if the coordinates given do not fit any of the poly, circle or rect directives, and there are no point directives. Defaults to nocontent in the absence of an ImapDefault configuration setting, causing a status code of 204 No Content to be returned. The client should keep the same page displayed.
poly Directive
Takes three to one-hundred points, and is obeyed if the user selected coordinates fall within the polygon defined by these points.
circle
Takes the center coordinates of a circle and a point on the circle. Is obeyed if the user selected point is with the circle.
rect Directive
Takes the coordinates of two opposing corners of a rectangle. Obeyed if the point selected is within this rectangle.
point Directive
Takes a single point. The point directive closest to the user selected point is obeyed if no other directives are satisfied. Note that default will not be followed if a point directive is present and valid coordinates are given.

Values

The values for each of the directives can any of the following:

a URL

The URL can be relative or absolute URL. Relative URLs can contain '..' syntax and will be resolved relative to the base value.

base itself will not resolved according to the current value. A statement base mailto: will work properly, though.

map
Equivalent to the URL of the imagemap file itself. No coordinates are sent with this, so a menu will be generated unless ImapMenu is set to none.
menu
Synonymous with map.
referer
Equivalent to the URL of the referring document. Defaults to http://servername/ if no Referer: header was present.
nocontent
Sends a status code of 204 No Content, telling the client to keep the same page displayed. Valid for all but base.
error
Fails with a 500 Server Error. Valid for all but base, but sort of silly for anything but default.

Coordinates

0,0 200,200
A coordinate consists of an x and a y value separated by a comma. The coordinates are separated from each other by whitespace. To accommodate the way Lynx handles imagemaps, should a user select the coordinate 0,0, it is as if no coordinate had been selected.

Quoted Text

"Menu Text"

After the value or after the coordinates, the line optionally may contain text within double quotes. This string is used as the text for the link if a menu is generated:

<a href="http://foo.com/">Menu text</a>

If no quoted text is present, the name of the link will be used as the text:

<a href="http://foo.com/">http://foo.com</a>

If you want to use double quotes within this text, you have to write them as &quot;.

Example Mapfile

#Comments are printed in a 'formatted' or 'semiformatted' menu.
#And can contain html tags. <hr>
base referer
poly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0
rect .. 0,0 77,27 "the directory of the referer"
circle http://www.inetnebr.com/lincoln/feedback/ 195,0 305,27
rect another_file "in same directory as referer" 306,0 419,27
point http://www.zyzzyva.com/ 100,100
point http://www.tripod.com/ 200,200
rect mailto:nate@tripod.com 100,150 200,0 "Bugs?"

Referencing your mapfile

HTML example

<a href="/maps/imagemap1.map">
<img ismap src="/images/imagemap1.gif">
 </a>

XHTML example

<a href="/maps/imagemap1.map">
<img ismap="ismap" src="/images/imagemap1.gif" />
 </a>

ImapBase Directive

Description: | Default base for imagemap files
Syntax: | ImapBase map|referer|URL
Default: | ImapBase http://servername/
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Base
Module: | mod_imap

The ImapBase directive sets the default base used in the imagemap files. Its value is overridden by a base directive within the imagemap file. If not present, the base defaults to http://servername/.

See also

  • UseCanonicalName

ImapDefault Directive

Description: | Default action when an imagemap is called with coordinates that are not explicitly mapped
Syntax: | ImapDefault error|nocontent|map|referer|URL
Default: | ImapDefault nocontent
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Base
Module: | mod_imap

The ImapDefault directive sets the default default used in the imagemap files. Its value is overridden by a default directive within the imagemap file. If not present, the default action is nocontent, which means that a 204 No Content is sent to the client. In this case, the client should continue to display the original page.

ImapMenu Directive

Description: | Action if no coordinates are given when calling an imagemap
Syntax: | ImapMenu none|formatted|semiformatted|unformatted
Context: | server config, virtual host, directory, .htaccess
Override: | Indexes
Status: | Base
Module: | mod_imap

The ImapMenu directive determines the action taken if an imagemap file is called without valid coordinates.

none
If ImapMenu is none, no menu is generated, and the default action is performed.
formatted
A formatted menu is the simplest menu. Comments in the imagemap file are ignored. A level one header is printed, then an hrule, then the links each on a separate line. The menu has a consistent, plain look close to that of a directory listing.
semiformatted
In the semiformatted menu, comments are printed where they occur in the imagemap file. Blank lines are turned into HTML breaks. No header or hrule is printed, but otherwise the menu is the same as a formatted menu.
unformatted
Comments are printed, blank lines are ignored. Nothing is printed that does not appear in the imagemap file. All breaks and headers must be included as comments in the imagemap file. This gives you the most flexibility over the appearance of your menus, but requires you to treat your map files as HTML instead of plaintext.


mod_include - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_include

Description: | Server-parsed html documents (Server Side Includes)
Status: | Base
Module Identifier: | include_module
Source File: | mod_include.c
Compatibility: | Implemented as an output filter since Apache 2.0

Summary

This module provides a filter which will process files before they are sent to the client. The processing is controlled by specially formatted SGML comments, referred to as elements. These elements allow conditional text, the inclusion of other files or programs, as well as the setting and printing of environment variables.

See also

  • Options
  • AcceptPathInfo
  • International Customized Server Error Messages
  • Filters
  • SSI Tutorial

Enabling Server-Side Includes

Server Side Includes are implemented by the INCLUDES filter. If documents containing server-side include directives are given the extension .shtml, the following directives will make Apache parse them and assign the resulting document the mime type of text/html:

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

The following directive must be given for the directories containing the shtml files (typically in a <Directory> section, but this directive is also valid in .htaccess files if AllowOverride Options is set):

Options +Includes

For backwards compatibility, the server-parsed handler also activates the INCLUDES filter. As well, Apache will activate the INCLUDES filter for any document with mime type text/x-server-parsed-html or text/x-server-parsed-html3 (and the resulting output will have the mime type text/html).

For more information, see our Tutorial on Server Side Includes.

PATH_INFO with Server Side Includes

Files processed for server-side includes no longer accept requests with PATH_INFO (trailing pathname information) by default. You can use the AcceptPathInfo directive to configure the server to accept requests with PATH_INFO.

Basic Elements

The document is parsed as an HTML document, with special commands embedded as SGML comments. A command has the syntax:

<!--#element attribute=value attribute=value ... -->

The value will often be enclosed in double quotes, but single quotes (') and backticks (`) are also possible. Many commands only allow a single attribute-value pair. Note that the comment terminator (-->) should be preceded by whitespace to ensure that it isn't considered part of an SSI token. Note that the leading <!--# is one token and may not contain any whitespaces.

The allowed elements are listed in the following table:

Element | Description
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 elements may be defined by modules other than mod_include. In fact, the exec element is provided by mod_cgi, and will only be available if this module is loaded.

The config Element

This command controls various aspects of the parsing. The valid attributes are:

errmsg
The value is a message that is sent back to the client if an error occurs while parsing the document.
sizefmt
The value sets the format to be used which displaying the size of a file. Valid values are bytes for a count in bytes, or abbrev for a count in Kb or Mb as appropriate, for example a size of 1024 bytes will be printed as "1K".
timefmt
The value is a string to be used by the strftime(3) library routine when printing dates.

The echo Element

This command prints one of the include variables, defined below. If the variable is unset, the result is determined by the SSIUndefinedEcho directive. Any dates printed are subject to the currently configured timefmt.

Attributes:

var
The value is the name of the variable to print.
encoding

Specifies how Apache should encode special characters contained in the variable before outputting them. If set to none, no encoding will be done. If set to url, then URL encoding (also known as %-encoding; this is appropriate for use within URLs in links, etc.) will be performed. At the start of an echo element, the default is set to entity, resulting in entity encoding (which is appropriate in the context of a block-level HTML element, e.g. a paragraph of text). This can be changed by adding an encoding attribute, which will remain in effect until the next encoding attribute is encountered or the element ends, whichever comes first.

The encoding attribute must precede the corresponding var attribute to be effective, and only special characters as defined in the ISO-8859-1 character encoding will be encoded. This encoding process may not have the desired result if a different character encoding is in use.

In order to avoid cross-site scripting issues, you should always encode user supplied data.

The exec Element

The exec command executes a given shell command or CGI script. It requires mod_cgi to be present in the server. If Options IncludesNOEXEC is set, this command is completely disabled. The valid attributes are:

cgi

The value specifies a (%-encoded) URL-path to the CGI script. If the path does not begin with a slash (/), then it is taken to be relative to the current document. The document referenced by this path is invoked as a CGI script, even if the server would not normally recognize it as such. However, the directory containing the script must be enabled for CGI scripts (with ScriptAlias or Options ExecCGI).

The CGI script is given the PATH_INFO and query string (QUERY_STRING) of the original request from the client; these cannot be specified in the URL path. The include variables will be available to the script in addition to the standard CGI environment.

Example

<!--#exec cgi="/cgi-bin/example.cgi" -->

If the script returns a Location: header instead of output, then this will be translated into an HTML anchor.

The include virtual element should be used in preference to exec cgi. In particular, if you need to pass additional arguments to a CGI program, using the query string, this cannot be done with exec cgi, but can be done with include virtual, as shown here:

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

cmd

The server will execute the given string using /bin/sh. The include variables are available to the command, in addition to the usual set of CGI variables.

The use of #include virtual is almost always prefered to using either #exec cgi or #exec cmd. The former (#include virtual) uses the standard Apache sub-request mechanism to include files or scripts. It is much better tested and maintained.

In addition, on some platforms, like Win32, and on unix when using suexec, you cannot pass arguments to a command in an exec directive, or otherwise include spaces in the command. Thus, while the following will work under a non-suexec configuration on unix, it will not produce the desired result under Win32, or when running suexec:

<!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->

The fsize Element

This command prints the size of the specified file, subject to the sizefmt format specification. Attributes:

file
The value is a path relative to the directory containing the current document being parsed.
virtual
The value is a (%-encoded) URL-path. If it does not begin with a slash (/) then it is taken to be relative to the current document. Note, that this does not print the size of any CGI output, but the size of the CGI script itself.

The flastmod Element

This command prints the last modification date of the specified file, subject to the timefmt format specification. The attributes are the same as for the fsize command.

The include Element

This command inserts the text of another document or file into the parsed file. Any included file is subject to the usual access control. If the directory containing the parsed file has Options IncludesNOEXEC set, then only documents with a text MIME type (text/plain, text/html etc.) will be included. Otherwise CGI scripts are invoked as normal using the complete URL given in the command, including any query string.

An attribute defines the location of the document; the inclusion is done for each attribute given to the include command. The valid attributes are:

file
The value is a path relative to the directory containing the current document being parsed. It cannot contain ../, nor can it be an absolute path. Therefore, you cannot include files that are outside of the document root, or above the current document in the directory structure. The virtual attribute should always be used in preference to this one.
virtual

The value is a (%-encoded) URL-path. The URL cannot contain a scheme or hostname, only a path and an optional query string. If it does not begin with a slash (/) then it is taken to be relative to the current document.

A URL is constructed from the attribute, and the output the server would return if the URL were accessed by the client is included in the parsed output. Thus included files can be nested.

If the specified URL is a CGI program, the program will be executed and its output inserted in place of the directive in the parsed file. You may include a query string in a CGI url:

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

include virtual should be used in preference to exec cgi to include the output of CGI programs into an HTML document.

The printenv Element

This prints out a listing of all existing variables and their values. Special characters are entity encoded (see the echo element for details) before being output. There are no attributes.

Example

<!--#printenv -->

The set Element

This sets the value of a variable. Attributes:

var
The name of the variable to set.
value
The value to give a variable.

Example

<!--#set var="category" value="help" -->

Include Variables

In addition to the variables in the standard CGI environment, these are available for the echo command, for if and elif, and to any program invoked by the document.

DATE_GMT
The current date in Greenwich Mean Time.
DATE_LOCAL
The current date in the local time zone.
DOCUMENT_NAME
The filename (excluding directories) of the document requested by the user.
DOCUMENT_URI
The (%-decoded) URL path of the document requested by the user. Note that in the case of nested include files, this is not the URL for the current document.
LAST_MODIFIED
The last modification date of the document requested by the user.
QUERY_STRING_UNESCAPED
If a query string is present, this variable contains the (%-decoded) query string, which is escaped for shell usage (special characters like & etc. are preceded by backslashes).

Variable Substitution

Variable substitution is done within quoted strings in most cases where they may reasonably occur as an argument to an SSI directive. This includes the config, exec, flastmod, fsize, include, echo, and set directives, as well as the arguments to conditional operators. You can insert a literal dollar sign into the string using backslash quoting:

<!--#if expr="$a = \$test" -->

If a variable reference needs to be substituted in the middle of a character sequence that might otherwise be considered a valid identifier in its own right, it can be disambiguated by enclosing the reference in braces, a la shell substitution:

<!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->

This will result in the Zed variable being set to "X_Y" if REMOTE_HOST is "X" and REQUEST_METHOD is "Y".

The below example will print "in foo" if the DOCUMENT_URI is /foo/file.html, "in bar" if it is /bar/file.html and "in neither" otherwise:

<!--#if expr='"$DOCUMENT_URI" = "/foo/file.html"' -->
in foo
 <!--#elif expr='"$DOCUMENT_URI" = "/bar/file.html"' -->
in bar
 <!--#else -->
in neither
 <!--#endif -->

Flow Control Elements

The basic flow control elements are:

<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->

The if element works like an if statement in a programming language. The test condition is evaluated and if the result is true, then the text until the next elif, else or endif element is included in the output stream.

The elif or else statements are be used to put text into the output stream if the original test_condition was false. These elements are optional.

The endif element ends the if element and is required.

test_condition is one of the following:

string
true if string is not empty
string1 = string2
string1 != string2

Compare string1 with string2. If string2 has the form /string2/ then it is treated as a regular expression. Regular expressions are implemented by the PCRE engine and have the same syntax as those in perl 5.

If you are matching positive (=), you can capture grouped parts of the regular expression. The captured parts are stored in the special variables $1 .. $9.

Example

<!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
<!--#set var="session" value="$1" -->
 <!--#endif -->

string1 < string2
string1 <= string2
string1 > string2
string1 >= string2
Compare string1 with string2. Note, that strings are compared literally (using strcmp(3)). Therefore the string "100" is less than "20".
( test_condition )
true if test_condition is true
! test_condition
true if test_condition is false
test_condition1 && test_condition2
true if both test_condition1 and test_condition2 are true
test_condition1 || test_condition2
true if either test_condition1 or test_condition2 is true

"=" and "!=" bind more tightly than "&&" and "||". "!" binds most tightly. Thus, the following are equivalent:

<!--#if expr="$a = test1 && $b = test2" -->
<!--#if expr="($a = test1) && ($b = test2)" -->

Anything that's not recognized as a variable or an operator is treated as a string. Strings can also be quoted: 'string'. Unquoted strings can't contain whitespace (blanks and tabs) because it is used to separate tokens such as variables. If multiple strings are found in a row, they are concatenated using blanks. So,

string1    string2 results in string1 string2

and

'string1    string2' results in string1    string2.

SSIEndTag Directive

Description: | String that ends an include element
Syntax: | SSIEndTag tag
Default: | SSIEndTag "-->"
Context: | server config, virtual host
Status: | Base
Module: | mod_include
Compatibility: | Available in version 2.0.30 and later.

This directive changes the string that mod_include looks for to mark the end of an include element.

Example

SSIEndTag "%>"

See also

  • SSIStartTag

SSIErrorMsg Directive

Description: | Error message displayed when there is an SSI error
Syntax: | SSIErrorMsg message
Default: | SSIErrorMsg "[an error occurred while processing this directive]"
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Base
Module: | mod_include
Compatibility: | Available in version 2.0.30 and later.

The SSIErrorMsg directive changes the error message displayed when mod_include encounters an error. For production servers you may consider changing the default error message to "<!-- Error -->" so that the message is not presented to the user.

This directive has the same effect as the <!--#config errmsg=message --> element.

Example

SSIErrorMsg "<!-- Error -->"

SSIStartTag Directive

Description: | String that starts an include element
Syntax: | SSIStartTag tag
Default: | SSIStartTag "<!--#"
Context: | server config, virtual host
Status: | Base
Module: | mod_include
Compatibility: | Available in version 2.0.30 and later.

This directive changes the string that mod_include looks for to mark an include element to process.

You may want to use this option if you have 2 servers parsing the output of a file each processing different commands (possibly at different times).

Example

SSIStartTag "<%"

The example given above, in conjunction with a matching SSIEndTag, will allow you to use SSI directives as shown in the example below:

SSI directives with alternate start and end tags

<%printenv %>

See also

  • SSIEndTag

SSITimeFormat Directive

Description: | Configures the format in which date strings are displayed
Syntax: | SSITimeFormat formatstring
Default: | SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"
Context: | server config, virtual host, directory, .htaccess
Override: | All
Status: | Base
Module: | mod_include
Compatibility: | Available in version 2.0.30 and later.

This directive changes the format in which date strings are displayed when echoing DATE environment variables. The formatstring is as in strftime(3) from the C standard library.

This directive has the same effect as the <!--#config timefmt=formatstring --> element.

Example

SSITimeFormat "%R, %B %d, %Y"

The above directive would cause times to be displayed in the format "22:26, June 14, 2002".

SSIUndefinedEcho Directive

Description: | String displayed when an unset variable is echoed
Syntax: | SSIUndefinedEcho string
Default: | SSIUndefinedEcho "(none)"
Context: | server config, virtual host
Status: | Base
Module: | mod_include
Compatibility: | Available in version 2.0.34 and later.

This directive changes the string that mod_include displays when a variable is not set and "echoed".

Example

SSIUndefinedEcho "<!-- undef -->"

XBitHack Directive

Description: | Parse SSI directives in files with the execute bit set
Syntax: | XBitHack on|off|full
Default: | XBitHack off
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Base
Module: | mod_include

The XBitHack directive controls the parsing of ordinary html documents. This directive only affects files associated with the MIME type text/html. XBitHack can take on the following values:

off
No special treatment of executable files.
on
Any text/html file that has the user-execute bit set will be treated as a server-parsed html document.
full
As for on but also test the group-execute bit. If it is set, then set the Last-modified date of the returned file to be the last modified time of the file. If it is not set, then no last-modified date is sent. Setting this bit allows clients and proxies to cache the result of the request.

Note

You would not want to use the full option, unless you assure the group-execute bit is unset for every SSI script which might #include a CGI or otherwise produces different output on each hit (or could potentially change on subsequent requests).


mod_info - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_info

Description: | Provides a comprehensive overview of the server configuration
Status: | Extension
Module Identifier: | info_module
Source File: | mod_info.c

Summary

To configure mod_info, add the following to your httpd.conf file.

<Location /server-info>
SetHandler server-info
 </Location>

You may wish to add a <Limit> clause inside the <Location> directive to limit access to your server configuration information.

Once configured, the server information is obtained by accessing http://your.host.dom/server-info

Note that the configuration files are read by the module at run-time, and therefore the display may not reflect the running server's active configuration if the files have been changed since the server was last reloaded. Also, the configuration files must be readable by the user as which the server is running (see the User directive), or else the directive settings will not be listed.

It should also be noted that if mod_info is compiled into the server, its handler capability is available in all configuration files, including per-directory files (e.g., .htaccess). This may have security-related ramifications for your site.

In particular, this module can leak sensitive information from the configuration directives of other Apache modules such as system paths, usernames/passwords, database names, etc. Due to the way this module works there is no way to block information from it. Therefore, this module should only be used in a controlled environment and always with caution.

AddModuleInfo Directive

Description: | Adds additional information to the module information displayed by the server-info handler
Syntax: | AddModuleInfo module-name string
Context: | server config, virtual host
Status: | Extension
Module: | mod_info
Compatibility: | Apache 1.3 and above

This allows the content of string to be shown as HTML interpreted, Additional Information for the module module-name. Example:

AddModuleInfo mod_auth.c 'See <a \
href="http://www.apache.org/docs-2.0/mod/mod_auth.html">\
http://www.apache.org/docs-2.0/mod/mod_auth.html</a>'


mod_isapi - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_isapi

Description: | ISAPI Extensions within Apache for Windows
Status: | Base
Module 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-isa handler, and map it to them with their file extensions. To enable any .dll file to be processed as an ISAPI extension, edit the httpd.conf file and add the following line:

AddHandler isapi-isa .dll

There is no capability within the Apache server to leave a requested module loaded. However, you may preload and keep a specific module loaded by using the following syntax in your httpd.conf:

ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll

Whether or not you have preloaded an ISAPI extension, all ISAPI extensions are governed by the same permissions and restrictions as CGI scripts. That is, Options ExecCGI must be set for the directory that contains the ISAPI .dll file.

Review the Additional Notes and the Programmer's Journal for additional details and clarification of the specific ISAPI support offered by mod_isapi.

Additional Notes

Apache's ISAPI implementation conforms to all of the ISAPI 2.0 specification, except for some "Microsoft-specific" extensions dealing with asynchronous I/O. Apache's I/O model does not allow asynchronous reading and writing in a manner that the ISAPI could access. If an ISA tries to access unsupported features, including async I/O, a message is placed in the error log to help with debugging. Since these messages can become a flood, the directive ISAPILogNotSupported Off exists to quiet this noise.

Some servers, like Microsoft IIS, load the ISAPI extension into the server and keep it loaded until memory usage is too high, or unless configuration options are specified. Apache currently loads and unloads the ISAPI extension each time it is requested, unless the ISAPICacheFile directive is specified. This is inefficient, but Apache's memory model makes this the most effective method. Many ISAPI modules are subtly incompatible with the Apache server, and unloading these modules helps to ensure the stability of the server.

Also, remember that while Apache supports ISAPI Extensions, it does not support ISAPI Filters. Support for filters may be added at a later date, but no support is planned at this time.

Programmer's Journal

If you are programming Apache 2.0 mod_isapi modules, you must limit your calls to ServerSupportFunction to the following directives:

HSE_REQ_SEND_URL_REDIRECT_RESP
Redirect the user to another location.
This must be a fully qualified URL (e.g. http://server/location).
HSE_REQ_SEND_URL
Redirect the user to another location.
This cannot be a fully qualified URL, you are not allowed to pass the protocol or a server name (e.g. simply /location).
This redirection is handled by the server, not the browser.

Warning

In their recent documentation, Microsoft appears to have abandoned the distinction between the two HSE_REQ_SEND_URL functions. Apache continues to treat them as two distinct functions with different requirements and behaviors.

HSE_REQ_SEND_RESPONSE_HEADER
Apache accepts a response body following the header if it follows the blank line (two consecutive newlines) in the headers string argument. This body cannot contain NULLs, since the headers argument is NULL terminated.
HSE_REQ_DONE_WITH_SESSION
Apache considers this a no-op, since the session will be finished when the ISAPI returns from processing.
HSE_REQ_MAP_URL_TO_PATH
Apache will translate a virtual name to a physical name.
HSE_APPEND_LOG_PARAMETER
This logged message may be captured in any of the following logs:
  • in the \"%{isapi-parameter}n\" component in a CustomLog directive
  • in the %q log component with the ISAPIAppendLogToQuery On directive
  • in the error log with the ISAPIAppendLogToErrors On directive

The first option, the %{isapi-parameter}n component, is always available and preferred.

HSE_REQ_IS_KEEP_CONN
Will return the negotiated Keep-Alive status.
HSE_REQ_SEND_RESPONSE_HEADER_EX
Will behave as documented, although the fKeepConn flag is ignored.
HSE_REQ_IS_CONNECTED
Will report false if the request has been aborted.

Apache returns FALSE to any unsupported call to ServerSupportFunction, and sets the GetLastError value to ERROR_INVALID_PARAMETER.

ReadClient retrieves the request body exceeding the initial buffer (defined by ISAPIReadAheadBuffer). Based on the ISAPIReadAheadBuffer setting (number of bytes to buffer prior to calling the ISAPI handler) shorter requests are sent complete to the extension when it is invoked. If the request is longer, the ISAPI extension must use ReadClient to retrieve the remaining request body.

WriteClient is supported, but only with the HSE_IO_SYNC flag or no option flag (value of 0). Any other WriteClient request will be rejected with a return value of FALSE, and a GetLastError value of ERROR_INVALID_PARAMETER.

GetServerVariable is supported, although extended server variables do not exist (as defined by other servers.) All the usual Apache CGI environment variables are available from GetServerVariable, as well as the ALL_HTTP and ALL_RAW values.

Apache 2.0 mod_isapi supports additional features introduced in later versions of the ISAPI specification, as well as limited emulation of async I/O and the TransmitFile semantics. Apache also supports preloading ISAPI .dlls for performance, neither of which were not available under Apache 1.3 mod_isapi.

ISAPIAppendLogToErrors Directive

Description: | Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the error log
Syntax: | ISAPIAppendLogToErrors on|off
Default: | ISAPIAppendLogToErrors off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the server error log.

ISAPIAppendLogToQuery Directive

Description: | Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the query field
Syntax: | ISAPIAppendLogToQuery on|off
Default: | ISAPIAppendLogToQuery on
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

Record HSE_APPEND_LOG_PARAMETER requests from ISAPI extensions to the query field (appended to the CustomLog %q component).

ISAPICacheFile Directive

Description: | ISAPI .dll files to be loaded at startup
Syntax: | ISAPICacheFile file-path [file-path] ...
Context: | server config, virtual host
Status: | Base
Module: | mod_isapi

Specifies a space-separated list of file names to be loaded when the Apache server is launched, and remain loaded until the server is shut down. This directive may be repeated for every ISAPI .dll file desired. The full path name of each file should be specified. If the path name is not absolute, it will be treated relative to ServerRoot.

ISAPIFakeAsync Directive

Description: | Fake asynchronous support for ISAPI callbacks
Syntax: | ISAPIFakeAsync on|off
Default: | ISAPIFakeAsync off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

While set to on, asynchronous support for ISAPI callbacks is simulated.

ISAPILogNotSupported Directive

Description: | Log unsupported feature requests from ISAPI extensions
Syntax: | ISAPILogNotSupported on|off
Default: | ISAPILogNotSupported off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

Logs all requests for unsupported features from ISAPI extensions in the server error log. This may help administrators to track down problems. Once set to on and all desired ISAPI modules are functioning, it should be set back to off.

ISAPIReadAheadBuffer Directive

Description: | Size of the Read Ahead Buffer sent to ISAPI extensions
Syntax: | ISAPIReadAheadBuffer size
Default: | ISAPIReadAheadBuffer 49152
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_isapi

Defines the maximum size of the Read Ahead Buffer sent to ISAPI extensions when they are initially invoked. All remaining data must be retrieved using the ReadClient callback; some ISAPI extensions may not support the ReadClient function. Refer questions to the ISAPI extension's author.


mod_ldap - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_ldap

Description: | LDAP connection pooling and result caching services for use by other LDAP modules
Status: | Experimental
Module 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 support requires that mod_ldap be linked with one of the following LDAP SDKs: OpenLDAP SDK (both 1.x and 2.x), Novell LDAP SDK or the iPlanet(Netscape) SDK.

Example Configuration

The following is an example configuration that uses mod_ldap to increase the performance of HTTP Basic authentication provided by mod_auth_ldap.

# Enable the LDAP connection pool and shared
# memory cache. Enable the LDAP cache status
# handler. Requires that mod_ldap and mod_auth_ldap
# be loaded. Change the "yourdomain.example.com" to
# match your domain.

LDAPSharedCacheSize 200000
LDAPCacheEntries 1024
LDAPCacheTTL 600
LDAPOpCacheEntries 1024
LDAPOpCacheTTL 600

<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
AuthLDAPEnabled on
AuthLDAPURL ldap://127.0.0.1/dc=example,dc=com?uid?one
AuthLDAPAuthoritative on
require valid-user
 </Location>

LDAP Connection Pool

LDAP connections are pooled from request to request. This allows the LDAP server to remain connected and bound ready for the next request, without the need to unbind/connect/rebind. The performance advantages are similar to the effect of HTTP keepalives.

On a busy server it is possible that many requests will try and access the same LDAP server connection simultaneously. Where an LDAP connection is in use, Apache will create a new connection alongside the original one. This ensures that the connection pool does not become a bottleneck.

There is no need to manually enable connection pooling in the Apache configuration. Any module using this module for access to LDAP services will share the connection pool.

LDAP Cache

For improved performance, mod_ldap uses an aggressive caching strategy to minimize the number of times that the LDAP server must be contacted. Caching can easily double or triple the throughput of Apache when it is serving pages protected with mod_auth_ldap. In addition, the load on the LDAP server will be significantly decreased.

mod_ldap supports two types of LDAP caching during the search/bind phase with a search/bind cache and during the compare phase with two operation caches. Each LDAP URL that is used by the server has its own set of these three caches.

The Search/Bind Cache

The process of doing a search and then a bind is the most time-consuming aspect of LDAP operation, especially if the directory is large. The search/bind cache is used to cache all searches that resulted in successful binds. Negative results (i.e., unsuccessful searches, or searches that did not result in a successful bind) are not cached. The rationale behind this decision is that connections with invalid credentials are only a tiny percentage of the total number of connections, so by not caching invalid credentials, the size of the cache is reduced.

mod_ldap stores the username, the DN retrieved, the password used to bind, and the time of the bind in the cache. Whenever a new connection is initiated with the same username, mod_ldap compares the password of the new connection with the password in the cache. If the passwords match, and if the cached entry is not too old, mod_ldap bypasses the search/bind phase.

The search and bind cache is controlled with the LDAPCacheEntries and LDAPCacheTTL directives.

Operation Caches

During attribute and distinguished name comparison functions, mod_ldap uses two operation caches to cache the compare operations. The first compare cache is used to cache the results of compares done to test for LDAP group membership. The second compare cache is used to cache the results of comparisons done between distinguished names.

The behavior of both of these caches is controlled with the LDAPOpCacheEntries and LDAPOpCacheTTL directives.

Monitoring the Cache

mod_ldap has a content handler that allows administrators to monitor the cache performance. The name of the content handler is ldap-status, so the following directives could be used to access the mod_ldap cache information:

<Location /server/cache-info>
SetHandler ldap-status
 </Location>

By fetching the URL http://servername/cache-info, the administrator can get a status report of every cache that is used by mod_ldap cache. Note that if Apache does not support shared memory, then each httpd instance has its own cache, so reloading the URL will result in different information each time, depending on which httpd instance processes the request.

Using SSL

The ability to create an SSL connections to an LDAP server is defined by the directives LDAPTrustedCA and LDAPTrustedCAType. These directives specify the certificate file or database and the certificate type. Whenever the LDAP url includes ldaps://, mod_ldap will establish a secure connection to the LDAP server.

# Establish an SSL LDAP connection. Requires that
# mod_ldap and mod_auth_ldap be loaded. Change the
# "yourdomain.example.com" to match your domain.

LDAPTrustedCA /certs/certfile.der
LDAPTrustedCAType DER_FILE

<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
AuthLDAPEnabled on
AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one
AuthLDAPAuthoritative on
require valid-user
 </Location>

If mod_ldap is linked against the Netscape/iPlanet LDAP SDK, it will not talk to any SSL server unless that server has a certificate signed by a known Certificate Authority. As part of the configuration mod_ldap needs to be told where it can find a database containing the known CAs. This database is in the same format as Netscape Communicator's cert7.db database. The easiest way to get this file is to start up a fresh copy of Netscape, and grab the resulting $HOME/.netscape/cert7.db file.

LDAPCacheEntries Directive

Description: | Maximum number of entries in the primary LDAP cache
Syntax: | LDAPCacheEntries number
Default: | LDAPCacheEntries 1024
Context: | server config
Status: | Experimental
Module: | mod_ldap

Specifies the maximum size of the primary LDAP cache. This cache contains successful search/binds. Set it to 0 to turn off search/bind caching. The default size is 1024 cached searches.

LDAPCacheTTL Directive

Description: | Time that cached items remain valid
Syntax: | LDAPCacheTTL seconds
Default: | LDAPCacheTTL 600
Context: | server config
Status: | Experimental
Module: | mod_ldap

Specifies the time (in seconds) that an item in the search/bind cache remains valid. The default is 600 seconds (10 minutes).

LDAPOpCacheEntries Directive

Description: | Number of entries used to cache LDAP compare operations
Syntax: | LDAPOpCacheEntries number
Default: | LDAPOpCacheEntries 1024
Context: | server config
Status: | Experimental
Module: | mod_ldap

This specifies the number of entries mod_ldap will use to cache LDAP compare operations. The default is 1024 entries. Setting it to 0 disables operation caching.

LDAPOpCacheTTL Directive

Description: | Time that entries in the operation cache remain valid
Syntax: | LDAPOpCacheTTL seconds
Default: | LDAPOpCacheTTL 600
Context: | server config
Status: | Experimental
Module: | mod_ldap

Specifies the time (in seconds) that entries in the operation cache remain valid. The default is 600 seconds.

LDAPSharedCacheFile Directive

Description: | Sets the shared memory chache file
Syntax: | LDAPSharedCacheFile directory-path/filename
Context: | server config
Status: | Experimental
Module: | mod_ldap

Specifies the directory path and file name of the shared memory cache file. If not set, shared memory caching will not be used.

LDAPSharedCacheSize Directive

Description: | Size in bytes of the shared-memory cache
Syntax: | LDAPSharedCacheSize bytes
Default: | LDAPSharedCacheSize 102400
Context: | server config
Status: | Experimental
Module: | mod_ldap

Specifies the number of bytes to allocate for the shared memory cache. The default is 100kb. If set to 0, shared memory caching will not be used.

LDAPTrustedCA Directive

Description: | Sets the file containing the trusted Certificate Authority certificate or database
Syntax: | LDAPTrustedCA directory-path/filename
Context: | server config
Status: | Experimental
Module: | mod_ldap

It specifies the directory path and file name of the trusted CA mod_ldap should use when establishing an SSL connection to an LDAP server. If using the Netscape/iPlanet Directory SDK, the file name should be cert7.db.

LDAPTrustedCAType Directive

Description: | Specifies the type of the Certificate Authority file
Syntax: | LDAPTrustedCAType type
Context: | server config
Status: | Experimental
Module: | mod_ldap

The following types are supported:
DER_FILE - file in binary DER format
BASE64_FILE - file in Base64 format
CERT7_DB_PATH - Netscape certificate database file ")


mod_log_config - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_log_config

Description: | Logging of the requests made to the server
Status: | Base
Module Identifier: | log_config_module
Source File: | mod_log_config.c

Summary

This module provides for flexible logging of client requests. Logs are written in a customizable format, and may be written directly to a file, or to an external program. Conditional logging is provided so that individual requests may be included or excluded from the logs based on characteristics of the request.

Three directives are provided by this module: TransferLog to create a log file, LogFormat to set a custom format, and CustomLog to define a log file and format in one step. The TransferLog and CustomLog directives can be used multiple times in each server to cause each request to be logged to multiple files.

See also

  • Apache Log Files

Custom Log Formats

The format argument to the LogFormat and CustomLog directives is a string. This string is used to log each request to the log file. It can contain literal characters copied into the log files and the C-style control characters "\n" and "\t" to represent new-lines and tabs. Literal quotes and back-slashes should be escaped with back-slashes.

The characteristics of the request itself are logged by placing "%" directives in the format string, which are replaced in the log file by the values as follows:

Format String | Description
%% The percent sign (Apache 2.0.44 and later)
%...a | Remote IP-address
%...A | Local IP-address
%...B | Bytes sent, excluding HTTP headers.
%...b | Bytes sent, excluding HTTP headers. In CLF format, i.e. a '-' rather than a 0 when no bytes are sent.
%...{Foobar}C | The contents of cookie Foobar in the request sent to the server.
%...D | The time taken to serve the request, in microseconds.
%...{FOOBAR}e | The contents of the environment variable FOOBAR
%...f | Filename
%...h | Remote host
%...H | The request protocol
%...{Foobar}i | The contents of Foobar: header line(s) in the request sent to the server.
%...l | Remote logname (from identd, if supplied)
%...m | The request method
%...{Foobar}n | The contents of note Foobar from another module.
%...{Foobar}o | The contents of Foobar: header line(s) in the reply.
%...p | The canonical port of the server serving the request
%...P | The process ID of the child that serviced the request.
%...{format}P | The process ID or thread id of the child that serviced the request. Valid formats are pid and tid. (Apache 2.0.46 and later)
%...q | The query string (prepended with a ? if a query string exists, otherwise an empty string)
%...r | First line of request
%...s | Status. For requests that got internally redirected, this is the status of the *original* request --- %...>s for the last.
%...t | Time, in common log format time format (standard english format)
%...{format}t | The time, in the form given by format, which should be in strftime(3) format. (potentially localized)
%...T | The time taken to serve the request, in seconds.
%...u | Remote user (from auth; may be bogus if return status (%s) is 401)
%...U | The URL path requested, not including any query string.
%...v | The canonical ServerName of the server serving the request.
%...V | The server name according to the UseCanonicalName setting.
%...X Connection status when response is completed:
X = | connection aborted before the response completed.
+ = | connection may be kept alive after the response is sent.
- = | connection will be closed after the response is sent.

(This directive was %...c in late versions of Apache 1.3, but this conflicted with the historical ssl %...{var}c syntax.)

%...I | Bytes received, including request and headers, cannot be zero. You need to enable mod_logio to use this.
%...O | Bytes sent, including headers, cannot be zero. You need to enable mod_logio to use this.

The "..." can be nothing at all (e.g., "%h %u %r %s %b"), or it can indicate conditions for inclusion of the item (which will cause it to be replaced with "-" if the condition is not met). The forms of condition are a list of HTTP status codes, which may or may not be preceded by "!". Thus, "%400,501{User-agent}i" logs User-agent: on 400 errors and 501 errors (Bad Request, Not Implemented) only; "%!200,304,302{Referer}i" logs Referer: on all requests which did not return some sort of normal status.

Note that in httpd 2.0 versions prior to 2.0.46, no escaping was performed on the strings from %...r, %...i and %...o. This was mainly to comply with the requirements of the Common Log Format. This implied that clients could insert control characters into the log, so you had to be quite careful when dealing with raw log files.

For security reasons, starting with 2.0.46, non-printable and other special characters are escaped mostly by using \xhh sequences, where hh stands for the hexadecimal representation of the raw byte. Exceptions from this rule are " and \ which are escaped by prepending a backslash, and all whitespace characters which are written in their C-style notation (\n, \t etc).

Some commonly used log format strings are:

Common Log Format (CLF)
"%h %l %u %t \"%r\" %>s %b"
Common Log Format with Virtual Host
"%v %h %l %u %t \"%r\" %>s %b"
NCSA extended/combined log format
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
Referer log format
"%{Referer}i -> %U"
Agent (Browser) log format
"%{User-agent}i"

Note that the canonical ServerName and Listen of the server serving the request are used for %v and %p respectively. This happens regardless of the UseCanonicalName setting because otherwise log analysis programs would have to duplicate the entire vhost matching algorithm in order to decide what host really served the request.

Security Considerations

See the security tips document for details on why your security could be compromised if the directory where logfiles are stored is writable by anyone other than the user that starts the server.

CookieLog Directive

Description: | Sets filename for the logging of cookies
Syntax: | CookieLog filename
Context: | server config, virtual host
Status: | Base
Module: | mod_log_config
Compatibility: | This directive is deprecated.

The CookieLog directive sets the filename for logging of cookies. The filename is relative to the ServerRoot. This directive is included only for compatibility with mod_cookies, and is deprecated.

CustomLog Directive

Description: | Sets filename and format of log file
Syntax: | CustomLog file|pipe format|nickname [env=[!]environment-variable]
Context: | server config, virtual host
Status: | Base
Module: | mod_log_config

The CustomLog directive is used to log requests to the server. A log format is specified, and the logging can optionally be made conditional on request characteristics using environment variables.

The first argument, which specifies the location to which the logs will be written, can take one of the following two types of values:

file
A filename, relative to the ServerRoot.
pipe
The pipe character "|", followed by the path to a program to receive the log information on its standard input.

Security:

If a program is used, then it will be run as the user who started httpd. This will be root if the server was started by root; be sure that the program is secure.

Note

When entering a file path on non-Unix platforms, care should be taken to make sure that only forward slashed are used even though the platform may allow the use of back slashes. In general it is a good idea to always use forward slashes throughout the configuration files.

The second argument specifies what will be written to the log file. It can specify either a nickname defined by a previous LogFormat directive, or it can be an explicit format string as described in the log formats section.

For example, the following two sets of directives have exactly the same effect:

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

The third argument is optional and controls whether or not to log a particular request based on the presence or absence of a particular variable in the server environment. If the specified environment variable is set for the request (or is not set, in the case of a 'env=!name' clause), then the request will be logged.

Environment variables can be set on a per-request basis using the mod_setenvif and/or mod_rewrite modules. For example, if you want to record requests for all GIF images on your server in a separate logfile but not in your main log, you can use:

SetEnvIf Request_URI \.gif$ gif-image
CustomLog gif-requests.log common env=gif-image
CustomLog nongif-requests.log common env=!gif-image

LogFormat Directive

Description: | Describes a format for use in a log file
Syntax: | LogFormat format|nickname [nickname]
Default: | LogFormat "%h %l %u %t \"%r\" %>s %b"
Context: | server config, virtual host
Status: | Base
Module: | mod_log_config

This directive specifies the format of the access log file.

The LogFormat directive can take one of two forms. In the first form, where only one argument is specified, this directive sets the log format which will be used by logs specified in subsequent TransferLog directives. The single argument can specify an explicit format as discussed in the custom log formats section above. Alternatively, it can use a nickname to refer to a log format defined in a previous LogFormat directive as described below.

The second form of the LogFormat directive associates an explicit format with a nickname. This nickname can then be used in subsequent LogFormat or CustomLog directives rather than repeating the entire format string. A LogFormat directive that defines a nickname does nothing else -- that is, it only defines the nickname, it doesn't actually apply the format and make it the default. Therefore, it will not affect subsequent TransferLog directives. In addition, LogFormat cannot use one nickname to define another nickname. Note that the nickname should not contain percent signs (%).

Example

LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common

TransferLog Directive

Description: | Specify location of a log file
Syntax: | TransferLog file|pipe
Context: | server config, virtual host
Status: | Base
Module: | mod_log_config

This directive has exactly the same arguments and effect as the CustomLog directive, with the exception that it does not allow the log format to be specified explicitly or for conditional logging of requests. Instead, the log format is determined by the most recently specified LogFormat directive which does not define a nickname. Common Log Format is used if no other format has been specified.

Example

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


mod_logio - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_logio

Description: | Logging of input and output bytes per request
Status: | Base
Module Identifier: | logio_module
Source File: | mod_logio.c

Summary

This module provides the logging of input and output number of bytes received/sent per request. The numbers reflect the actual bytes as received on the network, which then takes into account the headers and bodies of requests and responses. The counting is done before SSL/TLS on input and after SSL/TLS on output, so the numbers will correctly reflect any changes made by encryption.

This module requires mod_log_config.

See also

  • mod_log_config
  • Apache Log Files

Custom Log Formats

This modules adds two new logging directives. The characteristics of the request itself are logged by placing "%" directives in the format string, which are replaced in the log file by the values as follows:

Format String | Description
%...I | Bytes received, including request and headers, cannot be zero.
%...O | Bytes sent, including headers, cannot be zero.

Usually, the functionality is used like this:

Combined I/O log format:
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\" %I %O"


mod_mem_cache - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_mem_cache

Description: | Content cache keyed to URIs
Status: | Experimental
Module Identifier: | mem_cache_module
Source File: | mod_mem_cache.c

Summary

This module is experimental. Documentation is still under development...

This module requires the service of mod_cache. It acts as a support module for mod_cache and provides a memory based storage manager. mod_mem_cache can be configured to operate in two modes: caching open file descriptors or caching objects in heap storage. mod_mem_cache is most useful when used to cache locally generated content or to cache backend server content for mod_proxy configured for ProxyPass (aka reverse proxy).

Content is stored in and retrieved from the cache using URI based keys. Content with access protection is not cached.

See also

  • mod_cache
  • mod_disk_cache

MCacheMaxObjectCount Directive

Description: | The maximum number of objects allowed to be placed in the cache
Syntax: | MCacheMaxObjectCount value
Default: | MCacheMaxObjectCount 1009
Context: | server config
Status: | Experimental
Module: | mod_mem_cache

The MCacheMaxObjectCount directive sets the maximum number of objects to be cached. The value is used to create the open hash table. If a new object needs to be inserted in the cache and the maximum number of objects has been reached, an object will be removed to allow the new object to be cached. The object to be removed is selected using the algorithm specified by MCacheRemovalAlgorithm.

Example

MCacheMaxObjectCount 13001

MCacheMaxObjectSize Directive

Description: | The maximum size (in bytes) of a document allowed in the cache
Syntax: | MCacheMaxObjectSize bytes
Default: | MCacheMaxObjectSize 10000
Context: | server config
Status: | Experimental
Module: | mod_mem_cache

The MCacheMaxObjectSize directive sets the maximum allowable size, in bytes, of a document for it to be considered cacheable.

Example

MCacheMaxObjectSize 6400000

Note

The value of MCacheMaxObjectSize must be greater than the value specified by the MCacheMinObjectSize directive.

MCacheMaxStreamingBuffer Directive

Description: | Maximum amount of a streamed response to buffer in memory before declaring the response uncacheable
Syntax: | MCacheMaxStreamingBuffer size_in_bytes
Default: | MCacheMaxStreamingBuffer the smaller of 100000 or MCacheMaxObjectSize
Context: | server config
Status: | Experimental
Module: | mod_mem_cache

The MCacheMaxStreamingBuffer directive specifies the maximum number of bytes of a streamed response to buffer before deciding that the response is too big to cache. A streamed response is one in which the entire content is not immediately available and in which the Content-Length may not be known. Sources of streaming responses include proxied responses and the output of CGI scripts. By default, a streamed response will not be cached unless it has a Content-Length header. The reason for this is to avoid using a large amount of memory to buffer a partial response that might end up being too large to fit in the cache. The MCacheMaxStreamingBuffer directive allows buffering of streamed responses that don't contain a Content-Length up to the specified maximum amount of space. If the maximum buffer space is reached, the buffered content is discarded and the attempt to cache is abandoned.

Note:

Using a nonzero value for MCacheMaxStreamingBuffer will not delay the transmission of the response to the client. As soon as mod_mem_cache copies a block of streamed content into a buffer, it sends the block on to the next output filter for delivery to the client.

# Enable caching of streamed responses up to 64KB:
MCacheMaxStreamingBuffer 65536

MCacheMinObjectSize Directive

Description: | The minimum size (in bytes) of a document to be allowed in the cache
Syntax: | MCacheMinObjectSize bytes
Default: | MCacheMinObjectSize 0
Context: | server config
Status: | Experimental
Module: | mod_mem_cache

The MCacheMinObjectSize directive sets the minimum size in bytes of a document for it to be considered cacheable.

Example

MCacheMinObjectSize 10000

MCacheRemovalAlgorithm Directive

Description: | The algorithm used to select documents for removal from the cache
Syntax: | MCacheRemovalAlgorithm LRU|GDSF
Default: | MCacheRemovalAlgorithm GDSF
Context: | server config
Status: | Experimental
Module: | mod_mem_cache

The MCacheRemovalAlgorithm directive specifies the algorithm used to select documents for removal from the cache. Two choices are available:

LRU (Least Recently Used)
LRU removes the documents that have not been accessed for the longest time.
GDSF (GreadyDual-Size)
GDSF assigns a priority to cached documents based on the cost of a cache miss and the size of the document. Documents with the lowest priority are removed first.

Example

MCacheRemovalAlgorithm GDSF
MCacheRemovalAlgorithm LRU

MCacheSize Directive

Description: | The maximum amount of memory used by the cache in KBytes
Syntax: | MCacheSize KBytes
Default: | MCacheSize 100
Context: | server config
Status: | Experimental
Module: | mod_mem_cache

The MCacheSize directive sets the maximum amount of memory to be used by the cache, in KBytes (1024-byte units). If a new object needs to be inserted in the cache and the size of the object is greater than the remaining memory, objects will be removed until the new object can be cached. The object to be removed is selected using the algorithm specified by MCacheRemovalAlgorithm.

Example

MCacheSize 700000

Note

The MCacheSize value must be greater than the value specified by the MCacheMaxObjectSize directive.


mod_mime - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_mime

Description: | Associates the requested filename's extensions with the file's behavior (handlers and filters) and content (mime-type, language, character set and encoding)
Status: | Base
Module Identifier: | mime_module
Source File: | mod_mime.c

Summary

This module is used to associate various bits of "meta information" with files by their filename extensions. This information relates the filename of the document to it's mime-type, language, character set and encoding. This information is sent to the browser, and participates in content negotiation, so the user's preferences are respected when choosing one of several possible files to serve. See mod_negotiation for more information about content negotiation.

The directives AddCharset, AddEncoding, AddLanguage and AddType are all used to map file extensions onto the meta-information for that file. Respectively they set the character set, content-encoding, content-language, and MIME-type (content-type) of documents. The directive TypesConfig is used to specify a file which also maps extensions onto MIME types.

In addition, mod_mime may define the handler and filters that originate and process content. The directives AddHandler, AddOutputFilter, and AddInputFilter control the modules or scripts that serve the document. The MultiviewsMatch directive allows mod_negotiation to consider these file extensions to be included when testing Multiviews matches.

While mod_mime associates meta-information with filename extensions, the core server provides directives that are used to associate all the files in a given container (e.g., <Location>, <Directory>, or <Files>) with particular meta-information. These directives include ForceType, SetHandler, SetInputFilter, and SetOutputFilter. The core directives override any filename extension mappings defined in mod_mime.

Note that changing the meta-information for a file does not change the value of the Last-Modified header. Thus, previously cached copies may still be used by a client or proxy, with the previous headers. If you change the meta-information (language, content type, character set or encoding) you may need to 'touch' affected files (updating their last modified date) to ensure that all visitors are receive the corrected content headers.

See also

  • MimeMagicFile
  • AddDefaultCharset
  • ForceType
  • DefaultType
  • SetHandler
  • SetInputFilter
  • SetOutputFilter

Files with Multiple Extensions

Files can have more than one extension, and the order of the extensions is normally irrelevant. For example, if the file welcome.html.fr maps onto content type text/html and language French then the file welcome.fr.html will map onto exactly the same information. If more than one extension is given which maps onto the same type of meta-information, then the one to the right will be used, except for languages and content encodings. For example, if .gif maps to the MIME-type image/gif and .html maps to the MIME-type text/html, then the file welcome.gif.html will be associated with the MIME-type text/html.

Languages and content encodings are treated accumulative, because one can assign more than one language or encoding to a particular ressource. For example, the file welcome.html.en.de will be delivered with Content-Language: en, de and Content-Type: text/html.

Care should be taken when a file with multiple extensions gets associated with both a MIME-type and a handler. This will usually result in the request being by the module associated with the handler. For example, if the .imap extension is mapped to the handler imap-file (from mod_imap) and the .html extension is mapped to the MIME-type text/html, then the file world.imap.html will be associated with both the imap-file handler and text/html MIME-type. When it is processed, the imap-file handler will be used, and so it will be treated as a mod_imap imagemap file.

Content encoding

A file of a particular MIME type can additionally be encoded a particular way to simplify transmission over the Internet. While this usually will refer to compression, such as gzip, it can also refer to encryption, such a pgp or to an encoding such as UUencoding, which is designed for transmitting a binary file in an ASCII (text) format.

The HTTP/1.1 RFC, section 14.11 puts it this way:

The Content-Encoding entity-header field is used as a modifier to the media-type. When present, its value indicates what additional content codings have been applied to the entity-body, and thus what decoding mechanisms must be applied in order to obtain the media-type referenced by the Content-Type header field. Content-Encoding is primarily used to allow a document to be compressed without losing the identity of its underlying media type.

By using more than one file extension (see section above about multiple file extensions), you can indicate that a file is of a particular type, and also has a particular encoding.

For example, you may have a file which is a Microsoft Word document, which is pkzipped to reduce its size. If the .doc extension is associated with the Microsoft Word file type, and the .zip extension is associated with the pkzip file encoding, then the file Resume.doc.zip would be known to be a pkzip'ed Word document.

Apache sends a Content-encoding header with the resource, in order to tell the client browser about the encoding method.

Content-encoding: pkzip

Character sets and languages

In addition to file type and the file encoding, another important piece of information is what language a particular document is in, and in what character set the file should be displayed. For example, the document might be written in the Vietnamese alphabet, or in Cyrillic, and should be displayed as such. This information, also, is transmitted in HTTP headers.

The character set, language, encoding and mime type are all used in the process of content negotiation (See mod_negotiation) to determine which document to give to the client, when there are alternative documents in more than one character set, language, encoding or mime type. All filename extensions associations created with AddCharset, AddEncoding, AddLanguage and AddType directives (and extensions listed in the MimeMagicFile) participate in this select process. Filename extensions that are only associated using the AddHandler, AddInputFilter or AddOutputFilter directives may be included or excluded from matching by using the MultiviewsMatch directive.

Charset

To convey this further information, Apache optionally sends a Content-Language header, to specify the language that the document is in, and can append additional information onto the Content-Type header to indicate the particular character set that should be used to correctly render the information.

Content-Language: en, fr
Content-Type: text/plain; charset=ISO-8859-1

The language specification is the two-letter abbreviation for the language. The charset is the name of the particular character set which should be used.

AddCharset Directive

Description: | Maps the given filename extensions to the specified content charset
Syntax: | AddCharset charset extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The AddCharset directive maps the given filename extensions to the specified content charset. charset is the MIME charset parameter of filenames containing extension. This mapping is added to any already in force, overriding any mappings that already exist for the same extension.

Example

AddLanguage ja .ja
AddCharset EUC-JP .euc
AddCharset ISO-2022-JP .jis
AddCharset SHIFT_JIS .sjis

Then the document xxxx.ja.jis will be treated as being a Japanese document whose charset is ISO-2022-JP (as will the document xxxx.jis.ja). The AddCharset directive is useful for both to inform the client about the character encoding of the document so that the document can be interpreted and displayed appropriately, and for content negotiation, where the server returns one from several documents based on the client's charset preference.

The extension argument is case-insensitive, and can be specified with or without a leading dot.

See also

  • mod_negotiation
  • AddDefaultCharset

AddEncoding Directive

Description: | Maps the given filename extensions to the specified encoding type
Syntax: | AddEncoding MIME-enc extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The AddEncoding directive maps the given filename extensions to the specified encoding type. MIME-enc is the MIME encoding to use for documents containing the extension. This mapping is added to any already in force, overriding any mappings that already exist for the same extension.

Example

AddEncoding x-gzip .gz
AddEncoding x-compress .Z

This will cause filenames containing the .gz extension to be marked as encoded using the x-gzip encoding, and filenames containing the .Z extension to be marked as encoded with x-compress.

Old clients expect x-gzip and x-compress, however the standard dictates that they're equivalent to gzip and compress respectively. Apache does content encoding comparisons by ignoring any leading x-. When responding with an encoding Apache will use whatever form (i.e., x-foo or foo) the client requested. If the client didn't specifically request a particular form Apache will use the form given by the AddEncoding directive. To make this long story short, you should always use x-gzip and x-compress for these two specific encodings. More recent encodings, such as deflate should be specified without the x-.

The extension argument is case-insensitive, and can be specified with or without a leading dot.

AddHandler Directive

Description: | Maps the filename extensions to the specified handler
Syntax: | AddHandler handler-name extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

Files having the name extension will be served by the specified handler-name. This mapping is added to any already in force, overriding any mappings that already exist for the same extension. For example, to activate CGI scripts with the file extension .cgi, you might use:

AddHandler cgi-script .cgi

Once that has been put into your httpd.conf file, any file containing the .cgi extension will be treated as a CGI program.

The extension argument is case-insensitive, and can be specified with or without a leading dot.

See also

  • SetHandler

AddInputFilter Directive

Description: | Maps filename extensions to the filters that will process client requests
Syntax: | AddInputFilter filter[;filter...] extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime
Compatibility: | AddInputFilter is only available in Apache 2.0.26 and later.

AddInputFilter maps the filename extension extension to the filters which will process client requests and POST input when they are received by the server. This is in addition to any filters defined elsewhere, including the SetInputFilter directive. This mapping is merged over any already in force, overriding any mappings that already exist for the same extension.

If more than one filter is specified, they must be separated by semicolons in the order in which they should process the content. Both the filter and extension arguments are case-insensitive, and the extension may be specified with or without a leading dot.

AddLanguage Directive

Description: | Maps the given filename extension to the specified content language
Syntax: | AddLanguage MIME-lang extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The AddLanguage directive maps the given filename extension to the specified content language. MIME-lang is the MIME language of filenames containing extension. This mapping is added to any already in force, overriding any mappings that already exist for the same extension.

Example

AddEncoding x-compress .Z
AddLanguage en .en
AddLanguage fr .fr

Then the document xxxx.en.Z will be treated as being a compressed English document (as will the document xxxx.Z.en). Although the content language is reported to the client, the browser is unlikely to use this information. The AddLanguage directive is more useful for content negotiation, where the server returns one from several documents based on the client's language preference.

If multiple language assignments are made for the same extension, the last one encountered is the one that is used. That is, for the case of:

AddLanguage en .en
AddLanguage en-uk .en
AddLanguage en-us .en

documents with the extension .en would be treated as being en-us.

The extension argument is case-insensitive, and can be specified with or without a leading dot.

See also

  • mod_negotiation

AddOutputFilter Directive

Description: | Maps filename extensions to the filters that will process responses from the server
Syntax: | AddOutputFilter filter[;filter...] extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime
Compatibility: | AddOutputFilter is only available in Apache 2.0.26 and later.

The AddOutputFilter directive maps the filename extension extension to the filters which will process responses from the server before they are sent to the client. This is in addition to any filters defined elsewhere, including SetOutputFilter and AddOutputFilterByType directive. This mapping is merged over any already in force, overriding any mappings that already exist for the same extension.

For example, the following configuration will process all .shtml files for server-side includes and will then compress the output using mod_deflate.

AddOutputFilter INCLUDES;DEFLATE shtml

If more than one filter is specified, they must be separated by semicolons in the order in which they should process the content. Both the filter and extension arguments are case-insensitive, and the extension may be specified with or without a leading dot.

See also

  • RemoveOutputFilter

AddType Directive

Description: | Maps the given filename extensions onto the specified content type
Syntax: | AddType MIME-type extension [extension] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The AddType directive maps the given filename extensions onto the specified content type. MIME-type is the MIME type to use for filenames containing extension. This mapping is added to any already in force, overriding any mappings that already exist for the same extension. This directive can be used to add mappings not listed in the MIME types file (see the TypesConfig directive).

Example

AddType image/gif .gif

It is recommended that new MIME types be added using the AddType directive rather than changing the TypesConfig file.

The extension argument is case-insensitive, and can be specified with or without a leading dot.

See also

  • DefaultType
  • ForceType

DefaultLanguage Directive

Description: | Sets all files in the given scope to the specified language
Syntax: | DefaultLanguage MIME-lang
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The DefaultLanguage directive tells Apache that all files in the directive's scope (e.g., all files covered by the current <Directory> container) that don't have an explicit language extension (such as .fr or .de as configured by AddLanguage) should be considered to be in the specified MIME-lang language. This allows entire directories to be marked as containing Dutch content, for instance, without having to rename each file. Note that unlike using extensions to specify languages, DefaultLanguage can only specify a single language.

If no DefaultLanguage directive is in force, and a file does not have any language extensions as configured by AddLanguage, then that file will be considered to have no language attribute.

Example

DefaultLanguage en

See also

  • mod_negotiation

ModMimeUsePathInfo Directive

Description: | Tells mod_mime to treat path_info components as part of the filename
Syntax: | ModMimeUsePathInfo On|Off
Default: | ModMimeUsePathInfo Off
Context: | directory
Status: | Base
Module: | mod_mime
Compatibility: | Available in Apache 2.0.41 and later

The ModMimeUsePathInfo directive is used to combine the filename with the path_info URL component to apply mod_mime's directives to the request. The default value is Off - therefore, the path_info component is ignored.

This directive is recommended when you have a virtual filesystem.

Example

ModMimeUsePathInfo On

If you have a request for /bar/foo.shtml where /bar is a Location and ModMimeUsePathInfo is On, mod_mime will treat the incoming request as /bar/foo.shtml and directives like AddOutputFilter INCLUDES .shtml will add the INCLUDES filter to the request. If ModMimeUsePathInfo is not set, the INCLUDES filter will not be added.

See also

  • AcceptPathInfo

MultiviewsMatch Directive

Description: | The types of files that will be included when searching for a matching file with MultiViews
Syntax: | MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers [Handlers|Filters]
Default: | MultiviewsMatch NegotiatedOnly
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime
Compatibility: | Available in Apache 2.0.26 and later.

MultiviewsMatch permits three different behaviors for mod_negotiation's Multiviews feature. Multiviews allows a request for a file, e.g. index.html, to match any negotiated extensions following the base request, e.g. index.html.en, index.html.fr, or index.html.gz.

The NegotiatedOnly option provides that every extension following the base name must correlate to a recognized mod_mime extension for content negotation, e.g. Charset, Content-Type, Language, or Encoding. This is the strictest implementation with the fewest unexpected side effects, and is the default behavior.

To include extensions associated with Handlers and/or Filters, set the MultiviewsMatch directive to either Handlers, Filters, or both option keywords. If all other factors are equal, the smallest file will be served, e.g. in deciding between index.html.cgi of 500 bytes and index.html.pl of 1000 bytes, the .cgi file would win in this example. Users of .asis files might prefer to use the Handler option, if .asis files are associated with the asis-handler.

You may finally allow Any extensions to match, even if mod_mime doesn't recognize the extension. This was the behavior in Apache 1.3, and can cause unpredicatable results, such as serving .old or .bak files the webmaster never expected to be served.

For example, the following configuration will allow handlers and filters to participate in Multviews, but will exclude unknown files:

MultiviewsMatch Handlers Filters

See also

  • Options
  • mod_negotiation

RemoveCharset Directive

Description: | Removes any character set associations for a set of file extensions
Syntax: | RemoveCharset extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime
Compatibility: | RemoveCharset is only available in Apache 2.0.24 and later.

The RemoveCharset directive removes any character set associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files.

The extension argument is case-insensitive, and can be specified with or without a leading dot.

Example

RemoveCharset .html .shtml

RemoveEncoding Directive

Description: | Removes any content encoding associations for a set of file extensions
Syntax: | RemoveEncoding extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The RemoveEncoding directive removes any encoding associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files. An example of its use might be:

/foo/.htaccess:

AddEncoding x-gzip .gz
AddType text/plain .asc
<Files *.gz.asc>
RemoveEncoding .gz
 </Files>

This will cause foo.gz to be marked as being encoded with the gzip method, but foo.gz.asc as an unencoded plaintext file.

Note

RemoveEncoding directives are processed after any AddEncoding directives, so it is possible they may undo the effects of the latter if both occur within the same directory configuration.

The extension argument is case-insensitive, and can be specified with or without a leading dot.

RemoveHandler Directive

Description: | Removes any handler associations for a set of file extensions
Syntax: | RemoveHandler extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The RemoveHandler directive removes any handler associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files. An example of its use might be:

/foo/.htaccess:

AddHandler server-parsed .html

/foo/bar/.htaccess:

RemoveHandler .html

This has the effect of returning .html files in the /foo/bar directory to being treated as normal files, rather than as candidates for parsing (see the mod_include module).

The extension argument is case-insensitive, and can be specified with or without a leading dot.

RemoveInputFilter Directive

Description: | Removes any input filter associations for a set of file extensions
Syntax: | RemoveInputFilter extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime
Compatibility: | RemoveInputFilter is only available in Apache 2.0.26 and later.

The RemoveInputFilter directive removes any input filter associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files.

The extension argument is case-insensitive, and can be specified with or without a leading dot.

RemoveLanguage Directive

Description: | Removes any language associations for a set of file extensions
Syntax: | RemoveLanguage extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime
Compatibility: | RemoveLanguage is only available in Apache 2.0.24 and later.

The RemoveLanguage directive removes any language associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files.

The extension argument is case-insensitive, and can be specified with or without a leading dot.

RemoveOutputFilter Directive

Description: | Removes any output filter associations for a set of file extensions
Syntax: | RemoveOutputFilter extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime
Compatibility: | RemoveOutputFilter is only available in Apache 2.0.26 and later.

The RemoveOutputFilter directive removes any output filter associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files.

The extension argument is case-insensitive, and can be specified with or without a leading dot.

Example

RemoveOutputFilter shtml

See also

  • AddOutputFilter

RemoveType Directive

Description: | Removes any content type associations for a set of file extensions
Syntax: | RemoveType extension [extension] ...
Context: | virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_mime

The RemoveType directive removes any MIME type associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files. An example of its use might be:

/foo/.htaccess:

RemoveType .cgi

This will remove any special handling of .cgi files in the /foo/ directory and any beneath it, causing the files to be treated as being of the DefaultType.

Note

RemoveType directives are processed after any AddType directives, so it is possible they may undo the effects of the latter if both occur within the same directory configuration.

The extension argument is case-insensitive, and can be specified with or without a leading dot.

TypesConfig Directive

Description: | The location of the mime.types file
Syntax: | TypesConfig file-path
Default: | TypesConfig conf/mime.types
Context: | server config
Status: | Base
Module: | mod_mime

The TypesConfig directive sets the location of the MIME types configuration file. File-path is relative to the ServerRoot. This file sets the default list of mappings from filename extensions to content types. Most administrators use the provided mime.types file, which associates common filename extensions with IANA registered content types. The current list is maintained at http://www.isi.edu/in-notes/iana/assignments/media-types/media-types. This simplifies the httpd.conf file by providing the majority of media-type definitions, and may be overridden by AddType directives as needed. You should not edit the mime.types file, because it may be replaced when you upgrade your server.

The file contains lines in the format of the arguments to an AddType directive:

MIME-type [extension] ...

The case of the extension does not matter. Blank lines, and lines beginning with a hash character (#) are ignored.

Please do not send requests to the Apache HTTP Server Project to add any new entries in the distributed mime.types file unless (1) they are already registered with IANA, and (2) they use widely accepted, non-conflicting filename extensions across platforms. category/x-subtype requests will be automatically rejected, as will any new two-letter extensions as they will likely conflict later with the already crowded language and character set namespace.

See also

  • mod_mime_magic


mod_mime_magic - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_mime_magic

Description: | Determines the MIME type of a file by looking at a few bytes of its contents
Status: | Extension
Module 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


mod_negotiation - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_negotiation

Description: | Provides for content negotiation
Status: | Base
Module Identifier: | negotiation_module
Source File: | mod_negotiation.c

Summary

Content negotiation, or more accurately content selection, is the selection of the document that best matches the clients capabilities, from one of several available documents. There are two implementations of this.

  • A type map (a file with the handler type-map) which explicitly lists the files containing the variants.
  • A MultiViews search (enabled by the MultiViews Options), where the server does an implicit filename pattern match, and choose from amongst the results.

See also

  • Options
  • mod_mime
  • Content Negotiation

Type maps

A type map has a format similar to RFC822 mail headers. It contains document descriptions separated by blank lines, with lines beginning with a hash character ('#') treated as comments. A document description consists of several header records; records may be continued on multiple lines if the continuation lines start with spaces. The leading space will be deleted and the lines concatenated. A header record consists of a keyword name, which always ends in a colon, followed by a value. Whitespace is allowed between the header name and value, and between the tokens of value. The headers allowed are:

Content-Encoding:
The encoding of the file. Apache only recognizes encodings that are defined by an AddEncoding directive. This normally includes the encodings x-compress for compress'd files, and x-gzip for gzip'd files. The x- prefix is ignored for encoding comparisons.
Content-Language:
The language(s) of the variant, as an Internet standard language tag (RFC 1766). An example is en, meaning English. If the variant contains more than one language, they are separated by a comma.
Content-Length:
The length of the file, in bytes. If this header is not present, then the actual length of the file is used.
Content-Type:
The MIME media type of the document, with optional parameters. Parameters are separated from the media type and from one another by a semi-colon, with a syntax of name=value. Common parameters include:
level
an integer specifying the version of the media type. For text/html this defaults to 2, otherwise 0.
qs
a floating-point number with a value in the range 0.0 to 1.0, indicating the relative 'quality' of this variant compared to the other available variants, independent of the client's capabilities. For example, a jpeg file is usually of higher source quality than an ascii file if it is attempting to represent a photograph. However, if the resource being represented is ascii art, then an ascii file would have a higher source quality than a jpeg file. All qs values are therefore specific to a given resource.

Example

Content-Type: image/jpeg; qs=0.8

URI:
uri of the file containing the variant (of the given media type, encoded with the given content encoding). These are interpreted as URLs relative to the map file; they must be on the same server (!), and they must refer to files to which the client would be granted access if they were to be requested directly.
Body:
New in Apache 2.0, the actual content of the resource may be included in the type-map file using the Body header. This header must contain a string that designates a delimiter for the body content. Then all following lines in the type map file will be considered part of the resource body until the delimiter string is found.

Example:

Body:----xyz----
<html>
<body>
<p>Content of the page.</p>
</body>
</html>
----xyz----

MultiViews

A MultiViews search is enabled by the MultiViews Options. If the server receives a request for /some/dir/foo and /some/dir/foo does not exist, then the server reads the directory looking for all files named foo.*, and effectively fakes up a type map which names all those files, assigning them the same media types and content-encodings it would have if the client had asked for one of them by name. It then chooses the best match to the client's requirements, and returns that document.

CacheNegotiatedDocs Directive

Description: | Allows content-negotiated documents to be cached by proxy servers
Syntax: | CacheNegotiatedDocs On|Off
Default: | CacheNegotiatedDocs Off
Context: | server config, virtual host
Status: | Base
Module: | mod_negotiation
Compatibility: | The syntax changed in version 2.0.

If set, this directive allows content-negotiated documents to be cached by proxy servers. This could mean that clients behind those proxys could retrieve versions of the documents that are not the best match for their abilities, but it will make caching more efficient.

This directive only applies to requests which come from HTTP/1.0 browsers. HTTP/1.1 provides much better control over the caching of negotiated documents, and this directive has no effect in responses to HTTP/1.1 requests.

Prior to version 2.0, CacheNegotiatedDocs did not take an argument; it was turned on by the presence of the directive by itself.

ForceLanguagePriority Directive

Description: | Action to take if a single acceptable document is not found
Syntax: | ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]
Default: | ForceLanguagePriority Prefer
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_negotiation
Compatibility: | Available in version 2.0.30 and later

The ForceLanguagePriority directive uses the given LanguagePriority to satisfy negotation where the server could otherwise not return a single matching document.

ForceLanguagePriority Prefer uses LanguagePriority to serve a one valid result, rather than returning an HTTP result 300 (MULTIPLE CHOICES) when there are several equally valid choices. If the directives below were given, and the user's Accept-Language header assigned en and de each as quality .500 (equally acceptable) then the first matching variant, en, will be served.

LanguagePriority en fr de
ForceLanguagePriority Prefer

ForceLanguagePriority Fallback uses LanguagePriority to serve a valid result, rather than returning an HTTP result 406 (NOT ACCEPTABLE). If the directives below were given, and the user's Accept-Language only permitted an es language response, but such a variant isn't found, then the first variant from the LanguagePriority list below will be served.

LanguagePriority en fr de
ForceLanguagePriority Fallback

Both options, Prefer and Fallback, may be specified, so either the first matching variant from LanguagePriority will be served if more than one variant is acceptable, or first available document will be served if none of the variants matched the client's acceptable list of languages.

See also

  • AddLanguage

LanguagePriority Directive

Description: | The precendence of language variants for cases where the client does not express a preference
Syntax: | LanguagePriority MIME-lang [MIME-lang] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_negotiation

The LanguagePriority sets the precedence of language variants for the case where the client does not express a preference, when handling a MultiViews request. The list of MIME-lang are in order of decreasing preference.

Example:

LanguagePriority en fr de

For a request for foo.html, where foo.html.fr and foo.html.de both existed, but the browser did not express a language preference, then foo.html.fr would be returned.

Note that this directive only has an effect if a 'best' language cannot be determined by any other means or the ForceLanguagePriority directive is not None. Correctly implemented HTTP/1.1 requests will mean this directive has no effect.

See also

  • AddLanguage


mod_nw_ssl - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_nw_ssl

Description: | Enable SSL encryption for NetWare
Status: | Base
Module 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.

SecureListen Directive

Description: | Enables SSL encryption for the specified port
Syntax: | SecureListen [IP-address:]portnumber Certificate-Name [MUTUAL]
Context: | server config
Status: | Base
Module: | mod_nw_ssl

Specifies the port and the eDirectory based certificate name that will be used to enable SSL encryption. An optional third parameter also enables mutual authentication.


mod_proxy - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_proxy

Description: | HTTP/1.1 proxy/gateway server
Status: | Extension
Module Identifier: | proxy_module
Source File: | mod_proxy.c

Summary

Warning

Do not enable proxying with ProxyRequests until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

This module implements a proxy/gateway for Apache. It implements proxying capability for FTP, CONNECT (for SSL), HTTP/0.9, HTTP/1.0, and HTTP/1.1. The module can be configured to connect to other proxy modules for these and other protocols.

Apache's proxy features are divided into several modules in addition to mod_proxy: mod_proxy_http, mod_proxy_ftp and mod_proxy_connect. Thus, if you want to use one or more of the particular proxy functions, load mod_proxy and the appropriate module(s) into the server (either statically at compile-time or dynamically via the LoadModule directive).

In addition, extended features are provided by other modules. Caching is provided by mod_cache and related modules. The ability to contact remote servers using the SSL/TLS protocol is provided by the SSLProxy* directives of mod_ssl. These additional modules will need to be loaded and configured to take advantage of these features.

See also

  • mod_cache
  • mod_proxy_http
  • mod_proxy_ftp
  • mod_proxy_connect
  • mod_ssl

Forward and Reverse Proxies

Apache can be configured in both a forward and reverse proxy mode.

An ordinary forward proxy is an intermediate server that sits between the client and the origin server. In order to get content from the origin server, the client sends a request to the proxy naming the origin server as the target and the proxy then requests the content from the origin server and returns it to the client. The client must be specially configured to use the forward proxy to access other sites.

A typical usage of a forward proxy is to provide Internet access to internal clients that are otherwise restricted by a firewall. The forward proxy can also use caching (as provided by mod_cache) to reduce network usage.

The forward proxy is activated using the ProxyRequests directive. Because forward proxys allow clients to access arbitrary sites through your server and to hide their true origin, it is essential that you secure your server so that only authorized clients can access the proxy before activating a forward proxy.

A reverse proxy, by contrast, appears to the client just like an ordinary web server. No special configuration on the client is necessary. The client makes ordinary requests for content in the name-space of the reverse proxy. The reverse proxy then decides where to send those requests, and returns the content as if it was itself the origin.

A typical usage of a reverse proxy is to provide Internet users access to a server that is behind a firewall. Reverse proxies can also be used to balance load among several back-end servers, or to provide caching for a slower back-end server. In addition, reverse proxies can be used simply to bring several servers into the same URL space.

A reverse proxy is activated using the ProxyPass directive or the [P] flag to the RewriteRule directive. It is not necessary to turn ProxyRequests on in order to configure a reverse proxy.

Basic Examples

The examples below are only a very basic idea to help you get started. Please read the documentation on the individual directives.

In addition, if you wish to have caching enabled, consult the documentation from mod_cache.

Forward Proxy

ProxyRequests On
ProxyVia On

<Proxy *>
Order deny,allow
Deny from all
Allow from internal.example.com
 </Proxy>

Reverse Proxy

ProxyRequests Off

<Proxy *>
Order deny,allow
Allow from all
 </Proxy>

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

Controlling access to your proxy

You can control who can access your proxy via the <Proxy> control block as in the following example:

<Proxy *>
Order Deny,Allow
Deny from all
Allow from 192.168.0
 </Proxy>

For more information on access control directives, see mod_access.

Strictly limiting access is essential if you are using a forward proxy (using the ProxyRequests directive). Otherwise, your server can be used by any client to access arbitrary hosts while hiding his or her true identity. This is dangerous both for your network and for the Internet at large. When using a reverse proxy (using the ProxyPass directive with ProxyRequests Off), access control is less critical because clients can only contact the hosts that you have specifically configured.

FTP Proxy

Why doesn't file type xxx download via FTP?

You probably don't have that particular file type defined as application/octet-stream in your proxy's mime.types configuration file. A useful line can be

application/octet-stream   bin dms lha lzh exe class tgz taz

How can I force an FTP ASCII download of File xxx?

In the rare situation where you must download a specific file using the FTP ASCII transfer method (while the default transfer is in binary mode), you can override mod_proxy's default by suffixing the request with ;type=a to force an ASCII transfer. (FTP Directory listings are always executed in ASCII mode, however.)

How can I access FTP files outside of my home directory?

An FTP URI is interpreted relative to the home directory of the user who is logging in. Alas, to reach higher directory levels you cannot use /../, as the dots are interpreted by the browser and not actually sent to the FTP server. To address this problem, the so called Squid %2f hack was implemented in the Apache FTP proxy; it is a solution which is also used by other popular proxy servers like the Squid Proxy Cache. By prepending /%2f to the path of your request, you can make such a proxy change the FTP starting directory to / (instead of the home directory). For example, to retrieve the file /etc/motd, you would use the URL:

ftp://user@host/%2f/etc/motd

How can I hide the FTP cleartext password in my browser's URL line?

To log in to an FTP server by username and password, Apache uses different strategies. In absense of a user name and password in the URL altogether, Apache sends an anonymous login to the FTP server, i.e.,

user: anonymous
password: apache_proxy@

This works for all popular FTP servers which are configured for anonymous access.

For a personal login with a specific username, you can embed the user name into the URL, like in:

ftp://username@host/myfile

If the FTP server asks for a password when given this username (which it should), then Apache will reply with a 401 (Authorization required) response, which causes the Browser to pop up the username/password dialog. Upon entering the password, the connection attempt is retried, and if successful, the requested resource is presented. The advantage of this procedure is that your browser does not display the password in cleartext (which it would if you had used

ftp://username:password@host/myfile

in the first place).

Note

The password which is transmitted in such a way is not encrypted on its way. It travels between your browser and the Apache proxy server in a base64-encoded cleartext string, and between the Apache proxy and the FTP server as plaintext. You should therefore think twice before accessing your FTP server via HTTP (or before accessing your personal files via FTP at all!) When using unsecure channels, an eavesdropper might intercept your password on its way.

Slow Startup

If you're using the ProxyBlock directive, hostnames' IP addresses are looked up and cached during startup for later match test. This may take a few seconds (or more) depending on the speed with which the hostname lookups occur.

Intranet Proxy

An Apache proxy server situated in an intranet needs to forward external requests through the company's firewall (for this, configure the ProxyRemote directive to forward the respective scheme to the firewall proxy). However, when it has to access resources within the intranet, it can bypass the firewall when accessing hosts. The NoProxy directive is useful for specifying which hosts belong to the intranet and should be accessed directly.

Users within an intranet tend to omit the local domain name from their WWW requests, thus requesting "http://somehost/" instead of http://somehost.example.com/. Some commercial proxy servers let them get away with this and simply serve the request, implying a configured local domain. When the ProxyDomain directive is used and the server is configured for proxy service, Apache can return a redirect response and send the client to the correct, fully qualified, server address. This is the preferred method since the user's bookmark files will then contain fully qualified hosts.

Protocol Adjustments

For circumstances where you have a application server which doesn't implement keepalives or HTTP/1.1 properly, there are 2 environment variables which when set send a HTTP/1.0 with no keepalive. These are set via the SetEnv directive.

These are the force-proxy-request-1.0 and proxy-nokeepalive notes.

<Location /buggyappserver/>
ProxyPass http://buggyappserver:7001/foo/
SetEnv force-proxy-request-1.0 1
SetEnv proxy-nokeepalive 1
 </Location>

AllowCONNECT Directive

Description: | Ports that are allowed to CONNECT through the proxy
Syntax: | AllowCONNECT port [port] ...
Default: | AllowCONNECT 443 563
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The AllowCONNECT directive specifies a list of port numbers to which the proxy CONNECT method may connect. Today's browsers use this method when a https connection is requested and proxy tunneling over HTTP is in effect.

By default, only the default https port (443) and the default snews port (563) are enabled. Use the AllowCONNECT directive to override this default and allow connections to the listed ports only.

Note that you'll need to have mod_proxy_connect present in the server in order to get the support for the CONNECT at all.

NoProxy Directive

Description: | Hosts, domains, or networks that will be connected to directly
Syntax: | NoProxy host [host] ...
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This directive is only useful for Apache proxy servers within intranets. The NoProxy directive specifies a list of subnets, IP addresses, hosts and/or domains, separated by spaces. A request to a host which matches one or more of these is always served directly, without forwarding to the configured ProxyRemote proxy server(s).

Example

ProxyRemote * http://firewall.mycompany.com:81
NoProxy .mycompany.com 192.168.112.0/21

The host arguments to the NoProxy directive are one of the following type list:

Domain

A Domain is a partially qualified DNS domain name, preceded by a period. It represents a list of hosts which logically belong to the same DNS domain or zone (i.e., the suffixes of the hostnames are all ending in Domain).

Examples

.com .apache.org.

To distinguish Domains from Hostnames (both syntactically and semantically; a DNS domain can have a DNS A record, too!), Domains are always written with a leading period.

Note

Domain name comparisons are done without regard to the case, and Domains are always assumed to be anchored in the root of the DNS tree, therefore two domains .MyDomain.com and .mydomain.com. (note the trailing period) are considered equal. Since a domain comparison does not involve a DNS lookup, it is much more efficient than subnet comparison.

SubNet

A SubNet is a partially qualified internet address in numeric (dotted quad) form, optionally followed by a slash and the netmask, specified as the number of significant bits in the SubNet. It is used to represent a subnet of hosts which can be reached over a common network interface. In the absence of the explicit net mask it is assumed that omitted (or zero valued) trailing digits specify the mask. (In this case, the netmask can only be multiples of 8 bits wide.) Examples:

192.168 or 192.168.0.0
the subnet 192.168.0.0 with an implied netmask of 16 valid bits (sometimes used in the netmask form 255.255.0.0)
192.168.112.0/21
the subnet 192.168.112.0/21 with a netmask of 21 valid bits (also used in the form 255.255.248.0)

As a degenerate case, a SubNet with 32 valid bits is the equivalent to an IPAddr, while a SubNet with zero valid bits (e.g., 0.0.0.0/0) is the same as the constant _Default_, matching any IP address.

IPAddr

A IPAddr represents a fully qualified internet address in numeric (dotted quad) form. Usually, this address represents a host, but there need not necessarily be a DNS domain name connected with the address.

Example

192.168.123.7

Note

An IPAddr does not need to be resolved by the DNS system, so it can result in more effective apache performance.

Hostname

A Hostname is a fully qualified DNS domain name which can be resolved to one or more IPAddrs via the DNS domain name service. It represents a logical host (in contrast to Domains, see above) and must be resolvable to at least one IPAddr (or often to a list of hosts with different IPAddrs).

Examples

prep.ai.mit.edu
www.apache.org

Note

In many situations, it is more effective to specify an IPAddr in place of a Hostname since a DNS lookup can be avoided. Name resolution in Apache can take a remarkable deal of time when the connection to the name server uses a slow PPP link.

Hostname comparisons are done without regard to the case, and Hostnames are always assumed to be anchored in the root of the DNS tree, therefore two hosts WWW.MyDomain.com and www.mydomain.com. (note the trailing period) are considered equal.

See also

  • DNS Issues

<Proxy> Directive

Description: | Container for directives applied to proxied resources
Syntax: | <Proxy wildcard-url> ...</Proxy>
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

Directives placed in <Proxy> sections apply only to matching proxied content. Shell-style wildcards are allowed.

For example, the following will allow only hosts in yournetwork.example.com to access content via your proxy server:

<Proxy *>
Order Deny,Allow
Deny from all
Allow from yournetwork.example.com
 </Proxy>

The following example will process all files in the foo directory of example.com through the INCLUDES filter when they are sent through the proxy server:

<Proxy http://example.com/foo/*>
SetOutputFilter INCLUDES
 </Proxy>

ProxyBadHeader Directive

Description: | Determines how to handle bad header lines in a response
Syntax: | ProxyBadHeader IsError|Ignore|StartBody
Default: | ProxyBadHeader IsError
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | available in Apache 2.0.44 and later

The ProxyBadHeader directive determines the behaviour of mod_proxy if it receives syntactically invalid header lines (i.e. containing no colon). The following arguments are possible:

IsError
Abort the request and end up with a 502 (Bad Gateway) response. This is the default behaviour.
Ignore
Treat bad header lines as if they weren't sent.
StartBody
When receiving the first bad header line, finish reading the headers and treat the remainder as body. This helps to work around buggy backend servers which forget to insert an empty line between the headers and the body.

ProxyBlock Directive

Description: | Words, hosts, or domains that are banned from being proxied
Syntax: | ProxyBlock *|word|host|domain [word|host|domain] ...
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyBlock directive specifies a list of words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and FTP document requests to sites whose names contain matched words, hosts or domains are blocked by the proxy server. The proxy module will also attempt to determine IP addresses of list items which may be hostnames during startup, and cache them for match test as well. That may slow down the startup time of the server.

Example

ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu

rocky.wotsamattau.edu would also be matched if referenced by IP address.

Note that wotsamattau would also be sufficient to match wotsamattau.edu.

Note also that

ProxyBlock *

blocks connections to all sites.

ProxyDomain Directive

Description: | Default domain name for proxied requests
Syntax: | ProxyDomain Domain
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This directive is only useful for Apache proxy servers within intranets. The ProxyDomain directive specifies the default domain which the apache proxy server will belong to. If a request to a host without a domain name is encountered, a redirection response to the same host with the configured Domain appended will be generated.

Example

ProxyRemote * http://firewall.mycompany.com:81
NoProxy .mycompany.com 192.168.112.0/21
ProxyDomain .mycompany.com

ProxyErrorOverride Directive

Description: | Override error pages for proxied content
Syntax: | ProxyErrorOverride On|Off
Default: | ProxyErrorOverride Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | Available in version 2.0 and later

This directive is useful for reverse-proxy setups, where you want to have a common look and feel on the error pages seen by the end user. This also allows for included files (via mod_include's SSI) to get the error code and act accordingly (default behavior would display the error page of the proxied server, turning this on shows the SSI Error message).

ProxyIOBufferSize Directive

Description: | Determine size of internal data throughput buffer
Syntax: | ProxyIOBufferSize bytes
Default: | ProxyIOBufferSize 8192
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyIOBufferSize directive adjusts the size of the internal buffer, which is used as a scratchpad for the data between input and output. The size must be less or equal 8192.

In almost every case there's no reason to change that value.

<ProxyMatch> Directive

Description: | Container for directives applied to regular-expression-matched proxied resources
Syntax: | <ProxyMatch regex> ...</ProxyMatch>
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The <ProxyMatch> directive is identical to the <Proxy> directive, except it matches URLs using regular expressions.

ProxyMaxForwards Directive

Description: | Maximium number of proxies that a request can be forwarded through
Syntax: | ProxyMaxForwards number
Default: | ProxyMaxForwards 10
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | Available in Apache 2.0 and later

The ProxyMaxForwards directive specifies the maximum number of proxies through which a request may pass, if there's no Max-Forwards header supplied with the request. This is set to prevent infinite proxy loops, or a DoS attack.

Example

ProxyMaxForwards 15

ProxyPass Directive

Description: | Maps remote servers into the local server URL-space
Syntax: | ProxyPass [path] !|url
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy

This directive allows remote servers to be mapped into the space of the local server; the local server does not act as a proxy in the conventional sense, but appears to be a mirror of the remote server. path is the name of a local virtual path; url is a partial URL for the remote server and cannot include a query string.

Suppose the local server has address http://example.com/; then

ProxyPass /mirror/foo/ http://backend.example.com/

will cause a local request for http://example.com/mirror/foo/bar to be internally converted into a proxy request to http://backend.example.com/bar.

The ! directive is useful in situations where you don't want to reverse-proxy a subdirectory, e.g.

ProxyPass /mirror/foo/i !
ProxyPass /mirror/foo http://backend.example.com

will proxy all requests to /mirror/foo to backend.example.com except requests made to /mirror/foo/i.

Note

Order is important. you need to put the exclusions before the general proxypass directive.

When used inside a <Location> section, the first argument is omitted and the local directory is obtained from the <Location>.

The ProxyRequests directive should usually be set off when using ProxyPass.

If you require a more flexible reverse-proxy configuration, see the RewriteRule directive with the [P] flag.

ProxyPassReverse Directive

Description: | Adjusts the URL in HTTP response headers sent from a reverse proxied server
Syntax: | ProxyPassReverse [path] url
Context: | server config, virtual host, directory
Status: | Extension
Module: | mod_proxy

This directive lets Apache adjust the URL in the Location, Content-Location and URI headers on HTTP redirect responses. This is essential when Apache is used as a reverse proxy to avoid by-passing the reverse proxy because of HTTP redirects on the backend servers which stay behind the reverse proxy.

Only the HTTP response headers specifically mentioned above will be rewritten. Apache will not rewrite other response headers, nor will it rewrite URL references inside HTML pages. This means that if the proxied content contains absolute URL references, they will by-pass the proxy. A third-party module that will look inside the HTML and rewrite URL references is Nick Kew's mod_proxy_html.

path is the name of a local virtual path. url is a partial URL for the remote server - the same way they are used for the ProxyPass directive.

For example, suppose the local server has address http://example.com/; then

ProxyPass /mirror/foo/ http://backend.example.com/
ProxyPassReverse /mirror/foo/ http://backend.example.com/

will not only cause a local request for the http://example.com/mirror/foo/bar to be internally converted into a proxy request to http://backend.example.com/bar (the functionality ProxyPass provides here). It also takes care of redirects the server backend.example.com sends: when http://backend.example.com/bar is redirected by him to http://backend.example.com/quux Apache adjusts this to http://example.com/mirror/foo/quux before forwarding the HTTP redirect response to the client. Note that the hostname used for constructing the URL is chosen in respect to the setting of the UseCanonicalName directive.

Note that this ProxyPassReverse directive can also be used in conjunction with the proxy pass-through feature (RewriteRule ... [P]) from mod_rewrite because its doesn't depend on a corresponding ProxyPass directive.

When used inside a <Location> section, the first argument is omitted and the local directory is obtained from the <Location>.

ProxyPreserveHost Directive

Description: | Use incoming Host HTTP request header for proxy request
Syntax: | ProxyPreserveHost On|Off
Default: | ProxyPreserveHost Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | Available in Apache 2.0.31 and later.

When enabled, this option will pass the Host: line from the incoming request to the proxied host, instead of the hostname specified in the proxypass line.

This option should normally be turned Off. It is mostly useful in special configurations like proxied mass name-based virtual hosting, where the original Host header needs to be evaluated by the backend server.

ProxyReceiveBufferSize Directive

Description: | Network buffer size for proxied HTTP and FTP connections
Syntax: | ProxyReceiveBufferSize bytes
Default: | ProxyReceiveBufferSize 0
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyReceiveBufferSize directive specifies an explicit (TCP/IP) network buffer size for proxied HTTP and FTP connections, for increased throughput. It has to be greater than 512 or set to 0 to indicate that the system's default buffer size should be used.

Example

ProxyReceiveBufferSize 2048

ProxyRemote Directive

Description: | Remote proxy used to handle certain requests
Syntax: | ProxyRemote match remote-server
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This defines remote proxies to this proxy. match is either the name of a URL-scheme that the remote server supports, or a partial URL for which the remote server should be used, or * to indicate the server should be contacted for all requests. remote-server is a partial URL for the remote server. Syntax:

remote-server = scheme://hostname[:port]

scheme is effectively the protocol that should be used to communicate with the remote server; only http is supported by this module.

Example

ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000
ProxyRemote * http://cleversite.com
ProxyRemote ftp http://ftpproxy.mydomain.com:8080

In the last example, the proxy will forward FTP requests, encapsulated as yet another HTTP proxy request, to another proxy which can handle them.

This option also supports reverse proxy configuration - a backend webserver can be embedded within a virtualhost URL space even if that server is hidden by another forward proxy.

ProxyRemoteMatch Directive

Description: | Remote proxy used to handle requests matched by regular expressions
Syntax: | ProxyRemoteMatch regex remote-server
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

The ProxyRemoteMatch is identical to the ProxyRemote directive, except the first argument is a regular expression match against the requested URL.

ProxyRequests Directive

Description: | Enables forward (standard) proxy requests
Syntax: | ProxyRequests On|Off
Default: | ProxyRequests Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This allows or prevents Apache from functioning as a forward proxy server. (Setting ProxyRequests to Off does not disable use of the ProxyPass directive.)

In a typical reverse proxy configuration, this option should be set to Off.

In order to get the functionality of proxying HTTP or FTP sites, you need also mod_proxy_http or mod_proxy_ftp (or both) present in the server.

Warning

Do not enable proxying with ProxyRequests until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

ProxyTimeout Directive

Description: | Network timeout for proxied requests
Syntax: | ProxyTimeout seconds
Default: | ProxyTimeout 300
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy
Compatibility: | Available in Apache 2.0.31 and later

This directive allows a user to specifiy a timeout on proxy requests. This is useful when you have a slow/buggy appserver which hangs, and you would rather just return a timeout and fail gracefully instead of waiting however long it takes the server to return.

ProxyVia Directive

Description: | Information provided in the Via HTTP response header for proxied requests
Syntax: | ProxyVia On|Off|Full|Block
Default: | ProxyVia Off
Context: | server config, virtual host
Status: | Extension
Module: | mod_proxy

This directive controls the use of the Via: HTTP header by the proxy. Its intended use is to control the flow of of proxy requests along a chain of proxy servers. See RFC 2616 (HTTP/1.1), section 14.45 for an explanation of Via: header lines.

  • If set to Off, which is the default, no special processing is performed. If a request or reply contains a Via: header, it is passed through unchanged.
  • If set to On, each request and reply will get a Via: header line added for the current host.
  • If set to Full, each generated Via: header line will additionally have the Apache server version shown as a Via: comment field.
  • If set to Block, every proxy request will have all its Via: header lines removed. No new Via: header will be generated.


mod_proxy_connect - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_proxy_connect

Description: | mod_proxy extension for CONNECT request handling
Status: | Extension
Module Identifier: | proxy_connect_module
Source File: | proxy_connect.c

Summary

This module requires the service of mod_proxy. It provides support for the CONNECT HTTP method. This method is mainly used to tunnel SSL requests through proxy servers.

Thus, in order to get the ability of handling CONNECT requests, mod_proxy and mod_proxy_connect have to be present in the server.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • AllowCONNECT
  • mod_proxy


mod_proxy_ftp - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_proxy_ftp

Description: | FTP support module for mod_proxy
Status: | Extension
Module Identifier: | proxy_ftp_module
Source File: | proxy_ftp.c

Summary

This module requires the service of mod_proxy. It provides support for the proxying FTP sites.

Thus, in order to get the ability of handling FTP proxy requests, mod_proxy and mod_proxy_ftp have to be present in the server.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • mod_proxy


mod_proxy_http - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_proxy_http

Description: | HTTP support module for mod_proxy
Status: | Extension
Module Identifier: | proxy_http_module
Source File: | proxy_http.c

Summary

This module requires the service of mod_proxy. It provides the features used for proxying HTTP requests. mod_proxy_http supports HTTP/0.9, HTTP/1.0 and HTTP/1.1. It does not provide any caching abilities. If you want to set up a caching proxy, you might want to use the additional service of the mod_cache module.

Thus, in order to get the ability of handling HTTP proxy requests, mod_proxy and mod_proxy_http have to be present in the server.

Warning

Do not enable proxying until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large.

See also

  • mod_proxy
  • mod_proxy_connect


mod_rewrite - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_rewrite

Description: | Provides a rule-based rewriting engine to rewrite requested URLs on the fly
Status: | Extension
Module Identifier: | rewrite_module
Source File: | mod_rewrite.c
Compatibility: | Available in Apache 1.3 and later

Summary

``The great thing about mod_rewrite is it gives you all the configurability and flexibility of Sendmail. The downside to mod_rewrite is that it gives you all the configurability and flexibility of Sendmail.''

-- Brian Behlendorf
Apache Group

`` Despite the tons of examples and docs, mod_rewrite is voodoo. Damned cool voodoo, but still voodoo. ''

-- Brian Moore
bem@news.cmc.net

Welcome to mod_rewrite, the Swiss Army Knife of URL manipulation!

This module uses a rule-based rewriting engine (based on a regular-expression parser) to rewrite requested URLs on the fly. It supports an unlimited number of rules and an unlimited number of attached rule conditions for each rule to provide a really flexible and powerful URL manipulation mechanism. The URL manipulations can depend on various tests, for instance server variables, environment variables, HTTP headers, time stamps and even external database lookups in various formats can be used to achieve a really granular URL matching.

This module operates on the full URLs (including the path-info part) both in per-server context (httpd.conf) and per-directory context (.htaccess) and can even generate query-string parts on result. The rewritten result can lead to internal sub-processing, external request redirection or even to an internal proxy throughput.

But all this functionality and flexibility has its drawback: complexity. So don't expect to understand this entire module in just one day.

This module was invented and originally written in April 1996 and gifted exclusively to the The Apache Group in July 1997 by

Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com

Internal Processing

The internal processing of this module is very complex but needs to be explained once even to the average user to avoid common mistakes and to let you exploit its full functionality.

API Phases

First you have to understand that when Apache processes a HTTP request it does this in phases. A hook for each of these phases is provided by the Apache API. Mod_rewrite uses two of these hooks: the URL-to-filename translation hook which is used after the HTTP request has been read but before any authorization starts and the Fixup hook which is triggered after the authorization phases and after the per-directory config files (.htaccess) have been read, but before the content handler is activated.

So, after a request comes in and Apache has determined the corresponding server (or virtual server) the rewriting engine starts processing of all mod_rewrite directives from the per-server configuration in the URL-to-filename phase. A few steps later when the final data directories are found, the per-directory configuration directives of mod_rewrite are triggered in the Fixup phase. In both situations mod_rewrite rewrites URLs either to new URLs or to filenames, although there is no obvious distinction between them. This is a usage of the API which was not intended to be this way when the API was designed, but as of Apache 1.x this is the only way mod_rewrite can operate. To make this point more clear remember the following two points:

  1. Although mod_rewrite rewrites URLs to URLs, URLs to filenames and even filenames to filenames, the API currently provides only a URL-to-filename hook. In Apache 2.0 the two missing hooks will be added to make the processing more clear. But this point has no drawbacks for the user, it is just a fact which should be remembered: Apache does more in the URL-to-filename hook than the API intends for it.
  2. Unbelievably mod_rewrite provides URL manipulations in per-directory context, i.e., within .htaccess files, although these are reached a very long time after the URLs have been translated to filenames. It has to be this way because .htaccess files live in the filesystem, so processing has already reached this stage. In other words: According to the API phases at this time it is too late for any URL manipulations. To overcome this chicken and egg problem mod_rewrite uses a trick: When you manipulate a URL/filename in per-directory context mod_rewrite first rewrites the filename back to its corresponding URL (which is usually impossible, but see the RewriteBase directive below for the trick to achieve this) and then initiates a new internal sub-request with the new URL. This restarts processing of the API phases.

    Again mod_rewrite tries hard to make this complicated step totally transparent to the user, but you should remember here: While URL manipulations in per-server context are really fast and efficient, per-directory rewrites are slow and inefficient due to this chicken and egg problem. But on the other hand this is the only way mod_rewrite can provide (locally restricted) URL manipulations to the average user.

Don't forget these two points!

Ruleset Processing

Now when mod_rewrite is triggered in these two API phases, it reads the configured rulesets from its configuration structure (which itself was either created on startup for per-server context or during the directory walk of the Apache kernel for per-directory context). Then the URL rewriting engine is started with the contained ruleset (one or more rules together with their conditions). The operation of the URL rewriting engine itself is exactly the same for both configuration contexts. Only the final result processing is different.

The order of rules in the ruleset is important because the rewriting engine processes them in a special (and not very obvious) order. The rule is this: The rewriting engine loops through the ruleset rule by rule (RewriteRule directives) and when a particular rule matches it optionally loops through existing corresponding conditions (RewriteCond directives). For historical reasons the conditions are given first, and so the control flow is a little bit long-winded. See Figure 1 for more details.

[Needs graphics capability to display]
Figure 1:The control flow through the rewriting ruleset

As you can see, first the URL is matched against the Pattern of each rule. When it fails mod_rewrite immediately stops processing this rule and continues with the next rule. If the Pattern matches, mod_rewrite looks for corresponding rule conditions. If none are present, it just substitutes the URL with a new value which is constructed from the string Substitution and goes on with its rule-looping. But if conditions exist, it starts an inner loop for processing them in the order that they are listed. For conditions the logic is different: we don't match a pattern against the current URL. Instead we first create a string TestString by expanding variables, back-references, map lookups, etc. and then we try to match CondPattern against it. If the pattern doesn't match, the complete set of conditions and the corresponding rule fails. If the pattern matches, then the next condition is processed until no more conditions are available. If all conditions match, processing is continued with the substitution of the URL with Substitution.

Quoting Special Characters

As of Apache 1.3.20, special characters in TestString and Substitution strings can be escaped (that is, treated as normal characters without their usual special meaning) by prefixing them with a slosh ('\') character. In other words, you can include an actual dollar-sign character in a Substitution string by using '\$'; this keeps mod_rewrite from trying to treat it as a backreference.

Regex Back-Reference Availability

One important thing here has to be remembered: Whenever you use parentheses in Pattern or in one of the CondPattern, back-references are internally created which can be used with the strings $N and %N (see below). These are available for creating the strings Substitution and TestString. Figure 2 shows to which locations the back-references are transfered for expansion.

[Needs graphics capability to display]
Figure 2: The back-reference flow through a rule.

We know this was a crash course on mod_rewrite's internal processing. But you will benefit from this knowledge when reading the following documentation of the available directives.

Environment Variables

This module keeps track of two additional (non-standard) CGI/SSI environment variables named SCRIPT_URL and SCRIPT_URI. These contain the logical Web-view to the current resource, while the standard CGI/SSI variables SCRIPT_NAME and SCRIPT_FILENAME contain the physical System-view.

Notice: These variables hold the URI/URL as they were initially requested, i.e., before any rewriting. This is important because the rewriting process is primarily used to rewrite logical URLs to physical pathnames.

Example

SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
SCRIPT_FILENAME=/u/rse/.www/index.html
SCRIPT_URL=/u/rse/
SCRIPT_URI=http://en1.engelschall.com/u/rse/

Practical Solutions

We also have an URL Rewriting Guide available, which provides a collection of practical solutions for URL-based problems. There you can find real-life rulesets and additional information about mod_rewrite.

RewriteBase Directive

Description: | Sets the base URL for per-directory rewrites
Syntax: | RewriteBase URL-path
Default: | See usage for information.
Context: | directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteBase directive explicitly sets the base URL for per-directory rewrites. As you will see below, RewriteRule can be used in per-directory config files (.htaccess). There it will act locally, i.e., the local directory prefix is stripped at this stage of processing and your rewriting rules act only on the remainder. At the end it is automatically added back to the path. The default setting is; RewriteBase physical-directory-path

When a substitution occurs for a new URL, this module has to re-inject the URL into the server processing. To be able to do this it needs to know what the corresponding URL-prefix or URL-base is. By default this prefix is the corresponding filepath itself. But at most websites URLs are NOT directly related to physical filename paths, so this assumption will usually be wrong! There you have to use the RewriteBase directive to specify the correct URL-prefix.

If your webserver's URLs are not directly related to physical file paths, you have to use RewriteBase in every .htaccess files where you want to use RewriteRule directives.

For example, assume the following per-directory config file:

#
#  /abc/def/.htaccess -- per-dir config file for directory /abc/def
#  Remember: /abc/def is the physical path of /xyz, i.e., the server
#            has a 'Alias /xyz /abc/def' directive e.g.
#

RewriteEngine On

#  let the server know that we were reached via /xyz and not
#  via the physical path prefix /abc/def
RewriteBase   /xyz

#  now the rewriting rules
RewriteRule   ^oldstuff\.html$  newstuff.html

In the above example, a request to /xyz/oldstuff.html gets correctly rewritten to the physical file /abc/def/newstuff.html.

For Apache Hackers

The following list gives detailed information about the internal processing steps:

Request:
  /xyz/oldstuff.html

Internal Processing:
  /xyz/oldstuff.html     -> /abc/def/oldstuff.html  (per-server Alias)
  /abc/def/oldstuff.html -> /abc/def/newstuff.html  (per-dir    RewriteRule)
  /abc/def/newstuff.html -> /xyz/newstuff.html      (per-dir    RewriteBase)
  /xyz/newstuff.html     -> /abc/def/newstuff.html  (per-server Alias)

Result:
  /abc/def/newstuff.html

This seems very complicated but is the correct Apache internal processing, because the per-directory rewriting comes too late in the process. So, when it occurs the (rewritten) request has to be re-injected into the Apache kernel! BUT: While this seems like a serious overhead, it really isn't, because this re-injection happens fully internally to the Apache server and the same procedure is used by many other operations inside Apache. So, you can be sure the design and implementation is correct.

RewriteCond Directive

Description: | Defines a condition under which rewriting will take place
Syntax: | RewriteCond TestString CondPattern
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteCond directive defines a rule condition. Precede a RewriteRule directive with one or more RewriteCond directives. The following rewriting rule is only used if its pattern matches the current state of the URI and if these additional conditions apply too.

TestString is a string which can contains the following expanded constructs in addition to plain text:

  • RewriteRule backreferences: These are backreferences of the form

    $N

    (0 <= N <= 9) which provide access to the grouped parts (parenthesis!) of the pattern from the corresponding RewriteRule directive (the one following the current bunch of RewriteCond directives).
  • RewriteCond backreferences: These are backreferences of the form

    %N

    (1 <= N <= 9) which provide access to the grouped parts (parentheses!) of the pattern from the last matched RewriteCond directive in the current bunch of conditions.
  • RewriteMap expansions: These are expansions of the form

    ${mapname:key|default}

    See the documentation for RewriteMap for more details.
  • Server-Variables: These are variables of the form

    %{ NAME_OF_VARIABLE }

    where NAME_OF_VARIABLE can be a string taken from the following list:
    HTTP headers: connection & request:
    HTTP_USER_AGENT
    HTTP_REFERER
    HTTP_COOKIE
    HTTP_FORWARDED
    HTTP_HOST
    HTTP_PROXY_CONNECTION
    HTTP_ACCEPT
             REMOTE_ADDR
    REMOTE_HOST
    REMOTE_USER
    REMOTE_IDENT
    REQUEST_METHOD
    SCRIPT_FILENAME
    PATH_INFO
    QUERY_STRING
    AUTH_TYPE
    server internals: system stuff: specials:
    DOCUMENT_ROOT
    SERVER_ADMIN
    SERVER_NAME
    SERVER_ADDR
    SERVER_PORT
    SERVER_PROTOCOL
    SERVER_SOFTWARE
             TIME_YEAR
    TIME_MON
    TIME_DAY
    TIME_HOUR
    TIME_MIN
    TIME_SEC
    TIME_WDAY
    TIME
             API_VERSION
    THE_REQUEST
    REQUEST_URI
    REQUEST_FILENAME
    IS_SUBREQ

    These variables all correspond to the similarly named HTTP MIME-headers, C variables of the Apache server or struct tm fields of the Unix system. Most are documented elsewhere in the Manual or in the CGI specification. Those that are special to mod_rewrite include:

    IS_SUBREQ
    Will contain the text "true" if the request currently being processed is a sub-request, "false" otherwise. Sub-requests may be generated by modules that need to resolve additional files or URIs in order to complete their tasks.
    API_VERSION
    This is the version of the Apache module API (the internal interface between server and module) in the current httpd build, as defined in include/ap_mmn.h. The module API version corresponds to the version of Apache in use (in the release version of Apache 1.3.14, for instance, it is 19990320:10), but is mainly of interest to module authors.
    THE_REQUEST
    The full HTTP request line sent by the browser to the server (e.g., "GET /index.html HTTP/1.1"). This does not include any additional headers sent by the browser.
    REQUEST_URI
    The resource requested in the HTTP request line. (In the example above, this would be "/index.html".)
    REQUEST_FILENAME
    The full local filesystem path to the file or script matching the request.

Special Notes:

  1. The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same value, i.e., the value of the filename field of the internal request_rec structure of the Apache server. The first name is just the commonly known CGI variable name while the second is the consistent counterpart to REQUEST_URI (which contains the value of the uri field of request_rec).
  2. There is the special format: %{ENV:variable} where variable can be any environment variable. This is looked-up via internal Apache structures and (if not found there) via getenv() from the Apache server process.
  3. There is the special format: %{HTTP:header} where header can be any HTTP MIME-header name. This is looked-up from the HTTP request. Example: %{HTTP:Proxy-Connection} is the value of the HTTP header ``Proxy-Connection:''.
  4. There is the special format %{LA-U:variable} for look-aheads which perform an internal (URL-based) sub-request to determine the final value of variable. Use this when you want to use a variable for rewriting which is actually set later in an API phase and thus is not available at the current stage. For instance when you want to rewrite according to the REMOTE_USER variable from within the per-server context (httpd.conf file) you have to use %{LA-U:REMOTE_USER} because this variable is set by the authorization phases which come after the URL translation phase where mod_rewrite operates. On the other hand, because mod_rewrite implements its per-directory context (.htaccess file) via the Fixup phase of the API and because the authorization phases come before this phase, you just can use %{REMOTE_USER} there.
  5. There is the special format: %{LA-F:variable} which performs an internal (filename-based) sub-request to determine the final value of variable. Most of the time this is the same as LA-U above.

CondPattern is the condition pattern, i.e., a regular expression which is applied to the current instance of the TestString, i.e., TestString is evaluated and then matched against CondPattern.

Remember: CondPattern is a perl compatible regular expression with some additions:

  1. You can prefix the pattern string with a '!' character (exclamation mark) to specify a non-matching pattern.
  2. There are some special variants of CondPatterns. Instead of real regular expression strings you can also use one of the following:
    • '<CondPattern' (is lexically lower)
      Treats the CondPattern as a plain string and compares it lexically to TestString. True if TestString is lexically lower than CondPattern.
    • '>CondPattern' (is lexically greater)
      Treats the CondPattern as a plain string and compares it lexically to TestString. True if TestString is lexically greater than CondPattern.
    • '=CondPattern' (is lexically equal)
      Treats the CondPattern as a plain string and compares it lexically to TestString. True if TestString is lexically equal to CondPattern, i.e the two strings are exactly equal (character by character). If CondPattern is just "" (two quotation marks) this compares TestString to the empty string.
    • '-d' (is directory)
      Treats the TestString as a pathname and tests if it exists and is a directory.
    • '-f' (is regular file)
      Treats the TestString as a pathname and tests if it exists and is a regular file.
    • '-s' (is regular file with size)
      Treats the TestString as a pathname and tests if it exists and is a regular file with size greater than zero.
    • '-l' (is symbolic link)
      Treats the TestString as a pathname and tests if it exists and is a symbolic link.
    • '-F' (is existing file via subrequest)
      Checks if TestString is a valid file and accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to determine the check, so use it with care because it decreases your servers performance!
    • '-U' (is existing URL via subrequest)
      Checks if TestString is a valid URL and accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to determine the check, so use it with care because it decreases your server's performance!

    Notice

    All of these tests can also be prefixed by an exclamation mark ('!') to negate their meaning.

Additionally you can set special flags for CondPattern by appending

[flags]

as the third argument to the RewriteCond directive. Flags is a comma-separated list of the following flags:

  • 'nocase|NC' (no case)
    This makes the test case-insensitive, i.e., there is no difference between 'A-Z' and 'a-z' both in the expanded TestString and the CondPattern. This flag is effective only for comparisons between TestString and CondPattern. It has no effect on filesystem and subrequest checks.
  • 'ornext|OR' (or next condition)
    Use this to combine rule conditions with a local OR instead of the implicit AND. Typical example:
    RewriteCond %{REMOTE_HOST}  ^host1.*  [OR]
RewriteCond %{REMOTE_HOST}  ^host2.*  [OR]
RewriteCond %{REMOTE_HOST}  ^host3.*
RewriteRule ...some special stuff for any of these hosts...
    Without this flag you would have to write the cond/rule three times.

Example:

To rewrite the Homepage of a site according to the ``User-Agent:'' header of the request, you can use the following:

RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
RewriteRule  ^/$                 /homepage.max.html  [L]

RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
RewriteRule  ^/$                 /homepage.min.html  [L]

RewriteRule  ^/$                 /homepage.std.html  [L]

Interpretation: If you use Netscape Navigator as your browser (which identifies itself as 'Mozilla'), then you get the max homepage, which includes Frames, etc. If you use the Lynx browser (which is Terminal-based), then you get the min homepage, which contains no images, no tables, etc. If you use any other browser you get the standard homepage.

RewriteEngine Directive

Description: | Enables or disables runtime rewriting engine
Syntax: | RewriteEngine on|off
Default: | RewriteEngine off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite

The RewriteEngine directive enables or disables the runtime rewriting engine. If it is set to off this module does no runtime processing at all. It does not even update the SCRIPT_URx environment variables.

Use this directive to disable the module instead of commenting out all the RewriteRule directives!

Note that, by default, rewrite configurations are not inherited. This means that you need to have a RewriteEngine on directive for each virtual host in which you wish to use it.

RewriteLock Directive

Description: | Sets the name of the lock file used for RewriteMap synchronization
Syntax: | RewriteLock file-path
Context: | server config
Status: | Extension
Module: | mod_rewrite

This directive sets the filename for a synchronization lockfile which mod_rewrite needs to communicate with RewriteMap programs. Set this lockfile to a local path (not on a NFS-mounted device) when you want to use a rewriting map-program. It is not required for other types of rewriting maps.

RewriteLog Directive

Description: | Sets the name of the file used for logging rewrite engine processing
Syntax: | RewriteLog file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_rewrite

The RewriteLog directive sets the name of the file to which the server logs any rewriting actions it performs. If the name does not begin with a slash ('/') then it is assumed to be relative to the Server Root. The directive should occur only once per server config.

To disable the logging of rewriting actions it is not recommended to set Filename to /dev/null, because although the rewriting engine does not then output to a logfile it still creates the logfile output internally. This will slow down the server with no advantage to the administrator! To disable logging either remove or comment out the RewriteLog directive or use RewriteLogLevel 0!

Security

See the Apache Security Tips document for details on why your security could be compromised if the directory where logfiles are stored is writable by anyone other than the user that starts the server.

Example

RewriteLog "/usr/local/var/apache/logs/rewrite.log"

RewriteLogLevel Directive

Description: | Sets the verbosity of the log file used by the rewrite engine
Syntax: | RewriteLogLevel Level
Default: | RewriteLogLevel 0
Context: | server config, virtual host
Status: | Extension
Module: | mod_rewrite

The RewriteLogLevel directive sets the verbosity level of the rewriting logfile. The default level 0 means no logging, while 9 or more means that practically all actions are logged.

To disable the logging of rewriting actions simply set Level to 0. This disables all rewrite action logs.

Using a high value for Level will slow down your Apache server dramatically! Use the rewriting logfile at a Level greater than 2 only for debugging!

Example

RewriteLogLevel 3

RewriteMap Directive

Description: | Defines a mapping function for key-lookup
Syntax: | RewriteMap MapName MapType:MapSource
Context: | server config, virtual host
Status: | Extension
Module: | mod_rewrite
Compatibility: | The choice of different dbm types is available in Apache 2.0.41 and later

The RewriteMap directive defines a Rewriting Map which can be used inside rule substitution strings by the mapping-functions to insert/substitute fields through a key lookup. The source of this lookup can be of various types.

The MapName is the name of the map and will be used to specify a mapping-function for the substitution strings of a rewriting rule via one of the following constructs:

${ MapName : LookupKey }
${ MapName : LookupKey | DefaultValue }

When such a construct occurs the map MapName is consulted and the key LookupKey is looked-up. If the key is found, the map-function construct is substituted by SubstValue. If the key is not found then it is substituted by DefaultValue or by the empty string if no DefaultValue was specified.

The following combinations for MapType and MapSource can be used:

  • Standard Plain Text
    MapType: txt, MapSource: Unix filesystem path to valid regular file

    This is the standard rewriting map feature where the MapSource is a plain ASCII file containing either blank lines, comment lines (starting with a '#' character) or pairs like the following - one per line.

    MatchingKey SubstValue

    Example

    ##
##  map.txt -- rewriting map
##

Ralf.S.Engelschall    rse   # Bastard Operator From Hell
Mr.Joe.Average        joe   # Mr. Average

    RewriteMap real-to-user txt:/path/to/file/map.txt

  • Randomized Plain Text
    MapType: rnd, MapSource: Unix filesystem path to valid regular file

    This is identical to the Standard Plain Text variant above but with a special post-processing feature: After looking up a value it is parsed according to contained ``|'' characters which have the meaning of ``or''. In other words they indicate a set of alternatives from which the actual returned value is chosen randomly. Although this sounds crazy and useless, it was actually designed for load balancing in a reverse proxy situation where the looked up values are server names. Example:

    ##
##  map.txt -- rewriting map
##

static   www1|www2|www3|www4
dynamic  www5|www6

    RewriteMap servers rnd:/path/to/file/map.txt

  • Hash File
    MapType: dbm[=type], MapSource: Unix filesystem path to valid regular file

    Here the source is a binary format DBM file containing the same contents as a Plain Text format file, but in a special representation which is optimized for really fast lookups. The type can be sdbm, gdbm, ndbm, or db depending on compile-time settings. If the type is ommitted, the compile-time default will be chosen. You can create such a file with any DBM tool or with the following Perl script. Be sure to adjust it to create the appropriate type of DBM. The example creates an NDBM file.

    #!/path/to/bin/perl
##
##  txt2dbm -- convert txt map to dbm format
##

use NDBM_File;
use Fcntl;

($txtmap, $dbmmap) = @ARGV;

open(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n";
tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644)
  or die "Couldn't create $dbmmap!\n";

while (<TXT>) {
  next if (/^\s*#/ or /^\s*$/);
  $DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/);
}

untie %DB;
close(TXT);

    $ txt2dbm map.txt map.db

  • Internal Function
    MapType: int, MapSource: Internal Apache function

    Here the source is an internal Apache function. Currently you cannot create your own, but the following functions already exists:

    • toupper:
      Converts the looked up key to all upper case.
    • tolower:
      Converts the looked up key to all lower case.
    • escape:
      Translates special characters in the looked up key to hex-encodings.
    • unescape:
      Translates hex-encodings in the looked up key back to special characters.
  • External Rewriting Program
    MapType: prg, MapSource: Unix filesystem path to valid regular file

    Here the source is a program, not a map file. To create it you can use the language of your choice, but the result has to be a executable (i.e., either object-code or a script with the magic cookie trick '#!/path/to/interpreter' as the first line).

    This program is started once at startup of the Apache servers and then communicates with the rewriting engine over its stdin and stdout file-handles. For each map-function lookup it will receive the key to lookup as a newline-terminated string on stdin. It then has to give back the looked-up value as a newline-terminated string on stdout or the four-character string ``NULL'' if it fails (i.e., there is no corresponding value for the given key). A trivial program which will implement a 1:1 map (i.e., key == value) could be:

    #!/usr/bin/perl
$| = 1;
while (<STDIN>) {
    # ...put here any transformations or lookups...
    print $_;
}

    But be very careful:

    1. ``Keep it simple, stupid'' (KISS), because if this program hangs it will hang the Apache server when the rule occurs.
    2. Avoid one common mistake: never do buffered I/O on stdout! This will cause a deadloop! Hence the ``$|=1'' in the above example...
    3. Use the RewriteLock directive to define a lockfile mod_rewrite can use to synchronize the communication to the program. By default no such synchronization takes place.

The RewriteMap directive can occur more than once. For each mapping-function use one RewriteMap directive to declare its rewriting mapfile. While you cannot declare a map in per-directory context it is of course possible to use this map in per-directory context.

Note

For plain text and DBM format files the looked-up keys are cached in-core until the mtime of the mapfile changes or the server does a restart. This way you can have map-functions in rules which are used for every request. This is no problem, because the external lookup only happens once!

RewriteOptions Directive

Description: | Sets some special options for the rewrite engine
Syntax: | RewriteOptions Options
Default: | RewriteOptions MaxRedirects=10
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite
Compatibility: | MaxRedirects is available in Apache 2.0.45 and later

The RewriteOptions directive sets some special options for the current per-server or per-directory configuration. The Option strings can be one of the following:

inherit
This forces the current configuration to inherit the configuration of the parent. In per-virtual-server context this means that the maps, conditions and rules of the main server are inherited. In per-directory context this means that conditions and rules of the parent directory's .htaccess configuration are inherited.
MaxRedirects=number
In order to prevent endless loops of internal redirects issued by per-directory RewriteRules, mod_rewrite aborts the request after reaching a maximum number of such redirects and responds with an 500 Internal Server Error. If you really need more internal redirects than 10 per request, you may increase the default to the desired value.

RewriteRule Directive

Description: | Defines rules for the rewriting engine
Syntax: | RewriteRule Pattern Substitution
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_rewrite
Compatibility: | The cookie-flag is available in Apache 2.0.40 and later.

The RewriteRule directive is the real rewriting workhorse. The directive can occur more than once. Each directive then defines one single rewriting rule. The definition order of these rules is important, because this order is used when applying the rules at run-time.

Pattern is a perl compatible regular expression which gets applied to the current URL. Here ``current'' means the value of the URL when this rule gets applied. This may not be the originally requested URL, because any number of rules may already have matched and made alterations to it.

Some hints about the syntax of regular expressions:

Text:
  .           Any single character
  [chars]     Character class: One  of chars
  [^chars]    Character class: None of chars
  text1|text2 Alternative: text1 or text2

Quantifiers:
  ?           0 or 1 of the preceding text
  *           0 or N of the preceding text (N > 0)
  +           1 or N of the preceding text (N > 1)

Grouping:
  (text)      Grouping of text
              (either to set the borders of an alternative or
              for making backreferences where the Nth group can
              be used on the RHS of a RewriteRule with $N)

Anchors:
  ^           Start of line anchor
  $           End   of line anchor

Escaping:
  \char       escape that particular char
              (for instance to specify the chars ".[]()" etc.)

For more information about regular expressions have a look at the perl regular expression manpage ("perldoc perlre"). If you are interested in more detailed information about regular expressions and their variants (POSIX regex etc.) have a look at the following dedicated book on this topic:

Mastering Regular Expressions
Jeffrey E.F. Friedl
Nutshell Handbook Series
O'Reilly & Associates, Inc. 1997
ISBN 1-56592-257-3

Additionally in mod_rewrite the NOT character ('!') is a possible pattern prefix. This gives you the ability to negate a pattern; to say, for instance: ``if the current URL does NOT match this pattern''. This can be used for exceptional cases, where it is easier to match the negative pattern, or as a last default rule.

Notice

When using the NOT character to negate a pattern you cannot have grouped wildcard parts in the pattern. This is impossible because when the pattern does NOT match, there are no contents for the groups. In consequence, if negated patterns are used, you cannot use $N in the substitution string!

Substitution of a rewriting rule is the string which is substituted for (or replaces) the original URL for which Pattern matched. Beside plain text you can use

  1. back-references $N to the RewriteRule pattern
  2. back-references %N to the last matched RewriteCond pattern
  3. server-variables as in rule condition test-strings (%{VARNAME})
  4. mapping-function calls (${mapname:key|default})

Back-references are $N (N=0..9) identifiers which will be replaced by the contents of the Nth group of the matched Pattern. The server-variables are the same as for the TestString of a RewriteCond directive. The mapping-functions come from the RewriteMap directive and are explained there. These three types of variables are expanded in the order of the above list.

As already mentioned above, all the rewriting rules are applied to the Substitution (in the order of definition in the config file). The URL is completely replaced by the Substitution and the rewriting process goes on until there are no more rules unless explicitly terminated by a L flag - see below.

There is a special substitution string named '-' which means: NO substitution! Sounds silly? No, it is useful to provide rewriting rules which only match some URLs but do no substitution, e.g., in conjunction with the C (chain) flag to be able to have more than one pattern to be applied before a substitution occurs.

One more note: You can even create URLs in the substitution string containing a query string part. Just use a question mark inside the substitution string to indicate that the following stuff should be re-injected into the QUERY_STRING. When you want to erase an existing query string, end the substitution string with just the question mark.

Note

There is a special feature: When you prefix a substitution field with http://thishost[:thisport] then mod_rewrite automatically strips it out. This auto-reduction on implicit external redirect URLs is a useful and important feature when used in combination with a mapping-function which generates the hostname part. Have a look at the first example in the example section below to understand this.

Remember

An unconditional external redirect to your own server will not work with the prefix http://thishost because of this feature. To achieve such a self-redirect, you have to use the R-flag (see below).

Additionally you can set special flags for Substitution by appending

[flags]

as the third argument to the RewriteRule directive. Flags is a comma-separated list of the following flags:

  • 'redirect|R [=code]' (force redirect)
    Prefix Substitution with http://thishost[:thisport]/ (which makes the new URL a URI) to force a external redirection. If no code is given a HTTP response of 302 (MOVED TEMPORARILY) is used. If you want to use other response codes in the range 300-400 just specify them as a number or use one of the following symbolic names: temp (default), permanent, seeother. Use it for rules which should canonicalize the URL and give it back to the client, e.g., translate ``/~'' into ``/u/'' or always append a slash to /u/user, etc.

    Note: When you use this flag, make sure that the substitution field is a valid URL! If not, you are redirecting to an invalid location! And remember that this flag itself only prefixes the URL with http://thishost[:thisport]/, rewriting continues. Usually you also want to stop and do the redirection immediately. To stop the rewriting you also have to provide the 'L' flag.

  • 'forbidden|F' (force URL to be forbidden)
    This forces the current URL to be forbidden, i.e., it immediately sends back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with appropriate RewriteConds to conditionally block some URLs.
  • 'gone|G' (force URL to be gone)
    This forces the current URL to be gone, i.e., it immediately sends back a HTTP response of 410 (GONE). Use this flag to mark pages which no longer exist as gone.
  • 'proxy|P' (force proxy)
    This flag forces the substitution part to be internally forced as a proxy request and immediately (i.e., rewriting rule processing stops here) put through the proxy module. You have to make sure that the substitution string is a valid URI (e.g., typically starting with http://hostname) which can be handled by the Apache proxy module. If not you get an error from the proxy module. Use this flag to achieve a more powerful implementation of the ProxyPass directive, to map some remote stuff into the namespace of the local server.

    Notice: To use this functionality make sure you have the proxy module compiled into your Apache server program. If you don't know please check whether mod_proxy.c is part of the ``httpd -l'' output. If yes, this functionality is available to mod_rewrite. If not, then you first have to rebuild the ``httpd'' program with mod_proxy enabled.

  • 'last|L' (last rule)
    Stop the rewriting process here and don't apply any more rewriting rules. This corresponds to the Perl last command or the break command from the C language. Use this flag to prevent the currently rewritten URL from being rewritten further by following rules. For example, use it to rewrite the root-path URL ('/') to a real one, e.g., '/e/www/'.
  • 'next|N' (next round)
    Re-run the rewriting process (starting again with the first rewriting rule). Here the URL to match is again not the original URL but the URL from the last rewriting rule. This corresponds to the Perl next command or the continue command from the C language. Use this flag to restart the rewriting process, i.e., to immediately go to the top of the loop.
    But be careful not to create an infinite loop!
  • 'chain|C' (chained with next rule)
    This flag chains the current rule with the next rule (which itself can be chained with the following rule, etc.). This has the following effect: if a rule matches, then processing continues as usual, i.e., the flag has no effect. If the rule does not match, then all following chained rules are skipped. For instance, use it to remove the ``.www'' part inside a per-directory rule set when you let an external redirect happen (where the ``.www'' part should not to occur!).
  • 'type|T=MIME-type' (force MIME type)
    Force the MIME-type of the target file to be MIME-type. For instance, this can be used to simulate the mod_alias directive ScriptAlias which internally forces all files inside the mapped directory to have a MIME type of ``application/x-httpd-cgi''.
  • 'nosubreq|NS' (used only if no internal sub-request)
    This flag forces the rewriting engine to skip a rewriting rule if the current request is an internal sub-request. For instance, sub-requests occur internally in Apache when mod_include tries to find out information about possible directory default files (index.xxx). On sub-requests it is not always useful and even sometimes causes a failure to if the complete set of rules are applied. Use this flag to exclude some rules.

    Use the following rule for your decision: whenever you prefix some URLs with CGI-scripts to force them to be processed by the CGI-script, the chance is high that you will run into problems (or even overhead) on sub-requests. In these cases, use this flag.

  • 'nocase|NC' (no case)
    This makes the Pattern case-insensitive, i.e., there is no difference between 'A-Z' and 'a-z' when Pattern is matched against the current URL.
  • 'qsappend|QSA' (query string append)
    This flag forces the rewriting engine to append a query string part in the substitution string to the existing one instead of replacing it. Use this when you want to add more data to the query string via a rewrite rule.
  • 'noescape|NE' (no URI escaping of output)
    This flag keeps mod_rewrite from applying the usual URI escaping rules to the result of a rewrite. Ordinarily, special characters (such as '%', '$', ';', and so on) will be escaped into their hexcode equivalents ('%25', '%24', and '%3B', respectively); this flag prevents this from being done. This allows percent symbols to appear in the output, as in

    RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]

    which would turn '/foo/zed' into a safe request for '/bar?arg=P1=zed'.
  • 'passthrough|PT' (pass through to next handler)
    This flag forces the rewriting engine to set the uri field of the internal request_rec structure to the value of the filename field. This flag is just a hack to be able to post-process the output of RewriteRule directives by Alias, ScriptAlias, Redirect, etc. directives from other URI-to-filename translators. A trivial example to show the semantics: If you want to rewrite /abc to /def via the rewriting engine of mod_rewrite and then /def to /ghi with mod_alias:

    RewriteRule ^/abc(.*) /def$1 [PT]
    Alias /def /ghi

    If you omit the PT flag then mod_rewrite will do its job fine, i.e., it rewrites uri=/abc/... to filename=/def/... as a full API-compliant URI-to-filename translator should do. Then mod_alias comes and tries to do a URI-to-filename transition which will not work.

    Note: You have to use this flag if you want to intermix directives of different modules which contain URL-to-filename translators. The typical example is the use of mod_alias and mod_rewrite..

  • 'skip|S=num' (skip next rule(s))
    This flag forces the rewriting engine to skip the next num rules in sequence when the current rule matches. Use this to make pseudo if-then-else constructs: The last rule of the then-clause becomes skip=N where N is the number of rules in the else-clause. (This is not the same as the 'chain|C' flag!)
  • 'env|E=VAR:VAL' (set environment variable)
    This forces an environment variable named VAR to be set to the value VAL, where VAL can contain regexp backreferences $N and %N which will be expanded. You can use this flag more than once to set more than one variable. The variables can be later dereferenced in many situations, but usually from within XSSI (via <!--#echo var="VAR"-->) or CGI (e.g. $ENV{'VAR'}). Additionally you can dereference it in a following RewriteCond pattern via %{ENV:VAR}. Use this to strip but remember information from URLs.
  • 'cookie|CO=NAME:VAL:domain[:lifetime[:path]]' (set cookie)
    This sets a cookie on the client's browser. The cookie's name is specified by NAME and the value is VAL. The domain field is the domain of the cookie, such as '.apache.org',the optional lifetime is the lifetime of the cookie in minutes, and the optional path is the path of the cookie

Note

Never forget that Pattern is applied to a complete URL in per-server configuration files. But in per-directory configuration files, the per-directory prefix (which always is the same for a specific directory!) is automatically removed for the pattern matching and automatically added after the substitution has been done. This feature is essential for many sorts of rewriting, because without this prefix stripping you have to match the parent directory which is not always possible.

There is one exception: If a substitution string starts with ``http://'' then the directory prefix will not be added and an external redirect or proxy throughput (if flag P is used!) is forced!

Note

To enable the rewriting engine for per-directory configuration files you need to set ``RewriteEngine On'' in these files and ``Options FollowSymLinks'' must be enabled. If your administrator has disabled override of FollowSymLinks for a user's directory, then you cannot use the rewriting engine. This restriction is needed for security reasons.

Here are all possible substitution combinations and their meanings:

Inside per-server configuration (httpd.conf)
for request ``GET /somepath/pathinfo'':

Given Rule                                      Resulting Substitution
----------------------------------------------  ----------------------------------
^/somepath(.*) otherpath$1                      not supported, because invalid!

^/somepath(.*) otherpath$1  [R]                 not supported, because invalid!

^/somepath(.*) otherpath$1  [P]                 not supported, because invalid!
----------------------------------------------  ----------------------------------
^/somepath(.*) /otherpath$1                     /otherpath/pathinfo

^/somepath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
                                                via external redirection

^/somepath(.*) /otherpath$1 [P]                 not supported, because silly!
----------------------------------------------  ----------------------------------
^/somepath(.*) http://thishost/otherpath$1      /otherpath/pathinfo

^/somepath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
                                                via external redirection

^/somepath(.*) http://thishost/otherpath$1 [P]  not supported, because silly!
----------------------------------------------  ----------------------------------
^/somepath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
                                                via external redirection

^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
                                                via external redirection
                                                (the [R] flag is redundant)

^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
                                                via internal proxy

Inside per-directory configuration for /somepath
(i.e., file .htaccess in dir /physical/path/to/somepath containing RewriteBase /somepath)
for request ``GET /somepath/localpath/pathinfo'':

Given Rule                                      Resulting Substitution
----------------------------------------------  ----------------------------------
^localpath(.*) otherpath$1                      /somepath/otherpath/pathinfo

^localpath(.*) otherpath$1  [R]                 http://thishost/somepath/otherpath/pathinfo
                                                via external redirection

^localpath(.*) otherpath$1  [P]                 not supported, because silly!
----------------------------------------------  ----------------------------------
^localpath(.*) /otherpath$1                     /otherpath/pathinfo

^localpath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
                                                via external redirection

^localpath(.*) /otherpath$1 [P]                 not supported, because silly!
----------------------------------------------  ----------------------------------
^localpath(.*) http://thishost/otherpath$1      /otherpath/pathinfo

^localpath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
                                                via external redirection

^localpath(.*) http://thishost/otherpath$1 [P]  not supported, because silly!
----------------------------------------------  ----------------------------------
^localpath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
                                                via external redirection

^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
                                                via external redirection
                                                (the [R] flag is redundant)

^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
                                                via internal proxy

Example:

We want to rewrite URLs of the form

/ Language /~ Realname /.../ File

into

/u/ Username /.../ File . Language

We take the rewrite mapfile from above and save it under /path/to/file/map.txt. Then we only have to add the following lines to the Apache server configuration file:

RewriteLog   /path/to/file/rewrite.log
RewriteMap   real-to-user               txt:/path/to/file/map.txt
RewriteRule  ^/([^/]+)/~([^/]+)/(.*)$   /u/${real-to-user:$2|nobody}/$3.$1


mod_setenvif - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_setenvif

Description: | Allows the setting of environment variables based on characteristics of the request
Status: | Base
Module Identifier: | setenvif_module
Source File: | mod_setenvif.c

Summary

The mod_setenvif module allows you to set environment variables according to whether different aspects of the request match regular expressions you specify. These environment variables can be used by other parts of the server to make decisions about actions to be taken.

The directives are considered in the order they appear in the configuration files. So more complex sequences can be used, such as this example, which sets netscape if the browser is mozilla but not MSIE.

BrowserMatch ^Mozilla netscape
BrowserMatch MSIE !netscape

See also

  • Environment Variables in Apache

BrowserMatch Directive

Description: | Sets environment variables conditional on HTTP User-Agent
Syntax: | BrowserMatch regex [!]env-variable[=value] [[!]env-variable[=value]] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_setenvif

The BrowserMatch is a special cases of the SetEnvIf directive that sets environment variables conditional on the User-Agent HTTP request header. The following two lines have the same effect:

BrowserMatchNoCase Robot is_a_robot
SetEnvIfNoCase User-Agent Robot is_a_robot

Some additional examples:

BrowserMatch ^Mozilla forms jpeg=yes browser=netscape
BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
BrowserMatch MSIE !javascript

BrowserMatchNoCase Directive

Description: | Sets environment variables conditional on User-Agent without respect to case
Syntax: | BrowserMatchNoCase regex [!]env-variable[=value] [[!]env-variable[=value]] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_setenvif
Compatibility: | Apache 1.2 and above (in Apache 1.2 this directive was found in the now-obsolete mod_browser module)

The BrowserMatchNoCase directive is semantically identical to the BrowserMatch directive. However, it provides for case-insensitive matching. For example:

BrowserMatchNoCase mac platform=macintosh
BrowserMatchNoCase win platform=windows

The BrowserMatch and BrowserMatchNoCase directives are special cases of the SetEnvIf and SetEnvIfNoCase directives. The following two lines have the same effect:

BrowserMatchNoCase Robot is_a_robot
SetEnvIfNoCase User-Agent Robot is_a_robot

SetEnvIf Directive

Description: | Sets environment variables based on attributes of the request
Syntax: | SetEnvIf attribute regex [!]env-variable[=value] [[!]env-variable[=value]] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_setenvif

The SetEnvIf directive defines environment variables based on attributes of the request. The attribute specified in the first argument can be one of three things:

  1. An HTTP request header field (see RFC2616 for more information about these); for example: Host, User-Agent, Referer, and Accept-Language. A regular expression may be used to specify a set of request headers.
  2. One of the following aspects of the request:
    • Remote_Host - the hostname (if available) of the client making the request
    • Remote_Addr - the IP address of the client making the request
    • Server_Addr - the IP address of the server on which the request was received (only with versions later than 2.0.43)
    • Remote_User - the authenticated username (if available)
    • Request_Method - the name of the method being used (GET, POST, et cetera)
    • Request_Protocol - the name and version of the protocol with which the request was made (e.g., "HTTP/0.9", "HTTP/1.1", etc.)
    • Request_URI - the resource requested on the HTTP request line -- generally the portion of the URL following the scheme and host portion without the query string
  3. The name of an environment variable in the list of those associated with the request. This allows SetEnvIf directives to test against the result of prior matches. Only those environment variables defined by earlier SetEnvIf[NoCase] directives are available for testing in this manner. 'Earlier' means that they were defined at a broader scope (such as server-wide) or previously in the current directive's scope. Environment variables will be considered only if there was no match among request characteristics and a regular expression was not used for the attribute.

The second argument (regex) is a Perl compatible regular expression. This is similar to a POSIX.2 egrep-style regular expression. If the regex matches against the attribute, then the remainder of the arguments are evaluated.

The rest of the arguments give the names of variables to set, and optionally values to which they should be set. These take the form of

  1. varname, or
  2. !varname, or
  3. varname=value

In the first form, the value will be set to "1". The second will remove the given variable if already defined, and the third will set the variable to the literal value given by value.

Example:

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

The first three will set the environment variable object_is_image if the request was for an image file, and the fourth sets intra_site_referral if the referring page was somewhere on the www.mydomain.com Web site.

The last example will set environment variable HAVE_TS if the request contains any headers that begin with "TS" whose values begins with any character in the set [a-z].

See also

  • Environment Variables in Apache, for additional examples.

SetEnvIfNoCase Directive

Description: | Sets environment variables based on attributes of the request without respect to case
Syntax: | SetEnvIfNoCase attribute regex [!]env-variable[=value] [[!]env-variable[=value]] ...
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Base
Module: | mod_setenvif
Compatibility: | Apache 1.3 and above

The SetEnvIfNoCase is semantically identical to the SetEnvIf directive, and differs only in that the regular expression matching is performed in a case-insensitive manner. For example:

SetEnvIfNoCase Host Apache\.Org site=apache

This will cause the site environment variable to be set to "apache" if the HTTP request header field Host: was included and contained Apache.Org, apache.org, or any other combination.


mod_so - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_so

Description: | Loading of executable code and modules into the server at start-up or restart time
Status: | Extension
Module Identifier: | so_module
Source File: | mod_so.c
Compatibility: | This is a Base module (always included) on Windows

Summary

On selected operating systems this module can be used to load modules into Apache at runtime via the Dynamic Shared Object (DSO) mechanism, rather than requiring a recompilation.

On Unix, the loaded code typically comes from shared object files (usually with .so extension), on Windows this may either the .so or .dll extension.

Warning

Apache 1.3 modules cannot be directly used with Apache 2.0 - the module must be modified to dynamically load or compile into Apache 2.0.

Creating Loadable Modules for Windows

Note

The module name format changed for Windows with Apache 1.3.15 and 2.0 - the modules are now named as mod_foo.so

While mod_so still loads modules with ApacheModuleFoo.dll names, the new naming convention is preferred; if you are converting your loadable module for 2.0, please fix the name to this 2.0 convention.

The Apache module API is unchanged between the Unix and Windows versions. Many modules will run on Windows with no or little change from Unix, although others rely on aspects of the Unix architecture which are not present in Windows, and will not work.

When a module does work, it can be added to the server in one of two ways. As with Unix, it can be compiled into the server. Because Apache for Windows does not have the Configure program of Apache for Unix, the module's source file must be added to the ApacheCore project file, and its symbols must be added to the os\win32\modules.c file.

The second way is to compile the module as a DLL, a shared library that can be loaded into the server at runtime, using the LoadModule directive. These module DLLs can be distributed and run on any Apache for Windows installation, without recompilation of the server.

To create a module DLL, a small change is necessary to the module's source file: The module record must be exported from the DLL (which will be created later; see below). To do this, add the AP_MODULE_DECLARE_DATA (defined in the Apache header files) to your module's module record definition. For example, if your module has:

module foo_module;

Replace the above with:

module AP_MODULE_DECLARE_DATA foo_module;

Note that this will only be activated on Windows, so the module can continue to be used, unchanged, with Unix if needed. Also, if you are familiar with .DEF files, you can export the module record with that method instead.

Now, create a DLL containing your module. You will need to link this against the libhttpd.lib export library that is created when the libhttpd.dll shared library is compiled. You may also have to change the compiler settings to ensure that the Apache header files are correctly located. You can find this library in your server root's modules directory. It is best to grab an existing module .dsp file from the tree to assure the build environment is configured correctly, or alternately compare the compiler and link options to your .dsp.

This should create a DLL version of your module. Now simply place it in the modules directory of your server root, and use the LoadModule directive to load it.

LoadFile Directive

Description: | Link in the named object file or library
Syntax: | LoadFile filename [filename] ...
Context: | server config
Status: | Extension
Module: | mod_so

The LoadFile directive links in the named object files or libraries when the server is started or restarted; this is used to load additional code which may be required for some module to work. Filename is either an absolute path or relative to ServerRoot.

For example:

LoadFile libexec/libxmlparse.so

LoadModule Directive

Description: | Links in the object file or library, and adds to the list of active modules
Syntax: | LoadModule module filename
Context: | server config
Status: | Extension
Module: | mod_so

The LoadModule directive links in the object file or library filename and adds the module structure named module to the list of active modules. Module is the name of the external variable of type module in the file, and is listed as the Module Identifier in the module documentation. Example:

LoadModule status_module modules/mod_status.so

loads the named module from the modules subdirectory of the ServerRoot.


mod_speling - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_speling

Description: | Attempts to correct mistaken URLs that users might have entered by ignoring capitalization and by allowing up to one misspelling
Status: | Extension
Module Identifier: | speling_module
Source File: | mod_speling.c

Summary

Requests to documents sometimes cannot be served by the core apache server because the request was misspelled or miscapitalized. This module addresses this problem by trying to find a matching document, even after all other modules gave up. It does its work by comparing each document name in the requested directory against the requested document name without regard to case, and allowing up to one misspelling (character insertion / omission / transposition or wrong character). A list is built with all document names which were matched using this strategy.

If, after scanning the directory,

  • no matching document was found, Apache will proceed as usual and return a "document not found" error.
  • only one document is found that "almost" matches the request, then it is returned in the form of a redirection response.
  • more than one document with a close match was found, then the list of the matches is returned to the client, and the client can select the correct candidate.

CheckSpelling Directive

Description: | Enables the spelling module
Syntax: | CheckSpelling on|off
Default: | CheckSpelling Off
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Extension
Module: | mod_speling
Compatibility: | CheckSpelling was available as a separately available module for Apache 1.1, but was limited to miscapitalizations. As of Apache 1.3, it is part of the Apache distribution. Prior to Apache 1.3.2, the CheckSpelling directive was only available in the "server" and "virtual host" contexts.

This directive enables or disables the spelling module. When enabled, keep in mind that

  • the directory scan which is necessary for the spelling correction will have an impact on the server's performance when many spelling corrections have to be performed at the same time.
  • the document trees should not contain sensitive files which could be matched inadvertently by a spelling "correction".
  • the module is unable to correct misspelled user names (as in http://my.host/~apahce/), just file names or directory names.
  • spelling corrections apply strictly to existing files, so a request for the <Location /status> may get incorrectly treated as the negotiated file "/stats.html".


mod_ssl - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_ssl

Description: | Strong cryptography using the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols
Status: | Extension
Module 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 provides a lot of SSL information as additional environment variables to the SSI and CGI namespace. The generated variables are listed in the table below. For backward compatibility the information can be made available under different names, too. Look in the Compatibility chapter for details on the compatibility variables.

Variable Name: | Value Type: | Description:
HTTPS | flag | HTTPS is being used.
SSL_PROTOCOL | string | The SSL protocol version (SSLv2, SSLv3, TLSv1)
SSL_SESSION_ID | string | The hex-encoded SSL session id
SSL_CIPHER | string | The cipher specification name
SSL_CIPHER_EXPORT | string | true if cipher is an export cipher
SSL_CIPHER_USEKEYSIZE | number | Number of cipher bits (actually used)
SSL_CIPHER_ALGKEYSIZE | number | Number of cipher bits (possible)
SSL_VERSION_INTERFACE | string | The mod_ssl program version
SSL_VERSION_LIBRARY | string | The OpenSSL program version
SSL_CLIENT_M_VERSION | string | The version of the client certificate
SSL_CLIENT_M_SERIAL | string | The serial of the client certificate
SSL_CLIENT_S_DN | string | Subject DN in client's certificate
SSL_CLIENT_S_DN_x509 | string | Component of client's Subject DN
SSL_CLIENT_I_DN | string | Issuer DN of client's certificate
SSL_CLIENT_I_DN_x509 | string | Component of client's Issuer DN
SSL_CLIENT_V_START | string | Validity of client's certificate (start time)
SSL_CLIENT_V_END | string | Validity of client's certificate (end time)
SSL_CLIENT_A_SIG | string | Algorithm used for the signature of client's certificate
SSL_CLIENT_A_KEY | string | Algorithm used for the public key of client's certificate
SSL_CLIENT_CERT | string | PEM-encoded client certificate
SSL_CLIENT_CERT_CHAIN n | string | PEM-encoded certificates in client certificate chain
SSL_CLIENT_VERIFY | string | NONE, SUCCESS, GENEROUS or FAILED:reason
SSL_SERVER_M_VERSION | string | The version of the server certificate
SSL_SERVER_M_SERIAL | string | The serial of the server certificate
SSL_SERVER_S_DN | string | Subject DN in server's certificate
SSL_SERVER_S_DN_x509 | string | Component of server's Subject DN
SSL_SERVER_I_DN | string | Issuer DN of server's certificate
SSL_SERVER_I_DN_x509 | string | Component of server's Issuer DN
SSL_SERVER_V_START | string | Validity of server's certificate (start time)
SSL_SERVER_V_END | string | Validity of server's certificate (end time)
SSL_SERVER_A_SIG | string | Algorithm used for the signature of server's certificate
SSL_SERVER_A_KEY | string | Algorithm used for the public key of server's certificate
SSL_SERVER_CERT | string | PEM-encoded server certificate
[ where x509 is a component of a X.509 DN: C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email ]

Custom Log Formats

When mod_ssl is built into Apache or at least loaded (under DSO situation) additional functions exist for the Custom Log Format of mod_log_config. First there is an additional ``%{varname}x'' eXtension format function which can be used to expand any variables provided by any module, especially those provided by mod_ssl which can you find in the above table.

For backward compatibility there is additionally a special ``%{name}c'' cryptography format function provided. Information about this function is provided in the Compatibility chapter.

Example:

CustomLog logs/ssl_request_log \ "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

SSLCACertificateFile Directive

Description: | File of concatenated PEM-encoded CA Certificates for Client Auth
Syntax: | SSLCACertificateFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose clients you deal with. These are used for Client Authentication. Such a file is simply the concatenation of the various PEM-encoded Certificate files, in order of preference. This can be used alternatively and/or additionally to SSLCACertificatePath.

Example

SSLCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt

SSLCACertificatePath Directive

Description: | Directory of PEM-encoded CA Certificates for Client Auth
Syntax: | SSLCACertificatePath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the Certificates of Certification Authorities (CAs) whose clients you deal with. These are used to verify the client certificate on Client Authentication.

The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you can't just place the Certificate files there: you also have to create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.

Example

SSLCACertificatePath /usr/local/apache2/conf/ssl.crt/

SSLCARevocationFile Directive

Description: | File of concatenated PEM-encoded CA CRLs for Client Auth
Syntax: | SSLCARevocationFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you can assemble the Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose clients you deal with. These are used for Client Authentication. Such a file is simply the concatenation of the various PEM-encoded CRL files, in order of preference. This can be used alternatively and/or additionally to SSLCARevocationPath.

Example

SSLCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-client.crl

SSLCARevocationPath Directive

Description: | Directory of PEM-encoded CA CRLs for Client Auth
Syntax: | SSLCARevocationPath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the Certificate Revocation Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. These are used to revoke the client certificate on Client Authentication.

The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you have not only to place the CRL files there. Additionally you have to create symbolic links named hash-value.rN. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.

Example

SSLCARevocationPath /usr/local/apache2/conf/ssl.crl/

SSLCertificateChainFile Directive

Description: | File of PEM-encoded Server CA Certificates
Syntax: | SSLCertificateChainFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the optional all-in-one file where you can assemble the certificates of Certification Authorities (CA) which form the certificate chain of the server certificate. This starts with the issuing CA certificate of of the server certificate and can range up to the root CA certificate. Such a file is simply the concatenation of the various PEM-encoded CA Certificate files, usually in certificate chain order.

This should be used alternatively and/or additionally to SSLCACertificatePath for explicitly constructing the server certificate chain which is sent to the browser in addition to the server certificate. It is especially useful to avoid conflicts with CA certificates when using client authentication. Because although placing a CA certificate of the server certificate chain into SSLCACertificatePath has the same effect for the certificate chain construction, it has the side-effect that client certificates issued by this same CA certificate are also accepted on client authentication. That's usually not one expect.

But be careful: Providing the certificate chain works only if you are using a single (either RSA or DSA) based server certificate. If you are using a coupled RSA+DSA certificate pair, this will work only if actually both certificates use the same certificate chain. Else the browsers will be confused in this situation.

Example

SSLCertificateChainFile /usr/local/apache2/conf/ssl.crt/ca.crt

SSLCertificateFile Directive

Description: | Server PEM-encoded X.509 Certificate file
Syntax: | SSLCertificateFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive points to the PEM-encoded Certificate file for the server and optionally also to the corresponding RSA or DSA Private Key file for it (contained in the same file). If the contained Private Key is encrypted the Pass Phrase dialog is forced at startup time. This directive can be used up to two times (referencing different filenames) when both a RSA and a DSA based server certificate is used in parallel.

Example

SSLCertificateFile /usr/local/apache2/conf/ssl.crt/server.crt

SSLCertificateKeyFile Directive

Description: | Server PEM-encoded Private Key file
Syntax: | SSLCertificateKeyFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive points to the PEM-encoded Private Key file for the server. If the Private Key is not combined with the Certificate in the SSLCertificateFile, use this additional directive to point to the file with the stand-alone Private Key. When SSLCertificateFile is used and the file contains both the Certificate and the Private Key this directive need not be used. But we strongly discourage this practice. Instead we recommend you to separate the Certificate and the Private Key. If the contained Private Key is encrypted, the Pass Phrase dialog is forced at startup time. This directive can be used up to two times (referencing different filenames) when both a RSA and a DSA based private key is used in parallel.

Example

SSLCertificateKeyFile /usr/local/apache2/conf/ssl.key/server.key

SSLCipherSuite Directive

Description: | Cipher Suite available for negotiation in SSL handshake
Syntax: | SSLCipherSuite cipher-spec
Default: | SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This complex directive uses a colon-separated cipher-spec string consisting of OpenSSL cipher specifications to configure the Cipher Suite the client is permitted to negotiate in the SSL handshake phase. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotation with the reconfigured Cipher Suite after the HTTP request was read but before the HTTP response is sent.

An SSL cipher specification in cipher-spec is composed of 4 major attributes plus a few extra minor ones:

  • Key Exchange Algorithm:
    RSA or Diffie-Hellman variants.
  • Authentication Algorithm:
    RSA, Diffie-Hellman, DSS or none.
  • Cipher/Encryption Algorithm:
    DES, Triple-DES, RC4, RC2, IDEA or none.
  • MAC Digest Algorithm:
    MD5, SHA or SHA1.

An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1 cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use, one can either specify all the Ciphers, one at a time, or use aliases to specify the preference and order for the ciphers (see Table 1).

Tag | Description
Key Exchange Algorithm:
kRSA | RSA key exchange
kDHr | Diffie-Hellman key exchange with RSA key
kDHd | Diffie-Hellman key exchange with DSA key
kEDH | Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)
Authentication Algorithm:
aNULL | No authentication
aRSA | RSA authentication
aDSS | DSS authentication
aDH | Diffie-Hellman authentication
Cipher Encoding Algorithm:
eNULL | No encoding
DES | DES encoding
3DES | Triple-DES encoding
RC4 | RC4 encoding
RC2 | RC2 encoding
IDEA | IDEA encoding
MAC Digest Algorithm:
MD5 | MD5 hash function
SHA1 | SHA1 hash function
SHA | SHA hash function
Aliases:
SSLv2 | all SSL version 2.0 ciphers
SSLv3 | all SSL version 3.0 ciphers
TLSv1 | all TLS version 1.0 ciphers
EXP | all export ciphers
EXPORT40 | all 40-bit export ciphers only
EXPORT56 | all 56-bit export ciphers only
LOW | all low strength ciphers (no export, single DES)
MEDIUM | all ciphers with 128 bit encryption
HIGH | all ciphers using Triple-DES
RSA | all ciphers using RSA key exchange
DH | all ciphers using Diffie-Hellman key exchange
EDH | all ciphers using Ephemeral Diffie-Hellman key exchange
ADH | all ciphers using Anonymous Diffie-Hellman key exchange
DSS | all ciphers using DSS authentication
NULL | all ciphers using no encryption

Now where this becomes interesting is that these can be put together to specify the order and ciphers you wish to use. To speed this up there are also aliases (SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM, HIGH) for certain groups of ciphers. These tags can be joined together with prefixes to form the cipher-spec. Available prefixes are:

  • none: add cipher to list
  • +: add ciphers to list and pull them to current location in list
  • -: remove cipher from list (can be added later again)
  • !: kill cipher from list completely (can not be added later again)

A simpler way to look at all of this is to use the ``openssl ciphers -v'' command which provides a nice way to successively create the correct cipher-spec string. The default cipher-spec string is ``ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'' which means the following: first, remove from consideration any ciphers that do not authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next, use ciphers using RC4 and RSA. Next include the high, medium and then the low security ciphers. Finally pull all SSLv2 and export ciphers to the end of the list.

$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'
NULL-SHA                SSLv3 Kx=RSA      Au=RSA  Enc=None      Mac=SHA1
NULL-MD5                SSLv3 Kx=RSA      Au=RSA  Enc=None      Mac=MD5
EDH-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
...                     ...               ...     ...           ...
EXP-RC4-MD5             SSLv3 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
EXP-RC2-CBC-MD5         SSLv2 Kx=RSA(512) Au=RSA  Enc=RC2(40)   Mac=MD5  export
EXP-RC4-MD5             SSLv2 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export

The complete list of particular RSA & DH ciphers for SSL is given in Table 2.

Example

SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW

Cipher-Tag | Protocol | Key Ex. | Auth. | Enc. | MAC | Type
RSA Ciphers:
DES-CBC3-SHA | SSLv3 | RSA | RSA | 3DES(168) | SHA1 |
DES-CBC3-MD5 | SSLv2 | RSA | RSA | 3DES(168) | MD5 |
IDEA-CBC-SHA | SSLv3 | RSA | RSA | IDEA(128) | SHA1 |
RC4-SHA | SSLv3 | RSA | RSA | RC4(128) | SHA1 |
RC4-MD5 | SSLv3 | RSA | RSA | RC4(128) | MD5 |
IDEA-CBC-MD5 | SSLv2 | RSA | RSA | IDEA(128) | MD5 |
RC2-CBC-MD5 | SSLv2 | RSA | RSA | RC2(128) | MD5 |
RC4-MD5 | SSLv2 | RSA | RSA | RC4(128) | MD5 |
DES-CBC-SHA | SSLv3 | RSA | RSA | DES(56) | SHA1 |
RC4-64-MD5 | SSLv2 | RSA | RSA | RC4(64) | MD5 |
DES-CBC-MD5 | SSLv2 | RSA | RSA | DES(56) | MD5 |
EXP-DES-CBC-SHA | SSLv3 | RSA(512) | RSA | DES(40) | SHA1 | export
EXP-RC2-CBC-MD5 | SSLv3 | RSA(512) | RSA | RC2(40) | MD5 | export
EXP-RC4-MD5 | SSLv3 | RSA(512) | RSA | RC4(40) | MD5 | export
EXP-RC2-CBC-MD5 | SSLv2 | RSA(512) | RSA | RC2(40) | MD5 | export
EXP-RC4-MD5 | SSLv2 | RSA(512) | RSA | RC4(40) | MD5 | export
NULL-SHA | SSLv3 | RSA | RSA | None | SHA1 |
NULL-MD5 | SSLv3 | RSA | RSA | None | MD5 |
Diffie-Hellman Ciphers:
ADH-DES-CBC3-SHA | SSLv3 | DH | None | 3DES(168) | SHA1 |
ADH-DES-CBC-SHA | SSLv3 | DH | None | DES(56) | SHA1 |
ADH-RC4-MD5 | SSLv3 | DH | None | RC4(128) | MD5 |
EDH-RSA-DES-CBC3-SHA | SSLv3 | DH | RSA | 3DES(168) | SHA1 |
EDH-DSS-DES-CBC3-SHA | SSLv3 | DH | DSS | 3DES(168) | SHA1 |
EDH-RSA-DES-CBC-SHA | SSLv3 | DH | RSA | DES(56) | SHA1 |
EDH-DSS-DES-CBC-SHA | SSLv3 | DH | DSS | DES(56) | SHA1 |
EXP-EDH-RSA-DES-CBC-SHA | SSLv3 | DH(512) | RSA | DES(40) | SHA1 | export
EXP-EDH-DSS-DES-CBC-SHA | SSLv3 | DH(512) | DSS | DES(40) | SHA1 | export
EXP-ADH-DES-CBC-SHA | SSLv3 | DH(512) | None | DES(40) | SHA1 | export
EXP-ADH-RC4-MD5 | SSLv3 | DH(512) | None | RC4(40) | MD5 | export

SSLEngine Directive

Description: | SSL Engine Operation Switch
Syntax: | SSLEngine on|off
Default: | SSLEngine off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive toggles the usage of the SSL/TLS Protocol Engine. This is usually used inside a <VirtualHost> section to enable SSL/TLS for a particular virtual host. By default the SSL/TLS Protocol Engine is disabled for both the main server and all configured virtual hosts.

Example

<VirtualHost _default_:443>
SSLEngine on
...
</VirtualHost>

SSLMutex Directive

Description: | Semaphore for internal mutual exclusion of operations
Syntax: | SSLMutex type
Default: | SSLMutex none
Context: | server config
Status: | Extension
Module: | mod_ssl

This configures the SSL engine's semaphore (aka. lock) which is used for mutual exclusion of operations which have to be done in a synchronized way between the pre-forked Apache server processes. This directive can only be used in the global server context because it's only useful to have one global mutex. This directive is designed to closely match the AcceptMutex directive

The following Mutex types are available:

  • none | no

    This is the default where no Mutex is used at all. Use it at your own risk. But because currently the Mutex is mainly used for synchronizing write access to the SSL Session Cache you can live without it as long as you accept a sometimes garbled Session Cache. So it's not recommended to leave this the default. Instead configure a real Mutex.

  • posixsem

    This is an elegant Mutex variant where a Posix Semaphore is used when possible. It is only available when the underlying platform and APR supports it.

  • sysvsem

    This is a somewhat elegant Mutex variant where a SystemV IPC Semaphore is used when possible. It is possible to "leak" SysV semaphores if processes crash before the semaphore is removed. It is only available when the underlying platform and APR supports it.

  • sem

    This directive tells the SSL Module to pick the "best" semaphore implementation available to it, choosing between Posix and SystemV IPC, in that order. It is only available when the underlying platform and APR supports at least one of the 2.

  • pthread

    This directive tells the SSL Module to use Posix thread mutexes. It is only available if the underlying platform and APR supports it.

  • fcntl:/path/to/mutex

    This is a portable Mutex variant where a physical (lock-)file and the fcntl() fucntion are used as the Mutex. Always use a local disk filesystem for /path/to/mutex and never a file residing on a NFS- or AFS-filesystem. It is only available when the underlying platform and APR supports it. Note: Internally, the Process ID (PID) of the Apache parent process is automatically appended to /path/to/mutex to make it unique, so you don't have to worry about conflicts yourself. Notice that this type of mutex is not available under the Win32 environment. There you have to use the semaphore mutex.

  • flock:/path/to/mutex

    This is similar to the fcntl:/path/to/mutex method with the exception that the flock() function is used to provide file locking. It is only available when the underlying platform and APR supports it.

  • file:/path/to/mutex

    This directive tells the SSL Module to pick the "best" file locking implementation available to it, choosing between fcntl and flock, in that order. It is only available when the underlying platform and APR supports at least one of the 2.

  • default | yes

    This directive tells the SSL Module to pick the default locking implementation as determined by the platform and APR.

Example

SSLMutex file:/usr/local/apache/logs/ssl_mutex

SSLOptions Directive

Description: | Configure various SSL engine run-time options
Syntax: | SSLOptions [+|-]option ...
Context: | server config, virtual host, directory, .htaccess
Override: | Options
Status: | Extension
Module: | mod_ssl

This directive can be used to control various run-time options on a per-directory basis. Normally, if multiple SSLOptions could apply to a directory, then the most specific one is taken completely; the options are not merged. However if all the options on the SSLOptions directive are preceded by a plus (+) or minus (-) symbol, the options are merged. Any options preceded by a + are added to the options currently in force, and any options preceded by a - are removed from the options currently in force.

The available options are:

  • StdEnvVars

    When this option is enabled, the standard set of SSL related CGI/SSI environment variables are created. This per default is disabled for performance reasons, because the information extraction step is a rather expensive operation. So one usually enables this option for CGI and SSI requests only.

  • CompatEnvVars

    When this option is enabled, additional CGI/SSI environment variables are created for backward compatibility to other Apache SSL solutions. Look in the Compatibility chapter for details on the particular variables generated.

  • ExportCertData

    When this option is enabled, additional CGI/SSI environment variables are created: SSL_SERVER_CERT, SSL_CLIENT_CERT and SSL_CLIENT_CERT_CHAIN n (with n = 0,1,2,..). These contain the PEM-encoded X.509 Certificates of server and client for the current HTTPS connection and can be used by CGI scripts for deeper Certificate checking. Additionally all other certificates of the client certificate chain are provided, too. This bloats up the environment a little bit which is why you have to use this option to enable it on demand.

  • FakeBasicAuth

    When this option is enabled, the Subject Distinguished Name (DN) of the Client X509 Certificate is translated into a HTTP Basic Authorization username. This means that the standard Apache authentication methods can be used for access control. The user name is just the Subject of the Client's X509 Certificate (can be determined by running OpenSSL's openssl x509 command: openssl x509 -noout -subject -in certificate.crt). Note that no password is obtained from the user. Every entry in the user file needs this password: ``xxj31ZMTZzkVA'', which is the DES-encrypted version of the word `password''. Those who live under MD5-based encryption (for instance under FreeBSD or BSD/OS, etc.) should use the following MD5 hash of the same word: ``$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/''.

  • StrictRequire

    This forces forbidden access when SSLRequireSSL or SSLRequire successfully decided that access should be forbidden. Usually the default is that in the case where a ``Satisfy any'' directive is used, and other access restrictions are passed, denial of access due to SSLRequireSSL or SSLRequire is overridden (because that's how the Apache Satisfy mechanism should work.) But for strict access restriction you can use SSLRequireSSL and/or SSLRequire in combination with an ``SSLOptions +StrictRequire''. Then an additional ``Satisfy Any'' has no chance once mod_ssl has decided to deny access.

  • OptRenegotiate

    This enables optimized SSL connection renegotiation handling when SSL directives are used in per-directory context. By default a strict scheme is enabled where every per-directory reconfiguration of SSL parameters causes a full SSL renegotiation handshake. When this option is used mod_ssl tries to avoid unnecessary handshakes by doing more granular (but still safe) parameter checks. Nevertheless these granular checks sometimes maybe not what the user expects, so enable this on a per-directory basis only, please.

Example

SSLOptions +FakeBasicAuth -StrictRequire
<Files ~ "\.(cgi|shtml)$">
SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData
<Files>

SSLPassPhraseDialog Directive

Description: | Type of pass phrase dialog for encrypted private keys
Syntax: | SSLPassPhraseDialog type
Default: | SSLPassPhraseDialog builtin
Context: | server config
Status: | Extension
Module: | mod_ssl

When Apache starts up it has to read the various Certificate (see SSLCertificateFile) and Private Key (see SSLCertificateKeyFile) files of the SSL-enabled virtual servers. Because for security reasons the Private Key files are usually encrypted, mod_ssl needs to query the administrator for a Pass Phrase in order to decrypt those files. This query can be done in two ways which can be configured by type:

  • builtin

    This is the default where an interactive terminal dialog occurs at startup time just before Apache detaches from the terminal. Here the administrator has to manually enter the Pass Phrase for each encrypted Private Key file. Because a lot of SSL-enabled virtual hosts can be configured, the following reuse-scheme is used to minimize the dialog: When a Private Key file is encrypted, all known Pass Phrases (at the beginning there are none, of course) are tried. If one of those known Pass Phrases succeeds no dialog pops up for this particular Private Key file. If none succeeded, another Pass Phrase is queried on the terminal and remembered for the next round (where it perhaps can be reused).

    This scheme allows mod_ssl to be maximally flexible (because for N encrypted Private Key files you can use N different Pass Phrases - but then you have to enter all of them, of course) while minimizing the terminal dialog (i.e. when you use a single Pass Phrase for all N Private Key files this Pass Phrase is queried only once).

  • exec:/path/to/program

    Here an external program is configured which is called at startup for each encrypted Private Key file. It is called with two arguments (the first is of the form ``servername:portnumber'', the second is either ``RSA'' or ``DSA''), which indicate for which server and algorithm it has to print the corresponding Pass Phrase to stdout. The intent is that this external program first runs security checks to make sure that the system is not compromised by an attacker, and only when these checks were passed successfully it provides the Pass Phrase.

    Both these security checks, and the way the Pass Phrase is determined, can be as complex as you like. Mod_ssl just defines the interface: an executable program which provides the Pass Phrase on stdout. Nothing more or less! So, if you're really paranoid about security, here is your interface. Anything else has to be left as an exercise to the administrator, because local security requirements are so different.

    The reuse-algorithm above is used here, too. In other words: The external program is called only once per unique Pass Phrase.

Example:

SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter

SSLProtocol Directive

Description: | Configure usable SSL protocol flavors
Syntax: | SSLProtocol [+|-]protocol ...
Default: | SSLProtocol all
Context: | server config, virtual host
Override: | Options
Status: | Extension
Module: | mod_ssl

This directive can be used to control the SSL protocol flavors mod_ssl should use when establishing its server environment. Clients then can only connect with one of the provided protocols.

The available (case-insensitive) protocols are:

  • SSLv2

    This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the original SSL protocol as designed by Netscape Corporation.

  • SSLv3

    This is the Secure Sockets Layer (SSL) protocol, version 3.0. It is the successor to SSLv2 and the currently (as of February 1999) de-facto standardized SSL protocol from Netscape Corporation. It's supported by almost all popular browsers.

  • TLSv1

    This is the Transport Layer Security (TLS) protocol, version 1.0. It is the successor to SSLv3 and currently (as of February 1999) still under construction by the Internet Engineering Task Force (IETF). It's still not supported by any popular browsers.

  • All

    This is a shortcut for ``+SSLv2 +SSLv3 +TLSv1'' and a convinient way for enabling all protocols except one when used in combination with the minus sign on a protocol as the example above shows.

Example

# enable SSLv3 and TLSv1, but not SSLv2
SSLProtocol all -SSLv2

SSLProxyCACertificateFile Directive

Description: | File of concatenated PEM-encoded CA Certificates for Remote Server Auth
Syntax: | SSLProxyCACertificateFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose remote servers you deal with. These are used for Remote Server Authentication. Such a file is simply the concatenation of the various PEM-encoded Certificate files, in order of preference. This can be used alternatively and/or additionally to SSLProxyCACertificatePath.

Example

SSLProxyCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-remote-server.crt

SSLProxyCACertificatePath Directive

Description: | Directory of PEM-encoded CA Certificates for Remote Server Auth
Syntax: | SSLProxyCACertificatePath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the Certificates of Certification Authorities (CAs) whose remote servers you deal with. These are used to verify the remote server certificate on Remote Server Authentication.

The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you can't just place the Certificate files there: you also have to create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.

Example

SSLProxyCACertificatePath /usr/local/apache2/conf/ssl.crt/

SSLProxyCARevocationFile Directive

Description: | File of concatenated PEM-encoded CA CRLs for Remote Server Auth
Syntax: | SSLProxyCARevocationFile file-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you can assemble the Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose remote servers you deal with. These are used for Remote Server Authentication. Such a file is simply the concatenation of the various PEM-encoded CRL files, in order of preference. This can be used alternatively and/or additionally to SSLProxyCARevocationPath.

Example

SSLProxyCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-remote-server.crl

SSLProxyCARevocationPath Directive

Description: | Directory of PEM-encoded CA CRLs for Remote Server Auth
Syntax: | SSLProxyCARevocationPath directory-path
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the Certificate Revocation Lists (CRL) of Certification Authorities (CAs) whose remote servers you deal with. These are used to revoke the remote server certificate on Remote Server Authentication.

The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you have not only to place the CRL files there. Additionally you have to create symbolic links named hash-value.rN. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.

Example

SSLProxyCARevocationPath /usr/local/apache2/conf/ssl.crl/

SSLProxyCipherSuite Directive

Description: | Cipher Suite available for negotiation in SSL proxy handshake
Syntax: | SSLProxyCipherSuite cipher-spec
Default: | SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

Equivalent to SSLCipherSuite, but for the proxy connection. Please refer to SSLCipherSuite for additional information.

SSLProxyEngine Directive

Description: | SSL Proxy Engine Operation Switch
Syntax: | SSLProxyEngine on|off
Default: | SSLProxyEngine off
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive toggles the usage of the SSL/TLS Protocol Engine for proxy. This is usually used inside a <VirtualHost> section to enable SSL/TLS for proxy usage in a particular virtual host. By default the SSL/TLS Protocol Engine is disabled for proxy image both for the main server and all configured virtual hosts.

Example

<VirtualHost _default_:443>
SSLProxyEngine on
...
</VirtualHost>

SSLProxyMachineCertificateFile Directive

Description: | File of concatenated PEM-encoded client certificates and keys to be used by the proxy
Syntax: | SSLProxyMachineCertificateFile filename
Context: | server config
Override: | Not applicable
Status: | Extension
Module: | mod_ssl

This directive sets the all-in-one file where you keep the certificates and keys used for authentication of the proxy server to remote servers.

This referenced file is simply the concatenation of the various PEM-encoded certificate files, in order of preference. Use this directive alternatively or additionally to SSLProxyMachineCertificatePath.

Currently there is no support for encrypted private keys

Example:

SSLProxyMachineCertificateFile /usr/local/apache2/conf/ssl.crt/proxy.pem

SSLProxyMachineCertificatePath Directive

Description: | Directory of PEM-encoded client certificates and keys to be used by the proxy
Syntax: | SSLProxyMachineCertificatePath directory
Context: | server config
Override: | Not applicable
Status: | Extension
Module: | mod_ssl

This directive sets the directory where you keep the certificates and keys used for authentication of the proxy server to remote servers.

The files in this directory must be PEM-encoded and are accessed through hash filenames. Additionally, you must create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.

Currently there is no support for encrypted private keys

Example:

SSLProxyMachineCertificatePath /usr/local/apache2/conf/proxy.crt/

SSLProxyProtocol Directive

Description: | Configure usable SSL protocol flavors for proxy usage
Syntax: | SSLProxyProtocol [+|-]protocol ...
Default: | SSLProxyProtocol all
Context: | server config, virtual host
Override: | Options
Status: | Extension
Module: | mod_ssl

This directive can be used to control the SSL protocol flavors mod_ssl should use when establishing its server environment for proxy . It will only connect to servers using one of the provided protocols.

Please refer to SSLProtocol for additional information.

SSLProxyVerify Directive

Description: | Type of remote server Certificate verification
Syntax: | SSLProxyVerify level
Default: | SSLProxyVerify none
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive sets the Certificate verification level for the remote server Authentication. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the remote server authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotation with the reconfigured remote server verification level after the HTTP request was read but before the HTTP response is sent.

The following levels are available for level:

  • none: no remote server Certificate is required at all
  • optional: the remote server may present a valid Certificate
  • require: the remote server has to present a valid Certificate
  • optional_no_ca: the remote server may present a valid Certificate
    but it need not to be (successfully) verifiable.

In practice only levels none and require are really interesting, because level optional doesn't work with all servers and level optional_no_ca is actually against the idea of authentication (but can be used to establish SSL test pages, etc.)

Example

SSLProxyVerify require

SSLProxyVerifyDepth Directive

Description: | Maximum depth of CA Certificates in Remote Server Certificate verification
Syntax: | SSLProxyVerifyDepth number
Default: | SSLProxyVerifyDepth 1
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive sets how deeply mod_ssl should verify before deciding that the remote server does not have a valid certificate. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotation with the reconfigured remote server verification depth after the HTTP request was read but before the HTTP response is sent.

The depth actually is the maximum number of intermediate certificate issuers, i.e. the number of CA certificates which are max allowed to be followed while verifying the remote server certificate. A depth of 0 means that self-signed remote server certificates are accepted only, the default depth of 1 means the remote server certificate can be self-signed or has to be signed by a CA which is directly known to the server (i.e. the CA's certificate is under SSLProxyCACertificatePath), etc.

Example

SSLProxyVerifyDepth 10

SSLRandomSeed Directive

Description: | Pseudo Random Number Generator (PRNG) seeding source
Syntax: | SSLRandomSeed context source [bytes]
Context: | server config
Status: | Extension
Module: | mod_ssl

This configures one or more sources for seeding the Pseudo Random Number Generator (PRNG) in OpenSSL at startup time (context is startup) and/or just before a new SSL connection is established (context is connect). This directive can only be used in the global server context because the PRNG is a global facility.

The following source variants are available:

  • builtin

    This is the always available builtin seeding source. It's usage consumes minimum CPU cycles under runtime and hence can be always used without drawbacks. The source used for seeding the PRNG contains of the current time, the current process id and (when applicable) a randomly choosen 1KB extract of the inter-process scoreboard structure of Apache. The drawback is that this is not really a strong source and at startup time (where the scoreboard is still not available) this source just produces a few bytes of entropy. So you should always, at least for the startup, use an additional seeding source.

  • file:/path/to/source

    This variant uses an external file /path/to/source as the source for seeding the PRNG. When bytes is specified, only the first bytes number of bytes of the file form the entropy (and bytes is given to /path/to/source as the first argument). When bytes is not specified the whole file forms the entropy (and 0 is given to /path/to/source as the first argument). Use this especially at startup time, for instance with an available /dev/random and/or /dev/urandom devices (which usually exist on modern Unix derivates like FreeBSD and Linux).

    But be careful: Usually /dev/random provides only as much entropy data as it actually has, i.e. when you request 512 bytes of entropy, but the device currently has only 100 bytes available two things can happen: On some platforms you receive only the 100 bytes while on other platforms the read blocks until enough bytes are available (which can take a long time). Here using an existing /dev/urandom is better, because it never blocks and actually gives the amount of requested data. The drawback is just that the quality of the received data may not be the best.

    On some platforms like FreeBSD one can even control how the entropy is actually generated, i.e. by which system interrupts. More details one can find under rndcontrol(8) on those platforms. Alternatively, when your system lacks such a random device, you can use tool like EGD (Entropy Gathering Daemon) and run it's client program with the exec:/path/to/program/ variant (see below) or use egd:/path/to/egd-socket (see below).

  • exec:/path/to/program

    This variant uses an external executable /path/to/program as the source for seeding the PRNG. When bytes is specified, only the first bytes number of bytes of its stdout contents form the entropy. When bytes is not specified, the entirety of the data produced on stdout form the entropy. Use this only at startup time when you need a very strong seeding with the help of an external program (for instance as in the example above with the truerand utility you can find in the mod_ssl distribution which is based on the AT&T truerand library). Using this in the connection context slows down the server too dramatically, of course. So usually you should avoid using external programs in that context.

  • egd:/path/to/egd-socket (Unix only)

    This variant uses the Unix domain socket of the external Entropy Gathering Daemon (EGD) (see http://www.lothar.com/tech /crypto/) to seed the PRNG. Use this if no random device exists on your platform.

Example

SSLRandomSeed startup builtin
SSLRandomSeed startup file:/dev/random
SSLRandomSeed startup file:/dev/urandom 1024
SSLRandomSeed startup exec:/usr/local/bin/truerand 16
SSLRandomSeed connect builtin
SSLRandomSeed connect file:/dev/random
SSLRandomSeed connect file:/dev/urandom 1024

SSLRequire Directive

Description: | Allow access only when an arbitrarily complex boolean expression is true
Syntax: | SSLRequire expression
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive specifies a general access requirement which has to be fulfilled in order to allow access. It's a very powerful directive because the requirement specification is an arbitrarily complex boolean expression containing any number of access checks.

The expression must match the following syntax (given as a BNF grammar notation):

expr     ::= "true" | "false"
           | "!" expr
           | expr "&&" expr
           | expr "||" expr
           | "(" expr ")"
           | comp

comp     ::= word "==" word | word "eq" word
           | word "!=" word | word "ne" word
           | word "<"  word | word "lt" word
           | word "<=" word | word "le" word
           | word ">"  word | word "gt" word
           | word ">=" word | word "ge" word
           | word "in" "{" wordlist "}"
           | word "=~" regex
           | word "!~" regex

wordlist ::= word
           | wordlist "," word

word     ::= digit
           | cstring
           | variable
           | function

digit    ::= [0-9]+
cstring  ::= "..."
variable ::= "%{" varname "}"
function ::= funcname "(" funcargs ")"

while for varname any variable from Table 3 can be used. Finally for funcname the following functions are available:

  • file(filename)

    This function takes one string argument and expands to the contents of the file. This is especially useful for matching this contents against a regular expression, etc.

Notice that expression is first parsed into an internal machine representation and then evaluated in a second step. Actually, in Global and Per-Server Class context expression is parsed at startup time and at runtime only the machine representation is executed. For Per-Directory context this is different: here expression has to be parsed and immediately executed for every request.

Example

SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \
and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \
and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \
and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \
and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \
or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/

Standard CGI/1.0 and Apache variables:

HTTP_USER_AGENT        PATH_INFO             AUTH_TYPE
HTTP_REFERER           QUERY_STRING          SERVER_SOFTWARE
HTTP_COOKIE            REMOTE_HOST           API_VERSION
HTTP_FORWARDED         REMOTE_IDENT          TIME_YEAR
HTTP_HOST              IS_SUBREQ             TIME_MON
HTTP_PROXY_CONNECTION  DOCUMENT_ROOT         TIME_DAY
HTTP_ACCEPT            SERVER_ADMIN          TIME_HOUR
HTTP:headername        SERVER_NAME           TIME_MIN
THE_REQUEST            SERVER_PORT           TIME_SEC
REQUEST_METHOD         SERVER_PROTOCOL       TIME_WDAY
REQUEST_SCHEME         REMOTE_ADDR           TIME
REQUEST_URI            REMOTE_USER           ENV:variablename
REQUEST_FILENAME

SSL-related variables:

HTTPS                  SSL_CLIENT_M_VERSION   SSL_SERVER_M_VERSION
                       SSL_CLIENT_M_SERIAL    SSL_SERVER_M_SERIAL
SSL_PROTOCOL           SSL_CLIENT_V_START     SSL_SERVER_V_START
SSL_SESSION_ID         SSL_CLIENT_V_END       SSL_SERVER_V_END
SSL_CIPHER             SSL_CLIENT_S_DN        SSL_SERVER_S_DN
SSL_CIPHER_EXPORT      SSL_CLIENT_S_DN_C      SSL_SERVER_S_DN_C
SSL_CIPHER_ALGKEYSIZE  SSL_CLIENT_S_DN_ST     SSL_SERVER_S_DN_ST
SSL_CIPHER_USEKEYSIZE  SSL_CLIENT_S_DN_L      SSL_SERVER_S_DN_L
SSL_VERSION_LIBRARY    SSL_CLIENT_S_DN_O      SSL_SERVER_S_DN_O
SSL_VERSION_INTERFACE  SSL_CLIENT_S_DN_OU     SSL_SERVER_S_DN_OU
                       SSL_CLIENT_S_DN_CN     SSL_SERVER_S_DN_CN
                       SSL_CLIENT_S_DN_T      SSL_SERVER_S_DN_T
                       SSL_CLIENT_S_DN_I      SSL_SERVER_S_DN_I
                       SSL_CLIENT_S_DN_G      SSL_SERVER_S_DN_G
                       SSL_CLIENT_S_DN_S      SSL_SERVER_S_DN_S
                       SSL_CLIENT_S_DN_D      SSL_SERVER_S_DN_D
                       SSL_CLIENT_S_DN_UID    SSL_SERVER_S_DN_UID
                       SSL_CLIENT_S_DN_Email  SSL_SERVER_S_DN_Email
                       SSL_CLIENT_I_DN        SSL_SERVER_I_DN
                       SSL_CLIENT_I_DN_C      SSL_SERVER_I_DN_C
                       SSL_CLIENT_I_DN_ST     SSL_SERVER_I_DN_ST
                       SSL_CLIENT_I_DN_L      SSL_SERVER_I_DN_L
                       SSL_CLIENT_I_DN_O      SSL_SERVER_I_DN_O
                       SSL_CLIENT_I_DN_OU     SSL_SERVER_I_DN_OU
                       SSL_CLIENT_I_DN_CN     SSL_SERVER_I_DN_CN
                       SSL_CLIENT_I_DN_T      SSL_SERVER_I_DN_T
                       SSL_CLIENT_I_DN_I      SSL_SERVER_I_DN_I
                       SSL_CLIENT_I_DN_G      SSL_SERVER_I_DN_G
                       SSL_CLIENT_I_DN_S      SSL_SERVER_I_DN_S
                       SSL_CLIENT_I_DN_D      SSL_SERVER_I_DN_D
                       SSL_CLIENT_I_DN_UID    SSL_SERVER_I_DN_UID
                       SSL_CLIENT_I_DN_Email  SSL_SERVER_I_DN_Email
                       SSL_CLIENT_A_SIG       SSL_SERVER_A_SIG
                       SSL_CLIENT_A_KEY       SSL_SERVER_A_KEY
                       SSL_CLIENT_CERT        SSL_SERVER_CERT
                       SSL_CLIENT_CERT_CHAINn
                       SSL_CLIENT_VERIFY

SSLRequireSSL Directive

Description: | Deny access when SSL is not used for the HTTP request
Syntax: | SSLRequireSSL
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for the current connection. This is very handy inside the SSL-enabled virtual host or directories for defending against configuration errors that expose stuff that should be protected. When this directive is present all requests are denied which are not using SSL.

Example

SSLRequireSSL

SSLSessionCache Directive

Description: | Type of the global/inter-process SSL Session Cache
Syntax: | SSLSessionCache type
Default: | SSLSessionCache none
Context: | server config
Status: | Extension
Module: | mod_ssl

This configures the storage type of the global/inter-process SSL Session Cache. This cache is an optional facility which speeds up parallel request processing. For requests to the same server process (via HTTP keep-alive), OpenSSL already caches the SSL session information locally. But because modern clients request inlined images and other data via parallel requests (usually up to four parallel requests are common) those requests are served by different pre-forked server processes. Here an inter-process cache helps to avoid unneccessary session handshakes.

The following two storage types are currently supported:

  • none

    This is the default and just disables the global/inter-process Session Cache. There is no drawback in functionality, but a noticeable speed penalty can be observed.

  • dbm:/path/to/datafile

    This makes use of a DBM hashfile on the local disk to synchronize the local OpenSSL memory caches of the server processes. The slight increase in I/O on the server results in a visible request speedup for your clients, so this type of storage is generally recommended.

  • shm:/path/to/datafile[(size)]

    This makes use of a high-performance hash table (approx. size bytes in size) inside a shared memory segment in RAM (established via /path/to/datafile) to synchronize the local OpenSSL memory caches of the server processes. This storage type is not available on all platforms.

Examples

SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data
SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000)

SSLSessionCacheTimeout Directive

Description: | Number of seconds before an SSL session expires in the Session Cache
Syntax: | SSLSessionCacheTimeout seconds
Default: | SSLSessionCacheTimeout 300
Context: | server config, virtual host
Status: | Extension
Module: | mod_ssl

This directive sets the timeout in seconds for the information stored in the global/inter-process SSL Session Cache and the OpenSSL internal memory cache. It can be set as low as 15 for testing, but should be set to higher values like 300 in real life.

Example

SSLSessionCacheTimeout 600

SSLVerifyClient Directive

Description: | Type of Client Certificate verification
Syntax: | SSLVerifyClient level
Default: | SSLVerifyClient none
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive sets the Certificate verification level for the Client Authentication. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotation with the reconfigured client verification level after the HTTP request was read but before the HTTP response is sent.

The following levels are available for level:

  • none: no client Certificate is required at all
  • optional: the client may present a valid Certificate
  • require: the client has to present a valid Certificate
  • optional_no_ca: the client may present a valid Certificate
    but it need not to be (successfully) verifiable.

In practice only levels none and require are really interesting, because level optional doesn't work with all browsers and level optional_no_ca is actually against the idea of authentication (but can be used to establish SSL test pages, etc.)

Example

SSLVerifyClient require

SSLVerifyDepth Directive

Description: | Maximum depth of CA Certificates in Client Certificate verification
Syntax: | SSLVerifyDepth number
Default: | SSLVerifyDepth 1
Context: | server config, virtual host, directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_ssl

This directive sets how deeply mod_ssl should verify before deciding that the clients don't have a valid certificate. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotation with the reconfigured client verification depth after the HTTP request was read but before the HTTP response is sent.

The depth actually is the maximum number of intermediate certificate issuers, i.e. the number of CA certificates which are max allowed to be followed while verifying the client certificate. A depth of 0 means that self-signed client certificates are accepted only, the default depth of 1 means the client certificate can be self-signed or has to be signed by a CA which is directly known to the server (i.e. the CA's certificate is under SSLCACertificatePath), etc.

Example

SSLVerifyDepth 10


mod_status - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_status

Description: | Provides information on server activity and performance
Status: | Base
Module Identifier: | status_module
Source File: | mod_status.c

Summary

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.

The Status module allows a server administrator to find out how well their server is performing. A HTML page is presented that gives the current server statistics in an easily readable form. If required this page can be made to automatically refresh (given a compatible browser). Another page gives a simple machine-readable list of the current server state.

The details given are:

  • The number of children serving requests
  • The number of idle children
  • The status of each child, the number of requests that child has performed and the total number of bytes served by the child (*)
  • A total number of accesses and byte count served (*)
  • The time the server was started/restarted and the time it has been running for
  • Averages giving the number of requests per second, the number of bytes served per second and the average number of bytes per request (*)
  • The current percentage CPU used by each child and in total by Apache (*)
  • The current hosts and requests being processed (*)

A compile-time option must be used to display the details marked "(*)" as the instrumentation required for obtaining these statistics does not exist within standard Apache.

Enabling Status Support

To enable status reports only for browsers from the foo.com domain add this code to your httpd.conf configuration file

<Location /server-status>
SetHandler server-status

Order Deny,Allow
Deny from all
Allow from .foo.com
</Location>

You can now access server statistics by using a Web browser to access the page http://your.server.name/server-status

Note that mod_status will only work when you are running Apache in standalone mode and not inetd mode.

Automatic Updates

You can get the status page to update itself automatically if you have a browser that supports "refresh". Access the page http://your.server.name/server-status?refresh=N to refresh the page every N seconds.

Machine Readable Status File

A machine-readable version of the status file is available by accessing the page http://your.server.name/server-status?auto. This is useful when automatically run, see the Perl program in the /support directory of Apache, log_server_status.

It should be noted that if mod_status is compiled into the server, its handler capability is available in all configuration files, including per-directory files (e.g., .htaccess). This may have security-related ramifications for your site.

ExtendedStatus Directive

Description: | Keep track of extended status information for each request
Syntax: | ExtendedStatus On|Off
Default: | ExtendedStatus Off
Context: | server config
Status: | Base
Module: | mod_status
Compatibility: | ExtendedStatus is only available in Apache 1.3.2 and later.

This setting applies to the entire server, and cannot be enabled or disabled on a virtualhost-by-virtualhost basis. The collection of extended status information can slow down the server.


mod_suexec - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_suexec

Description: | Allows CGI scripts to run as a specified user and Group
Status: | Extension
Module Identifier: | suexec_module
Source File: | mod_suexec.c
Compatibility: | Available in Apache 2.0 and later

Summary

This module, in combination with the suexec support program allows CGI scripts to run as a specified user and Group.

See also

  • SuEXEC support

SuexecUserGroup Directive

Description: | User and group permissions for CGI programs
Syntax: | SuexecUserGroup User Group
Context: | server config, virtual host
Status: | Extension
Module: | mod_suexec
Compatibility: | SuexecUserGroup is only available in 2.0 and later.

The SuexecUserGroup directive allows you to specify a user and group for CGI programs to run as. Non-CGI requests are still processes with the user specified in the User directive. This directive replaces the Apache 1.3 configuration of using the User and Group directives inside of VirtualHosts.

Example

SuexecUserGroup nobody nogroup


mod_unique_id - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_unique_id

Description: | Provides an environment variable with a unique identifier for each request
Status: | Extension
Module Identifier: | unique_id_module
Source File: | mod_unique_id.c

Summary

This module provides a magic token for each request which is guaranteed to be unique across "all" requests under very specific conditions. The unique identifier is even unique across multiple machines in a properly configured cluster of machines. The environment variable UNIQUE_ID is set to the identifier for each request. Unique identifiers are useful for various reasons which are beyond the scope of this document.

Theory

First a brief recap of how the Apache server works on Unix machines. This feature currently isn't supported on Windows NT. On Unix machines, Apache creates several children, the children process requests one at a time. Each child can serve multiple requests in its lifetime. For the purpose of this discussion, the children don't share any data with each other. We'll refer to the children as httpd processes.

Your website has one or more machines under your administrative control, together we'll call them a cluster of machines. Each machine can possibly run multiple instances of Apache. All of these collectively are considered "the universe", and with certain assumptions we'll show that in this universe we can generate unique identifiers for each request, without extensive communication between machines in the cluster.

The machines in your cluster should satisfy these requirements. (Even if you have only one machine you should synchronize its clock with NTP.)

  • The machines' times are synchronized via NTP or other network time protocol.
  • The machines' hostnames all differ, such that the module can do a hostname lookup on the hostname and receive a different IP address for each machine in the cluster.

As far as operating system assumptions go, we assume that pids (process ids) fit in 32-bits. If the operating system uses more than 32-bits for a pid, the fix is trivial but must be performed in the code.

Given those assumptions, at a single point in time we can identify any httpd process on any machine in the cluster from all other httpd processes. The machine's IP address and the pid of the httpd process are sufficient to do this. So in order to generate unique identifiers for requests we need only distinguish between different points in time.

To distinguish time we will use a Unix timestamp (seconds since January 1, 1970 UTC), and a 16-bit counter. The timestamp has only one second granularity, so the counter is used to represent up to 65536 values during a single second. The quadruple ( ip_addr, pid, time_stamp, counter ) is sufficient to enumerate 65536 requests per second per httpd process. There are issues however with pid reuse over time, and the counter is used to alleviate this issue.

When an httpd child is created, the counter is initialized with ( current microseconds divided by 10 ) modulo 65536 (this formula was chosen to eliminate some variance problems with the low order bits of the microsecond timers on some systems). When a unique identifier is generated, the time stamp used is the time the request arrived at the web server. The counter is incremented every time an identifier is generated (and allowed to roll over).

The kernel generates a pid for each process as it forks the process, and pids are allowed to roll over (they're 16-bits on many Unixes, but newer systems have expanded to 32-bits). So over time the same pid will be reused. However unless it is reused within the same second, it does not destroy the uniqueness of our quadruple. That is, we assume the system does not spawn 65536 processes in a one second interval (it may even be 32768 processes on some Unixes, but even this isn't likely to happen).

Suppose that time repeats itself for some reason. That is, suppose that the system's clock is screwed up and it revisits a past time (or it is too far forward, is reset correctly, and then revisits the future time). In this case we can easily show that we can get pid and time stamp reuse. The choice of initializer for the counter is intended to help defeat this. Note that we really want a random number to initialize the counter, but there aren't any readily available numbers on most systems (i.e., you can't use rand() because you need to seed the generator, and can't seed it with the time because time, at least at one second resolution, has repeated itself). This is not a perfect defense.

How good a defense is it? Suppose that one of your machines serves at most 500 requests per second (which is a very reasonable upper bound at this writing, because systems generally do more than just shovel out static files). To do that it will require a number of children which depends on how many concurrent clients you have. But we'll be pessimistic and suppose that a single child is able to serve 500 requests per second. There are 1000 possible starting counter values such that two sequences of 500 requests overlap. So there is a 1.5% chance that if time (at one second resolution) repeats itself this child will repeat a counter value, and uniqueness will be broken. This was a very pessimistic example, and with real world values it's even less likely to occur. If your system is such that it's still likely to occur, then perhaps you should make the counter 32 bits (by editing the code).

You may be concerned about the clock being "set back" during summer daylight savings. However this isn't an issue because the times used here are UTC, which "always" go forward. Note that x86 based Unixes may need proper configuration for this to be true -- they should be configured to assume that the motherboard clock is on UTC and compensate appropriately. But even still, if you're running NTP then your UTC time will be correct very shortly after reboot.

The UNIQUE_ID environment variable is constructed by encoding the 112-bit (32-bit IP address, 32 bit pid, 32 bit time stamp, 16 bit counter) quadruple using the alphabet [A-Za-z0-9@-] in a manner similar to MIME base64 encoding, producing 19 characters. The MIME base64 alphabet is actually [A-Za-z0-9+/] however + and / need to be specially encoded in URLs, which makes them less desirable. All values are encoded in network byte ordering so that the encoding is comparable across architectures of different byte ordering. The actual ordering of the encoding is: time stamp, IP address, pid, counter. This ordering has a purpose, but it should be emphasized that applications should not dissect the encoding. Applications should treat the entire encoded UNIQUE_ID as an opaque token, which can be compared against other UNIQUE_IDs for equality only.

The ordering was chosen such that it's possible to change the encoding in the future without worrying about collision with an existing database of UNIQUE_IDs. The new encodings should also keep the time stamp as the first element, and can otherwise use the same alphabet and bit length. Since the time stamps are essentially an increasing sequence, it's sufficient to have a flag second in which all machines in the cluster stop serving and request, and stop using the old encoding format. Afterwards they can resume requests and begin issuing the new encodings.

This we believe is a relatively portable solution to this problem. It can be extended to multithreaded systems like Windows NT, and can grow with future needs. The identifiers generated have essentially an infinite life-time because future identifiers can be made longer as required. Essentially no communication is required between machines in the cluster (only NTP synchronization is required, which is low overhead), and no communication between httpd processes is required (the communication is implicit in the pid value assigned by the kernel). In very specific situations the identifier can be shortened, but more information needs to be assumed (for example the 32-bit IP address is overkill for any site, but there is no portable shorter replacement for it).


mod_userdir - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_userdir

Description: | User-specific directories
Status: | Base
Module Identifier: | userdir_module
Source File: | mod_userdir.c

Summary

This module allows user-specific directories to be accessed using the http://example.com/~user/ syntax.

See also

  • Mapping URLs to the Filesystem
  • public_html tutorial

UserDir Directive

Description: | Location of the user-specific directories
Syntax: | UserDir directory-filename
Default: | UserDir public_html
Context: | server config, virtual host
Status: | Base
Module: | mod_userdir

The UserDir directive sets the real directory in a user's home directory to use when a request for a document for a user is received. Directory-filename is one of the following:

  • The name of a directory or a pattern such as those shown below.
  • The keyword disabled. This turns off all username-to-directory translations except those explicitly named with the enabled keyword (see below).
  • The keyword disabled followed by a space-delimited list of usernames. Usernames that appear in such a list will never have directory translation performed, even if they appear in an enabled clause.
  • The keyword enabled followed by a space-delimited list of usernames. These usernames will have directory translation performed even if a global disable is in effect, but not if they also appear in a disabled clause.

If neither the enabled nor the disabled keywords appear in the Userdir directive, the argument is treated as a filename pattern, and is used to turn the name into a directory specification. A request for http://www.foo.com/~bob/one/two.html will be translated to:

UserDir directive used | Translated path
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

The following directives will send redirects to the client:

UserDir directive used | Translated path
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
Be careful when using this directive; for instance, "UserDir ./" would map "/~root" to "/" - which is probably undesirable. It is strongly recommended that your configuration include a "UserDir disabled root" declaration. See also the Directory directive and the Security Tips page for more information.

Additional examples:

To allow a few users to have UserDir directories, but not anyone else, use the following:

UserDir disabled
UserDir enabled user1 user2 user3

To allow most users to have UserDir directories, but deny this to a few, use the following:

UserDir enabled
UserDir disabled user4 user5 user6

It is also possible to specify alternative user directories. If you use a command like:

Userdir public_html /usr/web http://www.foo.com/

With a request for http://www.foo.com/~bob/one/two.html, will try to find the page at ~bob/public_html/one/two.html first, then /usr/web/bob/one/two.html, and finally it will send a redirect to http://www.foo.com/bob/one/two.html.

If you add a redirect, it must be the last alternative in the list. Apache cannot determine if the redirect succeeded or not, so if you have the redirect earlier in the list, that will always be the alternative that is used.

See also

  • public_html tutorial


mod_usertrack - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_usertrack

Description: | Clickstream logging of user activity on a site
Status: | Extension
Module 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, ".foo.com" is legal, but "foo.bar.com" and ".com" are not.

CookieExpires Directive

Description: | Expiry time for the tracking cookie
Syntax: | CookieExpires expiry-period
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

When used, this directive sets an expiry time on the cookie generated by the usertrack module. The expiry-period can be given either as a number of seconds, or in the format such as "2 weeks 3 days 7 hours". Valid denominations are: years, months, weeks, days, hours, minutes and seconds. If the expiry time is in any format other than one number indicating the number of seconds, it must be enclosed by double quotes.

If this directive is not used, cookies last only for the current browser session.

CookieName Directive

Description: | Name of the tracking cookie
Syntax: | CookieName token
Default: | CookieName Apache
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

This directive allows you to change the name of the cookie this module uses for its tracking purposes. By default the cookie is named "Apache".

You must specify a valid cookie name; results are unpredictable if you use a name containing unusual characters. Valid characters include A-Z, a-z, 0-9, "_", and "-".

CookieStyle Directive

Description: | Format of the cookie header field
Syntax: | CookieStyle Netscape|Cookie|Cookie2|RFC2109|RFC2965
Default: | CookieStyle Netscape
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

This directive controls the format of the cookie header field. The three formats allowed are:

  • Netscape, which is the original but now deprecated syntax. This is the default, and the syntax Apache has historically used.
  • Cookie or RFC2109, which is the syntax that superseded the Netscape syntax.
  • Cookie2 or RFC2965, which is the most current cookie syntax.

Not all clients can understand all of these formats. but you should use the newest one that is generally acceptable to your users' browsers.

CookieTracking Directive

Description: | Enables tracking cookie
Syntax: | CookieTracking on|off
Default: | CookieTracking off
Context: | server config, virtual host, directory, .htaccess
Override: | FileInfo
Status: | Extension
Module: | mod_usertrack

When the user track module is compiled in, and "CookieTracking on" is set, Apache will start sending a user-tracking cookie for all new requests. This directive can be used to turn this behavior on or off on a per-server or per-directory basis. By default, compiling mod_usertrack will not activate cookies.


mod_vhost_alias - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Modules

Apache Module mod_vhost_alias

Description: | Provides for dynamically configured mass virtual hosting
Status: | Extension
Module 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.


Developer Documentation for Apache 2.0 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Developer Documentation for Apache 2.0

Many of the documents on these Developer pages are lifted from Apache 1.3's documentation. While they are all being updated to Apache 2.0, they are in different stages of progress. Please be patient, and point out any discrepancies or errors on the developer/ pages directly to the dev@httpd.apache.org mailing list.

Topics

  • Apache 1.3 API Notes
  • Apache 2.0 Hook Functions
  • Request Processing in Apache 2.0
  • How filters work in Apache 2.0
  • Converting Modules from Apache 1.3 to Apache 2.0
  • Debugging Memory Allocation in APR
  • Documenting Apache 2.0
  • Apache 2.0 Thread Safety Issues

External Resources

  • Tools provided by Ian Holsman:
    • Apache 2 cross reference
    • Autogenerated Apache 2 code documentation
  • Module Development Tutorials by Kevin O'Donnell
    • Integrating a module into the Apache build system
    • Handling configuration directives
  • Some notes on Apache module development by Ryan Bloom


Apache 1.3 API notes - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Apache 1.3 API notes

Warning

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

These are some notes on the Apache API and the data structures you have to deal with, etc. They are not yet nearly complete, but hopefully, they will help you get your bearings. Keep in mind that the API is still subject to change as we gain experience with it. (See the TODO file for what might be coming). However, it will be easy to adapt modules to any changes that are made. (We have more modules to adapt than you do).

A few notes on general pedagogical style here. In the interest of conciseness, all structure declarations here are incomplete -- the real ones have more slots that I'm not telling you about. For the most part, these are reserved to one component of the server core or another, and should be altered by modules with caution. However, in some cases, they really are things I just haven't gotten around to yet. Welcome to the bleeding edge.

Finally, here's an outline, to give you some bare idea of what's coming up, and in what order:

  • Basic concepts.
    • Handlers, Modules, and Requests
    • A brief tour of a module
  • How handlers work
    • A brief tour of the request_rec
    • Where request_rec structures come from
    • Handling requests, declining, and returning error codes
    • Special considerations for response handlers
    • Special considerations for authentication handlers
    • Special considerations for logging handlers
  • Resource allocation and resource pools
  • Configuration, commands and the like
    • Per-directory configuration structures
    • Command handling
    • Side notes --- per-server configuration, virtual servers, etc.

Basic concepts

We begin with an overview of the basic concepts behind the API, and how they are manifested in the code.

Handlers, Modules, and Requests

Apache breaks down request handling into a series of steps, more or less the same way the Netscape server API does (although this API has a few more stages than NetSite does, as hooks for stuff I thought might be useful in the future). These are:

  • URI -> Filename translation
  • Auth ID checking [is the user who they say they are?]
  • Auth access checking [is the user authorized here?]
  • Access checking other than auth
  • Determining MIME type of the object requested
  • `Fixups' -- there aren't any of these yet, but the phase is intended as a hook for possible extensions like SetEnv, which don't really fit well elsewhere.
  • Actually sending a response back to the client.
  • Logging the request

These phases are handled by looking at each of a succession of modules, looking to see if each of them has a handler for the phase, and attempting invoking it if so. The handler can typically do one of three things:

  • Handle the request, and indicate that it has done so by returning the magic constant OK.
  • Decline to handle the request, by returning the magic integer constant DECLINED. In this case, the server behaves in all respects as if the handler simply hadn't been there.
  • Signal an error, by returning one of the HTTP error codes. This terminates normal handling of the request, although an ErrorDocument may be invoked to try to mop up, and it will be logged in any case.

Most phases are terminated by the first module that handles them; however, for logging, `fixups', and non-access authentication checking, all handlers always run (barring an error). Also, the response phase is unique in that modules may declare multiple handlers for it, via a dispatch table keyed on the MIME type of the requested object. Modules may declare a response-phase handler which can handle any request, by giving it the key */* (i.e., a wildcard MIME type specification). However, wildcard handlers are only invoked if the server has already tried and failed to find a more specific response handler for the MIME type of the requested object (either none existed, or they all declined).

The handlers themselves are functions of one argument (a request_rec structure. vide infra), which returns an integer, as above.

A brief tour of a module

At this point, we need to explain the structure of a module. Our candidate will be one of the messier ones, the CGI module -- this handles both CGI scripts and the ScriptAlias config file command. It's actually a great deal more complicated than most modules, but if we're going to have only one example, it might as well be the one with its fingers in every place.

Let's begin with handlers. In order to handle the CGI scripts, the module declares a response handler for them. Because of ScriptAlias, it also has handlers for the name translation phase (to recognize ScriptAliased URIs), the type-checking phase (any ScriptAliased request is typed as a CGI script).

The module needs to maintain some per (virtual) server information, namely, the ScriptAliases in effect; the module structure therefore contains pointers to a functions which builds these structures, and to another which combines two of them (in case the main server and a virtual server both have ScriptAliases declared).

Finally, this module contains code to handle the ScriptAlias command itself. This particular module only declares one command, but there could be more, so modules have command tables which declare their commands, and describe where they are permitted, and how they are to be invoked.

A final note on the declared types of the arguments of some of these commands: a pool is a pointer to a resource pool structure; these are used by the server to keep track of the memory which has been allocated, files opened, etc., either to service a particular request, or to handle the process of configuring itself. That way, when the request is over (or, for the configuration pool, when the server is restarting), the memory can be freed, and the files closed, en masse, without anyone having to write explicit code to track them all down and dispose of them. Also, a cmd_parms structure contains various information about the config file being read, and other status information, which is sometimes of use to the function which processes a config-file command (such as ScriptAlias). With no further ado, the module itself:

        /* Declarations of handlers. */

int translate_scriptalias (request_rec *);
int type_scriptalias (request_rec *);
int cgi_handler (request_rec *);

/* Subsidiary dispatch table for response-phase
* handlers, by MIME type */

handler_rec cgi_handlers[] = {
{ "application/x-httpd-cgi", cgi_handler },
{ NULL }
};

/* Declarations of routines to manipulate the
* module's configuration info.  Note that these are
* returned, and passed in, as void *'s; the server
* core keeps track of them, but it doesn't, and can't,
* know their internal structure.
*/

void *make_cgi_server_config (pool *);
void *merge_cgi_server_config (pool *, void *, void *);

/* Declarations of routines to handle config-file commands */

extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
                                  char *real);

command_rec cgi_cmds[] = {
{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,
"a fakename and a realname"},
{ NULL }
};

module cgi_module = {

  STANDARD_MODULE_STUFF,
  NULL,                     /* initializer */
  NULL,                     /* dir config creator */
  NULL,                     /* dir merger */
  make_cgi_server_config,   /* server config */
  merge_cgi_server_config,  /* merge server config */
  cgi_cmds,                 /* command table */
  cgi_handlers,             /* handlers */
  translate_scriptalias,    /* filename translation */
  NULL,                     /* check_user_id */
  NULL,                     /* check auth */
  NULL,                     /* check access */
  type_scriptalias,         /* type_checker */
  NULL,                     /* fixups */
  NULL,                     /* logger */
  NULL                      /* header parser */
};

How handlers work

The sole argument to handlers is a request_rec structure. This structure describes a particular request which has been made to the server, on behalf of a client. In most cases, each connection to the client generates only one request_rec structure.

A brief tour of the request_rec

The request_rec contains pointers to a resource pool which will be cleared when the server is finished handling the request; to structures containing per-server and per-connection information, and most importantly, information on the request itself.

The most important such information is a small set of character strings describing attributes of the object being requested, including its URI, filename, content-type and content-encoding (these being filled in by the translation and type-check handlers which handle the request, respectively).

Other commonly used data items are tables giving the MIME headers on the client's original request, MIME headers to be sent back with the response (which modules can add to at will), and environment variables for any subprocesses which are spawned off in the course of servicing the request. These tables are manipulated using the ap_table_get and ap_table_set routines.

Note that the Content-type header value cannot be set by module content-handlers using the ap_table_*() routines. Rather, it is set by pointing the content_type field in the request_rec structure to an appropriate string. e.g.,

r->content_type = "text/html";

Finally, there are pointers to two data structures which, in turn, point to per-module configuration structures. Specifically, these hold pointers to the data structures which the module has built to describe the way it has been configured to operate in a given directory (via .htaccess files or <Directory> sections), for private data it has built in the course of servicing the request (so modules' handlers for one phase can pass `notes' to their handlers for other phases). There is another such configuration vector in the server_rec data structure pointed to by the request_rec, which contains per (virtual) server configuration data.

Here is an abridged declaration, giving the fields most commonly used:

struct request_rec {

pool *pool;
conn_rec *connection;
server_rec *server;

/* What object is being requested */

char *uri;
char *filename;
char *path_info;

char *args;           /* QUERY_ARGS, if any */
struct stat finfo;    /* Set by server core;
                       * st_mode set to zero if no such file */

char *content_type;
char *content_encoding;

/* MIME header environments, in and out. Also,
 * an array containing environment variables to
 * be passed to subprocesses, so people can write
 * modules to add to that environment.
 *
 * The difference between headers_out and
 * err_headers_out is that the latter are printed
 * even on error, and persist across internal
 * redirects (so the headers printed for
 * ErrorDocument handlers will have them).
 */

table *headers_in;
table *headers_out;
table *err_headers_out;
table *subprocess_env;

/* Info about the request itself... */

int header_only;     /* HEAD request, as opposed to GET */
char *protocol;      /* Protocol, as given to us, or HTTP/0.9 */
char *method;        /* GET, HEAD, POST, etc. */
int method_number;   /* M_GET, M_POST, etc. */

/* Info for logging */

char *the_request;
int bytes_sent;

/* A flag which modules can set, to indicate that
 * the data being returned is volatile, and clients
 * should be told not to cache it.
 */

int no_cache;

/* Various other config info which may change
 * with .htaccess files
 * These are config vectors, with one void*
 * pointer for each module (the thing pointed
 * to being the module's business).
 */

void *per_dir_config;   /* Options set in config files, etc. */
void *request_config;   /* Notes on *this* request */

};

Where request_rec structures come from

Most request_rec structures are built by reading an HTTP request from a client, and filling in the fields. However, there are a few exceptions:

  • If the request is to an imagemap, a type map (i.e., a *.var file), or a CGI script which returned a local `Location:', then the resource which the user requested is going to be ultimately located by some URI other than what the client originally supplied. In this case, the server does an internal redirect, constructing a new request_rec for the new URI, and processing it almost exactly as if the client had requested the new URI directly.
  • If some handler signaled an error, and an ErrorDocument is in scope, the same internal redirect machinery comes into play.

  • Finally, a handler occasionally needs to investigate `what would happen if' some other request were run. For instance, the directory indexing module needs to know what MIME type would be assigned to a request for each directory entry, in order to figure out what icon to use.

    Such handlers can construct a sub-request, using the functions ap_sub_req_lookup_file, ap_sub_req_lookup_uri, and ap_sub_req_method_uri; these construct a new request_rec structure and processes it as you would expect, up to but not including the point of actually sending a response. (These functions skip over the access checks if the sub-request is for a file in the same directory as the original request).

    (Server-side includes work by building sub-requests and then actually invoking the response handler for them, via the function ap_run_sub_req).

Handling requests, declining, and returning error codes

As discussed above, each handler, when invoked to handle a particular request_rec, has to return an int to indicate what happened. That can either be

  • OK -- the request was handled successfully. This may or may not terminate the phase.
  • DECLINED -- no erroneous condition exists, but the module declines to handle the phase; the server tries to find another.
  • an HTTP error code, which aborts handling of the request.

Note that if the error code returned is REDIRECT, then the module should put a Location in the request's headers_out, to indicate where the client should be redirected to.

Special considerations for response handlers

Handlers for most phases do their work by simply setting a few fields in the request_rec structure (or, in the case of access checkers, simply by returning the correct error code). However, response handlers have to actually send a request back to the client.

They should begin by sending an HTTP response header, using the function ap_send_http_header. (You don't have to do anything special to skip sending the header for HTTP/0.9 requests; the function figures out on its own that it shouldn't do anything). If the request is marked header_only, that's all they should do; they should return after that, without attempting any further output.

Otherwise, they should produce a request body which responds to the client as appropriate. The primitives for this are ap_rputc and ap_rprintf, for internally generated output, and ap_send_fd, to copy the contents of some FILE * straight to the client.

At this point, you should more or less understand the following piece of code, which is the handler which handles GET requests which have no more specific handler; it also shows how conditional GETs can be handled, if it's desirable to do so in a particular response handler -- ap_set_last_modified checks against the If-modified-since value supplied by the client, if any, and returns an appropriate code (which will, if nonzero, be USE_LOCAL_COPY). No similar considerations apply for ap_set_content_length, but it returns an error code for symmetry.

        int default_handler (request_rec *r)
{
int errstatus;
FILE *f;

if (r->method_number != M_GET) return DECLINED;
if (r->finfo.st_mode == 0) return NOT_FOUND;

if ((errstatus = ap_set_content_length (r, r->finfo.st_size))
||
             (errstatus = ap_set_last_modified (r, r->finfo.st_mtime)))
return errstatus;

f = fopen (r->filename, "r");

if (f == NULL) {
log_reason("file permissions deny server access", r->filename, r);
return FORBIDDEN;
}

register_timeout ("send", r);
ap_send_http_header (r);

if (!r->header_only) send_fd (f, r);
ap_pfclose (r->pool, f);
return OK;
}

Finally, if all of this is too much of a challenge, there are a few ways out of it. First off, as shown above, a response handler which has not yet produced any output can simply return an error code, in which case the server will automatically produce an error response. Secondly, it can punt to some other handler by invoking ap_internal_redirect, which is how the internal redirection machinery discussed above is invoked. A response handler which has internally redirected should always return OK.

(Invoking ap_internal_redirect from handlers which are not response handlers will lead to serious confusion).

Special considerations for authentication handlers

Stuff that should be discussed here in detail:

  • Authentication-phase handlers not invoked unless auth is configured for the directory.
  • Common auth configuration stored in the core per-dir configuration; it has accessors ap_auth_type, ap_auth_name, and ap_requires.
  • Common routines, to handle the protocol end of things, at least for HTTP basic authentication (ap_get_basic_auth_pw, which sets the connection->user structure field automatically, and ap_note_basic_auth_failure, which arranges for the proper WWW-Authenticate: header to be sent back).

Special considerations for logging handlers

When a request has internally redirected, there is the question of what to log. Apache handles this by bundling the entire chain of redirects into a list of request_rec structures which are threaded through the r->prev and r->next pointers. The request_rec which is passed to the logging handlers in such cases is the one which was originally built for the initial request from the client; note that the bytes_sent field will only be correct in the last request in the chain (the one for which a response was actually sent).

Resource allocation and resource pools

One of the problems of writing and designing a server-pool server is that of preventing leakage, that is, allocating resources (memory, open files, etc.), without subsequently releasing them. The resource pool machinery is designed to make it easy to prevent this from happening, by allowing resource to be allocated in such a way that they are automatically released when the server is done with them.

The way this works is as follows: the memory which is allocated, file opened, etc., to deal with a particular request are tied to a resource pool which is allocated for the request. The pool is a data structure which itself tracks the resources in question.

When the request has been processed, the pool is cleared. At that point, all the memory associated with it is released for reuse, all files associated with it are closed, and any other clean-up functions which are associated with the pool are run. When this is over, we can be confident that all the resource tied to the pool have been released, and that none of them have leaked.

Server restarts, and allocation of memory and resources for per-server configuration, are handled in a similar way. There is a configuration pool, which keeps track of resources which were allocated while reading the server configuration files, and handling the commands therein (for instance, the memory that was allocated for per-server module configuration, log files and other files that were opened, and so forth). When the server restarts, and has to reread the configuration files, the configuration pool is cleared, and so the memory and file descriptors which were taken up by reading them the last time are made available for reuse.

It should be noted that use of the pool machinery isn't generally obligatory, except for situations like logging handlers, where you really need to register cleanups to make sure that the log file gets closed when the server restarts (this is most easily done by using the function ap_pfopen, which also arranges for the underlying file descriptor to be closed before any child processes, such as for CGI scripts, are execed), or in case you are using the timeout machinery (which isn't yet even documented here). However, there are two benefits to using it: resources allocated to a pool never leak (even if you allocate a scratch string, and just forget about it); also, for memory allocation, ap_palloc is generally faster than malloc.

We begin here by describing how memory is allocated to pools, and then discuss how other resources are tracked by the resource pool machinery.

Allocation of memory in pools

Memory is allocated to pools by calling the function ap_palloc, which takes two arguments, one being a pointer to a resource pool structure, and the other being the amount of memory to allocate (in chars). Within handlers for handling requests, the most common way of getting a resource pool structure is by looking at the pool slot of the relevant request_rec; hence the repeated appearance of the following idiom in module code:

int my_handler(request_rec *r)
{
struct my_structure *foo;
...

foo = (foo *)ap_palloc (r->pool, sizeof(my_structure));
 }

Note that there is no ap_pfree -- ap_palloced memory is freed only when the associated resource pool is cleared. This means that ap_palloc does not have to do as much accounting as malloc(); all it does in the typical case is to round up the size, bump a pointer, and do a range check.

(It also raises the possibility that heavy use of ap_palloc could cause a server process to grow excessively large. There are two ways to deal with this, which are dealt with below; briefly, you can use malloc, and try to be sure that all of the memory gets explicitly freed, or you can allocate a sub-pool of the main pool, allocate your memory in the sub-pool, and clear it out periodically. The latter technique is discussed in the section on sub-pools below, and is used in the directory-indexing code, in order to avoid excessive storage allocation when listing directories with thousands of files).

Allocating initialized memory

There are functions which allocate initialized memory, and are frequently useful. The function ap_pcalloc has the same interface as ap_palloc, but clears out the memory it allocates before it returns it. The function ap_pstrdup takes a resource pool and a char * as arguments, and allocates memory for a copy of the string the pointer points to, returning a pointer to the copy. Finally ap_pstrcat is a varargs-style function, which takes a pointer to a resource pool, and at least two char * arguments, the last of which must be NULL. It allocates enough memory to fit copies of each of the strings, as a unit; for instance:

ap_pstrcat (r->pool, "foo", "/", "bar", NULL);

returns a pointer to 8 bytes worth of memory, initialized to "foo/bar".

Commonly-used pools in the Apache Web server

A pool is really defined by its lifetime more than anything else. There are some static pools in http_main which are passed to various non-http_main functions as arguments at opportune times. Here they are:

permanent_pool
never passed to anything else, this is the ancestor of all pools
pconf
  • subpool of permanent_pool
  • created at the beginning of a config "cycle"; exists until the server is terminated or restarts; passed to all config-time routines, either via cmd->pool, or as the "pool *p" argument on those which don't take pools
  • passed to the module init() functions
ptemp
  • sorry I lie, this pool isn't called this currently in 1.3, I renamed it this in my pthreads development. I'm referring to the use of ptrans in the parent... contrast this with the later definition of ptrans in the child.
  • subpool of permanent_pool
  • created at the beginning of a config "cycle"; exists until the end of config parsing; passed to config-time routines via cmd->temp_pool. Somewhat of a "bastard child" because it isn't available everywhere. Used for temporary scratch space which may be needed by some config routines but which is deleted at the end of config.
pchild
  • subpool of permanent_pool
  • created when a child is spawned (or a thread is created); lives until that child (thread) is destroyed
  • passed to the module child_init functions
  • destruction happens right after the child_exit functions are called... (which may explain why I think child_exit is redundant and unneeded)
ptrans
  • should be a subpool of pchild, but currently is a subpool of permanent_pool, see above
  • cleared by the child before going into the accept() loop to receive a connection
  • used as connection->pool
r->pool
  • for the main request this is a subpool of connection->pool; for subrequests it is a subpool of the parent request's pool.
  • exists until the end of the request (i.e., ap_destroy_sub_req, or in child_main after process_request has finished)
  • note that r itself is allocated from r->pool; i.e., r->pool is first created and then r is the first thing palloc()d from it

For almost everything folks do, r->pool is the pool to use. But you can see how other lifetimes, such as pchild, are useful to some modules... such as modules that need to open a database connection once per child, and wish to clean it up when the child dies.

You can also see how some bugs have manifested themself, such as setting connection->user to a value from r->pool -- in this case connection exists for the lifetime of ptrans, which is longer than r->pool (especially if r->pool is a subrequest!). So the correct thing to do is to allocate from connection->pool.

And there was another interesting bug in mod_include / mod_cgi. You'll see in those that they do this test to decide if they should use r->pool or r->main->pool. In this case the resource that they are registering for cleanup is a child process. If it were registered in r->pool, then the code would wait() for the child when the subrequest finishes. With mod_include this could be any old #include, and the delay can be up to 3 seconds... and happened quite frequently. Instead the subprocess is registered in r->main->pool which causes it to be cleaned up when the entire request is done -- i.e., after the output has been sent to the client and logging has happened.

Tracking open files, etc.

As indicated above, resource pools are also used to track other sorts of resources besides memory. The most common are open files. The routine which is typically used for this is ap_pfopen, which takes a resource pool and two strings as arguments; the strings are the same as the typical arguments to fopen, e.g.,

...
FILE *f = ap_pfopen (r->pool, r->filename, "r");

if (f == NULL) { ... } else { ... }

There is also a ap_popenf routine, which parallels the lower-level open system call. Both of these routines arrange for the file to be closed when the resource pool in question is cleared.

Unlike the case for memory, there are functions to close files allocated with ap_pfopen, and ap_popenf, namely ap_pfclose and ap_pclosef. (This is because, on many systems, the number of files which a single process can have open is quite limited). It is important to use these functions to close files allocated with ap_pfopen and ap_popenf, since to do otherwise could cause fatal errors on systems such as Linux, which react badly if the same FILE* is closed more than once.

(Using the close functions is not mandatory, since the file will eventually be closed regardless, but you should consider it in cases where your module is opening, or could open, a lot of files).

Other sorts of resources -- cleanup functions

More text goes here. Describe the the cleanup primitives in terms of which the file stuff is implemented; also, spawn_process.

Pool cleanups live until clear_pool() is called: clear_pool(a) recursively calls destroy_pool() on all subpools of a; then calls all the cleanups for a; then releases all the memory for a. destroy_pool(a) calls clear_pool(a) and then releases the pool structure itself. i.e., clear_pool(a) doesn't delete a, it just frees up all the resources and you can start using it again immediately.

Fine control -- creating and dealing with sub-pools, with a note on sub-requests

On rare occasions, too-free use of ap_palloc() and the associated primitives may result in undesirably profligate resource allocation. You can deal with such a case by creating a sub-pool, allocating within the sub-pool rather than the main pool, and clearing or destroying the sub-pool, which releases the resources which were associated with it. (This really is a rare situation; the only case in which it comes up in the standard module set is in case of listing directories, and then only with very large directories. Unnecessary use of the primitives discussed here can hair up your code quite a bit, with very little gain).

The primitive for creating a sub-pool is ap_make_sub_pool, which takes another pool (the parent pool) as an argument. When the main pool is cleared, the sub-pool will be destroyed. The sub-pool may also be cleared or destroyed at any time, by calling the functions ap_clear_pool and ap_destroy_pool, respectively. (The difference is that ap_clear_pool frees resources associated with the pool, while ap_destroy_pool also deallocates the pool itself. In the former case, you can allocate new resources within the pool, and clear it again, and so forth; in the latter case, it is simply gone).

One final note -- sub-requests have their own resource pools, which are sub-pools of the resource pool for the main request. The polite way to reclaim the resources associated with a sub request which you have allocated (using the ap_sub_req_... functions) is ap_destroy_sub_req, which frees the resource pool. Before calling this function, be sure to copy anything that you care about which might be allocated in the sub-request's resource pool into someplace a little less volatile (for instance, the filename in its request_rec structure).

(Again, under most circumstances, you shouldn't feel obliged to call this function; only 2K of memory or so are allocated for a typical sub request, and it will be freed anyway when the main request pool is cleared. It is only when you are allocating many, many sub-requests for a single main request that you should seriously consider the ap_destroy_... functions).

Configuration, commands and the like

One of the design goals for this server was to maintain external compatibility with the NCSA 1.3 server --- that is, to read the same configuration files, to process all the directives therein correctly, and in general to be a drop-in replacement for NCSA. On the other hand, another design goal was to move as much of the server's functionality into modules which have as little as possible to do with the monolithic server core. The only way to reconcile these goals is to move the handling of most commands from the central server into the modules.

However, just giving the modules command tables is not enough to divorce them completely from the server core. The server has to remember the commands in order to act on them later. That involves maintaining data which is private to the modules, and which can be either per-server, or per-directory. Most things are per-directory, including in particular access control and authorization information, but also information on how to determine file types from suffixes, which can be modified by AddType and DefaultType directives, and so forth. In general, the governing philosophy is that anything which can be made configurable by directory should be; per-server information is generally used in the standard set of modules for information like Aliases and Redirects which come into play before the request is tied to a particular place in the underlying file system.

Another requirement for emulating the NCSA server is being able to handle the per-directory configuration files, generally called .htaccess files, though even in the NCSA server they can contain directives which have nothing at all to do with access control. Accordingly, after URI -> filename translation, but before performing any other phase, the server walks down the directory hierarchy of the underlying filesystem, following the translated pathname, to read any .htaccess files which might be present. The information which is read in then has to be merged with the applicable information from the server's own config files (either from the <Directory> sections in access.conf, or from defaults in srm.conf, which actually behaves for most purposes almost exactly like <Directory />).

Finally, after having served a request which involved reading .htaccess files, we need to discard the storage allocated for handling them. That is solved the same way it is solved wherever else similar problems come up, by tying those structures to the per-transaction resource pool.

Per-directory configuration structures

Let's look out how all of this plays out in mod_mime.c, which defines the file typing handler which emulates the NCSA server's behavior of determining file types from suffixes. What we'll be looking at, here, is the code which implements the AddType and AddEncoding commands. These commands can appear in .htaccess files, so they must be handled in the module's private per-directory data, which in fact, consists of two separate tables for MIME types and encoding information, and is declared as follows:

typedef struct {
    table *forced_types;      /* Additional AddTyped stuff */
    table *encoding_types;    /* Added with AddEncoding... */
} mime_dir_config;

When the server is reading a configuration file, or <Directory> section, which includes one of the MIME module's commands, it needs to create a mime_dir_config structure, so those commands have something to act on. It does this by invoking the function it finds in the module's `create per-dir config slot', with two arguments: the name of the directory to which this configuration information applies (or NULL for srm.conf), and a pointer to a resource pool in which the allocation should happen.

(If we are reading a .htaccess file, that resource pool is the per-request resource pool for the request; otherwise it is a resource pool which is used for configuration data, and cleared on restarts. Either way, it is important for the structure being created to vanish when the pool is cleared, by registering a cleanup on the pool if necessary).

For the MIME module, the per-dir config creation function just ap_pallocs the structure above, and a creates a couple of tables to fill it. That looks like this:

void *create_mime_dir_config (pool *p, char *dummy)
{
mime_dir_config *new =
(mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config));
new->forced_types = ap_make_table (p, 4);
new->encoding_types = ap_make_table (p, 4);

return new;
 }

Now, suppose we've just read in a .htaccess file. We already have the per-directory configuration structure for the next directory up in the hierarchy. If the .htaccess file we just read in didn't have any AddType or AddEncoding commands, its per-directory config structure for the MIME module is still valid, and we can just use it. Otherwise, we need to merge the two structures somehow.

To do that, the server invokes the module's per-directory config merge function, if one is present. That function takes three arguments: the two structures being merged, and a resource pool in which to allocate the result. For the MIME module, all that needs to be done is overlay the tables from the new per-directory config structure with those from the parent:

void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
{
mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
mime_dir_config *subdir = (mime_dir_config *)subdirv;
mime_dir_config *new =
(mime_dir_config *)ap_palloc (p, sizeof(mime_dir_config));
new->forced_types = ap_overlay_tables (p, subdir->forced_types,
parent_dir->forced_types);
 new->encoding_types = ap_overlay_tables (p, subdir->encoding_types,
parent_dir->encoding_types);
return new;
 }

As a note -- if there is no per-directory merge function present, the server will just use the subdirectory's configuration info, and ignore the parent's. For some modules, that works just fine (e.g., for the includes module, whose per-directory configuration information consists solely of the state of the XBITHACK), and for those modules, you can just not declare one, and leave the corresponding structure slot in the module itself NULL.

Command handling

Now that we have these structures, we need to be able to figure out how to fill them. That involves processing the actual AddType and AddEncoding commands. To find commands, the server looks in the module's command table. That table contains information on how many arguments the commands take, and in what formats, where it is permitted, and so forth. That information is sufficient to allow the server to invoke most command-handling functions with pre-parsed arguments. Without further ado, let's look at the AddType command handler, which looks like this (the AddEncoding command looks basically the same, and won't be shown here):

char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)
{
if (*ext == '.') ++ext;
ap_table_set (m->forced_types, ext, ct);
return NULL;
 }

This command handler is unusually simple. As you can see, it takes four arguments, two of which are pre-parsed arguments, the third being the per-directory configuration structure for the module in question, and the fourth being a pointer to a cmd_parms structure. That structure contains a bunch of arguments which are frequently of use to some, but not all, commands, including a resource pool (from which memory can be allocated, and to which cleanups should be tied), and the (virtual) server being configured, from which the module's per-server configuration data can be obtained if required.

Another way in which this particular command handler is unusually simple is that there are no error conditions which it can encounter. If there were, it could return an error message instead of NULL; this causes an error to be printed out on the server's stderr, followed by a quick exit, if it is in the main config files; for a .htaccess file, the syntax error is logged in the server error log (along with an indication of where it came from), and the request is bounced with a server error response (HTTP error status, code 500).

The MIME module's command table has entries for these commands, which look like this:

command_rec mime_cmds[] = {
{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2,
"a mime type followed by a file extension" },
 { "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,
"an encoding (e.g., gzip), followed by a file extension" },
 { NULL }
 };

The entries in these tables are:

  • The name of the command
  • The function which handles it
  • a (void *) pointer, which is passed in the cmd_parms structure to the command handler --- this is useful in case many similar commands are handled by the same function.
  • A bit mask indicating where the command may appear. There are mask bits corresponding to each AllowOverride option, and an additional mask bit, RSRC_CONF, indicating that the command may appear in the server's own config files, but not in any .htaccess file.
  • A flag indicating how many arguments the command handler wants pre-parsed, and how they should be passed in. TAKE2 indicates two pre-parsed arguments. Other options are TAKE1, which indicates one pre-parsed argument, FLAG, which indicates that the argument should be On or Off, and is passed in as a boolean flag, RAW_ARGS, which causes the server to give the command the raw, unparsed arguments (everything but the command name itself). There is also ITERATE, which means that the handler looks the same as TAKE1, but that if multiple arguments are present, it should be called multiple times, and finally ITERATE2, which indicates that the command handler looks like a TAKE2, but if more arguments are present, then it should be called multiple times, holding the first argument constant.
  • Finally, we have a string which describes the arguments that should be present. If the arguments in the actual config file are not as required, this string will be used to help give a more specific error message. (You can safely leave this NULL).

Finally, having set this all up, we have to use it. This is ultimately done in the module's handlers, specifically for its file-typing handler, which looks more or less like this; note that the per-directory configuration structure is extracted from the request_rec's per-directory configuration vector by using the ap_get_module_config function.

        int find_ct(request_rec *r)
{
int i;
char *fn = ap_pstrdup (r->pool, r->filename);
mime_dir_config *conf = (mime_dir_config *)
ap_get_module_config(r->per_dir_config, &mime_module);
char *type;

if (S_ISDIR(r->finfo.st_mode)) {
r->content_type = DIR_MAGIC_TYPE;
return OK;
}

if((i=ap_rind(fn,'.')) < 0) return DECLINED;
++i;

if ((type = ap_table_get (conf->encoding_types, &fn[i])))
{
r->content_encoding = type;

/* go back to previous extension to try to use it as a type */
fn[i-1] = '\0';
if((i=ap_rind(fn,'.')) < 0) return OK;
++i;
}

if ((type = ap_table_get (conf->forced_types, &fn[i])))
{
r->content_type = type;
}

return OK;

        }

Side notes -- per-server configuration, virtual servers, etc.

The basic ideas behind per-server module configuration are basically the same as those for per-directory configuration; there is a creation function and a merge function, the latter being invoked where a virtual server has partially overridden the base server configuration, and a combined structure must be computed. (As with per-directory configuration, the default if no merge function is specified, and a module is configured in some virtual server, is that the base configuration is simply ignored).

The only substantial difference is that when a command needs to configure the per-server private module data, it needs to go to the cmd_parms data to get at it. Here's an example, from the alias module, which also indicates how a syntax error can be returned (note that the per-directory configuration argument to the command handler is declared as a dummy, since the module doesn't actually have per-directory config data):

char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
{
server_rec *s = cmd->server;
alias_server_conf *conf = (alias_server_conf *)
ap_get_module_config(s->module_config,&alias_module);
 alias_entry *new = ap_push_array (conf->redirects);

if (!ap_is_url (url)) return "Redirect to non-URL";

new->fake = f; new->real = url;
return NULL;
 }


Debugging Memory Allocation in APR - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Debugging Memory Allocation in APR

The allocation mechanism's within APR have a number of debugging modes that can be used to assist in finding memory problems. This document describes the modes available and gives instructions on activating them.

Available debugging options

Allocation Debugging - ALLOC_DEBUG

Debugging support: Define this to enable code which helps detect re-use of free()d memory and other such nonsense.

The theory is simple. The FILL_BYTE (0xa5) is written over all malloc'd memory as we receive it, and is written over everything that we free up during a clear_pool. We check that blocks on the free list always have the FILL_BYTE in them, and we check during palloc() that the bytes still have FILL_BYTE in them. If you ever see garbage URLs or whatnot containing lots of 0xa5s then you know something used data that's been freed or uninitialized.

Malloc Support - ALLOC_USE_MALLOC

If defined all allocations will be done with malloc() and free()d appropriately at the end.

This is intended to be used with something like Electric Fence or Purify to help detect memory problems. Note that if you're using efence then you should also add in ALLOC_DEBUG. But don't add in ALLOC_DEBUG if you're using Purify because ALLOC_DEBUG would hide all the uninitialized read errors that Purify can diagnose.

Pool Debugging - POOL_DEBUG

This is intended to detect cases where the wrong pool is used when assigning data to an object in another pool.

In particular, it causes the table_{set,add,merge}n routines to check that their arguments are safe for the apr_table_t they're being placed in. It currently only works with the unix multiprocess model, but could be extended to others.

Table Debugging - MAKE_TABLE_PROFILE

Provide diagnostic information about make_table() calls which are possibly too small.

This requires a recent gcc which supports __builtin_return_address(). The error_log output will be a message such as:

table_push: apr_table_t created by 0x804d874 hit limit of 10

Use l *0x804d874 to find the source that corresponds to. It indicates that a apr_table_t allocated by a call at that address has possibly too small an initial apr_table_t size guess.

Allocation Statistics - ALLOC_STATS

Provide some statistics on the cost of allocations.

This requires a bit of an understanding of how alloc.c works.

Allowable Combinations

Not all the options outlined above can be activated at the same time. the following table gives more information.

 | ALLOC DEBUG | ALLOC USE MALLOC | POOL DEBUG | MAKE TABLE PROFILE | ALLOC STATS
ALLOC DEBUG | - | No | Yes | Yes | Yes
ALLOC USE MALLOC | No | - | No | No | No
POOL DEBUG | Yes | No | - | Yes | Yes
MAKE TABLE PROFILE | Yes | No | Yes | - | Yes
ALLOC STATS | Yes | No | Yes | Yes | -

Additionally the debugging options are not suitable for multi-threaded versions of the server. When trying to debug with these options the server should be started in single process mode.

Activating Debugging Options

The various options for debugging memory are now enabled in the apr_general.h header file in APR. The various options are enabled by uncommenting the define for the option you wish to use. The section of the code currently looks like this (contained in srclib/apr/include/apr_pools.h)

/*
#define ALLOC_DEBUG
#define POOL_DEBUG
#define ALLOC_USE_MALLOC
#define MAKE_TABLE_PROFILE
#define ALLOC_STATS
*/

typedef struct ap_pool_t {
union block_hdr *first;
union block_hdr *last;
struct cleanup *cleanups;
struct process_chain *subprocesses;
struct ap_pool_t *sub_pools;
struct ap_pool_t *sub_next;
struct ap_pool_t *sub_prev;
struct ap_pool_t *parent;
char *free_first_avail;
 #ifdef ALLOC_USE_MALLOC
void *allocation_list;
 #endif
#ifdef POOL_DEBUG
struct ap_pool_t *joined;
 #endif
int (*apr_abort)(int retcode);
struct datastruct *prog_data;
 } ap_pool_t;

To enable allocation debugging simply move the #define ALLOC_DEBUG above the start of the comments block and rebuild the server.

Note

In order to use the various options the server must be rebuilt after editing the header file.


Documenting Apache 2.0 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Documenting Apache 2.0

Apache 2.0 uses Doxygen to document the APIs and global variables in the the code. This will explain the basics of how to document using Doxygen.

Brief Description

To start a documentation block, use /**
To end a documentation block, use */

In the middle of the block, there are multiple tags we can use:

Description of this functions purpose
@param parameter_name description
@return description
@deffunc signature of the function

The deffunc is not always necessary. DoxyGen does not have a full parser in it, so any prototype that use a macro in the return type declaration is too complex for scandoc. Those functions require a deffunc. An example (using &gt; rather than >):

/**
 * return the final element of the pathname
 * @param pathname The path to get the final element of
 * @return the final element of the path
 * @tip Examples:
 * <pre>
 * "/foo/bar/gum" -&gt; "gum"
 * "/foo/bar/gum/" -&gt; ""
 * "gum" -&gt; "gum"
 * "wi\\n32\\stuff" -&gt; "stuff"
 * </pre>
 * @deffunc const char * ap_filename_of_pathname(const char *pathname)
 */

At the top of the header file, always include:

/**
 * @package Name of library header
 */

Doxygen uses a new HTML file for each package. The HTML files are named {Name_of_library_header}.html, so try to be concise with your names.

For a further discussion of the possibilities please refer to the Doxygen site.


Apache 2.0 Hook Functions - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Apache 2.0 Hook Functions

Warning

This document is still in development and may be partially out of date.

In general, a hook function is one that Apache will call at some point during the processing of a request. Modules can provide functions that are called, and specify when they get called in comparison to other modules.

Creating a hook function

In order to create a new hook, four things need to be done:

Declare the hook function

Use the AP_DECLARE_HOOK macro, which needs to be given the return type of the hook function, the name of the hook, and the arguments. For example, if the hook returns an int and takes a request_rec * and an int and is called do_something, then declare it like this:

AP_DECLARE_HOOK(int, do_something, (request_rec *r, int n))

This should go in a header which modules will include if they want to use the hook.

Create the hook structure

Each source file that exports a hook has a private structure which is used to record the module functions that use the hook. This is declared as follows:

APR_HOOK_STRUCT(
APR_HOOK_LINK(do_something)
...
 )

Implement the hook caller

The source file that exports the hook has to implement a function that will call the hook. There are currently three possible ways to do this. In all cases, the calling function is called ap_run_hookname().

Void hooks

If the return value of a hook is void, then all the hooks are called, and the caller is implemented like this:

AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n), (r, n))

The second and third arguments are the dummy argument declaration and the dummy arguments as they will be used when calling the hook. In other words, this macro expands to something like this:

void ap_run_do_something(request_rec *r, int n)
{
...
do_something(r, n);
 }

Hooks that return a value

If the hook returns a value, then it can either be run until the first hook that does something interesting, like so:

AP_IMPLEMENT_HOOK_RUN_FIRST(int, do_something, (request_rec *r, int n), (r, n), DECLINED)

The first hook that does not return DECLINED stops the loop and its return value is returned from the hook caller. Note that DECLINED is the tradition Apache hook return meaning "I didn't do anything", but it can be whatever suits you.

Alternatively, all hooks can be run until an error occurs. This boils down to permitting two return values, one of which means "I did something, and it was OK" and the other meaning "I did nothing". The first function that returns a value other than one of those two stops the loop, and its return is the return value. Declare these like so:

AP_IMPLEMENT_HOOK_RUN_ALL(int, do_something, (request_rec *r, int n), (r, n), OK, DECLINED)

Again, OK and DECLINED are the traditional values. You can use what you want.

Call the hook callers

At appropriate moments in the code, call the hook caller, like so:

int n, ret;
request_rec *r;

ret=ap_run_do_something(r, n);

Hooking the hook

A module that wants a hook to be called needs to do two things.

Implement the hook function

Include the appropriate header, and define a static function of the correct type:

static int my_something_doer(request_rec *r, int n)
{
...
return OK;
 }

Add a hook registering function

During initialisation, Apache will call each modules hook registering function, which is included in the module structure:

static void my_register_hooks()
{
ap_hook_do_something(my_something_doer, NULL, NULL, HOOK_MIDDLE);
 }

mode MODULE_VAR_EXPORT my_module =
{
...
my_register_hooks /* register hooks */
 };

Controlling hook calling order

In the example above, we didn't use the three arguments in the hook registration function that control calling order. There are two mechanisms for doing this. The first, rather crude, method, allows us to specify roughly where the hook is run relative to other modules. The final argument control this. There are three possible values: HOOK_FIRST, HOOK_MIDDLE and HOOK_LAST.

All modules using any particular value may be run in any order relative to each other, but, of course, all modules using HOOK_FIRST will be run before HOOK_MIDDLE which are before HOOK_LAST. Modules that don't care when they are run should use HOOK_MIDDLE. (I spaced these out so people could do stuff like HOOK_FIRST-2 to get in slightly earlier, but is this wise? - Ben)

Note that there are two more values, HOOK_REALLY_FIRST and HOOK_REALLY_LAST. These should only be used by the hook exporter.

The other method allows finer control. When a module knows that it must be run before (or after) some other modules, it can specify them by name. The second (third) argument is a NULL-terminated array of strings consisting of the names of modules that must be run before (after) the current module. For example, suppose we want "mod_xyz.c" and "mod_abc.c" to run before we do, then we'd hook as follows:

static void register_hooks()
{
static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL };

ap_hook_do_something(my_something_doer, aszPre, NULL, HOOK_MIDDLE);
 }

Note that the sort used to achieve this is stable, so ordering set by HOOK_ORDER is preserved, as far as is possible.

Ben Laurie, 15th August 1999


Converting Modules from Apache 1.3 to Apache 2.0 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Converting Modules from Apache 1.3 to Apache 2.0

This is a first attempt at writing the lessons I learned when trying to convert the mod_mmap_static module to Apache 2.0. It's by no means definitive and probably won't even be correct in some ways, but it's a start.

The easier changes ...

Cleanup Routines

These now need to be of type apr_status_t and return a value of that type. Normally the return value will be APR_SUCCESS unless there is some need to signal an error in the cleanup. Be aware that even though you signal an error not all code yet checks and acts upon the error.

Initialisation Routines

These should now be renamed to better signify where they sit in the overall process. So the name gets a small change from mmap_init to mmap_post_config. The arguments passed have undergone a radical change and now look like

  • apr_pool_t *p
  • apr_pool_t *plog
  • apr_pool_t *ptemp
  • server_rec *s

Data Types

A lot of the data types have been moved into the APR. This means that some have had a name change, such as the one shown above. The following is a brief list of some of the changes that you are likely to have to make.

  • pool becomes apr_pool_t
  • table becomes apr_table_t

The messier changes...

Register Hooks

The new architecture uses a series of hooks to provide for calling your functions. These you'll need to add to your module by way of a new function, static void register_hooks(void). The function is really reasonably straightforward once you understand what needs to be done. Each function that needs calling at some stage in the processing of a request needs to be registered, handlers do not. There are a number of phases where functions can be added, and for each you can specify with a high degree of control the relative order that the function will be called in.

This is the code that was added to 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);
};

This registers 2 functions that need to be called, one in the post_config stage (virtually every module will need this one) and one for the translate_name phase. note that while there are different function names the format of each is identical. So what is the format?

ap_hook_phase_name(function_name, predecessors, successors, position);

There are 3 hook positions defined...

  • HOOK_FIRST
  • HOOK_MIDDLE
  • HOOK_LAST

To define the position you use the position and then modify it with the predecessors and successors. Each of the modifiers can be a list of functions that should be called, either before the function is run (predecessors) or after the function has run (successors).

In the mod_mmap_static case I didn't care about the post_config stage, but the mmap_static_xlat must be called after the core module had done it's name translation, hence the use of the aszPre to define a modifier to the position HOOK_LAST.

Module Definition

There are now a lot fewer stages to worry about when creating your module definition. The old defintion looked like

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 */
};

The new structure is a great deal simpler...

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 */
};

Some of these read directly across, some don't. I'll try to summarise what should be done below.

The stages that read directly across :

/* dir config creater */
/* create per-directory config structures */
/* server config */
/* create per-server config structures */
/* dir merger */
/* merge per-directory config structures */
/* merge server config */
/* merge per-server config structures */
/* command table */
/* command apr_table_t */
/* handlers */
/* handlers */

The remainder of the old functions should be registered as hooks. There are the following hook stages defined so far...

ap_hook_post_config
this is where the old _init routines get registered
ap_hook_http_method
retrieve the http method from a request. (legacy)
ap_hook_open_logs
open any specified logs
ap_hook_auth_checker
check if the resource requires authorization
ap_hook_access_checker
check for module-specific restrictions
ap_hook_check_user_id
check the user-id and password
ap_hook_default_port
retrieve the default port for the server
ap_hook_pre_connection
do any setup required just before processing, but after accepting
ap_hook_process_connection
run the correct protocol
ap_hook_child_init
call as soon as the child is started
ap_hook_create_request
??
ap_hook_fixups
last chance to modify things before generating content
ap_hook_handler
generate the content
ap_hook_header_parser
lets modules look at the headers, not used by most modules, because they use post_read_request for this
ap_hook_insert_filter
to insert filters into the filter chain
ap_hook_log_transaction
log information about the request
ap_hook_optional_fn_retrieve
retrieve any functions registered as optional
ap_hook_post_read_request
called after reading the request, before any other phase
ap_hook_quick_handler
called before any request processing, used by cache modules.
ap_hook_translate_name
translate the URI into a filename
ap_hook_type_checker
determine and/or set the doc type


Request Processing in Apache 2.0 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Request Processing in Apache 2.0

Warning

Warning - this is a first (fast) draft that needs further revision!

Several changes in Apache 2.0 affect the internal request processing mechanics. Module authors need to be aware of these changes so they may take advantage of the optimizations and security enhancements.

The first major change is to the subrequest and redirect mechanisms. There were a number of different code paths in Apache 1.3 to attempt to optimize subrequest or redirect behavior. As patches were introduced to 2.0, these optimizations (and the server behavior) were quickly broken due to this duplication of code. All duplicate code has been folded back into ap_process_internal_request() to prevent the code from falling out of sync again.

This means that much of the existing code was 'unoptimized'. It is the Apache HTTP Project's first goal to create a robust and correct implementation of the HTTP server RFC. Additional goals include security, scalability and optimization. New methods were sought to optimize the server (beyond the performance of Apache 1.3) without introducing fragile or insecure code.

The Request Processing Cycle

All requests pass through ap_process_request_internal() in request.c, including subrequests and redirects. If a module doesn't pass generated requests through this code, the author is cautioned that the module may be broken by future changes to request processing.

To streamline requests, the module author can take advantage of the hooks offered to drop out of the request cycle early, or to bypass core Apache hooks which are irrelevant (and costly in terms of CPU.)

The Request Parsing Phase

Unescapes the URL

The request's parsed_uri path is unescaped, once and only once, at the beginning of internal request processing.

This step is bypassed if the proxyreq flag is set, or the parsed_uri.path element is unset. The module has no further control of this one-time unescape operation, either failing to unescape or multiply unescaping the URL leads to security reprecussions.

Strips Parent and This Elements from the URI

All /../ and /./ elements are removed by ap_getparents(). This helps to ensure the path is (nearly) absolute before the request processing continues.

This step cannot be bypassed.

Initial URI Location Walk

Every request is subject to an ap_location_walk() call. This ensures that <Location> sections are consistently enforced for all requests. If the request is an internal redirect or a sub-request, it may borrow some or all of the processing from the previous or parent request's ap_location_walk, so this step is generally very efficient after processing the main request.

translate_name

Modules can determine the file name, or alter the given URI in this step. For example, mod_vhost_alias will translate the URI's path into the configured virtual host, mod_alias will translate the path to an alias path, and if the request falls back on the core, the DocumentRoot is prepended to the request resource.

If all modules DECLINE this phase, an error 500 is returned to the browser, and a "couldn't translate name" error is logged automatically.

Hook: map_to_storage

After the file or correct URI was determined, the appropriate per-dir configurations are merged together. For example, mod_proxy compares and merges the appropriate <Proxy> sections. If the URI is nothing more than a local (non-proxy) TRACE request, the core handles the request and returns DONE. If no module answers this hook with OK or DONE, the core will run the request filename against the <Directory> and <Files> sections. If the request 'filename' isn't an absolute, legal filename, a note is set for later termination.

URI Location Walk

Every request is hardened by a second ap_location_walk() call. This reassures that a translated request is still subjected to the configured <Location> sections. The request again borrows some or all of the processing from its previous location_walk above, so this step is almost always very efficient unless the translated URI mapped to a substantially different path or Virtual Host.

Hook: header_parser

The main request then parses the client's headers. This prepares the remaining request processing steps to better serve the client's request.

The Security Phase

Needs Documentation. Code is:

switch (ap_satisfies(r)) {
case SATISFY_ALL:
case SATISFY_NOSPEC:
    if ((access_status = ap_run_access_checker(r)) != 0) {
        return decl_die(access_status, "check access", r);
    }

    if (ap_some_auth_required(r)) {
        if (((access_status = ap_run_check_user_id(r)) != 0)
            || !ap_auth_type(r)) {
            return decl_die(access_status, ap_auth_type(r)
                          ? "check user.  No user file?"
                          : "perform authentication. AuthType not set!",
                          r);
        }

        if (((access_status = ap_run_auth_checker(r)) != 0)
            || !ap_auth_type(r)) {
            return decl_die(access_status, ap_auth_type(r)
                          ? "check access.  No groups file?"
                          : "perform authentication. AuthType not set!",
                          r);
        }
    }
    break;

case SATISFY_ANY:
    if (((access_status = ap_run_access_checker(r)) != 0)) {
        if (!ap_some_auth_required(r)) {
            return decl_die(access_status, "check access", r);
        }

        if (((access_status = ap_run_check_user_id(r)) != 0)
            || !ap_auth_type(r)) {
            return decl_die(access_status, ap_auth_type(r)
                          ? "check user.  No user file?"
                          : "perform authentication. AuthType not set!",
                          r);
        }

        if (((access_status = ap_run_auth_checker(r)) != 0)
            || !ap_auth_type(r)) {
            return decl_die(access_status, ap_auth_type(r)
                          ? "check access.  No groups file?"
                          : "perform authentication. AuthType not set!",
                          r);
        }
    }
    break;
}

The Preparation Phase

Hook: type_checker

The modules have an opportunity to test the URI or filename against the target resource, and set mime information for the request. Both mod_mime and mod_mime_magic use this phase to compare the file name or contents against the administrator's configuration and set the content type, language, character set and request handler. Some modules may set up their filters or other request handling parameters at this time.

If all modules DECLINE this phase, an error 500 is returned to the browser, and a "couldn't find types" error is logged automatically.

Hook: fixups

Many modules are 'trounced' by some phase above. The fixups phase is used by modules to 'reassert' their ownership or force the request's fields to their appropriate values. It isn't always the cleanest mechanism, but occasionally it's the only option.

The Handler Phase

This phase is not part of the processing in ap_process_request_internal(). Many modules prepare one or more subrequests prior to creating any content at all. After the core, or a module calls ap_process_request_internal() it then calls ap_invoke_handler() to generate the request.

Hook: insert_filter

Modules that transform the content in some way can insert their values and override existing filters, such that if the user configured a more advanced filter out-of-order, then the module can move its order as need be. There is no result code, so actions in this hook better be trusted to always succeed.

Hook: handler

The module finally has a chance to serve the request in its handler hook. Note that not every prepared request is sent to the handler hook. Many modules, such as mod_autoindex, will create subrequests for a given URI, and then never serve the subrequest, but simply lists it for the user. Remember not to put required teardown from the hooks above into this module, but register pool cleanups against the request pool to free resources as required.


How filters work in Apache 2.0 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

How filters work in Apache 2.0

Warning

This is a cut 'n paste job from an email (<022501c1c529$f63a9550$7f00000a@KOJ>) and only reformatted for better readability. It's not up to date but may be a good start for further research.

Filter Types

There are three basic filter types (each of these is actually broken down into two categories, but that comes later).

CONNECTION
Filters of this type are valid for the lifetime of this connection. (AP_FTYPE_CONNECTION, AP_FTYPE_NETWORK)
PROTOCOL
Filters of this type are valid for the lifetime of this request from the point of view of the client, this means that the request is valid from the time that the request is sent until the time that the response is received. (AP_FTYPE_PROTOCOL, AP_FTYPE_TRANSCODE)
RESOURCE
Filters of this type are valid for the time that this content is used to satisfy a request. For simple requests, this is identical to PROTOCOL, but internal redirects and sub-requests can change the content without ending the request. (AP_FTYPE_RESOURCE, AP_FTYPE_CONTENT_SET)

It is important to make the distinction between a protocol and a resource filter. A resource filter is tied to a specific resource, it may also be tied to header information, but the main binding is to a resource. If you are writing a filter and you want to know if it is resource or protocol, the correct question to ask is: "Can this filter be removed if the request is redirected to a different resource?" If the answer is yes, then it is a resource filter. If it is no, then it is most likely a protocol or connection filter. I won't go into connection filters, because they seem to be well understood. With this definition, a few examples might help:

Byterange
We have coded it to be inserted for all requests, and it is removed if not used. Because this filter is active at the beginning of all requests, it can not be removed if it is redirected, so this is a protocol filter.
http_header
This filter actually writes the headers to the network. This is obviously a required filter (except in the asis case which is special and will be dealt with below) and so it is a protocol filter.
Deflate
The administrator configures this filter based on which file has been requested. If we do an internal redirect from an autoindex page to an index.html page, the deflate filter may be added or removed based on config, so this is a resource filter.

The further breakdown of each category into two more filter types is strictly for ordering. We could remove it, and only allow for one filter type, but the order would tend to be wrong, and we would need to hack things to make it work. Currently, the RESOURCE filters only have one filter type, but that should change.

How are filters inserted?

This is actually rather simple in theory, but the code is complex. First of all, it is important that everybody realize that there are three filter lists for each request, but they are all concatenated together. So, the first list is r->output_filters, then r->proto_output_filters, and finally r->connection->output_filters. These correspond to the RESOURCE, PROTOCOL, and CONNECTION filters respectively. The problem previously, was that we used a singly linked list to create the filter stack, and we started from the "correct" location. This means that if I had a RESOURCE filter on the stack, and I added a CONNECTION filter, the CONNECTION filter would be ignored. This should make sense, because we would insert the connection filter at the top of the c->output_filters list, but the end of r->output_filters pointed to the filter that used to be at the front of c->output_filters. This is obviously wrong. The new insertion code uses a doubly linked list. This has the advantage that we never lose a filter that has been inserted. Unfortunately, it comes with a separate set of headaches.

The problem is that we have two different cases were we use subrequests. The first is to insert more data into a response. The second is to replace the existing response with an internal redirect. These are two different cases and need to be treated as such.

In the first case, we are creating the subrequest from within a handler or filter. This means that the next filter should be passed to make_sub_request function, and the last resource filter in the sub-request will point to the next filter in the main request. This makes sense, because the sub-request's data needs to flow through the same set of filters as the main request. A graphical representation might help:

Default_handler --> includes_filter --> byterange --> ...

If the includes filter creates a sub request, then we don't want the data from that sub-request to go through the includes filter, because it might not be SSI data. So, the subrequest adds the following:

Default_handler --> includes_filter -/-> byterange --> ...
                                    /
Default_handler --> sub_request_core

What happens if the subrequest is SSI data? Well, that's easy, the includes_filter is a resource filter, so it will be added to the sub request in between the Default_handler and the sub_request_core filter.

The second case for sub-requests is when one sub-request is going to become the real request. This happens whenever a sub-request is created outside of a handler or filter, and NULL is passed as the next filter to the make_sub_request function.

In this case, the resource filters no longer make sense for the new request, because the resource has changed. So, instead of starting from scratch, we simply point the front of the resource filters for the sub-request to the front of the protocol filters for the old request. This means that we won't lose any of the protocol filters, neither will we try to send this data through a filter that shouldn't see it.

The problem is that we are using a doubly-linked list for our filter stacks now. But, you should notice that it is possible for two lists to intersect in this model. So, you do you handle the previous pointer? This is a very difficult question to answer, because there is no "right" answer, either method is equally valid. I looked at why we use the previous pointer. The only reason for it is to allow for easier addition of new servers. With that being said, the solution I chose was to make the previous pointer always stay on the original request.

This causes some more complex logic, but it works for all cases. My concern in having it move to the sub-request, is that for the more common case (where a sub-request is used to add data to a response), the main filter chain would be wrong. That didn't seem like a good idea to me.

Asis

The final topic. :-) Mod_Asis is a bit of a hack, but the handler needs to remove all filters except for connection filters, and send the data. If you are using mod_asis, all other bets are off.

Explanations

The absolutely last point is that the reason this code was so hard to get right, was because we had hacked so much to force it to work. I wrote most of the hacks originally, so I am very much to blame. However, now that the code is right, I have started to remove some hacks. Most people should have seen that the reset_filters and add_required_filters functions are gone. Those inserted protocol level filters for error conditions, in fact, both functions did the same thing, one after the other, it was really strange. Because we don't lose protocol filters for error cases any more, those hacks went away. The HTTP_HEADER, Content-length, and Byterange filters are all added in the insert_filters phase, because if they were added earlier, we had some interesting interactions. Now, those could all be moved to be inserted with the HTTP_IN, CORE, and CORE_IN filters. That would make the code easier to follow.


Terms Used to Describe Modules - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

Terms Used to Describe Modules

This document describes the terms that are used to describe each Apache module.

Description

A brief description of the purpose of the module.

Status

This indicates how tightly bound into the Apache Web server the module is; in other words, you may need to recompile the server in order to gain access to the module and its functionality. Possible values for this attribute are:

MPM
A module with status "MPM" is a Multi-Processing Module. Unlike the other types of modules, Apache must have one and only one MPM in use at any time. This type of module is responsible for basic request handling and dispatching.
Base
A module labeled as having "Base" status is compiled and loaded into the server by default, and is therefore normally available unless you have taken steps to remove the module from your configuration.
Extension
A module with "Extension" status is not normally compiled and loaded into the server. To enable the module and its functionality, you may need to change the server build configuration files and re-compile Apache.
Experimental
"Experimental" status indicates that the module is available as part of the Apache kit, but you are on your own if you try to use it. The module is being documented for completeness, and is not necessarily supported.
External
Modules which are not included with the base Apache distribution ("third-party modules") may use the "External" status. We are not responsible for, nor do we support such modules.

Source File

This quite simply lists the name of the source file which contains the code for the module. This is also the name used by the <IfModule> directive.

Module Identifier

This is a string which identifies the module for use in the LoadModule directive when dynamically loading modules. In particular, it is the name of the external variable of type module in the source file.

Compatibility

If the module was not part of the original Apache version 2 distribution, the version in which it was introduced should be listed here. In addition, if the module is limited to particular platforms, the details will be listed here.


지시어를 설명하는데 사용한 용어들 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

지시어를 설명하는데 사용한 용어들

이 문서는 아파치 설정 지시어를 설명하는데 사용한 용어들을 설명한다.

참고

  • 설정파일

설명 (Description)

지시어의 목적에 대한 간단한 설명.

문법 (Syntax)

설정파일에서 사용할 지시어의 형식을 알려준다. 이 문법은 지시어마다 매우 다르며, 지시어를 정의할 때마다 자세히 설명한다. 일반적으로 지시어 이름 뒤에 공백으로 구분한 아규먼트들이 나온다. 아규먼트가 공백을 포함한다면 아규먼트를 쌍따옴표로 묶어야 한다. 선택적인 아규먼트는 중괄호로 묶는다. 아규먼트가 여러 값중 하나일 경우 값들을 수직막대 "|"로 구분한다. 문자그대로 사용할 부분은 기본 문자체로 쓰고, 대체할 아규먼트는 강조한다. 아규먼트 개수가 정해지지않은 지시어는 마지막 아규먼트가 반복됨을 나타내는 "..."으로 끝난다.

지시어는 매우 다양한 종류의 아규먼트를 받는다. 이중 자주 사용하는 것은 아래와 같다.

URL
http://www.example.com/path/to/file.html과 같이 스킴(scheme), 호스트명, 선택적인 경로명을 포함한 완전한 Uniform Resource Locator
URL-path
/path/to/file.html과 같이 url에서 스킴과 호스트명 뒤에 나오는 부분. url-path는 파일시스템에서 본 시점이 아닌 웹에서 본 시점에서의 자료를 나타낸다.
file-path
/usr/local/apache/htdocs/path/to/file.html과 같이 root 디렉토리로 시작하는 파일시스템상의 파일 경로. 따로 언급하지않으면, 슬래쉬로 시작하지않은 file-path는 ServerRoot에 상대경로로 취급한다.
directory-path
/usr/local/apache/htdocs/path/to/와 같이 root 디렉토리로 시작하는 파일시스템상의 디렉토리 경로.
filename
file.html과 같이 경로 정보가 없는 파일명.
regex
문자를 검색할 패턴을 설명하는 정규표현식(regular expression). 지시어는 regex로 무엇인가를 검색한다.
extension
일반적으로 filename에서 마지막 마침표 뒤에 나오는 부분이다. 그러나 아파치는 여러 확장자를 인식할 수 있기때문에, filename에 마침표가 여러개 포함된 경우 마침표로 구분된 모든 부분을 확장자(extension)로 처리한다. 예를 들어, 파일명 file.html.en은 .html과 .en이라는 두가지 확장자를 가진다. 아파치 지시어에서 extension에 지정한 값 앞에 마침표가 있어도 되고 없어도 된다. 또, extension은 대소문자를 가리지않는다.
MIME-type
text/html과 같이 슬래쉬로 major format type과 minor format type를 구분하여 파일의 형식을 설명하는 방식.
env-variable
아파치 설정에서 정의한 환경변수 이름. 운영체제의 환경변수와 다름을 주의하라. 자세한 내용은 환경변수 문서를 참고하라.

기본값 (Default)

지시어에 기본값이 있다면 (예를 들어, 설정에서 지시어를 생략한 경우 아파치 웹서버는 이 값을 사용한다.) 이 항목에 나온다. 기본값이 없다면 이 항목은 "None"이어야 한다. 기본값이 서버에 포함된 기본 httpd.conf의 지시어 값과 다를 수 있음을 주의하라.

사용장소 (Context)

서버의 설정파일중 어느곳에서 지시어를 사용할 수 있는지 알려준다. 다음 값들을 쉼표로 구분한 목록이다:

주서버설정 (server config)
지시어를 서버 설정파일에서 (예를 들어, httpd.conf) 사용할 수 있으나, <VirtualHost>나 <Directory>에서 사용할 수 없음을 뜻한다. 이 지시어는 .htaccess 파일에서도 사용할 수 없다.
가상호스트 (virtual host)
지시어를 서버 설정파일의 <VirtualHost> 안에서 사용할 수 있음을 뜻한다.
디렉토리 (directory)
지시어가 어떻게 Directory, Location, Files 섹션이 동작하나에 설명한 제약을 따르며, 서버 설정파일의 <Directory>, <Location>, <Files>에서 사용할 수 있음을 뜻한다.
.htaccess
지시어를 디렉토리별 .htaccess 파일에서 사용할 수 있음을 뜻한다. 이 지시어는 현재 사용하는 overrides 값에 따라 무시될 수 있다.

지시어는 지정된 장소에서만 사용할 수 있다. 다른 곳에서 사용하면 설정오류가 발생하고 서버는 부분에 대한 요청을 올바로 처리하지 못하거나 작동이, 예를 들어 시작조차도, 안될 수 있다.

지시어를 사용할 수 있는 장소는 열거한 장소를 모두 불린(boolean) OR한 결과이다. 즉, "server config, .htaccess"에서 가능하다는 지시어는 httpd.conf 파일과 .htaccess 파일에서는 사용할 수 있지만, <Directory>나 <VirtualHost>에서는 사용할 수 없다.

Override 옵션 (Override)

이 지시어를 .htaccess 파일에서 사용하려면 어떤 override 옵션을 사용해야 하는지를 나타낸다. 지시어의 사용장소가 지시어를 .htaccess 파일에서 사용할 수 없다고 한다면 어떤 사용장소도 나오지 않는다.

Overrides는 AllowOverride 지시어로 지시하고, (디렉토리 등의) 특정 범위와 하위 범위에서 다른 AllowOverride 지시어로 다른 값을 설정하지않았다면 하위 범위에도 그대로 적용된다. 지시어 설명에 사용가능한 override 이름들이 나온다.

상태 (Status)

지시어가 아파치 웹서버에 얼마나 긴밀히 묶여있는지를 나타낸다. 즉, 그 지시어나 기능을 사용하기위해 서버를 모듈과 같이 다시 컴파일할 필요가 있을 수도 있다. 가능한 값은 다음과 같다:

Core
지시어가 "Core" 상태를 가지면, 지시어가 아파치 웹서버 핵심부분에 속하고 항상 사용가능함을 뜻한다.
MPM
"MPM" 상태인 지시어는 다중처리 모듈을 제공한다. 이런 지시어는 지시어 설명에서 모듈에 열거된 MPM중 하나를 사용할때만 가능하다.
Base
기본적으로 서버와 같이 컴파일되므로 직접 구성에서 모듈을 제거하지 않았다면 일반적으로 사용가능한 표준 아파치 모듈이 제공하는 지시어는 "Base" 상태이다.
Extension
아파치 서버 배포본에는 포함되있지만 보통 서버와 같이 컴파일되지않는 모듈이 제공하는 지시어는 "Extension" 상태이다. 이런 지시어를 사용하려면 서버 컴파일 구성파일을 수정하고 아파치를 다시 컴파일해야 한다.
Experimental
"Experimental"은 지시어가 아파치 배포본에 포함되있지만, 사용은 자신의 책임임을 나타낸다. 지시어는 문서화되있지만, 실제와 다를 수 있다. 지시어를 제공하는 모듈은 기본적으로 아파치와 같이 컴파일될 수도 안될 수도 있다. 지시어와 모듈을 설명하는 문서 앞에서 사용할 수 있는지 살펴봐라.

모듈 (Module)

단순히 지시어를 정의한 소스 모듈명을 열거한다.

지원 (Compatibility)

지시어가 원래 아파치 버전 2 배포본의 일부가 아니였다면, 지시어를 추가하기 시작한 버전이 여기 나온다. 또, 어떤 플래폼에서만 사용가능한 지시어도 여기 나온다.


용어 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

용어

이 문서는 웹 서비스 일반에 대한, 특히 아파치와 관련된, 용어들을 정의한다. 각 개념에 대한 자세한 정보는 링크를 참고하라. (역주; 현재 단어의 순서는 한글 순서가 아니라, 영문자 순서입니다. 용어번역표는 여기를 참고하길 바랍니다.)

정의

인증 (Authentication)
서버, 클라이언트, 사용자 등 네트웍 실체에 대한 확인.
참고: 인증, 권한부여, 접근제어
접근제어 (Access Control)
네트웍 영역에 대한 접근을 제한. 아파치에서는 보통 특정 URL의 접근을 제한하기위해 사용한다.
참고: 인증, 권한부여, 접근제어
알고리즘 (Algorithm)
유한한 단계를 거쳐 문제를 푸는 명확한 공식 혹은 규칙들. 암호화를 위한 알고리즘을 보통 암호기(Ciphers)라고 부른다.
APache eXtension Tool (apxs)
모듈 (module) 소스를 동적공유객체 (DSO)로 컴파일하고 아파치 웹서버에 설치하는 작업을 돕는 perl 스크립트.
참고: Manpage: apxs
인증서 (Certificate)
서버나 클라이언트와 같은 네트웍 실체를 인증하는 자료. 인증서에는 소유자 (subject라고 함), 서명 인증기관 (Certificate Authority) (issuer라고 함), 소유자의 공개키, CA가 만든 서명 등에 대한 X.509 정보가 있다. 네트웍 실체는 CA 인증서를 사용하여 서명을 검사한다.
참고: SSL/TLS 암호화
인증기관 (Certification Authority, CA)
안전한 방법으로 네트웍 실체에 대한 인증을 서명하는 신뢰하는 제삼자. 다른 네트웍 실체들은 서명으로 CA가 인증서 소유자를 인증했는지 확인할 수 있다.
참고: SSL/TLS 암호화
인증 서명 요청 (Certificate Signing Request, CSR)
인증기관 (Certification Authority)에 제출하여 CA 인증서 (Certificate)의 개인키 (Private Key)로 서명될 아직 서명되지않은 인증서. CSR이 서명되면 실제 인증서가 된다.
참고: SSL/TLS 암호화
암호기 (Cipher)
자료를 암호화하는 알고리즘이나 시스템. 예를 들어, DES, IDEA, RC4 등이 있다.
참고: SSL/TLS 암호화
암호문 (Ciphertext)
평문 (Plaintext)을 암호기 (Cipher)로 처리한 결과.
참고: SSL/TLS 암호화
공통 게이트웨이 인터페이스 (Common Gateway Interface, CGI)
외부 프로그램이 요청을 서비스할 수 있도록 만든 웹서버와 외부 프로그램 사이의 인터페이스 표준. 인터페이스는 원래 NCSA가 정의했지만, RFC 프로젝트이기도 하다.
참고: CGI로 동적 내용 생성
설정 지시어 (Configuration Directive)
참고: 지시어
설정파일 (Configuration File)
아파치를 설정하는 지시어 (directive)를 적어둔 텍스트파일.
참고: 설정파일
CONNECT
HTTP를 통해 자료흐름을 프록시하는 HTTP 메써드 (method). SSL 프로토콜 등 다른 프로토콜을 감싸기위해 사용한다.
사용장소 (Context)
설정파일 (configuration file)에서 특정 지시어 (directive)를 사용할 수 있는 장소.
참고: 아파치 지시어를 설명하는데 사용한 용어정의
전자서명 (Digital Signature)
인증서나 다른 파일을 검사하는 암호화된 문자들. 인증기관 (Certification Authority)은 인증서 (Certificate)에 포함된 공개키 (Public Key)를 해쉬한 결과를 자신의 개인키 (Private Key)로 암호화하여 서명을 만든다. 오직 CA의 공개키만이 서명을 풀 수 있기때문에, CA가 인증서 (Certificate)를 가진 네트웍 실체를 인증했음을 증명할 수 있다.
참고: SSL/TLS 암호화
지시어 (Directive)
아파치의 여러 기능을 조절하는 설정 명령어. 지시어는 설정파일 (Configuration File)에서 사용한다.
참고: 지시어 목록
동적공유객체 (Dynamic Shared Object) (DSO)
아파치 httpd 실행파일과 별도로 컴파일하여 필요할때 읽어들일 수 있는 모듈 (Module).
참고: 동적공유객체 지원
환경변수 (Environment Variable) (env-variable)
정보를 저장하고 프로그램간에 통신을 위해 운영체제 쉘이 관리하는 변수. 아파치에도 환경변수라는 내부 변수가 있지만, 쉘 환경이 아니라 아파치 내부에 저장된다.
참고: 아파치의 환경변수
수출용 (Export-Crippled)
미국 수출관리규제(Export Administration Regulations, EAR)를 준수하기위해 암호(와 보안)의 강도를 낮춤. 수출용 암호화 소프트웨어는 키 크기가 작게 제한되어, 암호문 (Ciphertext)을 무식한 방법(brute force)으로 풀 수 있다.
참고: SSL/TLS 암호화 (SSL/TLS Encryption)
필터 (Filter)
서버가 보내거나 받는 자료를 처리하는 과정. 입력필터는 클라이언트가 서버로 보내는 자료를 처리하고, 출력필터는 서버가 클라이언트에게 보낼 문서를 처리한다. 예를 들어, INCLUDES 출력필터는 문서의 Server Side Includes를 처리한다.
참고: 필터
완전한 도메인명 (Fully-Qualified Domain-Name) (FQDN)
IP 주소에 대응하는, 호스트명과 도메인명으로 구성된 네트웍 실체의 유일한 이름. 예를 들어, www가 호스트명이고 example.com이 도메인명일때, www.example.com은 완전한 도메인명이다.
핸들러 (Handler)
파일을 요청할때 수행하는 작업에 대한 아파치 내부 표현. 일반적으로 파일은 파일 종류에 따라 암묵적인 핸들러를 가진다. 보통 모든 파일은 서버가 간단히 서비스하지만, 어떤 파일 종류는 따로 "처리된다(handled)". 예를 들어, cgi-script 핸들러는 CGI로 처리할 파일을 지정한다.
참고: 아파치에서 핸들러 사용
헤더 (Header)
HTTP 요청과 응답에서 실제 내용 이전에 보내는 부분으로 내용을 설명하는 정보가 있다.
.htaccess
웹문서들 안에 있는 설정파일 (configuration file)로, 설정 지시어 (directive)를 자신이 위치한 디렉토리와 모든 하위디렉토리에 적용한다. 이름과 달리 이 파일에서는 단순한 접근제어 지시어외에 거의 모든 종류의 지시어를 사용할 수 있다.
참고: 설정파일
httpd.conf
아파치 주 설정파일 (configuration file). 기본적인 위치는 /usr/local/apache2/conf/httpd.conf이지만, 실행할때 혹은 컴파일때 설정으로 변경할 수 있다.
참고: 설정파일
HyperText Transfer Protocol (HTTP)
월드와이드웹에서 사용하는 표준 전송 프로토콜. 아파치는 RFC 2616에서 정의한 HTTP/1.1이라는 프로토콜의 1.1 버전을 구현한다.
HTTPS
월드화이드웹의 표준 암호통신 방법, HyperText Transport Protocol (Secure). 사실 밑단에 SSL을 사용한 HTTP이다.
참고: SSL/TLS 암호화
메써드 (Method)
클라이언트가 보내는 HTTP 요청줄이 자원에 수행하도록 지시한 행동. HTTP 메써드에는 GET, POST, PUT 등이 있다.
메시지 요약 (Message Digest)
메시지 내용이 전송중 변경되지 않았음을 증명하기위한 메시지의 해쉬.
참고: SSL/TLS 암호화
MIME-type
전송할 문서의 종류를 설명하는 방식. Multipurpose Internet Mail Extensions 형식을 빌려왔기때문에 이렇게 이름을 지었다. 슬래쉬를 사이에 둔 major type과 minor type으로 이루어진다. 예를 들면, text/html, image/gif, application/octet-stream 등이다. MIME-type은 HTTP의 Content-Type 헤더 (header)로 전송한다.
참고: mod_mime
모듈 (Module)
프로그램의 독립된 부분. 많은 아파치 기능은 당신이 포함여부를 선택할 수 있는 모듈에 들어있다. 아파치 httpd 실행파일과 같이 컴파일한 모듈을 정적 모듈이라고 하며, 따로 분리되어 실행시 선택적으로 읽어들일 수 있는 모듈을 동적 모듈 혹은 DSO라고 한다. 기본적으로 포함하는 모듈을 base 모듈이라고 한다. 아파치 웹서버 타볼 (tarball)과 같이 배포되지는 않지만 아파치에는 많은 모듈들이 있다. 이들을 제삼자가 만든(third-party) 모듈이라고 한다.
참고: 모듈 목록
모듈 마법수 (Module Magic Number) (MMN)
모듈 마법수는 아파치 소스코드가 정의한 상수로, 모듈의 이진호환성과 관련이 있다. 모듈 마법수는 이진호환성을 더 이상 보장할 수 없도록 아파치 내부 구조나 함수 호출, 다른 API 일부가 변경된 경우에 바뀐다. MMN이 변하면 제삼자가 만든 모듈은 모두 최소한 다시 컴파일되야 한다. 새 아파치 버전에 맞도록 조금 수정해야할 경우도 있다.
OpenSSL
SSL/TLS를 위한 오픈소스 도구
참고 http://www.openssl.org/
Pass Phrase
개인키 파일을 보호하는 문구. 인증하지않은 사용자가 이 개인키 파일을 사용하여 암호화하지 못하도록 한다. 보통 암호기 (Ciphers)가 사용하는 비밀스런 암호/해독 키이다.
참고: SSL/TLS 암호화
평문 (Plaintext)
암호화하지 않은 글.
개인키 (Private Key)
받은 자료를 해독하고 보내는 자료를 서명하기위한 공개키 암호화 (Public Key Cryptography) 시스템의 암호키.
참고: SSL/TLS 암호화
프록시 (Proxy)
클라이언트와 실제 서버 사이에 있는 중간 서버. 클라이언트에게 요청을 받아 실제 서버로 보내고, 실제 서버에게서 받은 응답을 다시 클라이언트에게 보낸다. 여러 클라이언트가 같은 내용을 요청하면 프록시는 매번 서버에 요청하지않고 캐쉬에 저장된 내용을 사용하여 응답시간을 줄일 수 있다.
참고: mod_proxy
공개키 (Public Key)
공개키 암호화 (Public Key Cryptography) 시스템에서 키의 소유자에게 보내는 문구를 암호화하거나 소유자가 만든 서명을 풀기위한 공개된 키.
참고: SSL/TLS 암호화
공개키 암호화 (Public Key Cryptography)
암호와 해독에 서로 다른 키를 사용하는 비대칭(asymmetric) 암호화 시스템의 연구 및 활용. 암호와 해독에 사용하는 두개의 키는 키쌍(key pair)을 이룬다. 비대칭 암호화라고도 부른다.
참고: SSL/TLS 암호화
정규표현식 (Regular Expression) (Regex)
글의 패턴을 기술하는 방식. 예를 들어, "문자 A로 시작하는 모든 단어", "숫자 10개로된 전화번호", 심지어 "쉼표가 두개있고 대문자 Q가 없는 문장" 등을 표현할 수 있다. 정규표현식을 사용하면 매우 유연하게 파일이나 자원에 어떤 성질을 적용할 수 있다. 예를 들어, "images"란 디렉토리 아래에 있는 모든 .gif와 .jpg 파일은 "/images/.*(jpg|gif)$"로 지칭할 수 있다. 아파치는 PCRE 라이브러리를 사용하여 Perl호환 정규표현식을 지원한다.
역프록시 (Reverse Proxy)
클라이언트에게 실제 서버처럼 보이는 프록시 (proxy) 서버. 보안상 이유 혹은 부하를 분산하기위해 클라이언트에게 실제 서버를 숨길때 유용하다.
Secure Sockets Layer (SSL)
Netscape Communications사가 TCP/IP 네트웍의 일반적인 통신 인증과 암호화를 위해 만든 프로토콜. 가장 일반적인 용도는 HTTPS (HyperText Transfer Protocol (HTTP) over SSL)이다.
참고: SSL/TLS 암호화
Server Side Includes (SSI)
HTML 파일 안에 처리지시어를 포함하는 기술.
참고: Server Side Includes 소개
세션 (Session)
일반적으로 통신의 상황(context) 정보.
SSLeay
Eric A. Young이 개발한 원래 SSL/TLS 구현 라이브러리
대칭적 암호법 (Symmetric Cryptography)
암호와 해독 작업에 같은 암호키를 사용하는 암호기 (Ciphers)의 연구 및 활용.
참고: SSL/TLS Encryption
타볼 (Tarball)
tar 도구를 사용하여 파일들을 모은 묶음. 아파치는 tar 파일을 압축하거나 pkzip으로 압축하여 배포된다.
Transport Layer Security (TLS)
인터넷기술 관련 국제표준화기구(Internet Engineering Task Force, IETF)가 TCP/IP 네트웍의 일반적인 통신 인증과 암호화를 위해 만든 SSL의 후속 프로토콜. TLS 버전 1은 SSL 버전 3과 거의 유사하다.
참고: SSL/TLS 암호화
Uniform Resource Locator (URL)
인터넷에 있는 자원의 이름/주소. 정식으로는 Uniform Resource Identifier라고 하는 것의 일상적인 비공식 용어다. 보통 URL은 http나 https같은 스킴(scheme), 호스트명, 경로로 구성된다. 이 페이지의 URL은 http://httpd.apache.org/docs-2.0/glossary.html이다.
Uniform Resource Identifier (URI)
추상적인 자원이나 실제 자원을 지칭하기위한 간결한 문자열. 공식적으로 RFC 2396에서 정의한다. 월드와이드웹에서 사용하는 URI를 보통 URL이라고 부른다.
가상호스트 (Virtual Hosting)
아파치 하나로 여러 웹사이트를 서비스하기. IP 가상호스트는 웹사이트마다 IP 주소가 다르다. 이름기반(name-based) 가상호스트는 호스트명만을 사용하므로 한 IP 주소에서 여러 사이트를 서비스할 수 있다.
참고: 아파치 가상호스트 문서
X.509
국제전기통신연합(International Telecommunication Union, ITU-T)이 권장하는 인증서 양식. SSL/TLS 인증에서 사용한다.
참고: SSL/TLS 암호화


사이트맵 - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0

사이트맵

이 페이지는 현재 Apache HTTP Server Version 2.0 문서 목록을 보여준다.

발표문

  • 1.3에서 2.0으로 업그레이드
  • 아파치 2.0의 새로운 기능
  • 아파치 라이선스

아파치 웹서버 사용하기

  • 아파치 컴파일과 설치
  • 아파치 시작
  • 서버 중단과 재시작
  • 설정파일
  • 어떻게 Directory, Location, Files 섹션이 동작하나
  • 서버 전역 설정
  • 로그파일
  • URL을 파일시스템에 대응
  • 보안 팁
  • 동적공유객체 (DSO) 지원
  • 내용협상 (content negotiation)
  • 사용자정의 오류 응답
  • 아파치가 사용할 주소와 포트 지정
  • 다중처리모듈 (MPM)
  • 아파치의 환경변수
  • 아파치에서 핸들러 사용
  • 필터
  • suEXEC 지원
  • 성능향상 힌트
  • URL 재작성(rewriting) 지침서

아파치 가상호스트 문서

  • 개요
  • 이름기반 가상호스트
  • IP기반 가상호스트 지원
  • 대량의 가상호스트를 동적으로 설정하기
  • 가상호스트 예
  • 가상호스트 찾기에 대한 자세한 설명
  • 파일기술자(file descriptor) 한계
  • DNS와 아파치와 관련된 사항

아파치 서버에 대해 자주 물어보는 질문

  • 개요
  • 모두 한 페이지에
  • 지원

아파치 SSL/TLS 암호화

  • 소개
  • SSL/TLS 암호화: 소개
  • SSL/TLS 암호화: 호환성
  • SSL/TLS 암호화: How-To
  • SSL/TLS 암호화: FAQ

지침서, 투토리얼, HowTo

  • 개요
  • 인증
  • CGI로 동적 내용
  • Server Side Includes 소개
  • .htaccess 파일
  • 사용자별 웹디렉토리
  • 아파치 투토리얼

플래폼별 설명

  • 개요
  • Microsoft Windows에서 아파치 사용하기
  • Microsoft Windows에서 아파치 컴파일하기
  • Novell NetWare에서 아파치 사용하기
  • HPUX에서 고성능 웹서버 실행하기
  • 아파치 EBCDIC 포팅

아파치 웹서버와 지원 프로그램

  • 개요
  • Manpage: httpd
  • Manpage: ab
  • Manpage: apachectl
  • Manpage: apxs
  • Manpage: dbmmanage
  • Manpage: htdigest
  • Manpage: htpasswd
  • Manpage: logresolve
  • Manpage: rotatelogs
  • Manpage: suexec
  • 다른 프로그램들

기타 아파치 문서

  • 개요
  • 다국어 사용자정의 서버 오류문
  • FIN_WAIT_2 상태 연결과 아파치
  • 클라이언트의 이미 알려진 문제점
  • 파일기술자와 아파치
  • CGI 환경에서 PATH_INFO의 변화

아파치 모듈

  • 모듈 목록
  • 지시어 목록
  • 지시어 빠른참조
  • 아파치 핵심 기능
  • 아파치 MPM 공통 지시어
  • 아파치 MPM beos
  • 아파치 MPM leader
  • 아파치 MPM netware
  • 아파치 MPM os2
  • 아파치 MPM perchild
  • 아파치 MPM prefork
  • 아파치 MPM threadpool
  • 아파치 MPM winnt
  • 아파치 MPM worker
  • 아파치 모듈 mod_access
  • 아파치 모듈 mod_actions
  • 아파치 모듈 mod_alias
  • 아파치 모듈 mod_asis
  • 아파치 모듈 mod_auth
  • 아파치 모듈 mod_auth_anon
  • 아파치 모듈 mod_auth_dbm
  • 아파치 모듈 mod_auth_digest
  • 아파치 모듈 mod_auth_ldap
  • 아파치 모듈 mod_autoindex
  • 아파치 모듈 mod_cache
  • 아파치 모듈 mod_cern_meta
  • 아파치 모듈 mod_cgi
  • 아파치 모듈 mod_cgid
  • 아파치 모듈 mod_charset_lite
  • 아파치 모듈 mod_dav
  • 아파치 모듈 mod_dav_fs
  • 아파치 모듈 mod_deflate
  • 아파치 모듈 mod_dir
  • 아파치 모듈 mod_disk_cache
  • 아파치 모듈 mod_echo
  • 아파치 모듈 mod_env
  • 아파치 모듈 mod_example
  • 아파치 모듈 mod_expires
  • 아파치 모듈 mod_ext_filter
  • 아파치 모듈 mod_file_cache
  • 아파치 모듈 mod_headers
  • 아파치 모듈 mod_imap
  • 아파치 모듈 mod_include
  • 아파치 모듈 mod_info
  • 아파치 모듈 mod_isapi
  • 아파치 모듈 mod_ldap
  • 아파치 모듈 mod_log_config
  • 아파치 모듈 mod_logio
  • 아파치 모듈 mod_mem_cache
  • 아파치 모듈 mod_mime
  • 아파치 모듈 mod_mime_magic
  • 아파치 모듈 mod_negotiation
  • 아파치 모듈 mod_nw_ssl
  • 아파치 모듈 mod_proxy
  • 아파치 모듈 mod_proxy_connect
  • 아파치 모듈 mod_proxy_ftp
  • 아파치 모듈 mod_proxy_http
  • 아파치 모듈 mod_rewrite
  • 아파치 모듈 mod_setenvif
  • 아파치 모듈 mod_so
  • 아파치 모듈 mod_speling
  • 아파치 모듈 mod_ssl
  • 아파치 모듈 mod_status
  • 아파치 모듈 mod_suexec
  • 아파치 모듈 mod_unique_id
  • 아파치 모듈 mod_userdir
  • 아파치 모듈 mod_usertrack
  • 아파치 모듈 mod_vhost_alias

개발자 문서

  • 개요
  • Apache API 설명
  • APR의 메모리할당 디버깅
  • Apache 2.0 문서화
  • Apache 2.0 훅(hook) 함수
  • Apache 1.3에서 Apache 2.0으로 모듈을 수정하기
  • Apache 2.0의 요청처리
  • Apache 2.0의 필터 동작법

설명 정보

  • 아파치 모듈을 설명하는데 사용한 용어정의
  • 아파치 지시어를 설명하는데 사용한 용어정의
  • 용어
  • 사이트맵 (이 문서)


Apache 2.0 Thread Safety Issues - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > Developer Documentation

Apache 2.0 Thread Safety Issues

When using any of the threaded mpms in Apache 2.0 it is important that every function called from Apache be thread safe. When linking in 3rd party extensions it can be difficult to determine whether the resulting server will be thread safe. Casual testing generally won't tell you this either as thread safety problems can lead to subtle race conditons that may only show up in certain conditions under heavy load.

Global and static variables

When writing your module or when trying to determine if a module or 3rd party library is thread safe there are some common things to keep in mind.

First, you need to recognize that in a threaded model each individual thread has its own program counter, stack and registers. Local variables live on the stack, so those are fine. You need to watch out for any static or global variables. This doesn't mean that you are absolutely not allowed to use static or global variables. There are times when you actually want something to affect all threads, but generally you need to avoid using them if you want your code to be thread safe.

In the case where you have a global variable that needs to be global and accessed by all threads, be very careful when you update it. If, for example, it is an incrementing counter, you need to atomically increment it to avoid race conditions with other threads. You do this using a mutex (mutual exclusion). Lock the mutex, read the current value, increment it and write it back and then unlock the mutex. Any other thread that wants to modify the value has to first check the mutex and block until it is cleared.

If you are using APR, have a look at the apr_atomic_* functions and the apr_thread_mutex_* functions.

errno

This is a common global variable that holds the error number of the last error that occurred. If one thread calls a low-level function that sets errno and then another thread checks it, we are bleeding error numbers from one thread into another. To solve this, make sure your module or library defines _REENTRANT or is compiled with -D_REENTRANT. This will make errno a per-thread variable and should hopefully be transparent to the code. It does this by doing something like this:

#define errno (*(__errno_location()))

which means that accessing errno will call __errno_location() which is provided by the libc. Setting _REENTRANT also forces redefinition of some other functions to their *_r equivalents and sometimes changes the common getc/putc macros into safer function calls. Check your libc documentation for specifics. Instead of, or in addition to _REENTRANT the symbols that may affect this are _POSIX_C_SOURCE, _THREAD_SAFE, _SVID_SOURCE, and _BSD_SOURCE.

Common standard troublesome functions

Not only do things have to be thread safe, but they also have to be reentrant. strtok() is an obvious one. You call it the first time with your delimiter which it then remembers and on each subsequent call it returns the next token. Obviously if multiple threads are calling it you will have a problem. Most systems have a reentrant version of of the function called strtok_r() where you pass in an extra argument which contains an allocated char * which the function will use instead of its own static storage for maintaining the tokenizing state. If you are using APR you can use apr_strtok().

crypt() is another function that tends to not be reentrant, so if you run across calls to that function in a library, watch out. On some systems it is reentrant though, so it is not always a problem. If your system has crypt_r() chances are you should be using that, or if possible simply avoid the whole mess by using md5 instead.

Common 3rd Party Libraries

The following is a list of common libraries that are used by 3rd party Apache modules. You can check to see if your module is using a potentially unsafe library by using tools such as ldd(1) and nm(1). For PHP, for example, try this:

% ldd libphp4.so
libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)
libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)
libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)
libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)
libz.so.1 => /usr/lib/libz.so.1 (0x403e2000)
libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)
libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11 (0x40411000)
libming.so => /usr/lib/libming.so (0x40449000)
libm.so.6 => /lib/libm.so.6 (0x40487000)
libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)
libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)
libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)
libssl.so.2 => /lib/libssl.so.2 (0x40532000)
libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)
libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)
libdl.so.2 => /lib/libdl.so.2 (0x40634000)
libnsl.so.1 => /lib/libnsl.so.1 (0x40637000)
libc.so.6 => /lib/libc.so.6 (0x4064b000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)

In addition to these libraries you will need to have a look at any libraries linked statically into the module. You can use nm(1) to look for individual symbols in the module.

Library List

Please drop a note to dev@httpd.apache.org if you have additions or corrections to this list.

Library | Version | Thread Safe? | Notes
ASpell/PSpell |  | ? |
Berkeley DB | 3.x, 4.x | Yes | Be careful about sharing a connection across threads.
bzip2 |  | Yes | Both low-level and high-level APIs are thread-safe. However, high-level API requires thread-safe access to errno.
cdb |  | ? |
C-Client |  | Perhaps | c-client uses strtok() and gethostbyname() which are not thread-safe on most C library implementations. c-client's static data is meant to be shared across threads. If strtok() and gethostbyname() are thread-safe on your OS, c-client may be thread-safe.
cpdflib |  | ? |
libcrypt |  | ? |
Expat |  | Yes | Need a separate parser instance per thread
FreeTDS |  | ? |
FreeType |  | ? |
GD 1.8.x |  | ? |
GD 2.0.x |  | ? |
gdbm |  | No | Errors returned via a static gdbm_error variable
ImageMagick | 5.2.2 | Yes | ImageMagick docs claim it is thread safe since version 5.2.2 (see Change log).
Imlib2 |  | ? |
libjpeg | v6b | ? |
libmysqlclient |  | Yes | Use mysqlclient_r library variant to ensure thread-safety. For more information, please read http://www.mysql.com/doc/en/Threaded_clients.html.
Ming | 0.2a | ? |
Net-SNMP | 5.0.x | ? |
OpenLDAP | 2.1.x | Yes | Use ldap_r library variant to ensure thread-safety.
OpenSSL | 0.9.6g | Yes | Requires proper usage of CRYPTO_num_locks, CRYPTO_set_locking_callback, CRYPTO_set_id_callback
liboci8 (Oracle 8+) | 8.x,9.x | ? |
pdflib | 5.0.x | Yes | PDFLib docs claim it is thread safe; changes.txt indicates it has been partially thread-safe since V1.91: http://www.pdflib.com/products/pdflib/index.html.
libpng | 1.0.x | ? |
libpng | 1.2.x | ? |
libpq (PostgreSQL) | 7.x | Yes | Don't share connections across threads and watch out for crypt() calls
Sablotron | 0.95 | ? |
zlib | 1.1.4 | Yes | Relies upon thread-safe zalloc and zfree functions Default is to use libc's calloc/free which are thread-safe.


Error Messages - Frequently Asked Questions - Apache HTTP Server

Apache > HTTP Server > Documentation > Version 2.0 > FAQ

Error Messages - Frequently Asked Questions

Error Messages

  • Invalid argument: core_output_filter: writing data to the network

Invalid argument: core_output_filter: writing data to the network

Apache uses the sendfile syscall on platforms where it is available in order to speed sending of responses. Unfortunately, on some systems, Apache will detect the presence of sendfile at compile-time, even when it does not work properly. This happens most frequently when using network or other non-standard file-system.

Symptoms of this problem include the above message in the error log and zero-length responses to non-zero-sized files. The problem generally occurs only for static files, since dynamic content usually does not make use of sendfile.

To fix this problem, simply use the EnableSendfile directive to disable sendfile for all or part of your server. Also see the EnableMMAP, which can help with similar problems.


Relevant Standards - Apache HTTP Server

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

Relevant Standards

This page documents all the relevant standards that the Apache HTTP Server follows, along with brief descriptions.

In addition to the information listed below, the following resources should be consulted:

  • http://purl.org/NET/http-errata - HTTP/1.1 Specification Errata
  • http://www.rfc-editor.org/errata.html - RFC Errata
  • http://ftp.ics.uci.edu/pub/ietf/http/#RFC - A pre-compiled list of HTTP related RFCs

Notice

This document is not yet complete.

HTTP Recommendations

Regardless of what modules are compiled and used, Apache as a basic web server complies with the following IETF recommendations:

RFC 1945 (Informational)
The Hypertext Transfer Protocol (HTTP) is an application-level protocol with the lightness and speed necessary for distributed, collaborative, hypermedia information systems. This documents HTTP/1.0.
RFC 2616 (Standards Track)
The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. This documents HTTP/1.1.
RFC 2396 (Standards Track)
A Uniform Resource Identifier (URI) is a compact string of characters for identifying an abstract or physical resource.

HTML Recommendations

Regarding the Hypertext Markup Language, Apache complies with the following IETF and W3C recommendations:

RFC 2854 (Informational)
This document summarizes the history of HTML development, and defines the "text/html" MIME type by pointing to the relevant W3C recommendations.
HTML 4.01 Specification (Errata)
This specification defines the HyperText Markup Language (HTML), the publishing language of the World Wide Web. This specification defines HTML 4.01, which is a subversion of HTML 4.
HTML 3.2 Reference Specification
The HyperText Markup Language (HTML) is a simple markup language used to create hypertext documents that are portable from one platform to another. HTML documents are SGML documents.
XHTML? 1.1 - Module-based XHTML (Errata)
This Recommendation defines a new XHTML document type that is based upon the module framework and modules defined in Modularization of XHTML.
XHTML? 1.0 The Extensible HyperText Markup Language (Second Edition) (Errata)
This specification defines the Second Edition of XHTML 1.0, a reformulation of HTML 4 as an XML 1.0 application, and three DTDs corresponding to the ones defined by HTML 4.

Authentication

Concerning the different methods of authentication, Apache follows the following IETF recommendations:

RFC 2617 (Draft standard)
"HTTP/1.0", includes the specification for a Basic Access Authentication scheme.

Language/Country Codes

The following links document ISO and other language and country code information:

ISO 639-2
ISO 639 provides two sets of language codes, one as a two-letter code set (639-1) and another as a three-letter code set (this part of ISO 639) for the representation of names of languages.
ISO 3166-1
These pages document the country names (official short names in English) in alphabetical order as given in ISO 3166-1 and the corresponding ISO 3166-1-alpha-2 code elements.
BCP 47 (Best Current Practice), RFC 3066
This document describes a language tag for use in cases where it is desired to indicate the language used in an information object, how to register values for use in this language tag, and a construct for matching such language tags.
RFC 3282 (Standards Track)
This document defines a "Content-language:" header, for use in cases where one desires to indicate the language of something that has RFC 822-like headers, like MIME body parts or Web documents, and an "Accept-Language:" header for use in cases where one wishes to indicate one's preferences with regard to language.