apache http 2 - documentation.help · .htaccess server side includes (ssi) (public_html) microsoft...

||FAQ||

ApacheHTTP2.0Apache>HTTP>

ApacheHTTP2.0

GoogleSearch

Apache2.01.32.0Apache

SSL/TLSCGISuexecURLRewriting

How-To/

CGI:.htaccessServerSideIncludes(SSI) (public_html)

MicrosoftWindowsNovellNetWareEBCDIC

||FAQ||

ApacheHTTP2.0Apache>HTTP>>2.0

1.32.0

Apache

Apache2.0

Apache autoconf libtool Apache1.3APACI Apache2.0

Apache1.3 MPMApache1.3MPMProxy HTTP/1.1<Proxy>

PATH_INFO( )PHP PATH_INFO

SSI PATH_INFO

CacheNegotiatedDocs on offCacheNegotiatedDocs CacheNegotiatedDocson

ErrorDocument

ErrorDocument403"SomeMessage

ErrorDocument403"SomeMessage"

URLAccessConfig ResourceConfig httpd.confIncludeconf/srm.conf Apache

httpd.conf srm.confaccess.conf Include

BindAddress PortPortApache-1.3URL ServerName URLServerName MPMAgentLog RefererLog RefererIgnore

mod_log_agent mod_log_referer mod_log_config CustomLogAddModule ClearModuleList

APIFancyIndexing IndexOptions

FancyIndexingmod_negotiationMultiViews

MultiviewsMatch(2.0.51 )ErrorHeader

Headeralwayssetfoobar

Apache1.3 mod_auth_digestApache1.3 mod_mmap_static mod_file_cache

Apache src

||FAQ||

Apache2.0API Apache1.3Apache2.0

||FAQ||

Apache2.0

ApacheHTTP1.32.0

1.32.0

UnixPOSIXUnix Apache

autoconf libtool Apacheconfigure

Apache mod_echo

UnixApache2.0BeOSOS/2WindowsUnix (MPM) ApachePortableRuntime(APR) API POSIX

ApacheAPI2.0API 1.3/

IPv6ApacheApachePortableRuntimelibrary IPv6Apache IPv6listen Listen

NameVirtualHost,VirtualHostIPv6"Listen[2001:db8::1]:8080")

Apache ServerSideInclude

WindowsNTUnicode

WindowsNTApache2.0 utf-8UnicodeWindows2000WindowsXP WindowsNTWindows95,98,ME

Apache2.0 Perl(PCRE) Perl5

mod_ssl

Apache2.0OpenSSL SSL/TLS

mod_dav

Apache2.0 Versioning(DAV)

mod_deflate

Apache2.0

mod_auth_ldap

Apache2.0.41HTTP LDAP

mod_auth_digest

mod_charset_lite

Apache2.0

mod_file_cache

Apache2.0 Apache1.3 mod_mmap_static

mod_headers

Apache2.0 mod_proxy

mod_proxy

proxy HTTP/1.1proxyproxy() proxy_connect,proxy_ftp,proxy_http

mod_negotiation

NOTACCEPTABLEMULTIPLECHOICESForceLanguagePriority

mod_autoindex

Autoindex HTML

||FAQ||

mod_include

SSI SSImod_include$0..$9

mod_auth_dbm

AuthDBMTypeDBM

Modules|Directives|FAQ|Glossary|Sitemap

ApacheHTTPServerVersion2.0Apache>HTTPServer>Documentation>Version2.0

TheApacheLicense,Version2.0

ApacheLicenseVersion2.0,January2004

http://www.apache.org/licenses/

TERMSANDCONDITIONSFORUSE,REPRODUCTION,ANDDISTRIBUTION

1. Definitions

"License"shallmeanthetermsandconditionsforuse,reproduction,anddistributionasdefinedbySections1through9ofthisdocument.

"Licensor"shallmeanthecopyrightownerorentityauthorizedbythecopyrightownerthatisgrantingtheLicense.

"LegalEntity"shallmeantheunionoftheactingentityandallotherentitiesthatcontrol,arecontrolledby,orareundercommoncontrolwiththatentity.Forthepurposesofthisdefinition,"control"means(i)thepower,directorindirect,tocausethedirectionormanagementofsuchentity,whetherbycontractorotherwise,or(ii)ownershipoffiftypercent(50%)ormoreoftheoutstandingshares,or(iii)beneficialownershipofsuchentity.

"You"(or"Your")shallmeananindividualorLegalEntityexercisingpermissionsgrantedbythisLicense.

"Source"formshallmeanthepreferredformformakingmodifications,includingbutnotlimitedtosoftwaresourcecode,documentationsource,andconfigurationfiles.

"Object"formshallmeananyformresultingfrommechanicaltransformationortranslationofaSourceform,includingbutnot

limitedtocompiledobjectcode,generateddocumentation,andconversionstoothermediatypes.

"Work"shallmeantheworkofauthorship,whetherinSourceorObjectform,madeavailableundertheLicense,asindicatedbyacopyrightnoticethatisincludedinorattachedtothework(anexampleisprovidedintheAppendixbelow).

"DerivativeWorks"shallmeananywork,whetherinSourceorObjectform,thatisbasedon(orderivedfrom)theWorkandforwhichtheeditorialrevisions,annotations,elaborations,orothermodificationsrepresent,asawhole,anoriginalworkofauthorship.ForthepurposesofthisLicense,DerivativeWorksshallnotincludeworksthatremainseparablefrom,ormerelylink(orbindbyname)totheinterfacesof,theWorkandDerivativeWorksthereof.

"Contribution"shallmeananyworkofauthorship,includingtheoriginalversionoftheWorkandanymodificationsoradditionstothatWorkorDerivativeWorksthereof,thatisintentionallysubmittedtoLicensorforinclusionintheWorkbythecopyrightownerorbyanindividualorLegalEntityauthorizedtosubmitonbehalfofthecopyrightowner.Forthepurposesofthisdefinition,"submitted"meansanyformofelectronic,verbal,orwrittencommunicationsenttotheLicensororitsrepresentatives,includingbutnotlimitedtocommunicationonelectronicmailinglists,sourcecodecontrolsystems,andissuetrackingsystemsthataremanagedby,oronbehalfof,theLicensorforthepurposeofdiscussingandimprovingtheWork,butexcludingcommunicationthatisconspicuouslymarkedorotherwisedesignatedinwritingbythecopyrightowneras"NotaContribution."

"Contributor"shallmeanLicensorandanyindividualorLegalEntityonbehalfofwhomaContributionhasbeenreceivedby

LicensorandsubsequentlyincorporatedwithintheWork.

2. GrantofCopyrightLicense.SubjecttothetermsandconditionsofthisLicense,eachContributorherebygrantstoYouaperpetual,worldwide,non-exclusive,no-charge,royalty-free,irrevocablecopyrightlicensetoreproduce,prepareDerivativeWorksof,publiclydisplay,publiclyperform,sublicense,anddistributetheWorkandsuchDerivativeWorksinSourceorObjectform.

3. GrantofPatentLicense.SubjecttothetermsandconditionsofthisLicense,eachContributorherebygrantstoYouaperpetual,worldwide,non-exclusive,no-charge,royalty-free,irrevocable(exceptasstatedinthissection)patentlicensetomake,havemade,use,offertosell,sell,import,andotherwisetransfertheWork,wheresuchlicenseappliesonlytothosepatentclaimslicensablebysuchContributorthatarenecessarilyinfringedbytheirContribution(s)aloneorbycombinationoftheirContribution(s)withtheWorktowhichsuchContribution(s)wassubmitted.IfYouinstitutepatentlitigationagainstanyentity(includingacross-claimorcounterclaiminalawsuit)allegingthattheWorkoraContributionincorporatedwithintheWorkconstitutesdirectorcontributorypatentinfringement,thenanypatentlicensesgrantedtoYouunderthisLicenseforthatWorkshallterminateasofthedatesuchlitigationisfiled.

4. Redistribution.YoumayreproduceanddistributecopiesoftheWorkorDerivativeWorksthereofinanymedium,withorwithoutmodifications,andinSourceorObjectform,providedthatYoumeetthefollowingconditions:

a. YoumustgiveanyotherrecipientsoftheWorkorDerivativeWorksacopyofthisLicense;and

b. YoumustcauseanymodifiedfilestocarryprominentnoticesstatingthatYouchangedthefiles;and

c. Youmustretain,intheSourceformofanyDerivativeWorksthatYoudistribute,allcopyright,patent,trademark,andattributionnoticesfromtheSourceformoftheWork,excludingthosenoticesthatdonotpertaintoanypartoftheDerivativeWorks;and

d. IftheWorkincludesa"NOTICE"textfileaspartofitsdistribution,thenanyDerivativeWorksthatYoudistributemustincludeareadablecopyoftheattributionnoticescontainedwithinsuchNOTICEfile,excludingthosenoticesthatdonotpertaintoanypartoftheDerivativeWorks,inatleastoneofthefollowingplaces:withinaNOTICEtextfiledistributedaspartoftheDerivativeWorks;withintheSourceformordocumentation,ifprovidedalongwiththeDerivativeWorks;or,withinadisplaygeneratedbytheDerivativeWorks,ifandwhereversuchthird-partynoticesnormallyappear.ThecontentsoftheNOTICEfileareforinformationalpurposesonlyanddonotmodifytheLicense.YoumayaddYourownattributionnoticeswithinDerivativeWorksthatYoudistribute,alongsideorasanaddendumtotheNOTICEtextfromtheWork,providedthatsuchadditionalattributionnoticescannotbeconstruedasmodifyingtheLicense.

YoumayaddYourowncopyrightstatementtoYourmodificationsandmayprovideadditionalordifferentlicensetermsandconditionsforuse,reproduction,ordistributionofYourmodifications,orforanysuchDerivativeWorksasawhole,providedYouruse,reproduction,anddistributionoftheWorkotherwisecomplieswiththeconditionsstatedinthisLicense.

5. SubmissionofContributions.UnlessYouexplicitlystateotherwise,anyContributionintentionallysubmittedforinclusionintheWorkbyYoutotheLicensorshallbeunderthetermsandconditionsofthisLicense,withoutanyadditionaltermsorconditions.Notwithstandingtheabove,nothinghereinshall

supersedeormodifythetermsofanyseparatelicenseagreementyoumayhaveexecutedwithLicensorregardingsuchContributions.

6. Trademarks.ThisLicensedoesnotgrantpermissiontousethetradenames,trademarks,servicemarks,orproductnamesoftheLicensor,exceptasrequiredforreasonableandcustomaryuseindescribingtheoriginoftheWorkandreproducingthecontentoftheNOTICEfile.

7. DisclaimerofWarranty.Unlessrequiredbyapplicablelaworagreedtoinwriting,LicensorprovidestheWork(andeachContributorprovidesitsContributions)onan"ASIS"BASIS,WITHOUTWARRANTIESORCONDITIONSOFANYKIND,eitherexpressorimplied,including,withoutlimitation,anywarrantiesorconditionsofTITLE,NON-INFRINGEMENT,MERCHANTABILITY,orFITNESSFORAPARTICULARPURPOSE.YouaresolelyresponsiblefordeterminingtheappropriatenessofusingorredistributingtheWorkandassumeanyrisksassociatedwithYourexerciseofpermissionsunderthisLicense.

8. LimitationofLiability.Innoeventandundernolegaltheory,whetherintort(includingnegligence),contract,orotherwise,unlessrequiredbyapplicablelaw(suchasdeliberateandgrosslynegligentacts)oragreedtoinwriting,shallanyContributorbeliabletoYoufordamages,includinganydirect,indirect,special,incidental,orconsequentialdamagesofanycharacterarisingasaresultofthisLicenseoroutoftheuseorinabilitytousetheWork(includingbutnotlimitedtodamagesforlossofgoodwill,workstoppage,computerfailureormalfunction,oranyandallothercommercialdamagesorlosses),evenifsuchContributorhasbeenadvisedofthepossibilityofsuchdamages.

9. AcceptingWarrantyorAdditionalLiability.WhileredistributingtheWorkorDerivativeWorksthereof,Youmaychoosetooffer,andchargeafeefor,acceptanceofsupport,warranty,indemnity,

orotherliabilityobligationsand/orrightsconsistentwiththisLicense.However,inacceptingsuchobligations,YoumayactonlyonYourownbehalfandonYoursoleresponsibility,notonbehalfofanyotherContributor,andonlyifYouagreetoindemnify,defend,andholdeachContributorharmlessforanyliabilityincurredby,orclaimsassertedagainst,suchContributorbyreasonofyouracceptinganysuchwarrantyoradditionalliability.

ENDOFTERMSANDCONDITIONS

APPENDIX:HowtoapplytheApacheLicensetoyourwork.

ToapplytheApacheLicensetoyourwork,attachthefollowingboilerplatenotice,withthefieldsenclosedbybrackets"[]"replacedwithyourownidentifyinginformation.(Don'tincludethebrackets!)Thetextshouldbeenclosedintheappropriatecommentsyntaxforthefileformat.Wealsorecommendthatafileorclassnameanddescriptionofpurposebeincludedonthesame"printedpage"asthecopyrightnoticeforeasieridentificationwithinthird-partyarchives.

Copyright[yyyy][nameofcopyrightowner]

LicensedundertheApacheLicense,Version2.0(the"License");

youmaynotusethisfileexceptincompliancewiththeLicense.

YoumayobtainacopyoftheLicenseat

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

Unlessrequiredbyapplicablelaworagreedtoinwriting,software

distributedundertheLicenseisdistributedonan"ASIS"BASIS,

WITHOUTWARRANTIESORCONDITIONSOFANYKIND,eitherexpressorimplied.

SeetheLicenseforthespecificlanguagegoverningpermissionsand

limitationsundertheLicense.

||FAQ||

Thistranslationmaybeoutofdate.ChecktheEnglishversionforrecentchanges.

UnixUnix ApacheWindowsApache

Apache2.0Apache1.3 OpenSource libtool autoconf

(2.0.502.0.51)

ApacheApache

$lynxhttp://httpd.apache.org/download.cgi

$gzip-dhttpd-2_0_NN.tar.gz

$tarxvfhttpd-2_0_NN.tar

$./configure--prefix=PREFIX

$makeinstall

$viPREFIX/conf/httpd.conf

$PREFIX/bin/apachectlstart

NN PREFIX/usr/local/apache2

ApacheHTTPD

Apache:

50MB Apache10MB

ANSI-CANSI-C FreeSoftwareFoundation(FSF) GNUCcompiler(GCC)(2.7.2)GCC PATH make

HTTP xntpd NTPNTPcomp.protocols.time.ntp NTP

Perl5[] apxs dbmmanage PerlPerl 5(5.003)"configure" ApachePerl4Perl5) --with-perl()./configure

Apache ApacheHTTP

ApacheHTTP

ApacheHTTPDtarball tar:

$gzip-dhttpd-2_0_NN.tar.gz

$tarxvfhttpd-2_0_NN.tar

Apache autoconflibtool buildconf

./configure

Apache --prefixApache

Apache Apacheenable-module moduleenable-module=shared (DSO)disable-module Base

configure configure

/sw/pkg/apache

$CC="pgcc"CFLAGS="-O2"\

./configure--prefix=/sw/pkg/apache\

--enable-rewrite=shared\

--enable-speling=shared

configure Makefile

configure configure

Apache :

PentiumIII/Linux2.2 3

PREFIX( --prefix)

$makeinstall

PREFIX/conf/ ApacheHTTP

$viPREFIX/conf/httpd.conf

docs/manual/Apache http://httpd.apache.org/docs/2.0/

ApacheHTTP :

URLhttp://localhost/ PREFIX/htdocs/ :

$PREFIX/bin/apachectlstop

||FAQ||

(2.0.552.0.57) configure API (2.0.41

$./config.nice

$makeinstall

$PREFIX/bin/apachectlstop

||FAQ||

Apache

WindowsApache WindowsNT,2000,XPWindows9x,ME

Unix httpd

httpdapachectl

Apache

Listen80(1024) listen

httpd apachectlapachectl httpd HTTPD httpd

httpd httpd.conf

/usr/local/apache2/bin/apachectl-f

/usr/local/apache2/conf/httpd.conf

Apache ErrorLog

rootApache

ApacheFAQ

apachectl

apachectlSysVinit httpd init

||FAQ||

httpd apachectl

||FAQ||

Unix ApacheWindows9x,ME Apache

httpdapachectl

Apache httpd pidUSR1

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

httpd2 -khttpd apachectl apachectl

httpd :

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

ServerRootPidFile

:TERMapachectl-kstop

TERM stopkill

:USR1apachectl-kgraceful

USR1 graceful

USR1 (WINCH)

mod_status USR1

status

(httpd) httpd)

:HUPapachectl-krestart

HUP restart TERMkill

mod_status HUP

||FAQ||

Apache1.2b9 (:

ScoreBoardFile (HUP) "longlostchildcamehome!"(USR1) (HUP)

HTTP(KeepAlive)KeepAlive

||FAQ||

ApacheHTTP

mod_mime <IfDefine>

Include

TypesConfig

Apache Include

Apache11 "\"

apachectlconfigtest

mod_so <IfModule>

LoadModule

Apache LoadModule Apache

<Files>

Apache

||FAQ||

.htaccess

AccessFileName

AllowOverride

Apache .htaccess

.htaccess

.htaccess .htaccess

||FAQ||

URL .htaccess

mod_proxy

<Files>

<Proxy>

<IfDefine>httpd httpd-DClosedForNow:

Redirect/http://otherserver.example.com/

</IfDefine>

<IfModule> LoadModule

mod_mime_magic MimeMagicFiles

<IfModulemod_mime_magic.c>

MimeMagicFileconf/magic

</IfModule>

<IfDefine><IfModule>"!"

ApacheUnix/usr/local/apache2Windows "c:/Program

Files/ApacheGroup/Apache2"(ApacheWindows)UnixApache/usr/local/apache2/htdocs/dir/

<Directory><Files> <Directory>.htaccess /var/web/dir1

Options+Indexes

</Directory>

<Files> private.html

<Filesprivate.html>

Orderallow,deny

Denyfromall

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

<Filesprivate.html>

Orderallow,deny

Denyfromall

</Files>

</Directory>

<Location>/privateURLhttp://yoursite.example.com/private,http://yoursite.example.com/private123,http://yoursite.example.com/private/dir/file.html

/private

OrderAllow,Deny

Denyfromall

</Location>

<Location>URL mod_statusApacheserver-status

SetHandlerserver-status

</Location>

<Directory>,<Files>,<Location>Cshell"*""?"1"[

(regex) <DirectoryMatch>,<FilesMatch>,<LocationMatch>perl regex

OptionsIndexes

</Directory>

<FilesMatch\.(?i:gif|jpe?g|png)$>

Orderallow,deny

Denyfromall

</FilesMatch>

<Location>(URL)

Orderallow,deny

Denyfromall

</Location>

http://yoursite.example.com/dir/?http://yoursite.example.com/DIR/(Options)

<Location/>URL

<Proxy> <ProxyMatch>URL mod_proxycnn.com

<Proxyhttp://cnn.com/*>

Orderallow,deny

Denyfromall

</Proxy>

Context <Directory> <DirectoryMatch>,<Files>,<FilesMatch>,<Location>,<LocationMatch>,<Proxy>,<ProxyMatch>

AllowOverride<Directory>FollowSymLinks SymLinksIfOwnerMatch Options

<Directory> .htaccessOptions <Files> <FilesMatch>

1. <Directory>() .htaccess( .htaccess<Directory>)

2. <DirectoryMatch>( <Directory~>

3. <Files> <FilesMatch>

4. <Location> <LocationMatch>

<Directory><Directory/var/web/dir1> <Directory

/var/web/dir/subdir> <Directory>Include Include

(URL Alias<Location>/<LocationMatch>

A>B>C>D>E

</Location>

<Filesf.html>

</Files>

<VirtualHost*>

||FAQ||

</Directory>

</VirtualHost>

<DirectoryMatch"^.*b$">

</DirectoryMatch>

</Directory>

Orderdeny,allow

Allowfromall

</Location>

#Woops!This<Directory>sectionwillhavenoeffect

Orderallow,deny

Allowfromall

Denyfrombadguy.example.com

</Directory>

||FAQ||

ServerName

ServerAdmin

ServerSignature

ServerTokens

UseCanonicalName

ServerAdmin ServerTokensServerHTTP

ServerName UseCanonicalNameURL Apache

CoreDumpDirectory

DocumentRoot

ErrorLog

LockFile

PidFile

ScoreBoardFile

ServerRoot

Apache

||FAQ||

LimitRequestBody

LimitRequestFields

LimitRequestFieldsize

LimitRequestLine

RLimitCPU

RLimitMEM

RLimitNPROC

ThreadStackSize

LimitRequest*Apache

RLimit*Apache fork

ThreadStackSizeNetware

||FAQ||

Apache uid

ErrorLog

LogLevel

ErrorLog

(unix error_logWindowsOS/2Unix syslog

[WedOct1114:32:522000][error][client127.0.0.1]client

deniedbyserverconfiguration:

/export/home/live/ap/htdocs/test

tail-ferror_log

mod_log_config

mod_setenvif

CustomLog

LogFormat

SetEnvIf

Apachehttpdmod_log_config, mod_log_agent,TransferLog

Cprintf(1)

CommonLogFormat

LogFormat"%h%l%u%t\"%r\"%>s%b"common

CustomLoglogs/access_logcommon

common "\t"

CustomLog

CommonLogFormat(CLF)

127.0.0.1-frank[10/Oct/2000:13:55:36-0700]"GET

/apache_pb.gifHTTP/1.0"2002326

127.0.0.1(%h)

-(%l) IdentityCheck On

frank(%u)HTTP IDCGI401

[10/Oct/2000:13:55:36-0700](%t):

[day/month/year:hour:minute:secondzone]

day=2*digit

month=3*letter

year=4*digit

hour=2*digit

minute=2*digit

second=2*digit

zone=(`+'|`-')4*digit

%{format}t

"GET/apache_pb.gifHTTP/1.0"(\"%r\") HTTP/1.0 "%r"

200(%>s) (2))

2326(%b)

CombinedLogFormatCombinedLogFormat

LogFormat"%h%l%u%t\"%r\"%>s%b\"%{Referer}i\"\"%{User-

agent}i\""combined

CustomLoglog/access_logcombined

CommonLogFormat HTTP :

127.0.0.1-frank[10/Oct/2000:13:55:36-0700]"GET

/apache_pb.gifHTTP/1.0"2002326

"http://www.example.com/start.html""Mozilla/4.08[en](Win98;

I;Nav)"

"http://www.example.com/start.html"(\"%{Referer}i\")

"Referer"()HTTP )

"Mozilla/4.08[en](Win98;I;Nav)"(\"%{User-agent}i\")

User-AgentHTTP

CustomLogReferLog AgentLog

CustomLoglogs/referer_log"%{Referer}i->%U"

CustomLoglogs/agent_log"%{User-agent}i"

LogFormat

#Markrequestsfromtheloop-backinterface

SetEnvIfRemote_Addr"127\.0\.0\.1"dontlog

#Markrequestsfortherobots.txtfile

SetEnvIfRequest_URI"^/robots\.txt$"dontlog

#Logwhatremains

CustomLoglogs/access_logcommonenv=!dontlog

SetEnvIfAccept-Language"en"english

CustomLoglogs/english_logcommonenv=english

CustomLoglogs/non_english_logcommonenv=!english

10,000open open

mvaccess_logaccess_log.old

mverror_logerror_log.old

apachectlgraceful

sleep600

gzipaccess_log.olderror_log.old

Apachehttpd ( )

Apachehttpd ID

ApacheHTTP

CustomLog"|/usr/local/apache/bin/rotatelogs

/var/log/access_log86400"common

cronolog

>CustomLog ErrorLog <VirtualHost>

LogFormat"%v%l%u%t\"%r\"%>s%b"comonvhost

CustomLoglogs/access_logcomonvhost

||FAQ||

mod_cgi

mod_rewrite

PidFile

RewriteLog

RewriteLogLevel

ScriptLog

ScriptLogBuffer

ScriptLogLength

PIDApachehttpdID logs/httpd.pidPidFile ID

ScriptLog CGI

mod_rewrite RewriteLogLevel

||FAQ||

ApacheURL

mod_alias

mod_proxy

mod_rewrite

mod_userdir

mod_speling

mod_vhost_alias

AliasMatch

CheckSpelling

DocumentRoot

ErrorDocument

Options

ProxyPass

ProxyPassReverse

Redirect

RedirectMatch

RewriteCond

RewriteMatch

ScriptAlias

ScriptAliasMatch

UserDir

DocumentRoot

ApacheURL-Path(URL DocumentRoot

Apache IP

DocumentRoot

DocumentRootDocumentRoot SymLinksIfOwnerMatch

Alias/docs/var/web

URL http://www.example.com/docs/dir/file.html

/var/web/dir/file.html ScriptAlias CGI

AliasMatch ScriptAliasMatch

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

bin/$2

http://example.com/~user/cgi-bin/script.cgi/home/user/cgi-bin/script.cgi CGI

Unix user ~user/ mod_userdir

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

URL /home/user/public_html/file.html

/home/user/ /etc/passwd

Userdir /etc/passwd

"~"( %7e)

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

Apache DocumentRoot /foo/ /bar/

Redirectpermanent/foo/http://www.example.com/bar/

/foo/URL-Path www.example.com /bar/

Apache RedirectMatch

RedirectMatchpermanent^/$

http://www.example.com/startpage.html

RedirectMatchtemp.*

http://othersite.example.com/startpage.html

ApacheURL

/foo/ internal.example.com /bar/

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

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

ProxyPass ProxyPassReverseinternal.example.com

internal.example.cominternal.example.com

mod_rewrite () mod_rewrite

||FAQ||

FileNotFound

"FileNotFound" HTMLURLmod_speling() (:spelling)

Found"

mod_speling URLunixmod_speling

ApacheHTTP404(filenotfound)ErrorDocument

ApacheHTTPServerVersion2.0Apache>HTTPServer>Documentation>Version2.0>MiscellaneousDocumentation

SecurityTips

Somehintsandtipsonsecurityissuesinsettingupawebserver.Someofthesuggestionswillbegeneral,othersspecifictoApache.

KeepuptoDate

TheApacheHTTPServerhasagoodrecordforsecurityandadevelopercommunityhighlyconcernedaboutsecurityissues.Butitisinevitablethatsomeproblems--smallorlarge--willbediscoveredinsoftwareafteritisreleased.Forthisreason,itiscrucialtokeepawareofupdatestothesoftware.IfyouhaveobtainedyourversionoftheHTTPServerdirectlyfromApache,wehighlyrecommendyousubscribetotheApacheHTTPServerAnnouncementsListwhereyoucankeepinformedofnewreleasesandsecurityupdates.Similarservicesareavailablefrommostthird-partydistributorsofApachesoftware.

Ofcourse,mosttimesthatawebserveriscompromised,itisnotbecauseofproblemsintheHTTPServercode.Rather,itcomesfromproblemsinadd-oncode,CGIscripts,ortheunderlyingOperatingSystem.Youmustthereforestayawareofproblemsandupdateswithallthesoftwareonyoursystem.

PermissionsonServerRootDirectories

Intypicaloperation,Apacheisstartedbytherootuser,anditswitchestotheuserdefinedbytheUserdirectivetoservehits.Asisthecasewithanycommandthatrootexecutes,youmusttakecarethatitisprotectedfrommodificationbynon-rootusers.Notonlymustthefilesthemselvesbewriteableonlybyroot,butsomustthedirectories,andparentsofalldirectories.Forexample,ifyouchoosetoplaceServerRootin/usr/local/apachethenitissuggestedthatyoucreatethatdirectoryasroot,withcommandslikethese:

mkdir/usr/local/apache

cd/usr/local/apache

mkdirbinconflogs

chown0.binconflogs

chgrp0.binconflogs

chmod755.binconflogs

Itisassumedthat/,/usr,and/usr/localareonlymodifiablebyroot.Whenyouinstallthehttpdexecutable,youshouldensurethatitissimilarlyprotected:

cphttpd/usr/local/apache/bin

chown0/usr/local/apache/bin/httpd

chgrp0/usr/local/apache/bin/httpd

chmod511/usr/local/apache/bin/httpd

Youcancreateanhtdocssubdirectorywhichismodifiablebyotherusers--sincerootneverexecutesanyfilesoutofthere,andshouldn'tbecreatingfilesinthere.

Ifyouallownon-rootuserstomodifyanyfilesthatrooteitherexecutesorwritesonthenyouopenyoursystemtorootcompromises.Forexample,someonecouldreplacethehttpdbinarysothatthenexttimeyoustartit,itwillexecutesomearbitrarycode.Ifthelogsdirectoryiswriteable(byanon-rootuser),someonecouldreplacealogfilewithasymlinktosome

othersystemfile,andthenrootmightoverwritethatfilewitharbitrarydata.Ifthelogfilesthemselvesarewriteable(byanon-rootuser),thensomeonemaybeabletooverwritethelogitselfwithbogusdata.

ServerSideIncludes

ServerSideIncludes(SSI)presentaserveradministratorwithseveralpotentialsecurityrisks.

Thefirstriskistheincreasedloadontheserver.AllSSI-enabledfileshavetobeparsedbyApache,whetherornotthereareanySSIdirectivesincludedwithinthefiles.Whilethisloadincreaseisminor,inasharedserverenvironmentitcanbecomesignificant.

SSIfilesalsoposethesamerisksthatareassociatedwithCGIscriptsingeneral.Usingtheexeccmdelement,SSI-enabledfilescanexecuteanyCGIscriptorprogramunderthepermissionsoftheuserandgroupApacherunsas,asconfiguredinhttpd.conf.

TherearewaystoenhancethesecurityofSSIfileswhilestilltakingadvantageofthebenefitstheyprovide.

ToisolatethedamageawaywardSSIfilecancause,aserveradministratorcanenablesuexecasdescribedintheCGIinGeneralsection.

EnablingSSIforfileswith.htmlor.htmextensionscanbedangerous.Thisisespeciallytrueinashared,orhightraffic,serverenvironment.SSI-enabledfilesshouldhaveaseparateextension,suchastheconventional.shtml.Thishelpskeepserverloadataminimumandallowsforeasiermanagementofrisk.

AnothersolutionistodisabletheabilitytorunscriptsandprogramsfromSSIpages.TodothisreplaceIncludeswithIncludesNOEXECintheOptionsdirective.Notethatusersmaystilluse<--#includevirtual="..."-->toexecuteCGIscriptsifthesescriptsareindirectoriesdesignatedbyaScriptAliasdirective.

CGIinGeneral

Firstofall,youalwayshavetorememberthatyoumusttrustthewritersoftheCGIscripts/programsoryourabilitytospotpotentialsecurityholesinCGI,whethertheyweredeliberateoraccidental.CGIscriptscanrunessentiallyarbitrarycommandsonyoursystemwiththepermissionsofthewebserveruserandcanthereforebeextremelydangerousiftheyarenotcarefullychecked.

AlltheCGIscriptswillrunasthesameuser,sotheyhavepotentialtoconflict(accidentallyordeliberately)withotherscriptse.g.UserAhatesUserB,sohewritesascripttotrashUserB'sCGIdatabase.OneprogramwhichcanbeusedtoallowscriptstorunasdifferentusersissuEXECwhichisincludedwithApacheasof1.2andiscalledfromspecialhooksintheApacheservercode.AnotherpopularwayofdoingthisiswithCGIWrap.

NonScriptAliasedCGI

AllowinguserstoexecuteCGIscriptsinanydirectoryshouldonlybeconsideredif:

Youtrustyourusersnottowritescriptswhichwilldeliberatelyoraccidentallyexposeyoursystemtoanattack.Youconsidersecurityatyoursitetobesofeebleinotherareas,astomakeonemorepotentialholeirrelevant.Youhavenousers,andnobodyevervisitsyourserver.

ScriptAliasedCGI

LimitingCGItospecialdirectoriesgivestheadmincontroloverwhatgoesintothosedirectories.ThisisinevitablymoresecurethannonscriptaliasedCGI,butonlyifuserswithwriteaccesstothedirectoriesaretrustedortheadminiswillingtotesteachnewCGIscript/programforpotentialsecurityholes.

MostsiteschoosethisoptionoverthenonscriptaliasedCGIapproach.

Othersourcesofdynamiccontent

Embeddedscriptingoptionswhichrunaspartoftheserveritself,suchasmod_php,mod_perl,mod_tcl,andmod_python,runundertheidentityoftheserveritself(seetheUserdirective),andthereforescriptsexecutedbytheseenginespotentiallycanaccessanythingtheserverusercan.Somescriptingenginesmayproviderestrictions,butitisbettertobesafeandassumenot.

ProtectingSystemSettings

Torunareallytightship,you'llwanttostopusersfromsettingup.htaccessfileswhichcanoverridesecurityfeaturesyou'veconfigured.Here'sonewaytodoit.

Intheserverconfigurationfile,put

AllowOverrideNone

</Directory>

Thispreventstheuseof.htaccessfilesinalldirectoriesapartfromthosespecificallyenabled.

ProtectServerFilesbyDefault

OneaspectofApachewhichisoccasionallymisunderstoodisthefeatureofdefaultaccess.Thatis,unlessyoutakestepstochangeit,iftheservercanfinditswaytoafilethroughnormalURLmappingrules,itcanserveittoclients.

Forinstance,considerthefollowingexample:

#cd/;ln-s/public_html

Accessinghttp://localhost/~root/

Thiswouldallowclientstowalkthroughtheentirefilesystem.Toworkaroundthis,addthefollowingblocktoyourserver'sconfiguration:

OrderDeny,Allow

Denyfromall

</Directory>

Thiswillforbiddefaultaccesstofilesystemlocations.AddappropriateDirectoryblockstoallowaccessonlyinthoseareasyouwish.Forexample,

OrderDeny,Allow

Allowfromall

</Directory>

OrderDeny,Allow

Allowfromall

</Directory>

PayparticularattentiontotheinteractionsofLocationandDirectorydirectives;forinstance,evenif<Directory/>deniesaccess,a<Location/>directivemightoverturnit.

AlsobewaryofplayinggameswiththeUserDirdirective;setting

ittosomethinglike./wouldhavethesameeffect,forroot,asthefirstexampleabove.IfyouareusingApache1.3orabove,westronglyrecommendthatyouincludethefollowinglineinyourserverconfigurationfiles:

UserDirdisabledroot

WatchingYourLogs

Tokeepup-to-datewithwhatisactuallygoingonagainstyourserveryouhavetochecktheLogFiles.Eventhoughthelogfilesonlyreportswhathasalreadyhappened,theywillgiveyousomeunderstandingofwhatattacksisthrownagainsttheserverandallowyoutocheckifthenecessarylevelofsecurityispresent.

Acoupleofexamples:

grep-c"/jsp/source.jsp?/jsp//jsp/source.jsp??"access_log

grep"clientdenied"error_log|tail-n10

ThefirstexamplewilllistthenumberofattackstryingtoexploittheApacheTomcatSource.JSPMalformedRequestInformationDisclosureVulnerability,thesecondexamplewilllistthetenlastdeniedclients,forexample:

[ThuJul1117:18:392002][error][clientfoo.bar.com]client

deniedbyserverconfiguration:

/usr/local/apache/htdocs/.htpasswd

Asyoucansee,thelogfilesonlyreportwhatalreadyhashappened,soiftheclienthadbeenabletoaccessthe.htpasswdfileyouwouldhaveseensomethingsimilarto:

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

HTTP/1.1"

inyourAccessLog.Thismeansyouprobablycommentedoutthefollowinginyourserverconfigurationfile:

<Files~"^\.ht">

Orderallow,deny

Denyfromall

</Files>

LicensedundertheApacheLicense,Version2.0.

||FAQ||

ApacheHTTP SharedObject)(DSO) DSO

mod_so LoadModule

ApacheDSO mod_so.ccore.cDSO Apacheenable-module=shared DSODSODSO httpd.conf mod_so

Apache()DSOApache DSO :ApacheApache CDSODSO Apache

Apache2.0DSO :

1. Apache mod_foo.cDSO mod_foo.so:

$./configure--prefix=/path/to/install--enable-

foo=shared

$makeinstall

2. Apache mod_foo.cDSO mod_foo.so:

$./configure--add-

module=module_type:/path/to/3rdparty/mod_foo.c--enable-

foo=shared

$makeinstall

3. Apache:

$./configure--enable-so

$makeinstall

4. Apache mod_foo.c apxs Apache:

$cd/path/to/3rdparty

$apxs-cmod_foo.c

$apxs-i-a-nfoomod_foo.la

httpd.conf LoadModule

UnixOS (DSO)/

: ld.so

DSO DSO DSO libfoo.so libfoo.so.1.2

( /usr/lib) /usr/lib -R libfoo.so ()DSO

DSO (DSO))

DSO DSO (dlopen() DSO) DSO(

DSOAPI

DSO :DSO (

1998DSO :Perl5(XSDnaLoaderApache

ApacheDSO

||FAQ||

configureApache (SSL[mod_perl,PHP3] Apache

Apache DSO/ apxsApacheapxs-i apachectlrestart

Unix 20%(PIC)(positionindependentcode)

DSODSO () DSO DSOApache PIC(dlopen()

||FAQ||

ApacheHTTP/1.1

mod_negotiation

Accept-Language:fr

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

ApacheHTTP/1.1'server driven'Language,Accept-Charset,Accept-EncodingApache'transparent' RFC2295RFC2296'featurenegotiation'

URI (RFC2396)Apache HTTP01

Apache

variant

(*.var) variant'Multiviews'

type-map type-map (Apache MIMEtype-map)

AddHandlertype-map.var

variant) foo foo.var

URI:foo

URI:foo.en.html

Content-type:text/html

Content-language:en

URI:foo.fr.de.html

Content-type:text/html;charset=iso-8859-2

Content-language:fr,de

MultiViews "qs"

URI:foo

URI:foo.jpeg

Content-type:image/jpeg;qs=0.8

URI:foo.gif

Content-type:image/gif;qs=0.5

URI:foo.txt

Content-type:text/plain;qs=0.01

qs0.0001.000qs 0.000variant 'qs'variantqs1.0qs variantJPEG ASCII qs variant

mod_negotiation

MultiviewsMultiViews httpd.conf <Directory>

<Files>( AllowOverride) OptionsAll MultiViews

MultiViews: /some/dir/fooMultiViews /some/dir/foo

MultiViews DirectoryIndex

DirectoryIndexindex

index.html index.html3

MultiViews

Apachevariant

1. ApacheServer drivennegotiationApacheApache Apache

2. RFC2295 transparentcontentnegotiation variant 2296'remotevariantselectionalgorithm'

Accept Accept-Language

Accept-Encoding Accept-Charset

Apachevariant() Apache

1. Accept*variant4

2. variant variant variant

1. variant Acceptvariant

2. variant

3. () Accept-Language ()LanguagePriorityvariant

4. (text/html)

5. Accept-Charset varianttext/*

6. ISO-8859-1 variant

7. variant user-agentvariant variant

8. variant

9. variant

3. variant

4. variant ()representation") variantHTMLVary

Apache ApacheAccept

Accept: "image/*""*/*"

Accept:image/*,*/*

"image/"

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

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

q=0.01

Accept:q Apache"*/*"0.01q"type/*"0.02q ("*/*")

Apache2.0

Accept-Language

"MultipleChoices" LanguagePriority

Language en-GB enAcceptableVariants" LanguagePriorityen Apache "fr" "fr"

(CookieURL) mod_negotiationprefer-language

mod_negotiationvariant

ExampleSetEnvIfCookie"language=en"prefer-language=en

SetEnvIfCookie"language=fr"prefer-language=fr

TransparentContentNegotiation

Apachetransparentcontentnegotiation(RFC2295)variant {encoding..}variantvariantAccept-EncodingvariantvariantRVSA/1.0(RFC2296)RVSA/1.0variant5

MIME( html) (gz)

foo.en.htmlfoo.html.enfoo.en.html.gz

foo.html.en foofoo.html

foo.en.html foo foo.htmlfoo.html.en.gz foo

foo.htmlfoo.gzfoo.html.gz

foo.en.html.gz foo foo.htmlfoo.html.gzfoo.gz

foo.gz.html.en foofoo.gzfoo.gz.html

foo.html

foo.html.gz.en foofoo.htmlfoo.html.gz

foo.gz

( foo)

MIME( foo.html) ()

URLHTTP/1.0

HTTP/1.0 () HTTP/1.1

||FAQ||

AlanJ.Flavell Language2.0

||FAQ||

Apache

"500ServerError"

NCSAhttpd1.3/

1. NCSA

2. URL

3. URL

ApacheCGI :

REDIRECT_HTTP_ACCEPT=*/*,image/gif,image/x-xbitmap,

image/jpeg

REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2(X11;I;HP-UXA.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_STRINGURL(CGI CGI)

AllowOverride .htaccess ErrorDocument

ErrorDocument500/cgi-bin/crash-recover

ErrorDocument500"Sorry,ourscriptcrashed.Ohdear"

ErrorDocument500http://xxx/

ErrorDocument404/Lame_excuses/not_found.html

ErrorDocument401/Subscription/how_to_subscribe.html

ErrorDocument<3-digit-code><action>

action()

1. (")

2. URL

3. URL

||FAQ||

/SSI URLApache

HTTP_USER_AGENT REDIRECT_HTTP_USER_AGENT

Apache REDIRECT_URL

ErrorDocumentCGI ErrorDocumentPerl

print"Content-type:text/html\n";

printf"Status:%sConditionIntercepted\n",

$ENV{"REDIRECT_STATUS"};

404NotFound

||FAQ||

Apache

mpm_common

Listen

Apache IPApache

Listen Listen listen

808000

Listen80

Listen8000

Listen192.170.2.1:80

Listen192.170.2.5:8000

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

IPv6 APRIPv6

IPv6IPv4IPv6 ApacheIPv6 Apache

IPv4IPv6 IPv4IPv6configure Listen

Listen80

--enable-v4-mappedApache v4-mapped FreeBSD,NetBSD,OpenBSDApache

APR IPv4

Listen0.0.0.0:80

Listen192.170.2.1:80

IPv4IPv6 (IPv4)configure Listen

Listen[::]:80

Listen0.0.0.0:80

--disable-v4-mappedApache disable-v4-mapped FreeBSD,NetBSD,OpenBSD

||FAQ||

Listen Listenlisten<VirtualHost> <VirtualHost> <VirtualHost>listen

||FAQ||

ApacheHTTP

Apache2.0

Apache Apache1.3POSIX (perchild)

MPMApache MPM

MPM MPMApache

MPM./configure --with-mpm=NAMEMPM

MPM ./httpd-l

||FAQ||

OSMPMMPM

BeOS beos

Netware mpm_netware

OS/2 mpmt_os2

Unix prefork

Windows mpm_winnt

||FAQ||

Apache

ApacheHTTP

mod_env

mod_rewrite

mod_setenvif

mod_unique_id

BrowserMatch

BrowserMatchNoCase

PassEnv

RewriteRule

SetEnv

SetEnvIf

SetEnvIfNoCase

UnsetEnv

Apache

mod_setenvif referrerHTTPReferer )RewriteRule [E=...]

mod_unique_id

CGIApache CGISSI

CGICGI suexecCGI (:'_')

mod_access

mod_cgi

mod_ext_filter

mod_headers

mod_include

mod_log_config

mod_rewrite

CustomLog

ExtFilterDefine

Header

LogFormat

RewriteCond

RewriteRule

CGICGI CGIApache

SSImod_include INCLUDES server-parsed(SSI)

allowfromenv= denyfromenv=

LogFormat %e gif

Header

ExtFilterDefine mod_ext_filterenableenv=

URLRewriteCond %{ENV:...}mod_rewrite ENV:

ApachePassEnv

downgrade-1.0HTTP/1.0 HTTP/1.0

force-no-vary Vary

force-response-1.0HTTP/1.0 HTTP/1.0 HTTP/1.1

gzip-only-text/html1 text/html mod_deflate

no-gzipmod_deflate DEFLATE

nokeepaliveKeepAlive

prefer-languagemod_negotiation (en,ja,x-klingon) variant

redirect-carefully

suppress-error-charsetApache2.0.40

httpd.conf

#ThefollowingdirectivesmodifynormalHTTPresponsebehavior.

#ThefirstdirectivedisableskeepaliveforNetscape2.xandbrowsersthat

#spoofit.Thereareknownproblemswiththesebrowserimplementations.

#TheseconddirectiveisforMicrosoftInternetExplorer4.0b2

#whichhasabrokenHTTP/1.1implementationanddoesnotproperly

#supportkeepalivewhenitisusedon301or302(redirect)responses.

BrowserMatch"Mozilla/2"nokeepalive

BrowserMatch"MSIE4\.0b2;"nokeepalivedowngrade-1.0force-response-1.0

#ThefollowingdirectivedisablesHTTP/1.1responsestobrowserswhich

#areinviolationoftheHTTP/1.0specbynotbeingabletogroka

#basic1.1response.

BrowserMatch"RealPlayer4\.0"force-response-1.0

BrowserMatch"Java/1\.0"force-response-1.0

BrowserMatch"JDK/1\.0"force-response-1.0

SetEnvIfRequest_URI\.gifimage-request

SetEnvIfRequest_URI\.jpgimage-request

SetEnvIfRequest_URI\.pngimage-request

CustomLoglogs/access_logcommonenv=!image-request

inline

SetEnvIfReferer"^http://www.example.com/"local_referal

#AllowbrowsersthatdonotsendRefererinfo

SetEnvIfReferer"^$"local_referal

||FAQ||

OrderDeny,Allow

Denyfromall

Allowfromenv=local_referal

</Directory>

ApacheToday KeepingYourImagesfromAdorningOtherSites

||FAQ||

Apache

mod_actions

mod_asis

mod_cgi

mod_imap

mod_info

mod_mime

mod_negotiation

mod_status

Action

AddHandler

RemoveHandler

SetHandler

Apache

Apache1.1

Action

default-handler:default_handelr()send-as-is:HTTP (mod_asiscgi-script:CGI (mod_cgi)imap-file: (mod_imap)server-info: (mod_info)server-status: (mod_status)type-map:

CGI html footer.plCGI

Actionadd-footer/cgi-bin/footer.pl

AddHandleradd-footer.html

CGI ( PATH_TRANSLATED

HTTP send-as-isHTTPsend-as-is

SetHandlersend-as-is

</Directory>

||FAQ||

ApacheAPI

char*handler

(:"-")

||FAQ||

Apache

||FAQ||

mod_deflate

mod_ext_filter

mod_include

AddInputFilter

AddOutputFilter

RemoveInputFilter

RemoveOutputFilter

ExtFilterDefine

ExtFilterOptions

SetInputFilter

SetOutputFilter

Apache() SetOutputFilter,AddInputFilter,AddOutputFilter,RemoveInputFilter,RemoveOutputFilter

ApacheHTTP

INCLUDESmod_includeServer-SideInclude

DEFLATEmod_deflate

mod_ext_filter

||FAQ||

suEXEC

suEXECApacheWebID IDSSI web

CGI SSIsuEXEC

Apache

1 setuid setgidUNIX

3 suEXECsuEXEC ApachesuEXEC

4suEXECApache suEXECsuEXEC suEXEC

suEXEC

suEXECApacheweb setuid"wrapper"HTTPwrapper Apachewrapper

wrapper

1. wrapper?

wrapper

2. wrapper?

wrapper ApacheWebsuEXEC

3. wrapper ?

wrapper? (Apache)

4. CGI,SSI?

CGI,SSI'/' '..'?-with-suexec-docroot=DIR)

suEXEC rootCGI/SSI

8. IDID ?

ID CGI/SSIID

suEXEC'root'CGI/SSI

10. IDID ?

ID CGI/SSI

11. wrapper?

setuidsetgid

12. CGI/SSI (changedirectory)?

13. Apache?

suEXEC?(suEXEC)

15. CGI/SSI?

16. CGI/SSI

CGI/SSI

17. CGI/SSIsetuidsetgid ?

UID/GID

18. / /?

suEXEC ()

20. CGI/SSIexec?

suEXEC

suEXECwrapper

suEXEC

--enable-suexec

suEXECenable-suexec --with-suexec-xxxxx

--with-suexec-bin=PATH

suexec bin=/usr/sbin/suexec

--with-suexec-caller=UID

Apache suexec

--with-suexec-userdir=DIR

suEXEC ("*") UserdirUserDir

--with-suexec-docroot=DIR

ApachesuEXEC (UserDir"/htdocs" "--datadir=/home/apachewrapper"/home/apache/htdocs"

--with-suexec-uidmin=UID

suEXECUID 500100

--with-suexec-gidmin=GID

suEXECGID 100

--with-suexec-logfile=FILE

suEXEC ()logfiledir)

--with-suexec-safepath=PATH

CGIPATH "/usr/local/bin:/usr/bin:/bin"

suEXECwrapper--enable-suexecsuEXEC "make"(Apache) makeinstall"/usr/local/apache/sbin/suexec" rootwrapperID

suEXEC --with-suexec-callerconfiguresuEXEC

Userwww

Groupwebgroup

suexec"/usr/local/apache2/sbin/suexec"

chgrpwebgroup/usr/local/apache2/bin/suexec

chmod4750/usr/local/apache2/bin/suexec

Apache suEXEC

suEXEC

Apache --sbindir suexec"/usr/local/apache/sbin/suexec") suEXEC

[notice]suEXECmechanismenabled(wrapper:/path/to/suexec)

wrapper

suEXECApache ApachekillHUP

suEXEC suexec Apachekill

suEXEC

CGIsuEXEC SuexecUserGroup

:suEXECwrapper VirtualHost SuexecUserGroup

ID CGI <VirtualHost>

<VirtualHost> ID

:mod_userdir IDCGI--with-suexec-userdir

suEXEC

suEXECwrapper --with-suexec-logfile

||FAQ||

! Apache

wrapper suEXEC""

suEXEC

suEXEC Apache

suEXECPATH

suEXEC

ApachePerformanceTuning

Apache2.xisageneral-purposewebserver,designedtoprovideabalanceofflexibility,portability,andperformance.Althoughithasnotbeendesignedspecificallytosetbenchmarkrecords,Apache2.xiscapableofhighperformanceinmanyreal-worldsituations.

ComparedtoApache1.3,release2.xcontainsmanyadditionaloptimizationstoincreasethroughputandscalability.Mostoftheseimprovementsareenabledbydefault.However,therearecompile-timeandrun-timeconfigurationchoicesthatcansignificantlyaffectperformance.ThisdocumentdescribestheoptionsthataserveradministratorcanconfiguretotunetheperformanceofanApache2.xinstallation.SomeoftheseconfigurationoptionsenablethehttpdtobettertakeadvantageofthecapabilitiesofthehardwareandOS,whileothersallowtheadministratortotradefunctionalityforspeed.

HardwareandOperatingSystemIssues

ThesinglebiggesthardwareissueaffectingwebserverperformanceisRAM.Awebservershouldnevereverhavetoswap,asswappingincreasesthelatencyofeachrequestbeyondapointthatusersconsider"fastenough".Thiscausesuserstohitstopandreload,furtherincreasingtheload.Youcan,andshould,controltheMaxClientssettingsothatyourserverdoesnotspawnsomanychildrenitstartsswapping.Thisprocedurefordoingthisissimple:determinethesizeofyouraverageApacheprocess,bylookingatyourprocesslistviaatoolsuchastop,anddividethisintoyourtotalavailablememory,leavingsomeroomforotherprocesses.

Beyondthattherestismundane:getafastenoughCPU,afastenoughnetworkcard,andfastenoughdisks,where"fastenough"issomethingthatneedstobedeterminedbyexperimentation.

Operatingsystemchoiceislargelyamatteroflocalconcerns.Butsomeguidelinesthathaveprovengenerallyusefulare:

Runthelateststablereleaseandpatchleveloftheoperatingsystemthatyouchoose.ManyOSsuppliershaveintroducedsignificantperformanceimprovementstotheirTCPstacksandthreadlibrariesinrecentyears.

IfyourOSsupportsasendfile(2)systemcall,makesureyouinstallthereleaseand/orpatchesneededtoenableit.(WithLinux,forexample,thismeansusingLinux2.4orlater.ForearlyreleasesofSolaris8,youmayneedtoapplyapatch.)Onsystemswhereitisavailable,sendfileenablesApache2todeliverstaticcontentfasterandwithlowerCPUutilization.

Run-TimeConfigurationIssues

RelatedModules RelatedDirectivesmod_dir

mpm_common

mod_status

AllowOverride

DirectoryIndex

HostnameLookups

EnableMMAP

EnableSendfile

KeepAliveTimeout

MaxSpareServers

MinSpareServers

Options

StartServers

HostnameLookupsandotherDNSconsiderationsPriortoApache1.3,HostnameLookupsdefaultedtoOn.ThisaddslatencytoeveryrequestbecauseitrequiresaDNSlookuptocompletebeforetherequestisfinished.InApache1.3thissettingdefaultstoOff.Ifyouneedtohaveaddressesinyourlogfilesresolvedtohostnames,usethelogresolveprogramthatcomeswithApache,oroneofthenumerouslogreportingpackageswhichareavailable.

Itisrecommendedthatyoudothissortofpostprocessingofyourlogfilesonsomemachineotherthantheproductionwebservermachine,inorderthatthisactivitynotadverselyaffectserverperformance.

IfyouuseanyAllowfromdomainorDenyfromdomaindirectives(i.e.,usingahostname,oradomainname,ratherthananIPaddress)thenyouwillpayfortwoDNSlookups(areverse,followedbyaforwardlookuptomakesurethatthereverseisnotbeingspoofed).Forbestperformance,therefore,useIP

addresses,ratherthannames,whenusingthesedirectives,ifpossible.

Notethatit'spossibletoscopethedirectives,suchaswithina<Location/server-status>section.InthiscasetheDNSlookupsareonlyperformedonrequestsmatchingthecriteria.Here'sanexamplewhichdisableslookupsexceptfor.htmland.cgifiles:

HostnameLookupsoff

<Files~"\.(html|cgi)$">

HostnameLookupson

</Files>

Butevenstill,ifyoujustneedDNSnamesinsomeCGIsyoucouldconsiderdoingthegethostbynamecallinthespecificCGIsthatneedit.

FollowSymLinksandSymLinksIfOwnerMatchWhereverinyourURL-spaceyoudonothaveanOptionsFollowSymLinks,oryoudohaveanOptionsSymLinksIfOwnerMatchApachewillhavetoissueextrasystemcallstocheckuponsymlinks.Oneextracallperfilenamecomponent.Forexample,ifyouhad:

DocumentRoot/www/htdocs

OptionsSymLinksIfOwnerMatch

</Directory>

andarequestismadefortheURI/index.html.ThenApachewillperformlstat(2)on/www,/www/htdocs,and/www/htdocs/index.html.Theresultsoftheselstatsarenevercached,sotheywilloccuroneverysinglerequest.Ifyoureallydesirethesymlinkssecuritycheckingyoucandosomething

likethis:

OptionsFollowSymLinks

</Directory>

Options-FollowSymLinks+SymLinksIfOwnerMatch

</Directory>

ThisatleastavoidstheextrachecksfortheDocumentRootpath.Notethatyou'llneedtoaddsimilarsectionsifyouhaveanyAliasorRewriteRulepathsoutsideofyourdocumentroot.Forhighestperformance,andnosymlinkprotection,setFollowSymLinkseverywhere,andneversetSymLinksIfOwnerMatch.

AllowOverrideWhereverinyourURL-spaceyouallowoverrides(typically.htaccessfiles)Apachewillattempttoopen.htaccessforeachfilenamecomponent.Forexample,

AllowOverrideall

</Directory>

andarequestismadefortheURI/index.html.ThenApachewillattempttoopen/.htaccess,/www/.htaccess,and/www/htdocs/.htaccess.ThesolutionsaresimilartothepreviouscaseofOptionsFollowSymLinks.ForhighestperformanceuseAllowOverrideNoneeverywhereinyourfilesystem.

Negotiation

Ifatallpossible,avoidcontent-negotiationifyou'rereallyinterestedineverylastounceofperformance.Inpracticethebenefitsofnegotiationoutweightheperformancepenalties.There'sonecasewhereyoucanspeeduptheserver.Insteadofusingawildcardsuchas:

DirectoryIndexindex

Useacompletelistofoptions:

DirectoryIndexindex.cgiindex.plindex.shtmlindex.html

whereyoulistthemostcommonchoicefirst.

Alsonotethatexplicitlycreatingatype-mapfileprovidesbetterperformancethanusingMultiViews,asthenecessaryinformationcanbedeterminedbyreadingthissinglefile,ratherthanhavingtoscanthedirectoryforfiles.

Ifyoursiteneedscontentnegotiationconsiderusingtype-mapfiles,ratherthantheOptionsMultiViewsdirectivetoaccomplishthenegotiation.SeetheContentNegotiationdocumentationforafulldiscussionofthemethodsofnegotiation,andinstructionsforcreatingtype-mapfiles.

Memory-mappingInsituationswhereApache2.xneedstolookatthecontentsofafilebeingdelivered--forexample,whendoingserver-side-includeprocessing--itnormallymemory-mapsthefileiftheOSsupportssomeformofmmap(2).

Onsomeplatforms,thismemory-mappingimprovesperformance.However,therearecaseswherememory-mappingcanhurttheperformanceoreventhestabilityofthehttpd:

Onsomeoperatingsystems,mmapdoesnotscaleaswellasread(2)whenthenumberofCPUsincreases.OnmultiprocessorSolarisservers,forexample,Apache2.xsometimesdeliversserver-parsedfilesfasterwhenmmapisdisabled.

Ifyoumemory-mapafilelocatedonanNFS-mountedfilesystemandaprocessonanotherNFSclientmachinedeletesortruncatesthefile,yourprocessmaygetabuserrorthenexttimeittriestoaccessthemappedfilecontent.

Forinstallationswhereeitherofthesefactorsapplies,youshoulduseEnableMMAPofftodisablethememory-mappingofdeliveredfiles.(Note:Thisdirectivecanbeoverriddenonaper-directorybasis.)

SendfileInsituationswhereApache2.xcanignorethecontentsofthefiletobedelivered--forexample,whenservingstaticfilecontent--itnormallyusesthekernelsendfilesupportthefileiftheOSsupportsthesendfile(2)operation.

Onmostplatforms,usingsendfileimprovesperformancebyeliminatingseparatereadandsendmechanics.However,therearecaseswhereusingsendfilecanharmthestabilityofthehttpd:

Someplatformsmayhavebrokensendfilesupportthatthebuildsystemdidnotdetect,especiallyifthebinarieswerebuiltonanotherboxandmovedtosuchamachinewithbrokensendfilesupport.

WithanNFS-mountedfiles,thekernelmaybeunabletoreliablyservethenetworkfilethroughit'sowncache.

Forinstallationswhereeitherofthesefactorsapplies,youshould

useEnableSendfileofftodisablesendfiledeliveryoffilecontents.(Note:Thisdirectivecanbeoverriddenonaper-directorybasis.)

ProcessCreationPriortoApache1.3theMinSpareServers,MaxSpareServers,andStartServerssettingsallhaddrasticeffectsonbenchmarkresults.Inparticular,Apacherequireda"ramp-up"periodinordertoreachanumberofchildrensufficienttoservetheloadbeingapplied.AftertheinitialspawningofStartServerschildren,onlyonechildpersecondwouldbecreatedtosatisfytheMinSpareServerssetting.Soaserverbeingaccessedby100simultaneousclients,usingthedefaultStartServersof5wouldtakeontheorder95secondstospawnenoughchildrentohandletheload.Thisworksfineinpracticeonreal-lifeservers,becausetheyaren'trestartedfrequently.Butdoesreallypoorlyonbenchmarkswhichmightonlyrunfortenminutes.

Theone-per-secondrulewasimplementedinanefforttoavoidswampingthemachinewiththestartupofnewchildren.Ifthemachineisbusyspawningchildrenitcan'tservicerequests.ButithassuchadrasticeffectontheperceivedperformanceofApachethatithadtobereplaced.AsofApache1.3,thecodewillrelaxtheone-per-secondrule.Itwillspawnone,waitasecond,thenspawntwo,waitasecond,thenspawnfour,anditwillcontinueexponentiallyuntilitisspawning32childrenpersecond.ItwillstopwheneveritsatisfiestheMinSpareServerssetting.

Thisappearstoberesponsiveenoughthatit'salmostunnecessarytotwiddletheMinSpareServers,MaxSpareServersandStartServersknobs.Whenmorethan4childrenarespawnedpersecond,amessagewillbeemittedtotheErrorLog.Ifyouseealotoftheseerrorsthenconsider

tuningthesesettings.Usethemod_statusoutputasaguide.

RelatedtoprocesscreationisprocessdeathinducedbytheMaxRequestsPerChildsetting.Bydefaultthisis0,whichmeansthatthereisnolimittothenumberofrequestshandledperchild.Ifyourconfigurationcurrentlyhasthissettosomeverylownumber,suchas30,youmaywanttobumpthisupsignificantly.IfyouarerunningSunOSoranoldversionofSolaris,limitthisto10000orsobecauseofmemoryleaks.

Whenkeep-alivesareinuse,childrenwillbekeptbusydoingnothingwaitingformorerequestsonthealreadyopenconnection.ThedefaultKeepAliveTimeoutof15secondsattemptstominimizethiseffect.Thetradeoffhereisbetweennetworkbandwidthandserverresources.Innoeventshouldyouraisethisaboveabout60seconds,asmostofthebenefitsarelost.

Compile-TimeConfigurationIssues

ChoosinganMPMApache2.xsupportspluggableconcurrencymodels,calledMulti-ProcessingModules(MPMs).WhenbuildingApache,youmustchooseanMPMtouse.Thereareplatform-specificMPMsforsomeplatforms:beos,mpm_netware,mpmt_os2,andmpm_winnt.ForgeneralUnix-typesystems,thereareseveralMPMsfromwhichtochoose.ThechoiceofMPMcanaffectthespeedandscalabilityofthehttpd:

TheworkerMPMusesmultiplechildprocesseswithmanythreadseach.Eachthreadhandlesoneconnectionatatime.Workergenerallyisagoodchoiceforhigh-trafficserversbecauseithasasmallermemoryfootprintthanthepreforkMPM.ThepreforkMPMusesmultiplechildprocesseswithonethreadeach.Eachprocesshandlesoneconnectionatatime.Onmanysystems,preforkiscomparableinspeedtoworker,butitusesmorememory.Prefork'sthreadlessdesignhasadvantagesoverworkerinsomesituations:itcanbeusedwithnon-thread-safethird-partymodules,anditiseasiertodebugonplatformswithpoorthreaddebuggingsupport.

FormoreinformationontheseandotherMPMs,pleaseseetheMPMdocumentation.

ModulesSincememoryusageissuchanimportantconsiderationinperformance,youshouldattempttoeliminatemodulesthatyouarenotactuallyusing.IfyouhavebuiltthemodulesasDSOs,eliminatingmodulesisasimplematterofcommentingouttheassociatedLoadModuledirectiveforthatmodule.Thisallowsyoutoexperimentwithremovingmodules,andseeingifyoursitestill

functionsintheirabsense.

If,ontheotherhand,youhavemodulesstaticallylinkedintoyourApachebinary,youwillneedtorecompileApacheinordertoremoveunwantedmodules.

Anassociatedquestionthatariseshereis,ofcourse,whatmodulesyouneed,andwhichonesyoudon't.Theanswerherewill,ofcourse,varyfromonewebsitetoanother.However,theminimallistofmoduleswhichyoucangetbywithtendstoincludemod_mime,mod_dir,andmod_log_config.mod_log_configis,ofcourse,optional,asyoucanrunawebsitewithoutlogfiles.Thisis,however,notrecommended.

AtomicOperationsSomemodules,suchasmod_cacheandrecentdevelopmentbuildsoftheworkerMPM,useAPR'satomicAPI.ThisAPIprovidesatomicoperationsthatcanbeusedforlightweightthreadsynchronization.

Bydefault,APRimplementstheseoperationsusingthemostefficientmechanismavailableoneachtargetOS/CPUplatform.ManymodernCPUs,forexample,haveaninstructionthatdoesanatomiccompare-and-swap(CAS)operationinhardware.Onsomeplatforms,however,APRdefaultstoaslower,mutex-basedimplementationoftheatomicAPIinordertoensurecompatibilitywitholderCPUmodelsthatlacksuchinstructions.IfyouarebuildingApacheforoneoftheseplatforms,andyouplantorunonlyonnewerCPUs,youcanselectafasteratomicimplementationatbuildtimebyconfiguringApachewiththe--enable-nonportable-atomicsoption:

./buildconf

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

The--enable-nonportable-atomicsoptionisrelevantforthefollowingplatforms:

SolarisonSPARCBydefault,APRusesmutex-basedatomicsonSolaris/SPARC.Ifyouconfigurewith--enable-nonportable-atomics,however,APRgeneratescodethatusesaSPARCv8plusopcodeforfasthardwarecompare-and-swap.IfyouconfigureApachewiththisoption,theatomicoperationswillbemoreefficient(allowingforlowerCPUutilizationandhigherconcurrency),buttheresultingexecutablewillrunonlyonUltraSPARCchips.Linuxonx86Bydefault,APRusesmutex-basedatomicsonLinux.Ifyouconfigurewith--enable-nonportable-atomics,however,APRgeneratescodethatusesa486opcodeforfasthardwarecompare-and-swap.Thiswillresultinmoreefficientatomicoperations,buttheresultingexecutablewillrunonlyon486andlaterchips(andnoton386).

mod_statusandExtendedStatusOnIfyouincludemod_statusandyoualsosetExtendedStatusOnwhenbuildingandrunningApache,thenoneveryrequestApachewillperformtwocallstogettimeofday(2)(ortimes(2)dependingonyouroperatingsystem),and(pre-1.3)severalextracallstotime(2).Thisisalldonesothatthestatusreportcontainstimingindications.Forhighestperformance,setExtendedStatusoff(whichisthedefault).

acceptSerialization-multiplesockets

Warning:

Thissectionhasnotbeenfullyupdatedtotakeintoaccountchangesmadeinthe2.xversionoftheApacheHTTPServer.Someoftheinformationmaystillberelevant,butpleaseuseitwithcare.

ThisdiscussesashortcomingintheUnixsocketAPI.SupposeyourwebserverusesmultipleListenstatementstolistenoneithermultipleportsormultipleaddresses.InordertotesteachsockettoseeifaconnectionisreadyApacheusesselect(2).select(2)indicatesthatasockethaszerooratleastoneconnectionwaitingonit.Apache'smodelincludesmultiplechildren,andalltheidleonestestfornewconnectionsatthesametime.Anaiveimplementationlookssomethinglikethis(theseexamplesdonotmatchthecode,they'recontrivedforpedagogicalpurposes):

for(;;){

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

if(FD_ISSET(i,&accept_fds)){

new_connection=accept(i,NULL,NULL);

if(new_connection!=-1)break;

processthenew_connection;

Butthisnaiveimplementationhasaseriousstarvationproblem.

Recallthatmultiplechildrenexecutethisloopatthesametime,andsomultiplechildrenwillblockatselectwhentheyareinbetweenrequests.Allthoseblockedchildrenwillawakenandreturnfromselectwhenasinglerequestappearsonanysocket(thenumberofchildrenwhichawakenvariesdependingontheoperatingsystemandtimingissues).Theywillallthenfalldownintotheloopandtrytoaccepttheconnection.Butonlyonewillsucceed(assumingthere'sstillonlyoneconnectionready),therestwillbeblockedinaccept.Thiseffectivelylocksthosechildrenintoservingrequestsfromthatonesocketandnoothersockets,andthey'llbestuckthereuntilenoughnewrequestsappearonthatsockettowakethemallup.ThisstarvationproblemwasfirstdocumentedinPR#467.Thereareatleasttwosolutions.

Onesolutionistomakethesocketsnon-blocking.Inthiscasetheacceptwon'tblockthechildren,andtheywillbeallowedtocontinueimmediately.ButthiswastesCPUtime.Supposeyouhavetenidlechildreninselect,andoneconnectionarrives.Thennineofthosechildrenwillwakeup,trytoaccepttheconnection,fail,andloopbackintoselect,accomplishingnothing.Meanwhilenoneofthosechildrenareservicingrequeststhatoccurredonothersocketsuntiltheygetbackuptotheselectagain.OverallthissolutiondoesnotseemveryfruitfulunlessyouhaveasmanyidleCPUs(inamultiprocessorbox)asyouhaveidlechildren,notaverylikelysituation.

Anothersolution,theoneusedbyApache,istoserializeentryintotheinnerloop.Thelooplookslikethis(differenceshighlighted):

for(;;){

accept_mutex_on();

for(;;){

fd_setaccept_fds;

FD_ZERO(&accept_fds);

FD_SET(i,&accept_fds);

rc=select(last_socket+1,&accept_fds,NULL,NULL,

NULL);

if(rc<1)continue;

new_connection=-1;

if(FD_ISSET(i,&accept_fds)){

new_connection=accept(i,NULL,NULL);

if(new_connection!=-1)break;

accept_mutex_off();

processthenew_connection;

Thefunctionsaccept_mutex_onandaccept_mutex_offimplementamutualexclusionsemaphore.Onlyonechildcanhavethemutexatanytime.Thereareseveralchoicesforimplementingthesemutexes.Thechoiceisdefinedinsrc/conf.h(pre-1.3)orsrc/include/ap_config.h(1.3orlater).Somearchitecturesdonothaveanylockingchoicemade,onthesearchitecturesitisunsafetousemultipleListendirectives.

ThedirectiveAcceptMutexcanbeusedtochangetheselectedmuteximplementationatrun-time.

AcceptMutexflock

Thismethodusestheflock(2)systemcalltolockalockfile(locatedbytheLockFiledirective).

AcceptMutexfcntl

Thismethodusesthefcntl(2)systemcalltolockalockfile(locatedbytheLockFiledirective).

AcceptMutexsysvsem

(1.3orlater)ThismethodusesSysV-stylesemaphoresto

implementthemutex.UnfortunatelySysV-stylesemaphoreshavesomebadside-effects.Oneisthatit'spossibleApachewilldiewithoutcleaningupthesemaphore(seetheipcs(8)manpage).TheotheristhatthesemaphoreAPIallowsforadenialofserviceattackbyanyCGIsrunningunderthesameuidasthewebserver(i.e.,allCGIs,unlessyouusesomethinglikesuexecorcgiwrapper).ForthesereasonsthismethodisnotusedonanyarchitectureexceptIRIX(wheretheprevioustwoareprohibitivelyexpensiveonmostIRIXboxes).

AcceptMutexpthread

(1.3orlater)ThismethodusesPOSIXmutexesandshouldworkonanyarchitectureimplementingthefullPOSIXthreadsspecification,howeverappearstoonlyworkonSolaris(2.5orlater),andeventhenonlyincertainconfigurations.Ifyouexperimentwiththisyoushouldwatchoutforyourserverhangingandnotresponding.Staticcontentonlyserversmayworkjustfine.

AcceptMutexposixsem

(2.0orlater)ThismethodusesPOSIXsemaphores.Thesemaphoreownershipisnotrecoveredifathreadintheprocessholdingthemutexsegfaults,resultinginahangofthewebserver.

Ifyoursystemhasanothermethodofserializationwhichisn'tintheabovelistthenitmaybeworthwhileaddingcodeforittoAPR.

Anothersolutionthathasbeenconsideredbutneverimplementedistopartiallyserializetheloop--thatis,letinacertainnumberofprocesses.Thiswouldonlybeofinterestonmultiprocessorboxeswhereit'spossiblemultiplechildrencouldrunsimultaneously,andtheserializationactuallydoesn'ttakeadvantageofthefullbandwidth.Thisisapossibleareaoffutureinvestigation,butpriorityremainslowbecausehighlyparallelwebserversarenot

thenorm.

IdeallyyoushouldrunserverswithoutmultipleListenstatementsifyouwantthehighestperformance.Butreadon.

acceptSerialization-singlesocketTheaboveisfineanddandyformultiplesocketservers,butwhataboutsinglesocketservers?Intheorytheyshouldn'texperienceanyofthesesameproblemsbecauseallchildrencanjustblockinaccept(2)untilaconnectionarrives,andnostarvationresults.Inpracticethishidesalmostthesame"spinning"behaviourdiscussedaboveinthenon-blockingsolution.ThewaythatmostTCPstacksareimplemented,thekernelactuallywakesupallprocessesblockedinacceptwhenasingleconnectionarrives.Oneofthoseprocessesgetstheconnectionandreturnstouser-space,therestspininthekernelandgobacktosleepwhentheydiscoverthere'snoconnectionforthem.Thisspinningishiddenfromtheuser-landcode,butit'stherenonetheless.Thiscanresultinthesameload-spikingwastefulbehaviourthatanon-blockingsolutiontothemultiplesocketscasecan.

Forthisreasonwehavefoundthatmanyarchitecturesbehavemore"nicely"ifweserializeeventhesinglesocketcase.Sothisisactuallythedefaultinalmostallcases.CrudeexperimentsunderLinux(2.0.30onadualPentiumpro166w/128MbRAM)haveshownthattheserializationofthesinglesocketcasecauseslessthana3%decreaseinrequestspersecondoverunserializedsingle-socket.Butunserializedsingle-socketshowedanextra100mslatencyoneachrequest.Thislatencyisprobablyawashonlonghaullines,andonlyanissueonLANs.IfyouwanttooverridethesinglesocketserializationyoucandefineSINGLE_LISTEN_UNSERIALIZED_ACCEPTandthensingle-socketserverswillnotserializeatall.

LingeringCloseAsdiscussedindraft-ietf-http-connection-00.txtsection8,inorderforanHTTPservertoreliablyimplementtheprotocolitneedstoshutdowneachdirectionofthecommunicationindependently(recallthataTCPconnectionisbi-directional,eachhalfisindependentoftheother).Thisfactisoftenoverlookedbyotherservers,butiscorrectlyimplementedinApacheasof1.2.

WhenthisfeaturewasaddedtoApacheitcausedaflurryofproblemsonvariousversionsofUnixbecauseofashortsightedness.TheTCPspecificationdoesnotstatethattheFIN_WAIT_2statehasatimeout,butitdoesn'tprohibitit.Onsystemswithoutthetimeout,Apache1.2inducesmanysocketsstuckforeverintheFIN_WAIT_2state.InmanycasesthiscanbeavoidedbysimplyupgradingtothelatestTCP/IPpatchessuppliedbythevendor.Incaseswherethevendorhasneverreleasedpatches(i.e.,SunOS4--althoughfolkswithasourcelicensecanpatchitthemselves)wehavedecidedtodisablethisfeature.

Therearetwowaysofaccomplishingthis.OneisthesocketoptionSO_LINGER.Butasfatewouldhaveit,thishasneverbeenimplementedproperlyinmostTCP/IPstacks.Evenonthosestackswithaproperimplementation(i.e.,Linux2.0.31)thismethodprovestobemoreexpensive(cputime)thanthenextsolution.

Forthemostpart,Apacheimplementsthisinafunctioncalledlingering_close(inhttp_main.c).Thefunctionlooksroughlylikethis:

voidlingering_close(ints)

charjunk_buffer[2048];

/*shutdownthesendingside*/

shutdown(s,1);

signal(SIGALRM,lingering_death);

alarm(30);

for(;;){

select(sforreading,2secondtimeout);

if(error)break;

if(sisreadyforreading){

if(read(s,junk_buffer,sizeof(junk_buffer))<=0){

break;

/*justtossawaywhateverishere*/

close(s);

Thisnaturallyaddssomeexpenseattheendofaconnection,butitisrequiredforareliableimplementation.AsHTTP/1.1becomesmoreprevalent,andallconnectionsarepersistent,thisexpensewillbeamortizedovermorerequests.IfyouwanttoplaywithfireanddisablethisfeatureyoucandefineNO_LINGCLOSE,butthisisnotrecommendedatall.Inparticular,asHTTP/1.1pipelinedpersistentconnectionscomeintouselingering_closeisanabsolutenecessity(andpipelinedconnectionsarefaster,soyouwanttosupportthem).

ScoreboardFileApache'sparentandchildrencommunicatewitheachotherthroughsomethingcalledthescoreboard.Ideallythisshouldbeimplementedinsharedmemory.Forthoseoperatingsystemsthatweeitherhaveaccessto,orhavebeengivendetailedportsfor,ittypicallyisimplementedusingsharedmemory.Therestdefaulttousinganon-diskfile.Theon-diskfileisnotonlyslow,butitisunreliable(andlessfeatured).Perusethesrc/main/conf.hfileforyourarchitectureandlookforeitherUSE_MMAP_SCOREBOARDorUSE_SHMGET_SCOREBOARD.Definingoneofthosetwo(aswell

astheircompanionsHAVE_MMAPandHAVE_SHMGETrespectively)enablesthesuppliedsharedmemorycode.Ifyoursystemhasanothertypeofsharedmemory,editthefilesrc/main/http_main.candaddthehooksnecessarytouseitinApache.(Sendusbackapatchtooplease.)

Historicalnote:TheLinuxportofApachedidn'tstarttousesharedmemoryuntilversion1.2ofApache.ThisoversightresultedinreallypoorandunreliablebehaviourofearlierversionsofApacheonLinux.

DYNAMIC_MODULE_LIMITIfyouhavenointentionofusingdynamicallyloadedmodules(youprobablydon'tifyou'rereadingthisandtuningyourserverforeverylastounceofperformance)thenyoushouldadd-DDYNAMIC_MODULE_LIMIT=0whenbuildingyourserver.ThiswillsaveRAMthat'sallocatedonlyforsupportingdynamicallyloadedmodules.

Appendix:DetailedAnalysisofaTrace

HereisasystemcalltraceofApache2.0.38withtheworkerMPMonSolaris8.Thistracewascollectedusing:

truss-l-phttpd_child_pid.

The-loptiontellstrusstologtheIDoftheLWP(lightweightprocess--Solaris'sformofkernel-levelthread)thatinvokeseachsystemcall.

Othersystemsmayhavedifferentsystemcalltracingutilitiessuchasstrace,ktrace,orpar.Theyallproducesimilaroutput.

Inthistrace,aclienthasrequesteda10KBstaticfilefromthehttpd.Tracesofnon-staticrequestsorrequestswithcontentnegotiationlookwildlydifferent(andquiteuglyinsomecases).

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

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

Inthistrace,thelistenerthreadisrunningwithinLWP#67.

Notethelackofaccept(2)serialization.Onthisparticularplatform,theworkerMPMusesanunserializedacceptbydefaultunlessitislisteningonmultipleports.

/65:lwp_park(0x00000000,0)=0

/67:lwp_unpark(65,1)=0

Uponacceptingtheconnection,thelistenerthreadwakesupaworkerthreadtodotherequestprocessing.Inthistrace,theworkerthreadthathandlestherequestismappedtoLWP#65.

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

Inordertoimplementvirtualhosts,Apacheneedstoknowthelocalsocketaddressusedtoaccepttheconnection.Itispossibletoeliminatethiscallinmanysituations(suchaswhentherearenovirtualhosts,orwhenListendirectivesareusedwhichdonothavewildcardaddresses).Butnoefforthasyetbeenmadetodotheseoptimizations.

/65:brk(0x002170E8)=0

/65:brk(0x002190E8)=0

Thebrk(2)callsallocatememoryfromtheheap.Itisraretoseetheseinasystemcalltrace,becausethehttpdusescustommemoryallocators(apr_poolandapr_bucket_alloc)formostrequestprocessing.Inthistrace,thehttpdhasjustbeenstarted,soitmustcallmalloc(3)togettheblocksofrawmemorywithwhichtocreatethecustommemoryallocators.

/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,theworkerthreadputstheconnectiontotheclient(filedescriptor9)innon-blockingmode.Thesetsockopt(2)andgetsockopt(2)callsareaside-effectofhowSolaris'slibchandlesfcntl(2)onsockets.

/65:read(9,"GET/10k.htm"..,8000)=97

Theworkerthreadreadstherequestfromtheclient.

/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

ThishttpdhasbeenconfiguredwithOptionsFollowSymLinksandAllowOverrideNone.Thusitdoesn'tneedtolstat(2)eachdirectoryinthepathleadinguptotherequestedfile,norcheckfor.htaccessfiles.Itsimplycallsstat(2)toverifythatthefile:1)exists,and2)isaregularfile,notadirectory.

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

Inthisexample,thehttpdisabletosendtheHTTPresponseheaderandtherequestedfilewithasinglesendfilev(2)systemcall.Sendfilesemanticsvaryamongoperatingsystems.Onsomeothersystems,itisnecessarytodoawrite(2)orwritev(2)calltosendtheheadersbeforecallingsendfile(2).

/65:write(4,"127.0.0.1-"..,78)=78

Thiswrite(2)callrecordstherequestintheaccesslog.Notethatonethingmissingfromthistraceisatime(2)call.UnlikeApache1.3,Apache2.xusesgettimeofday(3)tolookupthetime.Onsomeoperatingsystems,likeLinuxorSolaris,gettimeofdayhasanoptimizedimplementationthatdoesn'trequireasmuchoverheadasatypicalsystemcall.

/65:shutdown(9,1,1)=0

/65:poll(0xFAF7B980,1,2000)=1

/65:read(9,0xFAF7BC20,512)=0

/65:close(9)=0

Theworkerthreaddoesalingeringcloseoftheconnection.

/65:close(10)=0

/65:lwp_park(0x00000000,0)(sleeping...)

Finallytheworkerthreadclosesthefilethatithasjustdelivered

andblocksuntilthelistenerassignsitanotherconnection.

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

Meanwhile,thelistenerthreadisabletoacceptanotherconnectionassoonasithasdispatchedthisconnectiontoaworkerthread(subjecttosomeflow-controllogicintheworkerMPMthatthrottlesthelistenerifalltheavailableworkersarebusy).Thoughitisn'tapparentfromthistrace,thenextaccept(2)can(andusuallydoes,underhighloadconditions)occurinparallelwiththeworkerthread'shandlingofthejust-acceptedconnection.

URLRewritingGuide

OriginallywrittenbyRalfS.Engelschall<rse@apache.org>December1997

Thisdocumentsupplementsthemod_rewritereferencedocumentation.ItdescribeshowonecanuseApache'smod_rewritetosolvetypicalURL-basedproblemswithwhichwebmastersarecommononyconfronted.WegivedetaileddescriptionsonhowtosolveeachproblembyconfiguringURLrewritingrulesets.

Introductiontomod_rewrite

TheApachemodulemod_rewriteisakillerone,i.e.itisareallysophisticatedmodulewhichprovidesapowerfulwaytodoURLmanipulations.WithityoucandonearlyalltypesofURLmanipulationsyoueverdreamedabout.Thepriceyouhavetopayistoacceptcomplexity,becausemod_rewrite'smajordrawbackisthatitisnoteasytounderstandanduseforthebeginner.AndevenApacheexpertssometimesdiscovernewaspectswheremod_rewritecanhelp.

Inotherwords:Withmod_rewriteyoueithershootyourselfinthefootthefirsttimeandneveruseitagainorloveitfortherestofyourlifebecauseofitspower.Thispapertriestogiveyouafewinitialsuccesseventstoavoidthefirstcasebypresentingalreadyinventedsolutionstoyou.

PracticalSolutions

HerecomealotofpracticalsolutionsI'veeitherinventedmyselforcollectedfromotherpeople'ssolutionsinthepast.FeelfreetolearntheblackmagicofURLrewritingfromtheseexamples.

ATTENTION:Dependingonyourserver-configurationitcanbenecessarytoslightlychangetheexamplesforyoursituation,e.g.addingthe[PT]flagwhenadditionallyusingmod_aliasandmod_userdir,etc.Orrewritingarulesettofitin.htaccesscontextinsteadofper-servercontext.Alwaystrytounderstandwhataparticularrulesetreallydoesbeforeyouuseit.Itavoidproblems.

URLLayout

CanonicalURLsDescription:

OnsomewebserverstherearemorethanoneURLforaresource.UsuallytherearecanonicalURLs(whichshouldbeactuallyusedanddistributed)andthosewhicharejustshortcuts,internalones,etc.IndependentofwhichURLtheusersuppliedwiththerequestheshouldfinallyseethecanonicaloneonly.

Solution:WedoanexternalHTTPredirectforallnon-canonicalURLstofixtheminthelocationviewoftheBrowserandforallsubsequentrequests.Intheexamplerulesetbelowwereplace/~userbythecanonical/u/userandfixamissingtrailingslashfor/u/user.

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

RewriteRule^/([uge])/([^/]+)$/$1/$2/[R]

CanonicalHostnamesDescription:

Thegoalofthisruleistoforcetheuseofaparticularhostname,inpreferencetootherhostnameswhichmaybeusedtoreachthesamesite.Forexample,ifyouwishtoforcetheuseofwww.example.cominsteadofexample.com,youmightuseavariantofthefollowingrecipe.

Solution:

#Forsitesrunningonaportotherthan80

RewriteCond%{HTTP_HOST}!^www\.example\.com[NC]

RewriteCond%{HTTP_HOST}!^$

RewriteCond%{SERVER_PORT}!^80$

RewriteRule^/(.*)http://www.example.com:%{SERVER_PORT}/$1[L,R]

#Andforasiterunningonport80

RewriteCond%{HTTP_HOST}!^www\.example\.com[NC]

RewriteRule^/(.*)http://www.example.com/$1[L,R]

MovedDocumentRootDescription:

UsuallytheDocumentRootofthewebserverdirectlyrelatestotheURL"/".Butoftenthisdataisnotreallyoftop-levelpriority,itisperhapsjustoneentityofalotofdatapools.ForinstanceatourIntranetsitesthereare/e/www/(thehomepageforWWW),/e/sww/(thehomepagefortheIntranet)etc.NowbecausethedataoftheDocumentRootstaysat/e/www/wehadtomakesurethatallinlinedimagesandotherstuffinsidethisdatapoolworkforsubsequentrequests.

Solution:WeredirecttheURL/to/e/www/:

RewriteEngineon

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

NotethatthiscanalsobehandledusingtheRedirectMatchdirective:

RedirectMatch^/$http://example.com/e/www/

TrailingSlashProblem

Description:EverywebmastercansingasongabouttheproblemofthetrailingslashonURLsreferencingdirectories.Iftheyaremissing,theserverdumpsanerror,becauseifyousay/~quux/fooinsteadof/~quux/foo/thentheserversearchesforafilenamedfoo.Andbecausethisfileisadirectoryitcomplains.Actuallyittriestofixititselfinmostofthecases,butsometimesthismechanismneedtobeemulatedbyyou.ForinstanceafteryouhavedonealotofcomplicatedURLrewritingstoCGIscriptsetc.

Solution:Thesolutiontothissubtleproblemistolettheserveraddthetrailingslashautomatically.Todothiscorrectlywehavetouseanexternalredirect,sothebrowsercorrectlyrequestssubsequentimagesetc.Ifweonlydidainternalrewrite,thiswouldonlyworkforthedirectorypage,butwouldgowrongwhenanyimagesareincludedintothispagewithrelativeURLs,becausethebrowserwouldrequestanin-linedobject.Forinstance,arequestforimage.gifin/~quux/foo/index.htmlwouldbecome/~quux/image.gifwithouttheexternalredirect!

So,todothistrickwewrite:

RewriteEngineon

RewriteBase/~quux/

RewriteRule^foo$foo/[R]

Thecrazyandlazycanevendothefollowinginthetop-level.htaccessfileoftheirhomedir.Butnoticethatthiscreatessomeprocessingoverhead.

RewriteEngineon

RewriteBase/~quux/

RewriteCond%{REQUEST_FILENAME}-d

RewriteRule^(.+[^/])$$1/[R]

WebclusterthroughHomogeneousURLLayoutDescription:

WewanttocreateahomogeneousandconsistentURLlayoutoverallWWWserversonaIntranetwebcluster,i.e.allURLs(perdefinitionserverlocalandthusserverdependent!)becomeactuallyserverindependent!WhatwewantistogivetheWWWnamespaceaconsistentserver-independentlayout:noURLshouldhavetoincludeanyphysicallycorrecttargetserver.Theclusteritselfshoulddriveusautomaticallytothephysicaltargethost.

Solution:First,theknowledgeofthetargetserverscomefrom(distributed)externalmapswhichcontaininformationwhereourusers,groupsandentitiesstay.Thehavetheform

user1server_of_user1

Weputthemintofilesmap.xxx-to-host.SecondweneedtoinstructallserverstoredirectURLsoftheforms

/u/user/anypath

/g/group/anypath

/e/entity/anypath

http://physical-host/u/user/anypath

http://physical-host/g/group/anypath

http://physical-host/e/entity/anypath

whentheURLisnotlocallyvalidtoaserver.Thefollowingrulesetdoesthisforusbythehelpofthemapfiles(assumingthatserver0isadefaultserverwhichwillbeusedifauserhasnoentryinthemap):

RewriteEngineon

RewriteMapuser-to-hosttxt:/path/to/map.user-to-host

RewriteMapgroup-to-hosttxt:/path/to/map.group-to-host

RewriteMapentity-to-hosttxt:/path/to/map.entity-to-host

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

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

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

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

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

MoveHomedirstoDifferentWebserverDescription:

Manywebmastershaveaskedforasolutiontothefollowingsituation:Theywantedtoredirectjustallhomedirsonawebservertoanotherwebserver.Theyusuallyneedsuchthingswhenestablishinganewerwebserverwhichwillreplacetheoldoneovertime.

Solution:Thesolutionistrivialwithmod_rewrite.Ontheoldwebserverwejustredirectall/~user/anypathURLsto

http://newserver/~user/anypath.

RewriteEngineon

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

StructuredHomedirsDescription:

Somesiteswiththousandsofusersusuallyuseastructuredhomedirlayout,i.e.eachhomedirisinasubdirectorywhichbeginsforinstancewiththefirstcharacteroftheusername.So,/~foo/anypathis/home/f/foo/.www/anypathwhile/~bar/anypathis/home/b/bar/.www/anypath.

Solution:WeusethefollowingrulesettoexpandthetildeURLsintoexactlytheabovelayout.

RewriteEngineon

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

FilesystemReorganizationDescription:

Thisreallyisahardcoreexample:akillerapplicationwhichheavilyusesper-directoryRewriteRulestogetasmoothlookandfeelontheWebwhileitsdatastructureisnevertouchedoradjusted.Background:net.swismyarchiveoffreelyavailableUnixsoftwarepackages,whichIstartedtocollectin1992.Itisbothmyhobbyandjobtotothis,becausewhileI'mstudyingcomputerscienceIhavealsoworkedformanyyearsasasystemandnetworkadministratorinmysparetime.EveryweekIneedsomesortofsoftwaresoIcreatedadeephierarchyofdirectorieswhereIstoredthe

packages:

drwxrwxr-x2netswusers512Aug318:39Audio/

drwxrwxr-x2netswusers512Jul914:37Benchmark/

drwxrwxr-x12netswusers512Jul900:34Crypto/

drwxrwxr-x5netswusers512Jul900:41Database/

drwxrwxr-x4netswusers512Jul3019:25Dicts/

drwxrwxr-x10netswusers512Jul901:54Graphic/

drwxrwxr-x5netswusers512Jul901:58Hackers/

drwxrwxr-x8netswusers512Jul903:19InfoSys/

drwxrwxr-x3netswusers512Jul903:21Math/

drwxrwxr-x3netswusers512Jul903:24Misc/

drwxrwxr-x9netswusers512Aug116:33Network/

drwxrwxr-x2netswusers512Jul905:53Office/

drwxrwxr-x7netswusers512Jul909:24SoftEng/

drwxrwxr-x7netswusers512Jul912:17System/

drwxrwxr-x12netswusers512Aug320:15Typesetting/

drwxrwxr-x10netswusers512Jul914:08X11/

InJuly1996IdecidedtomakethisarchivepublictotheworldviaaniceWebinterface."Nice"meansthatIwantedtoofferaninterfacewhereyoucanbrowsedirectlythroughthearchivehierarchy.And"nice"meansthatIdidn'twantedtochangeanythinginsidethishierarchy-notevenbyputtingsomeCGIscriptsatthetopofit.Why?BecausetheabovestructureshouldbelateraccessibleviaFTPaswell,andIdidn'twantanyWeborCGIstufftobethere.

Solution:Thesolutionhastwoparts:ThefirstisasetofCGIscriptswhichcreateallthepagesatalldirectorylevelson-the-fly.Iputthemunder/e/netsw/.www/asfollows:

-rw-r--r--1netswusers1318Aug118:10.wwwacl

drwxr-xr-x18netswusers512Aug515:51DATA/

-rw-rw-rw-1netswusers372982Aug516:35LOGFILE

-rw-r--r--1netswusers659Aug409:27TODO

-rw-r--r--1netswusers5697Aug118:01netsw-about.html

-rwxr-xr-x1netswusers579Aug210:33netsw-access.pl

-rwxr-xr-x1netswusers1532Aug117:35netsw-changes.cgi

-rwxr-xr-x1netswusers2866Aug514:49netsw-home.cgi

drwxr-xr-x2netswusers512Jul823:47netsw-img/

-rwxr-xr-x1netswusers24050Aug515:49netsw-lsdir.cgi

-rwxr-xr-x1netswusers1589Aug318:43netsw-search.cgi

-rwxr-xr-x1netswusers1885Aug117:41netsw-tree.cgi

-rw-r--r--1netswusers234Jul3016:35netsw-unlimit.lst

TheDATA/subdirectoryholdstheabovedirectorystructure,i.e.therealnet.swstuffandgetsautomaticallyupdatedviardistfromtimetotime.Thesecondpartoftheproblemremains:howtolinkthesetwostructurestogetherintoonesmooth-lookingURLtree?WewanttohidetheDATA/directoryfromtheuserwhilerunningtheappropriateCGIscriptsforthevariousURLs.Hereisthesolution:firstIputthefollowingintotheper-directoryconfigurationfileintheDocumentRootoftheservertorewritetheannouncedURL/net.sw/totheinternalpath/e/netsw:

RewriteRule^net.sw$net.sw/[R]

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

Thefirstruleisforrequestswhichmissthetrailingslash!Thesecondruledoestherealthing.Andthencomesthekillerconfigurationwhichstaysintheper-directoryconfigfile/e/netsw/.www/.wwwacl:

OptionsExecCGIFollowSymLinksIncludesMultiViews

RewriteEngineon

#wearereachedvia/net.sw/prefix

RewriteBase/net.sw/

#firstwerewritetherootdirto

#thehandlingcgiscript

RewriteRule^$netsw-home.cgi[L]

RewriteRule^index\.html$netsw-home.cgi[L]

#stripoutthesubdirswhen

#thebrowserrequestsusfromperdirpages

RewriteRule^.+/(netsw-[^/]+/.+)$$1[L]

#andnowbreaktherewritingforlocalfiles

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]

#anythingelseisasubdirwhichgetshandled

#byanothercgiscript

RewriteRule!^netsw-lsdir\.cgi.*-[C]

RewriteRule(.*)netsw-lsdir.cgi/$1

Somehintsforinterpretation:

1. NoticetheL(last)flagandnosubstitutionfield('-')intheforthpart

2. Noticethe!(not)characterandtheC(chain)flagatthefirstruleinthelastpart

3. Noticethecatch-allpatterninthelastrule

NCSAimagemaptoApachemod_imapDescription:

WhenswitchingfromtheNCSAwebservertothemoremodernApachewebserveralotofpeoplewantasmoothtransition.SotheywantpageswhichusetheiroldNCSAimagemapprogramtoworkunderApachewiththemodernmod_imap.Theproblemisthattherearealotofhyperlinksaroundwhichreferencetheimagemapprogramvia/cgi-bin/imagemap/path/to/page.map.UnderApachethishastoreadjust/path/to/page.map.

Solution:Weuseaglobalruletoremovetheprefixon-the-flyforallrequests:

RewriteEngineon

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

SearchpagesinmorethanonedirectoryDescription:

Sometimesitisnecessarytoletthewebserversearchforpagesinmorethanonedirectory.HereMultiViewsorothertechniquescannothelp.

Solution:Weprogramaexplicitrulesetwhichsearchesforthefilesinthedirectories.

RewriteEngineon

#firsttrytofinditincustom/...

#...andiffoundstopandbehappy:

RewriteCond/your/docroot/dir1/%{REQUEST_FILENAME}-f

RewriteRule^(.+)/your/docroot/dir1/$1[L]

#secondtrytofinditinpub/...

#elsegoonforotherAliasorScriptAliasdirectives,

RewriteRule^(.+)-[PT]

SetEnvironmentVariablesAccordingToURLPartsDescription:

PerhapsyouwanttokeepstatusinformationbetweenrequestsandusetheURLtoencodeit.Butyoudon'twanttouseaCGIwrapperforallpagesjusttostripoutthisinformation.

Solution:WeusearewriteruletostripoutthestatusinformationandrememberitviaanenvironmentvariablewhichcanbelaterdereferencedfromwithinXSSIorCGI.ThiswayaURL/foo/S=java/bar/getstranslatedto/foo/bar/andtheenvironmentvariablenamedSTATUSissettothevalue"java".

RewriteEngineon

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

VirtualUserHosts

Description:Assumethatyouwanttoprovidewww.username.host.domain.comforthehomepageofusernameviajustDNSArecordstothesamemachineandwithoutanyvirtualhostsonthismachine.

Solution:ForHTTP/1.0requeststhereisnosolution,butforHTTP/1.1requestswhichcontainaHost:HTTPheaderwecanusethefollowingrulesettorewritehttp://www.username.host.com/anypathinternallyto/home/username/anypath:

RewriteEngineon

RewriteCond%{HTTP_HOST}^www\.[^.]+\.host\.com$

RewriteRule^(.+)%{HTTP_HOST}$1[C]

RewriteRule^www\.([^.]+)\.host\.com(.*)/home/$1$2

RedirectHomedirsForForeignersDescription:

WewanttoredirecthomedirURLstoanotherwebserverwww.somewhere.comwhentherequestinguserdoesnotstayinthelocaldomainourdomain.com.Thisissometimesusedinvirtualhostcontexts.

Solution:Justarewritecondition:

RewriteEngineon

RewriteCond%{REMOTE_HOST}!^.+\.ourdomain\.com$

RewriteRule^(/~.+)http://www.somewhere.com/$1[R,L]

RedirectFailingURLsToOtherWebserverDescription:

AtypicalFAQaboutURLrewritingishowtoredirectfailingrequestsonwebserverAtowebserverB.UsuallythisisdoneviaErrorDocumentCGI-scriptsinPerl,butthereisalsoamod_rewritesolution.ButnoticethatthisperformsmorepoorlythanusinganErrorDocumentCGI-script!

Solution:Thefirstsolutionhasthebestperformancebutlessflexibility,andislesserrorsafe:

RewriteEngineon

RewriteCond/your/docroot/%{REQUEST_FILENAME}!-f

RewriteRule^(.+)http://webserverB

TheproblemhereisthatthiswillonlyworkforpagesinsidetheDocumentRoot.WhileyoucanaddmoreConditions(forinstancetoalsohandlehomedirs,etc.)thereisbettervariant:

RewriteEngineon

RewriteCond%{REQUEST_URI}!-U

RewriteRule^(.+)http://webserverB.dom/$1

ThisusestheURLlook-aheadfeatureofmod_rewrite.TheresultisthatthiswillworkforalltypesofURLsandisasafeway.Butitdoesaperformanceimpactonthewebserver,becauseforeveryrequestthereisonemoreinternalsubrequest.So,ifyourwebserverrunsonapowerfulCPU,usethisone.Ifitisaslowmachine,usethefirstapproachorbetteraErrorDocumentCGI-script.

ExtendedRedirection

Description:Sometimesweneedmorecontrol(concerningthecharacterescapingmechanism)ofURLsonredirects.UsuallytheApachekernelsURLescapefunctionalsoescapesanchors,i.e.URLslike"url#anchor".Youcannotusethisdirectlyonredirectswithmod_rewritebecausetheuri_escape()functionofApachewouldalsoescapethehashcharacter.HowcanweredirecttosuchaURL?

Solution:WehavetouseakludgebytheuseofaNPH-CGIscriptwhichdoestheredirectitself.Becauseherenoescapingisdone(NPH=non-parseableheaders).FirstweintroduceanewURLschemexredirect:bythefollowingper-serverconfig-line(shouldbeoneofthelastrewriterules):

RewriteRule^xredirect:(.+)/path/to/nph-xredirect.cgi/$1\

[T=application/x-httpd-cgi,L]

ThisforcesallURLsprefixedwithxredirect:tobepipedthroughthenph-xredirect.cgiprogram.Andthisprogramjustlookslike:

#!/path/to/perl

##nph-xredirect.cgi--NPH/CGIscriptforextendedredirects

$url=$ENV{'PATH_INFO'};

print"HTTP/1.0302MovedTemporarily\n";

print"Server:$ENV{'SERVER_SOFTWARE'}\n";

print"Location:$url\n";

print"\n";

print"<html>\n";

print"<head>\n";

print"<title>302MovedTemporarily(EXTENDED)</title>\n";

print"</head>\n";

print"<body>\n";

print"<h1>MovedTemporarily(EXTENDED)</h1>\n";

print"Thedocumenthasmoved<aHREF=\"$url\">here</a>.<p>\n";

print"</body>\n";

print"</html>\n";

##EOF##

ThisprovidesyouwiththefunctionalitytodoredirectstoallURLschemes,i.e.includingtheonewhicharenotdirectlyacceptedbymod_rewrite.Forinstanceyoucannowalsoredirecttonews:newsgroupvia

RewriteRule^anyurlxredirect:news:newsgroup

Notice:Youhavenottoput[R]or[R,L]totheaboverulebecausethexredirect:needtobeexpandedlaterbyourspecial"pipethrough"ruleabove.

ArchiveAccessMultiplexerDescription:

DoyouknowthegreatCPAN(ComprehensivePerlArchiveNetwork)underhttp://www.perl.com/CPAN?ThisdoesaredirecttooneofseveralFTPserversaroundtheworldwhichcarryaCPANmirrorandisapproximatelynearthelocationof

therequestingclient.ActuallythiscanbecalledanFTPaccessmultiplexingservice.WhileCPANrunsviaCGIscripts,howcanasimilarapproachimplementedviamod_rewrite?

Solution:Firstwenoticethatfromversion3.0.0mod_rewritecanalsousethe"ftp:"schemeonredirects.Andsecond,thelocationapproximationcanbedonebyaRewriteMapoverthetop-leveldomainoftheclient.Withatrickychainedrulesetwecanusethistop-leveldomainasakeytoourmultiplexingmap.

RewriteEngineon

RewriteMapmultiplextxt:/path/to/map.cxan

RewriteRule^/CxAN/(.*)%{REMOTE_HOST}::$1[C]

RewriteRule^.+\.([a-zA-Z]+)::(.*)$${multiplex:$1|ftp.default.dom}$2[R,L]

##map.cxan--MultiplexingMapforCxAN

deftp://ftp.cxan.de/CxAN/

ukftp://ftp.cxan.uk/CxAN/

comftp://ftp.cxan.com/CxAN/

##EOF##

Time-DependentRewritingDescription:

Whentricksliketime-dependentcontentshouldhappenalotofwebmastersstilluseCGIscriptswhichdoforinstanceredirectstospecializedpages.Howcanitbedonevia

mod_rewrite?

Solution:TherearealotofvariablesnamedTIME_xxxforrewriteconditions.Inconjunctionwiththespeciallexicographiccomparisonpatterns<STRING,>STRINGand=STRINGwecandotime-dependentredirects:

RewriteEngineon

RewriteCond%{TIME_HOUR}%{TIME_MIN}>0700

RewriteCond%{TIME_HOUR}%{TIME_MIN}<1900

RewriteRule^foo\.html$foo.day.html

RewriteRule^foo\.html$foo.night.html

Thisprovidesthecontentoffoo.day.htmlundertheURLfoo.htmlfrom07:00-19:00andattheremainingtimethecontentsoffoo.night.html.Justanicefeatureforahomepage...

BackwardCompatibilityforYYYYtoXXXXmigrationDescription:

HowcanwemakeURLsbackwardcompatible(stillexistingvirtually)aftermigratingdocument.YYYYtodocument.XXXX,e.g.aftertranslatingabunchof.htmlfilesto.phtml?

Solution:Wejustrewritethenametoitsbasenameandtestforexistenceofthenewextension.Ifitexists,wetakethatname,elsewerewritetheURLtoitsoriginalstate.

#backwardcompatibilityrulesetfor

#rewritingdocument.htmltodocument.phtml

#whenandonlywhendocument.phtmlexists

#butnolongerdocument.html

RewriteEngineon

RewriteBase/~quux/

#parseoutbasename,butrememberthefact

RewriteRule^(.*)\.html$$1[C,E=WasHTML:yes]

#rewritetodocument.phtmlifexists

RewriteCond%{REQUEST_FILENAME}.phtml-f

RewriteRule^(.*)$$1.phtml[S=1]

#elsereversethepreviousbasenamecutout

RewriteCond%{ENV:WasHTML}^yes$

RewriteRule^(.*)$$1.html

ContentHandling

FromOldtoNew(intern)Description:

Assumewehaverecentlyrenamedthepagefoo.htmltobar.htmlandnowwanttoprovidetheoldURLforbackwardcompatibility.ActuallywewantthatusersoftheoldURLevennotrecognizethatthepageswasrenamed.

Solution:WerewritetheoldURLtothenewoneinternallyviathefollowingrule:

RewriteEngineon

RewriteBase/~quux/

RewriteRule^foo\.html$bar.html

FromOldtoNew(extern)Description:

Assumeagainthatwehaverecentlyrenamedthepagefoo.htmltobar.htmlandnowwanttoprovidetheoldURLforbackwardcompatibility.ButthistimewewantthattheusersoftheoldURLgethintedtothenewone,i.e.theirbrowsersLocationfieldshouldchange,too.

Solution:WeforceaHTTPredirecttothenewURLwhichleadstoachangeofthebrowsersandthustheusersview:

RewriteEngineon

RewriteBase/~quux/

RewriteRule^foo\.html$bar.html[R]

BrowserDependentContentDescription:

Atleastforimportanttop-levelpagesitissometimesnecessarytoprovidetheoptimumofbrowserdependentcontent,i.e.onehastoprovideamaximumversionforthelatestNetscapevariants,aminimumversionfortheLynxbrowsersandaaveragefeatureversionforallothers.

Solution:Wecannotusecontentnegotiationbecausethebrowsersdonotprovidetheirtypeinthatform.InsteadwehavetoactontheHTTPheader"User-Agent".Thefollowingcondigdoesthefollowing:IftheHTTPheader"User-Agent"beginswith"Mozilla/3",thepagefoo.htmlisrewrittentofoo.NS.htmlandandtherewritingstops.Ifthebrowseris"Lynx"or"Mozilla"ofversion1or2theURLbecomesfoo.20.html.Allotherbrowsersreceivepagefoo.32.html.Thisisdonebythefollowingruleset:

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]

DynamicMirrorDescription:

Assumetherearenicewebpagesonremotehostswewanttobringintoournamespace.ForFTPserverswewouldusethemirrorprogramwhichactuallymaintainsanexplicitup-to-

datecopyoftheremotedataonthelocalmachine.ForawebserverwecouldusetheprogramwebcopywhichactssimilarviaHTTP.Butbothtechniqueshaveonemajordrawback:Thelocalcopyisalwaysjustasup-to-dateasoftenweruntheprogram.Itwouldbemuchbetterifthemirrorisnotastaticonewehavetoestablishexplicitly.Insteadwewantadynamicmirrorwithdatawhichgetsupdatedautomaticallywhenthereisneed(updateddataontheremotehost).

Solution:ToprovidethisfeaturewemaptheremotewebpageoreventhecompleteremotewebareatoournamespacebytheuseoftheProxyThroughputfeature(flag[P]):

RewriteEngineon

RewriteBase/~quux/

RewriteRule^hotsheet/(.*)$http://www.tstimpreso.com/hotsheet/

RewriteEngineon

RewriteBase/~quux/

RewriteRule^usa-news\.html$http://www.quux-corp.com/news/index.html

ReverseDynamicMirrorDescription:

Solution:

RewriteEngineon

RewriteCond/mirror/of/remotesite/$1-U

RewriteRule^http://www\.remotesite\.com/(.*)$/mirror/of/remotesite/$1

RetrieveMissingDatafromIntranetDescription:

Thisisatrickywayofvirtuallyrunningacorporate(external)Internetwebserver(www.quux-corp.dom),whileactuallykeepingandmaintainingitsdataona(internal)Intranetwebserver(www2.quux-corp.dom)whichisprotectedbyafirewall.Thetrickisthatontheexternalwebserverweretrievetherequesteddataon-the-flyfromtheinternalone.

Solution:First,wehavetomakesurethatourfirewallstillprotectstheinternalwebserverandthatonlytheexternalwebserverisallowedtoretrievedatafromit.Forapacket-filteringfirewallwecouldforinstanceconfigureafirewallrulesetlikethefollowing:

ALLOWHostwww.quux-corp.domPort>1024-->Hostwww2.quux-corp.domPort

DENYHost*Port*-->Hostwww2.quux-corp.domPort

Justadjustittoyouractualconfigurationsyntax.Nowwecanestablishthemod_rewriteruleswhichrequestthemissingdatainthebackgroundthroughtheproxythroughputfeature:

RewriteRule^/~([^/]+)/?(.*)/home/$1/.www/$2

RewriteCond%{REQUEST_FILENAME}!-f

RewriteCond%{REQUEST_FILENAME}!-d

RewriteRule^/home/([^/]+)/.www/?(.*)http://www2.quux-corp.dom/~$1/pub/$2[

LoadBalancingDescription:

Supposewewanttoloadbalancethetraffictowww.foo.comoverwww[0-5].foo.com(atotalof6servers).Howcanthis

bedone?

Solution:Therearealotofpossiblesolutionsforthisproblem.WewilldiscussfirstacommonlyknownDNS-basedvariantandthenthespecialonewithmod_rewrite:

1. DNSRound-RobinThesimplestmethodforload-balancingistousetheDNSround-robinfeatureofBIND.Hereyoujustconfigurewww[0-9].foo.comasusualinyourDNSwithA(address)records,e.g.

www0INA1.2.3.1

www1INA1.2.3.2

www2INA1.2.3.3

www3INA1.2.3.4

www4INA1.2.3.5

www5INA1.2.3.6

Thenyouadditionallyaddthefollowingentry:

wwwINCNAMEwww0.foo.com.

INCNAMEwww1.foo.com.

Noticethatthisseemswrong,butisactuallyanintendedfeatureofBINDandcanbeusedinthisway.However,nowwhenwww.foo.comgetsresolved,BINDgivesoutwww0-www6-butinaslightlypermutated/rotatedorder

everytime.Thiswaytheclientsarespreadoverthevariousservers.Butnoticethatthisnotaperfectloadbalancingscheme,becauseDNSresolveinformationgetscachedbytheothernameserversonthenet,soonceaclienthasresolvedwww.foo.comtoaparticularwwwN.foo.com,allsubsequentrequestsalsogotothisparticularnamewwwN.foo.com.Butthefinalresultisok,becausethetotalsumoftherequestsarereallyspreadoverthevariouswebservers.

2. DNSLoad-BalancingAsophisticatedDNS-basedmethodforload-balancingistousetheprogramlbnamedwhichcanbefoundathttp://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.htmlItisaPerl5programinconjunctionwithauxilliarytoolswhichprovidesarealload-balancingforDNS.

3. ProxyThroughputRound-RobinInthisvariantweusemod_rewriteanditsproxythroughputfeature.Firstwededicatewww0.foo.comtobeactuallywww.foo.combyusingasingle

entryintheDNS.Thenweconvertwww0.foo.comtoaproxy-onlyserver,i.e.weconfigurethismachinesoallarrivingURLsarejustpushedthroughtheinternalproxytooneofthe5otherservers(www1-www5).Toaccomplishthiswefirstestablisharulesetwhichcontactsaloadbalancingscriptlb.plforallURLs.

RewriteEngineon

RewriteMaplbprg:/path/to/lb.pl

RewriteRule^/(.+)$${lb:$1}[P,L]

Thenwewritelb.pl:

#!/path/to/perl

##lb.pl--loadbalancingscript

$name="www";#thehostnamebase

$first=1;#thefirstserver(not0here,because0ismyself)

$last=5;#thelastserverintheround-robin

$domain="foo.dom";#thedomainname

$cnt=0;

while(<STDIN>){

$cnt=(($cnt+1)%($last+1-$first));

$server=sprintf("%s%d.%s",$name,$cnt+$first,$domain);

print"http://$server/$_";

##EOF##

Alastnotice:Whyisthisuseful?Seemslikewww0.foo.comstillisoverloaded?Theanswerisyes,itisoverloaded,butwithplainproxythroughputrequests,only!AllSSI,CGI,ePerl,etc.processingiscompletelydoneontheothermachines.Thisistheessentialpoint.

4. Hardware/TCPRound-Robin

Thereisahardwaresolutionavailable,too.CiscohasabeastcalledLocalDirectorwhichdoesaloadbalancingattheTCP/IPlevel.Actuallythisissomesortofacircuitlevelgatewayinfrontofawebcluster.Ifyouhaveenoughmoneyandreallyneedasolutionwithhighperformance,usethisone.

NewMIME-type,NewServiceDescription:

OnthenettherearealotofniftyCGIprograms.Buttheirusageisusuallyboring,soalotofwebmasterdon'tusethem.EvenApache'sActionhandlerfeatureforMIME-typesisonlyappropriatewhentheCGIprogramsdon'tneedspecialURLs(actuallyPATH_INFOandQUERY_STRINGS)astheirinput.First,letusconfigureanewfiletypewithextension.scgi(forsecureCGI)whichwillbeprocessedbythepopularcgiwrapprogram.TheproblemhereisthatforinstanceweuseaHomogeneousURLLayout(seeabove)afileinsidetheuserhomedirshastheURL/u/user/foo/bar.scgi.ButcgiwrapneedstheURLintheform/~user/foo/bar.scgi/.Thefollowingrulesolvestheproblem:

RewriteRule^/[uge]/([^/]+)/\.www/(.+)\.scgi(.*)...

.../internal/cgi/user/cgiwrap/~$1/$2.scgi$3[NS,T=application/x-http-cgi

Orassumewehavesomemoreniftyprograms:wwwlog(whichdisplaystheaccess.logforaURLsubtreeandwwwidx(whichrunsGlimpseonaURLsubtree).WehavetoprovidetheURLareatotheseprogramssotheyknowonwhichareatheyhavetoacton.Butusuallythisugly,becausetheyareallthetimesstillrequestedfromthatareas,i.e.

typicallywewouldruntheswwidxprogramfromwithin/u/user/foo/viahyperlinkto

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

whichisugly.Becausewehavetohard-codeboththelocationoftheareaandthelocationoftheCGIinsidethehyperlink.Whenwehavetoreorganizethearea,wespendalotoftimechangingthevarioushyperlinks.

Solution:ThesolutionhereistoprovideaspecialnewURLformatwhichautomaticallyleadstotheproperCGIinvocation.Weconfigurethefollowing:

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

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

Nowthehyperlinktosearchat/u/user/foo/readsonly

HREF="*"

whichinternallygetsautomaticallytransformedto

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

ThesameapproachleadstoaninvocationfortheaccesslogCGIprogramwhenthehyperlink:loggetsused.

FromStatictoDynamicDescription:

Howcanwetransformastaticpagefoo.htmlintoa

dynamicvariantfoo.cgiinaseamlessway,i.e.withoutnoticebythebrowser/user.

Solution:WejustrewritetheURLtotheCGI-scriptandforcethecorrectMIME-typesoitgetsreallyrunasaCGI-script.Thiswayarequestto/~quux/foo.htmlinternallyleadstotheinvocationof/~quux/foo.cgi.

RewriteEngineon

RewriteBase/~quux/

RewriteRule^foo\.html$foo.cgi[T=application/x-httpd-cgi

On-the-flyContent-RegenerationDescription:

Herecomesareallyesotericfeature:Dynamicallygeneratedbutstaticallyservedpages,i.e.pagesshouldbedeliveredaspurestaticpages(readfromthefilesystemandjustpassedthrough),buttheyhavetobegenerateddynamicallybythewebserverifmissing.ThiswayyoucanhaveCGI-generatedpageswhicharestaticallyservedunlessone(oracronjob)removesthestaticcontents.Thenthecontentsgetsrefreshed.

Solution:Thisisdoneviathefollowingruleset:

RewriteCond%{REQUEST_FILENAME}!-s

RewriteRule^page\.html$page.cgi[T=application/x-httpd-cgi,L]

Herearequesttopage.htmlleadstoainternalrunofacorrespondingpage.cgiifpage.htmlisstillmissingorhasfilesizenull.Thetrickhereisthatpage.cgiisausualCGI

scriptwhich(additionallytoitsSTDOUT)writesitsoutputtothefilepage.html.Onceitwasrun,theserversendsoutthedataofpage.html.Whenthewebmasterwantstoforcearefreshthecontents,hejustremovespage.html(usuallydonebyacronjob).

DocumentWithAutorefreshDescription:

Wouldn'titbenicewhilecreatingacomplexwebpageifthewebbrowserwouldautomaticallyrefreshthepageeverytimewewriteanewversionfromwithinoureditor?Impossible?

Solution:No!WejustcombinetheMIMEmultipartfeature,thewebserverNPHfeatureandtheURLmanipulationpowerofmod_rewrite.First,weestablishanewURLfeature:Addingjust:refreshtoanyURLcausesthistoberefreshedeverytimeitgetsupdatedonthefilesystem.

RewriteRule^(/[uge]/[^/]+/?.*):refresh/internal/cgi/apache/nph-refresh?f=$1

NowwhenwereferencetheURL

/u/foo/bar/page.html:refresh

thisleadstotheinternalinvocationoftheURL

/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html

TheonlymissingpartistheNPH-CGIscript.Althoughonewouldusuallysay"leftasanexercisetothereader";-)Iwillprovidethis,too.

#!/sw/bin/perl

##nph-refresh--NPH/CGIscriptforautorefreshingpages

#splittheQUERY_STRINGvariable

@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=1if($QS_seq'');

$QS_n=3600if($QS_neq'');

if($QS_feq''){

print"HTTP/1.0200OK\n";

print"Content-type:text/html\n\n";

print"<b>ERROR</b>:Nofilegiven\n";

exit(0);

if(!-f$QS_f){

print"<b>ERROR</b>:File$QS_fnotfound\n";

exit(0);

subprint_http_headers_multipart_begin{

$bound="ThisRandomString12345";

print"Content-type:multipart/x-mixed-replace;boundary=$bound\n";

&print_http_headers_multipart_next;

subprint_http_headers_multipart_next{

print"\n--$bound\n";

subprint_http_headers_multipart_end{

print"\n--$bound--\n";

subdisplayhtml{

local($buffer)=@_;

$len=length($buffer);

print"Content-length:$len\n\n";

print$buffer;

subreadfile{

local($file)=@_;

local(*FP,$size,$buffer,$bytes);

($x,$x,$x,$x,$x,$x,$x,$size)=stat($file);

$size=sprintf("%d",$size);

open(FP,"<$file");

$bytes=sysread(FP,$buffer,$size);

close(FP);

return$buffer;

$buffer=&readfile($QS_f);

&print_http_headers_multipart_begin;

&displayhtml($buffer);

submystat{

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<$QS_n;$n++){

while(1){

$mtime=&mystat($QS_f);

if($mtimene$mtimeL){

$mtimeL=$mtime;

sleep(2);

sleep(5);

sleep($QS_s);

&print_http_headers_multipart_end;

exit(0);

##EOF##

MassVirtualHostingDescription:

The<VirtualHost>featureofApacheisniceandworksgreatwhenyoujusthaveafewdozensvirtualhosts.ButwhenyouareanISPandhavehundredsofvirtualhoststoprovidethisfeatureisnotthebestchoice.

##vhost.map

www.vhost1.dom:80/path/to/docroot/vhost1

www.vhostN.dom:80/path/to/docroot/vhostN

##httpd.conf

#usethecanonicalhostnameonredirects,etc.

UseCanonicalNameon

#addthevirtualhostinfrontoftheCLF-format

CustomLog/path/to/access_log"%{VHOST}e%h%l%u%t\"%r\"%>s%b"

#enabletherewritingengineinthemainserver

RewriteEngineon

#definetwomaps:oneforfixingtheURLandonewhichdefines

#theavailablevirtualhostswiththeircorresponding

#DocumentRoot.

RewriteMaplowercaseint:tolower

RewriteMapvhosttxt:/path/to/vhost.map

#Nowdotheactualvirtualhostmapping

#viaahugeandcomplicatedsinglerule:

#1.makesurewedon'tmapforcommonlocations

RewriteCond%{REQUEST_URI}!^/commonurl1/.*

RewriteCond%{REQUEST_URI}!^/commonurlN/.*

#2.makesurewehaveaHostheader,because

#currentlyourapproachonlysupports

#virtualhostingthroughthisheader

#3.lowercasethehostname

RewriteCond${lowercase:%{HTTP_HOST}|NONE}^(.+)$

#4.lookupthishostnameinvhost.mapand

#rememberitonlywhenitisapath

#(andnot"NONE"fromabove)

RewriteCond${vhost:%1}^(/.*)$

#5.finallywecanmaptheURLtoitsdocrootlocation

#andrememberthevirtualhostforloggingpuposes

RewriteRule^/(.*)$%1/$1[E=VHOST:${lowercase:%{HTTP_HOST}}]

AccessRestriction

BlockingofRobotsDescription:

Howcanweblockareallyannoyingrobotfromretrievingpagesofaspecificwebarea?A/robots.txtfilecontainingentriesofthe"RobotExclusionProtocol"istypicallynotenoughtogetridofsucharobot.

Solution:WeusearulesetwhichforbidstheURLsofthewebarea/~quux/foo/arc/(perhapsaverydeepdirectoryindexedareawheretherobottraversalwouldcreatebigserverload).Wehavetomakesurethatweforbidaccessonlytotheparticularrobot,i.e.justforbiddingthehostwheretherobotrunsisnotenough.Thiswouldblockusersfromthishost,too.WeaccomplishthisbyalsomatchingtheUser-AgentHTTPheaderinformation.

RewriteCond%{HTTP_USER_AGENT}^NameOfBadRobot.*

RewriteCond%{REMOTE_ADDR}^123\.45\.67\.[8-9]$

RewriteRule^/~quux/foo/arc/.+-[F]

BlockedInline-ImagesDescription:

Assumewehaveunderhttp://www.quux-corp.de/~quux/somepageswithinlinedGIFgraphics.Thesegraphicsarenice,soothersdirectlyincorporatethemviahyperlinkstotheirpages.Wedon'tlikethispracticebecauseitaddsuselesstraffictoourserver.

Solution:Whilewecannot100%protecttheimagesfrominclusion,we

canatleastrestrictthecaseswherethebrowsersendsaHTTPRefererheader.

RewriteCond%{HTTP_REFERER}!^$

RewriteCond%{HTTP_REFERER}!^http://www.quux-corp.de/~quux/.*$[NC]

RewriteRule.*\.gif$-[F]

RewriteCond%{HTTP_REFERER}!.*/foo-with-gif\.html$

RewriteRule^inlined-in-foo\.gif$-[F]

HostDenyDescription:

Howcanweforbidalistofexternallyconfiguredhostsfromusingourserver?

Solution:ForApache>=1.3b6:

RewriteEngineon

RewriteMaphosts-denytxt:/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]

ForApache<=1.3b6:

RewriteEngineon

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/(.*)$/$1

##hosts.deny

##ATTENTION!Thisisamap,notalist,evenwhenwetreatitassuch.

##mod_rewriteparsesitforkey/valuepairs,soatleasta

##dummyvalue"-"mustbepresentforeachentry.

193.102.180.41-

bsdti1.sdm.de-

192.76.162.40-

ProxyDenyDescription:

HowcanweforbidacertainhostorevenauserofaspecialhostfromusingtheApacheproxy?

Solution:Wefirsthavetomakesuremod_rewriteisbelow(!)mod_proxyintheConfigurationfilewhencompilingtheApachewebserver.Thiswayitgetscalledbeforemod_proxy.Thenweconfigurethefollowingforahost-dependentdeny...

RewriteCond%{REMOTE_HOST}^badhost\.mydomain\.com$

RewriteRule!^http://[^/.]\.mydomain.com.*-[F]

...andthisoneforauser@host-dependentdeny:

RewriteCond%{REMOTE_IDENT}@%{REMOTE_HOST}^badguy@badhost\.mydomain\.com$

SpecialAuthenticationVariantDescription:

Sometimesaveryspecialauthenticationisneeded,forinstanceaauthenticationwhichchecksforasetofexplicitlyconfiguredusers.Onlytheseshouldreceiveaccessandwithoutexplicitprompting(whichwouldoccurwhenusingtheBasicAuthviamod_auth).

Solution:Weusealistofrewriteconditionstoexcludeallexceptourfriends:

RewriteCond%{REMOTE_IDENT}@%{REMOTE_HOST}!^friend1@client1.quux-corp\.com$

RewriteRule^/~quux/only-for-friends/-[F]

Referer-basedDeflectorDescription:

HowcanweprogramaflexibleURLDeflectorwhichactsonthe"Referer"HTTPheaderandcanbeconfiguredwithasmanyreferringpagesaswelike?

Solution:Usethefollowingreallytrickyruleset...

RewriteMapdeflectortxt:/path/to/deflector.map

RewriteCond%{HTTP_REFERER}!=""

RewriteCond${deflector:%{HTTP_REFERER}}^-$

RewriteRule^.*%{HTTP_REFERER}[R,L]

RewriteCond${deflector:%{HTTP_REFERER}|NOT-FOUND}!=NOT-FOUND

RewriteRule^.*${deflector:%{HTTP_REFERER}}[R,L]

...inconjunctionwithacorrespondingrewritemap:

##deflector.map

http://www.badguys.com/bad/index.html-

http://www.badguys.com/bad/index2.html-

http://www.badguys.com/bad/index3.htmlhttp://somewhere.com/

Thisautomaticallyredirectstherequestbacktothereferringpage(when"-"isusedasthevalueinthemap)ortoaspecificURL(whenanURLisspecifiedinthemapasthesecondargument).

ExternalRewritingEngineDescription:

AFAQ:HowcanwesolvetheFOO/BAR/QUUX/etc.problem?Thereseemsnosolutionbytheuseofmod_rewrite...

Solution:UseanexternalRewriteMap,i.e.aprogramwhichactslikeaRewriteMap.ItisrunonceonstartupofApachereceivestherequestedURLsonSTDINandhastoputtheresulting(usuallyrewritten)URLonSTDOUT(sameorder!).

RewriteEngineon

RewriteMapquux-mapprg:/path/to/map.quux.pl

RewriteRule^/~quux/(.*)$/~quux/${quux-map:$1}

#!/path/to/perl

#disablebufferedI/Owhichwouldlead

#todeadloopsfortheApacheserver

#readURLsoneperlinefromstdinand

#generatesubstitutionURLonstdout

while(<>){

s|^foo/|bar/|;

print$_;

Thisisademonstration-onlyexampleandjustrewritesallURLs/~quux/foo/...to/~quux/bar/....Actuallyyoucanprogramwhateveryoulike.Butnoticethatwhilesuch

mapscanbeusedalsobyanaverageuser,onlythesystemadministratorcandefineit.

||FAQ||

ApacheHTTP2.0Apache>HTTP>>2.0 >

ServerPath

IPDNS IP

SSL SSL IP

core DocumentRoot

NameVirtualHost

ServerAlias

ServerName

ServerPath

VirtualHost

IP()NameVirtualHost *IP

*:80 NameVirtualHost IP

<VirtualHost> <VirtualHost>NameVirtualHost(IP ServerName

ServerName DocumentRoot

www.domain.tld www.otherdomain.tld

httpd.conf

NameVirtualHost*:80

<VirtualHost*:80>

ServerNamewww.domain.tld

ServerAliasdomain.tld*.domain.tld

DocumentRoot/www/domain

</VirtualHost>

<VirtualHost*:80>

ServerNamewww.otherdomain.tld

DocumentRoot/www/otherdomain

</VirtualHost>

NameVirtualHost VirtualHost *IP IPIP

ServerAliasdomain.tld*.domain.tld

domain.tld www.domain.tldServerName ServerAlias

<VirtualHost> (<VirtualHost>)

<NameVirtualHost>IP<VirtualHost> ServerName ServerAlias

IP NameVirtualHost <VirtualHost>

||FAQ||

ServerPath

NameVirtualHost111.22.33.44

<VirtualHost111.22.33.44>

ServerNamewww.domain.tld

ServerPath/domain

DocumentRoot/web/domain

</VirtualHost>

? "/domain"URIhttp://www.domain.tld/domain/ Host:

http://www.domain.tld/

http://www.domain.tld/domain/

"file.html"" ../icons/image.gif") /domain/(: "http://www.domain.tld/domain/misc/file.html""/domain/misc/file.html")

ApacheHTTPServerVersion2.0Apache>HTTPServer>Documentation>Version2.0>VirtualHosts

ApacheIP-basedVirtualHostSupport

SeealsoName-basedVirtualHostsSupport

Systemrequirements

AsthetermIP-basedindicates,theservermusthaveadifferentIPaddressforeachIP-basedvirtualhost.Thiscanbeachievedbythemachinehavingseveralphysicalnetworkconnections,orbyuseofvirtualinterfaceswhicharesupportedbymostmodernoperatingsystems(seesystemdocumentationfordetails,thesearefrequentlycalled"ipaliases",andthe"ifconfig"commandismostcommonlyusedtosetthemup).

HowtosetupApache

Therearetwowaysofconfiguringapachetosupportmultiplehosts.Eitherbyrunningaseparatehttpddaemonforeachhostname,orbyrunningasingledaemonwhichsupportsallthevirtualhosts.

Usemultipledaemonswhen:

Therearesecuritypartitioningissues,suchascompany1doesnotwantanyoneatcompany2tobeabletoreadtheirdataexceptviatheweb.Inthiscaseyouwouldneedtwodaemons,eachrunningwithdifferentUser,Group,Listen,andServerRootsettings.YoucanaffordthememoryandfiledescriptorrequirementsoflisteningtoeveryIPaliasonthemachine.It'sonlypossibletoListentothe"wildcard"address,ortospecificaddresses.Soifyouhaveaneedtolistentoaspecificaddressforwhateverreason,thenyouwillneedtolistentoallspecificaddresses.(AlthoughonehttpdcouldlistentoN-1oftheaddresses,andanothercouldlistentotheremainingaddress.)

Useasingledaemonwhen:

Sharingofthehttpdconfigurationbetweenvirtualhostsisacceptable.Themachineservicesalargenumberofrequests,andsotheperformancelossinrunningseparatedaemonsmaybesignificant.

Settingupmultipledaemons

Createaseparatehttpdinstallationforeachvirtualhost.Foreachinstallation,usetheListendirectiveintheconfigurationfiletoselectwhichIPaddress(orvirtualhost)thatdaemonservices.e.g.

Listenwww.smallco.com:80

ItisrecommendedthatyouuseanIPaddressinsteadofahostname(seeDNScaveats).

Settingupasingledaemonwithvirtualhosts

Forthiscase,asinglehttpdwillservicerequestsforthemainserverandallthevirtualhosts.TheVirtualHostdirectiveintheconfigurationfileisusedtosetthevaluesofServerAdmin,ServerName,DocumentRoot,ErrorLogandTransferLogorCustomLogconfigurationdirectivestodifferentvaluesforeachvirtualhost.e.g.

<VirtualHostwww.smallco.com>

ServerAdminwebmaster@mail.smallco.com

DocumentRoot/groups/smallco/www

ServerNamewww.smallco.com

ErrorLog/groups/smallco/logs/error_log

TransferLog/groups/smallco/logs/access_log

</VirtualHost>

<VirtualHostwww.baygroup.org>

ServerAdminwebmaster@mail.baygroup.org

DocumentRoot/groups/baygroup/www

ServerNamewww.baygroup.org

ErrorLog/groups/baygroup/logs/error_log

TransferLog/groups/baygroup/logs/access_log

</VirtualHost>

ItisrecommendedthatyouuseanIPaddressinsteadofahostname(seeDNScaveats).

AlmostanyconfigurationdirectivecanbeputintheVirtualHostdirective,withtheexceptionofdirectivesthatcontrolprocesscreationandafewotherdirectives.TofindoutifadirectivecanbeusedintheVirtualHostdirective,checktheContextusingthedirectiveindex.

SuexecUserGroupmaybeusedinsideaVirtualHostdirectiveifthesuEXECwrapperisused.

SECURITY:Whenspecifyingwheretowritelogfiles,beawareofsomesecurityriskswhicharepresentifanyoneotherthantheuserthatstartsApachehaswriteaccesstothedirectorywhere

theyarewritten.Seethesecuritytipsdocumentfordetails.

DynamicallyConfiguredMassVirtualHosting

ThisdocumentdescribeshowtoefficientlyserveanarbitrarynumberofvirtualhostswiththeApachehttpdwebserver.

Motivation

Thetechniquesdescribedhereareofinterestifyourhttpd.confcontainsmany<VirtualHost>sectionsthataresubstantiallythesame,forexample:

ServerNamewww.customer-1.com

DocumentRoot/www/hosts/www.customer-1.com/docs

ScriptAlias/cgi-bin//www/hosts/www.customer-1.com/cgi-bin

</VirtualHost>

ServerNamewww.customer-2.com

DocumentRoot/www/hosts/www.customer-2.com/docs

ScriptAlias/cgi-bin//www/hosts/www.customer-2.com/cgi-bin

</VirtualHost>

#blahblahblah

ServerNamewww.customer-N.com

DocumentRoot/www/hosts/www.customer-N.com/docs

ScriptAlias/cgi-bin//www/hosts/www.customer-N.com/cgi-bin

</VirtualHost>

Thebasicideaistoreplaceallofthestatic<VirtualHost>configurationswithamechanismthatworksthemoutdynamically.Thishasanumberofadvantages:

1. Yourconfigurationfileissmaller,soApachestartsmorequicklyanduseslessmemory.

2. AddingvirtualhostsissimplyamatterofcreatingtheappropriatedirectoriesinthefilesystemandentriesintheDNS-youdon'tneedtoreconfigureorrestartApache.

Themaindisadvantageisthatyoucannothaveadifferentlogfileforeachvirtualhost;however,ifyouhavemanyvirtualhosts,doingthiscanbeabadideaanyway,becauseofthenumberoffiledescriptorsneeded.Itisbettertologtoapipeorafifo,andarrangefortheprocessattheotherendtodistributethelogstothecustomers.(Thiscanalsobeusedtoaccumulatestatistics,

etc.).

Overview

Avirtualhostisdefinedbytwopiecesofinformation:itsIPaddress,andthecontentsoftheHost:headerintheHTTPrequest.Thedynamicmassvirtualhostingtechniqueusedhereisbasedonautomaticallyinsertingthisinformationintothepathnameofthefilethatisusedtosatisfytherequest.Thiscanbemosteasilydonebyusingmod_vhost_aliaswithApache2.0.Alternatively,mod_rewritecanbeused.Bothofthesemodulesaredisabledbydefault;youmustenableoneofthemwhenconfiguringandbuildingApacheifyouwanttousethistechnique.

Acoupleofthingsneedtobe`faked'tomakethedynamicvirtualhostlooklikeanormalone.Themostimportantistheservername,whichisusedbyApachetogenerateself-referentialURLsetc.ItisconfiguredwiththeServerNamedirective,anditisavailabletoCGIsviatheSERVER_NAMEenvironmentvariable.TheactualvalueusedatruntimeiscontrolledbytheUseCanonicalNamesetting.WithUseCanonicalNameOff,theservernameistakenfromthecontentsoftheHost:headerintherequest.WithUseCanonicalNameDNS,itistakenfromareverseDNSlookupofthevirtualhost'sIPaddress.Theformersettingisusedforname-baseddynamicvirtualhosting,andthelatterisusedforIP-basedhosting.IfApachecannotworkouttheservernamebecausethereisnoHost:header,ortheDNSlookupfails,thenthevalueconfiguredwithServerNameisusedinstead.

Theotherthingto`fake'isthedocumentroot(configuredwithDocumentRootandavailabletoCGIsviatheDOCUMENT_ROOTenvironmentvariable).Inanormalconfiguration,thisisusedbythecoremodulewhenmappingURIstofilenames,butwhentheserverisconfiguredtododynamicvirtualhosting,thatjobmustbetakenoverbyanothermodule(eithermod_vhost_aliasormod_rewrite),whichhasadifferentwayofdoingthemapping.

NeitherofthesemodulesisresponsibleforsettingtheDOCUMENT_ROOTenvironmentvariablesoifanyCGIsorSSIdocumentsmakeuseofit,theywillgetamisleadingvalue.

SimpleDynamicVirtualHosts

Thisextractfromhttpd.confimplementsthevirtualhostarrangementoutlinedintheMotivationsectionabove,butinagenericfashionusingmod_vhost_alias.

#gettheservernamefromtheHost:header

UseCanonicalNameOff

#thislogformatcanbesplitper-virtual-hostbasedonthe

firstfield

LogFormat"%V%h%l%u%t\"%r\"%s%b"vcommon

CustomLoglogs/access_logvcommon

#includetheservernameinthefilenamesusedtosatisfy

requests

VirtualDocumentRoot/www/hosts/%0/docs

VirtualScriptAlias/www/hosts/%0/cgi-bin

ThisconfigurationcanbechangedintoanIP-basedvirtualhostingsolutionbyjustturningUseCanonicalNameOffintoUseCanonicalNameDNS.TheservernamethatisinsertedintothefilenameisthenderivedfromtheIPaddressofthevirtualhost.

AVirtuallyHostedHomepagesSystem

Thisisanadjustmentoftheabovesystem,tailoredforanISP'shomepagesserver.Usingaslightlymorecomplicatedconfiguration,wecanselectsubstringsoftheservernametouseinthefilenamesothat,forexample,thedocumentsforwww.user.isp.comarefoundin/home/user/.Itusesasinglecgi-bindirectoryinsteadofonepervirtualhost.

#allthepreliminarystuffisthesameasabove,then

#includepartoftheservernameinthefilenames

VirtualDocumentRoot/www/hosts/%2/docs

#singlecgi-bindirectory

ScriptAlias/cgi-bin//www/std-cgi/

ThereareexamplesofmorecomplicatedVirtualDocumentRootsettingsinthemod_vhost_aliasdocumentation.

UsingMultipleVirtualHostingSystemsontheSameServer

Withmorecomplicatedsetups,youcanuseApache'snormal<VirtualHost>directivestocontrolthescopeofthevariousvirtualhostingconfigurations.Forexample,youcouldhaveoneIPaddressforgeneralcustomers'homepages,andanotherforcommercialcustomers,withthefollowingsetup.Thiscan,ofcourse,becombinedwithconventional<VirtualHost>configurationsections.

UseCanonicalNameOff

LogFormat"%V%h%l%u%t\"%r\"%s%b"vcommon

AllowOverrideAll

</Directory>

AllowOverrideNone

</Directory>

ServerNamewww.commercial.isp.com

CustomLoglogs/access_log.commercialvcommon

VirtualDocumentRoot/www/commercial/%0/docs

VirtualScriptAlias/www/commercial/%0/cgi-bin

</VirtualHost>

ServerNamewww.homepages.isp.com

CustomLoglogs/access_log.homepagesvcommon

VirtualDocumentRoot/www/homepages/%0/docs

</VirtualHost>

MoreEfficientIP-BasedVirtualHosting

TheconfigurationchangessuggestedtoturnthefirstexampleintoanIP-basedvirtualhostingsetupresultinaratherinefficientsetup.AnewDNSlookupisrequiredforeveryrequest.Toavoidthisoverhead,thefilesystemcanbearrangedtocorrespondtotheIPaddresses,insteadoftothehostnames,therebynegatingtheneedforaDNSlookup.Loggingwillalsohavetobeadjustedtofitthissystem.

#gettheservernamefromthereverseDNSoftheIPaddress

UseCanonicalNameDNS

#includetheIPaddressinthelogssotheymaybesplit

LogFormat"%A%h%l%u%t\"%r\"%s%b"vcommon

#includetheIPaddressinthefilenames

VirtualDocumentRootIP/www/hosts/%0/docs

VirtualScriptAliasIP/www/hosts/%0/cgi-bin

SimpleDynamicVirtualHostsUsingmod_rewrite

Thisextractfromhttpd.confdoesthesamethingasthefirstexample.Thefirsthalfisverysimilartothecorrespondingpartabove,exceptforsomechanges,requiredforbackwardcompatibilityandtomakethemod_rewritepartworkproperly;thesecondhalfconfiguresmod_rewritetodotheactualwork.

Thereareacoupleofespeciallytrickybits:bydefault,mod_rewriterunsbeforeotherURItranslationmodules(mod_aliasetc.)-soifyouwishtousethesemodules,mod_rewritemustbeconfiguredtoaccommodatethem.Also,somemagicisrequiredtodoaper-dynamic-virtual-hostequivalentofScriptAlias.

#gettheservernamefromtheHost:header

UseCanonicalNameOff

#splittablelogs

LogFormat"%{Host}i%h%l%u%t\"%r\"%s%b"vcommon

#ExecCGIisneededherebecausewecan'tforce

#CGIexecutioninthewaythatScriptAliasdoes

OptionsFollowSymLinksExecCGI

</Directory>

#nowforthehardbit

RewriteEngineOn

#aServerNamederivedfromaHost:headermaybeanycaseat

##dealwithnormaldocumentsfirst:

#allowAlias/icons/towork-repeatforotheraliases

RewriteCond%{REQUEST_URI}!^/icons/

#allowCGIstowork

RewriteCond%{REQUEST_URI}!^/cgi-bin/

#dothemagic

RewriteRule^/(.*)$/www/hosts/${lowercase:%

{SERVER_NAME}}/docs/$1

##andnowdealwithCGIs-wehavetoforceaMIMEtype

RewriteCond%{REQUEST_URI}^/cgi-bin/

RewriteRule^/(.*)$/www/hosts/${lowercase:%{SERVER_NAME}}/cgi-

bin/$1[T=application/x-httpd-cgi]

#that'sit!

AHomepagesSystemUsingmod_rewrite

Thisdoesthesamethingasthesecondexample.

RewriteEngineon

#allowCGIstowork

#checkthehostnameisrightsothattheRewriteRuleworks

RewriteCond${lowercase:%{SERVER_NAME}}^www\.[a-z-

]+\.isp\.com$

#concatenatethevirtualhostnameontothestartoftheURI

#the[C]meansdothenextrewriteontheresultofthisone

RewriteRule^(.+)${lowercase:%{SERVER_NAME}}$1[C]

#nowcreatetherealfilename

RewriteRule^www\.([a-z-]+)\.isp\.com/(.*)/home/$1/$2

#definetheglobalCGIdirectory

UsingaSeparateVirtualHostConfigurationFile

Thisarrangementusesmoreadvancedmod_rewritefeaturestoworkoutthetranslationfromvirtualhosttodocumentroot,fromaseparateconfigurationfile.Thisprovidesmoreflexibility,butrequiresmorecomplicatedconfiguration.

Thevhost.mapfileshouldlooksomethinglikethis:

www.customer-1.com/www/customers/1

www.customer-2.com/www/customers/2

www.customer-N.com/www/customers/N

Thehttpd.confshouldcontainthefollowing:

RewriteEngineon

#definethemapfile

RewriteMapvhosttxt:/www/conf/vhost.map

#dealwithaliasesasabove

RewriteCond%{REQUEST_URI}!^/icons/

RewriteCond${lowercase:%{SERVER_NAME}}^(.+)$

#thisdoesthefile-basedremap

RewriteRule^/(.*)$%1/docs/$1

RewriteCond%{REQUEST_URI}^/cgi-bin/

RewriteCond${lowercase:%{SERVER_NAME}}^(.+)$

RewriteRule^/(.*)$%1/cgi-bin/$1[T=application/x-httpd-cgi]

VirtualHostExamples

Thisdocumentattemptstoanswerthecommonly-askedquestionsaboutsettingupvirtualhosts.Thesescenariosarethoseinvolvingmultiplewebsitesrunningonasingleserver,vianame-basedorIP-basedvirtualhosts.

Runningseveralname-basedwebsitesonasingleIPaddress.

YourserverhasasingleIPaddress,andmultiplealiases(CNAMES)pointtothismachineinDNS.Youwanttorunawebserverforwww.example1.comandwww.example2.orgonthismachine.

CreatingvirtualhostconfigurationsonyourApacheserverdoesnotmagicallycauseDNSentriestobecreatedforthosehostnames.YoumusthavethenamesinDNS,resolvingtoyourIPaddress,ornobodyelsewillbeabletoseeyourwebsite.Youcanputentriesinyourhostsfileforlocaltesting,butthatwillworkonlyfromthemachinewiththosehostsentries.

Serverconfiguration#EnsurethatApachelistensonport80

Listen80

#ListenforvirtualhostrequestsonallIPaddresses

NameVirtualHost*:80

<VirtualHost*:80>

DocumentRoot/www/example1

ServerNamewww.example1.com

#Otherdirectiveshere

</VirtualHost>

<VirtualHost*:80>

ServerNamewww.example2.org

#Otherdirectiveshere

</VirtualHost>

Theasterisksmatchalladdresses,sothemainserverservesno

requests.Duetothefactthatwww.example1.comisfirstintheconfigurationfile,ithasthehighestpriorityandcanbeseenasthedefaultorprimaryserver.ThatmeansthatifarequestisreceivedthatdoesnotmatchoneofthespecifiedServerNamedirectives,itwillbeservedbythisfirstVirtualHost.

Youcan,ifyouwish,replace*withtheactualIPaddressofthesystem.Inthatcase,theargumenttoVirtualHostmustmatchtheargumenttoNameVirtualHost:

#etc...

However,itisadditionallyusefultouse*onsystemswheretheIPaddressisnotpredictable-forexampleifyouhaveadynamicIPaddresswithyourISP,andyouareusingsomevarietyofdynamicDNSsolution.Since*matchesanyIPaddress,thisconfigurationwouldworkwithoutchangeswheneveryourIPaddresschanges.

Theaboveconfigurationiswhatyouwillwanttouseinalmostallname-basedvirtualhostingsituations.Theonlythingthatthisconfigurationwillnotworkfor,infact,iswhenyouareservingdifferentcontentbasedondifferingIPaddressesorports.

Name-basedhostsonmorethanoneIPaddress.

AnyofthetechniquesdiscussedherecanbeextendedtoanynumberofIPaddresses.

TheserverhastwoIPaddresses.Onone(172.20.30.40),wewillservethe"main"server,server.domain.comandontheother(172.20.30.50),wewillservetwoormorevirtualhosts.

ServerconfigurationListen80

#Thisisthe"main"serverrunningon172.20.30.40

ServerNameserver.domain.com

DocumentRoot/www/mainserver

#Thisistheotheraddress

#Otherdirectiveshere...

</VirtualHost>

#Otherdirectiveshere...

</VirtualHost>

Anyrequesttoanaddressotherthan172.20.30.50willbeservedfromthemainserver.Arequestto172.20.30.50withanunknownhostname,ornoHost:header,willbeservedfromwww.example1.com.

ServingthesamecontentondifferentIPaddresses(suchasaninternalandexternaladdress).

TheservermachinehastwoIPaddresses(192.168.1.1and172.20.30.40).Themachineissittingbetweenaninternal(intranet)networkandanexternal(internet)network.Outsideofthenetwork,thenameserver.example.comresolvestotheexternaladdress(172.20.30.40),butinsidethenetwork,thatsamenameresolvestotheinternaladdress(192.168.1.1).

Theservercanbemadetorespondtointernalandexternalrequestswiththesamecontent,withjustoneVirtualHostsection.

ServerconfigurationNameVirtualHost192.168.1.1

<VirtualHost192.168.1.1172.20.30.40>

DocumentRoot/www/server1

ServerNameserver.example.com

ServerAliasserver

</VirtualHost>

NowrequestsfrombothnetworkswillbeservedfromthesameVirtualHost.

Ontheinternalnetwork,onecanjustusethenameserverratherthanthefullyqualifiedhostnameserver.example.com.

Notealsothat,intheaboveexample,youcanreplacethelistofIPaddresseswith*,whichwillcausetheservertorespondthesameonalladdresses.

Runningdifferentsitesondifferentports.

YouhavemultipledomainsgoingtothesameIPandalsowanttoservemultipleports.Bydefiningtheportsinthe"NameVirtualHost"tag,youcanallowthistowork.Ifyoutryusing<VirtualHostname:port>withouttheNameVirtualHostname:portoryoutrytousetheListendirective,yourconfigurationwillnotwork.

Listen8080

NameVirtualHost172.20.30.40:80

<VirtualHost172.20.30.40:80>

DocumentRoot/www/domain-80

</VirtualHost>

<VirtualHost172.20.30.40:8080>

DocumentRoot/www/domain-8080

</VirtualHost>

<VirtualHost172.20.30.40:80>

DocumentRoot/www/otherdomain-80

</VirtualHost>

<VirtualHost172.20.30.40:8080>

DocumentRoot/www/otherdomain-8080

</VirtualHost>

IP-basedvirtualhosting

TheserverhastwoIPaddresses(172.20.30.40and172.20.30.50)whichresolvetothenameswww.example1.comandwww.example2.orgrespectively.

</VirtualHost>

Requestsforanyaddressnotspecifiedinoneofthe<VirtualHost>directives(suchaslocalhost,forexample)willgotothemainserver,ifthereisone.

Mixedport-basedandip-basedvirtualhosts

TheservermachinehastwoIPaddresses(172.20.30.40and172.20.30.50)whichresolvetothenameswww.example1.comandwww.example2.orgrespectively.Ineachcase,wewanttorunhostsonports80and8080.

ServerconfigurationListen172.20.30.40:80

Listen172.20.30.40:8080

Listen172.20.30.50:80

Listen172.20.30.50:8080

<VirtualHost172.20.30.40:80>

DocumentRoot/www/example1-80

</VirtualHost>

<VirtualHost172.20.30.40:8080>

</VirtualHost>

<VirtualHost172.20.30.50:80>

</VirtualHost>

<VirtualHost172.20.30.50:8080>

</VirtualHost>

Mixedname-basedandIP-basedvhosts

Onsomeofmyaddresses,Iwanttodoname-basedvirtualhosts,andonothers,IP-basedhosts.

</VirtualHost>

ServerNamewww.example3.net

</VirtualHost>

#IP-based

ServerNamewww.example4.edu

</VirtualHost>

ServerNamewww.example5.gov

</VirtualHost>

UsingVirtual_hostandmod_proxytogether

Thefollowingexampleallowsafront-endmachinetoproxyavirtualhostthroughtoaserverrunningonanothermachine.Intheexample,avirtualhostofthesamenameisconfiguredonamachineat192.168.111.2.TheProxyPreserveHostOndirectiveisusedsothatthedesiredhostnameispassedthrough,incaseweareproxyingmultiplehostnamestoasinglemachine.

<VirtualHost*:*>

ProxyPreserveHostOn

ProxyPass/http://192.168.111.2/

ProxyPassReverse/http://192.168.111.2/

ServerNamehostname.example.com

</VirtualHost>

Using_default_vhosts

_default_vhostsforallportsCatchingeveryrequesttoanyunspecifiedIPaddressandport,i.e.,anaddress/portcombinationthatisnotusedforanyothervirtualhost.

Serverconfiguration<VirtualHost_default_:*>

DocumentRoot/www/default

</VirtualHost>

Usingsuchadefaultvhostwithawildcardporteffectivelypreventsanyrequestgoingtothemainserver.

Adefaultvhostneverservesarequestthatwassenttoanaddress/portthatisusedforname-basedvhosts.IftherequestcontainedanunknownornoHost:headeritisalwaysservedfromtheprimaryname-basedvhost(thevhostforthataddress/portappearingfirstintheconfigurationfile).

YoucanuseAliasMatchorRewriteRuletorewriteanyrequesttoasingleinformationpage(orscript).

_default_vhostsfordifferentportsSameassetup1,buttheserverlistensonseveralportsandwewanttouseasecond_default_vhostforport80.

Serverconfiguration<VirtualHost_default_:80>

DocumentRoot/www/default80

</VirtualHost>

<VirtualHost_default_:*>

</VirtualHost>

Thedefaultvhostforport80(whichmustappearbeforeanydefaultvhostwithawildcardport)catchesallrequeststhatweresenttoanunspecifiedIPaddress.Themainserverisneverusedtoservearequest.

_default_vhostsforoneportWewanttohaveadefaultvhostforport80,butnootherdefaultvhosts.

Serverconfiguration<VirtualHost_default_:80>

</VirtualHost>

Arequesttoanunspecifiedaddressonport80isservedfromthedefaultvhostanyotherrequesttoanunspecifiedaddressandportisservedfromthemainserver.

Migratinganame-basedvhosttoanIP-basedvhost

Thename-basedvhostwiththehostnamewww.example2.org(fromourname-basedexample,setup2)shouldgetitsownIPaddress.ToavoidproblemswithnameserversorproxieswhocachedtheoldIPaddressforthename-basedvhostwewanttoprovidebothvariantsduringamigrationphase.Thesolutioniseasy,becausewecansimplyaddthenewIPaddress(172.20.30.50)totheVirtualHostdirective.

<VirtualHost172.20.30.40172.20.30.50>

</VirtualHost>

ServerNamewww.example3.net

ServerAlias*.example3.net

</VirtualHost>

Thevhostcannowbeaccessedthroughthenewaddress(asanIP-basedvhost)andthroughtheoldaddress(asaname-basedvhost).

UsingtheServerPathdirective

Wehaveaserverwithtwoname-basedvhosts.InordertomatchthecorrectvirtualhostaclientmustsendthecorrectHost:header.OldHTTP/1.0clientsdonotsendsuchaheaderandApachehasnocluewhatvhosttheclienttriedtoreach(andservestherequestfromtheprimaryvhost).ToprovideasmuchbackwardcompatibilityaspossiblewecreateaprimaryvhostwhichreturnsasinglepagecontaininglinkswithanURLprefixtothename-basedvirtualhosts.

ServerconfigurationNameVirtualHost172.20.30.40

#primaryvhost

DocumentRoot/www/subdomain

RewriteEngineOn

RewriteRule^/.*/www/subdomain/index.html

</VirtualHost>

DocumentRoot/www/subdomain/sub1

ServerNamewww.sub1.domain.tld

ServerPath/sub1/

RewriteEngineOn

RewriteRule^(/sub1/.*)/www/subdomain$1

</VirtualHost>

DocumentRoot/www/subdomain/sub2

ServerNamewww.sub2.domain.tld

ServerPath/sub2/

RewriteEngineOn

RewriteRule^(/sub2/.*)/www/subdomain$1

</VirtualHost>

DuetotheServerPathdirectivearequesttotheURLhttp://www.sub1.domain.tld/sub1/isalwaysservedfromthesub1-vhost.

ArequesttotheURLhttp://www.sub1.domain.tld/isonlyservedfromthesub1-vhostiftheclientsentacorrectHost:header.IfnoHost:headerissenttheclientgetstheinformationpagefromtheprimaryhost.Pleasenotethatthereisoneoddity:Arequesttohttp://www.sub2.domain.tld/sub1/isalsoservedfromthesub1-vhostiftheclientsentnoHost:header.TheRewriteRuledirectivesareusedtomakesurethataclientwhichsentacorrectHost:headercanusebothURLvariants,i.e.,withorwithoutURLprefix.

AnIn-DepthDiscussionofVirtualHostMatching

ThevirtualhostcodewascompletelyrewritteninApache1.3.ThisdocumentattemptstoexplainexactlywhatApachedoeswhendecidingwhatvirtualhosttoserveahitfrom.WiththehelpofthenewNameVirtualHostdirectivevirtualhostconfigurationshouldbealoteasierandsaferthanwithversionspriorto1.3.

Ifyoujustwanttomakeitworkwithoutunderstandinghow,herearesomeexamples.

ConfigFileParsing

Thereisamain_serverwhichconsistsofallthedefinitionsappearingoutsideof<VirtualHost>sections.Therearevirtualservers,calledvhosts,whicharedefinedby<VirtualHost>sections.

ThedirectivesListen,ServerName,ServerPath,andServerAliascanappearanywherewithinthedefinitionofaserver.However,eachappearanceoverridesthepreviousappearance(withinthatserver).

ThedefaultvalueoftheListenfieldformain_serveris80.Themain_serverhasnodefaultServerPath,orServerAlias.ThedefaultServerNameisdeducedfromtheserver'sIPaddress.

Themain_serverListendirectivehastwofunctions.OnefunctionistodeterminethedefaultnetworkportApachewillbindto.ThesecondfunctionistospecifytheportnumberwhichisusedinabsoluteURIsduringredirects.

Unlikethemain_server,vhostportsdonotaffectwhatportsApachelistensforconnectionson.

EachaddressappearingintheVirtualHostdirectivecanhaveanoptionalport.Iftheportisunspecifieditdefaultstothevalueofthemain_server'smostrecentListenstatement.Thespecialport*indicatesawildcardthatmatchesanyport.Collectivelytheentiresetofaddresses(includingmultipleArecordresultsfromDNSlookups)arecalledthevhost'saddressset.

UnlessaNameVirtualHostdirectiveisusedforaspecificIPaddressthefirstvhostwiththataddressistreatedasanIP-basedvhost.TheIPaddresscanalsobethewildcard*.

Ifname-basedvhostsshouldbeusedaNameVirtualHost

directivemustappearwiththeIPaddresssettobeusedforthename-basedvhosts.Inotherwords,youmustspecifytheIPaddressthatholdsthehostnamealiases(CNAMEs)foryourname-basedvhostsviaaNameVirtualHostdirectiveinyourconfigurationfile.

MultipleNameVirtualHostdirectivescanbeusedeachwithasetofVirtualHostdirectivesbutonlyoneNameVirtualHostdirectiveshouldbeusedforeachspecificIP:portpair.

TheorderingofNameVirtualHostandVirtualHostdirectivesisnotimportantwhichmakesthefollowingtwoexamplesidentical(onlytheorderoftheVirtualHostdirectivesforoneaddresssetisimportant,seebelow):

NameVirtualHost

111.22.33.44

<VirtualHost

111.22.33.44>

#serverA

</VirtualHost>

<VirtualHost

111.22.33.44>

#serverB

</VirtualHost>

NameVirtualHost

111.22.33.55

<VirtualHost

111.22.33.55>

#serverC

</VirtualHost>

<VirtualHost

111.22.33.55>

#serverD

</VirtualHost>

<VirtualHost

111.22.33.44>

#serverA

</VirtualHost>

<VirtualHost

111.22.33.55>

#serverC

</VirtualHost>

<VirtualHost

111.22.33.44>

#serverB

</VirtualHost>

<VirtualHost

111.22.33.55>

#serverD

</VirtualHost>

NameVirtualHost

111.22.33.44

NameVirtualHost

111.22.33.55

(Toaidthereadabilityofyourconfigurationyoushouldprefertheleftvariant.)

AfterparsingtheVirtualHostdirective,thevhostserverisgivenadefaultListenequaltotheportassignedtothefirstnameinitsVirtualHostdirective.

ThecompletelistofnamesintheVirtualHostdirectivearetreatedjustlikeaServerAlias(butarenotoverriddenbyanyServerAliasstatement)ifallnamesresolvetothesameaddressset.NotethatsubsequentListenstatementsforthisvhostwillnotaffecttheportsassignedintheaddressset.

DuringinitializationalistforeachIPaddressisgeneratedandinsertedintoanhashtable.IftheIPaddressisusedinaNameVirtualHostdirectivethelistcontainsallname-basedvhostsforthegivenIPaddress.IftherearenovhostsdefinedforthataddresstheNameVirtualHostdirectiveisignoredandanerrorislogged.ForanIP-basedvhostthelistinthehashtableisempty.

DuetoafasthashingfunctiontheoverheadofhashinganIPaddressduringarequestisminimalandalmostnotexistent.AdditionallythetableisoptimizedforIPaddresseswhichvaryinthelastoctet.

Foreveryvhostvariousdefaultvaluesareset.Inparticular:

1. IfavhosthasnoServerAdmin,Timeout,KeepAliveTimeout,KeepAlive,MaxKeepAliveRequests,ReceiveBufferSize,orSendBufferSizedirectivethentherespectivevalueisinheritedfromthemain_server.(Thatis,inheritedfromwhateverthefinalsettingofthatvalueisinthemain_server.)

2. The"lookupdefaults"thatdefinethedefaultdirectorypermissionsforavhostaremergedwiththoseofthemain_server.Thisincludesanyper-directoryconfigurationinformationforanymodule.

3. Theper-serverconfigsforeachmodulefromthemain_serveraremergedintothevhostserver.

Essentially,themain_serveristreatedas"defaults"ora"base"onwhichtobuildeachvhost.Butthepositioningofthesemain_serverdefinitionsintheconfigfileislargelyirrelevant--theentireconfigofthemain_serverhasbeenparsedwhenthisfinalmergingoccurs.Soevenifamain_serverdefinitionappearsafteravhostdefinitionitmightaffectthevhostdefinition.

Ifthemain_serverhasnoServerNameatthispoint,thenthehostnameofthemachinethathttpdisrunningonisusedinstead.Wewillcallthemain_serveraddresssetthoseIPaddressesreturnedbyaDNSlookupontheServerNameofthemain_server.

ForanyundefinedServerNamefields,aname-basedvhostdefaultstotheaddressgivenfirstintheVirtualHoststatementdefiningthevhost.

Anyvhostthatincludesthemagic_default_wildcardisgiventhesameServerNameasthemain_server.

VirtualHostMatching

Theserverdetermineswhichvhosttouseforarequestasfollows:

HashtablelookupWhentheconnectionisfirstmadebyaclient,theIPaddresstowhichtheclientconnectedislookedupintheinternalIPhashtable.

Ifthelookupfails(theIPaddresswasn'tfound)therequestisservedfromthe_default_vhostifthereissuchavhostfortheporttowhichtheclientsenttherequest.Ifthereisnomatching_default_vhosttherequestisservedfromthemain_server.

IftheIPaddressisnotfoundinthehashtablethenthematchagainsttheportnumbermayalsoresultinanentrycorrespondingtoaNameVirtualHost*,whichissubsequentlyhandledlikeothername-basedvhosts.

Ifthelookupsucceeded(acorrespondinglistfortheIPaddresswasfound)thenextstepistodecideifwehavetodealwithanIP-basedoraname-basevhost.

IP-basedvhostIftheentrywefoundhasanemptynamelistthenwehavefoundanIP-basedvhost,nofurtheractionsareperformedandtherequestisservedfromthatvhost.

Name-basedvhostIftheentrycorrespondstoaname-basedvhostthenamelistcontainsoneormorevhoststructures.ThislistcontainsthevhostsinthesameorderastheVirtualHostdirectivesappearintheconfigfile.

Thefirstvhostonthislist(thefirstvhostintheconfigfilewiththespecifiedIPaddress)hasthehighestpriorityandcatchesanyrequesttoanunknownservernameorarequestwithoutaHost:headerfield.

IftheclientprovidedaHost:headerfieldthelistissearchedforamatchingvhostandthefirsthitonaServerNameorServerAliasistakenandtherequestisservedfromthatvhost.AHost:headerfieldcancontainaportnumber,butApachealwaysmatchesagainsttherealporttowhichtheclientsenttherequest.

IftheclientsubmittedaHTTP/1.0requestwithoutHost:headerfieldwedon'tknowtowhatservertheclienttriedtoconnectandanyexistingServerPathismatchedagainsttheURIfromtherequest.Thefirstmatchingpathonthelistisusedandtherequestisservedfromthatvhost.

IfnomatchingvhostcouldbefoundtherequestisservedfromthefirstvhostwithamatchingportnumberthatisonthelistfortheIPtowhichtheclientconnected(asalreadymentionedbefore).

PersistentconnectionsTheIPlookupdescribedaboveisonlydoneonceforaparticularTCP/IPsessionwhilethenamelookupisdoneoneveryrequestduringaKeepAlive/persistentconnection.Inotherwordsaclientmayrequestpagesfromdifferentname-basedvhostsduringasinglepersistentconnection.

AbsoluteURIIftheURIfromtherequestisanabsoluteURI,anditshostnameandportmatchthemainserveroroneoftheconfiguredvirtualhostsandmatchtheaddressandporttowhichtheclientsentthe

request,thenthescheme/hostname/portprefixisstrippedoffandtheremainingrelativeURIisservedbythecorrespondingmainserverorvirtualhost.Ifitdoesnotmatch,thentheURIremainsuntouchedandtherequestistakentobeaproxyrequest.

ObservationsAname-basedvhostcanneverinterferewithanIP-basevhostandviceversa.IP-basedvhostscanonlybereachedthroughanIPaddressofitsownaddresssetandneverthroughanyotheraddress.Thesameappliestoname-basedvhosts,theycanonlybereachedthroughanIPaddressofthecorrespondingaddresssetwhichmustbedefinedwithaNameVirtualHostdirective.ServerAliasandServerPathchecksareneverperformedforanIP-basedvhost.Theorderofname-/IP-based,the_default_vhostandtheNameVirtualHostdirectivewithintheconfigfileisnotimportant.Onlytheorderingofname-basedvhostsforaspecificaddresssetissignificant.Theonename-basedvhoststhatcomesfirstintheconfigurationfilehasthehighestpriorityforitscorrespondingaddressset.ForsecurityreasonstheportnumbergiveninaHost:headerfieldisneverusedduringthematchingprocess.Apachealwaysusestherealporttowhichtheclientsenttherequest.IfaServerPathdirectiveexistswhichisaprefixofanotherServerPathdirectivethatappearslaterintheconfigurationfile,thentheformerwillalwaysbematchedandthelatterwillneverbematched.(ThatisassumingthatnoHost:headerfieldwasavailabletodisambiguatethetwo.)IftwoIP-basedvhostshaveanaddressincommon,thevhostappearingfirstintheconfigfileisalwaysmatched.Suchathingmighthappeninadvertently.Theserverwillgivea

warningintheerrorlogfilewhenitdetectsthis.A_default_vhostcatchesarequestonlyifthereisnoothervhostwithamatchingIPaddressandamatchingportnumberfortherequest.Therequestisonlycaughtiftheportnumbertowhichtheclientsenttherequestmatchestheportnumberofyour_default_vhostwhichisyourstandardListenbydefault.Awildcardportcanbespecified(i.e.,_default_:*)tocatchrequeststoanyavailableport.ThisalsoappliestoNameVirtualHost*vhosts.Themain_serverisonlyusedtoservearequestiftheIPaddressandportnumbertowhichtheclientconnectedisunspecifiedanddoesnotmatchanyothervhost(includinga_default_vhost).Inotherwordsthemain_serveronlycatchesarequestforanunspecifiedaddress/portcombination(unlessthereisa_default_vhostwhichmatchesthatport).A_default_vhostorthemain_serverisnevermatchedforarequestwithanunknownormissingHost:headerfieldiftheclientconnectedtoanaddress(andport)whichisusedforname-basedvhosts,e.g.,inaNameVirtualHostdirective.YoushouldneverspecifyDNSnamesinVirtualHostdirectivesbecauseitwillforceyourservertorelyonDNStoboot.FurthermoreitposesasecuritythreatifyoudonotcontroltheDNSforallthedomainslisted.There'smoreinformationavailableonthisandthenexttwotopics.ServerNameshouldalwaysbesetforeachvhost.OtherwiseADNSlookupisrequiredforeachvhost.

InadditiontothetipsontheDNSIssuespage,herearesomefurthertips:

Placeallmain_serverdefinitionsbeforeanyVirtualHostdefinitions.(Thisistoaidthereadabilityoftheconfiguration--thepost-configmergingprocessmakesitnon-obviousthatdefinitionsmixedinaroundvirtualhostsmightaffectallvirtualhosts.)GroupcorrespondingNameVirtualHostandVirtualHostdefinitionsinyourconfigurationtoensurebetterreadability.AvoidServerPathswhichareprefixesofotherServerPaths.Ifyoucannotavoidthisthenyouhavetoensurethatthelonger(morespecific)prefixvhostappearsearlierintheconfigurationfilethantheshorter(lessspecific)prefix(i.e.,"ServerPath/abc"shouldappearafter"ServerPath/abc/def").

||FAQ||

20 Unix 64

Apache

1. setrlimit()

2. setrlimit(RLIMIT_NOFILE) (Solaris2.3)

4. stdio256

<VirtualHost>12 Apache

#!/bin/sh

ulimit-S-n100

exechttpd

||FAQ||

LogFormat %v:

LogFormat"%v%h%l%u%t\"%r\"%>s%b"vhost

CustomLoglogs/multiple_vhost_logvhost

commonlogformat( ServerName)(CustomLogFormats)

(1) split-logfileApachesupport

split-logfile</logs/multiple_vhost_log

||FAQ||

DNSApache

Apache DNSApache

<VirtualHostwww.abc.dom>

ServerAdminwebgirl@abc.dom

DocumentRoot/www/abc

</VirtualHost>

Apache ApacheDNS www.abc.dom DNS1.2)

www.abc.dom10.0.0.1

</VirtualHost>

ApacheDNS ServerName

IP URLURL

ServerNamewww.abc.dom

</VirtualHost>

() Apache1.2abc.dom DNS www.abc.dom

<VirtualHostwww.abc.dom>

</VirtualHost>

<VirtualHostwww.def.dom>

ServerAdminwebguy@def.dom

DocumentRoot/www/def

</VirtualHost>

10.0.0.1 www.abc.dom 10.0.0.2 www.def.domdef.domDNS abc.dom

www.def.dom10.0.0.1 DNSDNSwww.def.dom

10.0.0.1 (http://www.abc.dom/whateverURLdef.dom

Apache1.1 ApachehttpdIP ServerName C gethostname(DNS DNS

DNS OS /etc/resolv.conf

/etc/nsswitch.conf

DNS HOSTRESORDER localmod_env CGImanOS

VirtualHostIPListenIP ServerName <VirtualHost_default_:*>

||FAQ||

DNSApache1.2 DNS

DNSDNSDNS )

HTTP/1.1 HostIP

ApacheHTTPServerVersion2.0Apache>HTTPServer>Documentation>Version2.0>FAQ

Support-FrequentlyAskedQuestions

Support

"Whycan'tI...?Whywon't...work?"WhattodoincaseofproblemsWhomdoIcontactforsupport?

"Whycan'tI...?Whywon't...work?"WhattodoincaseofproblemsIfyouarehavingtroublewithyourApacheserversoftware,youshouldtakethefollowingsteps:

Checktheerrorlog!Apachetriestobehelpfulwhenitencountersaproblem.Inmanycases,itwillprovidesomedetailsbywritingoneormessagestotheservererrorlog.Sometimesthisisenoughforyoutodiagnose&fixtheproblemyourself(suchasfilepermissionsorthelike).Thedefaultlocationoftheerrorlogis/usr/local/apache2/logs/error_log,butseetheErrorLogdirectiveinyourconfigfilesforthelocationonyourserver.

ChecktheFAQ!ThelatestversionoftheApacheFrequently-AskedQuestionslistcanalwaysbefoundatthemainApachewebsite.

ChecktheApachebugdatabaseMostproblemsthatgetreportedtoTheApacheGrouparerecordedinthebugdatabase.Pleasechecktheexistingreports,openandclosed,beforeaddingone.Ifyoufindthatyourissuehasalreadybeenreported,pleasedon'tadda"me,too"report.Iftheoriginalreportisn'tclosedyet,wesuggestthatyoucheckitperiodically.Youmightalsoconsidercontactingtheoriginalsubmitter,becausetheremaybeanemailexchangegoingonabouttheissuethatisn'tgettingrecordedinthedatabase.

AskinausersupportforumApachehasanactivecommunityofuserswhoarewillingtosharetheirknowledge.Participatinginthiscommunityisusuallythebestandfastestwaytogetanswerstoyourquestionsandproblems.

Usersmailinglist

#httpdonFreenodeIRCisavailableforusersupportissues.

USENETnewsgroups:

comp.infosystems.www.servers.unix[news][google]comp.infosystems.www.servers.ms-windows[news][google]comp.infosystems.www.authoring.cgi[news][google]

Ifallelsefails,reporttheprobleminthebugdatabaseIfyou'vegonethroughthosestepsabovethatareappropriateandhaveobtainednorelief,thenpleasedoletthehttpddevelopersknowabouttheproblembyloggingabugreport.

Ifyourprobleminvolvestheservercrashingandgeneratingacoredump,pleaseincludeabacktrace(ifpossible).Asanexample,

#cdServerRoot

#dbxhttpdcore

(dbx)where

(SubstitutetheappropriatelocationsforyourServerRootandyourhttpdandcorefiles.Youmayhavetousegdbinsteadofdbx.)

WhomdoIcontactforsupport?

Withseveralmillionusersandfewerthanfortyvolunteerdevelopers,wecannotprovidepersonalsupportforApache.Forfreesupport,wesuggestparticipatinginauserforum.

ErrorMessages-FrequentlyAskedQuestions

ErrorMessages

Invalidargument:core_output_filter:writingdatatothenetworkAcceptExfailedPrematureendofscriptheaders

Invalidargument:core_output_filter:writingdatatothenetworkApacheusesthesendfilesyscallonplatformswhereitisavailableinordertospeedsendingofresponses.Unfortunately,onsomesystems,Apachewilldetectthepresenceofsendfileatcompile-time,evenwhenitdoesnotworkproperly.Thishappensmostfrequentlywhenusingnetworkorothernon-standardfile-system.

Symptomsofthisproblemincludetheabovemessageintheerrorlogandzero-lengthresponsestonon-zero-sizedfiles.Theproblemgenerallyoccursonlyforstaticfiles,sincedynamiccontentusuallydoesnotmakeuseofsendfile.

Tofixthisproblem,simplyusetheEnableSendfiledirectivetodisablesendfileforallorpartofyourserver.AlsoseetheEnableMMAP,whichcanhelpwithsimilarproblems.

AcceptExFailedIfyougeterrormessagesrelatedtotheAcceptExsyscallonwin32,seetheWin32DisableAcceptExdirective.

PrematureendofscriptheadersMostproblemswithCGIscriptsresultinthismessagewrittenintheerrorlogtogetherwithanInternalServerErrordeliveredtothebrowser.Aguidetohelpingdebugthistypeof

problemisavailableintheCGItutorial.

||FAQ||

ApacheHTTP2.0Apache>HTTP>>2.0 >SSL/TLS

SSL/TLS:

--A.Tanenbaum,"IntroductiontoComputerNetworks"

WebHTTPApacheSSL mod_ssl

TheOpenGroupResearchInstitute FrederickJ.HirschIntroducingSSLandCertificatesusingSSLeay WebSecurity:AMatterofTrust,WorldWideWebJournal,Volume2,Issue3,Summer1997 FrederickHirsch ()Engelschall(mod_ssl)[: Apache

SSL(:)([ AC96])

(CertificateAuthorityCA)(certificate)(authentication)

() ( 2)

CommonName() CNSSLURL

CN=www.example.com

OrganizationorCompany()

O O=ExampleJapanK.K.

OrganizationalUnit() OU OU=CustomerServiceCity/Locality() L L=SapporoState/Province() ST ST=HokkaidoCountry() C ISO C=JP

ASN.1 [X208][PKCS] EncodingRules(DER)BasicEncodingRules Base64[ MIME] ASCII"PrivacyEnhancedMail")

PEM(example.crt)-----BEGINCERTIFICATE-----

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

-----ENDCERTIFICATE-----

Thawte VeriSign :

SecureSocketsLayer(SSL)

SecureSocketsLayer(TCP/IP)(HTTP)SSL

SSLv2.0

VendorStandard(NetscapeCorp.)[ SSL2]

SSL -NSNavigator1.x/2.x-MSIE3.x-Lynx/2.8+OpenSSL

SSLv3.0

ExpiredInternetDraft(NetscapeCorp.)[ SSL3]

RSA-NSNavigator2.x/3.x/4.x-MSIE3.x/4.x-Lynx/2.8+OpenSSL

TLSv1.0

ProposedInternetStandard(IETF)[ TLS1]

MACHMACblockpadding3.0

-Lynx/2.8+OpenSSL

4SSLSSL3.0SSL3.0InternetEngineeringTaskForce(IETF)TransportLayerSecurity[TLS]

MessageAuthenticationCode(MAC)

Hellman

SSL () :

40-bitRC4128-bitRC4

CBC40bitRC240bitDES56bitDES168bitTriple-DESIdea(128bit)Fortezza(96bit)

CBC(CipherBlockChaining) EncryptionStandard)[AC96,ch12] DES403DES_EDE Idea RC2RSADSI

MD5(128-bit)SecureHashAlgorithm(SHA-1)(160-bit)

MessageAuthenticationCode(MAC)

SSLSSLSSLSSLSSL

3SSL SSL

3 :SSL

HTTPSSLHTTP HTTPHTTPS URL http https(443)mod_sslApache

[AC96]BruceSchneier,AppliedCryptography,2ndEdition,Wiley,1996.Seehttp://www.counterpane.com/forvariousothermaterialsbyBruceSchneier.

[X208]ITU-TRecommendationX.208,SpecificationofAbstractSyntaxNotationOne(ASN.1),1988.Seeforinstancehttp://www.itu.int/rec/recommendation.asp?type=items&lang=e&parent=T-REC-X.208-198811-I.

[X509]ITU-TRecommendationX.509,TheDirectory-AuthenticationFramework.Seeforinstancehttp://www.itu.int/rec/recommendation.asp?type=folders&lang=e&parent=T-REC-X.509.

[PKCS]PublicKeyCryptographyStandards(PKCS),RSALaboratoriesTechnicalNotes,Seehttp://www.rsasecurity.com/rsalabs/pkcs/.

[MIME]N.Freed,N.Borenstein,MultipurposeInternetMailExtensions(MIME)PartOne:FormatofInternetMessageBodies,RFC2045.Seeforinstancehttp://ietf.org/rfc/rfc2045.txt.

[SSL2]KippE.B.Hickman,TheSSLProtocol,1995.Seehttp://www.netscape.com/eng/security/SSL_2.html.

[SSL3]AlanO.Freier,PhilipKarlton,PaulC.Kocher,TheSSLProtocolVersion3.0,1996.Seehttp://www.netscape.com/eng/ssl3/draft302.txt.

||FAQ||

[TLS1]TimDierks,ChristopherAllen,TheTLSProtocolVersion1.0,1999.Seehttp://ietf.org/rfc/rfc2246.txt.

ApacheHTTPServerVersion2.0Apache>HTTPServer>Documentation>Version2.0>SSL/TLS

SSL/TLSStrongEncryption:Compatibility

AllPCsarecompatible.Butsomeofthemaremorecompatiblethanothers.

--Unknown

HerewetalkaboutbackwardcompatibilitytootherSSLsolutions.Asyouperhapsknow,mod_sslisnottheonlyexistingSSLsolutionforApache.Actuallytherearefouradditionalmajorproductsavailableonthemarket:BenLaurie'sfreelyavailableApache-SSL(fromwheremod_sslwereoriginallyderivedin1998),RedHat'scommercialSecureWebServer(whichisbasedonmod_ssl),Covalent'scommercialRavenSSLModule(alsobasedonmod_ssl)andfinallyC2Net'scommercialproductStronghold(basedonadifferentevolutionbranchnamedSiouxuptoStronghold2.xandbasedonmod_sslsinceStronghold3.x).

Theideainmod_sslismainlythefollowing:becausemod_sslprovidesmostlyasupersetofthefunctionalityofallothersolutionswecaneasilyprovidebackwardcompatibilityformostofthecases.Actuallytherearethreecompatibilityareaswecurrentlyaddress:configurationdirectives,environmentvariablesandcustomlogfunctions.

ConfigurationDirectives

ForbackwardcompatibilitytotheconfigurationdirectivesofotherSSLsolutionswedoanon-the-flymapping:directiveswhichhaveadirectcounterpartinmod_sslaremappedsilentlywhileotherdirectivesleadtoawarningmessageinthelogfiles.ThecurrentlyimplementeddirectivemappingislistedinTable1.CurrentlyfullbackwardcompatibilityisprovidedonlyforApache-SSL1.xandmod_ssl2.0.x.CompatibilitytoSioux1.xandStronghold2.xisonlypartialbecauseofspecialfunctionalityintheseinterfaceswhichmod_ssl(still)doesn'tprovide.

Table1:ConfigurationDirectiveMappingOldDirective mod_sslDirectiveApache-SSL1.x&mod_ssl2.0.xcompatibility:SSLEnable SSLEngineon

SSLDisable SSLEngineoff

SSLLogFilefile SSLLogfileSSLRequiredCiphersspec SSLCipherSuitespecSSLRequireCipherc1... SSLRequire%

{SSL_CIPHER}in

{"c1",...}SSLBanCipherc1... SSLRequirenot(%

{SSL_CIPHER}in

{"c1",...})SSLFakeBasicAuth SSLOptions

+FakeBasicAuth

SSLCacheServerPathdir -SSLCacheServerPortinteger -

Apache-SSL1.xcompatibility:SSLExportClientCertificates SSLOptions

+ExportCertData

SSLCacheServerRunDirdir -

Sioux1.xcompatibility:SSL_CertFilefile SSLCertificateFilefileSSL_KeyFilefile SSLCertificateKeyFile

fileSSL_CipherSuitearg SSLCipherSuiteargSSL_X509VerifyDirarg SSLCACertificatePath

argSSL_Logfile SSLLogFilefileSSL_Connectflag SSLEngineflagSSL_ClientAutharg SSLVerifyClientargSSL_X509VerifyDeptharg SSLVerifyDepthargSSL_FetchKeyPhraseFromarg -

SSL_SessionDirdir -

SSL_Requireexpr -

SSL_CertFileTypearg -

SSL_KeyFileTypearg -

SSL_X509VerifyPolicyarg -

SSL_LogX509Attributesarg -

Stronghold2.xcompatibility:StrongholdAcceleratordir -

StrongholdKeydir -

StrongholdLicenseFiledir -

SSLFlagflag SSLEngineflagSSLSessionLockFilefile SSLMutexfileSSLCipherListspec SSLCipherSuitespecRequireSSL SSLRequireSSL

SSLErrorFilefile -

SSLRootdir -

SSL_CertificateLogDirdir -

AuthCertDirdir -

SSL_Groupname -

SSLProxyMachineCertPathdir -

SSLProxyMachineCertFilefile -

SSLProxyCACertificatePath

SSLProxyCACertificateFile

SSLProxyVerifyDepthnumber -

SSLProxyCipherListspec -

EnvironmentVariables

Whenyouuse``SSLOptions+CompatEnvVars''additionalenvironmentvariablesaregenerated.Theyallcorrespondtoexistingofficialmod_sslvariables.ThecurrentlyimplementedvariablederivationislistedinTable2.

Table2:EnvironmentVariableDerivationOldVariable mod_sslVariableSSL_PROTOCOL_VERSION SSL_PROTOCOL

SSLEAY_VERSION SSL_VERSION_LIBRARY

HTTPS_SECRETKEYSIZE SSL_CIPHER_USEKEYSIZE

HTTPS_KEYSIZE SSL_CIPHER_ALGKEYSIZE

HTTPS_CIPHER SSL_CIPHER

HTTPS_EXPORT SSL_CIPHER_EXPORT

SSL_SERVER_KEY_SIZE SSL_CIPHER_ALGKEYSIZE

SSL_SERVER_CERTIFICATE SSL_SERVER_CERT

SSL_SERVER_CERT_START SSL_SERVER_V_START

SSL_SERVER_CERT_END SSL_SERVER_V_END

SSL_SERVER_CERT_SERIAL SSL_SERVER_M_SERIAL

SSL_SERVER_SIGNATURE_ALGORITHM SSL_SERVER_A_SIG

SSL_SERVER_DN SSL_SERVER_S_DN

SSL_SERVER_CN SSL_SERVER_S_DN_CN

SSL_SERVER_EMAIL SSL_SERVER_S_DN_Email

SSL_SERVER_O SSL_SERVER_S_DN_O

SSL_SERVER_OU SSL_SERVER_S_DN_OU

SSL_SERVER_C SSL_SERVER_S_DN_C

SSL_SERVER_SP SSL_SERVER_S_DN_SP

SSL_SERVER_L SSL_SERVER_S_DN_L

SSL_SERVER_IDN SSL_SERVER_I_DN

SSL_SERVER_ICN SSL_SERVER_I_DN_CN

SSL_SERVER_IEMAIL SSL_SERVER_I_DN_Email

SSL_SERVER_IO SSL_SERVER_I_DN_O

SSL_SERVER_IOU SSL_SERVER_I_DN_OU

SSL_SERVER_IC SSL_SERVER_I_DN_C

SSL_SERVER_ISP SSL_SERVER_I_DN_SP

SSL_SERVER_IL SSL_SERVER_I_DN_L

SSL_CLIENT_CERTIFICATE SSL_CLIENT_CERT

SSL_CLIENT_CERT_START SSL_CLIENT_V_START

SSL_CLIENT_CERT_END SSL_CLIENT_V_END

SSL_CLIENT_CERT_SERIAL SSL_CLIENT_M_SERIAL

SSL_CLIENT_SIGNATURE_ALGORITHM SSL_CLIENT_A_SIG

SSL_CLIENT_DN SSL_CLIENT_S_DN

SSL_CLIENT_CN SSL_CLIENT_S_DN_CN

SSL_CLIENT_EMAIL SSL_CLIENT_S_DN_Email

SSL_CLIENT_O SSL_CLIENT_S_DN_O

SSL_CLIENT_OU SSL_CLIENT_S_DN_OU

SSL_CLIENT_C SSL_CLIENT_S_DN_C

SSL_CLIENT_SP SSL_CLIENT_S_DN_SP

SSL_CLIENT_L SSL_CLIENT_S_DN_L

SSL_CLIENT_IDN SSL_CLIENT_I_DN

SSL_CLIENT_ICN SSL_CLIENT_I_DN_CN

SSL_CLIENT_IEMAIL SSL_CLIENT_I_DN_Email

SSL_CLIENT_IO SSL_CLIENT_I_DN_O

SSL_CLIENT_IOU SSL_CLIENT_I_DN_OU

SSL_CLIENT_IC SSL_CLIENT_I_DN_C

SSL_CLIENT_ISP SSL_CLIENT_I_DN_SP

SSL_CLIENT_IL SSL_CLIENT_I_DN_L

SSL_EXPORT SSL_CIPHER_EXPORT

SSL_KEYSIZE SSL_CIPHER_ALGKEYSIZE

SSL_SECKEYSIZE SSL_CIPHER_USEKEYSIZE

SSL_SSLEAY_VERSION SSL_VERSION_LIBRARY

SSL_STRONG_CRYPTO -

SSL_SERVER_KEY_EXP -

SSL_SERVER_KEY_ALGORITHM -

SSL_SERVER_KEY_SIZE -

SSL_SERVER_SESSIONDIR -

SSL_SERVER_CERTIFICATELOGDIR -

SSL_SERVER_CERTFILE -

SSL_SERVER_KEYFILE -

SSL_SERVER_KEYFILETYPE -

SSL_CLIENT_KEY_EXP -

SSL_CLIENT_KEY_ALGORITHM -

SSL_CLIENT_KEY_SIZE -

CustomLogFunctions

Whenmod_sslisbuiltintoApacheoratleastloaded(underDSOsituation)additionalfunctionsexistfortheCustomLogFormatofmod_log_configasdocumentedintheReferenceChapter.Besidethe``%{varname}x''eXtensionformatfunctionwhichcanbeusedtoexpandanyvariablesprovidedbyanymodule,anadditionalCryptography``%{name}c''cryptographyformatfunctionexistsforbackwardcompatibility.ThecurrentlyimplementedfunctioncallsarelistedinTable3.

Table3:CustomLogCryptographyFunctionFunctionCall Description%...{version}c SSLprotocolversion%...{cipher}c SSLcipher%...

{subjectdn}c

ClientCertificateSubjectDistinguishedName

%...{issuerdn}c ClientCertificateIssuerDistinguishedName

%...{errcode}c CertificateVerificationError(numerical)%...{errstr}c CertificateVerificationError(string)

SSL/TLSStrongEncryption:How-To

Thesolutionofthisproblemistrivialandisleftasanexerciseforthereader.

--Standardtextbookcookie

HowtosolveparticularsecurityconstraintsforanSSL-awarewebserverisnotalwaysobviousbecauseofthecoherencesbetweenSSL,HTTPandApache'swayofprocessingrequests.Thischaptergivesinstructionsonhowtosolvesuchtypicalsituations.Treatitasafirststeptofindoutthefinalsolution,butalwaystrytounderstandthestuffbeforeyouuseit.Nothingisworsethanusingasecuritysolutionwithoutknowingitsrestrictionsandcoherences.

CipherSuitesandEnforcedStrongSecurity

SSLv2onlyserverstrongencryptiononlyserverservergatedcryptographystrongerper-directoryrequirements

HowcanIcreatearealSSLv2-onlyserver?ThefollowingcreatesanSSLserverwhichspeaksonlytheSSLv2protocolanditsciphers.

httpd.confSSLProtocol-all+SSLv2

SSLCipherSuiteSSLv2:+HIGH:+MEDIUM:+LOW:+EXP

HowcanIcreateanSSLserverwhichacceptsstrongencryptiononly?Thefollowingenablesonlythestrongestciphers:

httpd.confSSLProtocolall-SSLv2

SSLCipherSuiteHIGH:!aNULL:!MD5

HowcanIcreateanSSLserverwhichacceptsstrongencryptiononly,butallowsexportbrowserstoupgradetostrongerencryption?ThisfacilityiscalledServerGatedCryptography(SGC)anddetailsyoucanfindintheREADME.GlobalIDdocumentinthemod_ssldistribution.Inshort:TheserverhasaGlobalIDservercertificate,signedbyaspecialCAcertificatefromVerisignwhichenablesstrongencryptioninexportbrowsers.Thisworksasfollowing:Thebrowserconnectswithanexportcipher,theserversendsitsGlobalIDcertificate,thebrowserverifiesitand

subsequentlyupgradestheciphersuitebeforeanyHTTPcommunicationtakesplace.Thequestionnowis:Howcanweallowthisupgrade,butenforcestrongencryption.Orinotherwords:Browsereitherhavetoinitiallyconnectwithstrongencryptionorhavetoupgradetostrongencryption,butarenotallowedtokeeptheexportciphers.Thefollowingdoesthetrick:

httpd.conf#allowallciphersfortheinitialhandshake,

#soexportbrowserscanupgradeviaSGCfacility

SSLCipherSuite

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

#butfinallydenyallbrowserswhichhaven'tupgraded

SSLRequire%{SSL_CIPHER_USEKEYSIZE}>=128

</Directory>

HowcanIcreateanSSLserverwhichacceptsalltypesofciphersingeneral,butrequiresastrongciphersforaccesstoaparticularURL?Obviouslyyoucannotjustuseaserver-wideSSLCipherSuitewhichrestrictsthecipherstothestrongvariants.Butmod_sslallowsyoutoreconfiguretheciphersuiteinper-directorycontextandautomaticallyforcesarenegotiationoftheSSLparameterstomeetthenewconfiguration.So,thesolutionis:

#beliberalingeneral

SSLCipherSuite

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

#buthttps://hostname/strong/area/andbelow

#requiresstrongciphers

SSLCipherSuiteHIGH:!aNULL:!MD5

</Location>

ClientAuthenticationandAccessControl

simplecertificate-basedclientauthenticationselectivecertificate-basedclientauthenticationparticularcertificate-basedclientauthenticationintranetvs.internetauthentication

HowcanIauthenticateclientsbasedoncertificateswhenIknowallmyclients?Whenyouknowyourusercommunity(i.e.aclosedusergroupsituation),asit'sthecaseforinstanceinanIntranet,youcanuseplaincertificateauthentication.AllyouhavetodoistocreateclientcertificatessignedbyyourownCAcertificateca.crtandthenverifytheclientsagainstthiscertificate.

httpd.conf#requireaclientcertificatewhichhastobedirectly

#signedbyourCAcertificateinca.crt

SSLVerifyClientrequire

SSLVerifyDepth1

SSLCACertificateFileconf/ssl.crt/ca.crt

HowcanIauthenticatemyclientsforaparticularURLbasedoncertificatesbutstillallowarbitraryclientstoaccesstheremainingpartsoftheserver?Forthisweagainusetheper-directoryreconfigurationfeatureofmod_ssl:

httpd.confSSLVerifyClientnone

SSLVerifyDepth1

</Location>

HowcanIauthenticateonlyparticularclientsforasomeURLsbasedoncertificatesbutstillallowarbitraryclientstoaccesstheremainingpartsoftheserver?Thekeyistocheckforvariousingredientsoftheclientcertificate.UsuallythismeanstocheckthewholeorpartoftheDistinguishedName(DN)oftheSubject.Forthistwomethodsexists:Themod_authbasedvariantandtheSSLRequirevariant.Thefirstmethodisgoodwhentheclientsareoftotallydifferenttype,i.e.whentheirDNshavenocommonfields(usuallytheorganisation,etc.).Inthiscaseyou'vetoestablishapassworddatabasecontainingallclients.ThesecondmethodisbetterwhenyourclientsareallpartofacommonhierarchywhichisencodedintotheDN.Thenyoucanmatchthemmoreeasily.

Thefirstmethod:

SSLVerifyDepth5

SSLCACertificatePathconf/ssl.crt

SSLOptions+FakeBasicAuth

SSLRequireSSL

AuthName"SnakeOilAuthentication"

AuthTypeBasic

AuthUserFile/usr/local/apache2/conf/httpd.passwd

requirevalid-user

</Directory>

ThepasswordusedinthisexampleistheDESencryptedstring"password".SeetheSSLOptionsdocsformoreinformation.

httpd.passwd

/C=DE/L=Munich/O=SnakeOil,Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA

/C=US/L=S.F./O=SnakeOil,Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA

/C=US/L=L.A./O=SnakeOil,Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA

Thesecondmethod:

SSLVerifyDepth5

SSLCACertificatePathconf/ssl.crt

SSLOptions+FakeBasicAuth

SSLRequireSSL

SSLRequire%{SSL_CLIENT_S_DN_O}eq"SnakeOil,Ltd."\

and%{SSL_CLIENT_S_DN_OU}in{"Staff","CA","Dev"}

</Directory>

HowcanIrequireHTTPSwithstrongciphersandeitherbasicauthenticationorclientcertificatesforaccesstoasubareaontheIntranetwebsiteforclientscomingfromtheInternetbutstillallowplainHTTPaccessforclientsontheIntranet?LetusassumetheIntranetcanbedistinguishedthroughtheIPnetwork192.168.1.0/24andthesubareaontheIntranetwebsitehastheURL/subarea.ThenconfigurethefollowingoutsideyourHTTPSvirtualhost(soitappliestobothHTTPSandHTTP):

httpd.confSSLCACertificateFileconf/ssl.crt/company-ca.crt

#OutsidethesubareaonlyIntranetaccessisgranted

Orderdeny,allow

Denyfromall

Allowfrom192.168.1.0/24

</Directory>

#InsidethesubareaanyIntranetaccessisallowed

#butfromtheInternetonlyHTTPS+Strong-Cipher+Password

#orthealternativeHTTPS+Strong-Cipher+Client-Certificate

#IfHTTPSisused,makesureastrongcipherisused.

#Additionallyallowclientcertsasalternativetobasicauth.

SSLVerifyClientoptional

SSLVerifyDepth1

SSLOptions+FakeBasicAuth+StrictRequire

SSLRequire%{SSL_CIPHER_USEKEYSIZE}>=128

#ForceclientsfromtheInternettouseHTTPS

RewriteEngineon

RewriteCond%{REMOTE_ADDR}!^192\.168\.1\.[0-9]+$

RewriteCond%{HTTPS}!=on

RewriteRule.*-[F]

#AllowNetworkAccessand/orBasicAuth

Satisfyany

#NetworkAccessControl

Orderdeny,allow

Denyfromall

Allow192.168.1.0/24

#HTTPBasicAuthentication

AuthTypebasic

AuthName"ProtectedIntranetArea"

AuthUserFileconf/protected.passwd

Requirevalid-user

</Directory>

SSL/TLSStrongEncryption:FAQ

Thewisemandoesn'tgivetherightanswers,heposestherightquestions.

--ClaudeLevi-Strauss

Thischapterisacollectionoffrequentlyaskedquestions(FAQ)andcorrespondinganswersfollowingthepopularUSENETtradition.MostofthesequestionsoccurredontheNewsgroupcomp.infosystems.www.servers.unixorthemod_sslSupportMailingListmodssl-users@modssl.org.Theyarecollectedatthisplacetoavoidansweringthesamequestionsoverandover.

Pleasereadthischapteratleastoncewheninstallingmod_ssloratleastsearchforyourproblemherebeforesubmittingaproblemreporttotheauthor.

AboutTheModule

Whatisthehistoryofmod_ssl?mod_sslandWassenaarArrangement?

Whatisthehistoryofmod_ssl?Themod_sslv1packagewasinitiallycreatedinApril1998byRalfS.EngelschallviaportingBenLaurie'sApache-SSL1.17sourcepatchesforApache1.2.6toApache1.3b6.BecauseofconflictswithBenLaurie'sdevelopmentcycleitthenwasre-assembledfromscratchforApache1.3.0bymergingtheoldmod_ssl1.xwiththenewerApache-SSL1.18.Fromthispointonmod_sslliveditsownlifeasmod_sslv2.Thefirstpubliclyreleasedversionwasmod_ssl2.0.0fromAugust10th,1998.

AfterUSexportrestrictionsoncryptographicsoftwarewereloosened,mod_sslbecamepartoftheApacheHTTPServerwiththereleaseofApachehttpd2.

Ismod_sslaffectedbytheWassenaarArrangement?First,letusexplainwhatWassenaaranditsArrangementonExportControlsforConventionalArmsandDual-UseGoodsandTechnologiesis:Thisisainternationalregime,establishedin1995,tocontroltradeinconventionalarmsanddual-usegoodsandtechnology.ItreplacedthepreviousCoComregime.FurtherdetailsonboththeArrangementanditssignatoriesareavailableathttp://www.wassenaar.org/.

Inshort,theaimoftheWassenaarArrangementistopreventthebuildupofmilitarycapabilitiesthatthreatenregionalandinternationalsecurityandstability.TheWassenaarArrangementcontrolstheexportofcryptographyasadual-usegood,thatis,somethingthathasbothmilitaryandcivilianapplications.However,theWassenaarArrangementalsoprovidesan

exemptionfromexportcontrolsformass-marketsoftwareandfreesoftware.

InthecurrentWassenaarListofDualUseGoodsandTechnologiesAndMunitions,under“GENERALSOFTWARENOTE(GSN)”itsays“TheListsdonotcontrol"software"whichiseither:1.[...]2."inthepublicdomain".”Andunder“DEFINITIONSOFTERMSUSEDINTHESELISTS”wefind“Inthepublicdomain”definedas“"technology"or"software"whichhasbeenmadeavailablewithoutrestrictionsuponitsfurtherdissemination.Note:Copyrightrestrictionsdonotremove"technology"or"software"frombeing"inthepublicdomain".”

So,bothmod_sslandOpenSSLare“inthepublicdomain”forthepurposesoftheWassenaarArrangementandits“ListofDualUseGoodsandTechnologiesAndMunitionsList”,andthusnotaffectedbyitsprovisions.

Installation

WhydoIgetpermissionerrorsrelatedtoSSLMutexwhenIstartApache?Whydoesmod_sslstopwiththeerror"Failedtogeneratetemporary512bitRSAprivatekey"whenIstartApache?

WhydoIgetpermissionerrorsrelatedtoSSLMutexwhenIstartApache?Errorssuchas``mod_ssl:ChildcouldnotopenSSLMutexlockfile

/opt/apache/logs/ssl_mutex.18332(Systemerror

follows)[...]System:Permissiondenied(errno:

13)''areusuallycausedbyoverlyrestrictivepermissionsontheparentdirectories.Makesurethatallparentdirectories(here/opt,/opt/apacheand/opt/apache/logs)havethex-bitsetfor,atminimum,theUIDunderwhichApache'schildrenarerunning(seetheUserdirective).

Whydoesmod_sslstopwiththeerror"Failedtogeneratetemporary512bitRSAprivatekey"whenIstartApache?Cryptographicsoftwareneedsasourceofunpredictabledatatoworkcorrectly.Manyopensourceoperatingsystemsprovidea"randomnessdevice"thatservesthispurpose(usuallynamed/dev/random).Onothersystems,applicationshavetoseedtheOpenSSLPseudoRandomNumberGenerator(PRNG)manuallywithappropriatedatabeforegeneratingkeysorperformingpublickeyencryption.Asofversion0.9.5,theOpenSSLfunctionsthatneedrandomnessreportanerrorifthePRNGhasnotbeenseededwithatleast128bitsofrandomness.

Topreventthiserror,mod_sslhastoprovideenoughentropytothePRNGtoallowittoworkcorrectly.Thiscanbedoneviathe

SSLRandomSeeddirective.

Configuration

IsitpossibletoprovideHTTPandHTTPSfromthesameserver?WhichportdoesHTTPSuse?HowdoIspeakHTTPSmanuallyfortestingpurposes?WhydoestheconnectionhangwhenIconnecttomySSL-awareApacheserver?WhydoIget``ConnectionRefused''errors,whentryingtoaccessmynewlyinstalledApache+mod_sslserverviaHTTPS?WhyaretheSSL_XXXvariablesnotavailabletomyCGI&SSIscripts?HowcanIswitchbetweenHTTPandHTTPSinrelativehyperlinks?

IsitpossibletoprovideHTTPandHTTPSfromthesameserver?Yes.HTTPandHTTPSusedifferentserverports(HTTPbindstoport80,HTTPStoport443),sothereisnodirectconflictbetweenthem.Youcaneitherruntwoseparateserverinstancesboundtotheseports,oruseApache'selegantvirtualhostingfacilitytocreatetwovirtualservers,bothservedbythesameinstanceofApache-onerespondingoverHTTPtorequestsonport80,andtheotherrespondingoverHTTPStorequestsonport443.

WhichportdoesHTTPSuse?YoucanrunHTTPSonanyport,butthestandardsspecifyport443,whichiswhereanyHTTPScompliantbrowserwilllookbydefault.YoucanforceyourbrowsertolookonadifferentportbyspecifyingitintheURL.Forexample,ifyourserverissetuptoservepagesoverHTTPSonport8080,youcanaccessthemathttps://example.com:8080/

HowdoIspeakHTTPSmanuallyfortestingpurposes?Whileyouusuallyjustuse

$telnetlocalhost80

GET/HTTP/1.0

forsimpletestingofApacheviaHTTP,it'snotsoeasyforHTTPSbecauseoftheSSLprotocolbetweenTCPandHTTP.WiththehelpofOpenSSL'ss_clientcommand,however,youcandoasimilarcheckviaHTTPS:

$openssls_client-connectlocalhost:443-state-debug

GET/HTTP/1.0

BeforetheactualHTTPresponseyouwillreceivedetailedinformationabouttheSSLhandshake.ForamoregeneralcommandlineclientwhichdirectlyunderstandsbothHTTPandHTTPS,canperformGETandPOSToperations,canuseaproxy,supportsbyteranges,etc.youshouldhavealookattheniftycURLtool.Usingthis,youcancheckthatApacheisrespondingcorrectlytorequestsviaHTTPandHTTPSasfollows:

$curlhttp://localhost/

$curlhttps://localhost/

WhydoestheconnectionhangwhenIconnecttomySSL-awareApacheserver?ThiscanhappenwhenyoutrytoconnecttoaHTTPSserver(orvirtualserver)viaHTTP(eg,usinghttp://example.com/insteadofhttps://example.com).ItcanalsohappenwhentryingtoconnectviaHTTPStoaHTTPserver(eg,usinghttps://example.com/onaserverwhichdoesn'tsupportHTTPS,orwhichsupportsitonanon-standardport).Makesure

thatyou'reconnectingtoa(virtual)serverthatsupportsSSL.

WhydoIget``ConnectionRefused''messages,whentryingtoaccessmynewlyinstalledApache+mod_sslserverviaHTTPS?Thiserrorcanbecausedbyanincorrectconfiguration.PleasemakesurethatyourListendirectivesmatchyour<VirtualHost>directives.Ifallelsefails,pleasestartafresh,usingthedefaultconfigurationprovidedbymod_ssl.

WhyaretheSSL_XXXvariablesnotavailabletomyCGI&SSIscripts?Pleasemakesureyouhave``SSLOptions+StdEnvVars''enabledforthecontextofyourCGI/SSIrequests.

HowcanIswitchbetweenHTTPandHTTPSinrelativehyperlinks?Usually,toswitchbetweenHTTPandHTTPS,youhavetousefully-qualifiedhyperlinks(becauseyouhavetochangetheURLscheme).Usingmod_rewritehowever,youcanmanipulaterelativehyperlinks,toachievethesameeffect.

RewriteEngineon

RewriteRule^/(.*):SSL$https://%{SERVER_NAME}/$1[R,L]

RewriteRule^/(.*):NOSSL$http://%{SERVER_NAME}/$1[R,L]

Thisrewriterulesetletsyouusehyperlinksoftheform<ahref="document.html:SSL">,toswitchtoHTTPSinarelativelink.(ReplaceSSLwithNOSSLtoswitchtoHTTP.)

Certificates

WhatareRSAPrivateKeys,CSRsandCertificates?Isthereadifferenceonstartupbetweenanon-SSL-awareApacheandanSSL-awareApache?HowdoIcreateaself-signedSSLCertificatefortestingpurposes?HowdoIcreatearealSSLCertificate?HowdoIcreateandusemyownCertificateAuthority(CA)?HowcanIchangethepass-phraseonmyprivatekeyfile?HowcanIgetridofthepass-phrasedialogatApachestartuptime?HowdoIverifythataprivatekeymatchesitsCertificate?Whydoconnectionsfailwithan"alertbadcertificate"error?Whydoesmy2048-bitprivatekeynotwork?WhyisclientauthenticationbrokenafterupgradingfromSSLeayversion0.8to0.9?HowcanIconvertacertificatefromPEMtoDERformat?Whycan'tIfindthegetcaorgetverisignprogramsmentionedbyVerisign,forinstallingmyVerisigncertificate?CanIusetheServerGatedCryptography(SGC)facility(akaVerisignGlobalID)withmod_ssl?WhydobrowserscomplainthattheycannotverifymyVerisignGlobalIDservercertificate?

WhatareRSAPrivateKeys,CSRsandCertificates?AnRSAprivatekeyfileisadigitalfilethatyoucanusetodecryptmessagessenttoyou.Ithasapubliccomponentwhichyoudistribute(viayourCertificatefile)whichallowspeopletoencryptthosemessagestoyou.

ACertificateSigningRequest(CSR)isadigitalfilewhichcontainsyourpublickeyandyourname.YousendtheCSRtoaCertifyingAuthority(CA),whowillconvertitintoarealCertificate,bysigningit.

ACertificatecontainsyourRSApublickey,yourname,thenameoftheCA,andisdigitallysignedbytheCA.BrowsersthatknowtheCAcanverifythesignatureonthatCertificate,therebyobtainingyourRSApublickey.Thatenablesthemtosendmessageswhichonlyyoucandecrypt.

SeetheIntroductionchapterforageneraldescriptionoftheSSLprotocol.

Isthereadifferenceonstartupbetweenanon-SSL-awareApacheandanSSL-awareApache?Yes.Ingeneral,startingApachewithmod_sslbuilt-inisjustlikestartingApachewithoutit.However,ifyouhaveapassphraseonyourSSLprivatekeyfile,astartupdialogwillpopupwhichasksyoutoenterthepassphrase.

Havingtomanuallyenterthepassphrasewhenstartingtheservercanbeproblematic-forexample,whenstartingtheserverfromthesystembootscripts.Inthiscase,youcanfollowthestepsbelowtoremovethepassphrasefromyourprivatekey.Bearinmindthatdoingsobringsadditionalsecurityrisks-proceedwithcaution!

HowdoIcreateaself-signedSSLCertificatefortestingpurposes?1. MakesureOpenSSLisinstalledandinyourPATH.

2. Runthefollowingcommand,tocreateserver.keyandserver.crtfiles:$opensslreq-new-x509-nodes-out

server.crt-keyoutserver.key

Thesecanbeusedasfollowsinyourhttpd.conffile:

SSLCertificateFile/path/to/this/server.crt

SSLCertificateKeyFile/path/to/this/server.key

3. Itisimportantthatyouareawarethatthisserver.keydoesnothaveanypassphrase.Toaddapassphrasetothekey,youshouldrunthefollowingcommand,andenter&verifythepassphraseasrequested.$opensslrsa-des3-inserver.key-out

server.key.new

$mvserver.key.newserver.key

Pleasebackuptheserver.keyfile,andthepassphraseyouentered,inasecurelocation.

HowdoIcreatearealSSLCertificate?Hereisastep-by-stepdescription:

1. MakesureOpenSSLisinstalledandinyourPATH.

2. CreateaRSAprivatekeyforyourApacheserver(willbeTriple-DESencryptedandPEMformatted):

$opensslgenrsa-des3-outserver.key1024

Pleasebackupthisserver.keyfileandthepass-phraseyouenteredinasecurelocation.YoucanseethedetailsofthisRSAprivatekeybyusingthecommand:

$opensslrsa-noout-text-inserver.key

Ifnecessary,youcanalsocreateadecryptedPEMversion(notrecommended)ofthisRSAprivatekeywith:

$opensslrsa-inserver.key-out

server.key.unsecure

3. CreateaCertificateSigningRequest(CSR)withtheserverRSAprivatekey(outputwillbePEMformatted):

$opensslreq-new-keyserver.key-out

server.csr

MakesureyouentertheFQDN("FullyQualifiedDomainName")oftheserverwhenOpenSSLpromptsyouforthe"CommonName",i.e.whenyougenerateaCSRforawebsitewhichwillbelateraccessedviahttps://www.foo.dom/,enter"www.foo.dom"here.YoucanseethedetailsofthisCSRbyusing

$opensslreq-noout-text-inserver.csr

4. YounowhavetosendthisCertificateSigningRequest(CSR)toaCertifyingAuthority(CA)tobesigned.OncetheCSRhasbeensigned,youwillhavearealCertificate,whichcanbeusedbyApache.YoucanhaveaCSRsignedbyacommercialCA,oryoucancreateyourownCAtosignit.CommercialCAsusuallyaskyoutoposttheCSRintoawebform,payforthesigning,andthensendasignedCertificate,whichyoucanstoreinaserver.crtfile.FormoreinformationaboutcommercialCAsseethefollowinglocations:

1. Verisignhttp://digitalid.verisign.com/server/apacheNotice.htm

2. Thawte

http://www.thawte.com/

3. CertiSignCertificadoraDigitalLtda.http://www.certisign.com.br

4. IKSGmbHhttp://www.iks-jena.de/leistungen/ca/

5. UptimeCommerceLtd.http://www.uptimecommerce.com

6. BelSignNV/SAhttp://www.belsign.be

FordetailsonhowtocreateyourownCA,andusethistosignaCSR,seebelow.OnceyourCSRhasbeensigned,youcanseethedetailsoftheCertificateasfollows:

$opensslx509-noout-text-inserver.crt

5. Youshouldnowhavetwofiles:server.keyandserver.crt.Thesecanbeusedasfollowsinyourhttpd.conffile:

SSLCertificateFile/path/to/this/server.crt

SSLCertificateKeyFile/path/to/this/server.key

Theserver.csrfileisnolongerneeded.

HowdoIcreateandusemyownCertificateAuthority(CA)?TheshortansweristousetheCA.shorCA.plscriptprovidedbyOpenSSL.Unlessyouhaveagoodreasonnotto,youshouldusetheseforpreference.Ifyoucannot,youcancreateaself-signedCertificateasfollows:

1. CreateaRSAprivatekeyforyourserver(willbeTriple-DESencryptedandPEMformatted):

$opensslgenrsa-des3-outserver.key1024

Pleasebackupthishost.keyfileandthepass-phraseyouenteredinasecurelocation.YoucanseethedetailsofthisRSAprivatekeybyusingthecommand:$opensslrsa-noout-text-inserver.key

Ifnecessary,youcanalsocreateadecryptedPEMversion(notrecommended)ofthisRSAprivatekeywith:

$opensslrsa-inserver.key-out

server.key.unsecure

2. Createaself-signedCertificate(X509structure)withtheRSAkeyyoujustcreated(outputwillbePEMformatted):

$opensslreq-new-x509-nodes-sha1-days

365-keyserver.key-outserver.crt

ThissignstheserverCSRandresultsinaserver.crtfile.YoucanseethedetailsofthisCertificateusing:

HowcanIchangethepass-phraseonmyprivatekeyfile?Yousimplyhavetoreaditwiththeoldpass-phraseandwriteitagain,specifyingthenewpass-phrase.Youcanaccomplishthis

withthefollowingcommands:

$opensslrsa-des3-inserver.key-out

server.key.new

$mvserver.key.newserver.key

Thefirsttimeyou'reaskedforaPEMpass-phrase,youshouldentertheoldpass-phrase.Afterthat,you'llbeaskedagaintoenterapass-phrase-thistime,usethenewpass-phrase.Ifyouareaskedtoverifythepass-phrase,you'llneedtoenterthenewpass-phraseasecondtime.

HowcanIgetridofthepass-phrasedialogatApachestartuptime?Thereasonthisdialogpopsupatstartupandeveryre-startisthattheRSAprivatekeyinsideyourserver.keyfileisstoredinencryptedformatforsecurityreasons.Thepass-phraseisneededtodecryptthisfile,soitcanbereadandparsed.Removingthepass-phraseremovesalayerofsecurityfromyourserver-proceedwithcaution!

1. RemovetheencryptionfromtheRSAprivatekey(whilekeepingabackupcopyoftheoriginalfile):

$cpserver.keyserver.key.org

$opensslrsa-inserver.key.org-out

server.key

2. Makesuretheserver.keyfileisonlyreadablebyroot:

$chmod400server.key

Nowserver.keycontainsanunencryptedcopyofthekey.Ifyou

pointyourserveratthisfile,itwillnotpromptyouforapass-phrase.HOWEVER,ifanyonegetsthiskeytheywillbeabletoimpersonateyouonthenet.PLEASEmakesurethatthepermissionsonthisfilearesuchthatonlyrootorthewebserverusercanreadit(preferablygetyourwebservertostartasrootbutrunasanotheruser,andhavethekeyreadableonlybyroot).

Asanalternativeapproachyoucanusethe``SSLPassPhraseDialogexec:/path/to/program''facility.Bearinmindthatthisisneithermorenorlesssecure,ofcourse.

HowdoIverifythataprivatekeymatchesitsCertificate?Aprivatekeycontainsaseriesofnumbers.Twoofthesenumbersformthe"publickey",theothersarepartofthe"privatekey".The"publickey"bitsareincludedwhenyougenerateaCSR,andsubsequentlyformpartoftheassociatedCertificate.

TocheckthatthepublickeyinyourCertificatematchesthepublicportionofyourprivatekey,yousimplyneedtocomparethesenumbers.ToviewtheCertificateandthekeyrunthecommands:

$opensslrsa-noout-text-inserver.key

The`modulus'andthe`publicexponent'portionsinthekeyandtheCertificatemustmatch.Asthepublicexponentisusually65537andit'sdifficulttovisuallycheckthatthelongmodulusnumbersarethesame,youcanusethefollowingapproach:

$opensslx509-noout-modulus-inserver.crt|

opensslmd5

$opensslrsa-noout-modulus-inserver.key|

opensslmd5

Thisleavesyouwithtworathershorternumberstocompare.Itis,intheory,possiblethatthesenumbersmaybethesame,withoutthemodulusnumbersbeingthesame,butthechancesofthisareoverwhelminglyremote.

ShouldyouwishtochecktowhichkeyorcertificateaparticularCSRbelongsyoucanperformthesamecalculationontheCSRasfollows:

$opensslreq-noout-modulus-inserver.csr|

opensslmd5

Whydoconnectionsfailwithan"alertbadcertificate"error?ErrorssuchasOpenSSL:error:14094412:SSLroutines:SSL3_READ_BYTES:sslv3alertbad

certificateintheSSLlogfile,areusuallycausedbyabrowserwhichisunabletohandletheservercertificate/private-key.Forexample,NetscapeNavigator3.xisunabletohandleRSAkeylengthsnotequalto1024bits.

Whydoesmy2048-bitprivatekeynotwork?TheprivatekeysizesforSSLmustbeeither512or1024bits,forcompatibilitywithcertainwebbrowsers.Akeysizeof1024bitsisrecommendedbecausekeyslargerthan1024bitsareincompatiblewithsomeversionsofNetscapeNavigatorandMicrosoftInternetExplorer,andwithotherbrowsersthatuseRSA'sBSAFEcryptographytoolkit.

WhyisclientauthenticationbrokenafterupgradingfromSSLeayversion0.8to0.9?TheCAcertificatesunderthepathyouconfiguredwithSSLCACertificatePatharefoundbySSLeaythroughhash

symlinks.Thesehashvaluesaregeneratedbythe`opensslx509-noout-hash'command.However,thealgorithmusedtocalculatethehashforacertificatechangedbetweenSSLeay0.8and0.9.Youwillneedtoremovealloldhashsymlinksandcreatenewonesafterupgrading.UsetheMakefileprovidedbymod_ssl.

HowcanIconvertacertificatefromPEMtoDERformat?ThedefaultcertificateformatforSSLeay/OpenSSLisPEM,whichissimplyBase64encodedDER,withheaderandfooterlines.Forsomeapplications(e.g.MicrosoftInternetExplorer)youneedthecertificateinplainDERformat.YoucanconvertaPEMfilecert.pemintothecorrespondingDERfilecert.derusingthefollowingcommand:$opensslx509-incert.pem-outcert.der-outformDER

Whycan'tIfindthegetcaorgetverisignprogramsmentionedbyVerisign,forinstallingmyVerisigncertificate?VerisignhasneverprovidedspecificinstructionsforApache+mod_ssl.TheinstructionsprovidedareforC2Net'sStronghold(acommercialApachebasedserverwithSSLsupport).

Toinstallyourcertificate,allyouneedtodoistosavethecertificatetoafile,andgivethenameofthatfiletotheSSLCertificateFiledirective.Youwillalsoneedtogiveitthekeyfile.Formoreinformation,seetheSSLCertificateKeyFiledirective.

CanIusetheServerGatedCryptography(SGC)

facility(akaVerisignGlobalID)withmod_ssl?Yes.mod_sslhasincludedsupportfortheSGCfacilitysinceversion2.1.Nospecialconfigurationisrequired-justusetheGlobalIDasyourservercertificate.Thestepupoftheclientsisthenautomaticallyhandledbymod_sslatrun-time.

WhydobrowserscomplainthattheycannotverifymyVerisignGlobalIDservercertificate?VerisignusesanintermediateCAcertificatebetweentherootCAcertificate(whichisinstalledinthebrowsers)andtheservercertificate(whichyouinstalledontheserver).YoushouldhavereceivedthisadditionalCAcertificatefromVerisign.Ifnot,complaintothem.Then,configurethiscertificatewiththeSSLCertificateChainFiledirective.ThisensuresthattheintermediateCAcertificateissenttothebrowser,fillingthegapinthecertificatechain.

TheSSLProtocol

WhydoIgetlotsofrandomSSLprotocolerrorsunderheavyserverload?Whydoesmywebserverhaveahigherload,nowthatitservesSSLencryptedtraffic?WhydoHTTPSconnectionstomyserversometimestakeupto30secondstoestablishaconnection?WhatSSLCiphersaresupportedbymod_ssl?WhydoIget``nosharedcipher''errors,whentryingtouseAnonymousDiffie-Hellman(ADH)ciphers?WhydoIgeta'nosharedciphers'errorwhenconnectingtomynewlyinstalledserver?Whycan'tIuseSSLwithname-based/non-IP-basedvirtualhosts?WhyisitnotpossibletouseName-BasedVirtualHostingtoidentifydifferentSSLvirtualhosts?HowdoIgetSSLcompressionworking?WhenIuseBasicAuthenticationoverHTTPSthelockiconinNetscapebrowsersstaysunlockedwhenthedialogpopsup.Doesthismeantheusername/passwordisbeingsentunencrypted?WhydoIgetI/OerrorswhenconnectingviaHTTPStoanApache+mod_sslserverwithMicrosoftInternetExplorer(MSIE)?WhydoIgetI/Oerrors,orthemessage"Netscapehasencounteredbaddatafromtheserver",whenconnectingviaHTTPStoanApache+mod_sslserverwithNetscapeNavigator?

WhydoIgetlotsofrandomSSLprotocolerrorsunderheavyserverload?Therecanbeanumberofreasonsforthis,butthemainoneisproblemswiththeSSLsessionCachespecifiedbythe

SSLSessionCachedirective.TheDBMsessioncacheisthemostlikelysourceoftheproblem,sousingtheSHMsessioncache(ornocacheatall)mayhelp.

Whydoesmywebserverhaveahigherload,nowthatitservesSSLencryptedtraffic?SSLusesstrongcryptographicencryption,whichnecessitatesalotofnumbercrunching.WhenyourequestawebpageviaHTTPS,everything(eventheimages)isencryptedbeforeitistransferred.SoincreasedHTTPStrafficleadstoloadincreases.

WhydoHTTPSconnectionstomyserversometimestakeupto30secondstoestablishaconnection?Thisisusuallycausedbya/dev/randomdeviceforSSLRandomSeedwhichblockstheread(2)calluntilenoughentropyisavailabletoservicetherequest.MoreinformationisavailableinthereferencemanualfortheSSLRandomSeeddirective.

WhatSSLCiphersaresupportedbymod_ssl?Usually,anySSLcipherssupportedbytheversionofOpenSSLinuse,arealsosupportedbymod_ssl.WhichciphersareavailablecandependonthewayyoubuiltOpenSSL.Typically,atleastthefollowingciphersaresupported:

1. RC4withMD5

2. RC4withMD5(exportversionrestrictedto40-bitkey)

3. RC2withMD5

4. RC2withMD5(exportversionrestrictedto40-bitkey)

5. IDEAwithMD5

6. DESwithMD5

7. Triple-DESwithMD5

Todeterminetheactuallistofciphersavailable,youshouldrunthefollowing:

$opensslciphers-v

WhydoIget``nosharedcipher''errors,whentryingtouseAnonymousDiffie-Hellman(ADH)ciphers?Bydefault,OpenSSLdoesnotallowADHciphers,forsecurityreasons.Pleasebesureyouareawareofthepotentialside-effectsifyouchoosetoenabletheseciphers.

InordertouseAnonymousDiffie-Hellman(ADH)ciphers,youmustbuildOpenSSLwith``-DSSL_ALLOW_ADH'',andthenadd``ADH''intoyourSSLCipherSuite.

WhydoIgeta'nosharedciphers'errorwhenconnectingtomynewlyinstalledserver?EitheryouhavemadeamistakewithyourSSLCipherSuitedirective(compareitwiththepre-configuredexampleinhttpd.conf-dist)oryouchosetouseDSA/DHalgorithmsinsteadofRSAwhenyougeneratedyourprivatekeyandignoredoroverlookedthewarnings.IfyouhavechosenDSA/DH,thenyourservercannotcommunicateusingRSA-basedSSLciphers(atleastuntilyouconfigureanadditionalRSA-basedcertificate/keypair).ModernbrowserslikeNSorIEcanonlycommunicateoverSSLusingRSAciphers.Theresultisthe"nosharedciphers"error.Tofixthis,regenerateyourservercertificate/keypair,usingtheRSAalgorithm.

Whycan'tIuseSSLwithname-based/non-IP-basedvirtualhosts?Thereasonisverytechnical,andasomewhat"chickenandegg"problem.TheSSLprotocollayerstaysbelowtheHTTPprotocollayerandencapsulatesHTTP.WhenanSSLconnection(HTTPS)isestablishedApache/mod_sslhastonegotiatetheSSLprotocolparameterswiththeclient.Forthis,mod_sslhastoconsulttheconfigurationofthevirtualserver(forinstanceithastolookfortheciphersuite,theservercertificate,etc.).ButinordertogotothecorrectvirtualserverApachehastoknowtheHostHTTPheaderfield.Todothis,theHTTPrequestheaderhastoberead.ThiscannotbedonebeforetheSSLhandshakeisfinished,buttheinformationisneededinordertocompletetheSSLhandshakephase.Bingo!

WhyisitnotpossibletouseName-BasedVirtualHostingtoidentifydifferentSSLvirtualhosts?Name-BasedVirtualHostingisaverypopularmethodofidentifyingdifferentvirtualhosts.ItallowsyoutousethesameIPaddressandthesameportnumberformanydifferentsites.WhenpeoplemoveontoSSL,itseemsnaturaltoassumethatthesamemethodcanbeusedtohavelotsofdifferentSSLvirtualhostsonthesameserver.

Itcomesasratherashocktolearnthatitisimpossible.

ThereasonisthattheSSLprotocolisaseparatelayerwhichencapsulatestheHTTPprotocol.SotheSSLsessionisaseparatetransaction,thattakesplacebeforetheHTTPsessionhasbegun.TheserverreceivesanSSLrequestonIPaddressXandportY(usually443).SincetheSSLrequestdoesnotcontainanyHost:field,theserverhasnowaytodecidewhichSSLvirtualhosttouse.Usually,itwilljustusethefirstoneitfinds,whichmatchestheportandIPaddressspecified.

Youcan,ofcourse,useName-BasedVirtualHostingtoidentifymanynon-SSLvirtualhosts(allonport80,forexample)andthenhaveasingleSSLvirtualhost(onport443).Butifyoudothis,youmustmakesuretoputthenon-SSLportnumberontheNameVirtualHostdirective,e.g.

Otherworkaroundsolutionsinclude:

UsingseparateIPaddressesfordifferentSSLhosts.UsingdifferentportnumbersfordifferentSSLhosts.

HowdoIgetSSLcompressionworking?AlthoughSSLcompressionnegotiationwasdefinedinthespecificationofSSLv2andTLS,ittookuntilMay2004forRFC3749todefineDEFLATEasanegotiablestandardcompressionmethod.

OpenSSL0.9.8startedtosupportthisbydefaultwhencompiledwiththezliboption.Ifboththeclientandtheserversupportcompression,itwillbeused.However,mostclientsstilltrytoinitiallyconnectwithanSSLv2Hello.AsSSLv2didnotincludeanarrayofpreferedcompressionalgorithmsinitshandshake,compressioncannotbenegotiatedwiththeseclients.IftheclientdisablessupportforSSLv2,eitheranSSLv3orTLSHellomaybesent,dependingonwhichSSLlibraryisused,andcompressionmaybesetup.YoucanverifywhetherclientsmakeuseofSSLcompressionbyloggingthe%{SSL_COMPRESS_METHOD}xvariable.

WhenIuseBasicAuthenticationoverHTTPSthelockiconinNetscapebrowsersstaysunlockedwhenthedialogpopsup.Doesthismeanthe

username/passwordisbeingsentunencrypted?No,theusername/passwordistransmittedencrypted.TheiconinNetscapebrowsersisnotactuallysynchronizedwiththeSSL/TLSlayer.Itonlytogglestothelockedstatewhenthefirstpartoftheactualwebpagedataistransferred,whichmayconfusepeople.TheBasicAuthenticationfacilityispartoftheHTTPlayer,whichisabovetheSSL/TLSlayerinHTTPS.BeforeanyHTTPdatacommunicationtakesplaceinHTTPS,theSSL/TLSlayerhasalreadycompleteditshandshakephase,andswitchedtoencryptedcommunication.Sodon'tbeconfusedbythisicon.

WhydoIgetI/OerrorswhenconnectingviaHTTPStoanApache+mod_sslserverwithMicrosoftInternetExplorer(MSIE)?ThefirstreasonisthattheSSLimplementationinsomeMSIEversionshassomesubtlebugsrelatedtotheHTTPkeep-alivefacilityandtheSSLclosenotifyalertsonsocketconnectionclose.AdditionallytheinteractionbetweenSSLandHTTP/1.1featuresareproblematicinsomeMSIEversions.YoucanworkaroundtheseproblemsbyforcingApachenottouseHTTP/1.1,keep-aliveconnectionsorsendtheSSLclosenotifymessagestoMSIEclients.ThiscanbedonebyusingthefollowingdirectiveinyourSSL-awarevirtualhostsection:

SetEnvIfUser-Agent".*MSIE.*"\

nokeepalivessl-unclean-shutdown\

downgrade-1.0force-response-1.0

Further,someMSIEversionshaveproblemswithparticularciphers.Unfortunately,itisnotpossibletoimplementaMSIE-specificworkaroundforthis,becausetheciphersareneededasearlyastheSSLhandshakephase.SoaMSIE-specificSetEnvIfwon'tsolvetheseproblems.Instead,youwillhavetomakemoredrasticadjustmentstotheglobalparameters.Before

youdecidetodothis,makesureyourclientsreallyhaveproblems.Ifnot,donotmakethesechanges-theywillaffectallyourclients,MSIEorotherwise.

Thenextproblemisthat56bitexportversionsofMSIE5.xbrowsershaveabrokenSSLv3implementation,whichinteractsbadlywithOpenSSLversionsgreaterthan0.9.4.Youcanacceptthisandrequireyourclientstoupgradetheirbrowsers,youcandowngradetoOpenSSL0.9.4(notadvised),oryoucanworkaroundthis,acceptingthatyourworkaroundwillaffectotherbrowserstoo:

SSLProtocolall-SSLv3

willcompletelydisablestheSSLv3protocolandallowthosebrowserstowork.Abetterworkaroundistodisableonlythosecipherswhichcausetrouble.

SSLCipherSuite

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

ThisalsoallowsthebrokenMSIEversionstowork,butonlyremovesthenewer56bitTLSciphers.

AnotherproblemwithMSIE5.xclientsisthattheyrefusetoconnecttoURLsoftheformhttps://12.34.56.78/(whereIP-addressesareusedinsteadofthehostname),iftheserverisusingtheServerGatedCryptography(SGC)facility.Thiscanonlybeavoidedbyusingthefullyqualifieddomainname(FQDN)ofthewebsiteinhyperlinksinstead,becauseMSIE5.xhasanerrorinthewayithandlestheSGCnegotiation.

AndfinallythereareversionsofMSIEwhichseemtorequirethatanSSLsessioncanbereused(atotallynonstandard-conformingbehaviour,ofcourse).ConnectingwiththoseMSIEversionsonly

workifaSSLsessioncacheisused.So,asawork-around,makesureyouareusingasessioncache(seetheSSLSessionCachedirective).

WhydoIgetI/Oerrors,orthemessage"Netscapehasencounteredbaddatafromtheserver",whenconnectingviaHTTPStoanApache+mod_sslserverwithNetscapeNavigator?Thisusuallyoccurswhenyouhavecreatedanewservercertificateforagivendomain,buthadpreviouslytoldyourbrowsertoalwaysaccepttheoldservercertificate.Onceyoucleartheentryfortheoldcertificatefromyourbrowser,everythingshouldbefine.Netscape'sSSLimplementationiscorrect,sowhenyouencounterI/OerrorswithNetscapeNavigatoritisusuallycausedbytheconfiguredcertificates.

mod_sslSupport

Whatinformationresourcesareavailableincaseofmod_sslproblems?Whatsupportcontactsareavailableincaseofmod_sslproblems?WhatinformationshouldIprovidewhenwritingabugreport?Ihadacoredump,canyouhelpme?HowdoIgetabacktrace,tohelpfindthereasonformycoredump?

Whatinformationresourcesareavailableincaseofmod_sslproblems?Thefollowinginformationresourcesareavailable.Incaseofproblemsyoushouldsearchherefirst.

AnswersintheUserManual'sF.A.Q.List(this)http://httpd.apache.org/docs/2.0/ssl/ssl_faq.htmlFirstchecktheF.A.Q.(thistext).Ifyourproblemisacommonone,itmayhavebeenansweredseveraltimesbefore,andbeenincludedinthisdoc.

Postingsfromthemodssl-usersSupportMailingListhttp://www.modssl.org/support/

Searchforyourprobleminthearchivesofthemodssl-usersmailinglist.You'reprobablynotthefirstpersontohavehadthisproblem!

Whatsupportcontactsareavailableincaseofmod_sslproblems?Thefollowinglistsallsupportpossibilitiesformod_ssl,inorderofpreference.Pleasegothroughthesepossibilitiesinthisorder-don'tjustpicktheoneyoulikethelookof.

1. SendaProblemReporttothemodssl-usersSupportMailing

Listmodssl-users@modssl.orgThisisthepreferredwayofsubmittingyourproblemreport,becausethisway,otherscanseetheproblem,andlearnfromanyanswers.Youmustsubscribetothelistfirst,butyoucantheneasilydiscussyourproblemwithboththeauthorandthewholemod_sslusercommunity.

2. SendaProblemReporttotheApachehttpdUsersSupportMailingListusers@httpd.apache.orgThisisthesecondwayofsubmittingyourproblemreport.Again,youmustsubscribetothelistfirst,butyoucantheneasilydiscussyourproblemwiththewholeApachehttpdusercommunity.

3. WriteaProblemReportintheBugDatabasehttp://httpd.apache.org/bug_report.htmlThisisthelastwayofsubmittingyourproblemreport.Youshouldonlydothisifyou'vealreadypostedtothemailinglists,andhadnosuccess.Pleasefollowtheinstructionsontheabovepagecarefully.

WhatinformationshouldIprovidewhenwritingabugreport?Youshouldalwaysprovideatleastthefollowinginformation:

ApacheandOpenSSLversioninformationTheApacheversioncanbedeterminedbyrunninghttpd-v.TheOpenSSLversioncanbedeterminedbyrunningopensslversion.Alternatively,ifyouhaveLynxinstalled,youcanrunthecommandlynx-mime_headerhttp://localhost/|grepServertogatherthisinformationinasinglestep.

ThedetailsonhowyoubuiltandinstalledApache+mod_ssl+OpenSSL

Forthisyoucanprovidealogfileofyourterminalsessionwhichshowstheconfigurationandinstallsteps.Ifthisisnotpossible,youshouldatleastprovidetheconfigurecommandlineyouused.

IncaseofcoredumpspleaseincludeaBacktraceIfyourApache+mod_ssl+OpenSSLdumpsitscore,pleaseattachastack-frame``backtrace''(seebelowforinformationonhowtogetthis).Thisinformationisrequiredinordertofindareasonforyourcoredump.

AdetaileddescriptionofyourproblemDon'tlaugh,wereallymeanit!Manyproblemreportsdon'tincludeadescriptionofwhattheactualproblemis.Withoutthis,it'sverydifficultforanyonetohelpyou.So,it'sinyourowninterest(youwanttheproblembesolved,don'tyou?)toincludeasmuchdetailaspossible,please.Ofcourse,youshouldstillincludealltheessentialsabovetoo.

Ihadacoredump,canyouhelpme?Ingeneralno,atleastnotunlessyouprovidemoredetailsaboutthecodelocationwhereApachedumpedcore.Whatisusuallyalwaysrequiredinordertohelpyouisabacktrace(seenextquestion).Withoutthisinformationitismostlyimpossibletofindtheproblemandhelpyouinfixingit.

HowdoIgetabacktrace,tohelpfindthereasonformycoredump?Followingarethestepsyouwillneedtocomplete,togetabacktrace:

1. Makesureyouhavedebuggingsymbolsavailable,atleastin

Apache.OnplatformswhereyouuseGCC/GDB,youwillhavetobuildApache+mod_sslwith``OPTIM="-g-ggdb3"''togetthis.Onotherplatformsatleast``OPTIM="-g"''isneeded.

2. Starttheserverandtrytoreproducethecore-dump.Forthisyoumaywanttouseadirectivelike``CoreDumpDirectory/tmp''tomakesurethatthecore-dumpfilecanbewritten.Thisshouldresultina/tmp/coreor/tmp/httpd.corefile.Ifyoudon'tgetoneofthese,tryrunningyourserverunderanon-rootUID.Manymodernkernelsdonotallowaprocesstodumpcoreafterithasdoneasetuid()(unlessitdoesanexec())forsecurityreasons(therecanbeprivilegedinformationleftoverinmemory).Ifnecessary,youcanrun/path/to/httpd-XmanuallytoforceApachetonotfork.

3. Analyzethecore-dump.Forthis,rungdb/path/to/httpd/tmp/httpd.coreorasimilarcommand.InGDB,allyouhavetodothenistoenterbt,andvoila,yougetthebacktrace.Forotherdebuggersconsultyourlocaldebuggermanual.

||FAQ||

ApacheHTTP2.0Apache>HTTP>>2.0 >How-To/

mod_auth

mod_access

AuthGroupFile

AuthName

AuthType

AuthUserFile

Options

Require

( <Directory>

.htaccess

AllowOverride

AllowOverrideAuthConfig

/usr/local/apache/passwd

Apache htpasswdApache

htpasswd-c/usr/local/apache/passwd/passwordsrbowen

htpasswd

#htpasswd-c/usr/local/apache/passwd/passwordsrbowen

Newpassword:mypassword

Re-typenewpassword:mypassword

Addingpasswordforuserrbowen

htpasswd /usr/local/apache/bin/htpasswd

/usr/local/apache/htdocs/secret/usr/local/apache/htdocs/secret/.htaccesshttpd.conf<Directory /usr/local/apache/apache/htdocs/secret>

AuthTypeBasic

AuthName"RestrictedFiles"

AuthUserFile/usr/local/apache/passwd/passwords

Requireuserrbowen

AuthTypeBasic mod_auth_digest Digest

AuthName Realm(:) Realm

"RestrictedFiles" "RestrictedFiles"

AuthUserFile htpasswd mod_auth_dbm AuthDBMUserFileApache

Require

( rbowen)

GroupName:rbowendpittssungorshersey

htpasswd/usr/local/apache/passwd/passwordsdpitts

.htaccess

AuthTypeBasic

AuthName"ByInvitationOnly"

AuthUserFile/usr/local/apache/passwd/passwords

AuthGroupFile/usr/local/apache/passwd/groups

RequiregroupGroupName

GroupName password

Requirevalid-user

requireuserrbowen AuthUserFile

Allow Deny

Allowfromaddress

addressIP (IP)

Denyfrom205.252.46.165

Denyfromhost.example.com

Denyfrom192.101.205

Denyfromcyberthugs.commoreidiots.com

Denyfromke

Order Deny Allow

Orderdeny,allow

Denyfromall

Allowfromdev.example.com

||FAQ||

mod_auth

||FAQ||

ApacheTutorial:CGI

mod_alias

mod_cgi

AddHandler

Options

ScriptAlias

CGI(CommonGatewayInterface)

CGIApache

CGICGI Apache

ScriptAliasScriptAlias CGIApache

ScriptAlias:

ScriptAlias/cgi-bin//usr/local/apache2/cgi-bin/

Apache httpd.conf

Alias Alias ScriptAliasAlias ScriptAlias ScriptAlias

/cgi-bin/CGIApache

URL http://dev.rcbowen.com/cgi-bin/test.plApache /usr/local/apache2/cgi-bin/test.pl Apache

ScriptAliasCGICGI ScriptAliasUserDir

CGI AddHandler

Options ExecCGI

CGIOptions Options CGI:

Options+ExecCGI

</Directory>

CGI ApacheCGIplCGI :

AddHandlercgi-script.cgi.pl

.htaccessfiles

.htaccess httpd.confCGI

User.cgiCGI

Options+ExecCGI

AddHandlercgi-script.cgi

</Directory>

cgi-bin CGI

OptionsExecCGI

SetHandlercgi-script

</Directory>

CGIMIME-type

CGI1CGI first.pl

#!/usr/bin/perl

print"Hello,World.";

Perl 12content-type World."

http://www.example.com/cgi-bin/first.pl

Hello,World.1

CGI"POSTMethodNotAllowed"CGIApache

"Forbidden" Apache

"InternalServerError"Apache "Prematureendofscriptheaders" CGI HTTP

chmoda+xfirst.pl

CGI CGI

( perl)CGI1:

#!/usr/bin/perl

CGI CGI

cd/usr/local/apache2/cgi-bin

./first.pl

(perl Apache

Content-Type HTTPendofscriptheaders CGI

Suexecsuexec scriptheaders

suexec apachectl-V SUEXEC_BIN Apachesuexecsuexec

suexec suexec suexec suexec-Vsuexec

CGI WebSite)CGI

PerlCGI Apache

#!/usr/bin/perl

foreach$key(keys%ENV){

print"$key-->$ENV{$key}<br>";

STDINSTDOUT (STDIN)( STDOUT)

CGI POST STDIN

(=)(&)

name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey

URL QUERY_STRING

GET POST FORM METHOD

PerlCGI CPAN

||FAQ||

CGICGI Usenet HTMLWritersGuide -servershttp://www.hwg.org/lists/hwg-servers/

Apache CGIApache

||FAQ||

Apache:ServerSideIncludes

mod_include

mod_cgi

mod_expires

Options

XBitHack

AddType

SetOutputFilter

BrowserMatchNoCase

SSIServerSideIncludes SSISSI

SSISSI

SSI(ServerSideIncludes)HTML HTML

SSI httpd.conf .htaccess:

Options+Includes

SSI ApacheOptions

SSI Apache

AddTypetext/html.shtml

AddOutputFilterINCLUDES.shtml

XBitHack:

XBitHackon

XBitHack SSIApachechmod

chmod+xpagename.html

.htmlSSIApacheXBitHack SSI

Windows

ApacheSSI HTTP

1. XBitHackFull

2. mod_expires

HTMLSSI

element

echo CGI

config timefmt

Todayis

Thisdocumentlastmodified

timefmt

CGI``'' CGISSI

SSIHTML

Thisfilelastmodified

ssi.shtml

Thisfilelastmodified

timefmt strftime

LAST_MODIFIED

config config

[anerroroccurredwhileprocessingthisdirective]

config errmsg:

<!--#configerrmsg="[Itappearsthatyoudon'tknowhowtouse

SSI]"-->

config sizefmt abbrev

CGISSI Win32DOS)

</pre>

Windows

</pre>

Windows

exec ``''IncludesNOEXEC SSI exec

ApacheSSI

Apache1.2 Apache1.2

( LAST_MODIFIED

test_condition ``''

BrowserMatchNoCasemacintoshMac

BrowserMatchNoCaseMSIEInternetExplorer

Macintosh

Apologetictextgoeshere

CoolJavaScriptcodegoeshere

MacIE JavaScriptMacIE

||FAQ||

SSICGI

||FAQ||

Apache:.htaccess

.htaccess

mod_auth

mod_cgi

mod_include

mod_mime

AccessFileName

AllowOverride

Options

AddHandler

SetHandler

AuthType

AuthName

AuthUserFile

AuthGroupFile

Require

.htaccess/

.htaccess()

.htaccess AccessFileName:

AccessFileName.config

.htaccess AllowOverride

AddDefaultCharset .htaccessFileInfo .htaccess FileInfo

: ,,,.htaccess: FileInfo

.htaccess ".htaccess"

.htaccess()

.htaccess

.htaccess rootISP

.htaccess .htaccess

.htaccess

AllowOverride .htaccessApache.htaccess .htaccess

Apache /www/htdocs/example Apache

/.htaccess

/www/.htaccess

/www/htdocs/.htaccess

/www/htdocs/example/.htaccess

.htaccess /www/htdocs/example<Directory/www/htdocs/example> :

/www/htdocs/example .htaccess:

/www/htdocs/example.htaccessAddTypetext/example.exm

httpd.conffile<Directory/www/htdocs/example>

AddTypetext/example.exm

</Directory>

AllowOverride none .htaccess

AllowOverrideNone

.htaccess .htaccess .htaccess .htaccess

/www/htdocs/example1 .htaccess:

Options+ExecCGI

(: .htaccess" Options")

/www/htdocs/example1/example2 .htaccess

OptionsIncludes

.htaccess /www/htdocs/example1/example2

CGI OptionsIncludes

.htaccess

"AllowOverrideAuthConfig"

.htaccess:

AuthTypeBasic

AuthName"PasswordRequired"

AuthUserFile/www/passwords/password.file

AuthGroupFile/www/passwords/group.file

RequireGroupadmins

AllowOverrideAuthConfig

.htaccess SSI

Options+Includes

AddTypetext/htmlshtml

AddHandlerserver-parsedshtml

AllowOverrideOptions

SSI SSI

Options+ExecCGI

AddHandlercgi-scriptcgipl

Options+ExecCGI

AllowOverrideOptions

CGI CGI

||FAQ||

.htaccess

AllowOverride.htaccess

Apache

||FAQ||

UserDir "username" UserDir

mod_userdir UserDir

DirectoryMatch

AllowOverride

UserDir

UserDirpublic_html

URLhttp://example.com/~rbowen/file.html/home/rbowen/public_html/file.html

UserDir/var/html

URLhttp://example.com/~rbowen/file.html/var/html/rbowen/file.html

UserDir/var/www/*/docs

URLhttp://example.com/~rbowen/file.html/var/www/rbowen/docs/file.html

UserDir :

UserDirenabled

UserDirdisabledrootjrofish

dissabled UserDir

UserDirdisabled

UserDirenabledrbowenkrietz

UserDir

cgi-bin <Directory>CGI

OptionsExecCGI

</Directory>

UserDir public_html CGI

http://example.com/~rbowen/cgi-bin/example.cgi

||FAQ||

.htaccess

ApacheTutorials

Warning:

Thisdocumenthasnotbeenfullyupdatedtotakeintoaccountchangesmadeinthe2.0versionoftheApacheHTTPServer.Someoftheinformationmaystillberelevant,butpleaseuseitwithcare.

Thefollowingdocumentsgiveyoustep-by-stepinstructionsonhowtoaccomplishcommontaskswiththeApacheHTTPserver.ManyofthesedocumentsarelocatedatexternalsitesandarenottheworkoftheApacheSoftwareFoundation.Copyrighttodocumentsonexternalsitesisownedbytheauthorsortheirassignees.PleaseconsulttheofficialApacheServerdocumentationtoverifywhatyoureadonexternalsites.

Installation&GettingStarted

GettingStartedwithApache1.3(ApacheToday)ConfiguringYourApacheServerInstallation(ApacheToday)Getting,Installing,andRunningApache(onUnix)(O'ReillyNetworkApacheDevCenter)MaximumApache:GettingStarted(CNETBuilder.com)HowtoBuildtheApacheofYourDreams(DeveloperShed)

BasicConfiguration

AnAmbleThroughApacheConfiguration(O'ReillyNetworkApacheDevCenter)Using.htaccessFileswithApache(ApacheToday)SettingUpVirtualHosts(ApacheToday)MaximumApache:ConfigureApache(CNETBuilder.com)GettingMoreOutofApache(DeveloperShed)

Security

SecurityandApache:AnEssentialPrimer(LinuxPlanet)UsingUserAuthentication(Apacheweek)DBMUserAuthentication(Apacheweek)AnIntroductiontoSecuringApache(Linux.com)SecuringApache-AccessControl(Linux.com)ApacheAuthenticationPart1-Part2-Part3-Part4(ApacheToday)mod_access:RestrictingAccessbyHost(ApacheToday)

Logging

LogRhythms(O'ReillyNetworkApacheDevCenter)GatheringVisitorInformation:CustomisingYourLogfiles(Apacheweek)ApacheGuide:LoggingPart1-Part2-Part3-Part4-Part5(ApacheToday)

CGIandSSI

DynamicContentwithCGI(ApacheToday)TheIdiot'sGuidetoSolvingPerlCGIProblems(CPAN)ExecutingCGIScriptsasOtherUsers(LinuxPlanet)CGIProgrammingFAQ(WebDesignGroup)IntroductiontoServerSideIncludesPart1-Part2(ApacheToday)AdvancedSSITechniques(ApacheToday)SettingupCGIandSSIwithApache(CNETBuilder.com)

OtherFeatures

ContentNegotiationExplained(Apacheweek)UsingApacheImagemaps(Apacheweek)KeepingYourImagesfromAdorningOtherSites(ApacheToday)LanguageNegotiationNotes(AlanJ.Flavell)

Ifyouhaveapointertoanaccurateandwell-writtentutorialnotincludedhere,pleaseletusknowbysubmittingittotheApacheBugDatabase.

ApacheHTTPServerVersion2.0Apache>HTTPServer>Documentation>Version2.0>PlatformSpecificNotes

UsingApachewithMicrosoftWindows

Thisdocumentexplainshowtoinstall,configureandrunApache2.0underMicrosoftWindows.Ifyoufindanybugs,orwishtocontributeinotherways,pleaseuseourbugreportingpage.

ThisdocumentassumesthatyouareinstallingabinarydistributionofApache.IfyouwanttocompileApacheyourself(possiblytohelpwithdevelopmentortrackingdownbugs),seeCompilingApacheforMicrosoftWindows.

BecauseofthecurrentversioningpoliciesonMicrosoftWindowsoperatingsystemfamilies,thisdocumentassumesthefollowing:

WindowsNT:ThismeansallversionsofWindowsthatarebasedontheWindowsNTkernel.IncludesWindowsNT,Windows2000,WindowsXPandWindows.NetServer2003.Windows9x:Thismeansolder,consumer-orientedversionsofWindows.IncludesWindows95(alsoOSR2),Windows98andWindowsME.

OperatingSystemRequirements

TheprimaryWindowsplatformforrunningApache2.0isWindowsNT.Thebinaryinstalleronlyworkswiththex86familyofprocessors,suchasIntelandAMDprocessors.RunningApacheonWindows9xisnotthoroughlytested,anditisneverrecommendedonproductionsystems.

Onalloperatingsystems,TCP/IPnetworkingmustbeinstalledandworking.IfrunningonWindows95,theWinsock2upgrademustbeinstalled.Winsock2forWindows95canbedownloadedfromhere.

OnWindowsNT4.0,installingServicePack6isstronglyrecommended,asServicePack4createdknownissueswithTCP/IPandWinsockintegritythatwereresolvedinlaterServicePacks.

DownloadingApacheforWindows

InformationonthelatestversionsofApachecanbefoundonthewebsiteoftheApachewebserverathttp://httpd.apache.org/download.cgi.Thereyouwillfindthecurrentrelease,aswellasmorerecentalphaorbetatestversions,andalistofHTTPandFTPmirrorsfromwhichyoucandownloadtheApachewebserver.Pleaseuseamirrorneartoyouforafastandreliabledownload.

ForWindowsinstallationsyoushoulddownloadtheversionofApacheforWindowswiththe.msiextension.ThisisasingleMicrosoftInstallerfile,whichcontainsaready-to-runversionofApache.Thereisaseparate.zipfile,whichcontainsonlythesourcecode.YoucancompileApacheyourselfwiththeMicrosoftVisualC++(VisualStudio)tools.

InstallingApacheforWindows

YouneedMicrosoftInstaller1.2orabovefortheinstallationtowork.OnWindows9xyoucanupdateyourMicrosoftInstallertoversion2.0hereandonWindowsNT4.0and2000theversion2.0updatecanbefoundhere.WindowsXPdoesnotneedthisupdate.

NotethatyoucannotinstalltwoversionsofApache2.0onthesamecomputerwiththebinaryinstaller.Youcan,however,installaversionofthe1.3seriesandaversionofthe2.0seriesonthesamecomputerwithoutproblems.Ifyouneedtohavetwodifferent2.0versionsonthesamecomputer,youhavetocompileandinstallApachefromthesource.

RuntheApache.msifileyoudownloadedabove.Theinstallationwillaskyouforthesethings:

1. NetworkDomain.EntertheDNSdomaininwhichyourserverisorwillberegisteredin.Forexample,ifyourserver'sfullDNSnameisserver.mydomain.net,youwouldtypemydomain.nethere.

2. ServerName.Yourserver'sfullDNSname.Fromtheexampleabove,youwouldtypeserver.mydomain.nethere.

3. Administrator'sEmailAddress.Entertheserveradministrator'sorwebmaster'semailaddresshere.Thisaddresswillbedisplayedalongwitherrormessagestotheclientbydefault.

4. ForwhomtoinstallApacheSelectforAllUsers,onPort80,asaService-Recommendedifyou'dlikeyournewApachetolistenatport80forincomingtraffic.Itwillrunasaservice(thatis,Apachewillrunevenifnooneis

loggedinontheserveratthemoment)SelectonlyfortheCurrentUser,onPort8080,whenstarted

Manuallyifyou'dliketoinstallApacheforyourpersonalexperimentingorifyoualreadyhaveanotherWWWserverrunningonport80.

5. Theinstallationtype.SelectTypicalforeverythingexceptthesourcecodeandlibrariesformoduledevelopment.WithCustomyoucanspecifywhattoinstall.Afullinstallwillrequireabout13megabytesoffreediskspace.Thisdoesnotincludethesizeofyourwebsite(s).

6. Wheretoinstall.ThedefaultpathisC:\ProgramFiles\ApacheGroupunderwhichadirectorycalledApache2willbecreatedbydefault.

Duringtheinstallation,Apachewillconfigurethefilesintheconfsubdirectorytoreflectthechoseninstallationdirectory.However,ifanyoftheconfigurationfilesinthisdirectoryalreadyexist,theywillnotbeoverwritten.Instead,thenewcopyofthecorrespondingfilewillbeleftwiththeextension.default.So,forexample,ifconf\httpd.confalreadyexists,itwillberenamedasconf\httpd.conf.default.Aftertheinstallationyoushouldmanuallychecktoseewhatnewsettingsareinthe.defaultfile,andifnecessary,updateyourexistingconfigurationfile.

Also,ifyoualreadyhaveafilecalledhtdocs\index.html,itwillnotbeoverwritten(andnoindex.html.defaultwillbeinstalledeither).ThismeansitshouldbesafetoinstallApacheoveranexistinginstallation,althoughyouwouldhavetostoptheexistingrunningserverbeforedoingtheinstallation,andthenstartthenewoneaftertheinstallationisfinished.

AfterinstallingApache,youmustedittheconfigurationfilesinthe

confsubdirectoryasrequired.ThesefileswillbeconfiguredduringtheinstallationsothatApacheisreadytoberunfromthedirectoryitwasinstalledinto,withthedocumentsserverfromthesubdirectoryhtdocs.TherearelotsofotheroptionswhichyoushouldsetbeforeyoureallystartusingApache.However,togetstartedquickly,thefilesshouldworkasinstalled.

CustomizingApacheforWindows

Apacheisconfiguredbythefilesintheconfsubdirectory.ThesearethesamefilesusedtoconfiguretheUnixversion,butthereareafewdifferentdirectivesforApacheonWindows.Seethedirectiveindexforalltheavailabledirectives.

ThemaindifferencesinApacheforWindowsare:

BecauseApacheforWindowsismultithreaded,itdoesnotuseaseparateprocessforeachrequest,asApachedoesonUnix.InsteadthereareusuallyonlytwoApacheprocessesrunning:aparentprocess,andachildwhichhandlestherequests.Withinthechildprocesseachrequestishandledbyaseparatethread.

Theprocessmanagementdirectivesarealsodifferent:

MaxRequestsPerChild:LiketheUnixdirective,thiscontrolshowmanyrequestsasinglechildprocesswillservebeforeexiting.However,unlikeonUnix,asingleprocessservesalltherequestsatonce,notjustone.Ifthisisset,itisrecommendedthataveryhighnumberisused.Therecommendeddefault,MaxRequestsPerChild0,causesthechildprocesstoneverexit.

Warning:Theserverconfigurationfileisrereadwhenanewchildprocessisstarted.Ifyouhavemodifiedhttpd.conf,thenewchildmaynotstartoryoumayreceiveunexpectedresults.

ThreadsPerChild:Thisdirectiveisnew.Ittellstheserverhowmanythreadsitshoulduse.Thisisthemaximumnumberofconnectionstheservercanhandleatonce,sobesuretosetthisnumberhighenoughforyoursiteifyougetalotof

hits.TherecommendeddefaultisThreadsPerChild50.

ThedirectivesthatacceptfilenamesasargumentsmustuseWindowsfilenamesinsteadofUnixones.However,becauseApacheusesUnix-stylenamesinternally,youmustuseforwardslashes,notbackslashes.Driveletterscanbeused;ifomitted,thedrivewiththeApacheexecutablewillbeassumed.

Whilefilenamesaregenerallycase-insensitiveonWindows,URLsarestilltreatedinternallyascase-sensitivebeforetheyaremappedtothefilesystem.Forexample,the<Location>,Alias,andProxyPassdirectivesallusecase-sensitivearguments.Forthisreason,itisparticularlyimportanttousethe<Directory>directivewhenattemptingtolimitaccesstocontentinthefilesystem,sincethisdirectiveappliestoanycontentinadirectory,regardlessofhowitisaccessed.IfyouwishtoassurethatonlylowercaseisusedinURLs,youcanusesomethinglike:

RewriteEngineOn

RewriteCond%{REQUEST_URI}[A-Z]

RewriteRule(.*)${lowercase:$1}[R,L]

ApacheforWindowscontainstheabilitytoloadmodulesatruntime,withoutrecompilingtheserver.IfApacheiscompilednormally,itwillinstallanumberofoptionalmodulesinthe\Apache2\modulesdirectory.Toactivatetheseorothermodules,thenewLoadModuledirectivemustbeused.Forexample,toactivatethestatusmodule,usethefollowing(inadditiontothestatus-activatingdirectivesinaccess.conf):

LoadModulestatus_modulemodules/mod_status.so

Informationoncreatingloadablemodulesisalsoavailable.

ApachecanalsoloadISAPI(InternetServerApplicationProgrammingInterface)extensions(i.e.internetserverapplications),suchasthoseusedbyMicrosoftIISandotherWindowsservers.Moreinformationisavailable.NotethatApachecannotloadISAPIFilters.

WhenrunningCGIscripts,themethodApacheusestofindtheinterpreterforthescriptisconfigurableusingtheScriptInterpreterSourcedirective.

Sinceitisoftendifficulttomanagefileswithnameslike.htaccessinWindows,youmayfinditusefultochangethenameofthisper-directoryconfigurationfileusingtheAccessFilenamedirective.

AnyerrorsduringApachestartupareloggedintotheWindowseventlogwhenrunningonWindowsNT.ThismechanismactsasabackupforthosesituationswhereApachecannotevenaccessthenormallyusederror.logfile.YoucanviewtheWindowseventlogbyusingtheEventViewerapplicationonWindowsNT4.0,andtheEventViewerMMCsnap-inonnewerversionsofWindows.

NotethatthereisnostartuperrorloggingonWindows9xbecausenoWindowseventlogexistsonthoseoperatingsystems.

RunningApacheasaService

ApachecanberunasaserviceonWindowsNT.ThereissomehighlyexperimentalsupportforsimilarbehavioronWindows9x.

YoucaninstallApacheasaserviceautomaticallyduringtheinstallation.Ifyouchosetoinstallforallusers,theinstallationwillcreateanApacheserviceforyou.Ifyouspecifytoinstallforyourselfonly,youcanmanuallyregisterApacheasaserviceaftertheinstallation.YouhavetobeamemberoftheAdministratorsgroupfortheserviceinstallationtosucceed.

ApachecomeswithautilitycalledtheApacheServiceMonitor.WithityoucanseeandmanagethestateofallinstalledApacheservicesonanymachineonyournetwork.TobeabletomanageanApacheservicewiththemonitor,youhavetofirstinstalltheservice(eitherautomaticallyviatheinstallationormanually).

YoucaninstallApacheasaWindowsNTserviceasfollowsfromthecommandpromptattheApachebinsubdirectory:

httpd-kinstall

Ifyouneedtospecifythenameoftheserviceyouwanttoinstall,usethefollowingcommand.YouhavetodothisifyouhaveseveraldifferentserviceinstallationsofApacheonyourcomputer.

httpd-kinstall-n"MyServiceName"

Ifyouneedtohavespecificallynamedconfigurationfilesfordifferentservices,youmustusethis:

httpd-kinstall-n"MyServiceName"-f"c:\files\my.conf"

Ifyouusethefirstcommandwithoutanyspecialparametersexcept-kinstall,theservicewillbecalledApache2andthe

configurationwillbeassumedtobeconf\httpd.conf.

RemovinganApacheserviceiseasy.Justuse:

httpd-kuninstall

ThespecificApacheservicetobeuninstalledcanbespecifiedbyusing:

httpd-kuninstall-n"MyServiceName"

Normalstarting,restartingandshuttingdownofanApacheserviceisusuallydoneviatheApacheServiceMonitor,byusingcommandslikeNETSTARTApache2andNETSTOPApache2orvianormalWindowsservicemanagement.BeforestartingApacheasaservicebyanymeans,youshouldtesttheservice'sconfigurationfilebyusing:

httpd-n"MyServiceName"-t

YoucancontrolanApacheservicebyitscommandlineswitches,too.TostartaninstalledApacheserviceyou'llusethis:

httpd-kstart

TostopanApacheserviceviathecommandlineswitches,usethis:

httpd-kstop

httpd-kshutdown

Youcanalsorestartarunningserviceandforceittorereaditsconfigurationfilebyusing:

httpd-krestart

Bydefault,allApacheservicesareregisteredtorunasthesystemuser(theLocalSystemaccount).TheLocalSystemaccounthasnoprivilegestoyournetworkviaanyWindows-securedmechanism,includingthefilesystem,namedpipes,DCOM,orsecureRPC.Ithas,however,wideprivilegeslocally.

NevergrantanynetworkprivilegestotheLocalSystemaccount!IfyouneedApachetobeabletoaccessnetworkresources,createaseparateaccountforApacheasnotedbelow.

YoumaywanttocreateaseparateaccountforrunningApacheservice(s).Especially,ifyouhavetoaccessnetworkresourcesviaApache,thisisstronglyrecommended.

1. Createanormaldomainuseraccount,andbesuretomemorizeitspassword.

2. Grantthenewly-createduseraprivilegeofLogonasaserviceandActaspartoftheoperatingsystem.OnWindowsNT4.0theseprivilegesaregrantedviaUserManagerforDomains,butonWindows2000andXPyouprobablywanttouseGroupPolicyforpropagatingthesesettings.YoucanalsomanuallysettheseviatheLocalSecurityPolicyMMCsnap-in.

3. ConfirmthatthecreatedaccountisamemberoftheUsersgroup.

4. Granttheaccountreadandexecute(RX)rightstoalldocumentandscriptfolders(htdocsandcgi-binfor

example).

5. Granttheaccountchange(RWXD)rightstotheApachelogsdirectory.

6. Granttheaccountreadandexecute(RX)rightstotheApache.exebinaryexecutable.

ItisusuallyagoodpracticetogranttheusertheApacheservicerunsasreadandexecute(RX)accesstothewholeApache2directory,exceptthelogssubdirectory,wheretheuserhastohaveatleastchange(RWXD)rights.

Ifyouallowtheaccounttologinasauserandasaservice,thenyoucanlogonwiththataccountandtestthattheaccounthastheprivilegestoexecutethescripts,readthewebpages,andthatyoucanstartApacheinaconsolewindow.Ifthisworks,andyouhavefollowedthestepsabove,Apacheshouldexecuteasaservicewithnoproblems.

Errorcode2186isagoodindicationthatyouneedtoreviewthe"LogOnAs"configurationfortheservice,sinceApachecannotaccessarequirednetworkresource.Also,paycloseattentiontotheprivilegesoftheuserApacheisconfiguredtorunas.

WhenstartingApacheasaserviceyoumayencounteranerrormessagefromtheWindowsServiceControlManager.Forexample,ifyoutrytostartApachebyusingtheServicesappletintheWindowsControlPanel,youmaygetthefollowingmessage:

CouldnotstarttheApache2serviceon\\COMPUTER

Error1067;Theprocessterminatedunexpectedly.

YouwillgetthisgenericerrorifthereisanyproblemwithstartingtheApacheservice.Inordertoseewhatisreallycausingthe

problemyoushouldfollowtheinstructionsforRunningApacheforWindowsfromtheCommandPrompt.

ThereissomesupportforApacheonWindows9xtobehaveinasimilarmannerasaserviceonWindowsNT.Itishighlyexperimental.Itisnotofproduction-classreliability,anditsfutureisnotguaranteed.Itcanbemostlyregardedasariskythingtoplaywith-proceedwithcaution!

Therearesomedifferencesbetweenthetwokindsofservicesyoushouldbeawareof:

Apachewillattempttostartandifsuccessfulitwillruninthebackground.Ifyourunthecommand

httpd-n"MyServiceName"-kstart

viaashortcutonyourdesktop,forexample,theniftheservicestartssuccessfully,aconsolewindowwillflashupbutitimmediatelydisappears.IfApachedetectsanyerrorsonstartupsuchasincorrectentriesinthehttpd.confconfigurationfile,theconsolewindowwillremainvisible.Thiswilldisplayanerrormessagewhichwillbeusefulintrackingdownthecauseoftheproblem.

Windows9xdoesnotsupportNETSTARTorNETSTOPcommands.YoumustcontroltheApacheserviceonthecommandpromptviathe-kswitches.

ApacheandWindows9xoffernosupportforrunningApacheasaspecificuserwithnetworkprivileges.Infact,Windows9xoffersnosecurityonthelocalmachine,either.ThisisthesimplereasonbecauseofwhichtheApacheSoftwareFoundationneverendorsesuseofaWindows9x-basedsystemasapublicApacheserver.Theprimitivesupportfor

Windows9xexistsonlytoassisttheuserindevelopingwebcontentandlearningtheApacheserver,andperhapsasanintranetserveronasecured,privatenetwork.

OnceyouhaveconfirmedthatApacherunscorrectlyasaconsoleapplicationyoucaninstall,controlanduninstallthepseudo-servicewiththesamecommandsasonWindowsNT.YoucanalsousetheApacheServiceMonitortomanageWindows9xpseudo-services.

RunningApacheasaConsoleApplication

RunningApacheasaserviceisusuallytherecommendedwaytouseit,butitissometimeseasiertoworkfromthecommandline(onWindows9xrunningApachefromthecommandlineistherecommendedwayduetothelackofreliableservicesupport.)

TorunApachefromthecommandlineasaconsoleapplication,usethefollowingcommand:

Apachewillexecute,andwillremainrunninguntilitisstoppedbypressingControl-C.

YoucanalsorunApacheviatheshortcutStartApacheinConsoleplacedtoStartMenu-->Programs-->ApacheHTTPServer2.0.xx-->ControlApacheServerduringtheinstallation.ThiswillopenaconsolewindowandstartApacheinsideit.Ifyoudon'thaveApacheinstalledasaservice,thewindowwillremainvisibleuntilyoustopApachebypressingControl-CintheconsolewindowwhereApacheisrunningin.Theserverwillexitinafewseconds.However,ifyoudohaveApacheinstalledasaservice,theshortcutstartstheservice.IftheApacheserviceisrunningalready,theshortcutdoesn'tdoanything.

YoucantellarunningApachetostopbyopeninganotherconsolewindowandentering:

httpd-kshutdown

ThisshouldbepreferredoverpressingControl-CbecausethisletsApacheendanycurrentoperationsandcleanupgracefully.

YoucanalsotellApachetorestart.Thisforcesittorereadtheconfigurationfile.Anyoperationsinprogressareallowedto

completewithoutinterruption.TorestartApache,use:

httpd-krestart

NoteforpeoplefamiliarwiththeUnixversionofApache:thesecommandsprovideaWindowsequivalenttokill-TERMpidandkill-USR1pid.Thecommandlineoptionused,-k,waschosenasareminderofthekillcommandusedonUnix.

IftheApacheconsolewindowclosesimmediatelyorunexpectedlyafterstartup,opentheCommandPromptfromtheStartMenu-->Programs.ChangetothefoldertowhichyouinstalledApache,typethecommandapache,andreadtheerrormessage.Thenchangetothelogsfolder,andreviewtheerror.logfileforconfigurationmistakes.IfyouacceptedthedefaultswhenyouinstalledApache,thecommandswouldbe:

cd"\ProgramFiles\ApacheGroup\Apache2\bin"

ThenwaitforApachetostop,orpressControl-C.Thenenterthefollowing:

cd..\logs

more<error.log

WhenworkingwithApacheitisimportanttoknowhowitwillfindtheconfigurationfile.Youcanspecifyaconfigurationfileonthecommandlineintwoways:

-fspecifiesanabsoluteorrelativepathtoaparticularconfigurationfile:

httpd-f"c:\myserverfiles\anotherconfig.conf"

httpd-ffiles\anotherconfig.conf

-nspecifiestheinstalledApacheservicewhoseconfigurationfileistobeused:

httpd-n"MyServiceName"

Inbothofthesecases,theproperServerRootshouldbesetintheconfigurationfile.

Ifyoudon'tspecifyaconfigurationfilewith-for-n,Apachewillusethefilenamecompiledintotheserver,suchasconf\httpd.conf.Thisbuilt-inpathisrelativetotheinstallationdirectory.YoucanverifythecompiledfilenamefromavaluelabelledasSERVER_CONFIG_FILEwheninvokingApachewiththe-Vswitch,likethis:

httpd-V

ApachewillthentrytodetermineitsServerRootbytryingthefollowing,inthisorder:

1. AServerRootdirectiveviathe-Ccommandlineswitch.

2. The-dswitchonthecommandline.

3. Currentworkingdirectory.

4. Aregistryentrywhichwascreatedifyoudidabinaryinstallation.

5. Theserverrootcompiledintotheserver.Thisis/apachebydefault,youcanverifyitbyusingapache-Vandlookingfor

avaluelabelledasHTTPD_ROOT.

Duringtheinstallation,aversion-specificregistrykeyiscreatedintheWindowsregistry.Thelocationofthiskeydependsonthetypeoftheinstallation.IfyouchosetoinstallApacheforallusers,thekeyislocatedundertheHKEY_LOCAL_MACHINEhive,likethis(theversionnumberswillofcoursevarybetweendifferentversionsofApache:

HKEY_LOCAL_MACHINE\SOFTWARE\ApacheGroup\Apache\2.0.43

Correspondingly,ifyouchosetoinstallApacheforthecurrentuseronly,thekeyislocatedundertheHKEY_CURRENT_USERhive,thecontentsofwhicharedependentoftheusercurrentlyloggedon:

HKEY_CURRENT_USER\SOFTWARE\ApacheGroup\Apache\2.0.43

Thiskeyiscompiledintotheserverandcanenableyoutotestnewversionswithoutaffectingthecurrentversion.Ofcourse,youmusttakecarenottoinstallthenewversioninthesamedirectoryasanotherversion.

Ifyoudidnotdoabinaryinstall,Apachewillinsomescenarioscomplainaboutthemissingregistrykey.Thiswarningcanbeignorediftheserverwasotherwiseabletofinditsconfigurationfile.

ThevalueofthiskeyistheServerRootdirectorywhichcontainstheconfsubdirectory.WhenApachestartsitreadsthehttpd.conffilefromthatdirectory.IfthisfilecontainsaServerRootdirectivewhichcontainsadifferentdirectoryfromtheoneobtainedfromtheregistrykeyabove,Apachewillforgettheregistrykeyandusethedirectoryfromtheconfigurationfile.IfyoucopytheApachedirectoryorconfigurationfilestoanew

locationitisvitalthatyouupdatetheServerRootdirectiveinthehttpd.conffiletoreflectthenewlocation.

TestingtheInstallation

AfterstartingApache(eitherinaconsolewindoworasaservice)itwillbelisteningonport80(unlessyouchangedtheListendirectiveintheconfigurationfilesorinstalledApacheonlyforthecurrentuser).Toconnecttotheserverandaccessthedefaultpage,launchabrowserandenterthisURL:

http://localhost/

ApacheshouldrespondwithawelcomepageandalinktotheApachemanual.Ifnothinghappensoryougetanerror,lookintheerror.logfileinthelogssubdirectory.Ifyourhostisnotconnectedtothenet,orifyouhaveseriousproblemswithyourDNS(DomainNameService)configuration,youmayhavetousethisURL:

http://127.0.0.1/

IfyouhappentoberunningApacheonanalternateport,youneedtoexplicitlyputthatintheURL:

http://127.0.0.1:8080/

Onceyourbasicinstallationisworking,youshouldconfigureitproperlybyeditingthefilesintheconfsubdirectory.Again,ifyouchangetheconfigurationoftheWindowsNTserviceforApache,firstattempttostartitfromthecommandlinetomakesurethattheservicestartswithnoerrors.

BecauseApachecannotsharethesameportwithanotherTCP/IPapplication,youmayneedtostop,uninstallorreconfigurecertainotherservicesbeforerunningApache.TheseconflictingservicesincludeotherWWWserversandsomefirewallimplementations.

CompilingApacheforMicrosoftWindows

TherearemanyimportantpointsbeforeyoubegincompilingApache.SeeUsingApachewithMicrosoftWindowsbeforeyoubegin.

Requirements

CompilingApacherequiresthefollowingenvironmenttobeproperlyinstalled:

DiskSpace

Makesureyouhaveatleast50MBoffreediskspaceavailable.AfterinstallationApacherequiresapproximately10MBofdiskspace,plusspaceforlogandcachefiles,whichcangrowrapidly.Theactualdiskspacerequirementswillvaryconsiderablybasedonyourchosenconfigurationandanythird-partymodulesorlibraries.

MicrosoftVisualC++5.0orhigher.

Apachecanbebuiltusingthecommandlinetools,orfromwithintheVisualStudioIDEWorkbench.ThecommandlinebuildrequirestheenvironmenttoreflectthePATH,INCLUDE,LIBandothervariablesthatcanbeconfiguredwiththevcvars32batchfile:

"c:\ProgramFiles\DevStudio\VC\Bin\vcvars32.bat"

TheWindowsPlatformSDK.

VisualC++5.0buildsrequireanupdatedMicrosoftWindowsPlatformSDKtoenablesomeApachefeatures.Forcommandlinebuilds,thePlatformSDKenvironmentispreparedbythesetenvbatchfile:

"c:\ProgramFiles\PlatformSDK\setenv.bat"

ThePlatformSDKfilesdistributedwithVisualC++6.0andlateraresufficient,sousersoflaterversionmayskipthisrequirement.

NotethattheWindowsPlatformSDKupdateisrequiredtoenableallsupportedmod_isapifeatures.Withoutarecentupdate,ApachewillissuewarningsunderMSVC++5.0thatsomemod_isapifeatureswillbedisabled.Lookfortheupdateathttp://msdn.microsoft.com/downloads/sdks/platform/platform.asp

Theawkutility(awk,gawkorsimilar).

ToinstallApachewithinthebuildsystem,severalfilesaremodifiedusingtheawk.exeutility.awkwaschosensinceitisaverysmalldownload(comparedwithPerlorWSH/VB)andaccomplishesthetaskofgeneratingfiles.BrianKernighan'shttp://cm.bell-labs.com/cm/cs/who/bwk/sitehasacompilednativeWin32binary,http://cm.bell-labs.com/cm/cs/who/bwk/awk95.exewhichyoumustsavewiththenameawk.exeratherthanawk95.exe.

NotethatDeveloperStudioIDEwillonlyfindawk.exefromtheToolsmenuOptions...Directoriestab(theProjects-VC++DirectoriespaneinDeveloperStudio7.0)listingExecutablefilepaths.Addthepathforawk.exetothislist,andyoursystemPATHenvironmentvariable,asneeded.

AlsonotethatifyouareusingCygwin(http://www.cygwin.com/)theawkutilityisnamedgawk.exeandthatthefileawk.exeisreallyasymlinktothegawk.exefile.TheWindowscommandshelldoesnotrecognizesymlinks,andbecauseofthatbuildingInstallBinwillfail.Aworkaroundistodeleteawk.exefromthecygwininstallationandrenamegawk.exetoawk.exe.

[Optional]OpenSSLlibraries(formod_sslandab.exewithsslsupport)

Caution:therearesignificantrestrictionsandprohibitionsontheuseanddistributionofstrongcryptographyandpatentedintellectualpropertythroughouttheworld.OpenSSLincludesstrongcryptographycontrolledbybothexportregulationsanddomesticlaw,aswellasintellectualpropertyprotectedbypatent,intheUnitedStatesandelsewhere.NeithertheApacheSoftwareFoundationnortheOpenSSLprojectcanprovidelegaladviseregardingpossession,use,ordistributionofthecodeprovidedbytheOpenSSLproject.Consultyourownlegalcounsel,youareresponsibleforyourownactions.

OpenSSLmustbeinstalledintoasrclibsubdirectorynamedopenssl,obtainedfromhttp://www.openssl.org/source/,inordertocompilemod_sslortheabsproject(ab.exewithSSLsupport.)ToprepareOpenSSLforbothreleaseanddebugbuildsofApache,anddisablethepatentprotectedfeaturesinOpenSSL,youmightusethefollowingbuildcommands:

perlConfigureVC-WIN32

perlutil\mkfiles.pl>MINFO

perlutil\mk1mf.pldllno-asmno-mdc2no-rc5no-ideaVC-

WIN32>makefile.rel

perlutil\mk1mf.pldlldebugno-asmno-mdc2no-rc5no-idea

VC-WIN32>makefile.dbg

perlutil\mkdef.pl32libeayno-asmno-mdc2no-rc5no-idea

>ms\libeay32.def

perlutil\mkdef.pl32ssleayno-asmno-mdc2no-rc5no-idea

>ms\ssleay32.def

nmake-fmakefile.rel

nmake-fmakefile.dbg

Note;youcanusethescriptsinthems\subdirectory,however,it'srathertrickytoforcems\do_masm.bat,forexample,toperformthepatentencumberancesasmentionedabove.Patchestoaddthe$*argumentlisttotheappropriate.batlinesinthesescriptsaren'tincorporated,thusfar.

[Optional]zlibsources(formod_deflate)

Zlibmustbeinstalledintoasrclibsubdirectorynamedzlib,howeverthosesourcesneednotbecompiled.Thebuildsystemwillcompilethecompressionsourcesdirectlyintothemod_deflatemodule.Zlibcanbeobtainedfromhttp://www.zlib.net/--mod_deflateisconfirmedtobuildcorrectlywithversion1.1.4.Tousealaterversionofzlib,upgradetoApacheHTTPServerrelease2.2orlater.

Command-LineBuild

First,unpacktheApachedistributionintoanappropriatedirectory.Openacommand-linepromptandcdtothatdirectory.

ThemasterApachemakefileinstructionsarecontainedintheMakefile.winfile.TocompileApacheonWindowsNT,simplyuseoneofthefollowingcommandstocompiledthereleaseordebugbuild,respectively:

nmake/fMakefile.win_apacher

nmake/fMakefile.win_apached

EithercommandwillcompileApache.Thelatterwillincludedebugginginformationintheresultingfiles,makingiteasiertofindbugsandtrackdownproblems.

DeveloperStudioWorkspaceIDEBuild

ApachecanalsobecompiledusingVC++'sVisualStudiodevelopmentenvironment.Tosimplifythisprocess,aVisualStudioworkspace,Apache.dsw,isprovided.Thisworkspaceexposestheentirelistofworking.dspprojectsthatarerequiredforthecompleteApachebinaryrelease.Itincludesdependenciesbetweentheprojectstoassurethattheyarebuiltintheappropriateorder.

OpentheApache.dswworkspace,andselectInstallBin(ReleaseorDebugbuild,asdesired)astheActiveProject.InstallBincausesallrelatedprojecttobebuilt,andtheninvokesMakefile.wintomovethecompiledexecutablesanddlls.YoumaypersonalizetheINSTDIR=choicebychangingInstallBin'sSettings,Generaltab,Buildcommandlineentry.INSTDIRdefaultstothe/Apache2directory.Ifyouonlywantatestcompile(withoutinstalling)youmaybuildtheBuildBinprojectinstead.

The.dspprojectfilesaredistributedinVisualC++6.0format.VisualC++5.0(97)willrecognizethem.VisualC++7.0(.net)mustconvertApache.dswplusthe.dspfilesintoanApache.slnplus.msprojfiles,besureyoureconvertthe.msprojfileifanyofthesource.dspfileschange!Thisisreallytrivial,justopenApache.dswintheVC++7.0IDEonceagain.

VisualC++7.0(.net)usersshouldalsousetheBuildmenu,ConfigurationManagerdialogtouncheckboththeDebugandReleaseSolutionmodulesabs,mod_sslandmod_deflate.ThesemodulesarebuiltbyinvokingnmakeortheIDEdirectlywiththeBinBuildtargettobuildthosemodulesexplicitly,onlyifthesrclibdirectoriesopenssland/orzlibexist.

Exported.makfilesposeagreaterhassle,buttheyarerequired

forVisualC++5.0userstobuildmod_ssl,abs(abwithSSLsupport)and/ormod_deflate.VC++7.0(.net)usersalsobenefit,nmakebuildsarefasterthanbinenvbuilds.BuildtheentireprojectfromwithintheVC++5.0or6.0IDE,thenusetheProjectMenuExportforallmakefiles.Youmustbuildtheprojectsfirstinordertocreatealldynamicauto-generatedtargets,sothatdependenciescanbeparsedcorrectly.Runthefollowingcommandtofixthepathssotheywillbuildanywhere:

perlsrclib\apr\build\fixwin32mak.pl

Youmusttypethiscommandfromthetopleveldirectoryofthehttpdsourcetree.Every.makand.depprojectfilewithinthecurrentdirectoryandbelowwillbecorrected,andthetimestampsadjustedtoreflectthe.dsp.

Ifyoucontributebackapatchthatrevisesprojectfiles,wemustcommitprojectfilesinVisualStudio6.0format.Changesshouldbesimple,withminimalcompilationandlinkageflagsthatwillberecognizedbyallVC++5.0through7.0environments.

ProjectComponents

TheApache.dswworkspaceandmakefile.winnmakescriptbothbuildthe.dspprojectsoftheApacheserverinthefollowingsequence:

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

Inaddition,themodules\subdirectorytreecontainsprojectfilesforthemajorityofthemodules.

Thesupport\directorycontainsprojectfilesforadditionalprogramsthatarenotpartoftheApacheruntime,butareusedbytheadministratortotestApacheandmaintainpasswordandlogfiles.Windows-specificsupportprojectsarebrokenoutinthesupport\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

OnceApachehasbeencompiled,itneedstobeinstalledinitsserverrootdirectory.Thedefaultisthe\Apache2directory,ofthesamedrive.

Tobuildandinstallallthefilesintothedesiredfolderdirautomatically,useoneofthefollowingnmakecommands:

nmake/fMakefile.wininstallrINSTDIR=dir

nmake/fMakefile.wininstalldINSTDIR=dir

ThedirargumenttoINSTDIRgivestheinstallationdirectory;itcanbeomittedifApacheistobeinstalledinto\Apache2.

Thiswillinstallthefollowing:

dir\bin\Apache.exe-Apacheexecutabledir\bin\ApacheMonitor.exe-Servicemonitortaskbariconutilitydir\bin\htdigest.exe-Digestauthpasswordfileutilitydir\bin\htdbm.exe-SDBMauthdatabasepasswordfileutilitydir\bin\htpasswd.exe-Basicauthpasswordfileutilitydir\bin\logresolve.exe-Logfilednsnamelookuputilitydir\bin\rotatelogs.exe-Logfilecyclingutility

dir\bin\wintty.exe-Consolewindowutilitydir\bin\libapr.dll-ApachePortableRuntimesharedlibrarydir\bin\libaprutil.dll-ApacheUtilityRuntimesharedlibrarydir\bin\libhttpd.dll-ApacheCorelibrarydir\modules\mod_*.so-LoadableApachemodulesdir\conf-Configurationdirectorydir\logs-Emptyloggingdirectorydir\include-Clanguageheaderfilesdir\lib-Linklibraryfiles

WarningaboutbuildingApachefromthedevelopmenttree

Noteonlythe.dspfilesaremaintainedbetweenreleasebuilds.The.makfilesareNOTregenerated,duetothetremendouswasteofreviewer'stime.Therefore,youcannotrelyontheNMAKEcommandsabovetobuildrevised.dspprojectfilesunlessyouthenexportall.makfilesyourselffromtheproject.ThisisunnecessaryifyoubuildfromwithintheMicrosoftDeveloperStudioenvironment.

AlsonoteitisveryworthwhiletobuildtheBuildBintargetproject(orthecommandline_apacheror_apachedtarget)priortoexportingthemakefiles.Manyfilesareautogeneratedinthebuildprocess.Onlyafullbuildprovidesallofthedependentfilesrequiredtobuildproperdependencytreesforcorrectbuildbehavior.

Inordertocreatedistribution.makfiles,alwaysreviewthegenerated.mak(or.dep)dependenciesforPlatformSDKorothergarbageincludes.TheDevStudio\SharedIDE\bin\

(VC5)orDevStudio\Common\MSDev98\bin\(VC6)directorycontainsthesysincl.datfile,whichmustlistallexceptions.Updatethisfile(includingbothforwardandbackslashedpaths,suchasbothsys/time.handsys\time.h)toincludesuchdependencies.Includinglocal-installpathsinadistributed.makfilewillcausethebuildtofailcompletely.Anddon'tforgettorunsrclib/apr/build/fixwin32mak.plinordertofixabsolutepathswithinthe.makfiles.

UsingApacheWithNovellNetWare

Thisdocumentexplainshowtoinstall,configureandrunApache2.0underNovellNetWare6.0andabove.Ifyoufindanybugs,orwishtocontributeinotherways,pleaseuseourbugreportingpage.

Thebugreportingpageanddev-httpdmailinglistarenotprovidedtoanswerquestionsaboutconfigurationorrunningApache.Beforeyousubmitabugreportorrequest,firstconsultthisdocument,theFrequentlyAskedQuestionspageandtheotherrelevantdocumentationtopics.Ifyoustillhaveaquestionorproblem,postittothenovell.devsup.webservernewsgroup,wheremanyApacheusersaremorethanwillingtoanswernewandobscurequestionsaboutusingApacheonNetWare.

MostofthisdocumentassumesthatyouareinstallingApachefromabinarydistribution.IfyouwanttocompileApacheyourself(possiblytohelpwithdevelopment,ortotrackdownbugs),seethesectiononCompilingApacheforNetWarebelow.

Requirements

Apache2.0isdesignedtorunonNetWare6.0servicepack3andabove.IfyouarerunningaservicepacklessthanSP3,youmustinstallthelatestNetWareLibrariesforC(LibC).

NetWareservicepacksareavailablehere.

Apache2.0forNetWarecanalsoberuninaNetWare5.1environmentaslongasthelatestservicepackorthelatestversionoftheNetWareLibrariesforC(LibC)hasbeeninstalled.WARNING:Apache2.0forNetWarehasnotbeentargetedforortestedinthisenvironment.

DownloadingApacheforNetWare

InformationonthelatestversionofApachecanbefoundontheApachewebserverathttp://www.apache.org/.Thiswilllistthecurrentrelease,anymorerecentalphaorbeta-testreleases,togetherwithdetailsofmirrorwebandanonymousftpsites.BinarybuildsofthelatestreleasesofApache2.0forNetWarecanbedownloadedfromhere.

InstallingApacheforNetWare

ThereisnoApacheinstallprogramforNetWarecurrently.IfyouarebuildingApache2.0forNetWarefromsource,youwillneedtocopythefilesovertotheservermanually.

FollowthesestepstoinstallApacheonNetWarefromthebinarydownload(assumingyouwillinstalltosys:/apache2):

UnzipthebinarydownloadfiletotherootoftheSYS:volume(maybeinstalledtoanyvolume)Editthehttpd.conffilesettingServerRootandServerNamealongwithanyfilepathvaluestoreflectyourcorrectserversettingsAddSYS:/APACHE2tothesearchpath,forexample:

SEARCHADDSYS:\APACHE2

FollowthesestepstoinstallApacheonNetWaremanuallyfromyourownbuildsource(assumingyouwillinstalltosys:/apache2):

CreateadirectorycalledApache2onaNetWarevolumeCopyAPACHE2.NLM,APRLIB.NLMtoSYS:/APACHE2CreateadirectoryunderSYS:/APACHE2calledBINCopyHTDIGEST.NLM,HTPASSWD.NLM,HTDBM.NLM,LOGRES.NLM,ROTLOGS.NLMtoSYS:/APACHE2/BINCreateadirectoryunderSYS:/APACHE2calledCONFCopytheHTTPD-STD.CONFfiletotheSYS:/APACHE2/CONFdirectoryandrenametoHTTPD.CONFCopytheMIME.TYPES,CHARSET.CONVandMAGICfilestoSYS:/APACHE2/CONFdirectoryCopyallfilesandsubdirectoriesin\HTTPD-2.0\DOCS\ICONStoSYS:/APACHE2/ICONS

Copyallfilesandsubdirectoriesin\HTTPD-2.0\DOCS\MANUALtoSYS:/APACHE2/MANUALCopyallfilesandsubdirectoriesin\HTTPD-2.0\DOCS\ERRORtoSYS:/APACHE2/ERRORCopyallfilesandsubdirectoriesin\HTTPD-2.0\DOCS\DOCROOTtoSYS:/APACHE2/HTDOCSCreatethedirectorySYS:/APACHE2/LOGSontheserverCreatethedirectorySYS:/APACHE2/CGI-BINontheserverCreatethedirectorySYS:/APACHE2/MODULESandcopyallnlmmodulesintothemodulesdirectoryEdittheHTTPD.CONFfilesearchingforall@@Value@@markersandreplacingthemwiththeappropriatesettingAddSYS:/APACHE2tothesearchpath,forexample:

SEARCHADDSYS:\APACHE2

ApachemaybeinstalledtoothervolumesbesidesthedefaultSYSvolume.

Duringthebuildprocess,addingthekeyword"install"tothemakefilecommandlinewillautomaticallyproduceacompletedistributionpackageunderthesubdirectoryDIST.InstallApachebysimplycopyingthedistributionthatwasproducedbythemakfilestotherootofaNetWarevolume(see:CompilingApacheforNetWarebelow).

RunningApacheforNetWare

TostartApachejusttypeapacheattheconsole.ThiswillloadapacheintheOSaddressspace.IfyouprefertoloadApacheinaprotectedaddressspaceyoumayspecifytheaddressspacewiththeloadstatementasfollows:

loadaddressspace=apache2apache2

ThiswillloadApacheintoanaddressspacecalledapache2.RunningmultipleinstancesofApacheconcurrentlyonNetWareispossiblebyloadingeachinstanceintoitsownprotectedaddressspace.

AfterstartingApache,itwillbelisteningtoport80(unlessyouchangedtheListendirectiveintheconfigurationfiles).Toconnecttotheserverandaccessthedefaultpage,launchabrowserandentertheserver'snameoraddress.Thisshouldrespondwithawelcomepage,andalinktotheApachemanual.Ifnothinghappensoryougetanerror,lookintheerror_logfileinthelogsdirectory.

Onceyourbasicinstallationisworking,youshouldconfigureitproperlybyeditingthefilesintheconfdirectory.

TounloadApacherunningintheOSaddressspacejusttypethefollowingattheconsole:

unloadapache2

apache2shutdown

Ifapacheisrunninginaprotectedaddressspacespecifytheaddressspaceintheunloadstatement:

unloadaddressspace=apache2apache2

WhenworkingwithApacheitisimportanttoknowhowitwillfindtheconfigurationfiles.Youcanspecifyaconfigurationfileonthecommandlineintwoways:

-fspecifiesapathtoaparticularconfigurationfile

apache2-f"vol:/myserver/conf/my.conf"

apache-ftest/test.conf

Inthesecases,theproperServerRootshouldbesetintheconfigurationfile.

Ifyoudon'tspecifyaconfigurationfilenamewith-f,Apachewillusethefilenamecompiledintotheserver,usuallyconf/httpd.conf.InvokingApachewiththe-VswitchwilldisplaythisvaluelabeledasSERVER_CONFIG_FILE.ApachewillthendetermineitsServerRootbytryingthefollowing,inthisorder:

AServerRootdirectiveviaa-Cswitch.The-dswitchonthecommandline.CurrentworkingdirectoryTheserverrootcompiledintotheserver.

Theserverrootcompiledintotheserverisusuallysys:/apache2.invokingapachewiththe-VswitchwilldisplaythisvaluelabeledasHTTPD_ROOT.

Apache2.0forNetWareincludesasetofcommandlinedirectivesthatcanbeusedtomodifyordisplayinformationabouttherunninginstanceofthewebserver.Thesedirectivesareonly

availablewhileApacheisrunning.EachofthesedirectivesmustbeprecededbythekeywordAPACHE2.

RESTARTInstructsApachetoterminateallrunningworkerthreadsastheybecomeidle,rereadtheconfigurationfileandrestarteachworkerthreadbasedonthenewconfiguration.

VERSIONDisplaysversioninformationaboutthecurrentlyrunninginstanceofApache.

MODULESDisplaysalistofloadedmodulesbothbuilt-inandexternal.

DIRECTIVESDisplaysalistofallavailabledirectives.

SETTINGSEnablesordisablesthethreadstatusdisplayontheconsole.Whenenabled,thestateofeachrunningthreadsisdisplayedontheApacheconsolescreen.

SHUTDOWNTerminatestherunninginstanceoftheApachewebserver.

HELPDescribeseachoftheruntimedirectives.

BydefaultthesedirectivesareissuedagainsttheinstanceofApacherunningintheOSaddressspace.Toissueadirectiveagainstaspecificinstancerunninginaprotectedaddressspace,includethe-pparameteralongwiththenameoftheaddressspace.Formoreinformationtype"apache2Help"onthecommandline.

ConfiguringApacheforNetWare

Apacheisconfiguredbyreadingconfigurationfilesusuallystoredintheconfdirectory.ThesearethesameasfilesusedtoconfiguretheUnixversion,butthereareafewdifferentdirectivesforApacheonNetWare.SeetheApachedocumentationforalltheavailabledirectives.

ThemaindifferencesinApacheforNetWareare:

BecauseApacheforNetWareismultithreaded,itdoesnotuseaseparateprocessforeachrequest,asApachedoesonsomeUniximplementations.Insteadthereareonlythreadsrunning:aparentthread,andmultiplechildorworkerthreadswhichhandletherequests.

Thereforethe"process"-managementdirectivesaredifferent:

MaxRequestsPerChild-LiketheUnixdirective,thiscontrolshowmanyrequestsaworkerthreadwillservebeforeexiting.Therecommendeddefault,MaxRequestsPerChild0,causesthethreadtocontinueservicingrequestindefinitely.ItisrecommendedonNetWare,unlessthereissomespecificreason,thatthisdirectivealwaysremainsetto0.

StartThreads-Thisdirectivetellstheserverhowmanythreadsitshouldstartinitially.TherecommendeddefaultisStartThreads50.

MinSpareThreads-Thisdirectiveinstructstheservertospawnadditionalworkerthreadsifthenumberofidlethreadseverfallsbelowthisvalue.TherecommendeddefaultisMinSpareThreads10.

MaxSpareThreads-Thisdirectiveinstructstheservertobeginterminatingworkerthreadsifthenumberofidlethreads

everexceedsthisvalue.TherecommendeddefaultisMaxSpareThreads100.

MaxThreads-Thisdirectivelimitsthetotalnumberofworkthreadstoamaximumvalue.TherecommendeddefaultisThreadsPerChild250.

ThreadStackSize-Thisdirectivetellstheserverwhatsizeofstacktousefortheindividualworkerthread.TherecommendeddefaultisThreadStackSize65536.

ThedirectivesthatacceptfilenamesasargumentsmustuseNetWarefilenamesinsteadofUnixnames.However,becauseApacheusesUnix-stylenamesinternally,forwardslashesmustbeusedratherthanbackslashes.Itisrecommendedthatallrootedfilepathsbeginwithavolumename.Ifomitted,ApachewillassumetheSYS:volumewhichmaynotbecorrect.

ApacheforNetWarehastheabilitytoloadmodulesatruntime,withoutrecompilingtheserver.IfApacheiscompilednormally,itwillinstallanumberofoptionalmodulesinthe\Apache2\modulesdirectory.Toactivatethese,orothermodules,theLoadModuledirectivemustbeused.Forexample,toactivethestatusmodule,usethefollowing:

LoadModulestatus_modulemodules/status.nlm

Informationoncreatingloadablemodulesisalsoavailable.

AdditionalNetWarespecificdirectives:CGIMapExtension-ThisdirectivemapsaCGIfileextensiontoascriptinterpreter.

SecureListen-EnablesSSLencryptionforaspecifiedport.

NWSSLTrustedCerts-Addstrustedcertificatesthatareusedtocreatesecureconnectionstoproxiedservers.

NWSSLUpgradeable-Allowaconnectioncreatedonthespecifiedaddress/porttobeupgradedtoanSSLconnection.

CompilingApacheforNetWare

CompilingApacherequiresMetroWerksCodeWarrior6.xorhigher.OnceApachehasbeenbuilt,itcanbeinstalledtotherootofanyNetWarevolume.Thedefaultisthesys:/Apache2directory.

Beforerunningtheserveryoumustfillouttheconfdirectory.CopythefileHTTPD-STD.CONFfromthedistributionconfdirectoryandrenameittoHTTPD.CONF.EdittheHTTPD.CONFfilesearchingforall@@Value@@markersandreplacingthemwiththeappropriatesetting.Copyovertheconf/magicandconf/mime.typesfilesaswell.Alternatively,acompletedistributioncanbebuiltbyincludingthekeywordinstallwheninvokingthemakefiles.

Requirements:ThefollowingdevelopmenttoolsarerequiredtobuildApache2.0forNetWare:

MetrowerksCodeWarrior6.0orhigherwiththeNetWarePDK3.0orhigher.NetWareLibrariesforC(LibC)LDAPLibrariesforCZLIBCompressionLibrarysourcecodeAWKutility(awk,gawkorsimilar).AWKcanbedownloadedfromhttp://developer.novell.com/ndk/apache.htm.Theutilitymustbefoundinyourwindowspathandmustbenamedawk.exe.Tobuildusingthemakefiles,youwillneedGNUmakeversion3.78.1(GMake)availableathttp://developer.novell.com/ndk/apache.htm.

BuildingApacheusingtheNetWaremakefiles:

SettheenvironmentvariableNOVELLLIBCtothelocationoftheNetWareLibrariesforCSDK,forexample:

SetNOVELLLIBC=c:\novell\ndk\libc

SettheenvironmentvariableMETROWERKStothelocationwhereyouinstalledtheMetrowerksCodeWarriorcompiler,forexample:

SetMETROWERKS=C:\ProgramFiles\Metrowerks\CodeWarrior

IfyouinstalledtothedefaultlocationC:\ProgramFiles\Metrowerks\CodeWarrior,youdon'tneedtosetthis.SettheenvironmentvariableLDAPSDKtothelocationwhereyouinstalledtheLDAPLibrariesforC,forexample:

SetLDAPSDK=c:\Novell\NDK\cldapsdk\NetWare\libc

SettheenvironmentvariableZLIBSDKtothelocationwhereyouinstalledthesourcecodefortheZLibLibrary,forexample:

SetZLIBSDK=D:\NOVELL\zlib

SettheenvironmentvariableAP_WORKtothefullpathofthe\httpd-2.0directory.SettheenvironmentvariableAPR_WORKtothefullpathofthe\httpd-2.0\srclib\aprdirectory.MakesurethatthepathtotheAWKutilityandtheGNUmakeutility(gmake.exe)havebeenincludedinthesystem'sPATHenvironmentvariable.Downloadthesourcecodeandunziptoanappropriate

directoryonyourworkstation.Changedirectoryto\httpd-2.0\srclib\apr-util\uriandbuildGENURI.nlmbyrunning"gmake-fnwgnumakefile".CopythefileGENURI.nlmtotheSYS:volumeofaNetWareserverandrunusingthefollowingcommand:

SYS:\genuri>sys:\uri_delims.h

Copythefileuri_delims.htothedirectory\httpd-2.0\srclib\apr-util\urionthebuildmachine.Changedirectoryto\httpd-2.0\srclib\aprandbuildAPRbyrunning"gmake-fnwgnumakefile"Changedirectoryto\httpd-2.0\srclib\pcreandbuildDFTABLES.nlmbyrunning"gmake-fnwgnumakefile"Changedirectoryto\httpd-2.0\serverandbuildGENCHARS.nlmbyrunning"gmake-fnwgnumakefile"CopythefilesGENCHARS.nlmandDFTABLES.nlmfromtheirrespectivedirectoriestotheSYS:volumeofaNetWareserverandrunthemusingthefollowingcommands:

SYS:\genchars>sys:\test_char.h

SYS:\dftables>sys:\chartables.c

Copythefilestest_char.handchartables.ctothedirectory\httpd-2.0\os\netwareonthebuildmachine.Changedirectoryto\httpd-2.0andbuildApachebyrunning"gmake-fnwgnumakefile".Youcancreateadistributiondirectorybyaddinganinstallparametertothecommand,forexample:

gmake-fnwgnumakefileinstall

Additionalmakeoptionsgmake-fnwgnumakefile

Buildsreleaseversionsofallofthebinariesandcopiesthemtoa\releasedestinationdirectory.

gmake-fnwgnumakefileDEBUG=1

Buildsdebugversionsofallofthebinariesandcopiesthemtoa\debugdestinationdirectory.

gmake-fnwgnumakefileinstall

CreatesacompleteApachedistributionwithbinaries,docsandadditionalsupportfilesina\dist\Apache2directory.

gmake-fnwgnumakefileinstalldev

Sameasinstallbutalsocreatesa\liband\includedirectoryinthedestinationdirectoryandcopiesheadersandimportfiles.

gmake-fnwgnumakefileclean

Cleansallobjectfilesandbinariesfromthe\releaseor\debugbuildareasdependingonwhetherDEBUGhasbeendefined.

gmake-fnwgnumakefileclobber_all

Sameascleanandalsodeletesthedistributiondirectoryifitexists.

RunningaHigh-PerformanceWebServeronHPUX

Date:Wed,05Nov199716:59:34-0800

From:RickJones<raj@cup.hp.com>

Reply-To:raj@cup.hp.com

Organization:NetworkPerformance

Subject:HP-UXtuningtips

HerearesometuningtipsforHP-UXtoaddtothetuningpage.

ForHP-UX9.X:Upgradeto10.20ForHP-UX10.[00|01|10]:Upgradeto10.20

ForHP-UX10.20:

InstallthelatestcumulativeARPATransportPatch.ThiswillallowyoutoconfigurethesizeoftheTCPconnectionlookuphashtable.Thedefaultis256bucketsandmustbesettoapoweroftwo.Thisisaccomplishedwithadbagainstthe*disc*imageofthekernel.Thevariablenameistcp_hash_size.Noticethatit'scriticallyimportantthatyouuse"W"towritea32bitquantity,not"w"towritea16bitvaluewhenpatchingthediscimagebecausethetcp_hash_sizevariableisa32bitquantity.

Howtopickthevalue?Examinetheoutputofftp://ftp.cup.hp.com/dist/networking/tools/connhistandseehowmanytotalTCPconnectionsexistonthesystem.Youprobablywantthatnumberdividedbythehashtablesizetobereasonablysmall,saylessthan10.FolkscanlookatHP'sSPECweb96disclosuresforsomecommonsettings.Thesecanbefoundathttp://www.specbench.org/.IfanHP-UXsystemwasperformingat1000SPECweb96connectionspersecond,theTIME_WAITtimeof60secondswouldmean60,000TCP"connections"beingtracked.

Folkscanchecktheirlistenqueuedepthswithftp://ftp.cup.hp.com/dist/networking/misc/listenq.

IffolksarerunningApacheonaPA-8000basedsystem,theyshouldconsider"chatr'ing"theApacheexecutabletohavealargepagesize.Thiswouldbe"chatr+piL<BINARY>".TheGIDoftherunningexecutablemusthaveMLOCKprivileges.Setprivgrp(1m)shouldbeconsultedforassigningMLOCK.ThechangecanbevalidatedbyrunningGlanceandexaminingthememoryregionsoftheserver(s)tomakesurethattheyshowanon-trivialfractionofthetextsegmentbeinglocked.

IffolksarerunningApacheonMPsystems,theymightconsiderwritingasmallprogramthatusesmpctl()tobindprocessestoprocessors.Asimplepid%numcpualgorithmisprobablysufficient.Thismightevengointothesourcecode.

IffolksareconcernedaboutthenumberofFIN_WAIT_2connections,theycanusenettunetoshrinkthevalueoftcp_keepstart.However,theyshouldbecarefulthere-certainlydonotmakeitlessthanohtwotofourminutes.Iftcp_hash_sizehasbeensetwell,itisprobablyOKtolettheFIN_WAIT_2'stakelongertotimeout(perhapseventhedefaulttwohours)-theywillnotonaveragehaveabigimpactonperformance.

Thereareotherthingsthatcouldgointothecodebase,butthatmightbeleftforanotheremail.Feelfreetodropmeamessageifyouorothersareinterested.

sincerely,

rickjones

http://www.cup.hp.com/netperf/NetperfPage.html

TheApacheEBCDICPort

Warning:Thisdocumenthasnotbeenupdatedtotakeintoaccountchangesmadeinthe2.0versionoftheApacheHTTPServer.Someoftheinformationmaystillberelevant,butpleaseuseitwithcare.

OverviewoftheApacheEBCDICPort

Version1.3oftheApacheHTTPServeristhefirstversionwhichincludesaporttoa(non-ASCII)mainframemachinewhichusestheEBCDICcharactersetasitsnativecodeset.

(ItistheSIEMENSfamilyofmainframesrunningtheBS2000/OSDoperatingsystem.ThismainframeOSnowadaysfeaturesaSVR4-derivedPOSIXsubsystem).

Theportwasstartedinitiallyto

provethefeasibilityofportingtheApacheHTTPservertothisplatformfinda"worthyandcapable"successorforthevenerableCERN-3.0daemon(whichwasportedacoupleofyearsago),andtoprovethatApache'spreforkingprocessmodelcanonthisplatformeasilyoutperformtheaccept-fork-servemodelusedbyCERNbyafactorof5ormore.

Thisdocumentservesasarationaletodescribesomeofthedesigndecisionsoftheporttothismachine.

DesignGoals

OneobjectiveoftheEBCDICportwastomaintainenoughbackwardscompatibilitywiththe(EBCDIC)CERNservertomakethetransitiontothenewserverattractiveandeasy.ThisrequiredtheadditionofaconfigurablemethodtodefinewhetheraHTMLdocumentwasstoredinASCII(theonlyformatacceptedbytheoldserver)orinEBCDIC(thenativedocumentformatinthePOSIXsubsystem,andthereforetheonlyrealisticformatinwhichtheotherPOSIXtoolslikegreporsedcouldoperateonthedocuments).Thecurrentsolutiontothisisa"pseudo-MIME-format"whichisinterceptedandinterpretedbytheApacheserver(seebelow).Futureversionsmightsolvetheproblembydefiningan"ebcdic-handler"foralldocumentswhichmustbeconverted.

TechnicalSolution

SinceallApacheinputandoutputisbasedupontheBUFFdatatypeanditsmethods,theeasiestsolutionwastoaddtheconversiontotheBUFFhandlingroutines.Theconversionmustbesettableatanytime,soaBUFFflagwasaddedwhichdefineswhetheraBUFFobjecthascurrentlyenabledconversionornot.ThisflagismodifiedatseveralpointsintheHTTPprotocol:

setbeforearequestisreceived(becausetherequestandtherequestheaderlinesarealwaysinASCIIformat)set/unsetwhentherequestbodyisreceived-dependingonthecontenttypeoftherequestbody(becausetherequestbodymaycontainASCIItextorabinaryfile)setbeforeareplyheaderissent(becausetheresponseheaderlinesarealwaysinASCIIformat)set/unsetwhentheresponsebodyissent-dependingonthecontenttypeoftheresponsebody(becausetheresponsebodymaycontaintextorabinaryfile)

PortingNotes

1. Therelevantchangesinthesourceare#ifdef'edintotwocategories:

#ifdefCHARSET_EBCDIC

CodewhichisneededforanyEBCDICbasedmachine.Thisincludescharactertranslations,differencesincontiguityofthetwocharactersets,flagswhichindicatewhichpartoftheHTTPprotocolhastobeconvertedandwhichpartdoesn'tetc.

#ifdef_OSD_POSIX

CodewhichisneededfortheSIEMENSBS2000/OSDmainframeplatformonly.ThisdealswithincludefiledifferencesandsocketimplementationtopicswhichareonlyrequiredontheBS2000/OSDplatform.

2. ThepossibilitytotranslatebetweenASCIIandEBCDICatthesocketlevel(onBS2000POSIX,thereisasocketoptionwhichsupportsthis)wasintentionallynotchosen,becausethebytestreamattheHTTPprotocollevelconsistsofamixtureofprotocolrelatedstringsandnon-protocolrelatedrawfiledata.HTTPprotocolstringsarealwaysencodedinASCII(theGETrequest,anyHeader:lines,thechunkinginformationetc.)whereasthefiletransferparts(i.e.,GIFimages,CGIoutputetc.)shouldusuallybejust"passedthrough"bytheserver.Thisseparationbetween"protocolstring"and"rawdata"isreflectedintheservercodebyfunctionslikebgets()orrvputs()forstrings,andfunctionslikebwrite()forbinarydata.Aglobaltranslationofeverythingwouldthereforebeinadequate.

(Inthecaseoftextfilesofcourse,provisionsmustbemadesothatEBCDICdocumentsarealwaysservedinASCII)

3. Thisportthereforefeaturesabuilt-inprotocollevelconversionfortheserver-internalstrings(whichthecompilertranslatedtoEBCDICstrings)andthusforallserver-generateddocuments.ThehardcodedASCIIescapes\012and\015whichareubiquitousintheservercodeareanexception:theyarealreadythebinaryencodingoftheASCII\nand\randmustnotbeconvertedtoASCIIasecondtime.Thisexceptionisonlyrelevantforserver-generatedstrings;andexternalEBCDICdocumentsarenotexpectedtocontainASCIInewlinecharacters.

4. ByexaminingthecallhierarchyfortheBUFFmanagementroutines,Iaddedan"ebcdic/asciiconversionlayer"whichwouldbecrossedoneveryputs/write/get/gets,andaconversionflagwhichallowedenabling/disablingtheconversionson-the-fly.Usually,adocumentcrossesthislayertwicefromitsoriginsource(afileorCGIoutput)toitsdestination(therequestingclient):file->Apache,andApache->client.

TheservercannowreadtheheaderlinesofaCGI-scriptoutputinEBCDICformat,andthenfindoutthattheremainderofthescript'soutputisinASCII(likeinthecaseoftheoutputofaWWWCounterprogram:thedocumentbodycontainsaGIFimage).AllheaderprocessingisdoneinthenativeEBCDICformat;theserverthendetermines,basedonthetypeofdocumentbeingserved,whetherthedocumentbody(exceptforthechunkinginformation,ofcourse)isinASCIIalreadyormustbeconvertedfromEBCDIC.

5. ForTextdocuments(MIMEtypestext/plain,text/htmletc.),animplicittranslationtoASCIIcanbeused,or(iftheusersprefertostoresomedocumentsinrawASCIIformforfasterserving,orbecausethefilesresideonaNFS-mounteddirectorytree)canbeservedwithoutconversion.

Example:

toservefileswiththesuffix.ahtmlasarawASCIItext/htmldocumentwithoutimplicitconversion(andsuffix.asciiasASCIItext/plain),usethedirectives:

AddTypetext/x-ascii-html.ahtml

AddTypetext/x-ascii-plain.ascii

Similarly,anytext/fooMIMEtypecanbeservedas"rawASCII"byconfiguringaMIMEtype"text/x-ascii-foo"foritusingAddType.

6. Non-textdocumentsarealwaysserved"binary"withoutconversion.Thisseemstobethemostsensiblechoicefor,.e.g.,GIF/ZIP/AUfiletypes.Thisofcourserequirestheusertocopythemtothemainframehostusingthe"rcp-b"binaryswitch.

7. Serverparsedfilesarealwaysassumedtobeinnative(i.e.,EBCDIC)formatasusedonthemachine,andareconvertedafterprocessing.

8. ForCGIoutput,theCGIscriptdetermineswhetheraconversionisneededornot:bysettingtheappropriateContent-Type,textfilescanbeconverted,orGIFoutputcanbepassedthroughunmodified.Anexampleforthelattercaseisthewwwcountprogramwhichweportedaswell.

DocumentStorageNotes

BinaryFilesAllfileswithaContent-Type:whichdoesnotstartwithtext/areregardedasbinaryfilesbytheserverandarenotsubjecttoanyconversion.ExamplesforbinaryfilesareGIFimages,gzip-compressedfilesandthelike.

WhenexchangingbinaryfilesbetweenthemainframehostandaUnixmachineorWindowsPC,besuretousetheftp"binary"(TYPEI)command,orusethercp-bcommandfromthemainframehost(the-bswitchisnotsupportedinunixrcp's).

TextDocumentsThedefaultassumptionoftheserveristhatTextFiles(i.e.,allfileswhoseContent-Type:startswithtext/)arestoredinthenativecharactersetofthehost,EBCDIC.

ServerSideIncludedDocumentsSSIdocumentsmustcurrentlybestoredinEBCDIConly.NoprovisionismadetoconvertitfromASCIIbeforeprocessing.

ApacheModules'Status

Module Status Notescore +mod_access +mod_actions +mod_alias +mod_asis +mod_auth +mod_auth_anon +mod_auth_dbm ? withownlibdb.amod_autoindex +mod_cern_meta ?mod_cgi +mod_digest +mod_dir +mod_so - nosharedlibsmod_env +mod_example - (testbedonly)mod_expires +mod_headers +mod_imap +mod_include +mod_info +mod_log_agent +mod_log_config +mod_log_referer +mod_mime +mod_mime_magic ? notportedyetmod_negotiation +

mod_proxy +mod_rewrite + untestedmod_setenvif +mod_speling +mod_status +mod_unique_id +mod_userdir +mod_usertrack ? untested

ThirdPartyModules'Status

Module Status Notesmod_jserv - JAVAstillbeingported.mod_php3 + mod_php3runsfine,withLDAPandGD

andFreeTypelibraries.mod_put ? untestedmod_session - untested

ApacheHTTPServerVersion2.0Apache>HTTPServer>Documentation>Version2.0>Programs

httpd-ApacheHypertextTransferProtocolServer

httpdistheApacheHyperTextTransferProtocol(HTTP)serverprogram.Itisdesignedtoberunasastandalonedaemonprocess.Whenusedlikethisitwillcreateapoolofchildprocessesorthreadstohandlerequests.

Ingeneral,httpdshouldnotbeinvokeddirectly,butrathershouldbeinvokedviaapachectlonUnix-basedsystemsorasaserviceonWindowsNT,2000andXPandasaconsoleapplicationonWindows9xandME.

SeealsoStartingApacheStoppingApacheConfigurationFilesPlatform-specificDocumentationapachectl

Synopsishttpd[-dserverroot][-fconfig][-C

directive][-cdirective][-Dparameter][-

elevel][-Efile][-k

start|restart|graceful|stop][-Rdirectory][

-h][-l][-L][-S][-t][-v][-V][

OnWindowssystems,thefollowingadditionalargumentsareavailable:

httpd[-kinstall|config|uninstall][-nname]

Options

-dserverroot

SettheinitialvaluefortheServerRootdirectivetoserverroot.ThiscanbeoverriddenbytheServerRootdirectiveintheconfigurationfile.Thedefaultis/usr/local/apache2.

-fconfig

Usesthedirectivesinthefileconfigonstartup.Ifconfigdoesnotbeginwitha/,thenitistakentobeapathrelativetotheServerRoot.Thedefaultisconf/httpd.conf.

-kstart|restart|graceful|stop

Signalshttpdtostart,restart,orstop.SeeStoppingApacheformoreinformation.

-Cdirective

Processtheconfigurationdirectivebeforereadingconfigfiles.

-cdirective

Processtheconfigurationdirectiveafterreadingconfigfiles.

-Dparameter

Setsaconfigurationparameterwhichcanbeusedwith<IfDefine>sectionsintheconfigurationfilestoconditionallyskiporprocesscommandsatserverstartupandrestart.

-elevel

SetstheLogLeveltolevelduringserverstartup.Thisisusefulfortemporarilyincreasingtheverbosityoftheerrormessagestofindproblemsduringstartup.

-Efile

Senderrormessagesduringserverstartuptofile.

-Rdirectory

WhentheserveriscompiledusingtheSHARED_CORErule,

thisspecifiesthedirectoryforthesharedobjectfiles.

Outputashortsummaryofavailablecommandlineoptions.

Outputalistofmodulescompiledintotheserver.ThiswillnotlistdynamicallyloadedmodulesincludedusingtheLoadModuledirective.

Outputalistofdirectivestogetherwithexpectedargumentsandplaceswherethedirectiveisvalid.

Showthesettingsasparsedfromtheconfigfile(currentlyonlyshowsthevirtualhostsettings).

Runsyntaxtestsforconfigurationfilesonly.Theprogramimmediatelyexitsafterthesesyntaxparsingtestswitheitherareturncodeof0(SyntaxOK)orreturncodenotequalto0(SyntaxError).If-DDUMP_VHOSTSisalsoset,detailsofthevirtualhostconfigurationwillbeprinted.

Printtheversionofhttpd,andthenexit.

Printtheversionandbuildparametersofhttpd,andthenexit.

Runhttpdindebugmode.Onlyoneworkerwillbestartedandtheserverwillnotdetachfromtheconsole.

ThefollowingargumentsareavailableonlyontheWindowsplatform:

-kinstall|config|uninstall

InstallApacheasaWindowsNTservice;changestartupoptionsfortheApacheservice;anduninstalltheApacheservice.

-nname

ThenameoftheApacheservicetosignal.

Keeptheconsolewindowopenonerrorsothattheerrormessagecanberead.

ab-ApacheHTTPserverbenchmarkingtool

abisatoolforbenchmarkingyourApacheHypertextTransferProtocol(HTTP)server.ItisdesignedtogiveyouanimpressionofhowyourcurrentApacheinstallationperforms.ThisespeciallyshowsyouhowmanyrequestspersecondyourApacheinstallationiscapableofserving.

Seealsohttpd

Synopsisab[-Aauth-username:password][-cconcurrency

][-Ccookie-name=value][-d][-ecsv-file]

[-ggnuplot-file][-h][-Hcustom-header][

-i][-k][-nrequests][-pPOST-file][-P

proxy-auth-username:password][-q][-s][-S

][-ttimelimit][-Tcontent-type][-v

verbosity][-V][-w][-x<table>-attributes

][-Xproxy[:port]][-y<tr>-attributes][-z

<td>-attributes][http://]hostname[:port]/path

Options

-Aauth-username:password

SupplyBASICAuthenticationcredentialstotheserver.Theusernameandpasswordareseparatedbyasingle:andsentonthewirebase64encoded.Thestringissentregardlessofwhethertheserverneedsit(i.e.,hassentan401authenticationneeded).

-cconcurrency

Numberofmultiplerequeststoperformatatime.Defaultisonerequestatatime.

-Ccookie-name=value

AddaCookie:linetotherequest.Theargumentistypicallyintheformofaname=valuepair.Thisfieldisrepeatable.

Donotdisplaythe"percentageservedwithinXX[ms]table".(legacysupport).

-ecsv-file

WriteaCommaseparatedvalue(CSV)filewhichcontainsforeachpercentage(from1%to100%)thetime(inmilliseconds)ittooktoservethatpercentageoftherequests.Thisisusuallymoreusefulthanthe'gnuplot'file;astheresultsarealready'binned'.

-ggnuplot-file

Writeallmeasuredvaluesoutasa'gnuplot'orTSV(Tabseparatevalues)file.ThisfilecaneasilybeimportedintopackageslikeGnuplot,IDL,Mathematica,IgororevenExcel.Thelabelsareonthefirstlineofthefile.

Displayusageinformation.

-Hcustom-header

Appendextraheaderstotherequest.Theargumentis

typicallyintheformofavalidheaderline,containingacolon-separatedfield-valuepair(i.e.,"Accept-Encoding:zip/zop;8bit").

DoHEADrequestsinsteadofGET.

EnabletheHTTPKeepAlivefeature,i.e.,performmultiplerequestswithinoneHTTPsession.DefaultisnoKeepAlive.

-nrequests

Numberofrequeststoperformforthebenchmarkingsession.Thedefaultistojustperformasinglerequestwhichusuallyleadstonon-representativebenchmarkingresults.

-pPOST-file

FilecontainingdatatoPOST.

-Pproxy-auth-username:password

SupplyBASICAuthenticationcredentialstoaproxyen-route.Theusernameandpasswordareseparatedbyasingle:andsentonthewirebase64encoded.Thestringissentregardlessofwhethertheproxyneedsit(i.e.,hassentan407proxyauthenticationneeded).

Whenprocessingmorethan150requests,aboutputsaprogresscountonstderrevery10%or100requestsorso.The-qflagwillsuppressthesemessages.

Whencompiledin(ab-hwillshowyou)usetheSSLprotectedhttpsratherthanthehttpprotocol.Thisfeatureisexperimentalandveryrudimentary.Youprobablydonotwanttouseit.

Donotdisplaythemedianandstandarddeviationvalues,nordisplaythewarning/errormessageswhentheaverageandmedianaremorethanoneortwotimesthestandarddeviationapart.Anddefaulttothemin/avg/maxvalues.(legacysupport).

-ttimelimit

Maximumnumberofsecondstospendforbenchmarking.Thisimpliesa-n50000internally.Usethistobenchmarktheserverwithinafixedtotalamountoftime.Perdefaultthereisnotimelimit.

-Tcontent-type

Content-typeheadertouseforPOSTdata.

-vverbosity

Setverbositylevel-4andaboveprintsinformationonheaders,3andaboveprintsresponsecodes(404,200,etc.),2andaboveprintswarningsandinfo.

Displayversionnumberandexit.

PrintoutresultsinHTMLtables.Defaulttableistwocolumnswide,withawhitebackground.

-x<table>-attributes

Stringtouseasattributesfor<table>.Attributesareinserted<tablehere>.

-Xproxy[:port]

Useaproxyserverfortherequests.

-y<tr>-attributes

Stringtouseasattributesfor<tr>.

-z<td>-attributes

Stringtouseasattributesfor<td>.

Therearevariousstaticallydeclaredbuffersoffixedlength.Combinedwiththelazyparsingofthecommandlinearguments,theresponseheadersfromtheserverandotherexternalinputs,thismightbiteyou.

ItdoesnotimplementHTTP/1.xfully;onlyacceptssome'expected'formsofresponses.Theratherheavyuseofstrstr(3)showsuptopinprofile,whichmightindicateaperformanceproblem;i.e.,youwouldmeasuretheabperformanceratherthantheserver's.

apachectl-ApacheHTTPServerControlInterface

apachectlisafrontendtotheApacheHyperTextTransferProtocol(HTTP)server.ItisdesignedtohelptheadministratorcontrolthefunctioningoftheApachehttpddaemon.

Theapachectlscriptcanoperateintwomodes.First,itcanactasasimplefront-endtothehttpdcommandthatsimplysetsanynecessaryenvironmentvariablesandtheninvokeshttpd,passingthroughanycommandlinearguments.Second,apachectlcanactasaSysVinitscript,takingsimpleone-wordargumentslikestart,restart,andstop,andtranslatingthemintoappropriatesignalstohttpd.

IfyourApacheinstallationusesnon-standardpaths,youwillneedtoedittheapachectlscripttosettheappropriatepathstothehttpdbinary.Youcanalsospecifyanynecessaryhttpdcommandlinearguments.Seethecommentsinthescriptfordetails.

Theapachectlscriptreturnsa0exitvalueonsuccess,and>0ifanerroroccurs.Formoredetails,viewthecommentsinthescript.

SeealsoStartingApacheStoppingApacheConfigurationFilesPlatformDocshttpd

Synopsis

Whenactinginpass-throughmode,apachectlcantakealltheargumentsavailableforthehttpdbinary.

apachectl[httpd-argument]

WhenactinginSysVinitmode,apachectltakessimple,one-wordcommands,definedbelow.

apachectlcommand

Options

OnlytheSysVinit-styleoptionsaredefinedhere.Otherargumentsaredefinedonthehttpdmanualpage.

StarttheApachehttpddaemon.Givesanerrorifitisalreadyrunning.Thisisequivalenttoapachectl-kstart.

StopstheApachehttpddaemon.Thisisequivalenttoapachectl-kstop.

restart

RestartstheApachehttpddaemon.Ifthedaemonisnotrunning,itisstarted.Thiscommandautomaticallycheckstheconfigurationfilesasinconfigtestbeforeinitiatingtherestarttomakesurethedaemondoesn'tdie.Thisisequivalenttoapachectl-krestart.

fullstatus

Displaysafullstatusreportfrommod_status.Forthistowork,youneedtohavemod_statusenabledonyourserverandatext-basedbrowsersuchaslynxavailableonyoursystem.TheURLusedtoaccessthestatusreportcanbesetbyeditingtheSTATUSURLvariableinthescript.

status

Displaysabriefstatusreport.Similartothefullstatusoption,exceptthatthelistofrequestscurrentlybeingservedisomitted.

graceful

GracefullyrestartstheApachehttpddaemon.Ifthedaemonisnotrunning,itisstarted.Thisdiffersfromanormalrestartinthatcurrentlyopenconnectionsarenotaborted.Asideeffect

isthatoldlogfileswillnotbeclosedimmediately.Thismeansthatifusedinalogrotationscript,asubstantialdelaymaybenecessarytoensurethattheoldlogfilesareclosedbeforeprocessingthem.ThiscommandautomaticallycheckstheconfigurationfilesasinconfigtestbeforeinitiatingtherestarttomakesureApachedoesn'tdie.Thisisequivalenttoapachectl-kgraceful.

configtest

Runaconfigurationfilesyntaxtest.ItparsestheconfigurationfilesandeitherreportsSyntaxOkordetailedinformationabouttheparticularsyntaxerror.Thisisequivalenttoapachectl-t.

Thefollowingadditionaloptionisavailable,butdeprecated.

startssl

Thisisequivalenttoapachectl-kstart-DSSL.Werecommendthatyouusethatcommandexplicitly,oryouadjustyourhttpd.conftoremovethe<IfDefine>sectionsothatSSLwillalwaysbeavailable.

apxs-APacheeXtenSiontool

apxsisatoolforbuildingandinstallingextensionmodulesfortheApacheHyperTextTransferProtocol(HTTP)server.Thisisachievedbybuildingadynamicsharedobject(DSO)fromoneormoresourceorobjectfileswhichthencanbeloadedintotheApacheserverunderruntimeviatheLoadModuledirectivefrommod_so.

SotousethisextensionmechanismyourplatformhastosupporttheDSOfeatureandyourApachehttpdbinaryhastobebuiltwiththemod_somodule.Theapxstoolautomaticallycomplainsifthisisnotthecase.Youcancheckthisyourselfbymanuallyrunningthecommand

$httpd-l

Themodulemod_soshouldbepartofthedisplayedlist.IftheserequirementsarefulfilledyoucaneasilyextendyourApacheserver'sfunctionalitybyinstallingyourownmoduleswiththeDSOmechanismbythehelpofthisapxstool:

$apxs-i-a-cmod_foo.c

gcc-fpic-DSHARED_MODULE-I/path/to/apache/include-cmod_foo.c

ld-Bshareable-omod_foo.somod_foo.o

cpmod_foo.so/path/to/apache/modules/mod_foo.so

chmod755/path/to/apache/modules/mod_foo.so

[activatingmodule`foo'in/path/to/apache/etc/httpd.conf]

$apachectlrestart

/path/to/apache/sbin/apachectlrestart:httpdnotrunning,trying

tostart

[TueMar3111:27:551998][debug]mod_so.c(303):loadedmodule

foo_module

/path/to/apache/sbin/apachectlrestart:httpdstarted

TheargumentsfilescanbeanyCsourcefile(.c),aobjectfile(.o)orevenalibraryarchive(.a).Theapxstoolautomaticallyrecognizes

theseextensionsandautomaticallyusedtheCsourcefilesforcompilationwhilejustusingtheobjectandarchivefilesforthelinkingphase.Butwhenusingsuchpre-compiledobjectsmakesuretheyarecompiledforpositionindependentcode(PIC)tobeabletousethemforadynamicallyloadedsharedobject.ForinstancewithGCCyoualwaysjusthavetouse-fpic.ForotherCcompilersconsultitsmanualpageoratwatchfortheflagsapxsusestocompiletheobjectfiles.

FormoredetailsaboutDSOsupportinApachereadthedocumentationofmod_soorperhapsevenreadthesrc/modules/standard/mod_so.csourcefile.

Seealsoapachectl

Synopsisapxs-g[-Sname=value]-nmodname

apxs-q[-Sname=value]query...

apxs-c[-Sname=value][-odsofile][-I

incdir][-Dname=value][-Llibdir][-l

libname][-Wc,compiler-flags][-Wl,linker-

flags]files...

apxs-i[-Sname=value][-nmodname][-a][

-A]dso-file...

apxs-e[-Sname=value][-nmodname][-a][

-A]dso-file...

Options

CommonOptions-nmodname

Thisexplicitlysetsthemodulenameforthe-i(install)and-g(templategeneration)option.Usethistoexplicitlyspecifythemodulename.Foroption-gthisisrequired,foroption-itheapxstooltriestodeterminethenamefromthesourceor(asafallback)atleastbyguessingitfromthefilename.

QueryOptions-q

Performsaqueryforapxs'sknowledgeaboutcertainsettings.Thequeryparameterscanbeoneormoreofthefollowingstrings:CC,CFLAGS,CFLAGS_SHLIB,INCLUDEDIR,LD_SHLIB,LDFLAGS_SHLIB,LIBEXECDIR,LIBS_SHLIB,SBINDIR,SYSCONFDIR,TARGET.Usethisformanuallydeterminingsettings.Forinstanceuse

INC=-I`apxs-qINCLUDEDIR`

insideyourownMakefilesifyouneedmanualaccesstoApache'sCheaderfiles.

ConfigurationOptions-Sname=value

Thisoptionchangestheapxssettingsdescribedabove.

TemplateGenerationOptions-g

Thisgeneratesasubdirectoryname(seeoption-n)andtheretwofiles:Asamplemodulesourcefilenamedmod_name.c

whichcanbeusedasatemplateforcreatingyourownmodulesorasaquickstartforplayingwiththeapxsmechanism.AndacorrespondingMakefileforeveneasierbuildandinstallingofthismodule.

DSOCompilationOptions-c

Thisindicatesthecompilationoperation.ItfirstcompilestheCsourcefiles(.c)offilesintocorrespondingobjectfiles(.o)andthenbuildsadynamicallysharedobjectindsofilebylinkingtheseobjectfilesplustheremainingobjectfiles(.oand.a)offiles.Ifno-ooptionisspecifiedtheoutputfileisguessedfromthefirstfilenameinfilesandthususuallydefaultstomod_name.so.

-odsofile

Explicitlyspecifiesthefilenameofthecreateddynamicallysharedobject.Ifnotspecifiedandthenamecannotbeguessedfromthefileslist,thefallbacknamemod_unknown.soisused.

-Dname=value

Thisoptionisdirectlypassedthroughtothecompilationcommand(s).Usethistoaddyourowndefinestothebuildprocess.

-Iincdir

Thisoptionisdirectlypassedthroughtothecompilationcommand(s).Usethistoaddyourownincludedirectoriestosearchtothebuildprocess.

-Llibdir

Thisoptionisdirectlypassedthroughtothelinkercommand.Usethistoaddyourownlibrarydirectoriestosearchtothebuildprocess.

-llibname

Thisoptionisdirectlypassedthroughtothelinkercommand.Usethistoaddyourownlibrariestosearchtothebuildprocess.

-Wc,compiler-flags

Thisoptionpassescompiler-flagsasadditionalflagstothecompilercommand.Usethistoaddlocalcompiler-specificoptions.

-Wl,linker-flags

Thisoptionpasseslinker-flagsasadditionalflagstothelinkercommand.Usethistoaddlocallinker-specificoptions.

DSOInstallationandConfigurationOptions-i

Thisindicatestheinstallationoperationandinstallsoneormoredynamicallysharedobjectsintotheserver'smodulesdirectory.

ThisactivatesthemodulebyautomaticallyaddingacorrespondingLoadModulelinetoApache'shttpd.confconfigurationfile,orbyenablingitifitalreadyexists.

Sameasoption-abutthecreatedLoadModuledirectiveisprefixedwithahashsign(#),i.e.,themoduleisjustpreparedforlateractivationbutinitiallydisabled.

Thisindicatestheeditingoperation,whichcanbeusedwiththe-aand-Aoptionssimilarlytothe-ioperationtoeditApache'shttpd.confconfigurationfilewithoutattemptingtoinstallthemodule.

Examples

AssumeyouhaveanApachemodulenamedmod_foo.cavailablewhichshouldextendApache'sserverfunctionality.ToaccomplishthisyoufirsthavetocompiletheCsourceintoasharedobjectsuitableforloadingintotheApacheserverunderruntimeviathefollowingcommand:

$apxs-cmod_foo.c

gcc-fpic-DSHARED_MODULE-I/path/to/apache/include-c

mod_foo.c

ThenyouhavetoupdatetheApacheconfigurationbymakingsureaLoadModuledirectiveispresenttoloadthissharedobject.Tosimplifythisstepapxsprovidesanautomaticwaytoinstallthesharedobjectinits"modules"directoryandupdatingthehttpd.conffileaccordingly.Thiscanbeachievedbyrunning:

$apxs-i-amod_foo.c

Thiswayalinenamed

LoadModulefoo_modulemodules/mod_foo.so

isaddedtotheconfigurationfileifstillnotpresent.Ifyouwanttohavethisdisabledperdefaultusethe-Aoption,i.e.

$apxs-i-Amod_foo.c

ForaquicktestoftheapxsmechanismyoucancreateasampleApachemoduletemplateplusacorrespondingMakefilevia:

$apxs-g-nfoo

Creating[DIR]foo

Creating[FILE]foo/Makefile

Creating[FILE]foo/mod_foo.c

ThenyoucanimmediatelycompilethissamplemoduleintoasharedobjectandloaditintotheApacheserver:

$cdfoo

$makeallreload

apxs-cmod_foo.c

gcc-fpic-DSHARED_MODULE-I/path/to/apache/include-c

mod_foo.c

apxs-i-a-n"foo"mod_foo.so

apachectlrestart

/path/to/apache/sbin/apachectlrestart:httpdnotrunning,

tryingtostart

[TueMar3111:27:551998][debug]mod_so.c(303):loadedmodule

foo_module

/path/to/apache/sbin/apachectlrestart:httpdstarted

YoucanevenuseapxstocompilecomplexmodulesoutsidetheApachesourcetree,likePHP3:

$cdphp3

$./configure--with-shared-apache=../apache-1.3

$apxs-c-olibphp3.somod_php3.clibmodphp3-so.a

gcc-fpic-DSHARED_MODULE-I/tmp/apache/include-cmod_php3.c

ld-Bshareable-olibphp3.somod_php3.olibmodphp3-so.a

becauseapxsautomaticallyrecognizedCsourcefilesandobjectfiles.OnlyCsourcefilesarecompiledwhileremainingobjectfilesareusedforthelinkingphase.

configure-Configurethesourcetree

TheconfigurescriptconfiguresthesourcetreeforcompilingandinstallingtheApacheHTTPServeronyourparticularplatform.Variousoptionsallowthecompilationofaservercorrespondingtoyourpersonalrequirements.

Thisscript,includedintherootdirectoryofthesourcedistribution,isforcompilationonUnixandUnix-likesystemsonly.Forotherplatforms,seetheplatformdocumentation.

SeealsoCompilingandInstalling

Synopsis

Youshouldcalltheconfigurescriptfromwithintherootdirectoryofthedistribution.

./configure[OPTION]...[VAR=VALUE]...

Toassignenvironmentvariables(e.g.CC,CFLAGS...),specifythemasVAR=VALUE.Seebelowfordescriptionsofsomeoftheusefulvariables.

Options

ConfigurationoptionsInstallationdirectoriesSystemtypesOptionalfeaturesOptionsforsupportprograms

ConfigurationoptionsThefollowingoptionsinfluencethebehaviorofconfigureitself.

--config-cache

Thisisanaliasfor--cache-file=config.cache

--cache-file=FILE

ThetestresultswillbecachedinfileFILE.Thisoptionisdisabledbydefault.

--help[short|recursive]

Outputthehelpandexit.Withtheargumentshortonlyoptionsspecifictothispackagewilldisplayed.Theargumentrecursivedisplaystheshorthelpofalltheincludedpackages.

--no-create

Theconfigurescriptisrunnormallybutdoesnotcreateoutputfiles.Thisisusefultocheckthetestresultsbeforegeneratingmakefilesforcompilation.

--quiet

Donotprintchecking...messagesduringtheconfigure

process.

--srcdir=DIR

DefinesdirectoryDIRtobethesourcefiledirectory.Defaultisthedirectory,whereconfigureislocated,ortheparentdirectory...

--silent

Sameas--quiet

--versionDisplaycopyrightinformationandexit.

InstallationdirectoriesTheseoptionsdefinetheinstallationdirectory.Theinstallationtreedependsontheselectedlayout.

--prefix=PREFIX

Installarchitecture-independentfilesinPREFIX.Bydefaulttheinstallationdirectoryissetto/usr/local/apache2.

--exec-prefix=EPREFIX

Installarchitecture-dependentfilesinEPREFIX.BydefaulttheinstallationdirectoryissettothePREFIXdirectory.

Bydefault,makeinstallwillinstallallthefilesin/usr/local/apache2/bin,/usr/local/apache2/libetc.Youcanspecifyaninstallationprefixotherthan/usr/local/apache2using--prefix,forinstance--prefix=$HOME.

Defineadirectorylayout--enable-layout=LAYOUT

Configurethesourcecodeandbuildscriptstoassumean

installationtreebasedonthelayoutLAYOUT.ThisallowsyoutoseparatelyspecifythelocationsforeachtypeoffilewithintheApacheHTTPServerinstallation.Theconfig.layoutfilecontainsseveralexampleconfigurations,andyoucanalsocreateyourowncustomconfigurationfollowingtheexamples.Thedifferentlayoutsinthisfilearegroupedinto<LayoutFOO>...</Layout>sectionsandreferredtobynameasinFOO.ThedefaultlayoutisApache.

FinetuningoftheinstallationdirectoriesForbettercontroloftheinstallationdirectories,usetheoptionsbelow.Pleasenotethatthedirectorydefaultsaresetbyautoconfandbeoverwrittenbythecorrespondinglayoutsetting.

--bindir=DIR

InstalluserexecutablesinDIR.Theuserexecutablesaresupportingprogramslikehtpasswd,dbmmanage,etc.whichareusefulforsiteadministrators.BydefaultDIRissettoEPREFIX/bin.

--datadir=DIR

Installread-onlyarchitecture-independentdatainDIR.BydefaultdatadirissettoPREFIX/share.Thisoptionisofferedbyautoconfandcurrentlyunused.

--includedir=DIR

InstallCheaderfilesinDIR.BydefaultincludedirissettoEPREFIX/include.

--infodir=DIR

InstallinfodocumentationinDIR.BydefaultinfodirissettoPREFIX/info.Thisoptioniscurrentlyunused.

--libdir=DIR

InstallobjectcodelibrariesinDIR.BydefaultlibdirissettoEPREFIX/lib.

--libexecdir=DIR

Installtheprogramexecutables(i.e.,sharedmodules)inDIR.BydefaultlibexecdirissettoEPREFIX/libexec.

--localstatedir=DIR

Installmodifiablesingle-machinedatainDIR.BydefaultlocalstatedirissettoPREFIX/var.Thisoptionisofferedbyautoconfandcurrentlyunused.

--mandir=DIR

InstallthemandocumentationinDIR.BydefaultmandirissettoEPREFIX/man.

--oldincludedir=DIR

InstallCheaderfilesfornon-gccinDIR.Bydefaultoldincludedirissetto/usr/include.Thisoptionisofferedbyautoconfandcurrentlyunused.

--sbindir=DIR

InstallthesystemadministratorexecutablesinDIR.Thoseareserverprogramslikehttpd,apachectl,suexec,etc.whichareneccessarytoruntheApacheHTTPServer.BydefaultsbindirissettoEPREFIX/sbin.

--sharedstatedir=DIR

Installmodifiablearchitecture-independentdatainDIR.BydefaultsharedstatedirissettoPREFIX/com.Thisoptionisofferedbyautoconfandcurrentlyunused.

--sysconfdir=DIR

Installread-onlysingle-machinedataliketheserverconfigurationfileshttpd.conf,mime.types,etc.inDIR.BydefaultsysconfdirissettoPREFIX/conf.

SystemtypesTheseoptionsareusedtocross-compiletheApacheHTTPServer

torunonanothersystem.Innormalcases,whenbuildingandrunningtheserveronthesamesystem,theseoptionsarenotused.

--build=BUILD

Definesthesystemtypeofthesystemonwhichthetoolsarebeingbuilt.Itdefaultstotheresultofthescriptconfig.guess.

--host=HOST

Definesthesystemtypeofthesystemonwhichtheserverwillrun.HOSTdefaultstoBUILD.

--target=TARGET

ConfigureforbuildingcompilersforthesystemtypeTARGET.ItdefaultstoHOST.ThisoptionisofferedbyautoconfandnotnecessaryfortheApacheHTTPServer.

OptionalFeaturesTheseoptionsareusedtofinetunethefeaturesyourHTTPserverwillhave.

GeneralsyntaxGenerallyyoucanusethefollowingsyntaxtoenableordisableafeature:

--disable-FEATURE

DonotincludeFEATURE.Thisisthesameas--enable-FEATURE=no.

--enable-FEATURE[=ARG]

IncludeFEATURE.ThedefaultvalueforARGisyes.

--enable-MODULE=shared

ThecorrespondingmodulewillbebuildasDSOmodule.

--enable-MODULE=static

Bydefaultenabledmodulesarelinkedstatically.Youcanforcethisexplicitly.

Noteconfigurewillnotcomplainabout--enable-fooeveniffoodoesn'texist,soyouneedtotypecarefully.

ModulesenabledbydefaultSomemodulesarecompiledbydefaultandhavetobedisabledexplicitly.Usethefollowingoptionstoremovediscretemodulesfromthecompilationprocess.

--disable-actions

Disableactiontriggeringonrequests,whichisprovidedbymod_actions.

--disable-alias

Disablethemappingofrequeststodifferentpartsofthefilesystem,whichisprovidedbymod_alias.

--disable-asis

Disablesupportforas-isfiletypes,whichisprovidedbymod_asis.

--disable-auth

Disableuser-basedaccesscontrolprovidedbymod_auth.ThismoduleprovidesforHTTPBasicAuthentication,wheretheusernamesandpasswordsarestoredinplaintextfiles.

--disable-autoindex

Disablethedirectorylistingfunctionalityprovidedbymod_autoindex.

--disable-access

Disablehost-basedaccesscontrolprovidedbymod_access.

--disable-cgi

mod_cgi,whichprovidessupportforCGIscripts,isenabledbydefaultwhenusinganon-threadedMPM.UsethisoptiontodisableCGIsupport.

--disable-cgid

WhenusingthethreadedMPMsworkerorperchildsupportforCGIscriptsisprovidedbymod_cgidbydefault.TodisableCGIsupportusethisoption.

--disable-charset-lite

Disablecharactersettranslationprovidedbymod_charset_lite.ThismodulewillbeinstalledbydefaultonlyonEBCDICsystems.

--disable-dir

Disabledirectoryrequesthandlingprovidedbymod_dir.

--disable-env

Disablesettingandclearingofenvironmentvariables,whichisprovidedbymod_env.

--disable-http

DisabletheHTTPprotocolhandling.Thehttpmoduleisabasicone,enablingtheservertofunctionasanHTTPserver.Itisonlyusefultodisableitifyouwanttouseanotherprotocolmoduleinstead.Don'tdisablethismoduleunlessyouarereallysurewhatyouaredoing.Note:Thismodulewillalwaysbelinkedstatically.

--disable-imap

Disablesupportforserverbasedimagemaps,whichprovidedbymod_imap.

--disable-include

DisableServerSideIncludesprovidedbymod_include.

--disable-log-config

Disabletheloggingconfigurationprovidedby

mod_log_config.Youwon'tbeabletologrequeststotheserverwithoutthismodule.

--disable-mime

mod_mimeassociatestherequestedfilename'sextensionswiththefile'sbehaviorandcontent(mime-type,language,charactersetandencoding).Disablingthemappingoffile-extensionstoMIMEisnormallynotrecommended.

--disable-negotiation

Disablecontentnegotiationprovidedbymod_negotiation.

--disable-setenvif

Disablesupportforbasingenvironmentvariablesonheaders,whichisprovidedbymod_setenvif.

--disable-status

Disabletheprocess/threadmonitoring,whichisprovidedbymod_status.

--disable-userdir

Disablethemappingofrequeststouser-specificdirectories,whichisprovidedbymod_userdir.

Modules,disabledbydefaultSomemodulesarecompiledbydefaultandhavetobeenabledexplicitlyorbyusingthekeywordsmostorall(see--enable-mods-sharedbelowforfurtherexplanation)tobeavailable.Thereforeusetheoptionsbelow.

--enable-auth-anon

Enableanonymoususeraccessprovidedbymod_auth_anon.

--enable-auth-dbm

mod_auth_dbmprovidesforHTTPBasicAuthentication,wheretheusernamesandpasswordsarestoredinDBMtype

databasefiles.Usethisoptiontoenablethemodule.

--enable-auth-digest

EnableRFC2617Digestauthenticationprovidedbymod_auth_digest.Thismoduleusesplaintextfilestostorethecredentials.

--enable-auth-ldap

EnableLDAPbasedauthenticationprovidedbymod_auth_ldap.

--enable-cache

Enabledynamicfilecachingprovidedbymod_cache.Thisexperimentalmodulemaybeinterestingforserverswithhighloadorcachingproxyservers.Atleastonestoragemanagementmodule(e.g.mod_disk_cacheormod_mem_cache)isalsonecessary.

--enable-cern-meta

EnabletheCERN-typemetafilessupportprovidedbymod_cern_meta.

--enable-charset-lite

Enablecharactersettranslationprovidedbymod_charset_lite.ThismodulewillbeinstalledbydefaultonlyonEBCDICsystems.Onothersystems,youhavetoenableit.

--enable-dav

EnabletheWebDAVprotocolhandlingprovidedbymod_dav.Supportforfilesystemresourcesisprovidedbytheseperatemodulemod_dav_fs.Thismoduleisalsoautomaticallyenabledwith--enable-dav.Note:mod_davcanonlybeusedtogetherwiththehttpprotocolmodule.

--enable-dav-fs

EnableDAVsupportforfilesystemresources,whichis

providedbymod_dav_fs.Thismoduleisaproviderforthemod_davmodule,soyoushouldalsouse--enable-dav.

--enable-deflate

Enabledeflatetransferencodingprovidedbymod_deflate.

--enable-disk-cache

Enablediskcachingprovidedbymod_disk_cache.

--enable-expires

EnableExpiresheadercontrolprovidedbymod_expires.

--enable-ext-filter

Enabletheexternalfiltersupportprovidedbymod_ext_filter.

--enable-file-cache

Enablethefilecacheprovidedbymod_file_cache.

--enable-headers

EnablecontrolofHTTPheadersprovidedbymod_headers.

--enable-info

Enabletheserverinformationprovidedbymod_info.

--enable-ldap

EnableLDAPcachingandconnectionpoolingservicesprovidedbymod_ldap.

--enable-logio

Enableloggingofinputandoutputbytesincludingheadersprovidedbymod_logio.

--enable-mem-cache

Enablememorycachingprovidedbymod_mem_cache.

--enable-mime-magic

EnableautomaticaldeterminingofMIMEtypes,whichisprovidedbymod_mime_magic.

--enable-isapi

Enabletheisapiextensionsupportprovidedbymod_isapi.

--enable-proxy

Enabletheproxy/gatewayfunctionalityprovidedbymod_proxy.TheproxyingcapabilitiesforCONNECT,FTPandHTTPareprovidedbytheseperatemodulesmod_proxy_connect,mod_proxy_ftpandmod_proxy_http.Thesethreemodulesarealsoautomaticallyenabledwith--enable-proxy.

--enable-proxy-connect

EnableproxysupportforCONNECTrequesthandling,whichisprovidedbymod_proxy_connect.Thismoduleisanextensionforthemod_proxymodule,soyoushouldalsouse--enable-proxy.

--enable-proxy-ftp

EnableproxysupportforFTPrequests,whichisprovidedbymod_proxy_ftp..Thismoduleisanextensionforthemod_proxymodule,soyoushouldalsouse--enable-proxy.

--enable-proxy-http

EnableproxysupportforHTTPrequests,whichisprovidedbymod_proxy_http.Thismoduleisanextensionforthemod_proxymodule,soyoushouldalsouse--enable-proxy.

--enable-rewrite

EnablerulebasedURLmanipulationprovidedbymod_rewrite.

--enable-so

EnableDSOcapabilityprovidedbymod_so.Thismodulewillbeautomaticallyenabledifyouusethe--enable-mods-sharedoption.

--enable-speling

EnablethefunctionalitytocorrectcommonURLmisspellings,whichisprovidedbymod_speling.

--enable-ssl

EnablesupportforSSL/TLSprovidedbymod_ssl.

--enable-unique-id

Enablethegenerationofper-requestuniqueids,whichisprovidedbymod_unique_id.

--enable-usertrack

Enableuser-sessiontrackingprovidedbymod_usertrack.

--enable-vhost-alias

Enablemassvirtualhostingprovidedbymod_vhost_alias.

ModulesfordevelopersThefollowingmodulesareusefulonlyfordevelopersandtestingpurposesandaredisabledbydefault.Usethefollowingoptionstoenablethem.Ifyouarenotsurewhetheryouneedoneofthesemodules,omitthem.

--enable-bucketeer

Enablethemanipulationfilterforbuckets,whichisprovidedbymod_bucketeer.

--enable-case-filter

Enabletheexampleuppercaseconversionoutputfiltersupportofmod_case_filter.

--enable-case-filter-in

Enabletheexampleuppercaseconversioninputfiltersupportofmod_case_filter_in.

--enable-echo

EnabletheECHOserverprovidedbymod_echo.

--enable-example

Enabletheexampleanddemomodulemod_example.

--enable-optional-fn-export

Enabletheexampleforanoptionalfunctionexporter,whichisprovidedbymod_optional_fn_export.

--enable-optional-fn-import

Enabletheexampleforanoptionalfunctionimporter,whichisprovidedbymod_optional_fn_import.

--enable-optional-hook-export

Enabletheexampleforanoptionalhookexporter,whichisprovidedbymod_optional_hook_export.

--enable-optional-hook-import

Enabletheexampleoptionalhookimporter,whichisprovidedbymod_optional_hook_import.

MPMsandthird-partymodulesToaddthenecessaryMultiProcessingModuleandadditionalthird-partymodulesusethefollowingoptions:

--with-module=module-type:module-file[,module-

type:module-file]

Addoneormorethird-partymodulestothelistofstaticallylinkedmodules.Themodulesourcefilemodule-filewillbesearchedinthemodules/module-typesubdirectoryofyourApacheHTTPserversourcetree.Ifitisnotfoundthereconfigureisconsideringmodule-filetobeanabsolutefilepathandtriestocopythesourcefileintothemodule-typesubdirectory.Ifthesubdirectorydoesn'texistitwillbecreatedandpopulatedwithastandardMakefile.in.

Thisoptionisusefultoaddsmallexternalmodulesconsistingofonesourcefile.Formorecomplexmodulesyoushouldreadthevendor'sdocumentation.

IfyouwanttobuildaDSOmoduleinsteadofastaticallylinkeduseapxs.

--with-mpm=MPM

Choosetheprocessmodelforyourserver.YouhavetoselectexactlyoneMulti-ProcessingModule.OtherwisethedefaultMPMforyouroperatingsystemwillbetaken.PossibleMPMsarebeos,leader,mpmt_os2,perchild,prefork,threadpoolandworker.

Cumulativeandotheroptions--enable-maintainer-mode

Turnondebuggingandcompiletimewarnings.

--enable-mods-shared=MODULE-LIST

Definesalistofmodulestobeenabledandbuildasdynamicsharedmodules.Thismean,thesemodulehavetobeloadeddynamicallybyusingtheLoadModuledirective.

MODULE-LISTisaspaceseparatedlistofmodulenamesenclosedbyquotationmarks.Themodulenamesaregivenwithouttheprecedingmod_.Forexample:

--enable-mods-shared='headersrewritedav'

Additionallyyoucanusethespecialkeywordsallandmost.Forexample,

--enable-mods-shared=most

willcompilemostmodulesandbuildthemasDSOmodules.

--enable-modules=MODULE-LIST

Thisoptionbehavessimilarto--enable-mods-shared,butwilllinkthegivenmodulesstatically.Thismean,thesemoduleswillalwaysbepresentwhilerunninghttpd.TheyneednotbeloadedwithLoadModule.

--enable-v4-mapped

AllowIPv6socketstohandleIPv4connections.

--with-port=PORT

Thisdefinestheportonwhichhttpdwilllisten.Thisportnumberisusedwhengeneratingtheconfigurationfilehttpd.conf.Thedefaultis80.

--with-program-name

Defineanalternativeexecutablename.Thedefaultishttpd.

OptionalpackagesTheseoptionsareusedtodefineoptionalpackages.

GeneralsyntaxGenerallyyoucanusethefollowingsyntaxtodefineanoptionalpackage:

--with-PACKAGE[=ARG]

UsethepackagePACKAGE.ThedefaultvalueforARGisyes.

--without-PACKAGE

DonotusethepackagePACKAGE.Thisisthesameas--with-PACKAGE=no.ThisoptionisprovidedbyautoconfbutnotveryusefulfortheApacheHTTPServer.

Specificpackages--with-apr=DIR|FILE

TheApachePortableRuntime(APR)ispartofthehttpd

sourcedistributionandwillautomaticallybebuildtogetherwiththeHTTPserver.IfyouwanttouseanalreadyinstalledAPRinsteadyouhavetotellconfigurethepathtotheapr-configscript.YoumaysettheabsolutepathandnameorthedirectorytotheinstalledAPR.apr-configmustexistwithinthisdirectoryorthesubdirectorybin.

--with-apr-util=DIR|FILE

TheApachePortableRuntimeUtilities(APU)arepartofthehttpdsourcedistributionandwillautomaticallybebuildtogetherwiththeHTTPserver.IfyouwanttouseanalreadyinstalledAPUinsteadyouhavetotellconfigurethepathtotheapu-configscript.YoumaysettheabsolutepathandnameorthedirectorytotheinstalledAPU.apu-configmustexistwithinthisdirectoryorthesubdirectorybin.

--with-ssl=DIR

Ifmod_sslhasbeenenabledconfiguresearchesforaninstalledOpenSSL.YoucansetthedirectorypathtotheSSL/TLStoolkitinstead.

--with-z=DIR

configuresearchesautomaticallyforaninstalledzliblibraryifyoursourceconfigurationrequiresone(e.g.,whenmod_deflateisenabled).Youcansetthedirectorypathtothecompressionlibraryinstead.

SeveralfeaturesoftheApacheHTTPServer,includingmod_authn_dbmandmod_rewrite'sDBMRewriteMapusesimplekey/valuedatabasesforquicklookupsofinformation.SDBMisincludedintheAPU,sothisdatabaseisalwaysavailable.Ifyouwouldliketouseotherdatabasetypes,usethefollowingoptionstoenablethem:

--with-gdbm[=path]

Ifnopathisspecified,configurewillsearchfortheincludefilesandlibrariesofaGNUDBMinstallationintheusualsearchpaths.Anexplicitpathwillcauseconfiguretolookinpath/libandpath/includefortherelevantfiles.Finally,thepathmayspecifyspecificincludeandlibrarypathsseparatedbyacolon.

--with-ndbm[=path]

Like--with-gdbm,bursearchesforaNewDBMinstallation.

--with-berkeley-db[=path]

Like--with-gdbm,butsearchesforaBerkeleyDBinstallation.

TheDBMoptionsareprovidedbytheAPUandpassedthroughtoitsconfigurationscript.TheyareuselesswhenusinganalreadyinstalledAPUdefinedby--with-apr-util.

YoumayusemorethenoneDBMimplementationtogetherwithyourHTTPserver.TheappropriatedDBMtypewillbeconfiguredwithintheruntimeconfigurationateachtime.

Optionsforsupportprograms--enable-static-support

Buildastaticallylinkedversionofthesupportbinaries.Thismeans,astand-aloneexecutablewillbebuiltwithallthenecessarylibrariesintegrated.Otherwisethesupportbinariesarelinkeddynamicallybydefault.

--enable-suexec

Usethisoptiontoenablesuexec,whichallowsyoutosetuidandgidforspawnedprocesses.Donotusethisoptionunlessyouunderstandallthesecurityimplicationsofrunningasuidbinaryonyourserver.Furtheroptionsto

configuresuexecaredescribedbelow.

Itispossibletocreateastaticallylinkedbinaryofasinglesupportprogrambyusingthefollowingoptions:

--enable-static-ab

Buildastaticallylinkedversionofab.

--enable-static-checkgid

Buildastaticallylinkedversionofcheckgid.

--enable-static-htdbm

Buildastaticallylinkedversionofhtdbm.

--enable-static-htdigest

Buildastaticallylinkedversionofhtdigest.

--enable-static-htpasswd

Buildastaticallylinkedversionofhtpasswd.

--enable-static-logresolve

Buildastaticallylinkedversionoflogresolve.

--enable-static-rotatelogs

Buildastaticallylinkedversionofrotatelogs.

suexecconfigurationoptionsThefollowingoptionsareusedtofinetunethebehaviorofsuexec.SeeConfiguringandinstallingsuEXECorfurtherinformation.

--with-suexec-bin

Thisdefinesthepathtosuexecbinary.Defaultis--sbindir(seeFinetuningofinstallationdirectories).

--with-suexec-caller

Thisdefinestheuserallowedtocallsuexec.Itshouldbethesameastheuserunderwhichhttpdnormallyruns.

--with-suexec-docroot

Thisdefinesthedirectorytreeunderwhichsuexecaccessisallowedforexecutables.Defaultvalueis--datadir/htdocs.

--with-suexec-gidmin

DefinethisasthelowestGIDallowedtobeatargetuserforsuexec.Thedefaultvalueis100.

--with-suexec-logfile

Thisdefinesthefilenameofthesuexeclogfile.Bydefaultthelogfileisnamedsuexec_logandlocatedin--logfiledir.

--with-suexec-safepath

DefinethevalueoftheenvironmentvariablePATHtobesetforprocessesstartedbysuexec.Defaultvalueis/usr/local/bin:/usr/bin:/bin.

--with-suexec-userdir

Thisdefinesthesubdirectoryundertheuser'sdirectorythatcontainsallexecutablesforwhichsuexecaccessisallowed.Thissettingisnecessarywhenyouwanttousesuexectogetherwithuser-specificdirectories(asprovidedbymod_userdir).Thedefaultispublic_html.

--with-suexec-uidmin

DefinethisasthelowestUIDallowedtobeatargetuserforsuexec.Thedefaultvalueis100.

--with-suexec-umask

Setumaskforprocessesstartedbysuexec.Itdefaultstoyoursystemsettings.

Environmentvariables

Therearesomeusefulenvironmentvariablestooverridethechoicesmadebyconfigureortohelpittofindlibrariesandprogramswithnonstandardnamesorlocations.

DefinetheCcompilercommandtobeusedforcompilation.

CFLAGS

SetCcompilerflagsyouwanttouseforcompilation.

DefinetheCpreprocessorcommandtobeused.

CPPFLAGS

SetC/C++preprocessorflags,e.g.-Iincludedirifyouhaveheadersinanonstandarddirectoryincludedir.

LDFLAGS

Setlinkerflags,e.g.-Llibdirifyouhavelibrariesinanonstandarddirectorylibdir.

dbmmanage-ManageuserauthenticationfilesinDBMformat

dbmmanageisusedtocreateandupdatetheDBMformatfilesusedtostoreusernamesandpasswordforbasicauthenticationofHTTPusersviamod_auth_dbm.ResourcesavailablefromtheApacheHTTPservercanberestrictedtojusttheuserslistedinthefilescreatedbydbmmanage.ThisprogramcanonlybeusedwhentheusernamesarestoredinaDBMfile.Touseaflat-filedatabaseseehtpasswd.

Thismanualpageonlyliststhecommandlinearguments.Fordetailsofthedirectivesnecessarytoconfigureuserauthenticationinhttpdseethehttpdmanual,whichispartoftheApachedistributionorcanbefoundathttp://httpd.apache.org/.

Seealsohttpd

mod_auth_dbm

Synopsisdbmmanage[encoding]filename

add|adduser|check|delete|updateusername[

encpasswd[group[,group...][comment]]]

dbmmanagefilenameview[username]

dbmmanagefilenameimport

Options

filename

ThefilenameoftheDBMformatfile.Usuallywithouttheextension.db,.pag,or.dir.

username

Theuserforwhichtheoperationsareperformed.Theusernamemaynotcontainacolon(:).

encpasswd

Thisisthealreadyencryptedpasswordtousefortheupdateandaddcommands.Youmayuseahyphen(-)ifyouwanttogetpromptedforthepassword,butfillinthefieldsafterwards.Additionallywhenusingtheupdatecommand,aperiod(.)keepstheoriginalpassworduntouched.

Agroup,whichtheuserismemberof.Agroupnamemaynotcontainacolon(:).Youmayuseahyphen(-)ifyoudon'twanttoassigntheusertoagroup,butfillinthecommentfield.Additionallywhenusingtheupdatecommand,aperiod(.)keepstheoriginalgroupsuntouched.

comment

Thisistheplaceforyouropaquecommentsabouttheuser,likerealname,mailaddressorsuchthings.Theserverwillignorethisfield.

Encodings-d

cryptencryption(default,exceptonWin32,Netware)

MD5encryption(defaultonWin32,Netware)

SHA1encryption

plaintext(notrecommended)

Commandsadd

Addsanentryforusernametofilenameusingtheencryptedpasswordencpasswd.

dbmmanagepasswords.dataddrbowenfoKntnEF3KSXA

adduser

Asksforapasswordandthenaddsanentryforusernametofilename.

dbmmanagepasswords.datadduserkrietz

Asksforapasswordandthenchecksifusernameisinfilenameandifit'spasswordmatchesthespecifiedone.

dbmmanagepasswords.datcheckrbowen

delete

Deletestheusernameentryfromfilename.

dbmmanagepasswords.datdeleterbowen

import

Readsusername:passwordentries(oneperline)fromSTDINandaddsthemtofilename.Thepasswordsalreadyhavetobecrypted.

update

Sameastheaddusercommand,exceptthatitmakessureusernamealreadyexistsinfilename.

dbmmanagepasswords.datupdaterbowen

JustdisplaysthecontentsoftheDBMfile.Ifyouspecifyausername,itdisplaystheparticularrecordonly.

dbmmanagepasswords.datview

OneshouldbeawarethatthereareanumberofdifferentDBMfileformatsinexistence,andwithalllikelihood,librariesformorethanoneformatmayexistonyoursystem.ThethreeprimaryexamplesareSDBM,NDBM,theGNUproject'sGDBM,andBerkeleyDB2.Unfortunately,alltheselibrariesusedifferentfileformats,andyoumustmakesurethatthefileformatusedbyfilenameisthesameformatthatdbmmanageexpectstosee.dbmmanagecurrentlyhasnowayofdeterminingwhattypeofDBMfileitislookingat.Ifusedagainstthewrongformat,willsimplyreturnnothing,ormaycreateadifferentDBMfilewithadifferentname,oratworst,itmaycorrupttheDBMfileifyouwereattemptingtowritetoit.

dbmmanagehasalistofDBMformatpreferences,definedbythe@AnyDBM::ISAarraynearthebeginningoftheprogram.SinceweprefertheBerkeleyDB2fileformat,theorderinwhichdbmmanagewilllookforsystemlibrariesisBerkeleyDB2,thenNDBM,thenGDBMandthenSDBM.ThefirstlibraryfoundwillbethelibrarydbmmanagewillattempttouseforallDBMfiletransactions.Thisorderingisslightlydifferentthanthestandard@AnyDBM::ISAorderinginPerl,aswellastheorderingusedbythesimpledbmopen()callinPerl,soifyouuseanyotherutilitiestomanageyourDBMfiles,theymustalsofollowthispreferenceordering.Similarcaremustbetakenifusingprogramsinotherlanguages,likeC,toaccessthesefiles.

OnecanusuallyusethefileprogramsuppliedwithmostUnixsystemstoseewhatformataDBMfileisin.

htdigest-manageuserfilesfordigestauthentication

htdigestisusedtocreateandupdatetheflat-filesusedtostoreusernames,realmandpasswordfordigestauthenticationofHTTPusers.ResourcesavailablefromtheApacheHTTPservercanberestrictedtojusttheuserslistedinthefilescreatedbyhtdigest.

Thismanualpageonlyliststhecommandlinearguments.FordetailsofthedirectivesnecessarytoconfiguredigestauthenticationinhttpdseetheApachemanual,whichispartoftheApachedistributionorcanbefoundathttp://httpd.apache.org/.

Seealsohttpd

mod_auth_digest

Synopsishtdigest[-c]passwdfilerealmusername

Options

Createthepasswdfile.Ifpasswdfilealreadyexists,itisdeletedfirst.

passwdfile

Nameofthefiletocontaintheusername,realmandpassword.If-cisgiven,thisfileiscreatedifitdoesnotalreadyexist,ordeletedandrecreatedifitdoesexist.

Therealmnametowhichtheusernamebelongs.

username

Theusernametocreateorupdateinpasswdfile.Ifusernamedoesnotexististhisfile,anentryisadded.Ifitdoesexist,thepasswordischanged.

htpasswd-Manageuserfilesforbasicauthentication

htpasswdisusedtocreateandupdatetheflat-filesusedtostoreusernamesandpasswordforbasicauthenticationofHTTPusers.Ifhtpasswdcannotaccessafile,suchasnotbeingabletowritetotheoutputfileornotbeingabletoreadthefileinordertoupdateit,itreturnsanerrorstatusandmakesnochanges.

ResourcesavailablefromtheApacheHTTPservercanberestrictedtojusttheuserslistedinthefilescreatedbyhtpasswd.Thisprogramcanonlymanageusernamesandpasswordsstoredinaflat-file.Itcanencryptanddisplaypasswordinformationforuseinothertypesofdatastores,though.TouseaDBMdatabaseseedbmmanage.

htpasswdencryptspasswordsusingeitheraversionofMD5modifiedforApache,orthesystem'scrypt()routine.Filesmanagedbyhtpasswdmaycontainbothtypesofpasswords;someuserrecordsmayhaveMD5-encryptedpasswordswhileothersinthesamefilemayhavepasswordsencryptedwithcrypt().

Thismanualpageonlyliststhecommandlinearguments.FordetailsofthedirectivesnecessarytoconfigureuserauthenticationinhttpdseetheApachemanual,whichispartoftheApachedistributionorcanbefoundathttp://httpd.apache.org/.

Seealsohttpd

Thescriptsinsupport/SHA1whichcomewiththedistribution.

Synopsishtpasswd[-c][-m][-D]passwdfileusername

htpasswd-b[-c][-m|-d|-p|-s][-D]

passwdfileusernamepassword

htpasswd-n[-m|-d|-s|-p]username

htpasswd-nb[-m|-d|-s|-p]username

password

Options

Usebatchmode;i.e.,getthepasswordfromthecommandlineratherthanpromptingforit.Thisoptionshouldbeusedwithextremecare,sincethepasswordisclearlyvisibleonthecommandline.

Createthepasswdfile.Ifpasswdfilealreadyexists,itisrewrittenandtruncated.Thisoptioncannotbecombinedwiththe-noption.

Displaytheresultsonstandardoutputratherthanupdatingafile.ThisisusefulforgeneratingpasswordrecordsacceptabletoApacheforinclusioninnon-textdatastores.Thisoptionchangesthesyntaxofthecommandline,sincethepasswdfileargument(usuallythefirstone)isomitted.Itcannotbecombinedwiththe-coption.

UseMD5encryptionforpasswords.OnWindows,NetwareandTPF,thisisthedefault.

Usecrypt()encryptionforpasswords.ThedefaultonallplatformsbutWindows,NetwareandTPF.Thoughpossiblysupportedbyhtpasswdonallplatforms,itisnotsupportedbythehttpdserveronWindows,NetwareandTPF.

UseSHAencryptionforpasswords.Facilitatesmigrationfrom/toNetscapeserversusingtheLDAPDirectoryInterchangeFormat(ldif).

Useplaintextpasswords.Thoughhtpasswdwillsupport

creationonallplatforms,thehttpddaemonwillonlyacceptplaintextpasswordsonWindows,NetwareandTPF.

Deleteuser.Iftheusernameexistsinthespecifiedhtpasswdfile,itwillbedeleted.

passwdfile

Nameofthefiletocontaintheusernameandpassword.If-cisgiven,thisfileiscreatedifitdoesnotalreadyexist,orrewrittenandtruncatedifitdoesexist.

username

Theusernametocreateorupdateinpasswdfile.Ifusernamedoesnotexistinthisfile,anentryisadded.Ifitdoesexist,thepasswordischanged.

password

Theplaintextpasswordtobeencryptedandstoredinthefile.Onlyusedwiththe-bflag.

ExitStatus

htpasswdreturnsazerostatus("true")iftheusernameandpasswordhavebeensuccessfullyaddedorupdatedinthepasswdfile.htpasswdreturns1ifitencounterssomeproblemaccessingfiles,2iftherewasasyntaxproblemwiththecommandline,3ifthepasswordwasenteredinteractivelyandtheverificationentrydidn'tmatch,4ifitsoperationwasinterrupted,5ifavalueistoolong(username,filename,password,orfinalcomputedrecord),6iftheusernamecontainsillegalcharacters(seetheRestrictionssection),and7ifthefileisnotavalidpasswordfile.

Examples

htpasswd/usr/local/etc/apache/.htpasswd-usersjsmith

Addsormodifiesthepasswordforuserjsmith.Theuserispromptedforthepassword.IfexecutedonaWindowssystem,thepasswordwillbeencryptedusingthemodifiedApacheMD5algorithm;otherwise,thesystem'scrypt()routinewillbeused.Ifthefiledoesnotexist,htpasswdwilldonothingexceptreturnanerror.

htpasswd-c/home/doe/public_html/.htpasswdjane

Createsanewfileandstoresarecordinitforuserjane.Theuserispromptedforthepassword.Ifthefileexistsandcannotberead,orcannotbewritten,itisnotalteredandhtpasswdwilldisplayamessageandreturnanerrorstatus.

htpasswd-mb/usr/web/.htpasswd-alljonesPwd4Steve

Encryptsthepasswordfromthecommandline(Pwd4Steve)usingtheMD5algorithm,andstoresitinthespecifiedfile.

SecurityConsiderations

WebpasswordfilessuchasthosemanagedbyhtpasswdshouldnotbewithintheWebserver'sURIspace--thatis,theyshouldnotbefetchablewithabrowser.

Theuseofthe-boptionisdiscouraged,sincewhenitisusedtheunencryptedpasswordappearsonthecommandline.

Restrictions

OntheWindowsandMPEplatforms,passwordsencryptedwithhtpasswdarelimitedtonomorethan255charactersinlength.Longerpasswordswillbetruncatedto255characters.

TheMD5algorithmusedbyhtpasswdisspecifictotheApachesoftware;passwordsencryptedusingitwillnotbeusablewithotherWebservers.

Usernamesarelimitedto255bytesandmaynotincludethecharacter:.

logresolve-ResolveIP-addressestohostnamesinApachelogfiles

logresolveisapost-processingprogramtoresolveIP-addressesinApache'saccesslogfiles.Tominimizeimpactonyournameserver,logresolvehasitsveryowninternalhash-tablecache.ThismeansthateachIPnumberwillonlybelookedupthefirsttimeitisfoundinthelogfile.

TakesanApachelogfileonstandardinput.TheIPaddressesmustbethefirstthingoneachlineandmustbeseperatedfromtheremainderofthelinebyaspace.

Synopsislogresolve[-sfilename][-c]<access_log>

access_log.new

Options

-sfilename

Specifiesafilenametorecordstatistics.

ThiscauseslogresolvetoapplysomeDNSchecks:afterfindingthehostnamefromtheIPaddress,itlooksuptheIPaddressesforthehostnameandchecksthatoneofthesematchestheoriginaladdress.

rotatelogs-PipedloggingprogramtorotateApachelogs

rotatelogsisasimpleprogramforuseinconjunctionwithApache'spipedlogfilefeature.Forexample:

CustomLog"|bin/rotatelogs/var/logs/logfile86400"common

Thiscreatesthefiles/var/logs/logfile.nnnnwherennnnisthesystemtimeatwhichthelognominallystarts(thistimewillalwaysbeamultipleoftherotationtime,soyoucansynchronizecronscriptswithit).Attheendofeachrotationtime(hereafter24hours)anewlogisstarted.

CustomLog"|bin/rotatelogs/var/logs/logfile5M"common

Thisconfigurationwillrotatethelogfilewheneveritreachesasizeof5megabytes.

ErrorLog"|bin/rotatelogs/var/logs/errorlog.%Y-%m-%d-%H_%M_%S5M"

Thisconfigurationwillrotatetheerrorlogfilewheneveritreachesasizeof5megabytes,andthesuffixtothelogfilenamewillbecreatedoftheformerrorlog.YYYY-mm-dd-HH_MM_SS.

Synopsisrotatelogs[-l]logfile[rotationtime[offset

]]|[filesizeM]

Options

-l(2.0.51andlater)CausestheuseoflocaltimeratherthanGMTasthebasefortheinterval.Notethatusing-linanenvironmentwhichchangestheGMToffset(suchasforBSTorDST)canleadtounpredictableresults!

logfile

Thepathplusbasenameofthelogfile.Iflogfileincludesany'%'characters,itistreatedasaformatstringforstrftime(3).Otherwise,thesuffix.nnnnnnnnnnisautomaticallyaddedandisthetimeinseconds.Bothformatscomputethestarttimefromthebeginningofthecurrentperiod.

rotationtime

Thetimebetweenlogfilerotationsinseconds.

offset

ThenumberofminutesoffsetfromUTC.Ifomitted,zeroisassumedandUTCisused.Forexample,touselocaltimeinthezoneUTC-5hours,specifyavalueof-300forthisargument.

filesizeM

ThemaximumfilesizeinmegabytesfollowedbytheletterMtospecifysizeratherthantime.Usethisparameterinplaceofbothrotationtimeandoffset.

Portability

Thefollowinglogfileformatstringsubstitutionsshouldbesupportedbyallstrftime(3)implementations,seethestrftime(3)manpageforlibrary-specificextensions.

%A fullweekdayname(localized)%a 3-characterweekdayname(localized)%B fullmonthname(localized)%b 3-charactermonthname(localized)%c dateandtime(localized)%d 2-digitdayofmonth%H 2-digithour(24hourclock)%I 2-digithour(12hourclock)%j 3-digitdayofyear%M 2-digitminute%m 2-digitmonth%p am/pmof12hourclock(localized)%S 2-digitsecond%U 2-digitweekofyear(Sundayfirstdayofweek)%W 2-digitweekofyear(Mondayfirstdayofweek)%w 1-digitweekday(Sundayfirstdayofweek)%X time(localized)%x date(localized)%Y 4-digityear%y 2-digityear%Z timezonename%% literal`%'

OtherPrograms

ThefollowingprogramsaresimplesupportprogramsincludedwiththeApacheHTTPServerwhichdonothavetheirownmanualpages.Theyarenotinstalledautomatically.Youcanfindthemaftertheconfigurationprocessinthesupport/directory.

log_server_status

Thisperlscriptisdesignedtoberunatafrequentintervalbysomethinglikecron.Itconnectstotheserveranddownloadsthestatusinformation.Itreformatstheinformationtoasinglelineandlogsittoafile.Adjustthevariablesatthetopofthescripttospecifythelocationoftheresultinglogfile.

split-logfile

ThisperlscriptwilltakeacombinedWebserveraccesslogfileandbreakitscontentsintoseparatefiles.Itassumesthatthefirstfieldofeachlineisthevirtualhostidentity(putthereby"%v"),andthatthelogfilesshouldbenamedthat+".log"inthecurrentdirectory.

Thecombinedlogfileisreadfromstdin.Recordsreadwillbeappendedtoanyexistinglogfiles.

split-logfile<access.log

InternationalCustomizedServerErrorMessages

Warning:

ThisdocumentdescribesaneasywaytoprovideyourApacheHTTPServerwithasetofcustomizederrormessageswhichtakeadvantageofContentNegotiationandmod_includetoreturnerrormessagesgeneratedbytheserverintheclient'snativelanguage.

Introduction

ByusingSSI,allErrorDocumentmessagescanshareahomogenousandconsistentstyleandlayout,andmaintenancework(changingimages,changinglinks)iskepttoaminimumbecausealllayoutinformationcanbekeptinasinglefile.

Errordocumentscanbesharedacrossdifferentservers,orevenhosts,becauseallvaryinginformationisinsertedatthetimetheerrordocumentisreturnedonbehalfofafailedrequest.

ContentNegotiationthenselectstheappropriatelanguageversionofaparticularerrormessagetext,honoringthelanguagepreferencespassedintheclient'srequest.(Usersusuallyselecttheirfavoritelanguagesinthepreferencesoptionsmenuoftoday'sbrowsers).Whenanerrordocumentintheclient'sprimarylanguageversionisunavailable,thesecondarylanguagesaretriedoradefault(fallback)versionisused.

Youhavefullflexibilityindesigningyourerrordocumentstoyourpersonaltaste(oryourcompany'sconventions).Fordemonstrationpurposes,wepresentasimplegenericerrordocumentscheme.Forthishypotheticserver,weassumethatallerrormessages...

possiblyareservedbydifferentvirtualhosts(differenthostname,differentIPaddress,ordifferentport)ontheservermachine,showapredefinedcompanylogointherighttopofthemessage(selectablebyvirtualhost),printtheerrortitlefirst,followedbyanexplanatorytextand(dependingontheerrorcontext)helponhowtoresolvetheerror,havesomekindofstandardizedbackgroundimage,displayanapachelogoandafeedbackemailaddressatthebottomoftheerrormessage.

Anexampleofa"documentnotfound"messageforagermanclientmightlooklikethis:

Alllinksinthedocumentaswellaslinkstotheserver'sadministratormailaddress,andeventhenameandportoftheservingvirtualhostareinsertedintheerrordocumentat"run-time",i.e.,whentheerroractuallyoccurs.

CreatinganErrorDocumentdirectory

Forthisconcepttoworkaseasilyaspossible,wemusttakeadvantageofasmuchserversupportaswecanget:

1. BydefiningtheMultiViewsOptions,weenablethelanguageselectionofthemostappropriatelanguagealternative(contentnegotiation).

2. BysettingtheLanguagePrioritydirectivewedefineasetofdefaultfallbacklanguagesinthesituationwheretheclient'sbrowserdidnotexpressanypreferenceatall.

3. Byenablingmod_include(anddisallowingexecutionofcgiscriptsforsecurityreasons),weallowtheservertoincludebuildingblocksoftheerrormessage,andtosubstitutethevalueofcertainenvironmentvariablesintothegenerateddocument(dynamicHTML)oreventoconditionallyincludeoromitpartsofthetext.

4. TheAddHandlerandAddTypedirectivesareusefulforautomaticallySSI-expandingallfileswitha.shtmlsuffixtotext/html.

5. ByusingtheAliasdirective,wekeeptheerrordocumentdirectoryoutsideofthedocumenttreebecauseitcanberegardedmoreasaserverpartthanpartofthedocumenttree.

6. The<Directory>blockrestrictsthese"special"settingstotheerrordocumentdirectoryandavoidsanimpactonanyofthesettingsfortheregulardocumenttree.

7. Foreachoftheerrorcodestobehandled(seeRFC2068foranexactdescriptionofeacherrorcode,orlookatsrc/main/http_protocol.cifyouwishtoseeapache'sstandardmessages),anErrorDocumentinthealiased/errordocsdirectoryisdefined.Notethatweonlydefine

thebasenameofthedocumentherebecausetheMultiViewsoptionwillselectthebestcandidatebasedonthelanguagesuffixesandtheclient'spreferences.Anyerrorsituationwithanerrorcodenothandledbyacustomdocumentwillbedealtwithbytheserverinthestandardway(i.e.,aplainerrormessageinenglish).

8. Finally,theAllowOverridedirectivetellsapachethatitisnotnecessarytolookfora.htaccessfileinthe/errordocsdirectory:aminorspeedoptimization.

Theresultinghttpd.confconfigurationwouldthenlooksimilartothis:

NoteNotethatyoucandefineyourownerrormessagesusingthismethodforonlypartofthedocumenttree,e.g.,a/~user/subtree.Inthiscase,theconfigurationcouldaswellbeputintothe.htaccessfileattherootofthesubtree,andthe<Directory>and</Directory>directives-butnotthecontaineddirectives-mustbeomitted.

LanguagePriorityenfrde

Alias/errordocs/usr/local/apache/errordocs

AllowOverridenone

OptionsMultiViewsIncludesNoExecFollowSymLinks

<FilesMatch"\.shtml[.$]">

SetOutputFilterINCLUDES

</FilesMatch>

</Directory>

#"400BadRequest",

ErrorDocument400/errordocs/400

#"401AuthorizationRequired",

#"403Forbidden",

#"404NotFound",

#"500InternalServerError",

Thedirectoryfortheerrormessages(here:/usr/local/apache/errordocs/)mustthenbecreatedwiththeappropriatepermissions(readableandexecutablebytheserveruidorgid,onlywritablefortheadministrator).

NamingtheIndividualErrorDocumentfilesBydefiningtheMultiViewsoption,theserverwastoldtoautomaticallyscanthedirectoryformatchingvariants(lookingatlanguageandcontenttypesuffixes)whenarequesteddocumentwasnotfound.Intheconfiguration,wedefinedthenamesfortheerrordocumentstobejusttheirerrornumber(withoutanysuffix).

Thenamesoftheindividualerrordocumentsarenowdeterminedlikethis(I'musing403asanexample,thinkofitasaplaceholderforanyoftheconfigurederrordocuments):

Nofileerrordocs/403shouldexist.Otherwise,itwouldbefoundandserved(withtheDefaultType,usuallytext/plain),allnegotiationwouldbebypassed.Foreachlanguageforwhichwehaveaninternationalizedversion(notethatthisneednotbethesamesetoflanguagesforeacherrorcode-youcangetbywithasinglelanguageversionuntilyouactuallyhavetranslatedversions),adocumenterrordocs/403.shtml.langiscreatedandfilledwiththeerrortextinthatlanguage(seebelow).Onefallbackdocumentcallederrordocs/403.shtmliscreated,usuallybycreatingasymlinktothedefaultlanguagevariant(seebelow).

TheCommonHeaderandFooterFiles

Byputtingasmuchlayoutinformationintwospecial"includefiles",theerrordocumentscanbereducedtoabareminimum.

OneoftheselayoutfilesdefinestheHTMLdocumentheaderandaconfigurablelistofpathstotheiconstobeshownintheresultingerrordocument.ThesepathsareexportedasasetofSSIenvironmentvariablesandarelaterevaluatedbythe"footer"specialfile.Thetitleofthecurrenterror(whichisputintotheTITLEtagandanH1header)issimplypassedinfromthemainerrordocumentinavariablecalledtitle.

Bychangingthisfile,thelayoutofallgeneratederrormessagescanbechangedinasecond.(ByexploitingthefeaturesofSSI,youcaneasilydefinedifferentlayoutsbasedonthecurrentvirtualhost,orevenbasedontheclient'sdomainname).

Thesecondlayoutfiledescribesthefootertobedisplayedatthebottomofeveryerrormessage.Inthisexample,itshowsanapachelogo,thecurrentservertime,theserverversionstringandaddsamailreferencetothesite'swebmaster.

Forsimplicity,theheaderfileissimplycalledhead.shtmlbecauseitcontainsserver-parsedcontentbutnolanguagespecificinformation.Thefooterfileexistsonceforeachlanguagetranslation,plusasymlinkforthedefaultlanguage.

forEnglish,FrenchandGermanversions(defaultenglish)

foot.shtml.en,

foot.shtml.fr,

foot.shtml.de,

foot.shtmlsymlinkto

foot.shtml.en

Bothfilesareincludedintotheerrordocumentbyusingthedirectivesand<!--

#includevirtual="foot"-->respectively:therestofthemagicoccursinmod_negotiationandinmod_include.

SeethelistingsbelowtoseeanactualHTMLimplementationofthediscussedexample.

CreatingErrorDocumentsinDifferentLanguagesAfterallthispreparationwork,littleremainstobesaidabouttheactualdocuments.Theyallshareasimplecommonstructure:

explanatoryerrortext

Inthelistingssection,youcanseeanexampleofa[400BadRequest]errordocument.Documentsassimpleasthatcertainlycausenoproblemstotranslateorexpand.

TheFallbackLanguageDoweneedaspecialhandlingforlanguagesotherthanthosewehavetranslationsfor?WedidsettheLanguagePriority,didn'twe?!

Well,theLanguagePrioritydirectiveisforthecasewheretheclientdoesnotexpressanylanguagepriorityatall.Butwhathappensinthesituationwheretheclientwantsoneofthelanguageswedonothave,andnoneofthosewedohave?

Withoutdoinganything,theApacheserverwillusuallyreturna[406noacceptablevariant]error,listingthechoicesfromwhichtheclientmayselect.Butwe'reinanerrormessagealready,andimportanterrorinformationmightgetlostwhentheclienthadtochoosealanguagerepresentationfirst.

So,inthissituationitappearstobeeasiertodefineafallback

language(bycopyingorlinking,e.g.,theenglishversiontoalanguage-lessversion).Becausethenegotiationalgorithmprefers"morespecialized"variantsover"moregeneric"variants,thesegenericalternativeswillonlybechosenwhenthenormalnegotiationdidnotsucceed.

Asimpleshellscripttodoit(executewithintheerrordocs/dir):

forfin*.shtml.en

ln-s$f`basename$f.en`

CustomizingProxyErrorMessages

AsofApache-1.3,itispossibletousetheErrorDocumentmechanismforproxyerrormessagesaswell(previousversionsalwaysreturnedfixedpredefinederrormessages).

Mostproxyerrorsreturnanerrorcodeof[500InternalServerError].Tofindoutwhetheraparticularerrordocumentwasinvokedonbehalfofaproxyerrororbecauseofsomeotherservererror,andwhatthereasonforthefailurewas,youcancheckthecontentsofthenewERROR_NOTESCGIenvironmentvariable:ifinvokedforaproxyerror,thisvariablewillcontaintheactualproxyerrormessagetextinHTMLform.

ThefollowingexcerptdemonstrateshowtoexploittheERROR_NOTESvariablewithinanerrordocument:

Theserverencounteredanunexpectedcondition

whichpreventeditfromfulfillingtherequest.

<ahref="mailto:"

SUBJECT="Errormessage[]

for<!--#echovar="REQUEST_URI"--

Pleaseforwardthiserrorscreento<!--#echo

var="SERVER_NAME"-->'s

WebMaster</a>;itincludesusefuldebugginginformation

theRequestwhichcausedtheerror.

HTMLListingoftheDiscussedExample

So,tosummarizeourexample,here'sthecompletelistingofthe400.shtml.endocument.Youwillnoticethatitcontainsalmostnothingbuttheerrortext(withconditionaladditions).Startingwiththisexample,youwillfinditeasytoaddmoreerrordocuments,ortotranslatetheerrordocumentstodifferentlanguages.

Yourbrowsersentarequestthatthisservercouldnot

understand:

</blockquote>

Therequestcouldnotbeunderstoodbytheserverdueto

malformed

syntax.Theclientshouldnotrepeattherequestwithout

modifications.

Pleaseinformtheownerof

<ahref="">thereferring

page</a>about

themalformedlink.

Pleasecheckyourrequestfortypingerrorsandretry.

Hereisthecompletehead.shtml.enfile(thefunnylinebreaksavoidemptylinesinthedocumentafterSSIprocessing).Notetheconfigurationsectionattop.That'swhereyouconfiguretheimagesandlogosaswellastheapachedocumentationdirectory.Lookhowthisfiledisplaystwodifferentlogosdependingonthe

contentofthevirtualhostname($SERVER_NAME),andthatananimatedapachelogoisshownifthebrowserappearstosupportit(thelatterrequiresserverconfigurationlinesoftheform

BrowserMatch"^Mozilla/[2-4]"anigif

forbrowsertypeswhichsupportanimatedGIFs).

<!--#setvar="IMG_CorpLogo"

value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif"

<!--#setvar="IMG_CorpLogo"

value="http://$SERVER_NAME:$SERVER_PORT/errordocs/PrivLogo.gif"

<!--#setvar="IMG_BgImage"

value="http://$SERVER_NAME:$SERVER_PORT/errordocs/BgImage.gif"

<!--#setvar="DOC_Apache"

value="http://$SERVER_NAME:$SERVER_PORT/Apache/"-->

<!--#setvar="IMG_Apache"

value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_anim.gif"

<!--#setvar="IMG_Apache"

value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_pb.gif"

<!DOCTYPEHTMLPUBLIC"-//IETF//DTDHTML//EN">

<html>

<head>

<title>

[]<!--#echovar="title"

</title>

</head>

<bodybgcolor="white"background="<!--#echovar="IMG_BgImage"-

<h1align="center">

[]<!--#echovar="title"

<imgsrc=""

alt=""align="right">

<hr/><!--

========================================================-->

andthisisthefoot.shtml.enfile:

</div>

<divalign="right">

<small>LocalServertime:

</small>

</div>

<divalign="center">

<ahref="">

<imgsrc=""border="0"

align="bottom"

alt="Poweredby">

<small><!--#setvar="var"value="Poweredby

$SERVER_SOFTWARE--

Filelastmodifiedon$LAST_MODIFIED"-->

</small>

</div>

<p>Iftheindicatederrorlookslikeamisconfiguration,

pleaseinform

<ahref="mailto:"

subject="FeedbackaboutErrormessage[<!--#echo

var="REDIRECT_STATUS"-->]

,req=<!--#echovar="REQUEST_URI"-

'sWebMaster</a>.

</body>

</html>

Ifyouhavetipstocontribute,sendmailtomartin@apache.org

ConnectionsintheFIN_WAIT_2stateandApache

Warning:

StartingwiththeApache1.2betas,peoplearereportingmanymoreconnectionsintheFIN_WAIT_2state(asreportedbynetstat)thantheysawusingolderversions.WhentheserverclosesaTCPconnection,itsendsapacketwiththeFINbitsettotheclient,whichthenrespondswithapacketwiththeACKbitset.TheclientthensendsapacketwiththeFINbitsettotheserver,whichrespondswithanACKandtheconnectionisclosed.ThestatethattheconnectionisinduringtheperiodbetweenwhentheservergetstheACKfromtheclientandtheservergetstheFINfromtheclientisknownasFIN_WAIT_2.SeetheTCPRFCforthetechnicaldetailsofthestatetransitions.

TheFIN_WAIT_2stateissomewhatunusualinthatthereisnotimeoutdefinedinthestandardforit.Thismeansthatonmanyoperatingsystems,aconnectionintheFIN_WAIT_2statewillstayarounduntilthesystemisrebooted.IfthesystemdoesnothaveatimeoutandtoomanyFIN_WAIT_2connectionsbuildup,itcanfillupthespaceallocatedforstoringinformationabouttheconnectionsandcrashthekernel.TheconnectionsinFIN_WAIT_2donottieupanhttpdprocess.

WhyDoesItHappen?

Therearenumerousreasonsforithappening,someofthemmaynotyetbefullyclear.Whatisknownfollows.

BuggyClientsandPersistentConnectionsSeveralclientshaveabugwhichpopsupwhendealingwithpersistentconnections(akakeepalives).Whentheconnectionisidleandtheserverclosestheconnection(basedontheKeepAliveTimeout),theclientisprogrammedsothattheclientdoesnotsendbackaFINandACKtotheserver.ThismeansthattheconnectionstaysintheFIN_WAIT_2stateuntiloneofthefollowinghappens:

Theclientopensanewconnectiontothesameoradifferentsite,whichcausesittofullyclosetheolderconnectiononthatsocket.Theuserexitstheclient,whichonsome(most?)clientscausestheOStofullyshutdowntheconnection.TheFIN_WAIT_2timesout,onserversthathaveatimeoutforthisstate.

Ifyouarelucky,thismeansthatthebuggyclientwillfullyclosetheconnectionandreleasetheresourcesonyourserver.However,therearesomecaseswherethesocketisneverfullyclosed,suchasadialupclientdisconnectingfromtheirproviderbeforeclosingtheclient.Inaddition,aclientmightsitidlefordayswithoutmakinganotherconnection,andthusmayholditsendofthesocketopenfordayseventhoughithasnofurtheruseforit.Thisisabuginthebrowserorinitsoperatingsystem'sTCPimplementation.

Theclientsonwhichthisproblemhasbeenverifiedtoexist:

Mozilla/3.01(X11;I;FreeBSD2.1.5-RELEASEi386)Mozilla/2.02(X11;I;FreeBSD2.1.5-RELEASEi386)Mozilla/3.01Gold(X11;I;SunOS5.5sun4m)

MSIE3.01ontheMacintoshMSIE3.01onWindows95

Thisdoesnotappeartobeaproblemon:

Mozilla/3.01(Win95;I)

Itisexpectedthatmanyotherclientshavethesameproblem.Whataclientshoulddoisperiodicallycheckitsopensocket(s)toseeiftheyhavebeenclosedbytheserver,andclosetheirsideoftheconnectioniftheserverhasclosed.Thischeckneedonlyoccuronceeveryfewseconds,andmayevenbedetectedbyaOSsignalonsomesystems(e.g.,Win95andNTclientshavethiscapability,buttheyseemtobeignoringit).

ApachecannotavoidtheseFIN_WAIT_2statesunlessitdisablespersistentconnectionsforthebuggyclients,justlikewerecommenddoingforNavigator2.xclientsduetootherbugs.However,non-persistentconnectionsincreasethetotalnumberofconnectionsneededperclientandslowretrievalofanimage-ladenwebpage.Sincenon-persistentconnectionshavetheirownresourceconsumptionsandashortwaitingperiodaftereachclosure,abusyservermayneedpersistenceinordertobestserveitsclients.

Asfarasweknow,theclient-causedFIN_WAIT_2problemispresentforallserversthatsupportpersistentconnections,includingApache1.1.xand1.2.

Anecessarybitofcodeintroducedin1.2Whiletheabovebugisaproblem,itisnotthewholeproblem.SomeusershaveobservednoFIN_WAIT_2problemswithApache1.1.x,butwith1.2benoughconnectionsbuildupintheFIN_WAIT_2statetocrashtheirserver.ThemostlikelysourceforadditionalFIN_WAIT_2statesisafunctioncalled

lingering_close()whichwasaddedbetween1.1and1.2.Thisfunctionisnecessaryfortheproperhandlingofpersistentconnectionsandanyrequestwhichincludescontentinthemessagebody(e.g.,PUTsandPOSTs).Whatitdoesisreadanydatasentbytheclientforacertaintimeaftertheserverclosestheconnection.Theexactreasonsfordoingthisaresomewhatcomplicated,butinvolvewhathappensiftheclientismakingarequestatthesametimetheserversendsaresponseandclosestheconnection.Withoutlingering,theclientmightbeforcedtoresetitsTCPinputbufferbeforeithasachancetoreadtheserver'sresponse,andthusunderstandwhytheconnectionhasclosed.Seetheappendixformoredetails.

Thecodeinlingering_close()appearstocauseproblemsforanumberoffactors,includingthechangeintrafficpatternsthatitcauses.Thecodehasbeenthoroughlyreviewedandwearenotawareofanybugsinit.ItispossiblethatthereissomeproblemintheBSDTCPstack,asidefromthelackofatimeoutfortheFIN_WAIT_2state,exposedbythelingering_closecodethatcausestheobservedproblems.

WhatCanIDoAboutit?

Thereareseveralpossibleworkaroundstotheproblem,someofwhichworkbetterthanothers.

AddatimeoutforFIN_WAIT_2TheobviousworkaroundistosimplyhaveatimeoutfortheFIN_WAIT_2state.ThisisnotspecifiedbytheRFC,andcouldbeclaimedtobeaviolationoftheRFC,butitiswidelyrecognizedasbeingnecessary.Thefollowingsystemsareknowntohaveatimeout:

FreeBSDversionsstartingat2.0orpossiblyearlier.NetBSDversion1.2(?)OpenBSDallversions(?)BSD/OS2.1,withtheK210-027patchinstalled.Solarisasofaroundversion2.2.Thetimeoutcanbetunedbyusingnddtomodifytcp_fin_wait_2_flush_interval,butthedefaultshouldbeappropriateformostserversandimpropertuningcanhavenegativeimpacts.Linux2.0.xandearlier(?)HP-UX10.xdefaultstoterminatingconnectionsintheFIN_WAIT_2stateafterthenormalkeepalivetimeouts.ThisdoesnotrefertothepersistentconnectionorHTTPkeepalivetimeouts,buttheSO_LINGERsocketoptionwhichisenabledbyApache.Thisparametercanbeadjustedbyusingnettunetomodifyparameterssuchastcp_keepstartandtcp_keepstop.Inlaterrevisions,thereisanexplicittimerforconnectionsinFIN_WAIT_2thatcanbemodified;contactHPsupportfordetails.SGIIRIXcanbepatchedtosupportatimeout.ForIRIX5.3,6.2,and6.3,usepatches1654,1703and1778respectively.Ifyouhavetroublelocatingthesepatches,pleasecontactyourSGIsupportchannelforhelp.NCR'sMPRASUnix2.xxand3.xxbothhaveFIN_WAIT_2

timeouts.In2.xxitisnon-tunableat600seconds,whilein3.xxitdefaultsto600secondsandiscalculatedbasedonthetunable"maxkeepaliveprobes"(defaultof8)multipliedbythe"keepaliveinterval"(default75seconds).Sequent'sptx/TCP/IPforDYNIX/ptxhashadaFIN_WAIT_2timeoutsincearoundrelease4.1inmid-1994.

Thefollowingsystemsareknowntonothaveatimeout:

SunOS4.xdoesnotandalmostcertainlyneverwillhaveonebecauseitasattheveryendofitsdevelopmentcycleforSun.Ifyouhavekernelsourceshouldbeeasytopatch.

ThereisapatchavailableforaddingatimeouttotheFIN_WAIT_2state;itwasoriginallyintendedforBSD/OS,butshouldbeadaptabletomostsystemsusingBSDnetworkingcode.Youneedkernelsourcecodetobeabletouseit.

Compilewithoutusinglingering_close()ItispossibletocompileApache1.2withoutusingthelingering_close()function.Thiswillresultinthatsectionofcodebeingsimilartothatwhichwasin1.1.Ifyoudothis,beawarethatitcancauseproblemswithPUTs,POSTsandpersistentconnections,especiallyiftheclientusespipelining.Thatsaid,itisnoworsethanon1.1,andweunderstandthatkeepingyourserverrunningisquiteimportant.

Tocompilewithoutthelingering_close()function,add-DNO_LINGCLOSEtotheendoftheEXTRA_CFLAGSlineinyourConfigurationfile,rerunConfigureandrebuildtheserver.

UseSO_LINGERasanalternativetolingering_close()

Onmostsystems,thereisanoptioncalledSO_LINGERthatcanbesetwithsetsockopt(2).Itdoessomethingverysimilartolingering_close(),exceptthatitisbrokenonmanysystemssothatitcausesfarmoreproblemsthanlingering_close.Onsomesystems,itcouldpossiblyworkbettersoitmaybeworthatryifyouhavenootheralternatives.

Totryit,add-DUSE_SO_LINGER-DNO_LINGCLOSEtotheendoftheEXTRA_CFLAGSlineinyourConfigurationfile,rerunConfigureandrebuildtheserver.

NOTEAttemptingtouseSO_LINGERandlingering_close()atthesametimeisverylikelytodoverybadthings,sodon't.

IncreasetheamountofmemoryusedforstoringconnectionstateBSDbasednetworkingcode:

BSDstoresnetworkdata,suchasconnectionstates,insomethingcalledanmbuf.Whenyougetsomanyconnectionsthatthekerneldoesnothaveenoughmbufstoputthemallin,yourkernelwilllikelycrash.Youcanreducetheeffectsoftheproblembyincreasingthenumberofmbufsthatareavailable;thiswillnotpreventtheproblem,itwilljustmaketheservergolongerbeforecrashing.TheexactwaytoincreasethemmaydependonyourOS;lookforsomereferencetothenumberof"mbufs"or"mbufclusters".Onmanysystems,thiscanbedonebyaddingthelineNMBCLUSTERS="n",wherenisthenumberofmbufclustersyouwanttoyourkernelconfigfileandrebuildingyourkernel.

DisableKeepAliveIfyouareunabletodoanyoftheabovethenyoushould,asalastresort,disableKeepAlive.Edityourhttpd.confandchange"KeepAliveOn"to"KeepAliveOff".

Appendix

BelowisamessagefromRoyFielding,oneoftheauthorsofHTTP/1.1.

WhythelingeringclosefunctionalityisnecessarywithHTTPTheneedforaservertolingeronasocketafteracloseisnotedacoupletimesintheHTTPspecs,butnotexplained.Thisexplanationisbasedondiscussionsbetweenmyself,HenrikFrystyk,RobertS.Thau,DaveRaggett,andJohnC.MalleryinthehallwaysofMITwhileIwasatW3C.

Ifaserverclosestheinputsideoftheconnectionwhiletheclientissendingdata(orisplanningtosenddata),thentheserver'sTCPstackwillsignalanRST(reset)backtotheclient.UponreceiptoftheRST,theclientwillflushitsownincomingTCPbufferbacktotheun-ACKedpacketindicatedbytheRSTpacketargument.Iftheserverhassentamessage,usuallyanerrorresponse,totheclientjustbeforetheclose,andtheclientreceivestheRSTpacketbeforeitsapplicationcodehasreadtheerrormessagefromitsincomingTCPbufferandbeforetheserverhasreceivedtheACKsentbytheclientuponreceiptofthatbuffer,thentheRSTwillflushtheerrormessagebeforetheclientapplicationhasachancetoseeit.Theresultisthattheclientisleftthinkingthattheconnectionfailedfornoapparentreason.

Therearetwoconditionsunderwhichthisislikelytooccur:

1. sendingPOSTorPUTdatawithoutproperauthorization

2. sendingmultiplerequestsbeforeeachresponse(pipelining)andoneofthemiddlerequestsresultinginanerrororotherbreak-the-connectionresult.

Thesolutioninallcasesistosendtheresponse,closeonlythe

writehalfoftheconnection(whatshutdownissupposedtodo),andcontinuereadingonthesocketuntilitiseitherclosedbytheclient(signifyingithasfinallyreadtheresponse)oratimeoutoccurs.ThatiswhatthekernelissupposedtodoifSO_LINGERisset.Unfortunately,SO_LINGERhasnoeffectonsomesystems;onsomeothersystems,itdoesnothaveitsowntimeoutandthustheTCPmemorysegmentsjustpile-upuntilthenextreboot(plannedornot).

Pleasenotethatsimplyremovingthelingercodewillnotsolvetheproblem--itonlymovesittoadifferentandmuchharderonetodetect.

KnownProblemsinClients

Warning:

OvertimetheApacheGrouphasdiscoveredorbeennotifiedofproblemswithvariousclientswhichwehavehadtoworkaround,orexplain.Thisdocumentdescribestheseproblemsandtheworkaroundsavailable.It'snotarrangedinanyparticularorder.Somefamiliaritywiththestandardsisassumed,butnotnecessary.

Forbrevity,NavigatorwillrefertoNetscape'sNavigatorproduct(whichinlaterversionswasrenamed"Communicator"andvariousothernames),andMSIEwillrefertoMicrosoft'sInternetExplorerproduct.Alltrademarksandcopyrightsbelongtotheirrespectivecompanies.Wewelcomeinputfromthevariousclientauthorstocorrectinconsistenciesinthispaper,ortoprovideuswithexactversionnumberswherethingsarebroken/fixed.

Forreference,RFC1945definesHTTP/1.0,andRFC2068definesHTTP/1.1.Apacheasofversion1.2isanHTTP/1.1server(withanoptionalHTTP/1.0proxy).

Variousoftheseworkaroundsaretriggeredbyenvironmentvariables.Theadmintypicallycontrolswhichareset,andforwhichclients,byusingmod_browser.Unlessotherwisenotedalloftheseworkaroundsexistinversions1.2andlater.

TrailingCRLFonPOSTs

Thisisalegacyissue.TheCERNwebserverrequiredPOSTdatatohaveanextraCRLFfollowingit.ThusmanyclientssendanextraCRLFthatisnotincludedintheContent-Lengthoftherequest.Apacheworksaroundthisproblembyeatinganyemptylineswhichappearbeforearequest.

BrokenKeepAlive

Variousclientshavehadbrokenimplementationsofkeepalive(persistentconnections).InparticulartheWindowsversionsofNavigator2.0getveryconfusedwhentheservertimesoutanidleconnection.Theworkaroundispresentinthedefaultconfigfiles:

BrowserMatchMozilla/2nokeepalive

NotethatthismatchessomeearlierversionsofMSIE,whichbeganthepracticeofcallingthemselvesMozillaintheiruser-agentstringsjustlikeNavigator.

MSIE4.0b2,whichclaimstosupportHTTP/1.1,doesnotproperlysupportkeepalivewhenitisusedon301or302(redirect)responses.UnfortunatelyApache'snokeepalivecodepriorto1.2.2wouldnotworkwithHTTP/1.1clients.Youmustapplythispatchtoversion1.2.1.Thenaddthistoyourconfig:

BrowserMatch"MSIE4\.0b2;"nokeepalive

IncorrectinterpretationofHTTP/1.1inresponse

Toquotefromsection3.1ofRFC1945:

HTTPusesa"<MAJOR>.<MINOR>"numberingschemetoindicateversionsoftheprotocol.TheprotocolversioningpolicyisintendedtoallowthesendertoindicatetheformatofamessageanditscapacityforunderstandingfurtherHTTPcommunication,ratherthanthefeaturesobtainedviathatcommunication.

SinceApacheisanHTTP/1.1server,itindicatessoaspartofitsresponse.Manyclientauthorsmistakenlytreatthispartoftheresponseasanindicationoftheprotocolthattheresponseisin,andthenrefusetoaccepttheresponse.

ThefirstmajorindicationofthisproblemwaswithAOL'sproxyservers.WhenApache1.2wentintobetaitwasthefirstwide-spreadHTTP/1.1server.Aftersomediscussion,AOLfixedtheirproxies.Inanticipationofsimilarproblems,theforce-response-1.0environmentvariablewasaddedtoApache.WhenpresentApachewillindicate"HTTP/1.0"inresponsetoanHTTP/1.0client,butwillnotinanyotherwaychangetheresponse.

Thepre-1.1JavaDevelopmentKit(JDK)thatisusedinmanyclients(includingNavigator3.xandMSIE3.x)exhibitsthisproblem.Asdosomeoftheearlypre-releasesofthe1.1JDK.Wethinkitisfixedinthe1.1JDKrelease.Inanyeventtheworkaround:

BrowserMatchJava/1.0force-response-1.0

BrowserMatchJDK/1.0force-response-1.0

RealPlayer4.0fromProgressiveNetworksalsoexhibitsthisproblem.Howevertheyhavefixeditinversion4.01oftheplayer,

butversion4.01usesthesameUser-Agentasversion4.0.Theworkaroundisstill:

BrowserMatch"RealPlayer4.0"force-response-1.0

RequestsuseHTTP/1.1butresponsesmustbeinHTTP/1.0

MSIE4.0b2hasthisproblem.ItsJavaVMmakesrequestsinHTTP/1.1formatbuttheresponsesmustbeinHTTP/1.0format(inparticular,itdoesnotunderstandchunkedresponses).TheworkaroundistofoolApacheintobelievingtherequestcameinHTTP/1.0format.

BrowserMatch"MSIE4\.0b2;"downgrade-1.0force-response-1.0

Thisworkaroundisavailablein1.2.2,andinapatchagainst1.2.1.

Boundaryproblemswithheaderparsing

AllversionsofNavigatorfrom2.0through4.0b2(andpossiblylater)haveaproblemifthetrailingCRLFoftheresponseheaderstartsatoffset256,257or258oftheresponse.ABrowserMatchforthiswouldmatchonnearlyeveryhit,sotheworkaroundisenabledautomaticallyonallresponses.TheworkaroundimplementeddetectswhenthisconditionwouldoccurinaresponseandaddsextrapaddingtotheheadertopushthetrailingCRLFpastoffset258oftheresponse.

MultipartresponsesandQuotedBoundaryStrings

Onmultipartresponsessomeclientswillnotacceptquotes(")aroundtheboundarystring.TheMIMEstandardrecommendsthatsuchquotesbeused.ButtheclientswereprobablywrittenbasedononeoftheexamplesinRFC2068,whichdoesnotincludequotes.Apachedoesnotincludequotesonitsboundarystringstoworkaroundthisproblem.

ByterangeRequests

Abyterangerequestisusedwhentheclientwishestoretrieveaportionofanobject,notnecessarilytheentireobject.TherewasaveryolddraftwhichincludedthesebyterangesintheURL.OldclientssuchasNavigator2.0b1andMSIE3.0fortheMACexhibitthisbehaviour,anditwillappearintheservers'accesslogsas(failed)attemptstoretrieveaURLwithatrailing";xxx-yyy".Apachedoesnotattempttoimplementthisatall.

AsubsequentdraftofthisstandarddefinesaheaderRequest-Range,andaresponsetypemultipart/x-byteranges.TheHTTP/1.1standardincludesthisdraftwithafewfixes,anditdefinestheheaderRangeandtypemultipart/byteranges.

Navigator(versions2and3)sendsbothRangeandRequest-Rangeheaders(withthesamevalue),butdoesnotacceptamultipart/byterangesresponse.Theresponsemustbemultipart/x-byteranges.Asaworkaround,ifApachereceivesaRequest-Rangeheaderitconsidersit"higherpriority"thanaRangeheaderandinresponseusesmultipart/x-byteranges.

TheAdobeAcrobatReaderpluginmakesextensiveuseofbyterangesandpriortoversion3.01supportsonlythemultipart/x-byterangeresponse.Unfortunatelythereisnocluethatitisthepluginmakingtherequest.IfthepluginisusedwithNavigator,theaboveworkaroundworksfine.ButifthepluginisusedwithMSIE3(onWindows)theworkaroundwon'tworkbecauseMSIE3doesn'tgivetheRange-RequestcluethatNavigatordoes.Toworkaroundthis,Apachespecialcases"MSIE3"intheUser-Agentandservesmultipart/x-byteranges.NotethatthenecessityforthiswithMSIE3isactuallyduetotheAcrobatplugin,notduetothebrowser.

NetscapeCommunicatorappearstonotissuethenon-standardRequest-Rangeheader.WhenanAcrobatpluginpriortoversion3.01isusedwithit,itwillnotproperlyunderstandbyteranges.TheusermustupgradetheirAcrobatreaderto3.01.

Set-Cookieheaderisunmergeable

TheHTTPspecificationssaythatitislegaltomergeheaderswithduplicatenamesintoone(separatedbycommas).SomebrowsersthatsupportCookiesdon'tlikemergedheadersandpreferthateachSet-Cookieheaderissentseparately.WhenparsingtheheadersreturnedbyaCGI,ApachewillexplicitlyavoidmerginganySet-Cookieheaders.

ExpiresheadersandGIF89Aanimations

Navigatorversions2through4willerroneouslyre-requestGIF89AanimationsoneachloopoftheanimationifthefirstresponseincludedanExpiresheader.Thishappensregardlessofhowfarinthefuturetheexpirytimeisset.ThereisnoworkaroundsuppliedwithApache,howevertherearehacksfor1.2andfor1.3.

POSTwithoutContent-Length

IncertainsituationsNavigator3.01through3.03appeartoincorrectlyissueaPOSTwithouttherequestbody.Thereisnoknownworkaround.IthasbeenfixedinNavigator3.04,Netscapesprovidessomeinformation.There'salsosomeinformationabouttheactualproblem.

JDK1.2betaslosepartsofresponses.

ThehttpclientintheJDK1.2beta2andbeta3willthrowawaythefirstpartoftheresponsebodywhenboththeheadersandthefirstpartofthebodyaresentinthesamenetworkpacketANDkeep-alive'sarebeingused.Ifeitherconditionisnotmetthenitworksfine.

SeealsoBug-ID's4124329and4125538atthejavadeveloperconnection.

Ifyouareseeingthisbugyourself,youcanaddthefollowingBrowserMatchdirectivetoworkaroundit:

BrowserMatch"Java1\.2beta[23]"nokeepalive

Wedon'tadvocatethisthoughsincebendingoverbackwardsforbetasoftwareisusuallynotagoodidea;ideallyitgetsfixed,newbetasorafinalreleasecomesout,andnooneusesthebrokenoldsoftwareanymore.Intheory.

Content-Typechangeisnotnoticedafterreload

Navigator(allversions?)willcachethecontent-typeforanobject"forever".Usingreloadorshift-reloadwillnotcauseNavigatortonoticeacontent-typechange.Theonlywork-aroundisfortheusertoflushtheircaches(memoryanddisk).Bywayofanexample,somefolksmaybeusinganoldmime.typesfilewhichdoesnotmap.htmtotext/html,inthiscaseApachewilldefaulttosendingtext/plain.Iftheuserrequeststhepageanditisservedastext/plain.Aftertheadminfixestheserver,theuserwillhavetoflushtheircachesbeforetheobjectwillbeshownwiththecorrecttext/htmltype.

MSIECookieproblemwithexpirydateintheyear2000

MSIEversions3.00and3.02(withouttheY2Kpatch)donothandlecookieexpirydatesintheyear2000properly.Yearsafter2000andbefore2000workfine.ThisisfixedinIE4.01servicepack1,andintheY2KpatchforIE3.02.Usersshouldavoidusingexpirydatesintheyear2000.

Lynxincorrectlyaskingfortransparentcontentnegotiation

TheLynxbrowserversions2.7and2.8senda"negotiate:trans"headerintheirrequests,whichisanindicationthebrowsersupportstransparentcontentnegotiation(TCN).HoweverthebrowserdoesnotsupportTCN.Asofversion1.3.4,ApachesupportsTCN,andthiscausesproblemswiththeseversionsofLynx.AsaworkaroundfutureversionsofApachewillignorethisheaderwhensentbytheLynxclient.

MSIE4.0mishandlesVaryresponseheader

MSIE4.0doesnothandleaVaryheaderproperly.TheVaryheaderisgeneratedbymod_rewriteinapache1.3.TheresultisanerrorfromMSIEsayingitcannotdownloadtherequestedfile.TherearemoredetailsinPR#4118.

Aworkaroundistoaddthefollowingtoyourserver'sconfigurationfiles:

BrowserMatch"MSIE4\.0"force-no-vary

(Thisworkaroundisonlyavailablewithreleasesafter1.3.6oftheApacheWebserver.)

DescriptorsandApache

Warning:

Adescriptor,alsocommonlycalledafilehandleisanobjectthataprogramusestoreadorwriteanopenfile,oropennetworksocket,oravarietyofotherdevices.Itisrepresentedbyaninteger,andyoumaybefamiliarwithstdin,stdout,andstderrwhicharedescriptors0,1,and2respectively.Apacheneedsadescriptorforeachlogfile,plusoneforeachnetworksocketthatitlistenson,plusahandfulofothers.LibrariesthatApacheusesmayalsorequiredescriptors.Normalprogramsdon'topenupmanydescriptorsatall,andsotherearesomelatentproblemsthatyoumayexperienceshouldyoustartrunningApachewithmanydescriptors(i.e.,withmanyvirtualhosts).

Theoperatingsystemenforcesalimitonthenumberofdescriptorsthataprogramcanhaveopenatatime.Therearetypicallythreelimitsinvolvedhere.Oneisakernellimitation,dependingonyouroperatingsystemyouwilleitherbeabletotunethenumberofdescriptorsavailabletohighernumbers(thisisfrequentlycalledFD_SETSIZE).Oryoumaybestuckwitha(relatively)lowamount.Thesecondlimitiscalledthehardresourcelimit,anditissometimessetbyrootinanobscureoperatingsystemfile,butfrequentlyisthesameasthekernellimit.Thethirdlimitiscalledthesoftresourcelimit.Thesoftlimitisalwayslessthanorequaltothehardlimit.Forexample,thehardlimitmaybe1024,butthesoftlimitonly64.Anyusercanraisetheirsoftlimituptothehardlimit.Rootcanraisethehardlimituptothesystemmaximumlimit.Thesoftlimitistheactual

limitthatisusedwhenenforcingthemaximumnumberoffilesaprocesscanhaveopen.

Tosummarize:

#openfiles<=softlimit<=hardlimit<=kernellimit

Youcontrolthehardandsoftlimitsusingthelimit(csh)orulimit(sh)directives.Seetherespectivemanpagesformoreinformation.Forexampleyoucanprobablyuseulimit-nunlimitedtoraiseyoursoftlimituptothehardlimit.Youshouldincludethiscommandinashellscriptwhichstartsyourwebserver.

Unfortunately,it'snotalwaysthissimple.Asmentionedabove,youwillprobablyrunintosomesystemlimitationsthatwillneedtobeworkedaroundsomehow.Workwasdoneinversion1.2.1toimprovethesituationsomewhat.Hereisapartiallistofsystemsandworkarounds(assumingyouareusing1.2.1orlater).

BSDI2.0

UnderBSDI2.0youcanbuildApachetosupportmoredescriptorsbyadding-DFD_SETSIZE=nnntoEXTRA_CFLAGS(wherennnisthenumberofdescriptorsyouwishtosupport,keepitlessthanthehardlimit).Butitwillrunintotroubleifmorethanapproximately240Listendirectivesareused.ThismaybecuredbyrebuildingyourkernelwithahigherFD_SETSIZE.

FreeBSD2.2,BSDI2.1+

SimilartotheBSDI2.0case,youshoulddefineFD_SETSIZEandrebuild.ButtheextraListenlimitationdoesn'texist.

BydefaultLinuxhasakernelmaximumof256opendescriptorsperprocess.Thereareseveralpatchesavailableforthe2.0.xserieswhichraisethisto1024andbeyond,andyoucanfindtheminthe"unofficialpatches"sectionoftheLinuxInformationHQ.Noneofthesepatchesareperfect,andanentirelydifferentapproachislikelytobetakenduringthe2.1.xdevelopment.ApplyingthesepatcheswillraisetheFD_SETSIZEusedtocompileallprograms,andunlessyourebuildallyourlibrariesyoushouldavoidrunninganyotherprogramwithasoftdescriptorlimitabove256.Asofthiswritingthepatchesavailableforincreasingthenumberofdescriptorsdonottakethisintoaccount.Onadedicatedwebserveryouprobablywon'trunintotrouble.

Solaristhrough2.5.1

Solarishasakernelhardlimitof1024(maybelowerinearlierversions).Butithasalimitationthatfilesusingthestdiolibrarycannothaveadescriptorabove255.ApacheusesthestdiolibraryfortheErrorLogdirective.Whenyouhavemorethanapproximately110virtualhosts(withanerrorlogandanaccesslogeach)youwillneedtobuildApachewith-DHIGH_SLACK_LINE=256addedtoEXTRA_CFLAGS.Youwillbelimitedtoapproximately240errorlogsifyoudothis.

AIXversion3.2??appearstohaveahardlimitof128descriptors.Endofstory.Version4.1.5hasahardlimitof2000.

SCOOpenServer

Editthe/etc/conf/cf.d/stunefileoruse/etc/conf/cf.d/configurechoice7(UserandGroupconfiguration)andmodifytheNOFILESkernelparametertoasuitablyhighervalue.SCOrecommendsanumberbetween60and11000,thedefaultis110.Relinkandreboot,andthenewnumberofdescriptorswillbeavailable.

CompaqTru64UNIX/DigitalUNIX/OSF

1. Raiseopen_max_softandopen_max_hardto4096intheprocsubsystem.Doamanonsysconfig,sysconfigdb,andsysconfigtab.

2. Raisemax-vnodestoalargenumberwhichisgreaterthanthenumberofapacheprocesses*4096(Settingitto250,000shouldbegoodformostpeople).Doamanonsysconfig,sysconfigdb,andsysconfigtab.

3. IfyouareusingTru645.0,5.0A,or5.1,defineNO_SLACKtoworkaroundabugintheOS.CFLAGS="-DNO_SLACK"./configure

Others

Ifyouhavedetailsonanotheroperatingsystem,pleasesubmititthroughourBugReportPage.

InadditiontotheproblemsdescribedabovethereareproblemswithmanylibrariesthatApacheuses.ThemostcommonexampleisthebindDNSresolverlibrarythatisusedbyprettymucheveryunix,whichfailsifitendsupwithadescriptorabove256.Wesuspectthereareotherlibrariesthatsimilarlimitations.Sothecodeasof1.2.1takesadefensivestanceandtriestosavedescriptorslessthan16forusewhileprocessingeachrequest.Thisiscalledthelowslackline.

Notethatthisshouldn'twastedescriptors.IfyoureallyarepushingthelimitsandApachecan'tgetadescriptorabove16whenitwantsit,itwillsettleforonebelow16.

Inextremesituationsyoumaywanttolowerthelowslackline,butyoushouldn'teverneedto.Forexample,loweringitcanincreasethelimits240describedaboveunderSolarisandBSDI2.0.Butyou'llplayadelicatebalancinggamewiththedescriptorsneededtoservearequest.Shouldyouwanttoplaythisgame,thecompiletimeparameterisLOW_SLACK_LINEandthere'satinybitofdocumentationintheheaderfilehttpd.h.

Finally,ifyoususpectthatallthisslackstuffiscausingyouproblems,youcandisableit.Add-DNO_SLACKtoEXTRA_CFLAGSandrebuild.ButpleasereportittoourBugReportPagesothatwecaninvestigate.

RelevantStandards

ThispagedocumentsalltherelevantstandardsthattheApacheHTTPServerfollows,alongwithbriefdescriptions.

Inadditiontotheinformationlistedbelow,thefollowingresourcesshouldbeconsulted:

http://purl.org/NET/http-errata-HTTP/1.1SpecificationErratahttp://www.rfc-editor.org/errata.html-RFCErratahttp://ftp.ics.uci.edu/pub/ietf/http/#RFC-Apre-compiledlistofHTTPrelatedRFCs

Notice

Thisdocumentisnotyetcomplete.

HTTPRecommendations

Regardlessofwhatmodulesarecompiledandused,ApacheasabasicwebservercomplieswiththefollowingIETFrecommendations:

RFC1945(Informational)TheHypertextTransferProtocol(HTTP)isanapplication-levelprotocolwiththelightnessandspeednecessaryfordistributed,collaborative,hypermediainformationsystems.ThisdocumentsHTTP/1.0.

RFC2616(StandardsTrack)TheHypertextTransferProtocol(HTTP)isanapplication-levelprotocolfordistributed,collaborative,hypermediainformationsystems.ThisdocumentsHTTP/1.1.

RFC2396(StandardsTrack)AUniformResourceIdentifier(URI)isacompactstringofcharactersforidentifyinganabstractorphysicalresource.

HTMLRecommendations

RegardingtheHypertextMarkupLanguage,ApachecomplieswiththefollowingIETFandW3Crecommendations:

RFC2854(Informational)ThisdocumentsummarizesthehistoryofHTMLdevelopment,anddefinesthe"text/html"MIMEtypebypointingtotherelevantW3Crecommendations.

HTML4.01Specification(Errata)ThisspecificationdefinestheHyperTextMarkupLanguage(HTML),thepublishinglanguageoftheWorldWideWeb.ThisspecificationdefinesHTML4.01,whichisasubversionofHTML4.

HTML3.2ReferenceSpecificationTheHyperTextMarkupLanguage(HTML)isasimplemarkuplanguageusedtocreatehypertextdocumentsthatareportablefromoneplatformtoanother.HTMLdocumentsareSGMLdocuments.

XHTML1.1-Module-basedXHTML(Errata)ThisRecommendationdefinesanewXHTMLdocumenttypethatisbaseduponthemoduleframeworkandmodulesdefinedinModularizationofXHTML.

XHTML1.0TheExtensibleHyperTextMarkupLanguage(SecondEdition)(Errata)

ThisspecificationdefinestheSecondEditionofXHTML1.0,areformulationofHTML4asanXML1.0application,andthreeDTDscorrespondingtotheonesdefinedbyHTML4.

Authentication

Concerningthedifferentmethodsofauthentication,ApachefollowsthefollowingIETFrecommendations:

RFC2617(Draftstandard)"HTTP/1.0",includesthespecificationforaBasicAccessAuthenticationscheme.

Language/CountryCodes

ThefollowinglinksdocumentISOandotherlanguageandcountrycodeinformation:

ISO639-2ISO639providestwosetsoflanguagecodes,oneasatwo-lettercodeset(639-1)andanotherasathree-lettercodeset(thispartofISO639)fortherepresentationofnamesoflanguages.

ISO3166-1Thesepagesdocumentthecountrynames(officialshortnamesinEnglish)inalphabeticalorderasgiveninISO3166-1andthecorrespondingISO3166-1-alpha-2codeelements.

BCP47(BestCurrentPractice),RFC3066Thisdocumentdescribesalanguagetagforuseincaseswhereitisdesiredtoindicatethelanguageusedinaninformationobject,howtoregistervaluesforuseinthislanguagetag,andaconstructformatchingsuchlanguagetags.

RFC3282(StandardsTrack)Thisdocumentdefinesa"Content-language:"header,foruseincaseswhereonedesirestoindicatethelanguageofsomethingthathasRFC822-likeheaders,likeMIMEbodypartsorWebdocuments,andan"Accept-Language:"headerforuseincaseswhereonewishestoindicateone'spreferenceswithregardtolanguage.

||FAQ||

Apache

MPM"MPM" ApacheMPM

Base"Base"

Extension"Extension"

Experimental"Experimental" Apache

External"External"Apache ("")

LoadModule module

||FAQ||

Apache2

||FAQ||

Apache

URLhttp://www.example.com/path/to/file.html() UniformResourceLocator

URL-path/path/to/file.html url

file-path/usr/local/apache/htdocs/path/to/file.html file-path ServerRoot

directory-path/usr/local/apache/htdocs/path/to/

filenamefile.html

regexPerl regex

extension filenameApache:) filenamefile.html.enApache extension

MIME-typetext/html

env-variableApache

( Apache

(httpd.conf,srm.conf,access.conf<VirtualHost> <Directory> .htaccess

<Directory>,<Location>,<Files>Location,Files

.htaccess.htaccess

(:BoolenOR)httpd.conf .htaccess <Directory>

.htaccess

AllowOverride ()

Apache

Core"Core"Apache

MPM"MPM"

Base"Base"

Extension"Extension"Apache

Experimental"Experimental"Apache

||FAQ||

Apache2

||FAQ||

Apache

: ApacheHTTP

: Core

AcceptPathInfo

:: AcceptPathInfoOn|Off|Default

: AcceptPathInfoDefault

: ,,,.htaccess: FileInfo: Core: core: Apache2.0.30

/test/ here.html /test/nothere.html/more /more PATH_INFO

AcceptPathInfo :

Default

PATH_INFO

AcceptPathInfo PATH_INFO PATH_INFO

<Files"mypaths.shtml">

Options+Includes

AcceptPathInfoOn

</Files>

AccessFileName

:: AccessFileNamefilename[filename]...

: AccessFileName.htaccess

: ,: Core: core

AccessFileName.acl

/usr/local/web/index.html

/usr/.acl,/usr/local/.acl,/usr/local/web/.acl

AllowOverrideNone

</Directory>

AllowOverride

.htaccess

AddDefaultCharset

: : AddDefaultCharsetOn|Off|charset

: AddDefaultCharsetOff

: ,,,.htaccess: FileInfo: Core: core

HTTP AddDefaultCharsetOn1 charset:

AddDefaultCharsetutf-8

AddOutputFilterByType

: MIME-type: AddOutputFilterByTypefilter[;filter...]

MIME-type[MIME-type]...

: ,,,.htaccess: FileInfo: Core: core: Apache2.0.33

MIME-type

mod_deflate DEFLATE text/html text/plain

AddOutputFilterByTypeDEFLATEtext/htmltext/plain

text/html INCLUDES DEFLATE

OptionsIncludes

AddOutputFilterByTypeINCLUDES;DEFLATEtext/html

</Location>

AddOutputFilterByType DefaultType DefaultType

AddOutputFilter

SetOutputFilter

AllowEncodedSlashes

: URL: AllowEncodedSlashesOn|Off

: AllowEncodedSlashesOff

: ,: Core: core: Apache2.0.46

AllowEncodedSlashes ( / %2F

URL404(Notfound)

AllowEncodedSlashesOn PATH_INFO

TurningAllowEncodedSlashesOnismostlyusefulwhenusedinconjunctionwithPATH_INFO.

%2F() %5CURL

AcceptPathInfo

AllowOverride

: .htaccess: AllowOverrideAll|None|directive-type

[directive-type]...

: AllowOverrideAll

:: Core: core

( AccessFileName) .htaccess

<Directory>AllowOverride<Directory> <Location>

None .htaccess

All .htaccess

directive-type

AuthConfig( AuthDBMGroupFile,AuthDBMUserFileAuthGroupFile,AuthName,AuthType,AuthUserFile,Require )

FileInfo( DefaultType

LanguagePriority,SetHandler,SetInputFilter,SetOutputFilter,mod_mimeAdd*Remove*

Indexes (AddDescriptionAddIconByType,DefaultIcon,DirectoryIndex,

FancyIndexing,HeaderName,IndexIgnore,IndexOptions,ReadmeName )

Limit( Allow

Options

AllowOverrideAuthConfigIndexes

AuthConfig Indexes

AccessFileName

.htaccess

AuthName

: HTTP(:realm): AuthNameauth-domain

: ,.htaccess: AuthConfig: Core: core

(:realm) Require AuthUserFile AuthGroupFile

AuthName"TopSecret"

AuthName

AuthType

:: AuthTypeBasic|Digest

AuthUserFile AuthGroupFile

CGIMapExtension

: CGI: CGIMapExtensioncgi-path.extension

: None

: ,.htaccess: FileInfo: Core: core: NetWare

ApacheCGI .foo .fooCGIFOO

ContentDigest

: Content-MD5HTTP: ContentDigestOn|Off

: ContentDigestOff

: ,,,.htaccess: Options: Core: core

RFC1864RFC2068 Content-MD5

MD5( )

Content-MD5 :

Content-MD5:AuLb7Dp1rqtRtxz2m9kRpA==

Content-MD5 core

DefaultType

: MIME: DefaultTypeMIME-type

: DefaultTypetext/plain

DefaultTypeimage/gif

.gif GIF

ForceType MIME

: : <Directorydirectory-path>...</Directory>

: ,: Core: core

pathUnix ?1 /home/user/public_html <Directory

/*/public_html> <Directory

/home/*/public_html> :

OptionsIndexesFollowSymLinks

</Directory>

directory-path:Apache <Directory>

<Directory~"^/www/.*/[0-9]{3}">

/www/ 3

() <Directory> ()

AllowOverrideNone

</Directory>

AllowOverrideFileInfo

</Directory>

/home/web/dir/doc.html :

AllowOverrideNone (.htaccess)AllowOverrideFileInfo (/home)/home/.htaccess,/home/web/.htaccess,/home/web/.htaccess FileInfo

<Directory~abc$>

#...directiveshere...

</Directory>

<Directory> .htaccess/home/abc/public_html/abc <Directory>

Apache <Directory/> AllowfromAllURLApache

OrderDeny,Allow

DenyfromAll

</Directory>

httpd.conf <Directory><LimitExcept>

: : <DirectoryMatchregex>...</DirectoryMatch>

: ,: Core: core

<DirectoryMatch"^/www/.*/[0-9]{3}">

/www/3

DocumentRoot

: : DocumentRootdirectory-path

: DocumentRoot/usr/local/apache/htdocs

: ,: Core: core

httpd Alias

DocumentRoot/usr/web

http://www.my.host.com/index.html/usr/web/index.html

DocumentRoot

EnableMMAP

: : EnableMMAPOn|Off

: EnableMMAPOn

httpdNFS DocumentRoot httpd

EnableMMAPOff

<Directory"/path-to-nfs-files">

EnableMMAPOff

</Directory>

EnableSendfile

: sendfile: EnableSendfileOn|Off

: EnableSendfileOn

: ,,,.htaccess: FileInfo: Core: core: 2.0.44

httpd sendfile

sendfilereadsend

sendfileLinuxsendfile IPv6TCP-checksum DocumentRoot(NFSSMB)

EnableSendfileOff

NFSSMB :

<Directory"/path-to-nfs-files">

EnableSendfileOff

</Directory>

ErrorDocument

:: ErrorDocumenterror-codedocument

: ,,,.htaccess: FileInfo: Core: core: Apache2.0

Apache

1. Apache

3. URL-path

4. URL

24 ErrorDocumentApache

URLURL(/) URL :

ErrorDocument500http://foo.example.com/cgi-bin/tester

ErrorDocument404/cgi-bin/bad_urls.pl

ErrorDocument401/subscription_info.html

ErrorDocument403"Sorrycan'tallowyouaccesstoday"

defaultApache ErrorDocument Apache

ErrorDocument404/cgi-bin/bad_urls.pl

ErrorDocument404default

</Directory>

URL( http) ErrorDocumentApache

ErrorDocument401URL 401ErrorDocument401

MicrosoftInternetExplorer(MSIE)MSIE Microsoft

ErrorLog

:: ErrorLogfile-path|syslog[:facility]

: ErrorLoglogs/error_log(Unix)ErrorLog

logs/error.log(WindowsandOS/2)

: ,: Core: core

ErrorLog

ErrorLog/var/log/httpd/error_log

file-path(|)

ErrorLog"|/usr/local/bin/httpd_errors"

syslog syslogd(8)syslog:facility syslog(1)

ErrorLogsyslog:user

LogLevel

Apache

FileETag

: ETagHTTP: FileETagcomponent...

: FileETagINodeMTimeSize

FileETag ETag

ETag inode,(mtime)

INodeinode

FileETagINodeMTimeSize

NoneETag

INode,MTime,Size + -

FileETagINodeMTimeSize ( )

<Files>

:: <Filesfilename>...</Files>

: ,,,.htaccess: All: Core: core

<Files> </Files> ()

.htaccess <Location> <Directory>

filename ? *

<Files~"\.(gif|jpe?g|png)$">

<Directory> <Location> <Files> .htaccess

: : <FilesMatchregex>...</FilesMatch>

<FilesMatch"\.(gif|jpe?g|png)$">

ForceType

: MIME: ForceTypeMIME-type|None

: ,.htaccess: FileInfo: Core: core: Apache2.0core

.htaccess <Directory> <Location> <Files>

MIME-type

ForceTypeimage/gif

DefaultType

None ForceType :

#forceallfilestobeimage/gif:

ForceTypeimage/gif

</Location>

#butnormalmime-typeassociationshere:

ForceTypeNone

</Location>

HostnameLookups

: IPDNS: HostnameLookupsOn|Off|Double

: HostnameLookupsOff

: ,,: Core: core

DNS IP

mod_access 2Double 2 REMOTE_HOST

IdentityCheck

: RFC1413: IdentityCheckOn|Off

: IdentityCheckOff

: ,,: Core: core

identd

: : <IfDefine[!]parameter-name>...</IfDefine>

<IfDefinetest>...</IfDefine> test test

<IfDefine> test :

parameter-name!parameter-name

parameter-name

parameter-name httpd -Dparameter-

httpd-DReverseProxy...

#httpd.conf

LoadModulerewrite_modulemodules/mod_rewrite.so

LoadModuleproxy_modulemodules/libproxy.so

</IfDefine>

: : <IfModule[!]module-name>...</IfModule>

<IfModuletest>...</IfModule>test test

<IfModule> test

modulename!modulename

modulename Apache (modulename

modulename mod_rewrite.c

STANDARD20_MODULE_STUFF

Include

:: Includefile-path|directory-path

: ,,: Core: core: 2.0.41

( fnmatch)httpd

ServerRoot

Include/usr/local/apache2/conf/ssl.conf

Include/usr/local/apache2/conf/vhosts/*.conf

ServerRoot:

Includeconf/ssl.conf

Includeconf/vhosts/*.conf

apachectlconfigtest :

root@host#apachectlconfigtest

Processingconfigfile:/usr/local/apache2/conf/ssl.conf

Processingconfigfile:

/usr/local/apache2/conf/vhosts/vhost1.conf

Processingconfigfile:

/usr/local/apache2/conf/vhosts/vhost2.conf

SyntaxOK

apachectl

KeepAlive

: HTTP: KeepAliveOn|Off

: KeepAliveOn

: ,: Core: core

HTTP/1.0Keep-AliveHTTP/1.1 TCP HTML50%

HTTP/1.0 Keep-AliveKeep-Alive CGISSI HTTP/1.1

MaxKeepAliveRequests

KeepAliveTimeout

:: KeepAliveTimeoutseconds

: KeepAliveTimeout15

: ,: Core: core

Apache

KeepAliveTimeout

<Limit>

: HTTP: <Limitmethod[method]...>...</Limit>

<Limit> HTTPDELETE :

Requirevalid-user

</Limit>

: GET,POST,PUT,PROPFIND,PROPPATCH,MKCOL,COPY,MOVE,LOCK,UNLOCK.

GET HEAD TRACE

: HTTP: <LimitExceptmethod[method]...>...

</LimitExcept>

Requirevalid-user

</LimitExcept>

LimitInternalRecursion

:: LimitInternalRecursionnumber[number]

: LimitInternalRecursion10

: ,: Core: core: Apache2.0.47

Action Actionmod_dir DirectoryIndex

LimitInternalRecursion

LimitInternalRecursion5

LimitRequestBody

: HTTP: LimitRequestBodybytes

: LimitRequestBody0

bytes0()2147483647(2GB)

LimitRequestBody ()

LimitRequestBody102400

LimitRequestFields

: HTTP: LimitRequestFieldsnumber

: LimitRequestFields100

:: Core: core

number0()32767 DEFAULT_LIMIT_REQUEST_FIELDS(100)

LimitRequestBody HTTPHTTP

LimitRequestFields50

LimitRequestFieldSize

: HTTP: LimitRequestFieldsizebytes

: LimitRequestFieldsize8190

:: Core: core

HTTP bytesDEFAULT_LIMIT_REQUEST_FIELDSIZE(8192)

LimitRequestFieldSize

LimitRequestFieldSize4094

LimitRequestLine

: HTTP: LimitRequestLinebytes

: LimitRequestLine8190

:: Core: core

HTTP bytes08190)

LimitRequestLine LimitRequestLine URI

LimitRequestLine4094

LimitXMLRequestBody

: XML: LimitXMLRequestBodybytes

: LimitXMLRequestBody1000000

XML() 0

LimitXMLRequestBody0

: URL: <LocationURL-path|URL>...</Location>

: ,: Core: core

() URL /path/ http://servername

scheme://servername/path

URL ? *

<Location~"/(extra|special)/data">

URL /extra/data /special/data<LocationMatch> <Location>

<Location> SetHandler

OrderDeny,Allow

Denyfromall

Allowfrom.foo.com

</Location>

URL <LocationMatch> <Location>

<LocationMatch^/abc> /abcURLURL () <Location><Location>proxy /abc//def

: URL: <LocationMatchregex>...</LocationMatch>

: ,: Core: core

<LocationMatch> <Location> URL

<LocationMatch"/(extra|special)/data">

URL /extra/data /special/data

LogLevel

: ErrorLog: LogLevellevel

: LogLevelwarn

: ,: Core: core

LogLevel( ErrorLog )

emerg - Childcannotopenlockfile.Exiting()

alert getpwuid:couldn'tdetermineusernamefromuid(getpwuid:UID)

crit socket:Failedtogetasocket,exitingchild(socket:)

error Prematureendofscriptheaders()warn childprocess1234didnotexit,sendinganother

SIGHUP(1234SIGHUP)notice httpd:caughtSIGBUS,attemptingtodumpcorein

...(httpd:SIGBUS...)info "Serverseemsbusy,(youmayneedtoincrease

StartServers,orMin/MaxSpareServers)..."((StartServersMin/MaxSpareServers))

debug "Openingconfigfile..."(...)

LogLevelnotice

notice

MaxKeepAliveRequests

:: MaxKeepAliveRequestsnumber

: MaxKeepAliveRequests100

: ,: Core: core

MaxKeepAliveRequests KeepAlive

MaxKeepAliveRequests500

MaxRanges

: Numberofrangesallowedbeforereturningthecompleteresource

: MaxRangesdefault|unlimited|none|

number-of-ranges

: MaxRanges200

: ,,: Core: core: AvailableinApacheHTTPServer2.0.65andlater

Thedocumentationforthisdirectivehasnotbeentranslatedyet.PleasehavealookattheEnglishversion.

NameVirtualHost

: IP: NameVirtualHostaddr[:port]

:: Core: core

NameVirtualHost

addr IP

NameVirtualHost IP

_default_ NameVirtualHostIPNameVirtualHost VirtualHost)

NameVirtualHost[2001:db8::a00:20ff:fea7:ccea]:8080

NameVirtualHost*

<VirtualHost> NameVirtualHost

</VirtualHost>

Options

:: Options[+|-]option[[+|-]option]...

: OptionsAll

: ,,,.htaccess: Options: Core: core

Options

option None 1

MultiViews

ExecCGI

mod_cgiCGI

FollowSymLinks

Includes

mod_includeSSI

IncludesNOEXEC

SSI #exec #execCGIvirtual ScriptAlias CGI

Indexes

URL DirectoryIndex

mod_autoindex

MultiViews

mod_negotiation "MultiViews"

SymLinksIfOwnerMatch

Options +

</Directory>

OptionsIncludes

</Directory>

/web/docs/spec Includes 2 -:

</Directory>

Options+Includes-Indexes

</Directory>

/web/docs/spec FollowSymLinks Includes

-IncludesNOEXEC -Includes SSI

Require

:: Requireentity-name[entity-name]...

Requireuseruserid[userid]...

Requiregroupgroup-name[group-name]...

Requirevalid-user

Require AuthName AuthType ()AuthUserFile AuthGroupFile

AuthTypeBasic

AuthName"RestrictedDirectory"

AuthUserFile/web/users

AuthGroupFile/web/groups

Requiregroupadmin

Satisfy

mod_access

RLimitCPU

: ApacheCPU: RLimitCPUseconds|max[seconds|max]

:: ,,,.htaccess: All: Core: core

Apache ApacheforkApache fork

RLimitMEM

RLimitNPROC

RLimitMEM

: Apache: RLimitMEMbytes|max[bytes|max]

RLimitCPU

RLimitNPROC

: Apache: RLimitNPROCnumber|max[number|max]

RLimitMEM

RLimitCPU

Satisfy

:: SatisfyAny|All

: SatisfyAll

: ,.htaccess: AuthConfig: Core: core: 2.0.51 <Limit>

Allow Require Any

Requirevalid-user

Allowfrom192.168.1

SatisfyAny

2.0.51 <Limit> <LimitExcept>

Require

ScriptInterpreterSource

: CGI: ScriptInterpreterSourceRegistry|Registry-

Strict|Script

: ScriptInterpreterSourceScript

: ,,,.htaccess: FileInfo: Core: core: Win32 Registry-StrictApache2.0

ApacheCGI ) Win32

#!C:/Perl/bin/perl.exe

perl PATH:

#!perl

ScriptInterpreterSourceRegistry (Windows HKEY_CLASSES_ROOTShell\ExecCGI\Command Shell\Open\Command

Apache Script

ScriptInterpreterSourceRegistry ScriptAliasApache MicrosoftInternetExplorer

Apache2.0 Registry-Strict RegistryShell\ExecCGI\Command ExecCGIWindows

ServerAdmin

: : ServerAdminemail-address

: ,: Core: core

ServerAdmin

ServerAdminwww-admin@foo.example.com

ServerAlias

: : ServerAliashostname[hostname]...

:: Core: core

ServerAlias

<VirtualHost*>

ServerNameserver.domain.com

ServerAliasserverserver2.domain.comserver2

</VirtualHost>

Apache

ServerName

:: ServerNamefully-qualified-domain-name[:port]

: ,: Core: core: 2.01.3 Port

ServerName simple.example.comDNS www.example.com

ServerNamewww.example.com:80

ServerName IPServerName

<VirtualHost> ServerName

URL( mod_dir)

DNSApacheApacheUseCanonicalName

NameVirtualHost

ServerAlias

ServerPath

: URL: ServerPathURL-path

:: Core: core

ServerPath URL

Apache

ServerRoot

:: ServerRootdirectory-path

: ServerRoot/usr/local/apache

:: Core: core

ServerRoot

ServerRoot/home/httpd

httpd -dServerRoot

ServerSignature

:: ServerSignatureOn|Off|EMail

: ServerSignatureOff

ServerSignature (mod_info)

Off (Apache-1.2)ServerName EMail ServerAdmin"mailto:"

2.0.44 ServerSignature

ServerTokens

: ServerHTTP: ServerTokens

: ServerTokensFull

:: Core: core

ServerOS

ServerTokensProd[uctOnly]

(): Server:Apache

ServerTokensMajor

Serversends(e.g.):Server:Apache/2

ServerTokensMinor

Serversends(e.g.):Server:Apache/2.0

ServerTokensMin[imal]

(): Server:Apache/2.0.41

ServerTokensOS

(): Server:Apache/2.0.41(Unix)

ServerTokensFull()(): Server:Apache/2.0.41(Unix)PHP/4.2.2

MyMod/1.2

2.0.44 ServerSignature

ServerSignature

SetHandler

:: SetHandlerhandler-name|None

: ,,,.htaccess: FileInfo: Core: core: Apache2.0core

.htaccess <Directory> <Location>name

SetHandlerimap-file

:URL http://servername/status

</Location>

None SetHandler

AddHandler

SetInputFilter

: POST: SetInputFilterfilter[;filter...]

SetInputFilter POST

SetOutputFilter

:: SetOutputFilterfilter[;filter...]

SetOutputFilter

/www/data/ SSI

</Directory>

TimeOut

: : TimeOutseconds

: TimeOut300

:: Core: core

TimeOut :

1. GET

2. POSTPUTTCP

3. TCPACK

Apache1.21200

TraceEnable

: DeterminesthebehaviouronTRACErequests: TraceEnable[on|off|extended]

: TraceEnableon

:: Core: core: AvailableinApache1.3.34,2.0.55andlater

UseCanonicalName

:: UseCanonicalNameOn|Off|Dns

: UseCanonicalNameOn

: ,,: Core: core

Apache URL URL UseCanonicalNameOn

)Apache ServerName PortSERVER_NAME SERVER_PORT

UseCanonicalNameOffApache URLCGI SERVER_NAME SERVER_PORT

www URLhttp://www.domain.com/splat/ 1 www.domain.com-- FAQ

UseCanonicalName Off Apachehtttp://www/splat/

UseCanonicalNameDNS Host: IPDNSURL

CGI SERVER_NAME URL

ServerName

Listen

: IP: <VirtualHostaddr[:port][addr[:port]]...>

...</VirtualHost>

:: Core: core

<VirtualHost> </VirtualHost> <VirtualHost> Addr:

IPIPNameVirtualHost* IPIPIP

ServerAdminwebmaster@host.foo.com

DocumentRoot/www/docs/host.foo.com

ServerNamehost.foo.com

ErrorLoglogs/host.foo.com-error_log

TransferLoglogs/host.foo.com-access_log

</VirtualHost>

IPv6 IPv6:

<VirtualHost[2001:db8::a00:20ff:fea7:ccea]>

ServerAdminwebmaster@host.example.com

DocumentRoot/www/docs/host.example.com

ServerNamehost.example.com

ErrorLoglogs/host.example.com-error_log

TransferLoglogs/host.example.com-access_log

</VirtualHost>

IP alias )

||FAQ||

:port )

<VirtualHost>ApacheListen IP ListenApachelisten

IP _default_VirtualHost (_default_ )

:port )

ApacheDNSApacheApache

||FAQ||

ApacheMPM

: (MPM)

AcceptMutex

: acceptApache: AcceptMutexdefault|method

: AcceptMutexdefault

:: MPM: leader,perchild,prefork,threadpool,worker

AcceptMutex accept

Default

LockFile flock(2)

LockFile fcntl(2)

posixsem

pthread

POSIXThreads(PThreads) POSIX

sysvsem

LogLevel

BS2000Account

: BS2000: BS2000Accountaccount

:: MPM: perchild,prefork: BS2000

BS2000Account BS2000 Apache(BS2000POSIX(sub-LOGON BS2000) SYSROOT

BS2000Account

ApacheEBCDICport

CoreDumpDirectory

: Apache: CoreDumpDirectorydirectory

::: MPM: beos,leader,mpm_winnt,perchild,prefork,

threadpool,worker

Apache

Apacheroot Linux2.4 CoreDumpDirectory

EnableExceptionHook

:: EnableExceptionHookOn|Off

: EnableExceptionHookOff

:: MPM: leader,perchild,prefork,threadpool,worker: 2.0.49

--enable-exception-hookconfigure

mod_whatkilledus mod_backtrace

Trawick EnableExceptionHooksite

:: Groupunix-group

: Group#-1

:: MPM: beos,leader,mpmt_os2,perchild,prefork,

threadpool,worker: Apache2.0

Group :

Groupwww-group

nobody

Group( User)

: <VirtualHost>Apache2.0SuexecUserGroup

Group beos mpmt_os2MPM

Listen

: listenIP: Listen[IP-address:]portnumber

:: MPM: beos,leader,mpm_netware,mpm_winnt,mpmt_os2,

perchild,prefork,threadpool,worker: Apache2.0

ListenApache IPlisten Apache

Listen

listen Listen

808000

Listen80

Listen8000

Listen192.170.2.1:80

Listen192.170.2.5:8000

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

IP Listen'Addressalreadyinuse'

DNSApache

ListenBackLog

:: ListenBacklogbacklog

: ListenBacklog511

perchild,prefork,threadpool,worker

OS OSOS

LockFile

:: LockFilefilename

: LockFilelogs/accept.lock

:: MPM: leader,perchild,prefork,threadpool,worker

AcceptMutex fcntl flocklogsNFS

/var/tmp

AcceptMutex

MaxClients

: : MaxClientsnumber

::: MPM: beos,leader,prefork,threadpool,worker

MaxClients

( prefork) MaxClientsServerLimit

( beosworker) MaxClientsMPM16 ServerLimit 25( ThreadsPerChild

MaxClients16 ServerLimit

MaxMemFree

: free(): MaxMemFreeKBytes

: MaxMemFree0

:: MPM: beos,leader,mpm_netware,prefork,threadpool,

worker,mpm_winnt

MaxMemFree free()

MaxRequestsPerChild

:: MaxRequestsPerChildnumber

: MaxRequestsPerChild10000

:: MPM: leader,mpm_netware,mpm_winnt,mpmt_os2,

MaxRequestsPerChild MaxRequestsPerChild 0

mpm_netware mpm_winnt 0

MaxRequestsPerChild:

KeepAlive

MaxSpareThreads

:: MaxSpareThreadsnumber

::: MPM: beos,leader,mpm_netware,mpmt_os2,perchild,

threadpool,worker

perchild MaxSpareThreads10 MPM

worker,leader,threadpool MaxSpareThreads

250 MPM

mpm_netware MaxSpareThreads100 MPM

beos mpmt_os2 mpm_netware beosMaxSpareThreads50 mpmt_os2 10

MaxSpareThreads Apache

perchild MaxSpareThreads ThreadLimitmpm_netware MinSpareThreadsleader,threadpool,worker MinSpareThreads

ThreadsPerChild

MinSpareThreads

StartServers

MinSpareThreads

: : MinSpareThreadsnumber

::: MPM: beos,leader,mpm_netware,mpmt_os2,perchild,

threadpool,worker

perchild MinSpareThreads5 NumServers10 MinSpareThreads 550

worker,leader,threadpool MinSpareThreads75

mpm_netware MinSpareThreads10 MPM

beos mpmt_os2 mpm_netware beosMinSpareThreads1 mpmt_os2 5

MaxSpareThreads

StartServers

PidFile

: ID: PidFilefilename

: PidFilelogs/httpd.pid

:: MPM: beos,leader,mpm_winnt,mpmt_os2,perchild,

prefork,threadpool,worker

PidFile ID

PidFile/var/run/apache.pid

ErrorLog TransferLog PidFileID

PidFile

Apache2 apachectl()

ReceiveBufferSize

: TCPreceivebuffersize: ReceiveBufferSizebytes

: ReceiveBufferSize0

ScoreBoardFile

: : ScoreBoardFilefile-path

: ScoreBoardFilelogs/apache_status

:: MPM: beos,leader,mpm_winnt,perchild,prefork,

threadpool,worker

Apache Apache

ScoreBoardFile/var/run/apache_status

ScoreBoardFile RAM

Apache

SendBufferSize

: TCP: SendBufferSizebytes

: SendBufferSize0

ServerLimit

:: ServerLimitnumber

::: MPM: leader,perchild,prefork,threadpool,worker

preforkMPM Apache MaxClients

) workerMPM ThreadLimit

MaxClients

ServerLimitApache

preforkMPM MaxClients256()MaxClients

worker,leader,threadpoolMPM MaxClientsThreadsPerChild16() ThreadsPerChild

perchildMPM NumServers8()

ServerLimit20000

Apache

StartServers

:: StartServersnumber

::: MPM: leader,mpmt_os2,prefork,threadpool,worker

StartServers

MPM leader,threadpool,worker3 prefork 5 mpmt_os2 2

StartThreads

:: StartThreadsnumber

::: MPM: beos,mpm_netware,perchild

perchild StartThreads5

mpm_netware StartThreads50

beos StartThreads10

ThreadLimit

: : ThreadLimitnumber

::: MPM: leader,mpm_winnt,perchild,threadpool,worker: Apache2.0.41 mpm_winnt

Apache ThreadsPerChild

ThreadLimit ThreadsPerChild

ThreadsPerChild ApacheThreadsPerChild

ThreadLimit mpm_winnt1920 64

ThreadLimit20000(mpm_winnt ThreadLimit15000

ThreadsPerChild

:: ThreadsPerChildnumber

::: MPM: leader,mpm_winnt,threadpool,worker

mpm_winnt ThreadsPerChild 64 25

: ID: Userunix-userid

: User#-1

:: MPM: leader,perchild,prefork,threadpool,worker: Apache2.0

User IDroot Unix-userid

User( Group)

perchildMPMID <VirtualHost>

: <VirtualHost>

User beos mpmt_os2MPM

ApacheHTTPServerVersion2.0Apache>HTTPServer>Documentation>Version2.0>Modules

ApacheMPMbeos

Description: ThisMulti-ProcessingModuleisoptimizedforBeOS.

Status: MPMModuleIdentifier: mpm_beos_moduleSourceFile: beos.c

SummaryThisMulti-ProcessingModule(MPM)isthedefaultforBeOS.Itusesasinglecontrolprocesswhichcreatesthreadstohandlerequests.

SeealsoSettingwhichaddressesandportsApacheuses

MaxRequestsPerThreadDirective

Description: Limitonthenumberofrequeststhatanindividualthreadwillhandleduringitslife

Syntax: MaxRequestsPerThreadnumber

Default: MaxRequestsPerThread0

Context: serverconfigStatus: MPMModule: beos

TheMaxRequestsPerThreaddirectivesetsthelimitonthenumberofrequeststhatanindividualserverthreadwillhandle.AfterMaxRequestsPerThreadrequests,thethreadwilldie.IfMaxRequestsPerThreadis0,thenthethreadwillneverexpire.

SettingMaxRequestsPerThreadtoanon-zerolimithastwobeneficialeffects:

itlimitstheamountofmemorythatathreadcanconsumeby(accidental)memoryleakage;bygivingthreadsafinitelifetime,ithelpsreducethenumberofthreadswhentheserverloadreduces.

ForKeepAliverequests,onlythefirstrequestiscountedtowardsthislimit.Ineffect,itchangesthebehaviortolimitthenumberofconnectionsperthread.

ApacheMPMleader

Description: AnexperimentalvariantofthestandardworkerMPM

Status: MPMModuleIdentifier: mpm_leader_moduleSourceFile: leader.c

Summary

Warning

ThisMPMisexperimental,soitmayormaynotworkasexpected.

ThisisanexperimentalvariantofthestandardworkerMPM.ItusesaLeader/Followersdesignpatterntocoordinateworkamongthreads.Formoreinfo,seehttp://deuce.doc.wustl.edu/doc/pspdfs/lf.pdf.

TousetheleaderMPM,add--with-mpm=leadertotheconfigurescript'sargumentswhenbuildingthehttpd.

ThisMPMdependsonAPR'satomiccompare-and-swapoperationsforthreadsynchronization.Ifyouarecompilingforanx86targetandyoudon'tneedtosupport386s,oryouarecompilingforaSPARCandyoudon'tneedtorunonpre-UltraSPARCchips,add--enable-nonportable-atomics=yestotheconfigurescript'sarguments.ThiswillcauseAPRtoimplementatomicoperationsusingefficientopcodesnotavailableinolderCPUs.

ApacheMPMnetware

Description: Multi-ProcessingModuleimplementinganexclusivelythreadedwebserveroptimizedforNovellNetWare

Status: MPMModuleIdentifier: mpm_netware_moduleSourceFile: mpm_netware.c

SummaryThisMulti-ProcessingModule(MPM)implementsanexclusivelythreadedwebserverthathasbeenoptimizedforNovellNetWare.

Themainthreadisresponsibleforlaunchingchildworkerthreadswhichlistenforconnectionsandservethemwhentheyarrive.Apachealwaystriestomaintainseveralspareoridleworkerthreads,whichstandreadytoserveincomingrequests.Inthisway,clientsdonotneedtowaitforanewchildthreadstobespawnedbeforetheirrequestscanbeserved.

TheStartThreads,MinSpareThreads,MaxSpareThreads,andMaxThreadsregulatehowthemainthreadcreatesworkerthreadstoserverequests.Ingeneral,Apacheisveryself-regulating,somostsitesdonotneedtoadjustthesedirectivesfromtheirdefaultvalues.SiteswithlimitedmemorymayneedtodecreaseMaxThreadstokeeptheserverfromthrashing(spawningandterminatingidlethreads).Moreinformationabouttuningprocesscreationisprovidedintheperformancehintsdocumentation.

MaxRequestsPerChildcontrolshowfrequentlytheserverrecyclesprocessesbykillingoldonesandlaunchingnewones.OntheNetWareOSitishighlyrecommendedthatthisdirectiveremainsetto0.Thisallowsworkerthreadstocontinueservicingrequests

indefinitely.

MaxThreadsDirective

Description: SetthemaximumnumberofworkerthreadsSyntax: MaxThreadsnumber

Default: MaxThreads2048

Context: serverconfigStatus: MPMModule: mpm_netware

TheMaxThreadsdirectivesetsthedesiredmaximumnumberworkerthreadsallowable.Thedefaultvalueisalsothecompiledinhardlimit.Thereforeitcanonlybelowered,forexample:

MaxThreads512

ThreadStackSizeDirective

Description: DeterminethestacksizeforeachthreadSyntax: ThreadStackSizenumber

Default: ThreadStackSize65536

Context: serverconfigStatus: MPMModule: mpm_netware

Thisdirectivetellstheserverwhatstacksizetouseforeachoftherunningthreads.Ifyouevergetastackoverflowyouwillneedtobumpthisnumbertoahighersetting.

ApacheMPMos2

Description: Hybridmulti-process,multi-threadedMPMforOS/2

Status: MPMModuleIdentifier: mpm_mpmt_os2_moduleSourceFile: mpmt_os2.c

SummaryTheServerconsistsofamain,parentprocessandasmall,staticnumberofchildprocesses.

Theparentprocess'sjobistomanagethechildprocesses.ThisinvolvesspawningchildrenasrequiredtoensuretherearealwaysStartServersprocessesacceptingconnections.

Eachchildprocessconsistsofaapoolofworkerthreadsandamainthreadthatacceptsconnectionsandpassesthemtotheworkersviaaworkqueue.Theworkerthreadpoolisdynamic,managedbyamaintenancethreadsothatthenumberofidlethreadsiskeptbetweenMinSpareThreadsandMaxSpareThreads.

ApacheMPMperchild

Description: Multi-ProcessingModuleallowingfordaemonprocessesservingrequeststobeassignedavarietyofdifferentuserids

Status: MPMModuleIdentifier: mpm_perchild_moduleSourceFile: perchild.c

Summary

Thismoduleisnotfunctional.Developmentofthismoduleisnotcompleteandisnotcurrentlyactive.Donotuseperchildunlessyouareaprogrammerwillingtohelpfixit.

ThisMulti-ProcessingModule(MPM)implementsahybridmulti-process,multi-threadedwebserver.Afixednumberofprocessescreatethreadstohandlerequests.Fluctuationsinloadarehandledbyincreasingordecreasingthenumberofthreadsineachprocess.

Howitworks

AsinglecontrolprocesslaunchesthenumberofchildprocessesindicatedbytheNumServersdirectiveatserverstartup.EachchildprocesscreatesthreadsasspecifiedintheStartThreadsdirective.Theindividualthreadsthenlistenforconnectionsandservethemwhentheyarrive.

Apachealwaystriestomaintainapoolofspareoridleserverthreads,whichstandreadytoserveincomingrequests.Inthisway,clientsdonotneedtowaitfornewthreadstobecreated.Foreachchildprocess,ApacheassessesthenumberofidlethreadsandcreatesordestroysthreadstokeepthisnumberwithintheboundariesspecifiedbyMinSpareThreadsandMaxSpareThreads.Sincethisprocessisveryself-regulating,itisrarelynecessarytomodifythesedirectivesfromtheirdefaultvalues.Themaximumnumberofclientsthatmaybeservedsimultaneouslyisdeterminedbymultiplyingthenumberofserverprocessesthatwillbecreated(NumServers)bythemaximumnumberofthreadscreatedineachprocess(MaxThreadsPerChild).

WhiletheparentprocessisusuallystartedasrootunderUnixinordertobindtoport80,thechildprocessesandthreadsarelaunchedbyApacheasaless-privilegeduser.TheUserandGroupdirectivesareusedtosettheprivilegesoftheApachechildprocesses.Thechildprocessesmustbeabletoreadallthecontentthatwillbeserved,butshouldhaveasfewprivilegesbeyondthataspossible.Inaddition,unlesssuexecisused,thesedirectivesalsosettheprivilegeswhichwillbeinheritedbyCGIscripts.

MaxRequestsPerChildcontrolshowfrequentlytheserverrecyclesprocessesbykillingoldonesandlaunchingnewones.

Workingwithdifferentuser-IDsTheperchildMPMaddstheextraabilitytospecifythatparticularprocessesshouldserverequestsunderdifferentuser-IDs.Theseuser-IDscanthenbeassociatedwithspecificvirtualhosts.YouhavetouseoneChildPerUserIDdirectiveforeveryuser/groupcombinationyouwanttoberun.ThenyoucantieparticularvirtualhoststothatuserandgroupIDs.

Thefollowingexampleruns7childprocesses.Twoofthemarerununderuser1/group1.Thenextfourarerununderuser2/group2andtheremainingprocessusestheUserandGroupofthemainserver:

GlobalconfigNumServers7

ChildPerUserIDuser1group12

ChildPerUserIDuser2group24

Usingunbalancednumbersofprocessesasaboveisuseful,iftheparticularvirtualhostsproducedifferentload.Theassignmenttothevirtualhostsiseasilydoneasintheexamplebelow.Inconclusionwiththeexampleabovethefollowingassumes,thatserver2hastoserveabouttwiceofthehitsofserver1.

ExampleNameVirtualHost*

<VirtualHost*>

ServerNamefallbackhost

#noassignment;usefallback

</VirtualHost>

<VirtualHost*>

ServerNameserver1

AssignUserIDuser1group1

</VirtualHost>

<VirtualHost*>

ServerNameserver2

AssignUserIDuser2group2

</VirtualHost>

AssignUserIDDirective

Description: TieavirtualhosttoauserandgroupIDSyntax: AssignUserIDuser-idgroup-id

Context: virtualhostStatus: MPMModule: perchild

Tieavirtualhosttoaspecificuser/groupcombination.RequestsaddressedtothevirtualhostwherethisdirectiveappearswillbeservedbyaprocessrunningwiththespecifieduserandgroupID.

TheuserandgroupIDhastobeassignedtoanumberofchildrenintheglobalserverconfigusingtheChildPerUserIDdirective.Seethesectionaboveforaconfigurationexample.

ChildPerUserIDDirective

Description: SpecifyuserIDandgroupIDforanumberofchildprocesses

Syntax: ChildPerUserIDuser-idgroup-idnum-

children

Context: serverconfigStatus: MPMModule: perchild

SpecifyauserIDandgroupIDforanumberofchildprocesses.Thethirdargument,num-children,isthenumberofchildprocessestostartwiththespecifieduserandgroup.Itdoesnotrepresentaspecificchildnumber.Inordertousethisdirective,theservermustberuninitiallyasroot.Ifyoustarttheserverasanon-rootuser,itwillfailtochangetothelesserprivilegeduser.

Ifthetotalnumberofchildprocesses,foundbytotalingallofthethirdargumentstoallChildPerUserIDdirectivesintheconfigfile,islessthanNumServers,thenallremainingchildrenwillinherittheUserandGroupsettingsfromthemainserver.Seethesectionaboveforaconfigurationexample.

Security

Don'tsetuser-id(orgroup-id)torootunlessyouknowexactlywhatyouaredoing,andwhatthedangersare.

MaxThreadsPerChildDirective

Description: MaximumnumberofthreadsperchildprocessSyntax: MaxThreadsPerChildnumber

Default: MaxThreadsPerChild64

Thisdirectivesetsthemaximumnumberofthreadsthatwillbecreatedineachchildprocess.Toincreasethisvaluebeyonditsdefault,itisnecessarytochangethevalueoftheThreadLimitdirectiveandstopandre-starttheserver.

NumServersDirective

Description: TotalnumberofchildrenaliveatthesametimeSyntax: NumServersnumber

Default: NumServers2

TheNumServersdirectivedeterminesthenumberofchildrenaliveatthesametime.Thisnumbershouldbelargeenoughtohandletherequestsfortheentiresite.Toincreasethisvaluebeyondthevalueof8,itisnecessarytochangethevalueoftheServerLimitdirectiveandstopandre-starttheserver.Seethesectionaboveforaconfigurationexample.

||FAQ||

ApacheMPMprefork

: fork: MPM: mpm_prefork_module: prefork.c

(MPM) UnixApache1.3 MPM

MPMMPM

Apache

listen

StartServers

MaxClientsApache ()

Unix80 rootApache

MaxRequestsPerChild

MaxSpareServers

:: MaxSpareServersnumber

: MaxSpareServers10

:: MPM: prefork

MaxSpareServers kill

MinSpareServers

StartServers

||FAQ||

MinSpareServers

:: MinSpareServersnumber

: MinSpareServers5

:: MPM: prefork

MaxSpareServers 11

MaxSpareServers

StartServers

ApacheMPMthreadpool

Description: YetanotherexperimentalvariantofthestandardworkerMPM

Status: MPMModuleIdentifier: mpm_threadpool_moduleSourceFile: threadpool.c

Summary

Warning

ThisMPMisadeveloperplaygroundandhighlyexperimental,soitmayormaynotworkasexpected.

ThisisanexperimentalvariantofthestandardworkerMPM.RatherthanqueuingconnectionsliketheworkerMPM,thethreadpoolMPMqueuesidleworkerthreadsandhandseachacceptedconnectiontothenextavailableworker.

ThethreadpoolMPMcan'tmatchtheperformanceoftheworkerMPMinbenchmarktesting.Asof2.0.39,someofthekeyload-throttingconceptsfromthethreadpoolMPMhavebeenincorporatedintotheworkerMPM.Thethreadpoolcodeisusefulprimarilyasaresearchplatform.Forgeneral-purposeuseandforanyproductionenvironments,useworkerinstead.

||FAQ||

ApacheMPMwinnt

: WindowsNT: MPM: mpm_winnt_module: mpm_winnt.c

(MPM) WindowsNT

||FAQ||

Win32DisableAcceptEx

: accept()AcceptEx: Win32DisableAcceptEx

: AcceptEx()AcceptEx()

:: MPM: mpm_winnt: 2.0.49

AcceptEx()MicrosoftWinSockv2API BSD accept()

API WindowsVPNAcceptEx()

[error](730038)Anoperationwasattemptedonsomethingthatis

notasocket.:winnt_accept:AcceptExfailed.Attemptingto

recover.

||FAQ||

ApacheMPMworker

: : MPM: mpm_worker_module: worker.c

MPM ThreadsPerChild

ThreadsPerChild MaxClients

Apache

||FAQ||

() ThreadsPerChild

Apache MinSpareThreads MaxSpareThreadsfork ThreadsPerChild

ThreadsPerChild ThreadLimit

ThreadsPerChild

MaxRequestsPerChild0MaxSpareThreads MaxClients

workerMPM

ServerLimit16

StartServers2

MaxClients150

MinSpareThreads25

MaxSpareThreads75

ThreadsPerChild25

Unix80 rootApache

MaxRequestsPerChild

||FAQ||

Apachemod_access

: IP: Base: access_module: mod_access.c: 2.1

mod_access .htaccessIP Order Allow Deny

(GET,PUT,POST)

Satisfy

Require

:: Allowfromall|host|env=env-variable

[host|env=env-variable]...

: ,.htaccess: Limit: Base: mod_access

from Allowfromall

:Allowfromapache.org

Apache HostnameLookupsIPIPDNS

:Allowfrom10.1.2.3

Allowfrom10.1

:Allowfrom10.1.0.0/255.255.0.0

a.b.c.dw.x.y.z

/nnnCIDR

:Allowfrom10.1.0.0/16

IPv6IPv6:

Allowfrom2001:db8::a00:20ff:fea7:ccea

Allowfrom2001:db8::a00:20ff:fea7:ccea/10

Allow variable mod_setenvif

) RefererHTTP

:SetEnvIfUser-Agent^KnockKnock/2\.0let_me_in

OrderDeny,Allow

Denyfromall

Allowfromenv=let_me_in

</Directory>

user-agent KnockKnock/2.0

:: Denyfromall|host|env=env-variable

[host|env=env-variable]...

: Allow Deny: Orderordering

: OrderDeny,Allow

Order Allow Deny

Deny,Allow

Deny Allow

Allow,Deny

Allow Deny

Mutual-failure

Allow Deny

apache.org

OrderDeny,Allow

Denyfromall

Allowfromapache.org

foo.apache.org apache.org

OrderAllow,Deny

Allowfromapache.org

Denyfromfoo.apache.org

Order Deny,Allowapache.org Denyfromfoo.apache.org

||FAQ||

apache.org allow

Order Allow

OrderAllow,Deny

</Directory>

deny /www

Order Directory .htaccess Allow Deny

Directory,Location,Files

||FAQ||

Apachemod_actions

: CGI: Base: actions_module: mod_actions.c

Action CGI

mod_cgi

CGIApache

Action

: CGI: Actionaction-typecgi-script

: ,,,.htaccess: FileInfo: Base: mod_actions

action-type cgi-scriptAddHandler CGIURL-pathMIMEURL CGIPATH_INFOPATH_TRANSLATED

#Requestsforfilesofaparticulartype:

Actionimage/gif/cgi-bin/images.cgi

#Filesofaparticularfileextension

AddHandlermy-file-type.xyz

Actionmy-file-type/cgi-bin/program.cgi

MIME image/gif

2 .xyz

AddHandler

||FAQ||

Script

: CGI: Scriptmethodcgi-script

: ,,: Base: mod_actions

method cgi-scriptAddHandler CGIURL-pathPATH_INFOPATH_TRANSLATED

ScriptPUT Scriptput

Script CGI

#For<ISINDEX>-stylesearching

ScriptGET/cgi-bin/search

#ACGIPUThandler

ScriptPUT/~bob/put.cgi

||FAQ||

Apachemod_alias

: : Base: alias_module: mod_alias.c

URLScriptAliasCGI

Redirect URL

mod_aliasURL

mod_rewrite

AliasRedirect ( <VirtualHost>)AliasRedirect

AliasRedirect Redirect RedirectMatchAliasAliasRedirect

Alias/foo/bar/baz

Alias/foo/gaq

/fooAlias /foo/barAlias

: URL: AliasURL-pathfile-path|directory-path

: ,: Base: mod_alias

Alias DocumentRoot

directory-filename

Alias/image/ftp/pub/image

http://myserver/image/foo.gif /ftp/pub/image/foo.gif

url-path/ //usr/local/apache/icons/ /icons

Alias DocumentRoot

Alias/image/ftp/pub/image

Orderallow,deny

Allowfromall

</Directory>

AliasMatch

: URL: AliasMatchregexfile-path|directory-path

Alias URL

AliasMatch^/icons(.*)/usr/local/apache/icons$1

Redirect

: URL: Redirect[status]URL-pathURL

: ,,,.htaccess: FileInfo: Base: mod_alias

RedirectURL URL URL (%)URL

Redirect/servicehttp://foo2.bar.com/service

http://myserver/service/foo.txthttp://foo2.bar.com/service/foo.txt

RedirectAliasScriptAlias.htaccess<Directory> URL-pathURL

status "temporary"(HTTP302)HTTP:

permanent(301)

temp(302)

seeother"SeeOther"(303)

gone"Gone"(410)

Status 300399(http_protocol.c send_error_response)

Redirectpermanent/onehttp://example.com/two

Redirect303/threehttp://example.com/other

RedirectMatch

: URL: RedirectMatch[status]regexURL

RedirectJPEG:

RedirectMatch(.*)\.gif$http://www.anotherserver.com$1.jpg

RedirectPermanent

: URL: RedirectPermanentURL-pathURL

Redirect (301)

RedirectTemp

: URL: RedirectTempURL-pathURL

Redirect (302)

ScriptAlias

: URLCGI: ScriptAliasURL-pathfile-path|directory-path

ScriptAlias mod_cgicgi-scriptURL(%) URL-path

ScriptAlias/cgi-bin//web/cgi-bin/

http://myserver/cgi-bin/foo

||FAQ||

ScriptAliasMatch

: URLCGI: ScriptAliasMatchregexfile-path|directory-

ScriptAliasbin:

ScriptAliasMatch^/cgi-bin(.*)/usr/local/apache/cgi-bin$1

||FAQ||

Apachemod_asis

: HTTP: Base: asis_module: mod_asis.c

send-as-isHTTP

Cginph

mime httpd/send-as-is

mod_headers

mod_cern_meta

Apache

||FAQ||

send-as-is

AddHandlersend-as-isasis

.asisApache HTTP

asis()

Status:301NowwheredidIleavethatURL

Location:http://xyz.abc.com/foo/bar.html

<html>

<head>

<title>Lameexcuses'R'us</title>

</head>

<body>

<h1>Fred'sexceptionallywonderfulpagehasmovedto

<ahref="http://xyz.abc.com/foo/bar.html">Joe's</a>site.

</body>

</html>

: Date: Server:

||FAQ||

Apachemod_auth

:: Base: auth_module: mod_auth.c: 2.1

HTTPmod_auth_digest

Require

Satisfy

AuthName

AuthType

AuthAuthoritative

: : AuthAuthoritativeOn|Off

: AuthAuthoritativeOn

: ,.htaccess: AuthConfig: Base: mod_auth

AuthAuthoritative Off ID(Configuration modules.c)"AuthenticationRequired"

mod_auth_dbm,mod_auth_msql,mod_auth_anon() AuthUserFile

ID "AuthenticationRequired"NCSA

.htaccessAuthUserFile AuthGroupFile AuthUserFile AuthGroupFile

AuthGroupFile

: : AuthGroupFilefile-path

AuthGroupFile

:mygroup:bobjoeanne

AuthDBMGroupFile

AuthGroupFile

||FAQ||

AuthUserFile

: : AuthUserFilefile-path

AuthUserFile

src/support htpasswd

ID username Filename :

htpasswd-cFilenameusername

Filename username2:

htpasswdFilenameusername2

AuthUserFile

ApacheModulemod_auth_anon

Description: Allows"anonymous"useraccesstoauthenticatedareas

Status: ExtensionModuleIdentifier: auth_anon_moduleSourceFile: mod_auth_anon.cCompatibility: Availableonlyinversionspriorto2.1

SummaryThismoduledoesaccesscontrolinamannersimilartoanonymous-ftpsites;i.e.havea'magic'userid'anonymous'andtheemailaddressasapassword.Theseemailaddressescanbelogged.

Combinedwithother(database)accesscontrolmethods,thisallowsforeffectiveusertrackingandcustomizationaccordingtoauserprofilewhilestillkeepingthesiteopenfor'unregistered'users.OneadvantageofusingAuth-basedusertrackingisthat,unlikemagic-cookiesandfunnyURLpre/postfixes,itiscompletelybrowserindependentanditallowsuserstoshareURLs.

Example

Theexamplebelow(whencombinedwiththeAuthdirectivesofahtpasswd-filebased(orGDM,mSQLetc.)baseaccesscontrolsystemallowsusersinas'guests'withthefollowingproperties:

ItinsiststhattheuserentersauserID.(Anonymous_NoUserID)Itinsiststhattheuserentersapassword.(Anonymous_MustGiveEmail)Thepasswordenteredmustbeavalidemailaddress,ie.containatleastone'@'anda'.'.(Anonymous_VerifyEmail)TheuserIDmustbeoneofanonymousguestwwwtestwelcomeandcomparisonisnotcasesensitive.(Anonymous)AndtheEmailaddressesenteredinthepasswdfieldareloggedtotheerrorlogfile.(Anonymous_LogEmail)

Excerptofhttpd.conf:Anonymous_NoUserIDoff

Anonymous_MustGiveEmailon

Anonymous_VerifyEmailon

Anonymous_LogEmailon

Anonymousanonymousguestwwwtestwelcome

AuthName"Use'anonymous'&Emailaddressforguestentry"

AuthTypebasic

#AnAuthUserFile/AuthDBUserFile/AuthDBMUserFile

#directivemustbespecified,oruse

#Anonymous_Authoritativeforpublicaccess.

#Inthe.htaccessforthepublicdirectory,add:

<Files*>

OrderDeny,Allow

Allowfromall

Requirevalid-user

</Files>

AnonymousDirective

Description: SpecifiesuserIDsthatareallowedaccesswithoutpasswordverification

Syntax: Anonymoususer[user]...

Context: directory,.htaccessOverride: AuthConfigStatus: ExtensionModule: mod_auth_anon

Alistofoneormore'magic'userIDswhichareallowedaccesswithoutpasswordverification.TheuserIDsarespaceseparated.Itispossibletousethe'and"quotestoallowaspaceinauserIDaswellasthe\escapecharacter.

Pleasenotethatthecomparisoniscase-IN-sensitive.Istronglysuggestthatthemagicusername'anonymous'isalwaysoneofthealloweduserIDs.

Example:Anonymousanonymous"NotRegistered""Idon'tknow"

ThiswouldallowtheusertoenterwithoutpasswordverificationbyusingtheuserIDs"anonymous","AnonyMous","NotRegistered"and"IDon'tKnow".

Anonymous_AuthoritativeDirective

Description: Configuresifauthorizationwillfall-throughtoothermethods

Syntax: Anonymous_AuthoritativeOn|Off

Default: Anonymous_AuthoritativeOff

WhensetOn,thereisnofall-throughtootherauthenticationmethods.SoifauserIDdoesnotmatchthevaluesspecifiedintheAnonymousdirective,accessisdenied.

Besureyouknowwhatyouaredoingwhenyoudecidetoswitchiton.AndrememberthattheorderinwhichtheAuthenticationmodulesarequeriedisdefinedinthemodules.cfilesatcompiletime.

Anonymous_LogEmailDirective

Description: Setswhetherthepasswordenteredwillbeloggedintheerrorlog

Syntax: Anonymous_LogEmailOn|Off

Default: Anonymous_LogEmailOn

WhensetOn,thedefault,the'password'entered(whichhopefullycontainsasensibleemailaddress)isloggedintheerrorlog.

Anonymous_MustGiveEmailDirective

Description: SpecifieswhetherblankpasswordsareallowedSyntax: Anonymous_MustGiveEmailOn|Off

Default: Anonymous_MustGiveEmailOn

Specifieswhethertheusermustspecifyanemailaddressasthepassword.Thisprohibitsblankpasswords.

Anonymous_NoUserIDDirective

Description: SetswhethertheuserIDfieldmaybeemptySyntax: Anonymous_NoUserIDOn|Off

Default: Anonymous_NoUserIDOff

WhensetOn,userscanleavetheuserID(andperhapsthepasswordfield)empty.ThiscanbeveryconvenientforMS-ExploreruserswhocanjusthitreturnorclickdirectlyontheOKbutton;whichseemsanaturalreaction.

Anonymous_VerifyEmailDirective

Description: Setswhethertocheckthepasswordfieldforacorrectlyformattedemailaddress

Syntax: Anonymous_VerifyEmailOn|Off

Default: Anonymous_VerifyEmailOff

WhensetOnthe'password'enteredischeckedforatleastone'@'anda'.'toencourageuserstoentervalidemailaddresses(seetheaboveAnonymous_LogEmail).

ApacheModulemod_auth_dbm

Description: ProvidesforuserauthenticationusingDBMfilesStatus: ExtensionModuleIdentifier: auth_dbm_moduleSourceFile: mod_auth_dbm.cCompatibility: Availableonlyinversionspriorto2.1

SummaryThismoduleprovidesforHTTPBasicAuthentication,wheretheusernamesandpasswordsarestoredinDBMtypedatabasefiles.Itisanalternativetotheplaintextpasswordfilesprovidedbymod_auth.

SeealsoAuthName

AuthType

Require

Satisfy

AuthDBMAuthoritativeDirective

Description: Setswhetherauthenticationandauthorizationwillbepassedontolowerlevelmodules

Syntax: AuthDBMAuthoritativeOn|Off

Default: AuthDBMAuthoritativeOn

Context: directory,.htaccessOverride: AuthConfigStatus: ExtensionModule: mod_auth_dbm

SettingtheAuthDBMAuthoritativedirectiveexplicitlytoOffallowsforbothauthenticationandauthorizationtobepassedontolowerlevelmodules(asdefinedinthemodules.cfiles)ifthereisnouserIDorrulematchingthesupplieduserID.IfthereisauserIDand/orrulespecified;theusualpasswordandaccesscheckswillbeappliedandafailurewillgivean"AuthenticationRequired"reply.

SoifauserIDappearsinthedatabaseofmorethanonemodule;orifavalidRequiredirectiveappliestomorethanonemodule;thenthefirstmodulewillverifythecredentials;andnoaccessispassedon;regardlessoftheAuthDBMAuthoritativesetting.

Acommonuseforthisisinconjunctionwithoneofthebasicauthmodules;suchasmod_auth.WhereasthisDBMmodulesuppliesthebulkoftheusercredentialchecking;afew(administrator)relatedaccessesfallthroughtoalowerlevelwithawellprotected.htpasswdfile.

Bydefault,controlisnotpassedonandanunknownuserIDorrulewillresultinan"AuthenticationRequired"reply.NotsettingitthuskeepsthesystemsecureandforcesanNCSAcompliantbehaviour.

Security:

Doconsidertheimplicationsofallowingausertoallowfall-throughinhis.htaccessfile;andverifythatthisisreallywhatyouwant;Generallyitiseasiertojustsecureasingle.htpasswdfile,thanitistosecureadatabasewhichmighthavemoreaccessinterfaces.

AuthDBMGroupFileDirective

Description: Setsthenameofthedatabasefilecontainingthelistofusergroupsforauthentication

Syntax: AuthDBMGroupFilefile-path

TheAuthDBMGroupFiledirectivesetsthenameofaDBMfilecontainingthelistofusergroupsforuserauthentication.File-pathistheabsolutepathtothegroupfile.

Thegroupfileiskeyedontheusername.Thevalueforauserisacomma-separatedlistofthegroupstowhichtheusersbelongs.Theremustbenowhitespacewithinthevalue,anditmustnevercontainanycolons.

Security:makesurethattheAuthDBMGroupFileisstoredoutsidethedocumenttreeoftheweb-server;donotputitinthedirectorythatitprotects.Otherwise,clientswillbeabletodownloadtheAuthDBMGroupFileunlessotherwiseprotected.

CombiningGroupandPasswordDBMfiles:Insomecasesitiseasiertomanageasingledatabasewhichcontainsboththepasswordandgroupdetailsforeachuser.Thissimplifiesanysupportprogramsthatneedtobewritten:theynowonlyhavetodealwithwritingtoandlockingasingleDBMfile.ThiscanbeaccomplishedbyfirstsettingthegroupandpasswordfilestopointtothesameDBM:

AuthDBMGroupFile/www/userbase

AuthDBMUserFile/www/userbase

ThekeyforthesingleDBMistheusername.Thevalueconsistsof

UnixCrypt-edPassword:ListofGroups[:(ignored)]

Thepasswordsectioncontainstheencryptedpasswordasbefore.Thisisfollowedbyacolonandthecommaseparatedlistofgroups.OtherdatamayoptionallybeleftintheDBMfileafteranothercolon;itisignoredbytheauthenticationmodule.Thisiswhatwww.telescope.orgusesforitscombinedpasswordandgroupdatabase.

AuthDBMTypeDirective

Description: Setsthetypeofdatabasefilethatisusedtostorepasswords

Syntax: AuthDBMType

default|SDBM|GDBM|NDBM|DB

Default: AuthDBMTypedefault

Context: directory,.htaccessOverride: AuthConfigStatus: ExtensionModule: mod_auth_dbmCompatibility: Availableinversion2.0.30andlater.

Setsthetypeofdatabasefilethatisusedtostorethepasswords.Thedefaultdatabasetypeisdeterminedatcompiletime.Theavailabilityofothertypesofdatabasefilesalsodependsoncompile-timesettings.

Itiscrucialthatwhateverprogramyouusetocreateyourpasswordfilesisconfiguredtousethesametypeofdatabase.

AuthDBMUserFileDirective

Description: Setsthenameofadatabasefilecontainingthelistofusersandpasswordsforauthentication

Syntax: AuthDBMUserFilefile-path

TheAuthDBMUserFiledirectivesetsthenameofaDBMfilecontainingthelistofusersandpasswordsforuserauthentication.File-pathistheabsolutepathtotheuserfile.

Theuserfileiskeyedontheusername.Thevalueforauseristheencryptedpassword,optionallyfollowedbyacolonandarbitrarydata.Thecolonandthedatafollowingitwillbeignoredbytheserver.

Security:

MakesurethattheAuthDBMUserFileisstoredoutsidethedocumenttreeoftheweb-server;donotputitinthedirectorythatitprotects.Otherwise,clientswillbeabletodownloadtheAuthDBMUserFile.

Importantcompatibilitynote:Theimplementationof"dbmopen"intheapachemodulesreadsthestringlengthofthehashedvaluesfromtheDBMdatastructures,ratherthanrelyinguponthestringbeingNULL-appended.Someapplications,suchastheNetscapewebserver,relyuponthestringbeingNULL-appended,soifyouarehavingtroubleusingDBMfilesinterchangeablybetweenapplicationsthismaybeapartoftheproblem.

AperlscriptcalleddbmmanageisincludedwithApache.This

programcanbeusedtocreateandupdateDBMformatpasswordfilesforusewiththismodule.

ApacheModulemod_auth_digest

Description: UserauthenticationusingMD5DigestAuthentication.

Status: ExperimentalModuleIdentifier: auth_digest_moduleSourceFile: mod_auth_digest.c

SummaryThismoduleimplementsHTTPDigestAuthentication.However,ithasnotbeenextensivelytestedandisthereforemarkedexperimental.

SeealsoAuthName

AuthType

Require

Satisfy

UsingDigestAuthentication

UsingMD5Digestauthenticationisverysimple.Simplysetupauthenticationnormally,usingAuthTypeDigestandAuthDigestFileinsteadofthenormalAuthTypeBasicandAuthUserFile;also,replaceanyAuthGroupFilewithAuthDigestGroupFile.ThenaddaAuthDigestDomaindirectivecontainingatleasttherootURI(s)forthisprotectionspace.

Appropriateuser(text)filescanbecreatedusingthehtdigesttool.

Example:<Location/private/>

AuthTypeDigest

AuthName"privatearea"

AuthDigestDomain/private/http://mirror.my.dom/private2/

AuthDigestFile/web/auth/.digest_pw

Requirevalid-user

</Location>

DigestauthenticationprovidesamoresecurepasswordsystemthanBasicauthentication,butonlyworkswithsupportingbrowsers.AsofNovember2002,themajorbrowsersthatsupportdigestauthenticationareOpera,MSInternetExplorer(failswhenusedwithaquerystring-see"WorkingwithMSInternetExplorer"belowforaworkaround),Amaya,MozillaandNetscapesinceversion7.Sincedigestauthenticationisnotaswidelyimplementedasbasicauthentication,youshoulduseitonlyincontrolledenvironments.

WorkingwithMSInternetExplorer

TheDigestauthenticationimplementationinpreviousInternetExplorerforWindowsversions(5and6)hadissues,namelythatGETrequestswithaquerystringwerenotRFCcompliant.Thereareafewwaystoworkaroundthisissue.

ThefirstwayistousePOSTrequestsinsteadofGETrequeststopassdatatoyourprogram.Thismethodisthesimplestapproachifyourapplicationcanworkwiththislimitation.

Sinceversion2.0.51ApachealsoprovidesaworkaroundintheAuthDigestEnableQueryStringHackenvironmentvariable.IfAuthDigestEnableQueryStringHackissetfortherequest,ApachewilltakestepstoworkaroundtheMSIEbugandremovethequerystringfromthedigestcomparison.Usingthismethodwouldlooksimilartothefollowing.

UsingDigestAuthenticationwithMSIE:BrowserMatch"MSIE"AuthDigestEnableQueryStringHack=On

ThisworkaroundisnotnecessaryforMSIE7,thoughenablingitdoesnotcauseanycompatibilityissuesorsignificantoverhead.

SeetheBrowserMatchdirectiveformoredetailsonconditionallysettingenvironmentvariables

AuthDigestAlgorithmDirective

Description: Selectsthealgorithmusedtocalculatethechallengeandresponsehasesindigestauthentication

Syntax: AuthDigestAlgorithmMD5|MD5-sess

Default: AuthDigestAlgorithmMD5

Context: directory,.htaccessOverride: AuthConfigStatus: ExperimentalModule: mod_auth_digest

TheAuthDigestAlgorithmdirectiveselectsthealgorithmusedtocalculatethechallengeandresponsehashes.

MD5-sessisnotcorrectlyimplementedyet.

AuthDigestDomainDirective

Description: URIsthatareinthesameprotectionspacefordigestauthentication

Syntax: AuthDigestDomainURI[URI]...

TheAuthDigestDomaindirectiveallowsyoutospecifyoneormoreURIswhichareinthesameprotectionspace(i.e.usethesamerealmandusername/passwordinfo).ThespecifiedURIsareprefixes,i.e.theclientwillassumethatallURIs"below"thesearealsoprotectedbythesameusername/password.TheURIsmaybeeitherabsoluteURIs(i.e.includingascheme,host,port,etc)orrelativeURIs.

Thisdirectiveshouldalwaysbespecifiedandcontainatleastthe(setof)rootURI(s)forthisspace.OmittingtodosowillcausetheclienttosendtheAuthorizationheaderforeveryrequestsenttothisserver.Apartfromincreasingthesizeoftherequest,itmayalsohaveadetrimentaleffectonperformanceifAuthDigestNcCheckison.

TheURIsspecifiedcanalsopointtodifferentservers,inwhichcaseclients(whichunderstandthis)willthenshareusername/passwordinfoacrossmultipleserverswithoutpromptingtheusereachtime.

AuthDigestFileDirective

Description: Locationofthetextfilecontainingthelistofusersandencodedpasswordsfordigestauthentication

Syntax: AuthDigestFilefile-path

TheAuthDigestFiledirectivesetsthenameofatextualfilecontainingthelistofusersandencodedpasswordsfordigestauthentication.File-pathistheabsolutepathtotheuserfile.

Thedigestfileusesaspecialformat.Filesinthisformatcanbecreatedusingthehtdigestutilityfoundinthesupport/subdirectoryoftheApachedistribution.

AuthDigestGroupFileDirective

Description: Nameofthetextfilecontainingthelistofgroupsfordigestauthentication

Syntax: AuthDigestGroupFilefile-path

TheAuthDigestGroupFiledirectivesetsthenameofatextualfilecontainingthelistofgroupsandtheirmembers(usernames).File-pathistheabsolutepathtothegroupfile.

Eachlineofthegroupfilecontainsagroupnamefollowedbyacolon,followedbythememberusernamesseparatedbyspaces.Example:

mygroup:bobjoeanne

Notethatsearchinglargetextfilesisveryinefficient.

Security:

MakesurethattheAuthGroupFileisstoredoutsidethedocumenttreeoftheweb-server;donotputitinthedirectorythatitprotects.Otherwise,clientsmaybeabletodownloadtheAuthGroupFile.

AuthDigestNcCheckDirective

Description: Enablesordisablescheckingofthenonce-countsentbytheserver

Syntax: AuthDigestNcCheckOn|Off

Default: AuthDigestNcCheckOff

Context: serverconfigStatus: ExperimentalModule: mod_auth_digest

Notimplementedyet.

AuthDigestNonceFormatDirective

Description: DetermineshowthenonceisgeneratedSyntax: AuthDigestNonceFormatformat

Notimplementedyet.

AuthDigestNonceLifetimeDirective

Description: HowlongtheservernonceisvalidSyntax: AuthDigestNonceLifetimeseconds

Default: AuthDigestNonceLifetime300

TheAuthDigestNonceLifetimedirectivecontrolshowlongtheservernonceisvalid.Whentheclientcontactstheserverusinganexpirednoncetheserverwillsendbacka401withstale=true.Ifsecondsisgreaterthan0thenitspecifiestheamountoftimeforwhichthenonceisvalid;thisshouldprobablyneverbesettolessthan10seconds.Ifsecondsislessthan0thenthenonceneverexpires.

AuthDigestQopDirective

Description: Determinesthequality-of-protectiontouseindigestauthentication

Syntax: AuthDigestQopnone|auth|auth-int

[auth|auth-int]

Default: AuthDigestQopauth

TheAuthDigestQopdirectivedeterminesthequality-of-protectiontouse.authwillonlydoauthentication(username/password);auth-intisauthenticationplusintegritychecking(anMD5hashoftheentityisalsocomputedandchecked);nonewillcausethemoduletousetheoldRFC-2069digestalgorithm(whichdoesnotincludeintegritychecking).Bothauthandauth-intmaybespecified,inwhichthecasethebrowserwillchoosewhichofthesetouse.noneshouldonlybeusedifthebrowserforsomereasondoesnotlikethechallengeitreceivesotherwise.

auth-intisnotimplementedyet.

AuthDigestShmemSizeDirective

Description: Theamountofsharedmemorytoallocateforkeepingtrackofclients

Syntax: AuthDigestShmemSizesize

Default: AuthDigestShmemSize1000

Context: serverconfigStatus: ExperimentalModule: mod_auth_digest

TheAuthDigestShmemSizedirectivedefinestheamountofsharedmemory,thatwillbeallocatedattheserverstartupforkeepingtrackofclients.Notethatthesharedmemorysegmentcannotbesetlessthanthespacethatisneccessaryfortrackingatleastoneclient.Thisvalueisdependantonyoursystem.Ifyouwanttofindouttheexactvalue,youmaysimplysetAuthDigestShmemSizetothevalueof0andreadtheerrormessageaftertryingtostarttheserver.

ThesizeisnormallyexpressedinBytes,butyoumayletthenumberfollowaKoranMtoexpressyourvalueasKBytesorMBytes.Forexample,thefollowingdirectivesareallequivalent:

AuthDigestShmemSize1048576

AuthDigestShmemSize1024K

AuthDigestShmemSize1M

ApacheModulemod_auth_ldap

Description: AllowsanLDAPdirectorytobeusedtostorethedatabaseforHTTPBasicauthentication.

Status: ExperimentalModuleIdentifier: auth_ldap_moduleSourceFile: mod_auth_ldap.cCompatibility: Availableinversion2.0.41andlater

Summarymod_auth_ldapsupportsthefollowingfeatures:

KnowntosupporttheOpenLDAPSDK(both1.xand2.x),NovellLDAPSDKandtheiPlanet(Netscape)SDK.ComplexauthorizationpoliciescanbeimplementedbyrepresentingthepolicywithLDAPfilters.SupportforMicrosoftFrontPageallowsFrontPageuserstocontrolaccesstotheirwebs,whileretainingLDAPforuserauthentication.UsesextensivecachingofLDAPoperationsviamod_ldap.SupportforLDAPoverSSL(requirestheNetscapeSDK)orTLS(requirestheOpenLDAP2.xSDKorNovellLDAPSDK).

Seealsomod_ldap

Contents

OperationTheAuthenticationPhaseTheAuthorizationPhase

TheRequireDirectivesRequirevalid-userRequireuserRequiregroupRequirednRequireldap-attribute

ExamplesUsingTLSUsingSSLUsingMicrosoftFrontPagewithmod_auth_ldap

HowItWorksCaveats

Operation

Therearetwophasesingrantingaccesstoauser.Thefirstphaseisauthentication,inwhichmod_auth_ldapverifiesthattheuser'scredentialsarevalid.Thisalsocalledthesearch/bindphase.Thesecondphaseisauthorization,inwhichmod_auth_ldapdeterminesiftheauthenticateduserisallowedaccesstotheresourceinquestion.Thisisalsoknownasthecomparephase.

TheAuthenticationPhaseDuringtheauthenticationphase,mod_auth_ldapsearchesforanentryinthedirectorythatmatchestheusernamethattheHTTPclientpasses.Ifasingleuniquematchisfound,thenmod_auth_ldapattemptstobindtothedirectoryserverusingtheDNoftheentryplusthepasswordprovidedbytheHTTPclient.Becauseitdoesasearch,thenabind,itisoftenreferredtoasthesearch/bindphase.Herearethestepstakenduringthesearch/bindphase.

1. GenerateasearchfilterbycombiningtheattributeandfilterprovidedintheAuthLDAPURLdirectivewiththeusernamepassedbytheHTTPclient.

2. Searchthedirectoryusingthegeneratedfilter.Ifthesearchdoesnotreturnexactlyoneentry,denyordeclineaccess.

3. FetchthedistinguishednameoftheentryretrievedfromthesearchandattempttobindtotheLDAPserverusingtheDNandthepasswordpassedbytheHTTPclient.Ifthebindisunsuccessful,denyordeclineaccess.

Thefollowingdirectivesareusedduringthesearch/bindphase

AuthLDAPURL SpecifiestheLDAPserver,thebaseDN,theattributetouseinthesearch,aswellastheextrasearchfilterto

use.AuthLDAPBindDN AnoptionalDNtobindwithduring

thesearchphase.AuthLDAPBindPassword Anoptionalpasswordtobindwith

duringthesearchphase.

TheAuthorizationPhaseDuringtheauthorizationphase,mod_auth_ldapattemptstodetermineiftheuserisauthorizedtoaccesstheresource.Manyofthesechecksrequiremod_auth_ldaptodoacompareoperationontheLDAPserver.Thisiswhythisphaseisoftenreferredtoasthecomparephase.mod_auth_ldapacceptsthefollowingRequiredirectivestodetermineifthecredentialsareacceptable:

GrantaccessifthereisaRequirevalid-userdirective.GrantaccessifthereisaRequireuserdirective,andtheusernameinthedirectivematchestheusernamepassedbytheclient.GrantaccessifthereisaRequiredndirective,andtheDNinthedirectivematchestheDNfetchedfromtheLDAPdirectory.GrantaccessifthereisaRequiregroupdirective,andtheDNfetchedfromtheLDAPdirectory(ortheusernamepassedbytheclient)occursintheLDAPgroup.GrantaccessifthereisaRequireldap-attributedirective,andtheattributefetchedfromtheLDAPdirectorymatchesthegivenvalue.otherwise,denyordeclineaccess

mod_auth_ldapusesthefollowingdirectivesduringthecomparephase:

AuthLDAPURL Theattributespecifiedinthe

URLisusedincompareoperationsfortheRequireuseroperation.

AuthLDAPCompareDNOnServer DeterminesthebehavioroftheRequiredndirective.

AuthLDAPGroupAttribute DeterminestheattributetouseforcomparisonsintheRequiregroupdirective.

AuthLDAPGroupAttributeIsDN SpecifieswhethertousetheuserDNortheusernamewhendoingcomparisonsfortheRequiregroupdirective.

TheRequireDirectives

Apache'sRequiredirectivesareusedduringtheauthorizationphasetoensurethatauserisallowedtoaccessaresource.

Requirevalid-userIfthisdirectiveexists,mod_auth_ldapgrantsaccesstoanyuserthathassuccessfullyauthenticatedduringthesearch/bindphase.

RequireuserTheRequireuserdirectivespecifieswhatusernamescanaccesstheresource.Oncemod_auth_ldaphasretrievedauniqueDNfromthedirectory,itdoesanLDAPcompareoperationusingtheusernamespecifiedintheRequireusertoseeifthatusernameispartofthejust-fetchedLDAPentry.Multipleuserscanbegrantedaccessbyputtingmultipleusernamesontheline,separatedwithspaces.Ifausernamehasaspaceinit,thenitmustbesurroundedwithdoublequotes.MultipleuserscanalsobegrantedaccessbyusingmultipleRequireuserdirectives,withoneuserperline.Forexample,withaAuthLDAPURLofldap://ldap/o=Airius?cn(i.e.,cnisusedforsearches),thefollowingRequiredirectivescouldbeusedtorestrictaccess:

Requireuser"BarbaraJenson"

Requireuser"FredUser"

Requireuser"JoeManager"

Becauseofthewaythatmod_auth_ldaphandlesthisdirective,BarbaraJensoncouldsignonasBarbaraJenson,BabsJensonoranyothercnthatshehasinherLDAPentry.OnlythesingleRequireuserlineisneededtosupportallvaluesoftheattributeintheuser'sentry.

IftheuidattributewasusedinsteadofthecnattributeintheURL

above,theabovethreelinescouldbecondensedto

Requireuserbjensonfuserjmanager

RequiregroupThisdirectivespecifiesanLDAPgroupwhosemembersareallowedaccess.IttakesthedistinguishednameoftheLDAPgroup.Note:Donotsurroundthegroupnamewithquotes.Forexample,assumethatthefollowingentryexistedintheLDAPdirectory:

dn:cn=Administrators,o=Airius

objectClass:groupOfUniqueNames

uniqueMember:cn=BarbaraJenson,o=Airius

uniqueMember:cn=FredUser,o=Airius

ThefollowingdirectivewouldgrantaccesstobothFredandBarbara:

Requiregroupcn=Administrators,o=Airius

BehaviorofthisdirectiveismodifiedbytheAuthLDAPGroupAttributeandAuthLDAPGroupAttributeIsDNdirectives.

RequirednTheRequiredndirectiveallowstheadministratortograntaccessbasedondistinguishednames.ItspecifiesaDNthatmustmatchforaccesstobegranted.IfthedistinguishednamethatwasretrievedfromthedirectoryservermatchesthedistinguishednameintheRequiredn,thenauthorizationisgranted.Note:donotsurroundthedistinguishednamewithquotes.

ThefollowingdirectivewouldgrantaccesstoaspecificDN:

Requiredncn=BarbaraJenson,o=Airius

BehaviorofthisdirectiveismodifiedbytheAuthLDAPCompareDNOnServerdirective.

Requireldap-attributeTheRequireldap-attributedirectiveallowstheadministratortograntaccessbasedonattributesoftheauthenticateduserintheLDAPdirectory.Iftheattributeinthedirectorymatchesthevaluegivenintheconfiguration,accessisgranted.

ThefollowingdirectivewouldgrantaccesstoanyonewiththeattributeemployeeType=active

Requireldap-attributeemployeeType=active

Multipleattribute/valuepairscanbespecifiedonthesamelineseparatedbyspacesortheycanbespecifiedinmultipleRequireldap-attributedirectives.Theeffectoflistingmultipleattribute/valuespairsisanORoperation.Accesswillbegrantedifanyofthelistedattributevaluesmatchthevalueofacorrespondingattributeintheuserobject.Ifthevalueoftheattributecontainsaspace,onlythevaluemustbewithindoublequotes.

Thefollowingdirectivewouldgrantaccesstoanyonewiththecityattributeequalto"SanJose"orstatusequalto"Active"

Requireldap-attributecity="SanJose"status=active

Examples

GrantaccesstoanyonewhoexistsintheLDAPdirectory,usingtheirUIDforsearches.

AuthLDAPURL"ldap://ldap1.airius.com:389/ou=People,

o=Airius?uid?sub?(objectClass=*)"

Requirevalid-user

Thenextexampleisthesameasabove;butwiththefieldsthathaveusefuldefaultsomitted.Also,notetheuseofaredundantLDAPserver.

AuthLDAPURL"ldap://ldap1.airius.com

ldap2.airius.com/ou=People,o=Airius"

Requirevalid-user

Thenextexampleissimilartothepreviousone,butisusesthecommonnameinsteadoftheUID.Notethatthiscouldbeproblematicalifmultiplepeopleinthedirectorysharethesamecn,becauseasearchoncnmustreturnexactlyoneentry.That'swhythisapproachisnotrecommended:it'sabetterideatochooseanattributethatisguaranteeduniqueinyourdirectory,suchasuid.

AuthLDAPURL"ldap://ldap.airius.com/ou=People,o=Airius?

Requirevalid-user

GrantaccesstoanybodyintheAdministratorsgroup.TheusersmustauthenticateusingtheirUID.

AuthLDAPURLldap://ldap.airius.com/o=Airius?uid

Requiregroupcn=Administrators,o=Airius

ThenextexampleassumesthateveryoneatAiriuswhocarriesanalphanumericpagerwillhaveanLDAPattributeof

qpagePagerID.Theexamplewillgrantaccessonlytopeople(authenticatedviatheirUID)whohavealphanumericpagers:

AuthLDAPURLldap://ldap.airius.com/o=Airius?uid??

(qpagePagerID=*)

Requirevalid-user

Thenextexampledemonstratesthepowerofusingfilterstoaccomplishcomplicatedadministrativerequirements.Withoutfilters,itwouldhavebeennecessarytocreateanewLDAPgroupandensurethatthegroup'smembersremainsynchronizedwiththepagerusers.Thisbecomestrivialwithfilters.Thegoalistograntaccesstoanyonewhohasafilter,plusgrantaccesstoJoeManager,whodoesn'thaveapager,butdoesneedtoaccessthesameresource:

AuthLDAPURLldap://ldap.airius.com/o=Airius?uid??(|

(qpagePagerID=*)(uid=jmanager))

Requirevalid-user

Thislastmaylookconfusingatfirst,soithelpstoevaluatewhatthesearchfilterwilllooklikebasedonwhoconnects,asshownbelow.ThetextinblueisthepartthatisfilledinusingtheattributespecifiedintheURL.ThetextinredisthepartthatisfilledinusingthefilterspecifiedintheURL.ThetextingreenisfilledinusingtheinformationthatisretrievedfromtheHTTPclient.IfFredUserconnectsasfuser,thefilterwouldlooklike

(&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))

Theabovesearchwillonlysucceediffuserhasapager.WhenJoeManagerconnectsasjmanager,thefilterlookslike

(&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))

Theabovesearchwillsucceedwhetherjmanagerhasapagerornot.

UsingTLS

TouseTLS,seethemod_ldapdirectivesLDAPTrustedCAandLDAPTrustedCAType.

UsingSSL

TouseSSL,seethemod_ldapdirectivesLDAPTrustedCAandLDAPTrustedCAType.

TospecifyasecureLDAPserver,useldaps://intheAuthLDAPURLdirective,insteadofldap://.

UsingMicrosoftFrontPagewithmod_auth_ldap

Normally,FrontPageusesFrontPage-web-specificuser/groupfiles(i.e.,themod_authmodule)tohandleallauthentication.Unfortunately,itisnotpossibletojustchangetoLDAPauthenticationbyaddingtheproperdirectives,becauseitwillbreakthePermissionsformsintheFrontPageclient,whichattempttomodifythestandardtext-basedauthorizationfiles.

OnceaFrontPagewebhasbeencreated,addingLDAPauthenticationtoitisamatterofaddingthefollowingdirectivestoevery.htaccessfilethatgetscreatedintheweb

AuthLDAPURL"theurl"

AuthLDAPAuthoritativeoff

AuthLDAPFrontPageHackon

AuthLDAPAuthoritativemustbeofftoallowmod_auth_ldaptodeclinegroupauthenticationsothatApachewillfallbacktofileauthenticationforcheckinggroupmembership.ThisallowstheFrontPage-managedgroupfiletobeused.

HowItWorksFrontPagerestrictsaccesstoawebbyaddingtheRequirevalid-userdirectivetothe.htaccessfiles.IfAuthLDAPFrontPageHackisnoton,theRequirevalid-userdirectivewillsucceedforanyuserwhoisvalidasfarasLDAPisconcerned.ThismeansthatanybodywhohasanentryintheLDAPdirectoryisconsideredavaliduser,whereasFrontPageconsidersonlythosepeopleinthelocaluserfiletobevalid.ThepurposeofthehackistoforceApachetoconsultthelocaluserfile(whichismanagedbyFrontPage)-insteadofLDAP-whenhandlingtheRequirevalid-userdirective.

Oncedirectiveshavebeenaddedasspecifiedabove,FrontPage

userswillbeabletoperformallmanagementoperationsfromtheFrontPageclient.

CaveatsWhenchoosingtheLDAPURL,theattributetouseforauthenticationshouldbesomethingthatwillalsobevalidforputtingintoamod_authuserfile.TheuserIDisidealforthis.WhenaddingusersviaFrontPage,FrontPageadministratorsshouldchooseusernamesthatalreadyexistintheLDAPdirectory(forobviousreasons).Also,thepasswordthattheadministratorentersintotheformisignored,sinceApachewillactuallybeauthenticatingagainstthepasswordintheLDAPdatabase,andnotagainstthepasswordinthelocaluserfile.Thiscouldcauseconfusionforwebadministrators.Apachemustbecompiledwithmod_authinordertouseFrontPagesupport.ThisisbecauseApachewillstillusethemod_authgroupfilefordeterminetheextentofauser'saccesstotheFrontPageweb.Thedirectivesmustbeputinthe.htaccessfiles.Attemptingtoputtheminside<Location>or<Directory>directiveswon'twork.Thisisbecausemod_auth_ldaphastobeabletograbtheAuthUserFiledirectivethatisfoundinFrontPage.htaccessfilessothatitknowswheretolookforthevaliduserlist.Ifthemod_auth_ldapdirectivesaren'tinthesame.htaccessfileastheFrontPagedirectives,thenthehackwon'twork,becausemod_auth_ldapwillnevergetachancetoprocessthe.htaccessfile,andwon'tbeabletofindtheFrontPage-manageduserfile.

AuthLDAPAuthoritativeDirective

Description: Preventotherauthenticationmodulesfromauthenticatingtheuserifthisonefails

Syntax: AuthLDAPAuthoritativeon|off

Default: AuthLDAPAuthoritativeon

Context: directory,.htaccessOverride: AuthConfigStatus: ExperimentalModule: mod_auth_ldap

Settooffifthismoduleshouldletotherauthenticationmodulesattempttoauthenticatetheuser,shouldauthenticationwiththismodulefail.ControlisonlypassedontolowermodulesifthereisnoDNorrulethatmatchesthesuppliedusername(aspassedbytheclient).

AuthLDAPBindDNDirective

Description: OptionalDNtouseinbindingtotheLDAPserverSyntax: AuthLDAPBindDNdistinguished-name

AnoptionalDNusedtobindtotheserverwhensearchingforentries.Ifnotprovided,mod_auth_ldapwilluseananonymousbind.

AuthLDAPBindPasswordDirective

Description: PasswordusedinconjuctionwiththebindDNSyntax: AuthLDAPBindPasswordpassword

AbindpasswordtouseinconjunctionwiththebindDN.Notethatthebindpasswordisprobablysensitivedata,andshouldbeproperlyprotected.YoushouldonlyusetheAuthLDAPBindDNandAuthLDAPBindPasswordifyouabsolutelyneedthemtosearchthedirectory.

AuthLDAPCharsetConfigDirective

Description: LanguagetocharsetconversionconfigurationfileSyntax: AuthLDAPCharsetConfigfile-path

Context: serverconfigStatus: ExperimentalModule: mod_auth_ldap

TheAuthLDAPCharsetConfigdirectivesetsthelocationofthelanguagetocharsetconversionconfigurationfile.File-pathisrelativetotheServerRoot.Thisfilespecifiesthelistoflanguageextensionstocharactersets.Mostadministratorsusetheprovidedcharset.convfile,whichassociatescommonlanguageextensionstocharactersets.

Thefilecontainslinesinthefollowingformat:

Language-Extensioncharset[Language-String]...

Thecaseoftheextensiondoesnotmatter.Blanklines,andlinesbeginningwithahashcharacter(#)areignored.

AuthLDAPCompareDNOnServerDirective

Description: UsetheLDAPservertocomparetheDNsSyntax: AuthLDAPCompareDNOnServeron|off

Default: AuthLDAPCompareDNOnServeron

Whenset,mod_auth_ldapwillusetheLDAPservertocomparetheDNs.ThisistheonlyfoolproofwaytocompareDNs.mod_auth_ldapwillsearchthedirectoryfortheDNspecifiedwiththeRequiredndirective,then,retrievetheDNandcompareitwiththeDNretrievedfromtheuserentry.Ifthisdirectiveisnotset,mod_auth_ldapsimplydoesastringcomparison.Itispossibletogetfalsenegativeswiththisapproach,butitismuchfaster.Notethemod_ldapcachecanspeedupDNcomparisoninmostsituations.

AuthLDAPDereferenceAliasesDirective

Description: Whenwillthemodulede-referencealiasesSyntax: AuthLDAPDereferenceAliases

never|searching|finding|always

Default: AuthLDAPDereferenceAliasesAlways

Thisdirectivespecifieswhenmod_auth_ldapwillde-referencealiasesduringLDAPoperations.Thedefaultisalways.

AuthLDAPEnabledDirective

Description: TurnonoroffLDAPauthenticationSyntax: AuthLDAPEnabledon|off

Default: AuthLDAPEnabledon

Settoofftodisablemod_auth_ldapincertaindirectories.Thisisusefulifyouhavemod_auth_ldapenabledatornearthetopofyourtree,butwanttodisableitcompletelyincertainlocations.

AuthLDAPFrontPageHackDirective

Description: AllowLDAPauthenticationtoworkwithMSFrontPage

Syntax: AuthLDAPFrontPageHackon|off

Default: AuthLDAPFrontPageHackoff

SeethesectiononusingMicrosoftFrontPagewithmod_auth_ldap.

AuthLDAPGroupAttributeDirective

Description: LDAPattributesusedtocheckforgroupmembership

Syntax: AuthLDAPGroupAttributeattribute

ThisdirectivespecifieswhichLDAPattributesareusedtocheckforgroupmembership.Multipleattributescanbeusedbyspecifyingthisdirectivemultipletimes.Ifnotspecified,thenmod_auth_ldapusesthememberanduniquememberattributes.

AuthLDAPGroupAttributeIsDNDirective

Description: UsetheDNoftheclientusernamewhencheckingforgroupmembership

Syntax: AuthLDAPGroupAttributeIsDNon|off

Default: AuthLDAPGroupAttributeIsDNon

Whenseton,thisdirectivesaystousethedistinguishednameoftheclientusernamewhencheckingforgroupmembership.Otherwise,theusernamewillbeused.Forexample,assumethattheclientsenttheusernamebjenson,whichcorrespondstotheLDAPDNcn=BabsJenson,o=Airius.Ifthisdirectiveisset,mod_auth_ldapwillcheckifthegrouphascn=BabsJenson,o=Airiusasamember.Ifthisdirectiveisnotset,thenmod_auth_ldapwillcheckifthegrouphasbjensonasamember.

AuthLDAPRemoteUserIsDNDirective

Description: UsetheDNoftheclientusernametosettheREMOTE_USERenvironmentvariable

Syntax: AuthLDAPRemoteUserIsDNon|off

Default: AuthLDAPRemoteUserIsDNoff

Ifthisdirectiveissettoon,thevalueoftheREMOTE_USERenvironmentvariablewillbesettothefulldistinguishednameoftheauthenticateduser,ratherthanjusttheusernamethatwaspassedbytheclient.Itisturnedoffbydefault.

AuthLDAPUrlDirective

Description: URLspecifyingtheLDAPsearchparametersSyntax: AuthLDAPUrlurl

AnRFC2255URLwhichspecifiestheLDAPsearchparameterstouse.ThesyntaxoftheURLis

ldap://host:port/basedn?attribute?scope?filter

ldapForregularldap,usethestringldap.ForsecureLDAP,useldapsinstead.SecureLDAPisonlyavailableifApachewaslinkedtoanLDAPlibrarywithSSLsupport.

host:portThename/portoftheldapserver(defaultstolocalhost:389forldap,andlocalhost:636forldaps).Tospecifymultiple,redundantLDAPservers,justlistallservers,separatedbyspaces.mod_auth_ldapwilltryconnectingtoeachserverinturn,untilitmakesasuccessfulconnection.

Onceaconnectionhasbeenmadetoaserver,thatconnectionremainsactiveforthelifeofthehttpdprocess,oruntiltheLDAPservergoesdown.

IftheLDAPservergoesdownandbreaksanexistingconnection,mod_auth_ldapwillattempttore-connect,startingwiththeprimaryserver,andtryingeachredundantserverinturn.Notethatthisisdifferentthanatrueround-

robinsearch.

basednTheDNofthebranchofthedirectorywhereallsearchesshouldstartfrom.Attheveryleast,thismustbethetopofyourdirectorytree,butcouldalsospecifyasubtreeinthedirectory.

attributeTheattributetosearchfor.AlthoughRFC2255allowsacomma-separatedlistofattributes,onlythefirstattributewillbeused,nomatterhowmanyareprovided.Ifnoattributesareprovided,thedefaultistouseuid.It'sagoodideatochooseanattributethatwillbeuniqueacrossallentriesinthesubtreeyouwillbeusing.

scopeThescopeofthesearch.Canbeeitheroneorsub.NotethatascopeofbaseisalsosupportedbyRFC2255,butisnotsupportedbythismodule.Ifthescopeisnotprovided,orifbasescopeisspecified,thedefaultistouseascopeofsub.

filterAvalidLDAPsearchfilter.Ifnotprovided,defaultsto(objectClass=*),whichwillsearchforallobjectsinthetree.Filtersarelimitedtoapproximately8000characters(thedefinitionofMAX_STRING_LENintheApachesourcecode).Thisshouldbethansufficientforanyapplication.

Whendoingsearches,theattribute,filterandusernamepassedbytheHTTPclientarecombinedtocreateasearchfilterthatlookslike(&(filter)(attribute=username)).

Forexample,consideranURLofldap://ldap.airius.com/o=Airius?cn?sub?

(posixid=*).Whenaclientattemptstoconnectusinga

usernameofBabsJenson,theresultingsearchfilterwillbe(&(posixid=*)(cn=BabsJenson)).

SeeaboveforexamplesofAuthLDAPURLURLs.

||FAQ||

Apachemod_autoindex

: Unix ls Win32dir

: Base: autoindex_module: mod_autoindex.c

index.html DirectoryIndex

AddIconByType

Options+Indexes Options

FancyIndexing IndexOptionsIndexOptions SuppressColumnSorting

"Size" -

Autoindex

Apache2.0.23

C=NC=MC=SC=D

O=AO=D

F=0 (FancyIndex)F=1FancyIndexF=2HTML FancyIndexV=0V=1

P=pattern pattern

"P(P)" IndexIgnoremod_autoindex()

HEADER.html

<formaction=""method="get">

Showmea<selectname="F">

<optionvalue="0">Plainlist</option>

<optionvalue="1"selected="selected">Fancylist</option>

<optionvalue="2">Tablelist</option>

</select>

Sortedby<selectname="C">

<optionvalue="N"selected="selected">Name</option>

<optionvalue="M">DateModified</option>

<optionvalue="S">Size</option>

<optionvalue="D">Description</option>

</select>

<selectname="O">

<optionvalue="A"selected="selected">Ascending</option>

<optionvalue="D">Descending</option>

</select>

<selectname="V">

<optionvalue="0"selected="selected">inNormal

order</option>

<optionvalue="1">inVersionorder</option>

</select>

Matching<inputtype="text"name="P"value="*"/>

<inputtype="submit"name="X"value="Go"/>

</form>

AddAlt

: : AddAltstringfile[file]...

: ,,,.htaccess: Indexes: Base: mod_autoindex

AddAlt FancyIndexing (" ')

AddAlt"PDFfile"*.pdf

AddAltCompressed*.gz*.zip*.Z

AddAltByEncoding

: MIME: AddAltByEncodingstringMIME-encoding[MIME-

encoding]...

AddAltByEncoding FancyIndexingencoding x-compress string( " ')

AddAltByEncodinggzipx-gzip

AddAltByType

: MIME: AddAltByTypestringMIME-type[MIME-type]...

AddAltByType FancyIndexingtext/html string( " ')

AddAltByType'plaintext'text/plain

AddDescription

:: AddDescriptionstringfile[file]...

FancyIndexing file

AddDescription"TheplanetMars"/web/pics/mars.gif

23 IndexOptionsSuppressIcon

IndexOptionsSuppressSize7 IndexOptions

SuppressLastModified19

AddDescription HTML

AddIcon

:: AddIconiconname[name]...

FancyIndexing name(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: AddIconByEncodingiconMIME-encoding[MIME-

encoding]...

FancyIndexing icon(alttext,url) alttext

MIME-encoding

AddIconByEncoding/icons/compress.xbmx-compress

AddIconByType

: MIME: AddIconByTypeiconMIME-type[MIME-type]...

FancyIndexing icon(alttext,url) alttext

MIME-type

AddIconByType(IMG,/icons/image.xbm)image/*

DefaultIcon

: : DefaultIconurl-path

FancyIndexing

DefaultIcon/icon/unknown.xbm

HeaderName

:: HeaderNamefilename

HeaderName

HeaderNameHEADER.html

HeaderName ReadmeName filenameURIfilename DocumentRoot

HeaderName/include/HEADER.html

filename " text/*"(text/html,text/plain CGI

AddTypetext/html.cgi

OptionsMultiViews filenametext/html optionsIncludes IncludesNOEXEC

(mod_include)

HeaderName HTML(<html>,<head>,IndexOptions+SuppressHTMLPreamble

IndexIgnore

: : IndexIgnorefile[file]...

IndexIgnore ()

IndexIgnoreREADME.htaccess*.bak*~

IndexOptions

:: IndexOptions[+|-]option[[+|-]option]...

IndexOptions option:

DescriptionWidth=[n|*](2.0.23)DescriptionWidth-DescriptionWidth() mod_autoindexDescriptionWidth=n nDescriptionWidth=* AddDescription

FancyIndexing

FoldersFirst(2.0.23) Zed Beta Gamma

HTMLTable( Apache2.0.23)FancyIndexing

IconsAreLinksFancyIndexing

IconHeight[=pixels]IconWidth Apache

IconWidth[=pixels]IconHeight

Apache

IgnoreCasegamma)

IgnoreClient mod_autoindex SuppressColumnSorting)

NameWidth=[n|*]NameWidth-NameWidth() mod_autoindexNameWidth=n nNameWidth=*

ScanHTMLTitlesFancyIndexing HTMLhttpd title CPUdisk

SuppressColumnSortingApache FancyIndexing2.0.23 IgnoreClient

SuppressDescriptionFancyIndexing AddDescription DescriptionWidth

SuppressHTMLPreamble HeaderName HTML SuppressHTMLPreamble

SuppressIcon(Apache2.0.23 )FancyIndexing SuppressIcon

HTML3.2 HTML3.2(FancyIndexing)

SuppressLastModifiedFancyIndexing

SuppressRules(Apache2.0.23)( hr) SuppressIcon SuppressRulesHTML3.2 HTML3.2(FancyIndexing)

SuppressSizeFancyIndexing

TrackModified(Apache2.0.23)HTTP ETagOS2JFSWin32NTFS OS2Win32FAT HEAD

VersionSort(Apache2.0a3)VersionSort

:foo-1.7

foo-1.7.2

foo-1.7.12

foo-1.8.2

foo-1.8.2a

foo-1.12

foo-1.001

foo-1.002

foo-1.030

foo-1.04

XHTML(Apache2.0.49)XHTML mod_autoindexHTML3.2XHTML1.0

IndexOptions

Apache1.3.3 IndexOptions

IndexOptions

IndexOptionsHTMLTable

IndexOptionsSuppressColumnsorting

</Directory>

IndexOptionsHTMLTableSuppressColumnsorting

('+''-' )

'+''-' IndexOptions

IndexOptions+ScanHTMLTitles-IconsAreLinksFancyIndexing

IndexOptions+SuppressSize

IndexOptionsFancyIndexing+SuppressSize

FancyIndexing

IndexOptions

IndexOrderDefault

:: IndexOrderDefaultAscending|Descending

Name|Date|Size|Description

: IndexOrderDefaultAscendingName

IndexOrderDefault FancyIndexing IndexOrderDefault

IndexOrderDefaultName,Date,Size Description

SuppressColumnSorting

||FAQ||

ReadmeName

:: ReadmeNamefilename

ReadmeName DocumentRoot

ReadmeNameFOOTER.html

2ReadmeName/include/FOOTER.html

HeaderName

ApacheModulemod_cache

Description: ContentcachekeyedtoURIs.Status: ExperimentalModuleIdentifier: cache_moduleSourceFile: mod_cache.c

Summary

Thismoduleisexperimental.Documentationisstillunderdevelopment...

mod_cacheimplementsanRFC2616compliantHTTPcontentcachethatcanbeusedtocacheeitherlocalorproxiedcontent.mod_cacherequirestheservicesofoneormorestoragemanagementmodules.TwostoragemanagementmodulesareincludedinthebaseApachedistribution:

mod_disk_cache

implementsadiskbasedstoragemanager.

mod_mem_cache

implementsamemorybasedstoragemanager.mod_mem_cachecanbeconfiguredtooperateintwomodes:cachingopenfiledescriptorsorcachingobjectsinheapstorage.mod_mem_cachecanbeusedtocachelocallygeneratedcontentortocachebackendservercontentformod_proxywhenconfiguredusingProxyPass(akareverseproxy)

ContentisstoredinandretrievedfromthecacheusingURIbasedkeys.Contentwithaccessprotectionisnotcached.

RelatedModulesandDirectives

RelatedModules RelatedDirectivesmod_disk_cache

mod_mem_cache

CacheRoot

CacheSize

CacheGcInterval

CacheDirLevels

CacheDirLength

CacheExpiryCheck

CacheMinFileSize

CacheMaxFileSize

CacheTimeMargin

CacheGcDaily

CacheGcUnused

CacheGcClean

CacheGcMemUsage

MCacheSize

MCacheMaxObjectCount

MCacheMinObjectSize

MCacheMaxObjectSize

MCacheRemovalAlgorithm

MCacheMaxStreamingBuffer

SampleConfiguration

Samplehttpd.conf#

#SampleCacheConfiguration

LoadModulecache_modulemodules/mod_cache.so

<IfModulemod_cache.c>

#LoadModuledisk_cache_modulemodules/mod_disk_cache.so

<IfModulemod_disk_cache.c>

CacheRootc:/cacheroot

CacheSize256

CacheEnabledisk/

CacheDirLevels5

CacheDirLength3

</IfModule>

LoadModulemem_cache_modulemodules/mod_mem_cache.so

<IfModulemod_mem_cache.c>

CacheEnablemem/

MCacheSize4096

MCacheMaxObjectCount100

MCacheMinObjectSize1

MCacheMaxObjectSize2048

</IfModule>

CacheDefaultExpireDirective

Description: Thedefaultdurationtocacheadocumentwhennoexpirydateisspecified.

Syntax: CacheDefaultExpireseconds

Default: CacheDefaultExpire3600(onehour)

Context: serverconfig,virtualhostStatus: ExperimentalModule: mod_cache

TheCacheDefaultExpiredirectivespecifiesadefaulttime,inseconds,tocacheadocumentifneitheranexpirydatenorlast-modifieddateareprovidedwiththedocument.ThevaluespecifiedwiththeCacheMaxExpiredirectivedoesnotoverridethissetting.

CacheDefaultExpire86400

CacheDisableDirective

Description: DisablecachingofspecifiedURLsSyntax: CacheDisableurl-string

TheCacheDisabledirectiveinstructsmod_cachetonotcacheurlsatorbelowurl-string.

ExampleCacheDisable/local_files

CacheEnableDirective

Description: EnablecachingofspecifiedURLsusingaspecifiedstoragemanager

Syntax: CacheEnablecache_typeurl-string

TheCacheEnabledirectiveinstructsmod_cachetocacheurlsatorbelowurl-string.Thecachestoragemanagerisspecifiedwiththecache_typeargument.cache_typememinstructsmod_cachetousethememorybasedstoragemanagerimplementedbymod_mem_cache.cache_typediskinstructsmod_cachetousethediskbasedstoragemanagerimplementedbymod_disk_cache.cache_typefdinstructsmod_cachetousethefiledescriptorcacheimplementedbymod_mem_cache.

IntheeventthattheURLspaceoverlapsbetweendifferentCacheEnabledirectives(asintheexamplebelow),eachpossiblestoragemanagerwillberununtilthefirstonethatactuallyprocessestherequest.TheorderinwhichthestoragemanagersarerunisdeterminedbytheorderoftheCacheEnabledirectivesintheconfigurationfile.

CacheEnablemem/manual

CacheEnablefd/images

CacheEnabledisk/

CacheForceCompletionDirective

Description: Percentageofdocumentserved,afterwhichtheserverwillcompletecachingthefileeveniftherequestiscancelled.

Syntax: CacheForceCompletionPercentage

Default: CacheForceCompletion60

Ordinarily,ifarequestiscancelledwhiletheresponseisbeingcachedanddeliveredtotheclienttheprocessingoftheresponsewillstopandthecacheentrywillberemoved.TheCacheForceCompletiondirectivespecifiesathresholdbeyondwhichthedocumentwillcontinuetobecachedtocompletion,eveniftherequestiscancelled.

Thethresholdisapercentagespecifiedasavaluebetween1and100.Avalueof0specifiesthatthedefaultbeused.Avalueof100willonlycachedocumentsthatareservedintheirentirety.Avaluebetween60and90isrecommended.

CacheForceCompletion80

Note:Thisfeatureiscurrentlynotimplemented.

CacheIgnoreCacheControlDirective

Description: Ignorethefactthattheclientrequestedthecontentnotbecached.

Syntax: CacheIgnoreCacheControlOn|Off

Default: CacheIgnoreCacheControlOff

Ordinarily,documentswithno-cacheorno-storeheadervalueswillnotbestoredinthecache.TheCacheIgnoreCacheControldirectiveallowsthisbehaviortobeoverridden.CacheIgnoreCacheControlOntellstheservertoattempttocachethedocumentevenifitcontainsno-cacheorno-storeheadervalues.Documentsrequiringauthorizationwillneverbecached.

CacheIgnoreCacheControlOn

CacheIgnoreHeadersDirective

Description: DonotstorethegivenHTTPheader(s)inthecache.

Syntax: CacheIgnoreHeadersheader-string

[header-string]...

Default: CacheIgnoreHeadersNone

AccordingtoRFC2616,hop-by-hopHTTPheadersarenotstoredinthecache.ThefollowingHTTPheadersarehop-by-hopheadersandthusdonotgetstoredinthecacheinanycaseregardlessofthesettingofCacheIgnoreHeaders:

Connection

Keep-Alive

Proxy-Authenticate

Proxy-Authorization

Trailers

Transfer-Encoding

Upgrade

CacheIgnoreHeadersspecifiesadditionalHTTPheadersthatshouldnottobestoredinthecache.Forexample,itmakessenseinsomecasestopreventcookiesfrombeingstoredinthecache.

CacheIgnoreHeaderstakesaspaceseparatedlistofHTTPheadersthatshouldnotbestoredinthecache.Ifonlyhop-by-hopheadersnotshouldbestoredinthecache(theRFC2616compliantbehaviour),CacheIgnoreHeaderscanbesettoNone.

Example1CacheIgnoreHeadersSet-Cookie

Example2CacheIgnoreHeadersNone

Warning:IfheaderslikeExpireswhichareneededforpropercachemanagementarenotstoredduetoaCacheIgnoreHeaderssetting,thebehaviourofmod_cacheisundefined.

CacheIgnoreNoLastModDirective

Description: IgnorethefactthataresponsehasnoLastModifiedheader.

Syntax: CacheIgnoreNoLastModOn|Off

Default: CacheIgnoreNoLastModOff

Ordinarily,documentswithoutalast-modifieddatearenotcached.Undersomecircumstancesthelast-modifieddateisremoved(duringmod_includeprocessingforexample)ornotprovidedatall.TheCacheIgnoreNoLastModdirectiveprovidesawaytospecifythatdocumentswithoutlast-modifieddatesshouldbeconsideredforcaching,evenwithoutalast-modifieddate.Ifneitheralast-modifieddatenoranexpirydateareprovidedwiththedocumentthenthevaluespecifiedbytheCacheDefaultExpiredirectivewillbeusedtogenerateanexpirationdate.

CacheIgnoreNoLastModOn

CacheLastModifiedFactorDirective

Description: ThefactorusedtocomputeanexpirydatebasedontheLastModifieddate.

Syntax: CacheLastModifiedFactorfloat

Default: CacheLastModifiedFactor0.1

Intheeventthatadocumentdoesnotprovideanexpirydatebutdoesprovidealast-modifieddate,anexpirydatecanbecalculatedbasedonthetimesincethedocumentwaslastmodified.TheCacheLastModifiedFactordirectivespecifiesafactortobeusedinthegenerationofthisexpirydateaccordingtothefollowingformula:expiry-period=time-since-last-modified-date*factorexpiry-date=current-date

+expiry-periodForexample,ifthedocumentwaslastmodified10hoursago,andfactoris0.1thentheexpiry-periodwillbesetto10*0.1=1hour.Ifthecurrenttimewas3:00pmthenthecomputedexpiry-datewouldbe3:00pm+1hour=4:00pm.Iftheexpiry-periodwouldbelongerthanthatsetbyCacheMaxExpire,thenthelattertakesprecedence.

CacheLastModifiedFactor0.5

CacheMaxExpireDirective

Description: Themaximumtimeinsecondstocacheadocument

Syntax: CacheMaxExpireseconds

Default: CacheMaxExpire86400(oneday)

TheCacheMaxExpiredirectivespecifiesthemaximumnumberofsecondsforwhichcachableHTTPdocumentswillberetainedwithoutcheckingtheoriginserver.Thus,documentswillbeoutofdateatmostthisnumberofseconds.Thismaximumvalueisenforcedevenifanexpirydatewassuppliedwiththedocument.

CacheMaxExpire604800

ApacheModulemod_cern_meta

Description: CERNhttpdmetafilesemanticsStatus: ExtensionModuleIdentifier: cern_meta_moduleSourceFile: mod_cern_meta.c

SummaryEmulatetheCERNHTTPDMetafilesemantics.MetafilesareHTTPheadersthatcanbeoutputinadditiontothenormalrangeofheadersforeachfileaccessed.TheyappearratherliketheApache.asisfiles,andareabletoprovideacrudewayofinfluencingtheExpires:header,aswellasprovidingothercuriosities.Therearemanywaystomanagemetainformation,thisonewaschosenbecausethereisalreadyalargenumberofCERNuserswhocanexploitthismodule.

MoreinformationontheCERNmetafilesemanticsisavailable.

Seealsomod_headers

mod_asis

MetaDirDirective

Description: NameofthedirectorytofindCERN-stylemetainformationfiles

Syntax: MetaDirdirectory

Default: MetaDir.web

Context: serverconfig,virtualhost,directory,.htaccessOverride: IndexesStatus: ExtensionModule: mod_cern_meta

SpecifiesthenameofthedirectoryinwhichApachecanfindmetainformationfiles.Thedirectoryisusuallya'hidden'subdirectoryofthedirectorythatcontainsthefilebeingaccessed.Setto"."tolookinthesamedirectoryasthefile:

MetaDir.

Or,tosetittoasubdirectoryofthedirectorycontainingthefiles:

MetaDir.meta

MetaFilesDirective

Description: ActivatesCERNmeta-fileprocessingSyntax: MetaFileson|off

Default: MetaFilesoff

Turnson/offMetafileprocessingonaper-directorybasis.

MetaSuffixDirective

Description: FilenamesuffixforthefilecontaingCERN-stylemetainformation

Syntax: MetaSuffixsuffix

Default: MetaSuffix.meta

Specifiesthefilenamesuffixforthefilecontainingthemetainformation.Forexample,thedefaultvaluesforthetwodirectiveswillcausearequesttoDOCUMENT_ROOT/somedir/index.htmltolookinDOCUMENT_ROOT/somedir/.web/index.html.metaandwilluseitscontentstogenerateadditionalMIMEheaderinformation.

Example:MetaSuffix.meta

||FAQ||

Apachemod_cgi

: CGI: Base: cgi_module: mod_cgi.c

Mime application/x-httpd-cgi cgi-script

(Apache1.1) CGI ScriptAlias

CGI DOCUMENT_ROOT

ApacheCGI CGI

UnixMPM mod_cgid

AcceptPathInfo

Options

ScriptAlias

AddHandler

CGIIDCGI

CGI CGI

PATH_INFO AcceptPathInfo off

mod_cgi (URI /more/path/info

NOTFOUND AcceptPathInfo

REMOTE_HOSTHostnameLookups on(off) DNS

REMOTE_IDENTIdentityCheck on ident

REMOTE_USERCGI

CGI ()

CGICGI CGICGI

%%[time]request-line

%%HTTP-statusCGI-script-filename

CGI 2:

%%error

error-message

%request

()POSTPUT

%response

%stdout

%stderr

( %stdout%stderr)

ScriptLog

: CGI: ScriptLogfile-path

: ,: Base: mod_cgi,mod_cgid

ScriptLogCGIServerRoot

ScriptLoglogs/cgi_log

ScriptLogBuffer

: PUTPOST: ScriptLogBufferbytes

: ScriptLogBuffer1024

PUTPOST

||FAQ||

ScriptLogLength

: CGI: ScriptLogLengthbytes

: ScriptLogLength10385760

ScriptLogLengthCGI CGI

||FAQ||

Apachemod_cgid

: CGICGI

: Base: cgid_module: mod_cgid.c: Unix

ScriptSock mod_cgid mod_cgiCGI mod_cgi

Unix fork unix

MPM mod_cgiCGI

mod_cgi

||FAQ||

ScriptSock

: CGI: ScriptSockfile-path

: ScriptSocklogs/cgisock

: ,: Base: mod_cgid

CGI Apache(root)

ScriptSock/var/run/cgid.sock

ApacheModulemod_charset_lite

Description: SpecifycharactersettranslationorrecodingStatus: ExperimentalModuleIdentifier: charset_lite_moduleSourceFile: mod_charset_lite.c

SummaryThisisanexperimentalmoduleandshouldbeusedwithcare.Experimentwithyourmod_charset_liteconfigurationtoensurethatitperformsthedesiredfunction.

mod_charset_liteallowstheadministratortospecifythesourcecharactersetofobjectsaswellasthecharactersettheyshouldbetranslatedintobeforesendingtotheclient.mod_charset_litedoesnottranslatethedataitselfbutinsteadtellsApachewhattranslationtoperform.mod_charset_liteisapplicabletoEBCDICandASCIIhostenvironments.InanEBCDICenvironment,ApachenormallytranslatestextcontentfromthecodepageoftheApacheprocesslocaletoISO-8859-1.mod_charset_litecanbeusedtospecifythatadifferenttranslationistobeperformed.InanASCIIenvironment,Apachenormallyperformsnotranslation,somod_charset_liteisneededinorderforanytranslationtotakeplace.

ThismoduleprovidesasmallsubsetofconfigurationmechanismsimplementedbyRussianApacheanditsassociatedmod_charset.

CommonProblems

InvalidcharactersetnamesThecharactersetnameparametersofCharsetSourceEncandCharsetDefaultmustbeacceptabletothetranslationmechanismusedbyAPRonthesystemwheremod_charset_liteisdeployed.Thesecharactersetnamesarenotstandardizedandareusuallynotthesameasthecorrespondingvaluesusedinhttpheaders.Currently,APRcanonlyuseiconv(3),soyoucaneasilytestyourcharactersetnamesusingtheiconv(1)program,asfollows:

iconv-fcharsetsourceenc-value-tcharsetdefault-value

MismatchbetweencharactersetofcontentandtranslationrulesIfthetranslationrulesdon'tmakesenseforthecontent,translationcanfailinvariousways,including:

Thetranslationmechanismmayreturnabadreturncode,andtheconnectionwillbeaborted.Thetranslationmechanismmaysilentlyplacespecialcharacters(e.g.,questionmarks)intheoutputbufferwhenitcannottranslatetheinputbuffer.

CharsetDefaultDirective

Description: CharsettotranslateintoSyntax: CharsetDefaultcharset

Context: serverconfig,virtualhost,directory,.htaccessOverride: FileInfoStatus: ExperimentalModule: mod_charset_lite

TheCharsetDefaultdirectivespecifiesthecharsetthatcontentintheassociatedcontainershouldbetranslatedto.

ThevalueofthecharsetargumentmustbeacceptedasavalidcharactersetnamebythecharactersetsupportinAPR.Generally,thismeansthatitmustbesupportedbyiconv.

Example<Directory/export/home/trawick/apacheinst/htdocs/convert>

CharsetSourceEncUTF-16BE

CharsetDefaultISO-8859-1

</Directory>

CharsetOptionsDirective

Description: ConfigurescharsettranslationbehaviorSyntax: CharsetOptionsoption[option]...

Default: CharsetOptionsDebugLevel=0

NoImplicitAdd

TheCharsetOptionsdirectiveconfigurescertainbehaviorsofmod_charset_lite.Optioncanbeoneof

DebugLevel=n

TheDebugLevelkeywordallowsyoutospecifythelevelofdebugmessagesgeneratedbymod_charset_lite.Bydefault,nomessagesaregenerated.ThisisequivalenttoDebugLevel=0.Withhighernumbers,moredebugmessagesaregenerated,andserverperformancewillbedegraded.TheactualmeaningsofthenumericvaluesaredescribedwiththedefinitionsoftheDBGLVL_constantsnearthebeginningofmod_charset_lite.c.

ImplicitAdd|NoImplicitAdd

TheImplicitAddkeywordspecifiesthatmod_charset_liteshouldimplicitlyinsertitsfilterwhentheconfigurationspecifiesthatthecharactersetofcontentshouldbetranslated.IfthefilterchainisexplicitlyconfiguredusingtheAddOutputFilterdirective,NoImplicitAddshouldbespecifiedsothatmod_charset_litedoesn'tadditsfilter.

CharsetSourceEncDirective

Description: SourcecharsetoffilesSyntax: CharsetSourceEnccharset

TheCharsetSourceEncdirectivespecifiesthesourcecharsetoffilesintheassociatedcontainer.

ThevalueofthecharsetargumentmustbeacceptedasavalidcharactersetnamebythecharactersetsupportinAPR.Generally,thismeansthatitmustbesupportedbyiconv.

Example<Directory/export/home/trawick/apacheinst/htdocs/convert>

CharsetSourceEncUTF-16BE

CharsetDefaultISO-8859-1

</Directory>

ThecharactersetnamesinthisexampleworkwiththeiconvtranslationsupportinSolaris8.

||FAQ||

Apachemod_dav

: (WebDAV)

: Extension: dav_module: mod_dav.c

12 WebDAV('')

DavLockDB

LimitXMLRequestBody

WebDAVResources

EnablingWebDAV

mod_dav httpd.conf:

DAVDAV

DAV DavLockDB httd.conf

DavLockDB/usr/local/apache2/var/DavLock

Apache User

<Limit> <Location>DAVLimitXMLRequestBody

DavLockDB/usr/local/apache2/var/DavLock

AuthTypeBasic

AuthNameDAV

AuthUserFileuser.passwd

requireuseradmin

</LimitExcept>

</Location>

mod_davGregStein Apache1.3mod_dav

DAV HTTPWebDAV SSL

mod_dav ApacheGroup )

mod_dav LimitXMLRequestBody

DavDepthInfinity PROPFINDDAV

mod_dav (PHPCGI)URL DAV

Alias/phparea/home/gstein/php_files

Alias/php-source/home/gstein/php_files

ForceTypetext/plain

</Location>

http://example.com/phpareaPHPhttp://example.com/php-sourceDAV

: WebDAVHTTP: DavOn|Off|provider-name

: DavOff

:: Extension: mod_dav

WebDAVHTTP

</Location>

On mod_dav_fs filesystem

WebDAV

DavDepthInfinity

: PROPFIND,Depth:Infinity: DavDepthInfinityon|off

: DavDepthInfinityoff

: ,,: Extension: mod_dav

'Depth:Infinity' PROPFINDdenial-of-service

||FAQ||

DavMinTimeout

: DAV: DavMinTimeoutseconds

: DavMinTimeout0

: ,,: Extension: mod_dav

DavMinTimeout

DavMinTimeout600

</Location>

||FAQ||

Apachemod_dav_fs

: mod_dav: Extension: dav_fs_module: mod_dav_fs.c

mod_dav mod_dav

Davfilesystem

filesystem mod_dav

mod_dav

||FAQ||

DavLockDB

: DAV: DavLockDBfile-path

: ,: Extension: mod_dav_fs

DavLockDB

DavLockDBlogs/DavLock

||FAQ||

Apachemod_deflate

:: Extension: deflate_module: mod_deflate.c

mod_deflate DEFLATE

Filters

AddOutputFilterByTypeDEFLATEtext/htmltext/plaintext/xml

#Insertfilter

SetOutputFilterDEFLATE

#Netscape4.xhassomeproblems...

BrowserMatch^Mozilla/4gzip-only-text/html

#Netscape4.06-4.08havesomemoreproblems

BrowserMatch^Mozilla/4\.0[678]no-gzip

#MSIEmasqueradesasNetscape,butitisfine

#BrowserMatch\bMSIE!no-gzip!gzip-only-text/html

#NOTE:Duetoabuginmod_setenvifuptoApache2.0.48

#theaboveregexwon'twork.Youcanusethefollowing

#workaroundtogetthedesiredeffect:

BrowserMatch\bMSI[E]!no-gzip!gzip-only-text/html

#Don'tcompressimages

SetEnvIfNoCaseRequest_URI\

\.(?:gif|jpe?g|png)$no-gzipdont-vary

#Makesureproxiesdon'tdeliverthewrongcontent

HeaderappendVaryUser-Agentenv=!dont-vary

</Location>

OutputCompression DEFLATE

SetOutputFilterDEFLATE

MIME AddOutputFilterByType

<Directory"/your-server-root/manual">

AddOutputFilterByTypeDEFLATEtext/html

</Directory>

BrowserMatch

only-text/html

BrowserMatch^Mozilla/4gzip-only-text/html

BrowserMatch^Mozilla/4\.0[678]no-gzip

BrowserMatch\bMSIE!no-gzip!gzip-only-text/html

User-AgentNetscapeNavigator 4.x 4.06,4.07,4.08html

3 BrowserMatch"Mozilla/4" User-Agent

DEFLATEPHPSSIRESOURCE

mod_deflategzip AddInputFilter DEFLATE

SetInputFilterDEFLATE

</Location>

Content-Encoding:gzip

Content-Length

Content-Length Content-Length

mod_deflate Vary:Accept-EncodingHTTPAccept-Encoding

User-Agent VaryDEFLATE

HeaderappendVaryUser-Agent

( HTTP) Vary *

HeadersetVary*

DeflateBufferSize

: zlib: DeflateBufferSizevalue

: DeflateBufferSize8096

: ,: Extension: mod_deflate

DeflateBufferSize zlib

DeflateCompressionLevel

:: DeflateCompressionLevelvalue

: Zlib

: ,: Extension: mod_deflate: ThisdirectiveisavailablesinceApache2.0.45

DeflateCompressionLevel

1()9()

DeflateFilterNote

:: DeflateFilterNote[type]notename

: ,: Extension: mod_deflate: typeisavailablesinceApache2.0.45

DeflateFilterNote

DeflateFilterNoteratio

LogFormat'"%r"%b(%{ratio}n)"%{User-agent}i"'deflate

CustomLoglogs/deflate_logdeflate

type type

Output

( /*100 ) type

DeflateFilterNoteInputinstream

DeflateFilterNoteOutputoutstream

DeflateFilterNoteRatioratio

LogFormat'"%r"%{outstream}n/%{instream}n(%{ratio}n%%)'

deflate

CustomLoglogs/deflate_logdeflate

mod_log_config

DeflateMemLevel

: zlib: DeflateMemLevelvalue

: DeflateMemLevel9

DeflateMemLevel zlib(19))

||FAQ||

DeflateWindowSize

: Zlib: DeflateWindowSizevalue

: DeflateWindowSize15

DeflateWindowSize zlib(:zlib) (:2

||FAQ||

Apachemod_dir

: Base: dir_module: mod_dir.c

index.htmlmod_dir

http://servername/foo/dirnameURLURL

http://servername/foo/dirname/

DirectoryIndex

: : DirectoryIndexlocal-url[local-url]...

: DirectoryIndexindex.html

: ,,,.htaccess: Indexes: Base: mod_dir

DirectoryIndexindex.html

http://myserver/docs/http://myserver/docs/index.htmlURL

DirectoryIndexindex.htmlindex.txt/cgi-bin/index.pl

index.html index.txtCGI

||FAQ||

DirectorySlash

:: DirectorySlashOn|Off

: DirectorySlashOn

: ,,,.htaccess: Indexes: Base: mod_dir: 2.0.51

URL mod_dir

URLmod_autoindex mod_autoindexDirectoryIndexHTMLURL

#seesecuritywarningbelow!

DirectorySlashOff

SetHandlersome-handler

</Location>

DirectoryIndex( index.html)URL index.html

ApacheModulemod_disk_cache

Description: ContentcachestoragemanagerkeyedtoURIsStatus: ExperimentalModuleIdentifier: disk_cache_moduleSourceFile: mod_disk_cache.c

Summary

Thismoduleisexperimental.Documentationisstillunderdevelopment...

mod_disk_cacheimplementsadiskbasedstoragemanager.Itisprimarilyofuseinconjunctionwithmod_proxy.

ContentisstoredinandretrievedfromthecacheusingURIbasedkeys.Contentwithaccessprotectionisnotcached.

mod_disk_cacherequirestheservicesofmod_cache.

CacheDirLengthDirective

Description: ThenumberofcharactersinsubdirectorynamesSyntax: CacheDirLengthlength

Default: CacheDirLength2

Context: serverconfig,virtualhostStatus: ExperimentalModule: mod_disk_cache

TheCacheDirLengthdirectivesetsthenumberofcharactersforeachsubdirectorynameinthecachehierarchy.

TheresultofCacheDirLevels*CacheDirLengthmustnotbehigherthan20.

CacheDirLength4

CacheDirLevelsDirective

Description: Thenumberoflevelsofsubdirectoriesinthecache.

Syntax: CacheDirLevelslevels

Default: CacheDirLevels3

TheCacheDirLevelsdirectivesetsthenumberofsubdirectorylevelsinthecache.CacheddatawillbesavedthismanydirectorylevelsbelowtheCacheRootdirectory.

TheresultofCacheDirLevels*CacheDirLengthmustnotbehigherthan20.

CacheDirLevels5

CacheExpiryCheckDirective

Description: IndicatesifthecacheobservesExpiresdateswhenseekingfiles

Syntax: CacheExpiryCheckOn|Off

Default: CacheExpiryCheckOn

Moredetailwillbeaddedhere,whenthefunctionisimplemented.

CacheExpiryCheckOff

TheCacheExpiryCheckdirectiveiscurrentlynotimplemented.

CacheGcCleanDirective

Description: ThetimetoretainunchangedcachedfilesthatmatchaURL

Syntax: CacheGcCleanhoursurl-string

Default: CacheGcClean?

CacheGcClean12/daily_scripts

TheCacheGcCleandirectiveiscurrentlynotimplemented.

CacheGcDailyDirective

Description: Therecurringtimeeachdayforgarbagecollectiontoberun.(24hourclock)

Syntax: CacheGcDailytime

Default: CacheGcDaily?

CacheGcDaily23:59

TheCacheGcDailydirectiveiscurrentlynotimplemented.

CacheGcIntervalDirective

Description: Theintervalbetweengarbagecollectionattempts.Syntax: CacheGcIntervalhours

TheCacheGcIntervaldirectivespecifiesthenumberofhourstowaitbetweenattemptstofreeupdiskspace.

CacheGcInterval24

TheCacheGcIntervaldirectiveiscurrentlynotimplemented.

CacheGcMemUsageDirective

Description: Themaximumkilobytesofmemoryusedforgarbagecollection

Syntax: CacheGcMemUsageKBytes

Default: CacheGcMemUsage?

CacheGcMemUsage16

TheCacheGcMemUsagedirectiveiscurrentlynotimplemented.

CacheGcUnusedDirective

Description: ThetimetoretainunreferencedcachedfilesthatmatchaURL.

Syntax: CacheGcUnusedhoursurl-string

Default: CacheGcUnused?

CacheGcUnused12/local_images

TheCacheGcUnuseddirectiveiscurrentlynotimplemented.

CacheMaxFileSizeDirective

Description: Themaximumsize(inbytes)ofadocumenttobeplacedinthecache

Syntax: CacheMaxFileSizebytes

Default: CacheMaxFileSize1000000

TheCacheMaxFileSizedirectivesetsthemaximumsize,inbytes,foradocumenttobeconsideredforstorageinthecache.

CacheMaxFileSize64000

CacheMinFileSizeDirective

Description: Theminimumsize(inbytes)ofadocumenttobeplacedinthecache

Syntax: CacheMinFileSizebytes

Default: CacheMinFileSize1

TheCacheMinFileSizedirectivesetstheminimumsize,inbytes,foradocumenttobeconsideredforstorageinthecache.

CacheMinFileSize64

CacheRootDirective

Description: Thedirectoryrootunderwhichcachefilesarestored

Syntax: CacheRootdirectory

TheCacheRootdirectivedefinesthenameofthedirectoryonthedisktocontaincachefiles.Ifthemod_disk_cachemodulehasbeenloadedorcompiledintotheApacheserver,thisdirectivemustbedefined.FailingtoprovideavalueforCacheRootwillresultinaconfigurationfileprocessingerror.TheCacheDirLevelsandCacheDirLengthdirectivesdefinethestructureofthedirectoriesunderthespecifiedrootdirectory.

CacheRootc:/cacheroot

CacheSizeDirective

Description: ThemaximumamountofdiskspacethatwillbeusedbythecacheinKBytes

Syntax: CacheSizeKBytes

Default: CacheSize1000000

TheCacheSizedirectivesetsthedesireddiskspaceusageofthecache,inKBytes(1024-byteunits).Thisdirectivedoesnotputahardlimitonthesizeofthecache.Thegarbagecollectorwilldeletefilesuntiltheusageisatorbelowthesettings.Alwaysuseavaluethatislowerthantheavailablediskspace.

CacheSize5000000

CacheTimeMarginDirective

Description: TheminimumtimemargintocacheadocumentSyntax: CacheTimeMargin?

Default: CacheTimeMargin?

CacheTimeMarginX

TheCacheTimeMargindirectiveiscurrentlynotimplemented.

ApacheModulemod_dumpio

Description: DumpsallI/Otoerrorlogasdesired.Status: ExperimentalModuleIdentifier: dumpio_moduleSourceFile: mod_dumpio.c

Summarymod_dumpioallowsfortheloggingofallinputreceivedbyApacheand/oralloutputsentbyApachetobelogged(dumped)totheerror.logfile.

ThedataloggingisdonerightafterSSLdecoding(forinput)andrightbeforeSSLencoding(foroutput).Ascanbeexpected,thiscanproduceextremevolumesofdata,andshouldonlybeusedwhendebuggingproblems.

EnablingdumpioSupport

Toenablethemodule,itshouldbecompiledandloadedintoyourrunningApacheconfiguration.Loggingcanthenbeenabledordisabledviathebelowdirectives.

InorderfordumpingtoworkLogLevelmustbesettodebug.

DumpIOInputDirective

Description: DumpallinputdatatotheerrorlogSyntax: DumpIOInputOn|Off

Default: DumpIOInputOff

Context: serverconfigStatus: ExperimentalModule: mod_dumpioCompatibility: DumpIOInputisonlyavailableinApache2.0.53

andlater.

Enabledumpingofallinput.

ExampleDumpIOInputOn

DumpIOOutputDirective

Description: DumpalloutputdatatotheerrorlogSyntax: DumpIOOutputOn|Off

Default: DumpIOOutputOff

Context: serverconfigStatus: ExperimentalModule: mod_dumpioCompatibility: DumpIOOutputisonlyavailableinApache2.0.53

andlater.

Enabledumpingofalloutput.

ExampleDumpIOOutputOn

||FAQ||

Apachemod_echo

:: Experimental: echo_module: mod_echo.c: Apache2.0

||FAQ||

ProtocolEcho

:: ProtocolEchoOn|Off

: ,: Experimental: mod_echo: Apache2.0

ProtocolEcho

ProtocolEchoOn

||FAQ||

Apachemod_env

: CGISSI

: Base: env_module: mod_env.c

CGISSI

PassEnv

:: PassEnvenv-variable[env-variable]...

: ,,,.htaccess: FileInfo: Base: mod_env

httpdCGI SSI

PassEnvLD_LIBRARY_PATH

SetEnv

:: SetEnvenv-variablevalue

CGISSI

SetEnvSPECIAL_PATH/foo/bin

||FAQ||

UnsetEnv

:: UnsetEnvenv-variable[env-variable]...

CGISSI

UnsetEnvLD_LIBRARY_PATH

ApacheModulemod_example

Description: IllustratestheApachemoduleAPIStatus: ExperimentalModuleIdentifier: example_moduleSourceFile: mod_example.c

Summary

Thisdocumenthasnotbeenupdatedtotakeintoaccountchangesmadeinthe2.0versionoftheApacheHTTPServer.Someoftheinformationmaystillberelevant,butpleaseuseitwithcare.

Thefilesinthesrc/modules/exampledirectoryundertheApachedistributiondirectorytreeareprovidedasanexampletothosethatwishtowritemodulesthatusetheApacheAPI.

Themainfileismod_example.c,whichillustratesallthedifferentcallbackmechanismsandcallsyntaxes.Bynomeansdoesanadd-onmoduleneedtoincluderoutinesforallofthecallbacks-quitethecontrary!

Theexamplemoduleisanactualworkingmodule.Ifyoulinkitintoyourserver,enablethe"example-handler"handlerforalocation,andthenbrowsetothatlocation,youwillseeadisplayofsomeofthetracingtheexamplemoduledidasthevariouscallbacksweremade.

Compilingtheexamplemodule

Toincludetheexamplemoduleinyourserver,followthestepsbelow:

1. Uncommentthe"AddModulemodules/example/mod_example"linenearthebottomofthesrc/Configurationfile.Ifthereisn'tone,addit;itshouldlooklikethis:

AddModulemodules/example/mod_example.o

2. Runthesrc/Configurescript("cdsrc;./Configure").ThiswillbuildtheMakefilefortheserveritself,andupdatethesrc/modules/Makefileforanyadditionalmodulesyouhaverequestedfrombeneaththatsubdirectory.

3. Maketheserver(run"make"inthesrcdirectory).

Toaddanothermoduleofyourown:

A. mkdirsrc/modules/mymodule

B. cpsrc/modules/example/*src/modules/mymodule

C. Modifythefilesinthenewdirectory.

D. Followsteps[1]through[3]above,withappropriatechanges.

Usingthemod_exampleModule

Toactivatetheexamplemodule,includeablocksimilartothefollowinginyoursrm.conffile:

SetHandlerexample-handler

</Location>

Asanalternative,youcanputthefollowingintoa.htaccessfileandthenrequestthefile"test.example"fromthatlocation:

AddHandlerexample-handler.example

Afterreloading/restartingyourserver,youshouldbeabletobrowsetothislocationandseethebriefdisplaymentionedearlier.

ExampleDirective

Description: DemonstrationdirectivetoillustratetheApachemoduleAPI

Syntax: Example

Context: serverconfig,virtualhost,directory,.htaccessStatus: ExperimentalModule: mod_example

TheExampledirectivejustsetsademonstrationflagwhichtheexamplemodule'scontenthandlerdisplays.Ittakesnoarguments.IfyoubrowsetoanURLtowhichtheexamplecontent-handlerapplies,youwillgetadisplayoftheroutineswithinthemoduleandhowandinwhatordertheywerecalledtoservicethedocumentrequest.Theeffectofthisdirectiveonecanobserveunderthepoint"Exampledirectivedeclaredhere:YES/NO".

||FAQ||

Apachemod_expires

: Expires Cache-Control

HTTP: Extension: expires_module: mod_expires.c

ExpiresHTTP Cache-Control max-age

max-age( RFC2616section14.9) Cache-ControlHeader

ExpiresDefault ExpiresByType :

ExpiresDefault"<base>[plus]{<num><type>}*"

ExpiresByTypetype/encoding"<base>[plus]{<num><type>}*"

<base>:

access

now('access')modification

plus<num> ( atoi()) <type>:

months

minutes

seconds

ExpiresDefault"accessplus1month"

ExpiresDefault"accessplus4weeks"

ExpiresDefault"accessplus30days"

'<num><type>' :

ExpiresByTypetext/html"accessplus1month15days2hours"

ExpiresByTypeimage/gif"modificationplus5hours3minutes"

Expires

ExpiresActive

: Expires: ExpiresActiveOn|Off

: ,,,.htaccess: Indexes: Extension: mod_expires

Expires Cache-Control

( .htaccessExpiresDefault ()

Expires Cache-Control

ExpiresByType

: MIME Expires: ExpiresByTypeMIME-type<code>seconds

(text/html)

:#enableexpirations

ExpiresActiveOn

#expireGIFimagesafteramonthintheclient'scache

ExpiresByTypeimage/gifA2592000

#HTMLdocumentsaregoodforaweekfromthe

#timetheywerechanged

ExpiresByTypetext/htmlM604800

ExpiresActiveOn

||FAQ||

ExpiresDefault

:: ExpiresDefault<code>seconds

ApacheModulemod_ext_filter

Description: Passtheresponsebodythroughanexternalprogrambeforedeliverytotheclient

Status: ExtensionModuleIdentifier: ext_filter_moduleSourceFile: mod_ext_filter.c

Summarymod_ext_filterpresentsasimpleandfamiliarprogrammingmodelforfilters.Withthismodule,aprogramwhichreadsfromstdinandwritestostdout(i.e.,aUnix-stylefiltercommand)canbeafilterforApache.ThisfilteringmechanismismuchslowerthanusingafilterwhichisspeciallywrittenfortheApacheAPIandrunsinsideoftheApacheserverprocess,butitdoeshavethefollowingbenefits:

theprogrammingmodelismuchsimpleranyprogramming/scriptinglanguagecanbeused,providedthatitallowstheprogramtoreadfromstandardinputandwritetostandardoutputexistingprogramscanbeusedunmodifiedasApachefilters

Evenwhentheperformancecharacteristicsarenotsuitableforproductionuse,mod_ext_filtercanbeusedasaprototypeenvironmentforfilters.

SeealsoFilters

Examples

GeneratingHTMLfromsomeothertypeofresponse

#mod_ext_filterdirectivetodefineafilter

#toHTML-izetext/cfilesusingtheexternal

#program/usr/bin/enscript,withthetypeof

#theresultsettotext/html

ExtFilterDefinec-to-htmlmode=output\

intype=text/couttype=text/html\

cmd="/usr/bin/enscript--color-Whtml-Ec-o--"

<Directory"/export/home/trawick/apacheinst/htdocs/c">

#coredirectivetocausethenewfilterto

#berunonoutput

SetOutputFilterc-to-html

#mod_mimedirectivetosetthetypeof.c

#filestotext/c

AddTypetext/c.c

#mod_ext_filterdirectivetosetthedebug

#leveljusthighenoughtoseealogmessage

#perrequestshowingtheconfigurationinforce

ExtFilterOptionsDebugLevel=1

</Directory>

ImplementingacontentencodingfilterNote:thisgzipexampleisjustforthepurposesofillustration.Pleaserefertomod_deflateforapracticalimplementation.

#mod_ext_filterdirectivetodefinetheexternalfilter

ExtFilterDefinegzipmode=outputcmd=/bin/gzip

#coredirectivetocausethegzipfiltertobe

#runonoutput

SetOutputFiltergzip

#mod_headerdirectivetoadd

#"Content-Encoding:gzip"headerfield

HeadersetContent-Encodinggzip

</Location>

Slowingdowntheserver

#mod_ext_filterdirectivetodefineafilter

#whichrunseverythingthroughcat;catdoesn't

#modifyanything;itjustintroducesextrapathlength

#andconsumesmoreresources

ExtFilterDefineslowdownmode=outputcmd=/bin/cat\

preservescontentlength

#coredirectivetocausetheslowdownfilterto

#berunseveraltimesonoutput

SetOutputFilterslowdown;slowdown;slowdown

</Location>

Usingsedtoreplacetextintheresponse

#mod_ext_filterdirectivetodefineafilterwhich

#replacestextintheresponse

ExtFilterDefinefixtextmode=outputintype=text/html\

cmd="/bin/seds/verdana/arial/g"

#coredirectivetocausethefixtextfilterto

#berunonoutput

SetOutputFilterfixtext

</Location>

Tracinganotherfilter

#Tracethedatareadandwrittenbymod_deflate

#foraparticularclient(IP192.168.1.31)

#experiencingcompressionproblems.

#Thisfilterwilltracewhatgoesintomod_deflate.

ExtFilterDefinetracebefore\

cmd="/bin/tracefilter.pl/tmp/tracebefore"\

EnableEnv=trace_this_client

#Thisfilterwilltracewhatgoesaftermod_deflate.

#Notethatwithouttheftypeparameter,thedefault

#filtertypeofAP_FTYPE_RESOURCEwouldcausethe

#filtertobeplaced*before*mod_deflateinthefilter

#chain.Givingitanumericvalueslightlyhigherthan

#AP_FTYPE_CONTENT_SETwillensurethatitisplaced

#aftermod_deflate.

ExtFilterDefinetraceafter\

cmd="/bin/tracefilter.pl/tmp/traceafter"\

EnableEnv=trace_this_clientftype=21

SetEnvIfRemote_Addr192.168.1.31trace_this_client

SetOutputFiltertracebefore;deflate;traceafter

</Directory>

Hereisthefilterwhichtracesthedata:#!/usr/local/bin/perl-w

usestrict;

open(SAVE,">$ARGV[0]")

ordie"can'topen$ARGV[0]:$?";

while(<STDIN>){

printSAVE$_;

print$_;

close(SAVE);

ExtFilterDefineDirective

Description: DefineanexternalfilterSyntax: ExtFilterDefinefilternameparameters

Context: serverconfigStatus: ExtensionModule: mod_ext_filter

TheExtFilterDefinedirectivedefinesthecharacteristicsofanexternalfilter,includingtheprogramtorunanditsarguments.

filternamespecifiesthenameofthefilterbeingdefined.ThisnamecanthenbeusedinSetOutputFilterdirectives.Itmustbeuniqueamongallregisteredfilters.Atthepresenttime,noerrorisreportedbytheregister-filterAPI,soaproblemwithduplicatenamesisn'treportedtotheuser.

Subsequentparameterscanappearinanyorderanddefinetheexternalcommandtorunandcertainothercharacteristics.Theonlyrequiredparameteriscmd=.Theseparametersare:

cmd=cmdline

Thecmd=keywordallowsyoutospecifytheexternalcommandtorun.Ifthereareargumentsaftertheprogramname,thecommandlineshouldbesurroundedinquotationmarks(e.g.,cmd="/bin/mypgmarg1arg2".Normalshellquotingisnotnecessarysincetheprogramisrundirectly,bypassingtheshell.Programargumentsareblank-delimited.Abackslashcanbeusedtoescapeblankswhichshouldbepartofaprogramargument.Anybackslasheswhicharepartoftheargumentmustbeescapedwithbackslashthemselves.InadditiontothestandardCGIenvironmentvariables,DOCUMENT_URI,DOCUMENT_PATH_INFO,andQUERY_STRING_UNESCAPEDwillalsobesetfortheprogram.

mode=mode

modeshouldbeoutputfornow(thedefault).Inthefuture,mode=inputwillbeusedtospecifyafilterforrequestbodies.

intype=imt

Thisparameterspecifiestheinternetmediatype(i.e.,MIMEtype)ofdocumentswhichshouldbefiltered.Bydefault,alldocumentsarefiltered.Ifintype=isspecified,thefilterwillbedisabledfordocumentsofothertypes.

outtype=imt

Thisparameterspecifiestheinternetmediatype(i.e.,MIMEtype)offiltereddocuments.Itisusefulwhenthefilterchangestheinternetmediatypeaspartofthefilteringoperation.Bydefault,theinternetmediatypeisunchanged.

PreservesContentLength

ThePreservesContentLengthkeywordspecifiesthatthefilterpreservesthecontentlength.Thisisnotthedefault,asmostfilterschangethecontentlength.Intheeventthatthefilterdoesn'tmodifythelength,thiskeywordshouldbespecified.

ftype=filtertype

Thisparameterspecifiesthenumericvalueforfiltertypethatthefiltershouldberegisteredas.Thedefaultvalue,AP_FTYPE_RESOURCE,issufficientinmostcases.Ifthefilterneedstooperateatadifferentpointinthefilterchainthanresourcefilters,thenthisparameterwillbenecessary.SeetheAP_FTYPE_foodefinitionsinutil_filter.hforappropriatevalues.

disableenv=env

Thisparameterspecifiesthenameofanenvironmentvariablewhich,ifset,willdisablethefilter.

enableenv=env

Thisparameterspecifiesthenameofanenvironmentvariablewhichmustbeset,orthefilterwillbedisabled.

ExtFilterOptionsDirective

Description: Configuremod_ext_filteroptionsSyntax: ExtFilterOptionsoption[option]...

Default: ExtFilterOptionsDebugLevel=0

NoLogStderr

Context: directoryStatus: ExtensionModule: mod_ext_filter

TheExtFilterOptionsdirectivespecifiesspecialprocessingoptionsformod_ext_filter.Optioncanbeoneof

DebugLevel=n

TheDebugLevelkeywordallowsyoutospecifythelevelofdebugmessagesgeneratedbymod_ext_filter.Bydefault,nodebugmessagesaregenerated.ThisisequivalenttoDebugLevel=0.Withhighernumbers,moredebugmessagesaregenerated,andserverperformancewillbedegraded.TheactualmeaningsofthenumericvaluesaredescribedwiththedefinitionsoftheDBGLVL_constantsnearthebeginningofmod_ext_filter.c.Note:ThecoredirectiveLogLevelshouldbeusedtocausedebugmessagestobestoredintheApacheerrorlog.

LogStderr|NoLogStderr

TheLogStderrkeywordspecifiesthatmessageswrittentostandarderrorbytheexternalfilterprogramwillbesavedintheApacheerrorlog.NoLogStderrdisablesthisfeature.

ExampleExtFilterOptionsLogStderrDebugLevel=0

Messageswrittentothefilter'sstandarderrorwillbestoredinthe

Apacheerrorlog.Nodebugmessageswillbegeneratedbymod_ext_filter.

ApacheModulemod_file_cache

Description: CachesastaticlistoffilesinmemoryStatus: ExperimentalModuleIdentifier: file_cache_moduleSourceFile: mod_file_cache.c

Summary

Thismoduleshouldbeusedwithcare.Youcaneasilycreateabrokensiteusingmod_file_cache,soreadthisdocumentcarefully.

Cachingfrequentlyrequestedfilesthatchangeveryinfrequentlyisatechniqueforreducingserverload.mod_file_cacheprovidestwotechniquesforcachingfrequentlyrequestedstaticfiles.Throughconfigurationdirectives,youcandirectmod_file_cachetoeitheropenthenmmap()afile,ortopre-openafileandsavethefile'sopenfilehandle.Bothtechniquesreduceserverloadwhenprocessingrequestsforthesefilesbydoingpartofthework(specifically,thefileI/O)forservingthefilewhentheserverisstartedratherthanduringeachrequest.

Notice:YoucannotusethisforspeedingupCGIprogramsorotherfileswhichareservedbyspecialcontenthandlers.ItcanonlybeusedforregularfileswhichareusuallyservedbytheApachecorecontenthandler.

Thismoduleisanextensionofandborrowsheavilyfromthemod_mmap_staticmoduleinApache1.3.

Usingmod_file_cache

mod_file_cachecachesalistofstaticallyconfiguredfilesviaMMapFileorCacheFiledirectivesinthemainserverconfiguration.

Notallplatformssupportbothdirectives.Forexample,ApacheonWindowsdoesnotcurrentlysupporttheMMapStaticdirective,whileotherplatforms,likeAIX,supportboth.Youwillreceiveanerrormessageintheservererrorlogifyouattempttouseanunsupporteddirective.Ifgivenanunsupporteddirective,theserverwillstartbutthefilewillnotbecached.Onplatformsthatsupportbothdirectives,youshouldexperimentwithbothtoseewhichworksbestforyou.

MMapFileDirectiveTheMMapFiledirectiveofmod_file_cachemapsalistofstaticallyconfiguredfilesintomemorythroughthesystemcallmmap().ThissystemcallisavailableonmostmodernUnixderivates,butnotonall.Therearesometimessystem-specificlimitsonthesizeandnumberoffilesthatcanbemmap()ed,experimentationisprobablytheeasiestwaytofindout.

Thismmap()ingisdoneonceatserverstartorrestart,only.Sowheneveroneofthemappedfileschangesonthefilesystemyouhavetorestarttheserver(seetheStoppingandRestartingdocumentation).Toreiteratethatpoint:ifthefilesaremodifiedinplacewithoutrestartingtheserveryoumayendupservingrequeststhatarecompletelybogus.Youshouldupdatefilesbyunlinkingtheoldcopyandputtinganewcopyinplace.Mosttoolssuchasrdistandmvdothis.Thereasonwhythismodulesdoesn'ttakecareofchangestothefilesisthatthischeckwouldneedanextrastat()everytimewhichisawasteandagainsttheintentofI/Oreduction.

CacheFileDirectiveTheCacheFiledirectiveofmod_file_cacheopensanactivehandleorfiledescriptortothefile(orfiles)listedintheconfigurationdirectiveandplacestheseopenfilehandlesinthecache.Whenthefileisrequested,theserverretrievesthehandlefromthecacheandpassesittothesendfile()(orTransmitFile()onWindows),socketAPI.

Thisfilehandlecachingisdoneonceatserverstartorrestart,only.Sowheneveroneofthecachedfileschangesonthefilesystemyouhavetorestarttheserver(seetheStoppingandRestartingdocumentation).Toreiteratethatpoint:ifthefilesaremodifiedinplacewithoutrestartingtheserveryoumayendupservingrequeststhatarecompletelybogus.Youshouldupdatefilesbyunlinkingtheoldcopyandputtinganewcopyinplace.Mosttoolssuchasrdistandmvdothis.

Don'tbotheraskingforadirectivewhichrecursivelycachesallthefilesinadirectory.Trythisinstead...SeetheIncludedirective,andconsiderthiscommand:

find/www/htdocs-typef-print\

|sed-e's/.*/mmapfile&/'>/www/conf/mmap.conf

CacheFileDirective

Description: CachealistoffilehandlesatstartuptimeSyntax: CacheFilefile-path[file-path]...

Context: serverconfigStatus: ExperimentalModule: mod_file_cache

TheCacheFiledirectiveopenshandlestooneormorefiles(givenaswhitespaceseparatedarguments)andplacesthesehandlesintothecacheatserverstartuptime.Handlestocachedfilesareautomaticallyclosedonaservershutdown.Whenthefileshavechangedonthefilesystem,theservershouldberestartedtotore-cachethem.

Becarefulwiththefile-patharguments:TheyhavetoliterallymatchthefilesystempathApache'sURL-to-filenametranslationhandlerscreate.Wecannotcompareinodesorotherstufftomatchpathsthroughsymboliclinksetc.becausethatagainwouldcostextrastat()systemcallswhichisnotacceptable.Thismodulemayormaynotworkwithfilenamesrewrittenbymod_aliasormod_rewrite.

ExampleCacheFile/usr/local/apache/htdocs/index.html

MMapFileDirective

Description: MapalistoffilesintomemoryatstartuptimeSyntax: MMapFilefile-path[file-path]...

Context: serverconfigStatus: ExperimentalModule: mod_file_cache

TheMMapFiledirectivemapsoneormorefiles(givenaswhitespaceseparatedarguments)intomemoryatserverstartuptime.Theyareautomaticallyunmappedonaservershutdown.WhenthefileshavechangedonthefilesystematleastaHUPorUSR1signalshouldbesendtotheservertore-mmap()them.

Becarefulwiththefile-patharguments:TheyhavetoliterallymatchthefilesystempathApache'sURL-to-filenametranslationhandlerscreate.Wecannotcompareinodesorotherstufftomatchpathsthroughsymboliclinksetc.becausethatagainwouldcostextrastat()systemcallswhichisnotacceptable.Thismodulemayormaynotworkwithfilenamesrewrittenbymod_aliasormod_rewrite.

ExampleMMapFile/usr/local/apache/htdocs/index.html

ApacheModulemod_headers

Description: CustomizationofHTTPrequestandresponseheaders

Status: ExtensionModuleIdentifier: headers_moduleSourceFile: mod_headers.c

SummaryThismoduleprovidesdirectivestocontrolandmodifyHTTPrequestandresponseheaders.Headerscanbemerged,replacedorremoved.

OrderofProcessing

Thedirectivesprovidedbymod_headerscanoccuralmostanywherewithintheserverconfiguration.Theyarevalidinthemainserverconfigandvirtualhostsections,inside<Directory>,<Location>and<Files>sections,andwithin.htaccessfiles.

Thedirectivesareprocessedinthefollowingorder:

1. mainserver

2. virtualhost

3. <Directory>sectionsand.htaccess

4. <Files>

5. <Location>

Orderisimportant.Thesetwoheadershaveadifferenteffectifreversed:

RequestHeaderappendMirrorID"mirror12"

RequestHeaderunsetMirrorID

Thiswayround,theMirrorIDheaderisnotset.Ifreversed,theMirrorIDheaderissetto"mirror12".

Examples

1. Copyallrequestheadersthatbeginwith"TS"totheresponseheaders:

Headerecho^TS

2. Addaheader,MyHeader,totheresponseincludingatimestampforwhentherequestwasreceivedandhowlongittooktobeginservingtherequest.Thisheadercanbeusedbytheclienttointuitloadontheserverorinisolatingbottlenecksbetweentheclientandtheserver.

HeaderaddMyHeader"%D%t"

resultsinthisheaderbeingaddedtotheresponse:

MyHeader:D=3775428t=991424704447256

3. SayhellotoJoe

HeaderaddMyHeader"HelloJoe.Ittook%Dmicroseconds\

forApachetoservethisrequest."

resultsinthisheaderbeingaddedtotheresponse:

MyHeader:HelloJoe.IttookD=3775428microsecondsfor

Apachetoservethisrequest.

4. ConditionallysendMyHeaderontheresponseifandonlyifheader"MyRequestHeader"ispresentontherequest.Thisisusefulforconstructingheadersinresponsetosomeclientstimulus.Notethatthisexamplerequirestheservicesofthemod_setenvifmodule.

SetEnvIfMyRequestHeadervalueHAVE_MyRequestHeader

HeaderaddMyHeader"%D%tmytext"

env=HAVE_MyRequestHeader

IftheheaderMyRequestHeader:valueispresentontheHTTPrequest,theresponsewillcontainthefollowingheader:

MyHeader:D=3775428t=991424704447256mytext

HeaderDirective

Description: ConfigureHTTPresponseheadersSyntax: Header[condition]

set|append|add|unset|echoheader

[value][env=[!]variable]

Context: serverconfig,virtualhost,directory,.htaccessOverride: FileInfoStatus: ExtensionModule: mod_headersCompatibility: Conditionisavailableinversion2.0.51andlater

Thisdirectivecanreplace,mergeorremoveHTTPresponseheaders.Theheaderismodifiedjustafterthecontenthandlerandoutputfiltersarerun,allowingoutgoingheaderstobemodified.

Theoptionalconditioncanbeeitheronsuccessoralways.Itdetermines,whichinternalheadertableshouldbeoperatedon.onsuccessstandsfor2xxstatuscodesandalwaysforallstatuscodes(including2xx).Especiallyifyouwanttounsetheaderssetbycertainmodules,youshouldtryout,whichtableisaffected.

Theactionitperformsisdeterminedbythesecondargument.Thiscanbeoneofthefollowingvalues:

Theresponseheaderisset,replacinganypreviousheaderwiththisname.Thevaluemaybeaformatstring.

append

Theresponseheaderisappendedtoanyexistingheaderofthesamename.Whenanewvalueismergedontoanexistingheaderitisseparatedfromtheexistingheaderwithacomma.ThisistheHTTPstandardwayofgivingaheader

multiplevalues.

Theresponseheaderisaddedtotheexistingsetofheaders,evenifthisheaderalreadyexists.Thiscanresultintwo(ormore)headershavingthesamename.Thiscanleadtounforeseenconsequences,andingeneral"append"shouldbeusedinstead.

Theresponseheaderofthisnameisremoved,ifitexists.Iftherearemultipleheadersofthesamename,allwillberemoved.

Requestheaderswiththisnameareechoedbackintheresponseheaders.headermaybearegularexpression.

Thisargumentisfollowedbyaheadername,whichcanincludethefinalcolon,butitisnotrequired.Caseisignoredforset,append,addandunset.Theheadernameforechoiscasesensitiveandmaybearegularexpression.

Foradd,appendandsetavalueisspecifiedasthethirdargument.Ifvaluecontainsspaces,itshouldbesurroundedbydoublequotes.valuemaybeacharacterstring,astringcontainingformatspecifiersoracombinationofboth.Thefollowingformatspecifiersaresupportedinvalue:

%t ThetimetherequestwasreceivedinUniversalCoordinatedTimesincetheepoch(Jan.1,1970)measuredinmicroseconds.Thevalueisprecededbyt=.

%D Thetimefromwhentherequestwasreceivedtothetimetheheadersaresentonthewire.Thisisameasureofthedurationoftherequest.Thevalueis

precededbyD=.%

{FOOBAR}e

ThecontentsoftheenvironmentvariableFOOBAR.

WhentheHeaderdirectiveisusedwiththeadd,append,orsetargument,afourthargumentmaybeusedtospecifyconditionsunderwhichtheactionwillbetaken.Iftheenvironmentvariablespecifiedintheenv=...argumentexists(oriftheenvironmentvariabledoesnotexistandenv=!...isspecified)thentheactionspecifiedbytheHeaderdirectivewilltakeeffect.Otherwise,thedirectivewillhavenoeffectontherequest.

TheHeaderdirectivesareprocessedjustbeforetheresponseissenttothenetwork.Thesemeansthatitispossibletosetand/oroverridemostheaders,exceptforthoseheadersaddedbytheheaderfilter.

RequestHeaderDirective

Description: ConfigureHTTPrequestheadersSyntax: RequestHeaderset|append|add|unset

header[value[env=[!]variable]]

Context: serverconfig,virtualhost,directory,.htaccessOverride: FileInfoStatus: ExtensionModule: mod_headers

Thisdirectivecanreplace,mergeorremoveHTTPrequestheaders.Theheaderismodifiedjustbeforethecontenthandlerisrun,allowingincomingheaderstobemodified.Theactionitperformsisdeterminedbythefirstargument.Thiscanbeoneofthefollowingvalues:

Therequestheaderisset,replacinganypreviousheaderwiththisname

append

Therequestheaderisappendedtoanyexistingheaderofthesamename.Whenanewvalueismergedontoanexistingheaderitisseparatedfromtheexistingheaderwithacomma.ThisistheHTTPstandardwayofgivingaheadermultiplevalues.

Therequestheaderisaddedtotheexistingsetofheaders,evenifthisheaderalreadyexists.Thiscanresultintwo(ormore)headershavingthesamename.Thiscanleadtounforeseenconsequences,andingeneralappendshouldbeusedinstead.

Therequestheaderofthisnameisremoved,ifitexists.If

therearemultipleheadersofthesamename,allwillberemoved.

Thisargumentisfollowedbyaheadername,whichcanincludethefinalcolon,butitisnotrequired.Caseisignored.Foradd,appendandsetavalueisgivenasthethirdargument.Ifvaluecontainsspaces,itshouldbesurroundedbydoublequotes.Forunset,novalueshouldbegiven.

WhentheRequestHeaderdirectiveisusedwiththeadd,append,orsetargument,afourthargumentmaybeusedtospecifyconditionsunderwhichtheactionwillbetaken.Iftheenvironmentvariablespecifiedintheenv=...argumentexists(oriftheenvironmentvariabledoesnotexistandenv=!...isspecified)thentheactionspecifiedbytheRequestHeaderdirectivewilltakeeffect.Otherwise,thedirectivewillhavenoeffectontherequest.

TheRequestHeaderdirectiveisprocessedjustbeforetherequestisrunbyitshandlerinthefixupphase.Thisshouldallowheadersgeneratedbythebrowser,orbyApacheinputfilterstobeoverriddenormodified.

ApacheModulemod_imap

Description: Server-sideimagemapprocessingStatus: BaseModuleIdentifier: imap_moduleSourceFile: mod_imap.c

SummaryThismoduleprocesses.mapfiles,therebyreplacingthefunctionalityoftheimagemapCGIprogram.Anydirectoryordocumenttypeconfiguredtousethehandlerimap-file(usingeitherAddHandlerorSetHandler)willbeprocessedbythismodule.

Thefollowingdirectivewillactivatefilesendingwith.mapasimagemapfiles:

AddHandlerimap-filemap

Notethatthefollowingisstillsupported:

AddTypeapplication/x-httpd-imapmap

However,wearetryingtophaseout"magicMIMEtypes"sowearedeprecatingthismethod.

NewFeatures

Theimagemapmoduleaddssomenewfeaturesthatwerenotpossiblewithpreviouslydistributedimagemapprograms.

URLreferencesrelativetotheReferer:information.Default<base>assignmentthroughanewmapdirectivebase.Noneedforimagemap.conffile.Pointreferences.Configurablegenerationofimagemapmenus.

ImagemapFile

Thelinesintheimagemapfilescanhaveoneofseveralformats:

directivevalue[x,y...]

directivevalue"Menutext"[x,y...]

directivevaluex,y..."Menutext"

Thedirectiveisoneofbase,default,poly,circle,rect,orpoint.ThevalueisanabsoluteorrelativeURL,oroneofthespecialvalueslistedbelow.Thecoordinatesarex,ypairsseparatedbywhitespace.Thequotedtextisusedasthetextofthelinkifaimagemapmenuisgenerated.Linesbeginningwith'#'arecomments.

ImagemapFileDirectivesTherearesixdirectivesallowedintheimagemapfile.Thedirectivescancomeinanyorder,butareprocessedintheordertheyarefoundintheimagemapfile.

baseDirectiveHastheeffectof<basehref="value">.Thenon-absoluteURLsofthemap-filearetakenrelativetothisvalue.ThebasedirectiveoverridesImapBaseassetina.htaccessfileorintheserverconfigurationfiles.IntheabsenceofanImapBaseconfigurationdirective,basedefaultstohttp://server_name/.

base_uriissynonymouswithbase.NotethatatrailingslashontheURLissignificant.

defaultDirectiveTheactiontakenifthecoordinatesgivendonotfitanyofthepoly,circleorrectdirectives,andtherearenopointdirectives.Defaultstonocontentintheabsenceofan

ImapDefaultconfigurationsetting,causingastatuscodeof204NoContenttobereturned.Theclientshouldkeepthesamepagedisplayed.

polyDirectiveTakesthreetoone-hundredpoints,andisobeyediftheuserselectedcoordinatesfallwithinthepolygondefinedbythesepoints.

circle

Takesthecentercoordinatesofacircleandapointonthecircle.Isobeyediftheuserselectedpointiswiththecircle.

rectDirectiveTakesthecoordinatesoftwoopposingcornersofarectangle.Obeyedifthepointselectediswithinthisrectangle.

pointDirectiveTakesasinglepoint.Thepointdirectiveclosesttotheuserselectedpointisobeyedifnootherdirectivesaresatisfied.Notethatdefaultwillnotbefollowedifapointdirectiveispresentandvalidcoordinatesaregiven.

ValuesThevaluesforeachofthedirectivescananyofthefollowing:

aURLTheURLcanberelativeorabsoluteURL.RelativeURLscancontain'..'syntaxandwillberesolvedrelativetothebasevalue.

baseitselfwillnotresolvedaccordingtothecurrentvalue.Astatementbasemailto:willworkproperly,though.

EquivalenttotheURLoftheimagemapfileitself.No

coordinatesaresentwiththis,soamenuwillbegeneratedunlessImapMenuissettonone.

Synonymouswithmap.

referer

EquivalenttotheURLofthereferringdocument.Defaultstohttp://servername/ifnoReferer:headerwaspresent.

nocontent

Sendsastatuscodeof204NoContent,tellingtheclienttokeepthesamepagedisplayed.Validforallbutbase.

Failswitha500ServerError.Validforallbutbase,butsortofsillyforanythingbutdefault.

Coordinates0,0200,200

Acoordinateconsistsofanxandayvalueseparatedbyacomma.Thecoordinatesareseparatedfromeachotherbywhitespace.ToaccommodatethewayLynxhandlesimagemaps,shouldauserselectthecoordinate0,0,itisasifnocoordinatehadbeenselected.

QuotedText"MenuText"

Afterthevalueorafterthecoordinates,thelineoptionallymaycontaintextwithindoublequotes.Thisstringisusedasthetextforthelinkifamenuisgenerated:

<ahref="http://foo.com/">Menutext</a>

Ifnoquotedtextispresent,thenameofthelinkwillbeused

asthetext:

<ahref="http://foo.com/">http://foo.com</a>

Ifyouwanttousedoublequoteswithinthistext,youhavetowritethemas".

ExampleMapfile

#Commentsareprintedina'formatted'or'semiformatted'menu.

#Andcancontainhtmltags.<hr>

basereferer

polymap"CouldIhaveamenu,please?"0,00,1010,1010,0

rect..0,077,27"thedirectoryofthereferer"

circlehttp://www.inetnebr.com/lincoln/feedback/195,0305,27

rectanother_file"insamedirectoryasreferer"306,0419,27

pointhttp://www.zyzzyva.com/100,100

pointhttp://www.tripod.com/200,200

rectmailto:nate@tripod.com100,150200,0"Bugs?"

Referencingyourmapfile

HTMLexample<ahref="/maps/imagemap1.map">

<imgismapsrc="/images/imagemap1.gif">

XHTMLexample<ahref="/maps/imagemap1.map">

<imgismap="ismap"src="/images/imagemap1.gif"/>

ImapBaseDirective

Description: DefaultbaseforimagemapfilesSyntax: ImapBasemap|referer|URL

Default: ImapBasehttp://servername/

Context: serverconfig,virtualhost,directory,.htaccessOverride: IndexesStatus: BaseModule: mod_imap

TheImapBasedirectivesetsthedefaultbaseusedintheimagemapfiles.Itsvalueisoverriddenbyabasedirectivewithintheimagemapfile.Ifnotpresent,thebasedefaultstohttp://servername/.

SeealsoUseCanonicalName

ImapDefaultDirective

Description: Defaultactionwhenanimagemapiscalledwithcoordinatesthatarenotexplicitlymapped

Syntax: ImapDefault

error|nocontent|map|referer|URL

Default: ImapDefaultnocontent

TheImapDefaultdirectivesetsthedefaultdefaultusedintheimagemapfiles.Itsvalueisoverriddenbyadefaultdirectivewithintheimagemapfile.Ifnotpresent,thedefaultactionisnocontent,whichmeansthata204NoContentissenttotheclient.Inthiscase,theclientshouldcontinuetodisplaytheoriginalpage.

ImapMenuDirective

Description: Actionifnocoordinatesaregivenwhencallinganimagemap

Syntax: ImapMenu

none|formatted|semiformatted|unformatted

TheImapMenudirectivedeterminestheactiontakenifanimagemapfileiscalledwithoutvalidcoordinates.

IfImapMenuisnone,nomenuisgenerated,andthedefaultactionisperformed.

formatted

Aformattedmenuisthesimplestmenu.Commentsintheimagemapfileareignored.Aleveloneheaderisprinted,thenanhrule,thenthelinkseachonaseparateline.Themenuhasaconsistent,plainlookclosetothatofadirectorylisting.

semiformatted

Inthesemiformattedmenu,commentsareprintedwheretheyoccurintheimagemapfile.BlanklinesareturnedintoHTMLbreaks.Noheaderorhruleisprinted,butotherwisethemenuisthesameasaformattedmenu.

unformatted

Commentsareprinted,blanklinesareignored.Nothingisprintedthatdoesnotappearintheimagemapfile.Allbreaksandheadersmustbeincludedascommentsintheimagemapfile.Thisgivesyouthemostflexibilityovertheappearanceofyourmenus,butrequiresyoutotreatyourmapfilesasHTML

insteadofplaintext.

||FAQ||

Apachemod_include

: html(ServerSideIncludes)

: Base: include_module: mod_include.c: Apache2.0

Options

AcceptPathInfo

Server-SideIncludes

ServerSideIncludes INCLUDES Server-sideinclude.shtmlApache

AddOutputFilterINCLUDES.shtml

shtml (Options .htaccess):

Options+Includes

server-parsedINCLUDES MIMEserver-parsed-html text/x-server-parsed-html3ApacheINCLUDES( MIME

TutorialonServerSideIncludes.

(SSI)PATH_INFO

SSI PATH_INFO()

SGML HTML

(:value) (')(`) ( -->)SSI

(:element)

config configureoutputformatsecho printvariablesexec executeexternalprogramsfsize printsizeofafileflastmod printlastmodificationtimeofafileinclude includeafileprintenv printallavailablevariablesset setavalueofavariable

SSI mod_include exec

config

errmsg

sizefmt

timefmt

strftime(3)

echo include SSIUndefinedEcho

encoding

echo entityencoding encoding

encoding var ISO-8859-1

execexecCGI mod_cgi

(%-)URL (/)(ScriptAlias OptionExecCGI)CGI

CGI PATH_INFO( CGIinclude

Location: HTML()

execcgi includevirtualCGI

cgi includevirtual

<!--#includevirtual="/cgi-bin/example.cgi?argument=value"

/bin/sh CGI include

#includevirtual #execcgi #execcmd( #includevirtual)Apache

Win32 suexecunix execunixsuexec Win32suexecunix:

fsize sizefmt

virtual

(%)URL-path(/)

flastmod timefmt

include (text/plain,text/html)

include

virtual

(%)URL URL

URLURL

URLCGI

<!--#includevirtual="/cgi-bin/example.cgi?argument=value"

HTMLCGI includevirtual

printenvApache1.3.12 (

Include

CGI echo if elif,

DATE_GMT

DATE_LOCAL

DOCUMENT_NAME

DOCUMENT_URI

(%)URL-path

LAST_MODIFIED

QUERY_STRING_UNESCAPED

(%-) shell

SSI echo,set :

REMOTE_HOST "X" REQUEST_METHOD "Y" Zed"X_Y"

DOCUMENT_URI /foo/file.html"infoo"/bar/file.html"inbar" "inneither"

inneither

elif else test_condition

endif if

test_condition:

string

string1=string2

string1==string2

string1!=string2

string1 string2 string2 /string/ perl5 == =

( = ==)

string1<string2

string1<=string2

string1>string2

string1>=string2

string1 string2 ( strcmp(3)) "100"

(test_condition)

test_condition

!test_condition

test_condition

test_condition1&&test_condition2

test_condition1 test_condition2

test_condition1||test_condition2

test_condition1 test_condition2

"="" !="" &&" " !" :

string1string2 string1string2

'string1string2' string1string2

SSIEndTag

: include: SSIEndTagtag

: SSIEndTag"-->"

: ,: Base: mod_include: 2.0.30

mod_include include

SSIEndTag"%>"

SSIStartTag

SSIErrorMsg

: SSI: SSIErrorMsgmessage

: SSIErrorMsg"[anerroroccurredwhile

processingthisdirective]"

: ,,,.htaccess: All: Base: mod_include: 2.0.30

SSIErrorMsg mod_include

SSIErrorMsg""

SSIStartTag

: include: SSIStartTagtag

: SSIStartTag"<!--#"

: ,: Base: mod_include: 2.0.30

mod_includeinclude

SSIStartTag"<%"

SSIEndTag"%>"

SSIEndTag SSI:

SSI<%printenv%>

SSIEndTag

SSITimeFormat

:: SSITimeFormatformatstring

: SSITimeFormat"%A,%d-%b-%Y%H:%M:%S%Z"

: ,,,.htaccess: All: Base: mod_include: 2.0.30

DATEecho

SSITimeFormat"%R,%B%d,%Y"

"22:26,June14,2002"

SSIUndefinedEcho

: echo: SSIUndefinedEchostring

: SSIUndefinedEcho"(none)"

: ,: All: Base: mod_include: 2.0.34

"echo" mod_include

SSIUndefinedEcho""

||FAQ||

XBitHack

: SSI: XBitHackon|off|full

: XBitHackoff

: ,,,.htaccess: Options: Base: mod_include

XBitHackHTML MIME

text/htmlhtml

CGI #include

||FAQ||

Apachemod_info

:: Extension: info_module: mod_info.c

mod_info httpd.conf

SetHandlerserver-info

</Location>

http://your.host.dom/server-info

mod_info ( .htaccess

/ Apache

||FAQ||

AddModuleInfo

: server-info: AddModuleInfomodule-namestring

: ,: Extension: mod_info: Apache1.3

string module-nameHTML :

AddModuleInfomod_authn_file.c'See<a\

href="http://www.apache.org/docs/2.0/mod/mod_authn_file.html">\

http://www.apache.org/docs/2.0/mod/mod_authn_file.html</a>'

ApacheModulemod_isapi

Description: ISAPIExtensionswithinApacheforWindowsStatus: BaseModuleIdentifier: isapi_moduleSourceFile: mod_isapi.cCompatibility: Win32only

SummaryThismoduleimplementstheInternetServerextensionAPI.ItallowsInternetServerextensions(e.g.ISAPI.dllmodules)tobeservedbyApacheforWindows,subjecttothenotedrestrictions.

ISAPIextensionmodules(.dllfiles)arewrittenbythirdparties.TheApacheGroupdoesnotauthorthesemodules,soweprovidenosupportforthem.PleasecontacttheISAPI'sauthordirectlyifyouareexperiencingproblemsrunningtheirISAPIextension.PleasedonotpostsuchproblemstoApache'slistsorbugreportingpages.

Intheserverconfigurationfile,usetheAddHandlerdirectivetoassociateISAPIfileswiththeisapi-handlerhandler,andmapittothemwiththeirfileextensions.Toenableany.dllfiletobeprocessedasanISAPIextension,editthehttpd.conffileandaddthefollowingline:

AddHandlerisapi-handler.dll

InversionsoftheApacheserverpriorto2.0.37,useisapi-isainsteadofisapi-handler.Thenewhandlernameisnotavailablepriortoversion2.0.37.Forcompatibility,configurationsmaycontinueusingisapi-isathroughallversionsofApachepriorto2.3.0.

ThereisnocapabilitywithintheApacheservertoleavearequestedmoduleloaded.However,youmaypreloadandkeepaspecificmoduleloadedbyusingthefollowingsyntaxinyourhttpd.conf:

ISAPICacheFilec:/WebWork/Scripts/ISAPI/mytest.dll

WhetherornotyouhavepreloadedanISAPIextension,allISAPIextensionsaregovernedbythesamepermissionsandrestrictionsasCGIscripts.Thatis,OptionsExecCGImustbesetforthedirectorythatcontainstheISAPI.dllfile.

ReviewtheAdditionalNotesandtheProgrammer'sJournalforadditionaldetailsandclarificationofthespecificISAPIsupportofferedbymod_isapi.

AdditionalNotes

Apache'sISAPIimplementationconformstoalloftheISAPI2.0specification,exceptforsome"Microsoft-specific"extensionsdealingwithasynchronousI/O.Apache'sI/OmodeldoesnotallowasynchronousreadingandwritinginamannerthattheISAPIcouldaccess.IfanISAtriestoaccessunsupportedfeatures,includingasyncI/O,amessageisplacedintheerrorlogtohelpwithdebugging.Sincethesemessagescanbecomeaflood,thedirectiveISAPILogNotSupportedOffexiststoquietthisnoise.

Someservers,likeMicrosoftIIS,loadtheISAPIextensionintotheserverandkeepitloadeduntilmemoryusageistoohigh,orunlessconfigurationoptionsarespecified.ApachecurrentlyloadsandunloadstheISAPIextensioneachtimeitisrequested,unlesstheISAPICacheFiledirectiveisspecified.Thisisinefficient,butApache'smemorymodelmakesthisthemosteffectivemethod.ManyISAPImodulesaresubtlyincompatiblewiththeApacheserver,andunloadingthesemoduleshelpstoensurethestabilityoftheserver.

Also,rememberthatwhileApachesupportsISAPIExtensions,itdoesnotsupportISAPIFilters.Supportforfiltersmaybeaddedatalaterdate,butnosupportisplannedatthistime.

Programmer'sJournal

IfyouareprogrammingApache2.0mod_isapimodules,youmustlimityourcallstoServerSupportFunctiontothefollowingdirectives:

HSE_REQ_SEND_URL_REDIRECT_RESP

Redirecttheusertoanotherlocation.ThismustbeafullyqualifiedURL(e.g.http://server/location).

HSE_REQ_SEND_URL

Redirecttheusertoanotherlocation.ThiscannotbeafullyqualifiedURL,youarenotallowedtopasstheprotocoloraservername(e.g.simply/location).Thisredirectionishandledbytheserver,notthebrowser.

Warning

Intheirrecentdocumentation,MicrosoftappearstohaveabandonedthedistinctionbetweenthetwoHSE_REQ_SEND_URLfunctions.Apachecontinuestotreatthemastwodistinctfunctionswithdifferentrequirementsandbehaviors.

HSE_REQ_SEND_RESPONSE_HEADER

Apacheacceptsaresponsebodyfollowingtheheaderifitfollowstheblankline(twoconsecutivenewlines)intheheadersstringargument.ThisbodycannotcontainNULLs,sincetheheadersargumentisNULLterminated.

HSE_REQ_DONE_WITH_SESSION

Apacheconsidersthisano-op,sincethesessionwillbefinishedwhentheISAPIreturnsfromprocessing.

HSE_REQ_MAP_URL_TO_PATH

Apachewilltranslateavirtualnametoaphysicalname.

HSE_APPEND_LOG_PARAMETER

Thisloggedmessagemaybecapturedinanyofthefollowinglogs:

inthe\"%{isapi-parameter}n\"componentinaCustomLogdirectiveinthe%qlogcomponentwiththeISAPIAppendLogToQueryOndirectiveintheerrorlogwiththeISAPIAppendLogToErrorsOndirective

Thefirstoption,the%{isapi-parameter}ncomponent,isalwaysavailableandpreferred.

HSE_REQ_IS_KEEP_CONN

WillreturnthenegotiatedKeep-Alivestatus.

HSE_REQ_SEND_RESPONSE_HEADER_EX

Willbehaveasdocumented,althoughthefKeepConnflagisignored.

HSE_REQ_IS_CONNECTED

Willreportfalseiftherequesthasbeenaborted.

ApachereturnsFALSEtoanyunsupportedcalltoServerSupportFunction,andsetstheGetLastErrorvaluetoERROR_INVALID_PARAMETER.

ReadClientretrievestherequestbodyexceedingtheinitialbuffer(definedbyISAPIReadAheadBuffer).BasedontheISAPIReadAheadBuffersetting(numberofbytestobufferpriortocallingtheISAPIhandler)shorterrequestsaresentcompletetotheextensionwhenitisinvoked.Iftherequestislonger,theISAPIextensionmustuseReadClienttoretrievetheremainingrequestbody.

WriteClientissupported,butonlywiththeHSE_IO_SYNCflagornooptionflag(valueof0).AnyotherWriteClientrequestwillberejectedwithareturnvalueofFALSE,andaGetLastErrorvalueofERROR_INVALID_PARAMETER.

GetServerVariableissupported,althoughextendedservervariablesdonotexist(asdefinedbyotherservers.)AlltheusualApacheCGIenvironmentvariablesareavailablefromGetServerVariable,aswellastheALL_HTTPandALL_RAWvalues.

Apache2.0mod_isapisupportsadditionalfeaturesintroducedinlaterversionsoftheISAPIspecification,aswellaslimitedemulationofasyncI/OandtheTransmitFilesemantics.ApachealsosupportspreloadingISAPI.dllsforperformance,neitherofwhichwerenotavailableunderApache1.3mod_isapi.

ISAPIAppendLogToErrorsDirective

Description: RecordHSE_APPEND_LOG_PARAMETERrequestsfromISAPIextensionstotheerrorlog

Syntax: ISAPIAppendLogToErrorson|off

Default: ISAPIAppendLogToErrorsoff

Context: serverconfig,virtualhost,directory,.htaccessOverride: FileInfoStatus: BaseModule: mod_isapi

RecordHSE_APPEND_LOG_PARAMETERrequestsfromISAPIextensionstotheservererrorlog.

ISAPIAppendLogToQueryDirective

Description: RecordHSE_APPEND_LOG_PARAMETERrequestsfromISAPIextensionstothequeryfield

Syntax: ISAPIAppendLogToQueryon|off

Default: ISAPIAppendLogToQueryon

RecordHSE_APPEND_LOG_PARAMETERrequestsfromISAPIextensionstothequeryfield(appendedtotheCustomLog%qcomponent).

ISAPICacheFileDirective

Description: ISAPI.dllfilestobeloadedatstartupSyntax: ISAPICacheFilefile-path[file-path]

Context: serverconfig,virtualhostStatus: BaseModule: mod_isapi

Specifiesaspace-separatedlistoffilenamestobeloadedwhentheApacheserverislaunched,andremainloadeduntiltheserverisshutdown.ThisdirectivemayberepeatedforeveryISAPI.dllfiledesired.Thefullpathnameofeachfileshouldbespecified.Ifthepathnameisnotabsolute,itwillbetreatedrelativetoServerRoot.

ISAPIFakeAsyncDirective

Description: FakeasynchronoussupportforISAPIcallbacksSyntax: ISAPIFakeAsyncon|off

Default: ISAPIFakeAsyncoff

Whilesettoon,asynchronoussupportforISAPIcallbacksissimulated.

ISAPILogNotSupportedDirective

Description: LogunsupportedfeaturerequestsfromISAPIextensions

Syntax: ISAPILogNotSupportedon|off

Default: ISAPILogNotSupportedoff

LogsallrequestsforunsupportedfeaturesfromISAPIextensionsintheservererrorlog.Thismayhelpadministratorstotrackdownproblems.OncesettoonandalldesiredISAPImodulesarefunctioning,itshouldbesetbacktooff.

ISAPIReadAheadBufferDirective

Description: SizeoftheReadAheadBuffersenttoISAPIextensions

Syntax: ISAPIReadAheadBuffersize

Default: ISAPIReadAheadBuffer49152

DefinesthemaximumsizeoftheReadAheadBuffersenttoISAPIextensionswhentheyareinitiallyinvoked.AllremainingdatamustberetrievedusingtheReadClientcallback;someISAPIextensionsmaynotsupporttheReadClientfunction.ReferquestionstotheISAPIextension'sauthor.

ApacheModulemod_ldap

Description: LDAPconnectionpoolingandresultcachingservicesforusebyotherLDAPmodules

Status: ExperimentalModuleIdentifier: ldap_moduleSourceFile: util_ldap.cCompatibility: Availableinversion2.0.41andlater

SummaryThismodulewascreatedtoimprovetheperformanceofwebsitesrelyingonbackendconnectionstoLDAPservers.InadditiontothefunctionsprovidedbythestandardLDAPlibraries,thismoduleaddsanLDAPconnectionpoolandanLDAPsharedmemorycache.

Toenablethismodule,LDAPsupportmustbecompiledintoapr-util.Thisisachievedbyaddingthe--with-ldapflagtotheconfigurescriptwhenbuildingApache.

SSLsupportrequiresthatmod_ldapbelinkedwithoneofthefollowingLDAPSDKs:OpenLDAPSDK(both1.xand2.x),NovellLDAPSDKortheiPlanet(Netscape)SDK.

ExampleConfiguration

Thefollowingisanexampleconfigurationthatusesmod_ldaptoincreasetheperformanceofHTTPBasicauthenticationprovidedbymod_auth_ldap.

#EnabletheLDAPconnectionpoolandshared

#memorycache.EnabletheLDAPcachestatus

#handler.Requiresthatmod_ldapandmod_auth_ldap

#beloaded.Changethe"yourdomain.example.com"to

#matchyourdomain.

LDAPSharedCacheSize200000

LDAPCacheEntries1024

LDAPCacheTTL600

LDAPOpCacheEntries1024

LDAPOpCacheTTL600

SetHandlerldap-status

Orderdeny,allow

Denyfromall

Allowfromyourdomain.example.com

AuthLDAPEnabledon

AuthLDAPURLldap://127.0.0.1/dc=example,dc=com?uid?one

AuthLDAPAuthoritativeon

Requirevalid-user

</Location>

LDAPConnectionPool

LDAPconnectionsarepooledfromrequesttorequest.ThisallowstheLDAPservertoremainconnectedandboundreadyforthenextrequest,withouttheneedtounbind/connect/rebind.TheperformanceadvantagesaresimilartotheeffectofHTTPkeepalives.

OnabusyserveritispossiblethatmanyrequestswilltryandaccessthesameLDAPserverconnectionsimultaneously.WhereanLDAPconnectionisinuse,Apachewillcreateanewconnectionalongsidetheoriginalone.Thisensuresthattheconnectionpooldoesnotbecomeabottleneck.

ThereisnoneedtomanuallyenableconnectionpoolingintheApacheconfiguration.AnymoduleusingthismoduleforaccesstoLDAPserviceswillsharetheconnectionpool.

LDAPCache

Forimprovedperformance,mod_ldapusesanaggressivecachingstrategytominimizethenumberoftimesthattheLDAPservermustbecontacted.CachingcaneasilydoubleortriplethethroughputofApachewhenitisservingpagesprotectedwithmod_auth_ldap.Inaddition,theloadontheLDAPserverwillbesignificantlydecreased.

mod_ldapsupportstwotypesofLDAPcachingduringthesearch/bindphasewithasearch/bindcacheandduringthecomparephasewithtwooperationcaches.EachLDAPURLthatisusedbytheserverhasitsownsetofthesethreecaches.

TheSearch/BindCacheTheprocessofdoingasearchandthenabindisthemosttime-consumingaspectofLDAPoperation,especiallyifthedirectoryislarge.Thesearch/bindcacheisusedtocacheallsearchesthatresultedinsuccessfulbinds.Negativeresults(i.e.,unsuccessfulsearches,orsearchesthatdidnotresultinasuccessfulbind)arenotcached.Therationalebehindthisdecisionisthatconnectionswithinvalidcredentialsareonlyatinypercentageofthetotalnumberofconnections,sobynotcachinginvalidcredentials,thesizeofthecacheisreduced.

mod_ldapstorestheusername,theDNretrieved,thepasswordusedtobind,andthetimeofthebindinthecache.Wheneveranewconnectionisinitiatedwiththesameusername,mod_ldapcomparesthepasswordofthenewconnectionwiththepasswordinthecache.Ifthepasswordsmatch,andifthecachedentryisnottooold,mod_ldapbypassesthesearch/bindphase.

ThesearchandbindcacheiscontrolledwiththeLDAPCacheEntriesandLDAPCacheTTLdirectives.

OperationCachesDuringattributeanddistinguishednamecomparisonfunctions,mod_ldapusestwooperationcachestocachethecompareoperations.ThefirstcomparecacheisusedtocachetheresultsofcomparesdonetotestforLDAPgroupmembership.Thesecondcomparecacheisusedtocachetheresultsofcomparisonsdonebetweendistinguishednames.

ThebehaviorofbothofthesecachesiscontrolledwiththeLDAPOpCacheEntriesandLDAPOpCacheTTLdirectives.

MonitoringtheCachemod_ldaphasacontenthandlerthatallowsadministratorstomonitorthecacheperformance.Thenameofthecontenthandlerisldap-status,sothefollowingdirectivescouldbeusedtoaccessthemod_ldapcacheinformation:

</Location>

ByfetchingtheURLhttp://servername/cache-info,theadministratorcangetastatusreportofeverycachethatisusedbymod_ldapcache.NotethatifApachedoesnotsupportsharedmemory,theneachhttpdinstancehasitsowncache,soreloadingtheURLwillresultindifferentinformationeachtime,dependingonwhichhttpdinstanceprocessestherequest.

UsingSSL

TheabilitytocreateanSSLconnectionstoanLDAPserverisdefinedbythedirectivesLDAPTrustedCAandLDAPTrustedCAType.Thesedirectivesspecifythecertificatefileordatabaseandthecertificatetype.WhenevertheLDAPurlincludesldaps://,mod_ldapwillestablishasecureconnectiontotheLDAPserver.

#EstablishanSSLLDAPconnection.Requiresthat

#mod_ldapandmod_auth_ldapbeloaded.Changethe

#"yourdomain.example.com"tomatchyourdomain.

LDAPTrustedCA/certs/certfile.der

LDAPTrustedCATypeDER_FILE

Orderdeny,allow

Denyfromall

Allowfromyourdomain.example.com

AuthLDAPEnabledon

AuthLDAPURLldaps://127.0.0.1/dc=example,dc=com?uid?one

AuthLDAPAuthoritativeon

Requirevalid-user

</Location>

Ifmod_ldapislinkedagainsttheNetscape/iPlanetLDAPSDK,itwillnottalktoanySSLserverunlessthatserverhasacertificatesignedbyaknownCertificateAuthority.Aspartoftheconfigurationmod_ldapneedstobetoldwhereitcanfindadatabasecontainingtheknownCAs.ThisdatabaseisinthesameformatasNetscapeCommunicator'scert7.dbdatabase.TheeasiestwaytogetthisfileistostartupafreshcopyofNetscape,andgrabtheresulting$HOME/.netscape/cert7.dbfile.

LDAPCacheEntriesDirective

Description: MaximumnumberofentriesintheprimaryLDAPcache

Syntax: LDAPCacheEntriesnumber

Default: LDAPCacheEntries1024

Context: serverconfigStatus: ExperimentalModule: mod_ldap

SpecifiesthemaximumsizeoftheprimaryLDAPcache.Thiscachecontainssuccessfulsearch/binds.Setitto0toturnoffsearch/bindcaching.Thedefaultsizeis1024cachedsearches.

LDAPCacheTTLDirective

Description: TimethatcacheditemsremainvalidSyntax: LDAPCacheTTLseconds

Default: LDAPCacheTTL600

Specifiesthetime(inseconds)thataniteminthesearch/bindcacheremainsvalid.Thedefaultis600seconds(10minutes).

LDAPConnectionTimeoutDirective

Description: SpecifiesthesocketconnectiontimeoutinsecondsSyntax: LDAPConnectionTimeoutseconds

Specifiesthetimeoutvalue(inseconds)inwhichthemodulewillattempttoconnecttotheLDAPserver.Ifaconnectionisnotsuccessfulwiththetimeoutperiod,eitheranerrorwillbereturnedorthemodulewillattempttoconnecttoasecondaryLDAPserverifoneisspecified.Thedefaultis10seconds.

LDAPOpCacheEntriesDirective

Description: NumberofentriesusedtocacheLDAPcompareoperations

Syntax: LDAPOpCacheEntriesnumber

Default: LDAPOpCacheEntries1024

Thisspecifiesthenumberofentriesmod_ldapwillusetocacheLDAPcompareoperations.Thedefaultis1024entries.Settingitto0disablesoperationcaching.

LDAPOpCacheTTLDirective

Description: Timethatentriesintheoperationcacheremainvalid

Syntax: LDAPOpCacheTTLseconds

Default: LDAPOpCacheTTL600

Specifiesthetime(inseconds)thatentriesintheoperationcacheremainvalid.Thedefaultis600seconds.

LDAPSharedCacheFileDirective

Description: SetsthesharedmemorycachefileSyntax: LDAPSharedCacheFiledirectory-

path/filename

Specifiesthedirectorypathandfilenameofthesharedmemorycachefile.Ifnotset,anonymoussharedmemorywillbeusediftheplatformsupportsit.

LDAPSharedCacheSizeDirective

Description: Sizeinbytesoftheshared-memorycacheSyntax: LDAPSharedCacheSizebytes

Default: LDAPSharedCacheSize102400

Specifiesthenumberofbytestoallocateforthesharedmemorycache.Thedefaultis100kb.Ifsetto0,sharedmemorycachingwillnotbeused.

LDAPTrustedCADirective

Description: SetsthefilecontainingthetrustedCertificateAuthoritycertificateordatabase

Syntax: LDAPTrustedCAdirectory-path/filename

ItspecifiesthedirectorypathandfilenameofthetrustedCAmod_ldapshouldusewhenestablishinganSSLconnectiontoanLDAPserver.IfusingtheNetscape/iPlanetDirectorySDK,thefilenameshouldbecert7.db.

LDAPTrustedCATypeDirective

Description: SpecifiesthetypeoftheCertificateAuthorityfileSyntax: LDAPTrustedCATypetype

Thefollowingtypesaresupported:DER_FILE-fileinbinaryDERformatBASE64_FILE-fileinBase64formatCERT7_DB_PATH-Netscapecertificatedatabasefile")

||FAQ||

Apachemod_log_config

:: Base: log_config_module: mod_log_config.c

: TransferLog

TransferLog CustomLog

Apache

LogFormat CustomLog

" %" "%"

%% ( Apache2.0.44)%...a IP%...A IP%...B HTTP%...b HTTPCLF 10%...

{Foobar}C

Foobar

{FOOBAR}e

FOOBAR

{Foobar}i

Foobar:

%...l (identd) IdentityCheck

-%...m

{Foobar}n

Foobar

{Foobar}o

Foobar:

%...P ID%...

{format}P IDID format2.0.46 )

%...q ( ? )%...r

%...s ---%...t CLF()%...

{format}t

formatformat strftime(3)

%...u (( %s) 401)%...U URL%...v ServerName

%...V UseCanonicalName%...X :

X=+=-=

(Apache 1.3{var}c)

%...I 0%...O 0

"..."( "%h%u%r%s%b") ("!" "%400,501{User-agent}i"400501RequestNotImplemented) User-agent:"%!200,304,302{Referer}i" Referer:

"<"">"

httpd2.01.3.25 %...r,%...i,%...oLogFormat

2.0.46 C( \n,\t)

CommonLogFormat(CLF)"%h%l%u%t\"%r\"%>s%b"

CommonLogFormat"%v%h%l%u%t\"%r\"%>s%b"

NCSAextended/combined"%h%l%u%t\"%r\"%>s%b\"%{Referer}i\"

\"%{User-agent}i\""

Referer"%{Referer}i->%U"

Agent()"%{User-agent}i"

%v %p ServerName

UseCanonicalName

BufferedLogs

: Bufferlogentriesinmemorybeforewritingtodisk: BufferedLogsOn|Off

: BufferedLogsOff

:: Base: mod_log_config: Availableinversions2.0.41andlater.

CookieLog

:: CookieLogfilename

: ,: Base: mod_log_config:

CookieLog filename

CustomLog

:: CustomLogfile|pipeformat|nickname[env=

[!]environment-variable]

: ,: Base: mod_log_config

CustomLog

fileServerRoot

pipe" |"

LogFormat

#CustomLogwithformatnickname

#CustomLogwithexplicitformatstring

CustomLoglogs/access_log"%h%l%u%t\"%r\"%>s%b"

mod_setenvif mod_rewrite

SetEnvIfRequest_URI\.gif$gif-image

CustomLoggif-requests.logcommonenv=gif-image

CustomLognongif-requests.logcommonenv=!gif-image

LogFormat

:: LogFormatformat|nickname[nickname]

: LogFormat"%h%l%u%t\"%r\"%>s%b"

LogFormat LogFormat nickname

LogFormat format nickname LogFormat CustomLog nicknameNickname (

LogFormat"%v%h%l%u%t\"%r\"%>s%b"vhost_common

||FAQ||

TransferLog

:: TransferLogfile|pipe

LogFormat

LogFormat"%h%l%u%t\"%r\"%>s%b\"%{Referer}i\"\"%{User-

agent}i\""

TransferLoglogs/access_log

ApacheModulemod_log_forensic

Description: ForensicLoggingoftherequestsmadetotheserver

Status: ExtensionModuleIdentifier: log_forensic_moduleSourceFile: mod_log_forensic.cCompatibility: Availableinversion2.0.50andlater

SummaryThismoduleprovidesforforensicloggingofclientrequests.Loggingisdonebeforeandafterprocessingarequest,sotheforensiclogcontainstwologlinesforeachrequest.Theforensicloggerisverystrict,whichmeans:

Theformatisfixed.Youcannotmodifytheloggingformatatruntime.Ifitcannotwriteitsdata,thechildprocessexitsimmediatelyandmaydumpcore(dependingonyourCoreDumpDirectoryconfiguration).

Thecheck_forensicscript,whichcanbefoundinthedistribution'ssupportdirectory,maybehelpfulinevaluatingtheforensiclogoutput.

Thismodulewasbackportedfromversion2.1whichusesamorepowerfulAPRversioninordertogeneratetheforensicIDs.Ifyouwanttorunmod_log_forensicinversion2.0,youneedtoincludemod_unique_idaswell.

SeealsoApacheLogFiles

mod_log_config

ForensicLogFormat

Eachrequestisloggedtwotimes.Thefirsttimeisbeforeit'sprocessedfurther(thatis,afterreceivingtheheaders).Thesecondlogentryiswrittenaftertherequestprocessingatthesametimewherenormalloggingoccurs.

Inordertoidentifyeachrequest,auniquerequestIDisassigned.ThisforensicIDcanbecrossloggedinthenormaltransferlogusingthe%{forensic-id}nformatstring.Ifyou'reusingmod_unique_id,itsgeneratedIDwillbeused.

ThefirstlinelogstheforensicID,therequestlineandallreceivedheaders,separatedbypipecharacters(|).Asamplelinelookslikethefollowing(allononeline):

+yQtJf8CoAB4AAFNXBIEAAAAA|GET/manual/de/images/down.gif

HTTP/1.1|Host:localhost%3a8080|User-Agent:Mozilla/5.0(X11;U;

Linuxi686;en-US;rv%3a1.6)Gecko/20040216

Firefox/0.8|Accept:image/png,etc...

Thepluscharacteratthebeginningindicatesthatthisisthefirstloglineofthisrequest.ThesecondlinejustcontainsaminuscharacterandtheIDagain:

-yQtJf8CoAB4AAFNXBIEAAAAA

Thecheck_forensicscripttakesasitsargumentthenameofthelogfile.Itlooksforthose+/-IDpairsandcomplainsifarequestwasnotcompleted.

Seethesecuritytipsdocumentfordetailsonwhyyoursecuritycouldbecompromisedifthedirectorywherelogfilesarestorediswritablebyanyoneotherthantheuserthatstartstheserver.

ForensicLogDirective

Description: SetsfilenameoftheforensiclogSyntax: ForensicLogfilename|pipe

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_log_forensic

TheForensicLogdirectiveisusedtologrequeststotheserverforforensicanalysis.EachlogentryisassignedauniqueIDwhichcanbeassociatedwiththerequestusingthenormalCustomLogdirective.mod_log_forensictakestheuniqueIDfrommod_unique_id,soyouneedtoloadthismoduleaswell.(Thisrequirementwillnotbenecessaryinversion2.1andlater,becauseofamorepowerfulAPRversion.)TheIDtokenisattachedtotherequestunderthenameforensic-id,whichcanbeaddedtothetransferlogusingthe%{forensic-id}nformatstring.

Theargument,whichspecifiesthelocationtowhichthelogswillbewritten,cantakeoneofthefollowingtwotypesofvalues:

filenameAfilename,relativetotheServerRoot.

pipeThepipecharacter"|",followedbythepathtoaprogramtoreceivetheloginformationonitsstandardinput.TheprogramnamecanbespecifiedrelativetotheServerRootdirective.

Security:

Ifaprogramisused,thenitwillberunastheuserwhostartedhttpd.Thiswillberootiftheserverwasstartedbyroot;besurethattheprogramissecureorswitchestoa

lessprivilegeduser.

Whenenteringafilepathonnon-Unixplatforms,careshouldbetakentomakesurethatonlyforwardslashedareusedeventhoughtheplatformmayallowtheuseofbackslashes.Ingeneralitisagoodideatoalwaysuseforwardslashesthroughouttheconfigurationfiles.

||FAQ||

Apachemod_logio

:: Extension: logio_module: mod_logio.c

mod_log_config

Apache

||FAQ||

%...I 0

%...O 0

I/O:"%h%l%u%t\"%r\"%>s%b\"%{Referer}i\"

\"%{User-agent}i\"%I%O"

||FAQ||

Apachemod_mem_cache

: URI: Experimental: mem_cache_module: mod_mem_cache.c

mod_cache mod_cache mod_proxy ProxyPass( )

mod_cache

mod_disk_cache

MCacheMaxObjectCount

:: MCacheMaxObjectCountvalue

: MCacheMaxObjectCount1009

:: Experimental: mod_mem_cache

MCacheMaxObjectCount MCacheRemovalAlgorithm

MCacheMaxObjectCount13001

MCacheMaxObjectSize

: (): MCacheMaxObjectSizebytes

: MCacheMaxObjectSize10000

MCacheMaxObjectSize

MCacheMaxObjectSize6400000

MCacheMaxObjectSize MCacheMinObjectSize

: : MCacheMaxStreamingBuffersize_in_bytes

: MCacheMaxStreamingBufferof100000

MCacheMaxObjectSize

MCacheMaxStreamingBuffer Length MCacheMaxStreamingBuffer Content-Length

#Enablecachingofstreamedresponsesupto64KB:

MCacheMaxStreamingBuffer65536

MCacheMinObjectSize

: (): MCacheMinObjectSizebytes

: MCacheMinObjectSize0

MCacheMinObjectSize

MCacheMinObjectSize10000

:: MCacheRemovalAlgorithmLRU|GDSF

: MCacheRemovalAlgorithmGDSF

LRU(LeastRecentlyUsed)LRU

GDSF(GreadyDual-Size)GDSF

MCacheRemovalAlgorithmGDSF

MCacheRemovalAlgorithmLRU

||FAQ||

MCacheSize

:: MCacheSizeKBytes

: MCacheSize100

MCacheSize (1024)MCacheRemovalAlgorithm

MCacheSize700000

MCacheSize MCacheMaxObjectSize

||FAQ||

Apachemod_mime

: ()(MIME)

: Base: mime_module: mod_mime.c

AddCharset AddEncoding AddHandlerAddLanguage AddType content-encoding,content-language,MIME(content-type)TypesConfig MIME

mod_mime AddHandler

AddInputFilter mod_negotiationMultiviews

mod_mime core (,<Location> SetOutputFilter mod_mime

Last-Modified 'touch' ()

MimeMagicFile

AddDefaultCharset

ForceType

DefaultType

SetHandler

SetInputFilter

SetOutputFilter

welcome.html.fr text/htmlwelcome.fr.html

image/gif .htmlMIME text/htmlwelcome.gif.html MIME text/html

en,de Content-Type:text/html

MIME .htmlMIME text/html world.imap.html

imap-file text/htmlMIMEmod_imap

MIME UUencoding

HTTP/1.1RFC14.11

Content-Encoding Content-Encoding

MicrosoftWord pkzip.zip pkzip

Apache

Content-encoding:pkzip

mime (MIME AddType ( MimeMagicFile

AddInputFilter,AddOutputFilter

CharsetApache Content-Language

Content-Language:en,fr

Content-Type:text/plain;charset=ISO-8859-1

charset

AddCharset

:: AddCharsetcharsetextension[extension]...

: ,,,.htaccess: FileInfo: Base: mod_mime

AddCharset charsetMIMEcharset

AddLanguageja.ja

AddCharsetEUC-JP.euc

AddCharsetISO-2022-JP.jis

AddCharsetSHIFT_JIS.sjis

xxxx.ja.jischarset ISO-2022-JP(xxxx.jis.ja) AddCharsetcharset

extension

mod_negotiation

AddDefaultCharset

AddEncoding

: : AddEncodingMIME-encextension[extension]

AddEncoding extension

AddEncodingx-gzip.gz

AddEncodingx-compress.Z

.gz x-gzip

x-zip x-compress x-Apache compress deflate

extension

AddHandler

:: AddHandlerhandler-nameextension[extension]

extension handler-name ".cgi"CGI

AddHandlercgi-script.cgi

httpd.conf ".cgi"CGI

extension

SetHandler

AddInputFilter

: : AddInputFilterfilter[;filter...]extension

[extension]...

: ,,,.htaccess: FileInfo: Base: mod_mime: 2.0.26

AddInputFilter extensionPOSTSetInputFilter

RemoveInputFilter

SetInputFilter

AddLanguage

:: AddLanguageMIME-langextension[extension]

AddLanguage contentlanguageextensionMIME

AddEncodingx-compress.Z

AddLanguageen.en

AddLanguagefr.fr

xxxx.en.Zcompress (language

AddLanguageen.en

AddLanguageen-gb.en

AddLanguageen-us.en

.en en-us

extension

mod_negotiation

AddOutputFilter

: : AddOutputFilterfilter[;filter...]extension

[extension]...

AddOutputFilter extension AddOutputFilterByType

.shtmlSSI mod_deflate

AddOutputFilterINCLUDES;DEFLATEshtml

RemoveOutputFilter

SetOutputFilter

AddType

:: AddTypeMIME-typeextension[extension]...

AddType extension MIME(

AddTypeimage/gif.gif

MIME TypesConfig AddType

extension

DefaultType

ForceType

DefaultLanguage

: : DefaultLanguageMIME-lang

DefaultLanguageApache ((AddLanguage .fr .de) MIME-lang DefaultLanguage

DefaultLanguage AddLanguage

DefaultLanguageen

mod_negotiation

ModMimeUsePathInfo

: path_infomod_mime: ModMimeUsePathInfoOn|Off

: ModMimeUsePathInfoOff

:: Base: mod_mime: Apache2.0.41

ModMimeUsePathInfo mod_mimeURL Off path_info

ModMimeUsePathInfoOn

/bar(foo.shtml) ModMimeUsePathInfo On

/bar/foo.shtml mod_mimeAddOutputFileterINCLUDES.shtml INCLUDES

ModMimeUsePathInfo INCLUDES

AcceptPathInfo

MultiviewsMatch

: MultiViews: MultiviewsMatch

Any|NegotiatedOnly|Filters|Handlers

[Handlers|Filters]

: MultiviewsMatchNegotiatedOnly

MultiviewsMatch mod_negotiation Multiviews3Multiviews( index.html)index.html.fr index.html.gz)

NegotiatedOnly

MultiviewsMatch

500 index.html.cgi1000 index.html.pl.cgi .asis .asis

mod_mime Any

Multiviews

MultiviewsMatchHandlersFilters

Options

mod_negotiation

RemoveCharset

: : RemoveCharsetextension[extension]...

: ,,.htaccess: FileInfo: Base: mod_mime: 2.0.24

RemoveCharset

extension

RemoveCharset.html.shtml

RemoveEncoding

: : RemoveEncodingextension[extension]...

: ,,.htaccess: FileInfo: Base: mod_mime

RemoveEncoding

/foo/.htaccess:AddEncodingx-gzip.gz

AddTypetext/plain.asc

<Files*.gz.asc>

RemoveEncoding.gz

</Files>

foo.gzgzip foo.gz.asc

RemoveEncoding AddEncoding

extension

RemoveHandler

: : RemoveHandlerextension[extension]...

RemoveHandler

/foo/.htaccess:AddHandlerserver-parsed.html

/foo/bar/.htaccess:RemoveHandler.html

/foo/bar .htmlSSI( mod_include)

extension

RemoveInputFilter

:: RemoveInputFilterextension[extension]...

RemoveInputFilter

extension

AddInputFilter

SetInputFilter

RemoveLanguage

:: RemoveLanguageextension[extension]...

RemoveLanguage

extension

RemoveOutputFilter

:: RemoveOutputFilterextension[extension]...

RemoveOutputFilter

extension

RemoveOutputFiltershtml

AddOutputFilter

RemoveType

: : RemoveTypeextension[extension]...

RemoveType MIME

/foo/.htaccess:RemoveType.cgi

/foo/ .cgi DefaultType

RemoveType AddType

extension

||FAQ||

TypesConfig

: mime.types: TypesConfigfile-path

: TypesConfigconf/mime.types

:: Base: mod_mime

TypesConfigMIME IANAhttp://www.isi.edu/in-notes/iana/assignments/media-types/media-types mime.types

AddType

MIME-type[extension]...

(1)IANA(2) ServerProject category/x-subtype

mod_mime_magic

ApacheModulemod_mime_magic

Description: DeterminestheMIMEtypeofafilebylookingatafewbytesofitscontents

Status: ExtensionModuleIdentifier: mime_magic_moduleSourceFile: mod_mime_magic.c

SummaryThismoduledeterminestheMIMEtypeoffilesinthesamewaytheUnixfile(1)commandworks:itlooksatthefirstfewbytesofthefile.Itisintendedasa"secondlineofdefense"forcasesthatmod_mimecan'tresolve.

Thismoduleisderivedfromafreeversionofthefile(1)commandforUnix,whichuses"magicnumbers"andotherhintsfromafile'scontentstofigureoutwhatthecontentsare.ThismoduleisactiveonlyifthemagicfileisspecifiedbytheMimeMagicFiledirective.

FormatoftheMagicFile

ThecontentsofthefileareplainASCIItextin4-5columns.Blanklinesareallowedbutignored.Commentedlinesuseahashmark(#).Theremaininglinesareparsedforthefollowingcolumns:

Column Description1 bytenumbertobegincheckingfrom

">"indicatesadependencyuponthepreviousnon-">"line

2 typeofdatatomatch

byte singlecharactershort machine-order16-bitintegerlong machine-order32-bitintegerstring arbitrary-lengthstringdate longintegerdate(secondssinceUnix

epoch/1970)beshort big-endian16-bitintegerbelong big-endian32-bitintegerbedate big-endian32-bitintegerdateleshort little-endian16-bitintegerlelong little-endian32-bitintegerledate little-endian32-bitintegerdate

3 contentsofdatatomatch4 MIMEtypeifmatched5 MIMEencodingifmatched(optional)

Forexample,thefollowingmagicfilelineswouldrecognizesomeaudioformats:

#Sun/NeXTaudiodata

0string.snd

>12belong1audio/basic

>12belong23audio/x-adpcm

Orthesewouldrecognizethedifferencebetween*.docfilescontainingMicrosoftWordorFrameMakerdocuments.(Theseareincompatiblefileformatswhichusethesamefilesuffix.)

#Frame

0string\<MakerFileapplication/x-frame

0string\<MIFFileapplication/x-frame

0string\<MakerDictionaryapplication/x-frame

0string\<MakerScreenFonapplication/x-frame

0string\<MMLapplication/x-frame

0string\<Bookapplication/x-frame

0string\<Makerapplication/x-frame

#MS-Word

0string\376\067\0\043application/msword

0string\320\317\021\340\241\261application/msword

0string\333\245-\0\0\0application/msword

AnoptionalMIMEencodingcanbeincludedasafifthcolumn.Forexample,thiscanrecognizegzippedfilesandsettheencodingforthem.

#gzip(GNUzip,nottobeconfusedwith

#[Info-ZIP/PKWARE]ziparchiver)

0string\037\213application/octet-streamx-gzip

PerformanceIssues

Thismoduleisnotforeverysystem.Ifyoursystemisbarelykeepingupwithitsloadorifyou'reperformingawebserverbenchmark,youmaynotwanttoenablethisbecausetheprocessingisnotfree.

However,aneffortwasmadetoimprovetheperformanceoftheoriginalfile(1)codetomakeitfitinabusywebserver.Itwasdesignedforaserverwheretherearethousandsofuserswhopublishtheirowndocuments.Thisisprobablyverycommononintranets.Manytimes,it'shelpfuliftheservercanmakemoreintelligentdecisionsaboutafile'scontentsthanthefilenameallows...evenifjusttoreducethe"whydoesn'tmypagework"callswhenusersimproperlynametheirownfiles.Youhavetodecideiftheextraworksuitsyourenvironment.

Thefollowingnotesapplytothemod_mime_magicmoduleandareincludedhereforcompliancewithcontributors'copyrightrestrictionsthatrequiretheiracknowledgment.

ThissoftwarewassubmittedbyCiscoSystemstotheApacheGroupinJuly1997.FuturerevisionsandderivativesofthissourcecodemustacknowledgeCiscoSystemsastheoriginalcontributorofthismodule.AllotherlicensingandusageconditionsarethoseoftheApacheGroup.

Someofthiscodeisderivedfromthefreeversionofthefilecommandoriginallypostedtocomp.sources.unix.Copyrightinfoforthatprogramisincludedbelowasrequired.

-Copyright(c)IanF.Darwin,1987.WrittenbyIanF.Darwin.

ThissoftwareisnotsubjecttoanylicenseoftheAmericanTelephoneandTelegraphCompanyoroftheRegentsoftheUniversityofCalifornia.

Permissionisgrantedtoanyonetousethissoftwareforanypurposeonanycomputersystem,andtoalteritandredistributeitfreely,subjecttothefollowingrestrictions:

1. Theauthorisnotresponsiblefortheconsequencesofuseofthissoftware,nomatterhowawful,eveniftheyarisefromflawsinit.

2. Theoriginofthissoftwaremustnotbemisrepresented,eitherbyexplicitclaimorbyomission.Sincefewuserseverreadsources,creditsmustappearinthedocumentation.

3. Alteredversionsmustbeplainlymarkedassuch,andmust

notbemisrepresentedasbeingtheoriginalsoftware.Sincefewuserseverreadsources,creditsmustappearinthedocumentation.

4. Thisnoticemaynotberemovedoraltered.

ForcompliancewithMrDarwin'sterms:thishasbeenverysignificantlymodifiedfromthefree"file"command.

all-in-onefileforcompilationconveniencewhenmovingfromoneversionofApachetothenext.MemoryallocationisdonethroughtheApacheAPI'spoolstructure.AllfunctionshavehadnecessaryApacheAPIrequestorserverstructurespassedtothemwherenecessarytocallotherApacheAPIroutines.(i.e.,usuallyforlogging,files,ormemoryallocationinitselforacalledfunction.)structmagichasbeenconvertedfromanarraytoasingle-endedlinkedlistbecauseitonlygrowsonerecordatatime,it'sonlyaccessedsequentially,andtheApacheAPIhasnoequivalentofrealloc().Functionshavebeenchangedtogettheirparametersfromtheserverconfigurationinsteadofglobals.(Itshouldbereentrantnowbuthasnotbeentestedinathreadedenvironment.)Placeswhereitusedtoprintresultstostdoutnowsavestheminalistwherethey'reusedtosettheMIMEtypeintheApacherequestrecord.Command-lineflagshavebeenremovedsincetheywillneverbeusedhere.

MimeMagicFileDirective

Description: EnableMIME-typedeterminationbasedonfilecontentsusingthespecifiedmagicfile

Syntax: MimeMagicFilefile-path

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_mime_magic

TheMimeMagicFiledirectivecanbeusedtoenablethismodule,thedefaultfileisdistributedatconf/magic.Non-rootedpathsarerelativetotheServerRoot.Virtualhostswillusethesamefileasthemainserverunlessamorespecificsettingisused,inwhichcasethemorespecificsettingoverridesthemainserver'sfile.

ExampleMimeMagicFileconf/magic

||FAQ||

Apachemod_negotiation

: : Base: negotiation_module: mod_negotiation.c

( type-map)variantsMultiViews( MultiViewsOption)

Options

mod_mime

RFC822 :

Content-Encoding:

Apache AddEncoding compresscompressgzip x-gzip

Content-Language:

(RFC1766)

Content-Length:

Content-Type:

text/html2

variant 0.01.0 ASCIIASCII

Content-Type:image/jpeg;qs=0.8

()variant uri.

Apache2.0Body

Example:Body:----xyz----

<html>

<body>

<p>Contentofthepage.</p>

</body>

</html>

----xyz----

MultiViews

MultiViews MultiviewsOptions/some/dir/foo

CacheNegotiatedDocs

: : CacheNegotiatedDocsOn|Off

: CacheNegotiatedDocsOff

: ,: Base: mod_negotiation: 2.0

HTTP/1.0 HTTP/1.1

2.0 CacheNegotiatedDocs on

ForceLanguagePriority

:: ForceLanguagePriorityNone|Prefer|Fallback

[Prefer|Fallback]

: ForceLanguagePriorityPrefer

: ,,,.htaccess: FileInfo: Base: mod_negotiation: 2.0.30

ForceLanguagePriorityPrefer HTTP300(MULTIPLECHOICES) LanguagePriorityAccept-Language en de .500()

ForceLanguagePriorityPrefer

ForceLanguagePriorityFallbackHTTP406 (NOTACCEPTABLE) LanguagePriorityLanguage esvariantvariant

ForceLanguagePriorityFallback

Prefer Fallback variant variantvaiant

AddLanguage

||FAQ||

LanguagePriority

: variant: LanguagePriorityMIME-lang[MIME-lang]...

: ,,,.htaccess: FileInfo: Base: mod_negotiation

LanguagePriorityMultiViews

Example:LanguagePriorityenfrde

foo.html foo.html.fr foo.html.defoo.html.fr

AddLanguage

ApacheModulemod_nw_ssl

Description: EnableSSLencryptionforNetWareStatus: BaseModuleIdentifier: nwssl_moduleSourceFile: mod_nw_ssl.cCompatibility: NetWareonly

SummaryThismoduleenablesSSLencryptionforaspecifiedport.IttakesadvantageoftheSSLencryptionfunctionalitythatisbuiltintotheNetWareoperatingsystem.

NWSSLTrustedCertsDirective

Description: ListofadditionalclientcertificatesSyntax: NWSSLTrustedCertsfilename[filename]

Context: serverconfigStatus: BaseModule: mod_nw_ssl

Specifiesalistofclientcertificatefiles(DERformat)thatareusedwhencreatingaproxiedSSLconnection.Eachclientcertificateusedbyaservermustbelistedseparatelyinitsown.derfile.

NWSSLUpgradeableDirective

Description: AllowsaconnectiontobeupgradedtoanSSLconnectionuponrequest

Syntax: NWSSLUpgradeable[IP-

address:]portnumber

Allowaconnectionthatwascreatedonthespecifiedaddressand/orporttobeupgradedtoanSSLconnectionuponrequestfromtheclient.Theaddressand/orportmusthavealreadybedefinedpreviouslywithaListendirective.

SecureListenDirective

Description: EnablesSSLencryptionforthespecifiedportSyntax: SecureListen[IP-address:]portnumber

Certificate-Name[MUTUAL]

SpecifiestheportandtheeDirectorybasedcertificatenamethatwillbeusedtoenableSSLencryption.Anoptionalthirdparameteralsoenablesmutualauthentication.

ApacheModulemod_proxy

Description: HTTP/1.1proxy/gatewayserverStatus: ExtensionModuleIdentifier: proxy_moduleSourceFile: mod_proxy.c

Summary

Warning

DonotenableproxyingwithProxyRequestsuntilyouhavesecuredyourserver.OpenproxyserversaredangerousbothtoyournetworkandtotheInternetatlarge.

Thismoduleimplementsaproxy/gatewayforApache.ItimplementsproxyingcapabilityforFTP,CONNECT(forSSL),HTTP/0.9,HTTP/1.0,andHTTP/1.1.Themodulecanbeconfiguredtoconnecttootherproxymodulesfortheseandotherprotocols.

Apache'sproxyfeaturesaredividedintoseveralmodulesinadditiontomod_proxy:mod_proxy_http,mod_proxy_ftpandmod_proxy_connect.Thus,ifyouwanttouseoneormoreoftheparticularproxyfunctions,loadmod_proxyandtheappropriatemodule(s)intotheserver(eitherstaticallyatcompile-timeordynamicallyviatheLoadModuledirective).

Inaddition,extendedfeaturesareprovidedbyothermodules.Cachingisprovidedbymod_cacheandrelatedmodules.TheabilitytocontactremoteserversusingtheSSL/TLSprotocolisprovidedbytheSSLProxy*directivesofmod_ssl.Theseadditionalmoduleswillneedtobeloadedandconfiguredtotakeadvantageofthesefeatures.

Seealsomod_cache

mod_proxy_http

mod_proxy_ftp

mod_proxy_connect

mod_ssl

ForwardandReverseProxies

Apachecanbeconfiguredinbothaforwardandreverseproxymode.

Anordinaryforwardproxyisanintermediateserverthatsitsbetweentheclientandtheoriginserver.Inordertogetcontentfromtheoriginserver,theclientsendsarequesttotheproxynamingtheoriginserverasthetargetandtheproxythenrequeststhecontentfromtheoriginserverandreturnsittotheclient.Theclientmustbespeciallyconfiguredtousetheforwardproxytoaccessothersites.

AtypicalusageofaforwardproxyistoprovideInternetaccesstointernalclientsthatareotherwiserestrictedbyafirewall.Theforwardproxycanalsousecaching(asprovidedbymod_cache)toreducenetworkusage.

TheforwardproxyisactivatedusingtheProxyRequestsdirective.Becauseforwardproxysallowclientstoaccessarbitrarysitesthroughyourserverandtohidetheirtrueorigin,itisessentialthatyousecureyourserversothatonlyauthorizedclientscanaccesstheproxybeforeactivatingaforwardproxy.

Areverseproxy,bycontrast,appearstotheclientjustlikeanordinarywebserver.Nospecialconfigurationontheclientisnecessary.Theclientmakesordinaryrequestsforcontentinthename-spaceofthereverseproxy.Thereverseproxythendecideswheretosendthoserequests,andreturnsthecontentasifitwasitselftheorigin.

AtypicalusageofareverseproxyistoprovideInternetusersaccesstoaserverthatisbehindafirewall.Reverseproxiescanalsobeusedtobalanceloadamongseveralback-endservers,ortoprovidecachingforaslowerback-endserver.Inaddition,reverseproxiescanbeusedsimplytobringseveralserversinto

thesameURLspace.

AreverseproxyisactivatedusingtheProxyPassdirectiveorthe[P]flagtotheRewriteRuledirective.ItisnotnecessarytoturnProxyRequestsoninordertoconfigureareverseproxy.

BasicExamples

Theexamplesbelowareonlyaverybasicideatohelpyougetstarted.Pleasereadthedocumentationontheindividualdirectives.

Inaddition,ifyouwishtohavecachingenabled,consultthedocumentationfrommod_cache.

ForwardProxyProxyRequestsOn

ProxyViaOn

<Proxy*>

Orderdeny,allow

Denyfromall

Allowfrominternal.example.com

</Proxy>

ReverseProxyProxyRequestsOff

<Proxy*>

Orderdeny,allow

Allowfromall

</Proxy>

ProxyPass/foohttp://foo.example.com/bar

ProxyPassReverse/foohttp://foo.example.com/bar

Controllingaccesstoyourproxy

Youcancontrolwhocanaccessyourproxyviathe<Proxy>controlblockasinthefollowingexample:

<Proxy*>

OrderDeny,Allow

Denyfromall

Allowfrom192.168.0

</Proxy>

Formoreinformationonaccesscontroldirectives,seemod_access.

Strictlylimitingaccessisessentialifyouareusingaforwardproxy(usingtheProxyRequestsdirective).Otherwise,yourservercanbeusedbyanyclienttoaccessarbitraryhostswhilehidinghisorhertrueidentity.ThisisdangerousbothforyournetworkandfortheInternetatlarge.Whenusingareverseproxy(usingtheProxyPassdirectivewithProxyRequestsOff),accesscontrolislesscriticalbecauseclientscanonlycontactthehoststhatyouhavespecificallyconfigured.

FTPProxy

Whydoesn'tfiletypexxxdownloadviaFTP?Youprobablydon'thavethatparticularfiletypedefinedasapplication/octet-streaminyourproxy'smime.typesconfigurationfile.Ausefullinecanbe

application/octet-streambindmslhalzhexeclasstgztaz

HowcanIforceanFTPASCIIdownloadofFilexxx?IntheraresituationwhereyoumustdownloadaspecificfileusingtheFTPASCIItransfermethod(whilethedefaulttransferisinbinarymode),youcanoverridemod_proxy'sdefaultbysuffixingtherequestwith;type=atoforceanASCIItransfer.(FTPDirectorylistingsarealwaysexecutedinASCIImode,however.)

HowcanIaccessFTPfilesoutsideofmyhomedirectory?AnFTPURIisinterpretedrelativetothehomedirectoryoftheuserwhoisloggingin.Alas,toreachhigherdirectorylevelsyoucannotuse/../,asthedotsareinterpretedbythebrowserandnotactuallysenttotheFTPserver.Toaddressthisproblem,thesocalledSquid%2fhackwasimplementedintheApacheFTPproxy;itisasolutionwhichisalsousedbyotherpopularproxyserversliketheSquidProxyCache.Byprepending/%2ftothepathofyourrequest,youcanmakesuchaproxychangetheFTPstartingdirectoryto/(insteadofthehomedirectory).Forexample,toretrievethefile/etc/motd,youwouldusetheURL:

ftp://user@host/%2f/etc/motd

HowcanIhidetheFTPcleartextpasswordinmybrowser'sURLline?TologintoanFTPserverbyusernameandpassword,Apacheusesdifferentstrategies.InabsenseofausernameandpasswordintheURLaltogether,ApachesendsananonymouslogintotheFTPserver,i.e.,

user:anonymous

password:apache_proxy@

ThisworksforallpopularFTPserverswhichareconfiguredforanonymousaccess.

Forapersonalloginwithaspecificusername,youcanembedtheusernameintotheURL,likein:

ftp://username@host/myfile

IftheFTPserverasksforapasswordwhengiventhisusername(whichitshould),thenApachewillreplywitha401(Authorizationrequired)response,whichcausestheBrowsertopopuptheusername/passworddialog.Uponenteringthepassword,theconnectionattemptisretried,andifsuccessful,therequestedresourceispresented.Theadvantageofthisprocedureisthatyourbrowserdoesnotdisplaythepasswordincleartext(whichitwouldifyouhadused

ftp://username:password@host/myfile

inthefirstplace).

Thepasswordwhichistransmittedinsuchawayisnotencryptedonitsway.Ittravelsbetweenyourbrowserandthe

Apacheproxyserverinabase64-encodedcleartextstring,andbetweentheApacheproxyandtheFTPserverasplaintext.YoushouldthereforethinktwicebeforeaccessingyourFTPserverviaHTTP(orbeforeaccessingyourpersonalfilesviaFTPatall!)Whenusingunsecurechannels,aneavesdroppermightinterceptyourpasswordonitsway.

SlowStartup

Ifyou'reusingtheProxyBlockdirective,hostnames'IPaddressesarelookedupandcachedduringstartupforlatermatchtest.Thismaytakeafewseconds(ormore)dependingonthespeedwithwhichthehostnamelookupsoccur.

IntranetProxy

AnApacheproxyserversituatedinanintranetneedstoforwardexternalrequeststhroughthecompany'sfirewall(forthis,configuretheProxyRemotedirectivetoforwardtherespectiveschemetothefirewallproxy).However,whenithastoaccessresourceswithintheintranet,itcanbypassthefirewallwhenaccessinghosts.TheNoProxydirectiveisusefulforspecifyingwhichhostsbelongtotheintranetandshouldbeaccesseddirectly.

UserswithinanintranettendtoomitthelocaldomainnamefromtheirWWWrequests,thusrequesting"http://somehost/"insteadofhttp://somehost.example.com/.Somecommercialproxyserversletthemgetawaywiththisandsimplyservetherequest,implyingaconfiguredlocaldomain.WhentheProxyDomaindirectiveisusedandtheserverisconfiguredforproxyservice,Apachecanreturnaredirectresponseandsendtheclienttothecorrect,fullyqualified,serveraddress.Thisisthepreferredmethodsincetheuser'sbookmarkfileswillthencontainfullyqualifiedhosts.

ProtocolAdjustments

Forcircumstanceswhereyouhaveaapplicationserverwhichdoesn'timplementkeepalivesorHTTP/1.1properly,thereare2environmentvariableswhichwhensetsendaHTTP/1.0withnokeepalive.ThesearesetviatheSetEnvdirective.

Thesearetheforce-proxy-request-1.0andproxy-nokeepalivenotes.

ProxyPasshttp://buggyappserver:7001/foo/

SetEnvforce-proxy-request-1.01

SetEnvproxy-nokeepalive1

</Location>

AllowCONNECTDirective

Description: PortsthatareallowedtoCONNECTthroughtheproxy

Syntax: AllowCONNECTport[port]...

Default: AllowCONNECT443563

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_proxy

TheAllowCONNECTdirectivespecifiesalistofportnumberstowhichtheproxyCONNECTmethodmayconnect.Today'sbrowsersusethismethodwhenahttpsconnectionisrequestedandproxytunnelingoverHTTPisineffect.

Bydefault,onlythedefaulthttpsport(443)andthedefaultsnewsport(563)areenabled.UsetheAllowCONNECTdirectivetooverridethisdefaultandallowconnectionstothelistedportsonly.

Notethatyou'llneedtohavemod_proxy_connectpresentintheserverinordertogetthesupportfortheCONNECTatall.

NoProxyDirective

Description: Hosts,domains,ornetworksthatwillbeconnectedtodirectly

Syntax: NoProxyhost[host]...

ThisdirectiveisonlyusefulforApacheproxyserverswithinintranets.TheNoProxydirectivespecifiesalistofsubnets,IPaddresses,hostsand/ordomains,separatedbyspaces.Arequesttoahostwhichmatchesoneormoreoftheseisalwaysserveddirectly,withoutforwardingtotheconfiguredProxyRemoteproxyserver(s).

ExampleProxyRemote*http://firewall.example.com:81

NoProxy.example.com192.168.112.0/21

ThehostargumentstotheNoProxydirectiveareoneofthefollowingtypelist:

DomainADomainisapartiallyqualifiedDNSdomainname,precededbyaperiod.ItrepresentsalistofhostswhichlogicallybelongtothesameDNSdomainorzone(i.e.,thesuffixesofthehostnamesareallendinginDomain).

Examples.com.apache.org.

TodistinguishDomainsfromHostnames(bothsyntacticallyandsemantically;aDNSdomaincanhaveaDNSArecord,

too!),Domainsarealwayswrittenwithaleadingperiod.

Domainnamecomparisonsaredonewithoutregardtothecase,andDomainsarealwaysassumedtobeanchoredintherootoftheDNStree,thereforetwodomains.MyDomain.comand.mydomain.com.(notethetrailingperiod)areconsideredequal.SinceadomaincomparisondoesnotinvolveaDNSlookup,itismuchmoreefficientthansubnetcomparison.

SubNetASubNetisapartiallyqualifiedinternetaddressinnumeric(dottedquad)form,optionallyfollowedbyaslashandthenetmask,specifiedasthenumberofsignificantbitsintheSubNet.Itisusedtorepresentasubnetofhostswhichcanbereachedoveracommonnetworkinterface.Intheabsenceoftheexplicitnetmaskitisassumedthatomitted(orzerovalued)trailingdigitsspecifythemask.(Inthiscase,thenetmaskcanonlybemultiplesof8bitswide.)Examples:

192.168or192.168.0.0thesubnet192.168.0.0withanimpliednetmaskof16validbits(sometimesusedinthenetmaskform255.255.0.0)

192.168.112.0/21

thesubnet192.168.112.0/21withanetmaskof21validbits(alsousedintheform255.255.248.0)

Asadegeneratecase,aSubNetwith32validbitsistheequivalenttoanIPAddr,whileaSubNetwithzerovalidbits(e.g.,0.0.0.0/0)isthesameastheconstant_Default_,matchinganyIPaddress.

IPAddrAIPAddrrepresentsafullyqualifiedinternetaddressinnumeric(dottedquad)form.Usually,thisaddressrepresentsahost,butthereneednotnecessarilybeaDNSdomainnameconnectedwiththeaddress.

Example192.168.123.7

AnIPAddrdoesnotneedtoberesolvedbytheDNSsystem,soitcanresultinmoreeffectiveapacheperformance.

HostnameAHostnameisafullyqualifiedDNSdomainnamewhichcanberesolvedtooneormoreIPAddrsviatheDNSdomainnameservice.Itrepresentsalogicalhost(incontrasttoDomains,seeabove)andmustberesolvabletoatleastoneIPAddr(oroftentoalistofhostswithdifferentIPAddrs).

Examplesprep.ai.mit.edu

www.apache.org

Inmanysituations,itismoreeffectivetospecifyanIPAddrinplaceofaHostnamesinceaDNSlookupcanbeavoided.NameresolutioninApachecantakearemarkabledealoftimewhentheconnectiontothenameserverusesaslowPPPlink.

Hostnamecomparisonsaredonewithoutregardtothe

case,andHostnamesarealwaysassumedtobeanchoredintherootoftheDNStree,thereforetwohostsWWW.MyDomain.comandwww.mydomain.com.(notethetrailingperiod)areconsideredequal.

SeealsoDNSIssues

<Proxy>Directive

Description: Containerfordirectivesappliedtoproxiedresources

Syntax: <Proxywildcard-url>...</Proxy>

Directivesplacedin<Proxy>sectionsapplyonlytomatchingproxiedcontent.Shell-stylewildcardsareallowed.

Forexample,thefollowingwillallowonlyhostsinyournetwork.example.comtoaccesscontentviayourproxyserver:

<Proxy*>

OrderDeny,Allow

Denyfromall

Allowfromyournetwork.example.com

</Proxy>

Thefollowingexamplewillprocessallfilesinthefoodirectoryofexample.comthroughtheINCLUDESfilterwhentheyaresentthroughtheproxyserver:

<Proxyhttp://example.com/foo/*>

</Proxy>

ProxyBadHeaderDirective

Description: Determineshowtohandlebadheaderlinesinaresponse

Syntax: ProxyBadHeader

IsError|Ignore|StartBody

Default: ProxyBadHeaderIsError

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_proxyCompatibility: AvailableinApache2.0.44andlater

TheProxyBadHeaderdirectivedeterminesthebehaviourofmod_proxyifitreceivessyntacticallyinvalidheaderlines(i.e.containingnocolon).Thefollowingargumentsarepossible:

IsError

Aborttherequestandendupwitha502(BadGateway)response.Thisisthedefaultbehaviour.

Ignore

Treatbadheaderlinesasiftheyweren'tsent.

StartBody

Whenreceivingthefirstbadheaderline,finishreadingtheheadersandtreattheremainderasbody.Thishelpstoworkaroundbuggybackendserverswhichforgettoinsertanemptylinebetweentheheadersandthebody.

ProxyBlockDirective

Description: Words,hosts,ordomainsthatarebannedfrombeingproxied

Syntax: ProxyBlock*|word|host|domain

[word|host|domain]...

TheProxyBlockdirectivespecifiesalistofwords,hostsand/ordomains,separatedbyspaces.HTTP,HTTPS,andFTPdocumentrequeststositeswhosenamescontainmatchedwords,hostsordomainsareblockedbytheproxyserver.TheproxymodulewillalsoattempttodetermineIPaddressesoflistitemswhichmaybehostnamesduringstartup,andcachethemformatchtestaswell.Thatmayslowdownthestartuptimeoftheserver.

ExampleProxyBlockjoes-garage.comsome-host.co.uk

rocky.wotsamattau.edu

rocky.wotsamattau.eduwouldalsobematchedifreferencedbyIPaddress.

Notethatwotsamattauwouldalsobesufficienttomatchwotsamattau.edu.

Notealsothat

ProxyBlock*

blocksconnectionstoallsites.

ProxyDomainDirective

Description: DefaultdomainnameforproxiedrequestsSyntax: ProxyDomainDomain

ThisdirectiveisonlyusefulforApacheproxyserverswithinintranets.TheProxyDomaindirectivespecifiesthedefaultdomainwhichtheapacheproxyserverwillbelongto.Ifarequesttoahostwithoutadomainnameisencountered,aredirectionresponsetothesamehostwiththeconfiguredDomainappendedwillbegenerated.

ExampleProxyRemote*http://firewall.example.com:81

NoProxy.example.com192.168.112.0/21

ProxyDomain.example.com

ProxyErrorOverrideDirective

Description: OverrideerrorpagesforproxiedcontentSyntax: ProxyErrorOverrideOn|Off

Default: ProxyErrorOverrideOff

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_proxyCompatibility: Availableinversion2.0andlater

Thisdirectiveisusefulforreverse-proxysetups,whereyouwanttohaveacommonlookandfeelontheerrorpagesseenbytheenduser.Thisalsoallowsforincludedfiles(viamod_include'sSSI)togettheerrorcodeandactaccordingly(defaultbehaviorwoulddisplaytheerrorpageoftheproxiedserver,turningthisonshowstheSSIErrormessage).

ProxyFtpDirCharsetDirective

Description: DefinethecharactersetforproxiedFTPlistingsSyntax: ProxyFtpDirCharsetcharacterset

Default: ProxyFtpDirCharsetISO-8859-1

Context: serverconfig,virtualhost,directoryStatus: ExtensionModule: mod_proxyCompatibility: AvailableinApache2.0.62andlater

TheProxyFtpDirCharsetdirectivedefinesthecharactersettobesetforFTPdirectorylistingsinHTMLgeneratedbymod_proxy_ftp.

ProxyIOBufferSizeDirective

Description: DeterminesizeofinternaldatathroughputbufferSyntax: ProxyIOBufferSizebytes

Default: ProxyIOBufferSize8192

TheProxyIOBufferSizedirectiveadjuststhesizeoftheinternalbuffer,whichisusedasascratchpadforthedatabetweeninputandoutput.Thesizemustbelessorequal8192.

Inalmosteverycasethere'snoreasontochangethatvalue.

<ProxyMatch>Directive

Description: Containerfordirectivesappliedtoregular-expression-matchedproxiedresources

Syntax: <ProxyMatchregex>...</ProxyMatch>

The<ProxyMatch>directiveisidenticaltothe<Proxy>directive,exceptitmatchesURLsusingregularexpressions.

ProxyMaxForwardsDirective

Description: Maximiumnumberofproxiesthatarequestcanbeforwardedthrough

Syntax: ProxyMaxForwardsnumber

Default: ProxyMaxForwards10

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_proxyCompatibility: AvailableinApache2.0andlater

TheProxyMaxForwardsdirectivespecifiesthemaximumnumberofproxiesthroughwhicharequestmaypass,ifthere'snoMax-Forwardsheadersuppliedwiththerequest.Thisissettopreventinfiniteproxyloops,oraDoSattack.

ExampleProxyMaxForwards15

ProxyPassDirective

Description: MapsremoteserversintothelocalserverURL-space

Syntax: ProxyPass[path]!|url

Context: serverconfig,virtualhost,directoryStatus: ExtensionModule: mod_proxy

Thisdirectiveallowsremoteserverstobemappedintothespaceofthelocalserver;thelocalserverdoesnotactasaproxyintheconventionalsense,butappearstobeamirroroftheremoteserver.pathisthenameofalocalvirtualpath;urlisapartialURLfortheremoteserverandcannotincludeaquerystring.

Supposethelocalserverhasaddresshttp://example.com/;then

ProxyPass/mirror/foo/http://backend.example.com/

willcausealocalrequestforhttp://example.com/mirror/foo/bartobeinternallyconvertedintoaproxyrequesttohttp://backend.example.com/bar.

The!directiveisusefulinsituationswhereyoudon'twanttoreverse-proxyasubdirectory,e.g.

ProxyPass/mirror/foo/i!

ProxyPass/mirror/foohttp://backend.example.com

willproxyallrequeststo/mirror/footobackend.example.comexceptrequestsmadeto/mirror/foo/i.

Orderisimportant.youneedtoputtheexclusionsbeforethegeneralproxypassdirective.

Whenusedinsidea<Location>section,thefirstargumentisomittedandthelocaldirectoryisobtainedfromthe<Location>.

TheProxyRequestsdirectiveshouldusuallybesetoffwhenusingProxyPass.

Ifyourequireamoreflexiblereverse-proxyconfiguration,seetheRewriteRuledirectivewiththe[P]flag.

ProxyPassReverseDirective

Description: AdjuststheURLinHTTPresponseheaderssentfromareverseproxiedserver

Syntax: ProxyPassReverse[path]url

Context: serverconfig,virtualhost,directoryStatus: ExtensionModule: mod_proxy

ThisdirectiveletsApacheadjusttheURLintheLocation,Content-LocationandURIheadersonHTTPredirectresponses.ThisisessentialwhenApacheisusedasareverseproxytoavoidby-passingthereverseproxybecauseofHTTPredirectsonthebackendserverswhichstaybehindthereverseproxy.

OnlytheHTTPresponseheadersspecificallymentionedabovewillberewritten.Apachewillnotrewriteotherresponseheaders,norwillitrewriteURLreferencesinsideHTMLpages.ThismeansthatiftheproxiedcontentcontainsabsoluteURLreferences,theywillby-passtheproxy.Athird-partymodulethatwilllookinsidetheHTMLandrewriteURLreferencesisNickKew'smod_proxy_html.

pathisthenameofalocalvirtualpath.urlisapartialURLfortheremoteserver-thesamewaytheyareusedfortheProxyPassdirective.

Forexample,supposethelocalserverhasaddresshttp://example.com/;then

ProxyPass/mirror/foo/http://backend.example.com/

ProxyPassReverse/mirror/foo/http://backend.example.com/

willnotonlycausealocalrequestforthehttp://example.com/mirror/foo/bartobeinternally

convertedintoaproxyrequesttohttp://backend.example.com/bar(thefunctionalityProxyPassprovideshere).Italsotakescareofredirectstheserverbackend.example.comsends:whenhttp://backend.example.com/barisredirectedbyhimtohttp://backend.example.com/quuxApacheadjuststhistohttp://example.com/mirror/foo/quuxbeforeforwardingtheHTTPredirectresponsetotheclient.NotethatthehostnameusedforconstructingtheURLischoseninrespecttothesettingoftheUseCanonicalNamedirective.

NotethatthisProxyPassReversedirectivecanalsobeusedinconjunctionwiththeproxypass-throughfeature(RewriteRule...[P])frommod_rewritebecauseitsdoesn'tdependonacorrespondingProxyPassdirective.

Whenusedinsidea<Location>section,thefirstargumentisomittedandthelocaldirectoryisobtainedfromthe<Location>.

ProxyPreserveHostDirective

Description: UseincomingHostHTTPrequestheaderforproxyrequest

Syntax: ProxyPreserveHostOn|Off

Default: ProxyPreserveHostOff

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_proxyCompatibility: AvailableinApache2.0.31andlater.

Whenenabled,thisoptionwillpasstheHost:linefromtheincomingrequesttotheproxiedhost,insteadofthehostnamespecifiedintheproxypassline.

ThisoptionshouldnormallybeturnedOff.Itismostlyusefulinspecialconfigurationslikeproxiedmassname-basedvirtualhosting,wheretheoriginalHostheaderneedstobeevaluatedbythebackendserver.

ProxyReceiveBufferSizeDirective

Description: NetworkbuffersizeforproxiedHTTPandFTPconnections

Syntax: ProxyReceiveBufferSizebytes

Default: ProxyReceiveBufferSize0

TheProxyReceiveBufferSizedirectivespecifiesanexplicit(TCP/IP)networkbuffersizeforproxiedHTTPandFTPconnections,forincreasedthroughput.Ithastobegreaterthan512orsetto0toindicatethatthesystem'sdefaultbuffersizeshouldbeused.

ExampleProxyReceiveBufferSize2048

ProxyRemoteDirective

Description: RemoteproxyusedtohandlecertainrequestsSyntax: ProxyRemotematchremote-server

Thisdefinesremoteproxiestothisproxy.matchiseitherthenameofaURL-schemethattheremoteserversupports,orapartialURLforwhichtheremoteservershouldbeused,or*toindicatetheservershouldbecontactedforallrequests.remote-serverisapartialURLfortheremoteserver.Syntax:

remote-server=scheme://hostname[:port]

schemeiseffectivelytheprotocolthatshouldbeusedtocommunicatewiththeremoteserver;onlyhttpissupportedbythismodule.

ExampleProxyRemotehttp://goodguys.com/http://mirrorguys.com:8000

ProxyRemote*http://cleversite.com

ProxyRemoteftphttp://ftpproxy.mydomain.com:8080

Inthelastexample,theproxywillforwardFTPrequests,encapsulatedasyetanotherHTTPproxyrequest,toanotherproxywhichcanhandlethem.

Thisoptionalsosupportsreverseproxyconfiguration-abackendwebservercanbeembeddedwithinavirtualhostURLspaceevenifthatserverishiddenbyanotherforwardproxy.

ProxyRemoteMatchDirective

Description: Remoteproxyusedtohandlerequestsmatchedbyregularexpressions

Syntax: ProxyRemoteMatchregexremote-server

TheProxyRemoteMatchisidenticaltotheProxyRemotedirective,exceptthefirstargumentisaregularexpressionmatchagainsttherequestedURL.

ProxyRequestsDirective

Description: Enablesforward(standard)proxyrequestsSyntax: ProxyRequestsOn|Off

Default: ProxyRequestsOff

ThisallowsorpreventsApachefromfunctioningasaforwardproxyserver.(SettingProxyRequeststoOffdoesnotdisableuseoftheProxyPassdirective.)

Inatypicalreverseproxyconfiguration,thisoptionshouldbesettoOff.

InordertogetthefunctionalityofproxyingHTTPorFTPsites,youneedalsomod_proxy_httpormod_proxy_ftp(orboth)presentintheserver.

Warning

DonotenableproxyingwithProxyRequestsuntilyouhavesecuredyourserver.OpenproxyserversaredangerousbothtoyournetworkandtotheInternetatlarge.

ProxyTimeoutDirective

Description: NetworktimeoutforproxiedrequestsSyntax: ProxyTimeoutseconds

Default: ProxyTimeout300

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_proxyCompatibility: AvailableinApache2.0.31andlater

Thisdirectiveallowsausertospecifiyatimeoutonproxyrequests.Thisisusefulwhenyouhaveaslow/buggyappserverwhichhangs,andyouwouldratherjustreturnatimeoutandfailgracefullyinsteadofwaitinghoweverlongittakestheservertoreturn.

ProxyViaDirective

Description: InformationprovidedintheViaHTTPresponseheaderforproxiedrequests

Syntax: ProxyViaOn|Off|Full|Block

Default: ProxyViaOff

ThisdirectivecontrolstheuseoftheVia:HTTPheaderbytheproxy.Itsintendeduseistocontroltheflowofofproxyrequestsalongachainofproxyservers.SeeRFC2616(HTTP/1.1),section14.45foranexplanationofVia:headerlines.

IfsettoOff,whichisthedefault,nospecialprocessingisperformed.IfarequestorreplycontainsaVia:header,itispassedthroughunchanged.IfsettoOn,eachrequestandreplywillgetaVia:headerlineaddedforthecurrenthost.IfsettoFull,eachgeneratedVia:headerlinewilladditionallyhavetheApacheserverversionshownasaVia:commentfield.IfsettoBlock,everyproxyrequestwillhaveallitsVia:headerlinesremoved.NonewVia:headerwillbegenerated.

ApacheModulemod_proxy_connect

Description: mod_proxyextensionforCONNECTrequesthandling

Status: ExtensionModuleIdentifier: proxy_connect_moduleSourceFile: proxy_connect.c

SummaryThismodulerequirestheserviceofmod_proxy.ItprovidessupportfortheCONNECTHTTPmethod.ThismethodismainlyusedtotunnelSSLrequeststhroughproxyservers.

Thus,inordertogettheabilityofhandlingCONNECTrequests,mod_proxyandmod_proxy_connecthavetobepresentintheserver.

Warning

Donotenableproxyinguntilyouhavesecuredyourserver.OpenproxyserversaredangerousbothtoyournetworkandtotheInternetatlarge.

SeealsoAllowCONNECT

mod_proxy

ApacheModulemod_proxy_ftp

Description: FTPsupportmoduleformod_proxyStatus: ExtensionModuleIdentifier: proxy_ftp_moduleSourceFile: proxy_ftp.c

SummaryThismodulerequirestheserviceofmod_proxy.ItprovidessupportfortheproxyingFTPsites.

Thus,inordertogettheabilityofhandlingFTPproxyrequests,mod_proxyandmod_proxy_ftphavetobepresentintheserver.

Warning

Seealsomod_proxy

ApacheModulemod_proxy_http

Description: HTTPsupportmoduleformod_proxyStatus: ExtensionModuleIdentifier: proxy_http_moduleSourceFile: proxy_http.c

SummaryThismodulerequirestheserviceofmod_proxy.ItprovidesthefeaturesusedforproxyingHTTPrequests.mod_proxy_httpsupportsHTTP/0.9,HTTP/1.0andHTTP/1.1.Itdoesnotprovideanycachingabilities.Ifyouwanttosetupacachingproxy,youmightwanttousetheadditionalserviceofthemod_cachemodule.

Thus,inordertogettheabilityofhandlingHTTPproxyrequests,mod_proxyandmod_proxy_httphavetobepresentintheserver.

Warning

Seealsomod_proxy

mod_proxy_connect

ApacheModulemod_rewrite

Description: Providesarule-basedrewritingenginetorewriterequestedURLsonthefly

Status: ExtensionModuleIdentifier: rewrite_moduleSourceFile: mod_rewrite.cCompatibility: AvailableinApache1.3andlater

SummaryThismoduleusesarule-basedrewritingengine(basedonaregular-expressionparser)torewriterequestedURLsonthefly.Itsupportsanunlimitednumberofrulesandanunlimitednumberofattachedruleconditionsforeachrule,toprovideareallyflexibleandpowerfulURLmanipulationmechanism.TheURLmanipulationscandependonvarioustests,ofservervariables,environmentvariables,HTTPheaders,ortimestamps.EvenexternaldatabaselookupsinvariousformatscanbeusedtoachievehighlygranularURLmatching.

ThismoduleoperatesonthefullURLs(includingthepath-infopart)bothinper-servercontext(httpd.conf)andper-directorycontext(.htaccess)andcangeneratequery-stringpartsonresult.Therewrittenresultcanleadtointernalsub-processing,externalrequestredirectionoreventoaninternalproxythroughput.

Furtherdetails,discussion,andexamples,areprovidedinthedetailedmod_rewritedocumentation.

SeealsoRewriteFlags

APIPhases

ApacheprocessesaHTTPrequestinseveralphases.AhookforeachofthesephasesisprovidedbytheApacheAPI.mod_rewriteusestwoofthesehooks:theURL-to-filenametranslationhook(usedaftertheHTTPrequesthasbeenread,butbeforeanyauthorizationstarts)andtheFixuphook(triggeredaftertheauthorizationphases,andaftertheper-directoryconfigfiles(.htaccess)havebeenread,butbeforethecontenthandlerisactivated).

Oncearequestcomesin,andApachehasdeterminedtheappropriateserver(orvirtualserver),therewriteenginestartstheURL-to-filenametranslation,processingthemod_rewritedirectivesfromtheper-serverconfiguration.Afewstepslater,whenthefinaldatadirectoriesarefound,theper-directoryconfigurationdirectivesofmod_rewritearetriggeredintheFixupphase.

RulesetProcessing

Whenmod_rewriteistriggeredduringthesetwoAPIphases,itreadstherelevantrulesetsfromitsconfigurationstructure(whichwaseithercreatedonstartup,forper-servercontext,orduringthedirectorytraversalforper-directorycontext).TheURLrewritingengineisstartedwiththeappropriateruleset(oneormorerulestogetherwiththeirconditions),anditsoperationisexactlythesameforbothconfigurationcontexts.Onlythefinalresultprocessingisdifferent.

Theorderofrulesintherulesetisimportantbecausetherewriteengineprocessestheminaparticular(notalwaysobvious)order,asfollows:Therewriteengineloopsthroughtherulesets(eachrulesetbeingmadeupofRewriteRuledirectives,withorwithoutRewriteConds),rulebyrule.Whenaparticularruleismatched,mod_rewritealsochecksthecorrespondingconditions(RewriteConddirectives).Forhistoricalreasonstheconditionsaregivenfirst,makingthecontrolflowalittlebitlong-winded.SeeFigure1formoredetails.

Figure1:Thecontrolflowoftherewriteenginethrougharewriteruleset

Asabove,firsttheURLismatchedagainstthePatternofarule.Ifitdoesnotmatch,mod_rewriteimmediatelystopsprocessingthatrule,andgoesontothenextrule.IfthePatternmatches,mod_rewritechecksforruleconditions.Ifnonearepresent,theURLwillbereplacedwithanewstring,constructedfromtheSubstitutionstring,andmod_rewritegoesontothenextrule.

IfRewriteCondsexist,aninnerloopisstarted,processingthemintheorderthattheyarelisted.ConditionsarenotmatchedagainstthecurrentURLdirectly.ATestStringisconstructedbyexpandingvariables,back-references,maplookups,etc.,againstwhichtheCondPatternismatched.Ifthepatternfailstomatchoneoftheconditions,thecompletesetofruleandassociatedconditionsfails.Ifthepatternmatchesagivencondition,thenmatchingcontinuestothenextcondition,untilnomoreconditionsareavailable.Ifallconditionsmatch,processingiscontinuedwith

thesubstitutionoftheSubstitutionstringfortheURL.

RegexBack-ReferenceAvailability

UsingparenthesesinPatternorinoneoftheCondPatternscausesback-referencestobeinternallycreated.Thesecanlaterbereferencedusingthestrings$Nand%N(seebelow),forcreatingtheSubstitutionandTestStringstrings.Figure2attemptstoshowhowtheback-referencesaretransferredthroughtheprocessforlaterexpansion.

Figure2:Theback-referenceflowthrougharule.

QuotingSpecialCharacters

AsofApache1.3.20,specialcharactersinTestStringandSubstitutionstringscanbeescaped(thatis,treatedasnormalcharacterswithouttheirusualspecialmeaning)byprefixingthemwithabackslash('\')character.Inotherwords,youcanincludeanactualdollar-signcharacterinaSubstitutionstringbyusing'\$';thiskeepsmod_rewritefromtryingtotreatitasabackreference.

Thismodulekeepstrackoftwoadditional(non-standard)CGI/SSIenvironmentvariablesnamedSCRIPT_URLandSCRIPT_URI.ThesecontainthelogicalWeb-viewtothecurrentresource,whilethestandardCGI/SSIvariablesSCRIPT_NAMEandSCRIPT_FILENAMEcontainthephysicalSystem-view.

Notice:ThesevariablesholdtheURI/URLastheywereinitiallyrequested,thatis,beforeanyrewriting.ThisisimportanttonotebecausetherewritingprocessisprimarilyusedtorewritelogicalURLstophysicalpathnames.

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

PracticalSolutions

Fornumerousexamplesofcommon,andnot-so-common,usesformod_rewrite,seetheRewriteGuide,andtheAdvancedRewriteGuidedocuments.

RewriteBaseDirective

Description: SetsthebaseURLforper-directoryrewritesSyntax: RewriteBaseURL-path

Default: Seeusageforinformation.

Context: directory,.htaccessOverride: FileInfoStatus: ExtensionModule: mod_rewrite

TheRewriteBasedirectiveexplicitlysetsthebaseURLforper-directoryrewrites.Asyouwillseebelow,RewriteRulecanbeusedinper-directoryconfigfiles(.htaccess).Insuchacase,itwillactlocally,strippingthelocaldirectoryprefixbeforeprocessing,andapplyingrewriterulesonlytotheremainder.Whenprocessingiscomplete,theprefixisautomaticallyaddedbacktothepath.Thedefaultsettingis;RewriteBasephysical-directory-path

WhenasubstitutionoccursforanewURL,thismodulehastore-injecttheURLintotheserverprocessing.TobeabletodothisitneedstoknowwhatthecorrespondingURL-prefixorURL-baseis.Bydefaultthisprefixisthecorrespondingfilepathitself.However,formostwebsites,URLsareNOTdirectlyrelatedtophysicalfilenamepaths,sothisassumptionwilloftenbewrong!Therefore,youcanusetheRewriteBasedirectivetospecifythecorrectURL-prefix.

Ifyourwebserver'sURLsarenotdirectlyrelatedtophysicalfilepaths,youwillneedtouseRewriteBaseinevery.htaccessfilewhereyouwanttouseRewriteRuledirectives.

Forexample,assumethefollowingper-directoryconfigfile:

#/abc/def/.htaccess--per-dirconfigfilefordirectory/abc/def

#Remember:/abc/defisthephysicalpathof/xyz,i.e.,theserver

#hasa'Alias/xyz/abc/def'directivee.g.

RewriteEngineOn

#lettheserverknowthatwewerereachedvia/xyzandnot

#viathephysicalpathprefix/abc/def

RewriteBase/xyz

#nowtherewritingrules

RewriteRule^oldstuff\.html$newstuff.html

Intheaboveexample,arequestto/xyz/oldstuff.htmlgetscorrectlyrewrittentothephysicalfile/abc/def/newstuff.html.

ForApacheHackers

Thefollowinglistgivesdetailedinformationabouttheinternalprocessingsteps:

Request:

/xyz/oldstuff.html

InternalProcessing:

/xyz/oldstuff.html->/abc/def/oldstuff.html(per-serverAlias)

/abc/def/oldstuff.html->/abc/def/newstuff.html(per-dirRewriteRule)

/abc/def/newstuff.html->/xyz/newstuff.html(per-dirRewriteBase)

/xyz/newstuff.html->/abc/def/newstuff.html(per-serverAlias)

Result:

/abc/def/newstuff.html

Thisseemsverycomplicated,butisinfactcorrectApacheinternalprocessing.Becausetheper-directoryrewritingcomeslateintheprocess,therewrittenrequesthastobere-injectedintotheApachekernel,asifitwereanewrequest.(Seemod_rewritetechnicaldetails.)Thisisnottheseriousoverheaditmayseemtobe-thisre-injectioniscompletelyinternaltotheApacheserver(andthesameprocedureisusedbymanyother

operationswithinApache).

RewriteCondDirective

Description: Definesaconditionunderwhichrewritingwilltakeplace

Syntax: RewriteCondTestStringCondPattern

Context: serverconfig,virtualhost,directory,.htaccessOverride: FileInfoStatus: ExtensionModule: mod_rewrite

TheRewriteConddirectivedefinesarulecondition.OneormoreRewriteCondcanprecedeaRewriteRuledirective.ThefollowingruleisthenonlyusedifboththecurrentstateoftheURImatchesitspattern,andiftheseconditionsaremet.

TestStringisastringwhichcancontainthefollowingexpandedconstructsinadditiontoplaintext:

RewriteRulebackreferences:Thesearebackreferencesoftheform$N(0<=N<=9),whichprovideaccesstothegroupedparts(inparentheses)ofthepattern,fromtheRewriteRulewhichissubjecttothecurrentsetofRewriteCondconditions..RewriteCondbackreferences:Thesearebackreferencesoftheform%N(1<=N<=9),whichprovideaccesstothegroupedparts(again,inparentheses)ofthepattern,fromthelastmatchedRewriteCondinthecurrentsetofconditions.RewriteMapexpansions:Theseareexpansionsoftheform${mapname:key|default}.SeethedocumentationforRewriteMapformoredetails.Server-Variables:Thesearevariablesoftheform%{NAME_OF_VARIABLE}whereNAME_OF_VARIABLEcanbeastringtakenfromthefollowinglist:

HTTPheaders: connection&

request:HTTP_USER_AGENTHTTP_REFERERHTTP_COOKIEHTTP_FORWARDEDHTTP_HOSTHTTP_PROXY_CONNECTIONHTTP_ACCEPT

REMOTE_ADDRREMOTE_HOSTREMOTE_PORTREMOTE_USERREMOTE_IDENTREQUEST_METHODSCRIPT_FILENAMEPATH_INFOQUERY_STRINGAUTH_TYPE

serverinternals: systemstuff: specials:DOCUMENT_ROOTSERVER_ADMINSERVER_NAMESERVER_ADDRSERVER_PORTSERVER_PROTOCOLSERVER_SOFTWARE

TIME_YEARTIME_MONTIME_DAYTIME_HOURTIME_MINTIME_SECTIME_WDAYTIME

API_VERSIONTHE_REQUESTREQUEST_URIREQUEST_FILENAMEIS_SUBREQHTTPS

ThesevariablesallcorrespondtothesimilarlynamedHTTPMIME-headers,CvariablesoftheApacheserverorstructtmfieldsoftheUnixsystem.MostaredocumentedelsewhereintheManualorintheCGIspecification.Thosethatarespecialtomod_rewriteincludethosebelow.

IS_SUBREQ

Willcontainthetext"true"iftherequestcurrentlybeingprocessedisasub-request,"false"otherwise.Sub-requestsmaybegeneratedbymodulesthatneedtoresolveadditionalfilesorURIsinordertocompletetheirtasks.

API_VERSION

ThisistheversionoftheApachemoduleAPI(theinternalinterfacebetweenserverandmodule)inthecurrenthttpdbuild,asdefinedininclude/ap_mmn.h.ThemoduleAPIversioncorrespondstotheversionofApacheinuse(inthereleaseversionofApache1.3.14,forinstance,itis19990320:10),butismainlyofinteresttomoduleauthors.

THE_REQUEST

ThefullHTTPrequestlinesentbythebrowsertotheserver(e.g.,"GET/index.htmlHTTP/1.1").Thisdoesnotincludeanyadditionalheaderssentbythebrowser.

REQUEST_URI

TheresourcerequestedintheHTTPrequestline.(Intheexampleabove,thiswouldbe"/index.html".)

REQUEST_FILENAME

Thefulllocalfilesystempathtothefileorscriptmatchingtherequest.

Willcontainthetext"on"iftheconnectionisusingSSL/TLS,or"off"otherwise.(Thisvariablecanbesafelyusedregardlessofwhetherornotmod_sslisloaded).

Otherthingsyoushouldbeawareof:

1. ThevariablesSCRIPT_FILENAMEandREQUEST_FILENAMEcontainthesamevalue-thevalueofthefilenamefieldoftheinternalrequest_recstructureoftheApacheserver.ThefirstnameisthecommonlyknownCGIvariablenamewhilethesecondistheappropriate

counterpartofREQUEST_URI(whichcontainsthevalueoftheurifieldofrequest_rec).

2. %{ENV:variable},wherevariablecanbeanyenvironmentvariable,isalsoavailable.Thisislooked-upviainternalApachestructuresand(ifnotfoundthere)viagetenv()fromtheApacheserverprocess.

3. %{SSL:variable},wherevariableisthenameofanSSLenvironmentvariable,canbeusedwhetherornotmod_sslisloaded,butwillalwaysexpandtotheemptystringifitisnot.Example:%{SSL:SSL_CIPHER_USEKEYSIZE}mayexpandto128.

4. %{HTTP:header},whereheadercanbeanyHTTPMIME-headername,canalwaysbeusedtoobtainthevalueofaheadersentintheHTTPrequest.Example:%{HTTP:Proxy-Connection}isthevalueoftheHTTPheader``Proxy-Connection:''.

5. %{LA-U:variable}canbeusedforlook-aheadswhichperformaninternal(URL-based)sub-requesttodeterminethefinalvalueofvariable.Thiscanbeusedtoaccessvariableforrewritingwhichisnotavailableatthecurrentstage,butwillbesetinalaterphase.Forinstance,torewriteaccordingtotheREMOTE_USERvariablefromwithintheper-servercontext(httpd.conffile)youmustuse%{LA-U:REMOTE_USER}-thisvariableissetbytheauthorizationphases,whichcomeaftertheURLtranslationphase(duringwhichmod_rewriteoperates).

Ontheotherhand,becausemod_rewriteimplementsitsper-directorycontext(.htaccessfile)viatheFixupphaseoftheAPIandbecausetheauthorizationphasescomebeforethisphase,youjustcanuse%{REMOTE_USER}inthatcontext.

6. %{LA-F:variable}canbeusedtoperformaninternal(filename-based)sub-request,todeterminethefinalvalueofvariable.Mostofthetime,thisisthesameasLA-Uabove.

CondPatternistheconditionpattern,aregularexpressionwhichisappliedtothecurrentinstanceoftheTestString.TestStringisfirstevaluated,beforebeingmatchedagainstCondPattern.

Remember:CondPatternisaperlcompatibleregularexpressionwithsomeadditions:

1. Youcanprefixthepatternstringwitha'!'character(exclamationmark)tospecifyanon-matchingpattern.

2. TherearesomespecialvariantsofCondPatterns.Insteadofrealregularexpressionstringsyoucanalsouseoneofthefollowing:

'<CondPattern'(lexicographicallyprecedes)TreatstheCondPatternasaplainstringandcomparesitlexicographicallytoTestString.TrueifTestStringlexicographicallyprecedesCondPattern.

'>CondPattern'(lexicographicallyfollows)TreatstheCondPatternasaplainstringandcomparesitlexicographicallytoTestString.TrueifTestStringlexicographicallyfollowsCondPattern.

'=CondPattern'(lexicographicallyequal)TreatstheCondPatternasaplainstringandcomparesitlexicographicallytoTestString.TrueifTestStringislexicographicallyequaltoCondPattern(thetwostringsareexactlyequal,characterforcharacter).IfCondPatternis""(twoquotationmarks)thiscomparesTestStringtotheemptystring.

'-d'(isdirectory)TreatstheTestStringasapathnameandtestswhetheror

notitexists,andisadirectory.

'-f'(isregularfile)TreatstheTestStringasapathnameandtestswhetherornotitexists,andisaregularfile.

'-s'(isregularfile,withsize)TreatstheTestStringasapathnameandtestswhetherornotitexists,andisaregularfilewithsizegreaterthanzero.

'-l'(issymboliclink)TreatstheTestStringasapathnameandtestswhetherornotitexists,andisasymboliclink.

'-F'(isexistingfile,viasubrequest)CheckswhetherornotTestStringisavalidfile,accessibleviaalltheserver'scurrently-configuredaccesscontrolsforthatpath.Thisusesaninternalsubrequesttodothecheck,souseitwithcare-itcanimpactyourserver'sperformance!

'-U'(isexistingURL,viasubrequest)CheckswhetherornotTestStringisavalidURL,accessibleviaalltheserver'scurrently-configuredaccesscontrolsforthatpath.Thisusesaninternalsubrequesttodothecheck,souseitwithcare-itcanimpactyourserver'sperformance!

Allofthesetestscanalsobeprefixedbyanexclamationmark('!')tonegatetheirmeaning.

3. YoucanalsosetspecialflagsforCondPatternbyappending[flags]asthethirdargumenttotheRewriteConddirective,whereflagsisacomma-separatedlistofanyofthefollowing

flags:

'nocase|NC'(nocase)Thismakesthetestcase-insensitive-differencesbetween'A-Z'and'a-z'areignored,bothintheexpandedTestStringandtheCondPattern.ThisflagiseffectiveonlyforcomparisonsbetweenTestStringandCondPattern.Ithasnoeffectonfilesystemandsubrequestchecks.

'ornext|OR'(ornextcondition)UsethistocombineruleconditionswithalocalORinsteadoftheimplicitAND.Typicalexample:

RewriteCond%{REMOTE_HOST}=host1[OR]

RewriteCond%{REMOTE_HOST}=host2[OR]

RewriteCond%{REMOTE_HOST}=host3

RewriteRule...somespecialstuffforanyofthesehosts...

Withoutthisflagyouwouldhavetowritethecondition/rulepairthreetimes.

Example:

TorewritetheHomepageofasiteaccordingtothe``User-Agent:''headeroftherequest,youcanusethefollowing:

RewriteCond%{HTTP_USER_AGENT}^Mozilla

RewriteRule^/$/homepage.max.html[L]

RewriteCond%{HTTP_USER_AGENT}^Lynx

RewriteRule^/$/homepage.min.html[L]

RewriteRule^/$/homepage.std.html[L]

Explanation:Ifyouuseabrowserwhichidentifiesitselfas'Mozilla'(includingNetscapeNavigator,Mozillaetc),thenyougetthemaxhomepage(whichcouldincludeframes,orotherspecialfeatures).

IfyouusetheLynxbrowser(whichisterminal-based),thenyougettheminhomepage(whichcouldbeaversiondesignedforeasy,text-onlybrowsing).Ifneitheroftheseconditionsapply(youuseanyotherbrowser,oryourbrowseridentifiesitselfassomethingnon-standard),yougetthestd(standard)homepage.

RewriteEngineDirective

Description: EnablesordisablesruntimerewritingengineSyntax: RewriteEngineon|off

Default: RewriteEngineoff

Context: serverconfig,virtualhost,directory,.htaccessOverride: FileInfoStatus: ExtensionModule: mod_rewrite

TheRewriteEnginedirectiveenablesordisablestheruntimerewritingengine.Ifitissettooffthismoduledoesnoruntimeprocessingatall.ItdoesnotevenupdatetheSCRIPT_URxenvironmentvariables.

UsethisdirectivetodisablethemoduleinsteadofcommentingoutalltheRewriteRuledirectives!

Notethat,bydefault,rewriteconfigurationsarenotinherited.ThismeansthatyouneedtohaveaRewriteEngineondirectiveforeachvirtualhostinwhichyouwishtouseit.

RewriteMapdirectivesofthetypeprgarenotstartedduringserverinitializationifthey'redefinedinacontextthatdoesnothaveRewriteEnginesettoon

RewriteLockDirective

Description: SetsthenameofthelockfileusedforRewriteMapsynchronization

Syntax: RewriteLockfile-path

Context: serverconfigStatus: ExtensionModule: mod_rewrite

Thisdirectivesetsthefilenameforasynchronizationlockfilewhichmod_rewriteneedstocommunicatewithRewriteMapprograms.Setthislockfiletoalocalpath(notonaNFS-mounteddevice)whenyouwanttousearewritingmap-program.Itisnotrequiredforothertypesofrewritingmaps.

RewriteLogDirective

Description: Setsthenameofthefileusedforloggingrewriteengineprocessing

Syntax: RewriteLogfile-path

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_rewrite

TheRewriteLogdirectivesetsthenameofthefiletowhichtheserverlogsanyrewritingactionsitperforms.Ifthenamedoesnotbeginwithaslash('/')thenitisassumedtoberelativetotheServerRoot.Thedirectiveshouldoccuronlyonceperserverconfig.

TodisabletheloggingofrewritingactionsitisnotrecommendedtosetFilenameto/dev/null,becausealthoughtherewritingenginedoesnotthenoutputtoalogfileitstillcreatesthelogfileoutputinternally.Thiswillslowdowntheserverwithnoadvantagetotheadministrator!TodisableloggingeitherremoveorcommentouttheRewriteLogdirectiveoruseRewriteLogLevel0!

SecuritySeetheApacheSecurityTipsdocumentfordetailsonhowyoursecuritycouldbecompromisedifthedirectorywherelogfilesarestorediswritablebyanyoneotherthantheuserthatstartstheserver.

ExampleRewriteLog"/usr/local/var/apache/logs/rewrite.log"

RewriteLogLevelDirective

Description: Setstheverbosityofthelogfileusedbytherewriteengine

Syntax: RewriteLogLevelLevel

Default: RewriteLogLevel0

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_rewrite

TheRewriteLogLeveldirectivesetstheverbosityleveloftherewritinglogfile.Thedefaultlevel0meansnologging,while9ormoremeansthatpracticallyallactionsarelogged.

TodisabletheloggingofrewritingactionssimplysetLevelto0.Thisdisablesallrewriteactionlogs.

UsingahighvalueforLevelwillslowdownyourApacheserverdramatically!UsetherewritinglogfileataLevelgreaterthan2onlyfordebugging!

ExampleRewriteLogLevel3

RewriteMapDirective

Description: Definesamappingfunctionforkey-lookupSyntax: RewriteMapMapNameMapType:MapSource

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_rewriteCompatibility: Thechoiceofdifferentdbmtypesisavailablein

Apache2.0.41andlater

TheRewriteMapdirectivedefinesaRewritingMapwhichcanbeusedinsiderulesubstitutionstringsbythemapping-functionstoinsert/substitutefieldsthroughakeylookup.Thesourceofthislookupcanbeofvarioustypes.

TheMapNameisthenameofthemapandwillbeusedtospecifyamapping-functionforthesubstitutionstringsofarewritingruleviaoneofthefollowingconstructs:

${MapName:LookupKey}${MapName:LookupKey|DefaultValue}

Whensuchaconstructoccurs,themapMapNameisconsultedandthekeyLookupKeyislooked-up.Ifthekeyisfound,themap-functionconstructissubstitutedbySubstValue.IfthekeyisnotfoundthenitissubstitutedbyDefaultValueorbytheemptystringifnoDefaultValuewasspecified.

Forexample,youmightdefineaRewriteMapas:

RewriteMapexamplemaptxt:/path/to/file/map.txt

YouwouldthenbeabletousethismapinaRewriteRuleasfollows:

RewriteRule^/ex/(.*)${examplemap:$1}

ThefollowingcombinationsforMapTypeandMapSourcecanbeused:

StandardPlainTextMapType:txt,MapSource:UnixfilesystempathtovalidregularfileThisisthestandardrewritingmapfeaturewheretheMapSourceisaplainASCIIfilecontainingeitherblanklines,commentlines(startingwitha'#'character)orpairslikethefollowing-oneperline.

MatchingKeySubstValue

Example##

##map.txt--rewritingmap

Ralf.S.Engelschallrse#BastardOperatorFromHell

Mr.Joe.Averagejoe#Mr.Average

RewriteMapreal-to-usertxt:/path/to/file/map.txt

RandomizedPlainTextMapType:rnd,MapSource:UnixfilesystempathtovalidregularfileThisisidenticaltotheStandardPlainTextvariantabovebutwithaspecialpost-processingfeature:Afterlookingupavalueitisparsedaccordingtocontained``|''characterswhichhavethemeaningof``or''.Inotherwordstheyindicateasetofalternativesfromwhichtheactualreturnedvalueis

chosenrandomly.Forexample,youmightusethefollowingmapfileanddirectivestoprovidearandomloadbalancingbetweenseveralback-endserver,viaareverse-proxy.Imagesaresenttooneoftheserversinthe'static'pool,whileeverythingelseissenttooneofthe'dynamic'pool.

Example:

Rewritemapfile##

##map.txt--rewritingmap

staticwww1|www2|www3|www4

dynamicwww5|www6

ConfigurationdirectivesRewriteMapserversrnd:/path/to/file/map.txt

RewriteRule^/(.*\.(png|gif|jpg))

http://${servers:static}/$1[NC,P,L]

RewriteRule^/(.*)http://${servers:dynamic}/$1[P,L]

HashFileMapType:dbm[=type],MapSource:UnixfilesystempathtovalidregularfileHerethesourceisabinaryformatDBMfilecontainingthesamecontentsasaPlainTextformatfile,butinaspecialrepresentationwhichisoptimizedforreallyfastlookups.Thetypecanbesdbm,gdbm,ndbm,ordbdependingoncompile-timesettings.Ifthetypeisommitted,thecompile-timedefaultwillbechosen.YoucancreatesuchafilewithanyDBMtoolorwiththefollowingPerlscript.BesuretoadjustittocreatetheappropriatetypeofDBM.TheexamplecreatesanNDBM

#!/path/to/bin/perl

##txt2dbm--converttxtmaptodbmformat

useNDBM_File;

useFcntl;

($txtmap,$dbmmap)=@ARGV;

open(TXT,"<$txtmap")ordie"Couldn'topen$txtmap!\n";

tie(%DB,'NDBM_File',$dbmmap,O_RDWR|O_TRUNC|O_CREAT,0644)

ordie"Couldn'tcreate$dbmmap!\n";

while(<TXT>){

nextif(/^\s*#/or/^\s*$/);

$DB{$1}=$2if(/^\s*(\S+)\s+(\S+)/);

untie%DB;

close(TXT);

$txt2dbmmap.txtmap.db

InternalFunctionMapType:int,MapSource:InternalApachefunctionHere,thesourceisaninternalApachefunction.Currentlyyoucannotcreateyourown,butthefollowingfunctionsalreadyexist:

toupper:Convertsthekeytoalluppercase.

tolower:Convertsthekeytoalllowercase.escape:Translatesspecialcharactersinthekeytohex-encodings.unescape:Translateshex-encodingsinthekeybacktospecialcharacters.

ExternalRewritingProgramMapType:prg,MapSource:UnixfilesystempathtovalidregularfileHerethesourceisaprogram,notamapfile.Tocreateityoucanusealanguageofyourchoice,buttheresulthastobeanexecutableprogram(eitherobject-codeorascriptwiththemagiccookietrick'#!/path/to/interpreter'asthefirstline).

Thisprogramisstartedonce,whentheApacheserverisstarted,andthencommunicateswiththerewritingengineviaitsstdinandstdoutfile-handles.Foreachmap-functionlookupitwillreceivethekeytolookupasanewline-terminatedstringonstdin.Itthenhastogivebackthelooked-upvalueasanewline-terminatedstringonstdoutorthefour-characterstring``NULL''ifitfails(i.e.,thereisnocorrespondingvalueforthegivenkey).Atrivialprogramwhichwillimplementa1:1map(i.e.,key==value)couldbe:

Externalrewritingprogramsarenotstartedifthey'redefinedinacontextthatdoesnothaveRewriteEnginesettoon

#!/usr/bin/perl

while(<STDIN>){

#...puthereanytransformationsorlookups...

print$_;

Butbeverycareful:

1. ``Keepitsimple,stupid''(KISS).Ifthisprogramhangs,itwillcauseApachetohangwhentryingtousetherelevantrewriterule.

2. AcommonmistakeistousebufferedI/Oonstdout.Avoidthis,asitwillcauseadeadloop!``$|=1''isusedabove,topreventthis.

3. TheRewriteLockdirectivecanbeusedtodefinealockfilewhichmod_rewritecanusetosynchronizecommunicationwiththemappingprogram.Bydefaultnosuchsynchronizationtakesplace.

TheRewriteMapdirectivecanoccurmorethanonce.Foreachmapping-functionuseoneRewriteMapdirectivetodeclareitsrewritingmapfile.Whileyoucannotdeclareamapinper-directorycontextitisofcoursepossibletousethismapinper-directorycontext.

NoteForplaintextandDBMformatfilesthelooked-upkeysarecachedin-coreuntilthemtimeofthemapfilechangesortheserverdoesarestart.Thiswayyoucanhavemap-functionsinruleswhichareusedforeveryrequest.Thisisnoproblem,becausetheexternallookuponlyhappensonce!

RewriteOptionsDirective

Description: SetssomespecialoptionsfortherewriteengineSyntax: RewriteOptionsOptions

Default: RewriteOptionsMaxRedirects=10

Context: serverconfig,virtualhost,directory,.htaccessOverride: FileInfoStatus: ExtensionModule: mod_rewriteCompatibility: MaxRedirectsisavailableinApache2.0.45

andlater

TheRewriteOptionsdirectivesetssomespecialoptionsforthecurrentper-serverorper-directoryconfiguration.TheOptionstringscanbeoneofthefollowing:

inherit

Thisforcesthecurrentconfigurationtoinherittheconfigurationoftheparent.Inper-virtual-servercontextthismeansthatthemaps,conditionsandrulesofthemainserverareinherited.Inper-directorycontextthismeansthatconditionsandrulesoftheparentdirectory's.htaccessconfigurationareinherited.

MaxRedirects=number

Inordertopreventendlessloopsofinternalredirectsissuedbyper-directoryRewriteRules,mod_rewriteabortstherequestafterreachingamaximumnumberofsuchredirectsandrespondswithan500InternalServerError.Ifyoureallyneedmoreinternalredirectsthan10perrequest,youmayincreasethedefaulttothedesiredvalue.

AllowAnyURI

WhenRewriteRuleisusedinVirtualHostorservercontextwithversion2.0.65orlaterofhttpd,mod_rewrite

willonlyprocesstherewriterulesiftherequestURIisaURL-path.Thisavoidssomesecurityissueswhereparticularrulescouldallow"surprising"patternexpansions(seeCVE-2011-3368andCVE-2011-4317).TolifttherestrictiononmatchingaURL-path,theAllowAnyURIoptioncanbeenabled,andmod_rewritewillapplytherulesettoanyrequestURIstring,regardlessofwhetherthatstringmatchestheURL-pathgrammarrequiredbytheHTTPspecification.

SecurityWarning

Enablingthisoptionwillmaketheservervulnerabletosecurityissuesifusedwithrewriteruleswhicharenotcarefullyauthored.Itisstronglyrecommendedthatthisoptionisnotused.Inparticular,bewareofinputstringscontainingthe'@'characterwhichcouldchangetheinterpretationofthetransformedURI,aspertheaboveCVEnames.

MergeBase

Withthisoption,thevalueofRewriteBaseiscopiedfromwhereit'sexplicitlydefinedintoanysub-directoryorsub-locationthatdoesn'tdefineitsownRewriteBase.ThisflagisavailableforApacheHTTPServer2.0.65andlater.

RewriteRuleDirective

Description: DefinesrulesfortherewritingengineSyntax: RewriteRulePatternSubstitution

Context: serverconfig,virtualhost,directory,.htaccessOverride: FileInfoStatus: ExtensionModule: mod_rewriteCompatibility: Thecookie-flagisavailableinApache2.0.40and

later.

TheRewriteRuledirectiveistherealrewritingworkhorse.Thedirectivecanoccurmorethanonce,witheachinstancedefiningasinglerewriterule.Theorderinwhichtheserulesaredefinedisimportant-thisistheorderinwhichtheywillbeappliedatrun-time.

Patternisaperlcompatibleregularexpression,whichisappliedtothecurrentURL.``Current''meansthevalueoftheURLwhenthisruleisapplied.ThismaynotbetheoriginallyrequestedURL,whichmayalreadyhavematchedapreviousrule,andhavebeenaltered.

Somehintsonthesyntaxofregularexpressions:

.Anysinglecharacter

[chars]Characterclass:Anycharacteroftheclass``chars''

[^chars]Characterclass:Notacharacteroftheclass``chars''

text1|text2Alternative:text1ortext2

Quantifiers:

?0or1occurrencesoftheprecedingtext

*0orNoccurrencesoftheprecedingtext(N>0)

+1orNoccurrencesoftheprecedingtext(N>1)

Grouping:

(text)Groupingoftext

(usedeithertosetthebordersofanalternativeasabove,or

tomakebackreferences,wheretheNthgroupcan

bereferredtoontheRHSofaRewriteRuleas$N)

Anchors:

^Start-of-lineanchor

$End-of-lineanchor

Escaping:

\charescapethegivenchar

(forinstance,tospecifythechars".[]()"etc.)

Formoreinformationaboutregularexpressions,havealookattheperlregularexpressionmanpage("perldocperlre").Ifyouareinterestedinmoredetailedinformationaboutregularexpressionsandtheirvariants(POSIXregexetc.)thefollowingbookisdedicatedtothistopic:

MasteringRegularExpressions,2ndEditionJeffreyE.F.FriedlO'Reilly&Associates,Inc.2002ISBN0-596-00289-0

Inmod_rewrite,theNOTcharacter('!')isalsoavailableasapossiblepatternprefix.Thisenablesyoutonegateapattern;tosay,forinstance:``ifthecurrentURLdoesNOTmatchthispattern''.Thiscanbeusedforexceptionalcases,whereitiseasiertomatchthenegativepattern,orasalastdefaultrule.

NoteWhenusingtheNOTcharactertonegateapattern,youcannotincludegroupedwildcardpartsinthatpattern.Thisisbecause,whenthepatterndoesNOTmatch(ie,thenegationmatches),therearenocontentsforthegroups.Thus,ifnegatedpatternsareused,youcannotuse$Ninthesubstitutionstring!

Thesubstitutionofarewriteruleisthestringwhichissubstituted

for(orreplaces)theoriginalURLwhichPatternmatched.Inadditiontoplaintext,itcaninclude

1. back-references($N)totheRewriteRulepattern

2. back-references(%N)tothelastmatchedRewriteCondpattern

3. server-variablesasinruleconditiontest-strings(%{VARNAME})

4. mapping-functioncalls(${mapname:key|default})

Back-referencesareidentifiersoftheform$N(N=0..9),whichwillbereplacedbythecontentsoftheNthgroupofthematchedPattern.Theserver-variablesarethesameasfortheTestStringofaRewriteConddirective.Themapping-functionscomefromtheRewriteMapdirectiveandareexplainedthere.Thesethreetypesofvariablesareexpandedintheorderabove.

Asalreadymentioned,allrewriterulesareappliedtotheSubstitution(intheorderinwhichtheyaredefinedintheconfigfile).TheURLiscompletelyreplacedbytheSubstitutionandtherewritingprocesscontinuesuntilallruleshavebeenapplied,oritisexplicitlyterminatedbyaLflag-seebelow.

Thereisaspecialsubstitutionstringnamed'-'whichmeans:NOsubstitution!ThisisusefulinprovidingrewritingruleswhichonlymatchURLsbutdonotsubstituteanythingforthem.ItiscommonlyusedinconjunctionwiththeC(chain)flag,inordertoapplymorethanonepatternbeforesubstitutionoccurs.

AdditionallyyoucansetspecialflagsforSubstitutionbyappending[flags]asthethirdargumenttotheRewriteRuledirective.Flagsisacomma-separatedlistofanyofthefollowingflags:

'chain|C'(chainedwithnextrule)

Thisflagchainsthecurrentrulewiththenextrule(whichitselfcanbechainedwiththefollowingrule,andsoon).Thishasthefollowingeffect:ifarulematches,thenprocessingcontinuesasusual-theflaghasnoeffect.Iftheruledoesnotmatch,thenallfollowingchainedrulesareskipped.Forinstance,itcanbeusedtoremovethe``.www''part,insideaper-directoryruleset,whenyouletanexternalredirecthappen(wherethe``.www''partshouldnotoccur!).'cookie|CO=NAME:VAL:domain[:lifetime[:path]]'(setcookie)Thissetsacookieintheclient'sbrowser.Thecookie'snameisspecifiedbyNAMEandthevalueisVAL.Thedomainfieldisthedomainofthecookie,suchas'.apache.org',theoptionallifetimeisthelifetimeofthecookieinminutes,andtheoptionalpathisthepathofthecookie'env|E=VAR:VAL'(setenvironmentvariable)ThisforcesanenvironmentvariablenamedVARtobesettothevalueVAL,whereVALcancontainregexpbackreferences($Nand%N)whichwillbeexpanded.Youcanusethisflagmorethanonce,tosetmorethanonevariable.Thevariablescanlaterbedereferencedinmanysituations,mostcommonlyfromwithinXSSI(via)orCGI($ENV{'VAR'}).YoucanalsodereferencethevariableinalaterRewriteCondpattern,using%{ENV:VAR}.UsethistostripinformationfromURLs,whilemaintainingarecordofthatinformation.'forbidden|F'(forceURLtobeforbidden)ThisforcesthecurrentURLtobeforbidden-itimmediatelysendsbackaHTTPresponseof403(FORBIDDEN).UsethisflaginconjunctionwithappropriateRewriteCondstoconditionallyblocksomeURLs.'gone|G'(forceURLtobegone)ThisforcesthecurrentURLtobegone-itimmediatelysendsbackaHTTPresponseof410(GONE).Usethisflagtomark

pageswhichnolongerexistasgone.'last|L'(lastrule)Stoptherewritingprocesshereanddon'tapplyanymorerewriterules.ThiscorrespondstothePerllastcommandorthebreakcommandinC.UsethisflagtopreventthecurrentlyrewrittenURLfrombeingrewrittenfurtherbyfollowingrules.Forexample,useittorewritetheroot-pathURL('/')toarealone,e.g.,'/e/www/'.'next|N'(nextround)Re-runtherewritingprocess(startingagainwiththefirstrewritingrule).Thistime,theURLtomatchisnolongertheoriginalURL,butrathertheURLreturnedbythelastrewritingrule.ThiscorrespondstothePerlnextcommandorthecontinuecommandinC.Usethisflagtorestarttherewritingprocess-toimmediatelygotothetopoftheloop.Becarefulnottocreateaninfiniteloop!'nocase|NC'(nocase)ThismakesthePatterncase-insensitive,ignoringdifferencebetween'A-Z'and'a-z'whenPatternismatchedagainstthecurrentURL.'noescape|NE'(noURIescapingofoutput)Thisflagpreventsmod_rewritefromapplyingtheusualURIescapingrulestotheresultofarewrite.Ordinarily,specialcharacters(suchas'%','$',';',andsoon)willbeescapedintotheirhexcodeequivalents('%25','%24',and'%3B',respectively);thisflagpreventsthisfromhappening.Thisallowspercentsymbolstoappearintheoutput,asin

RewriteRule/foo/(.*)/bar?arg=P1\%3d$1[R,NE]

whichwouldturn'/foo/zed'intoasaferequestfor'/bar?arg=P1=zed'.'nosubreq|NS'(notforinternalsub-requests)

Thisflagforcestherewriteenginetoskiparewriteruleifthecurrentrequestisaninternalsub-request.Forinstance,sub-requestsoccurinternallyinApachewhenmod_includetriestofindoutinformationaboutpossibledirectorydefaultfiles(index.xxx).Onsub-requestsitisnotalwaysuseful,andcanevencauseerrors,ifthecompletesetofrulesareapplied.Usethisflagtoexcludesomerules.Todecidewhetherornottousethisrule:ifyouprefixURLswithCGI-scripts,toforcethemtobeprocessedbytheCGI-script,it'slikelythatyouwillrunintoproblems(orsignificantoverhead)onsub-requests.Inthesecases,usethisflag.'proxy|P'(forceproxy)Thisflagforcesthesubstitutionparttobeinternallysentasaproxyrequestandimmediately(rewriteprocessingstopshere)putthroughtheproxymodule.YoumustmakesurethatthesubstitutionstringisavalidURI(typicallystartingwithhttp://hostname)whichcanbehandledbytheApacheproxymodule.Ifnot,youwillgetanerrorfromtheproxymodule.UsethisflagtoachieveamorepowerfulimplementationoftheProxyPassdirective,tomapremotecontentintothenamespaceofthelocalserver.Note:mod_proxymustbeenabledinordertousethisflag.

'passthrough|PT'(passthroughtonexthandler)Thisflagforcestherewriteenginetosettheurifieldoftheinternalrequest_recstructuretothevalueofthefilenamefield.Thisflagisjustahacktoenablepost-processingoftheoutputofRewriteRuledirectives,usingAlias,ScriptAlias,Redirect,andotherdirectivesfromvariousURI-to-filenametranslators.Forexample,torewrite/abcto/defusingmod_rewrite,andthen/defto/ghiusingmod_alias:

RewriteRule^/abc(.*)/def$1[PT]

Alias/def/ghi

IfyouomitthePTflag,mod_rewritewillrewriteuri=/abc/...tofilename=/def/...asafullAPI-compliantURI-to-filenametranslatorshoulddo.Thenmod_aliaswilltrytodoaURI-to-filenametransition,whichwillfail.Note:YoumustusethisflagifyouwanttomixdirectivesfromdifferentmoduleswhichallowURL-to-filenametranslators.Thetypicalexampleistheuseofmod_aliasandmod_rewrite.

'qsappend|QSA'(querystringappend)Thisflagforcestherewriteenginetoappendaquerystringpartofthesubstitutionstringtotheexistingstring,insteadofreplacingit.Usethiswhenyouwanttoaddmoredatatothequerystringviaarewriterule.'redirect|R[=code]'(forceredirect)PrefixSubstitutionwithhttp://thishost[:thisport]/(whichmakesthenewURLaURI)toforceaexternalredirection.Ifnocodeisgiven,aHTTPresponseof302(MOVEDTEMPORARILY)willbereturned.Ifyouwanttouseotherresponsecodesintherange300-400,simplyspecifytheappropriatenumberoruseoneofthefollowingsymbolicnames:temp(default),permanent,seeother.UsethisforrulestocanonicalizetheURLandreturnittotheclient-totranslate``/~''into``/u/'',ortoalwaysappendaslashto/u/user,etc.Note:Whenyouusethisflag,makesurethatthesubstitutionfieldisavalidURL!Otherwise,youwillberedirectingtoaninvalidlocation.Rememberthatthisflagonitsownwillonlyprependhttp://thishost[:thisport]/totheURL,andrewritingwillcontinue.Usually,youwillwanttostoprewritingatthispoint,andredirectimmediately.Tostoprewriting,you

shouldaddthe'L'flag.'skip|S=num'(skipnextrule(s))Thisflagforcestherewritingenginetoskipthenextnumrulesinsequence,ifthecurrentrulematches.Usethistomakepseudoif-then-elseconstructs:Thelastruleofthethen-clausebecomesskip=N,whereNisthenumberofrulesintheelse-clause.(Thisisnotthesameasthe'chain|C'flag!)'type|T=MIME-type'(forceMIMEtype)ForcetheMIME-typeofthetargetfiletobeMIME-type.Thiscanbeusedtosetupthecontent-typebasedonsomeconditions.Forexample,thefollowingsnippetallows.phpfilestobedisplayedbymod_phpiftheyarecalledwiththe.phpsextension:

RewriteRule^(.+\.php)s$$1[T=application/x-httpd-php-

source]

Homedirectoryexpansion

Whenthesubstitutionstringbeginswithastringresembling"/~user"(viaexplicittextorbackreferences),mod_rewriteperformshomedirectoryexpansionindependentofthepresenceorconfigurationofmod_userdir.

ThisexpansiondoesnotoccurwhenthePTflagisusedontheRewriteRuledirective.

Note:Enablingrewritesinper-directorycontextToenabletherewritingengineforper-directoryconfigurationfiles,youneedtoset``RewriteEngineOn''inthesefilesand``OptionsFollowSymLinks''mustbeenabled.IfyouradministratorhasdisabledoverrideofFollowSymLinksforauser'sdirectory,thenyoucannotusetherewritingengine.Thisrestrictionisneededforsecurityreasons.

Note:Patternmatchinginper-directorycontextNeverforgetthatPatternisappliedtoacompleteURLinper-serverconfigurationfiles.However,inper-directoryconfigurationfiles,theper-directoryprefix(whichalwaysisthesameforaspecificdirectory)isautomaticallyremovedforthepatternmatchingandautomaticallyaddedafterthesubstitutionhasbeendone.Thisfeatureisessentialformanysortsofrewriting-withoutthis,youwouldalwayshavetomatchtheparentdirectorywhichisnotalwayspossible.

Thereisoneexception:Ifasubstitutionstringstartswith``http://'',thenthedirectoryprefixwillnotbeadded,andanexternalredirectorproxythroughput(ifflagPisused)isforced!

Note:SubstitutionofAbsoluteURLs

Whenyouprefixasubstitutionfieldwithhttp://thishost[:thisport],mod_rewritewillautomaticallystripthatout.Thisauto-reductiononURLswithanimplicitexternalredirectismostusefulincombinationwithamapping-functionwhichgeneratesthehostnamepart.

Remember:Anunconditionalexternalredirecttoyourownserverwillnotworkwiththeprefixhttp://thishostbecauseofthisfeature.Toachievesuchaself-redirect,youhavetousetheR-flag.

Note:QueryString

ThePatternwillnotbematchedagainstthequerystring.Instead,youmustuseaRewriteCondwiththe%{QUERY_STRING}variable.Youcan,however,createURLsinthesubstitutionstring,containingaquerystringpart.Simplyuseaquestionmarkinsidethesubstitutionstring,toindicatethatthefollowingtextshouldbere-injectedintothequerystring.When

youwanttoeraseanexistingquerystring,endthesubstitutionstringwithjustaquestionmark.Tocombineanewquerystringwithanoldone,usethe[QSA]flag.

Hereareallpossiblesubstitutioncombinationsandtheirmeanings:

Insideper-serverconfiguration(httpd.conf)forrequest``GET/somepath/pathinfo'':

GivenRuleResultingSubstitution

--------------------------------------------------------------------------------

^/somepath(.*)otherpath$1invalid,notsupported

^/somepath(.*)otherpath$1[R]invalid,notsupported

^/somepath(.*)otherpath$1[P]invalid,notsupported

--------------------------------------------------------------------------------

^/somepath(.*)/otherpath$1/otherpath/pathinfo

^/somepath(.*)/otherpath$1[R]http://thishost/otherpath/pathinfo

viaexternalredirection

^/somepath(.*)/otherpath$1[P]doesn'tmakesense,notsupported

--------------------------------------------------------------------------------

^/somepath(.*)http://thishost/otherpath$1/otherpath/pathinfo

^/somepath(.*)http://thishost/otherpath$1[R]http://thishost/otherpath/pathinfo

^/somepath(.*)http://thishost/otherpath$1[P]doesn'tmakesense,notsupported

--------------------------------------------------------------------------------

^/somepath(.*)http://otherhost/otherpath$1http://otherhost/otherpath/pathinfo

^/somepath(.*)http://otherhost/otherpath$1[R]http://otherhost/otherpath/pathinfo

(the[R]flagisredundant)

^/somepath(.*)http://otherhost/otherpath$1[P]http://otherhost/otherpath/pathinfo

viainternalproxy

Insideper-directoryconfigurationfor/somepath(/physical/path/to/somepath/.htacccess,withRewriteBase/somepath)forrequest``GET/somepath/localpath/pathinfo'':

GivenRuleResultingSubstitution

--------------------------------------------------------------------------------

^localpath(.*)otherpath$1/somepath/otherpath/pathinfo

^localpath(.*)otherpath$1[R]http://thishost/somepath/otherpath/pathinfo

^localpath(.*)otherpath$1[P]doesn'tmakesense,notsupported

--------------------------------------------------------------------------------

^localpath(.*)/otherpath$1/otherpath/pathinfo

^localpath(.*)/otherpath$1[R]http://thishost/otherpath/pathinfo

^localpath(.*)/otherpath$1[P]doesn'tmakesense,notsupported

--------------------------------------------------------------------------------

^localpath(.*)http://thishost/otherpath$1/otherpath/pathinfo

^localpath(.*)http://thishost/otherpath$1[R]http://thishost/otherpath/pathinfo

^localpath(.*)http://thishost/otherpath$1[P]doesn'tmakesense,notsupported

--------------------------------------------------------------------------------

^localpath(.*)http://otherhost/otherpath$1http://otherhost/otherpath/pathinfo

^localpath(.*)http://otherhost/otherpath$1[R]http://otherhost/otherpath/pathinfo

(the[R]flagisredundant)

^localpath(.*)http://otherhost/otherpath$1[P]http://otherhost/otherpath/pathinfo

viainternalproxy

||FAQ||

Apachemod_setenvif

:: Base: setenvif_module: mod_setenvif.c

mod_setenvif

BrowserMatch^Mozillanetscape

BrowserMatchMSIE!netscape

Apache

BrowserMatch

: HTTPUser-Agent: BrowserMatchregex[!]env-variable[=value]

[[!]env-variable[=value]]...

: ,,,.htaccess: FileInfo: Base: mod_setenvif

BrowserMatch SetEnvIf User-AgentHTTP:

BrowserMatchNoCaseRobotis_a_robot

SetEnvIfNoCaseUser-AgentRobotis_a_robot

BrowserMatch^Mozillaformsjpeg=yesbrowser=netscape

BrowserMatch"^Mozilla/[2-3]"tablesagifframesjavascript

BrowserMatchMSIE!javascript

BrowserMatchNoCase

: HTTPUser-Agent: BrowserMatchNoCaseregex[!]env-

variable[=value][[!]env-variable[=value]]

: ,,,.htaccess: FileInfo: Base: mod_setenvif: Apache1.2 (Apache1.2

BrowserMatchNoCase BrowserMatch

BrowserMatchNoCasemacplatform=macintosh

BrowserMatchNoCasewinplatform=windows

BrowserMatch BrowserMatchNoCaseSetEnvIfNoCase 2:

BrowserMatchNoCaseRobotis_a_robot

SetEnvIfNoCaseUser-AgentRobotis_a_robot

SetEnvIf

:: SetEnvIfattributeregex[!]env-

: ,,,.htaccess: FileInfo: Base: mod_setenvif

SetEnvIf

1. HTTP( RFC2616 ) Host,User-AgentReferer,Accept-Language

Remote_Host-()

Remote_Addr-IP

Server_Addr-IP (2.0.43)

Request_Method-( GET,POST)

Request_Protocol-

Request_URI-URL

3. SetEnvIf SetEnvIf[NoCase]()

( regex) PerlPOSIX.2egrep regexattribute

1. varname

2. !varname

3. varname=value

"1" regex

:SetEnvIfRequest_URI"\.gif$"object_is_image=gif

SetEnvIfRequest_URI"\.jpg$"object_is_image=jpg

SetEnvIfRequest_URI"\.xbm$"object_is_image=xbm

SetEnvIfRefererwww\.mydomain\.comintra_site_referral

SetEnvIfobject_is_imagexbmXBIT_PROCESSING=1

SetEnvIf^TS*^[a-z].*HAVE_TS

object_is_imageintra_site_referral

"TS"[a-z]

Apache

||FAQ||

SetEnvIfNoCase

:: SetEnvIfNoCaseattributeregex[!]env-

: ,,,.htaccess: FileInfo: Base: mod_setenvif: Apache1.3

SetEnvIfNoCase SetEnvIf

SetEnvIfNoCaseHostApache\.Orgsite=apache

HTTP Host: Apache.Org apache.orgsite" apache"

||FAQ||

Apachemod_so

:: Extension: so_module: mod_so.c: Window()

Unix ( .so)

Apache1.3Apache2.0 ―Apache2.0

Windows

Apache1.3.152.0Windows ―mod_foo.so

mod_soApacheModuleFoo.dll

ApacheAPIUNIXWindows WindowsWindowsUnix

UnixConfigure ApacheCore

DLL DLLApache

DLL AP_MODULE_DECLARE_DATA(Apache)

modulefoo_module;

moduleAP_MODULE_DECLARE_DATAfoo_module;

Unix Windows

DLL libhttpd.lib modules .dsp

DLL modules

LoadFile

:: LoadFilefilename[filename]...

:: Extension: mod_so

LoadFile

LoadFilelibexec/libxmlparse.so

||FAQ||

LoadModule

: : LoadModulemodulefilename

:: Extension: mod_so

LoadModule filename:

LoadModulestatus_modulemodules/mod_status.so

ServerRootmodules

||FAQ||

Apachemod_speling

: URL: Extension: speling_module: mod_speling.c

Apache

||FAQ||

CheckSpelling

: spelling: CheckSpellingon|off

: CheckSpellingOff

: ,,,.htaccess: Options: Extension: mod_speling: CheckSpellingApache1.1Apache1.3

ApacheApache1.3.2 CheckSpelling

(http://my.host/~apahce/) <Location/status>

ApacheModulemod_ssl

Description: StrongcryptographyusingtheSecureSocketsLayer(SSL)andTransportLayerSecurity(TLS)protocols

Status: ExtensionModuleIdentifier: ssl_moduleSourceFile: mod_ssl.c

SummaryThismoduleprovidesSSLv2/v3andTLSv1supportfortheApacheHTTPServer.ItwascontributedbyRalfS.Engeschallbasedonhismod_sslprojectandoriginallyderivedfromworkbyBenLaurie.

ThismodulereliesonOpenSSLtoprovidethecryptographyengine.

Furtherdetails,discussion,andexamplesareprovidedintheSSLdocumentation.

ThismoduleprovidesalotofSSLinformationasadditionalenvironmentvariablestotheSSIandCGInamespace.Thegeneratedvariablesarelistedinthetablebelow.Forbackwardcompatibilitytheinformationcanbemadeavailableunderdifferentnames,too.LookintheCompatibilitychapterfordetailsonthecompatibilityvariables.

VariableName: ValueType:

Description:

HTTPS flag HTTPSisbeingused.SSL_PROTOCOL string TheSSLprotocolversion

(SSLv2,SSLv3,TLSv1)SSL_SESSION_ID string Thehex-encodedSSL

sessionidSSL_CIPHER string Thecipherspecification

nameSSL_CIPHER_EXPORT string trueifcipherisan

exportcipherSSL_CIPHER_USEKEYSIZE number Numberofcipherbits

(actuallyused)SSL_CIPHER_ALGKEYSIZE number Numberofcipherbits

(possible)SSL_VERSION_INTERFACE string Themod_sslprogram

versionSSL_VERSION_LIBRARY string TheOpenSSLprogram

versionSSL_CLIENT_M_VERSION string Theversionoftheclient

certificateSSL_CLIENT_M_SERIAL string Theserialoftheclient

certificateSSL_CLIENT_S_DN string SubjectDNinclient's

certificateSSL_CLIENT_S_DN_x509 string Componentofclient's

SubjectDNSSL_CLIENT_I_DN string IssuerDNofclient's

certificateSSL_CLIENT_I_DN_x509 string Componentofclient's

IssuerDNSSL_CLIENT_V_START string Validityofclient's

certificate(starttime)SSL_CLIENT_V_END string Validityofclient's

certificate(endtime)SSL_CLIENT_A_SIG string Algorithmusedforthe

signatureofclient'scertificate

SSL_CLIENT_A_KEY string Algorithmusedforthepublickeyofclient'scertificate

SSL_CLIENT_CERT string PEM-encodedclientcertificate

SSL_CLIENT_CERT_CHAINn string PEM-encodedcertificatesinclientcertificatechain

SSL_CLIENT_VERIFY string NONE,SUCCESS,GENEROUSorFAILED:reason

SSL_SERVER_M_VERSION string Theversionoftheservercertificate

SSL_SERVER_M_SERIAL string Theserialoftheservercertificate

SSL_SERVER_S_DN string SubjectDNinserver'scertificate

SSL_SERVER_S_DN_x509 string Componentofserver's

SubjectDNSSL_SERVER_I_DN string IssuerDNofserver's

certificateSSL_SERVER_I_DN_x509 string Componentofserver's

IssuerDNSSL_SERVER_V_START string Validityofserver's

certificate(starttime)SSL_SERVER_V_END string Validityofserver's

certificate(endtime)SSL_SERVER_A_SIG string Algorithmusedforthe

signatureofserver'scertificate

SSL_SERVER_A_KEY string Algorithmusedforthepublickeyofserver'scertificate

SSL_SERVER_CERT string PEM-encodedservercertificate

[wherex509isacomponentofaX.509DN:C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email]

CustomLogFormats

Whenmod_sslisbuiltintoApacheoratleastloaded(underDSOsituation)additionalfunctionsexistfortheCustomLogFormatofmod_log_config.Firstthereisanadditional``%{varname}x''eXtensionformatfunctionwhichcanbeusedtoexpandanyvariablesprovidedbyanymodule,especiallythoseprovidedbymod_sslwhichcanyoufindintheabovetable.

Forbackwardcompatibilitythereisadditionallyaspecial``%{name}c''cryptographyformatfunctionprovided.InformationaboutthisfunctionisprovidedintheCompatibilitychapter.

Example:

CustomLoglogs/ssl_request_log\"%t%h%{SSL_PROTOCOL}x%

{SSL_CIPHER}x\"%r\"%b"

SSLCACertificateFileDirective

Description: FileofconcatenatedPEM-encodedCACertificatesforClientAuth

Syntax: SSLCACertificateFilefile-path

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_ssl

Thisdirectivesetstheall-in-onefilewhereyoucanassembletheCertificatesofCertificationAuthorities(CA)whoseclientsyoudealwith.TheseareusedforClientAuthentication.SuchafileissimplytheconcatenationofthevariousPEM-encodedCertificatefiles,inorderofpreference.Thiscanbeusedalternativelyand/oradditionallytoSSLCACertificatePath.

ExampleSSLCACertificateFile/usr/local/apache2/conf/ssl.crt/ca-bundle-

client.crt

SSLCACertificatePathDirective

Description: DirectoryofPEM-encodedCACertificatesforClientAuth

Syntax: SSLCACertificatePathdirectory-path

ThisdirectivesetsthedirectorywhereyoukeeptheCertificatesofCertificationAuthorities(CAs)whoseclientsyoudealwith.TheseareusedtoverifytheclientcertificateonClientAuthentication.

ThefilesinthisdirectoryhavetobePEM-encodedandareaccessedthroughhashfilenames.Sousuallyyoucan'tjustplacetheCertificatefilesthere:youalsohavetocreatesymboliclinksnamedhash-value.N.Andyoushouldalwaysmakesurethisdirectorycontainstheappropriatesymboliclinks.

ExampleSSLCACertificatePath/usr/local/apache2/conf/ssl.crt/

SSLCARevocationFileDirective

Description: FileofconcatenatedPEM-encodedCACRLsforClientAuth

Syntax: SSLCARevocationFilefile-path

Thisdirectivesetstheall-in-onefilewhereyoucanassembletheCertificateRevocationLists(CRL)ofCertificationAuthorities(CA)whoseclientsyoudealwith.TheseareusedforClientAuthentication.SuchafileissimplytheconcatenationofthevariousPEM-encodedCRLfiles,inorderofpreference.Thiscanbeusedalternativelyand/oradditionallytoSSLCARevocationPath.

ExampleSSLCARevocationFile/usr/local/apache2/conf/ssl.crl/ca-bundle-

client.crl

SSLCARevocationPathDirective

Description: DirectoryofPEM-encodedCACRLsforClientAuthSyntax: SSLCARevocationPathdirectory-path

ThisdirectivesetsthedirectorywhereyoukeeptheCertificateRevocationLists(CRL)ofCertificationAuthorities(CAs)whoseclientsyoudealwith.TheseareusedtorevoketheclientcertificateonClientAuthentication.

ThefilesinthisdirectoryhavetobePEM-encodedandareaccessedthroughhashfilenames.SousuallyyouhavenotonlytoplacetheCRLfilesthere.Additionallyyouhavetocreatesymboliclinksnamedhash-value.rN.Andyoushouldalwaysmakesurethisdirectorycontainstheappropriatesymboliclinks.

ExampleSSLCARevocationPath/usr/local/apache2/conf/ssl.crl/

SSLCertificateChainFileDirective

Description: FileofPEM-encodedServerCACertificatesSyntax: SSLCertificateChainFilefile-path

Thisdirectivesetstheoptionalall-in-onefilewhereyoucanassemblethecertificatesofCertificationAuthorities(CA)whichformthecertificatechainoftheservercertificate.ThisstartswiththeissuingCAcertificateofoftheservercertificateandcanrangeuptotherootCAcertificate.SuchafileissimplytheconcatenationofthevariousPEM-encodedCACertificatefiles,usuallyincertificatechainorder.

Thisshouldbeusedalternativelyand/oradditionallytoSSLCACertificatePathforexplicitlyconstructingtheservercertificatechainwhichissenttothebrowserinadditiontotheservercertificate.ItisespeciallyusefultoavoidconflictswithCAcertificateswhenusingclientauthentication.BecausealthoughplacingaCAcertificateoftheservercertificatechainintoSSLCACertificatePathhasthesameeffectforthecertificatechainconstruction,ithastheside-effectthatclientcertificatesissuedbythissameCAcertificatearealsoacceptedonclientauthentication.That'susuallynotoneexpect.

Butbecareful:Providingthecertificatechainworksonlyifyouareusingasingle(eitherRSAorDSA)basedservercertificate.IfyouareusingacoupledRSA+DSAcertificatepair,thiswillworkonlyifactuallybothcertificatesusethesamecertificatechain.Elsethebrowserswillbeconfusedinthissituation.

ExampleSSLCertificateChainFile/usr/local/apache2/conf/ssl.crt/ca.crt

SSLCertificateFileDirective

Description: ServerPEM-encodedX.509CertificatefileSyntax: SSLCertificateFilefile-path

ThisdirectivepointstothePEM-encodedCertificatefilefortheserverandoptionallyalsotothecorrespondingRSAorDSAPrivateKeyfileforit(containedinthesamefile).IfthecontainedPrivateKeyisencryptedthePassPhrasedialogisforcedatstartuptime.Thisdirectivecanbeuseduptotwotimes(referencingdifferentfilenames)whenbothaRSAandaDSAbasedservercertificateisusedinparallel.

ExampleSSLCertificateFile/usr/local/apache2/conf/ssl.crt/server.crt

SSLCertificateKeyFileDirective

Description: ServerPEM-encodedPrivateKeyfileSyntax: SSLCertificateKeyFilefile-path

ThisdirectivepointstothePEM-encodedPrivateKeyfilefortheserver.IfthePrivateKeyisnotcombinedwiththeCertificateintheSSLCertificateFile,usethisadditionaldirectivetopointtothefilewiththestand-alonePrivateKey.WhenSSLCertificateFileisusedandthefilecontainsboththeCertificateandthePrivateKeythisdirectiveneednotbeused.Butwestronglydiscouragethispractice.InsteadwerecommendyoutoseparatetheCertificateandthePrivateKey.IfthecontainedPrivateKeyisencrypted,thePassPhrasedialogisforcedatstartuptime.Thisdirectivecanbeuseduptotwotimes(referencingdifferentfilenames)whenbothaRSAandaDSAbasedprivatekeyisusedinparallel.

ExampleSSLCertificateKeyFile

/usr/local/apache2/conf/ssl.key/server.key

SSLCipherSuiteDirective

Description: CipherSuiteavailablefornegotiationinSSLhandshakeSyntax: SSLCipherSuitecipher-spec

Default: SSLCipherSuite

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

Context: serverconfig,virtualhost,directory,.htaccessOverride: AuthConfigStatus: ExtensionModule: mod_ssl

Thiscomplexdirectiveusesacolon-separatedcipher-specstringconsistingofOpenSSLcipherspecificationstoconfiguretheCipherSuitetheclientispermittedtonegotiateintheSSLhandshakephase.Noticethatthisdirectivecanbeusedbothinper-serverandper-directorycontext.Inper-servercontextitappliestothestandardSSLhandshakewhenaconnectionisestablished.Inper-directorycontextitforcesaSSLrenegotationwiththereconfiguredCipherSuiteaftertheHTTPrequestwasreadbutbeforetheHTTPresponseissent.

AnSSLcipherspecificationincipher-speciscomposedof4majorattributesplusafewextraminorones:

KeyExchangeAlgorithm:RSAorDiffie-Hellmanvariants.AuthenticationAlgorithm:RSA,Diffie-Hellman,DSSornone.Cipher/EncryptionAlgorithm:DES,Triple-DES,RC4,RC2,IDEAornone.MACDigestAlgorithm:MD5,SHAorSHA1.

AnSSLciphercanalsobeanexportcipherandiseitheraSSLv2orSSLv3/TLSv1cipher(hereTLSv1isequivalenttoSSLv3).To

specifywhichcipherstouse,onecaneitherspecifyalltheCiphers,oneatatime,orusealiasestospecifythepreferenceandorderfortheciphers(seeTable1).

Tag DescriptionKeyExchangeAlgorithm:kRSA RSAkeyexchangekDHr Diffie-HellmankeyexchangewithRSAkeykDHd Diffie-HellmankeyexchangewithDSAkeykEDH Ephemeral(temp.key)Diffie-Hellmankeyexchange

(nocert)AuthenticationAlgorithm:aNULL NoauthenticationaRSA RSAauthenticationaDSS DSSauthenticationaDH Diffie-HellmanauthenticationCipherEncodingAlgorithm:eNULL NoencodingDES DESencoding3DES Triple-DESencodingRC4 RC4encodingRC2 RC2encodingIDEA IDEAencodingMACDigestAlgorithm:MD5 MD5hashfunctionSHA1 SHA1hashfunctionSHA SHAhashfunctionAliases:SSLv2 allSSLversion2.0ciphersSSLv3 allSSLversion3.0ciphers

TLSv1 allTLSversion1.0ciphersEXP allexportciphersEXPORT40 all40-bitexportciphersonlyEXPORT56 all56-bitexportciphersonlyLOW alllowstrengthciphers(noexport,singleDES)MEDIUM allcipherswith128bitencryptionHIGH allciphersusingTriple-DESRSA allciphersusingRSAkeyexchangeDH allciphersusingDiffie-HellmankeyexchangeEDH allciphersusingEphemeralDiffie-Hellmankey

exchangeADH allciphersusingAnonymousDiffie-Hellmankey

exchangeDSS allciphersusingDSSauthenticationNULL allciphersusingnoencryption

Nowwherethisbecomesinterestingisthatthesecanbeputtogethertospecifytheorderandciphersyouwishtouse.Tospeedthisuptherearealsoaliases(SSLv2,SSLv3,TLSv1,EXP,LOW,MEDIUM,HIGH)forcertaingroupsofciphers.Thesetagscanbejoinedtogetherwithprefixestoformthecipher-spec.Availableprefixesare:

none:addciphertolist+:movematchingcipherstothecurrentlocationinlist-:removecipherfromlist(canbeaddedlateragain)!:killcipherfromlistcompletely(cannotbeaddedlateragain)

Asimplerwaytolookatallofthisistousethe``opensslciphers-v''commandwhichprovidesanicewaytosuccessivelycreatethecorrectcipher-specstring.Thedefault

cipher-specstringis``ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP''whichmeansthefollowing:first,removefromconsiderationanyciphersthatdonotauthenticate,i.e.forSSLonlytheAnonymousDiffie-Hellmanciphers.Next,useciphersusingRC4andRSA.Nextincludethehigh,mediumandthenthelowsecurityciphers.FinallypullallSSLv2andexportcipherstotheendofthelist.

$opensslciphers-v'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'

NULL-SHASSLv3Kx=RSAAu=RSAEnc=NoneMac=SHA1

NULL-MD5SSLv3Kx=RSAAu=RSAEnc=NoneMac=MD5

EDH-RSA-DES-CBC3-SHASSLv3Kx=DHAu=RSAEnc=3DES(168)Mac=SHA1

...............

EXP-RC4-MD5SSLv3Kx=RSA(512)Au=RSAEnc=RC4(40)Mac=MD5export

EXP-RC2-CBC-MD5SSLv2Kx=RSA(512)Au=RSAEnc=RC2(40)Mac=MD5export

EXP-RC4-MD5SSLv2Kx=RSA(512)Au=RSAEnc=RC4(40)Mac=MD5export

ThecompletelistofparticularRSA&DHciphersforSSLisgiveninTable2.

ExampleSSLCipherSuiteRSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW

Cipher-Tag

Protocol KeyEx. Auth. Enc. MAC Type

RSACiphers:DES-

CBC3-SHA

SSLv3 RSA RSA 3DES(168) SHA1

CBC3-MD5

SSLv2 RSA RSA 3DES(168) MD5

CBC-SHA

SSLv3 RSA RSA IDEA(128) SHA1

RC4-SHA SSLv3 RSA RSA RC4(128) SHA1

RC4-MD5 SSLv3 RSA RSA RC4(128) MD5

CBC-MD5

SSLv2 RSA RSA IDEA(128) MD5

RC2-CBC-

SSLv2 RSA RSA RC2(128) MD5

RC4-MD5 SSLv2 RSA RSA RC4(128) MD5DES-CBC-

SSLv3 RSA RSA DES(56) SHA1

RC4-64-

SSLv2 RSA RSA RC4(64) MD5

DES-CBC-

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-

EXP-RC2-

CBC-MD5

EXP-RC4-

NULL-SHA SSLv3 RSA RSA None SHA1NULL-MD5 SSLv3 RSA RSA None MD5Diffie-HellmanCiphers:ADH-DES-

CBC3-SHA

SSLv3 DH None 3DES(168) SHA1

ADH-DES-

CBC-SHA

SSLv3 DH None DES(56) SHA1

ADH-RC4-

SSLv3 DH None RC4(128) MD5

EDH-RSA-

CBC3-SHA

SSLv3 DH RSA 3DES(168) SHA1

EDH-DSS-

CBC3-SHA

SSLv3 DH DSS 3DES(168) SHA1

EDH-RSA-

DES-CBC-

SSLv3 DH RSA DES(56) SHA1

EDH-DSS-

DES-CBC-

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-

SSLv3 DH(512) None DES(40) SHA1 export

EXP-ADH-

RC4-MD5

SSLv3 DH(512) None RC4(40) MD5 export

SSLEngineDirective

Description: SSLEngineOperationSwitchSyntax: SSLEngineon|off

Default: SSLEngineoff

ThisdirectivetogglestheusageoftheSSL/TLSProtocolEngine.Thisisusuallyusedinsidea<VirtualHost>sectiontoenableSSL/TLSforaparticularvirtualhost.BydefaulttheSSL/TLSProtocolEngineisdisabledforboththemainserverandallconfiguredvirtualhosts.

Example<VirtualHost_default_:443>

SSLEngineon

</VirtualHost>

SSLHonorCipherOrderDirective

Description: Optiontoprefertheserver'scipherpreferenceorder

Syntax: SSLHonorCipherOrderflag

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_sslCompatibility: AvailableinApache2.0.65andlater,ifusing

OpenSSL0.9.7orlater

WhenchoosingacipherduringanSSLv3orTLSv1handshake,normallytheclient'spreferenceisused.Ifthisdirectiveisenabled,theserver'spreferencewillbeusedinstead.

ExampleSSLHonorCipherOrderon

SSLInsecureRenegotiationDirective

Description: Optiontoenablesupportforinsecurerenegotiation

Syntax: SSLInsecureRenegotiationflag

Default: SSLInsecureRenegotiationoff

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_sslCompatibility: Availableinhttpd2.0.64andlater,ifusing

OpenSSL0.9.8morlater

Asoriginallyspecified,allversionsoftheSSLandTLSprotocols(uptoandincludingTLS/1.2)werevulnerabletoaMan-in-the-Middleattack(CVE-2009-3555)duringarenegotiation.Thisvulnerabilityallowedanattackerto"prefix"achosenplaintexttotheHTTPrequestasseenbythewebserver.Aprotocolextensionwasdevelopedwhichfixedthisvulnerabilityifsupportedbybothclientandserver.

Ifmod_sslislinkedagainstOpenSSLversion0.9.8morlater,bydefaultrenegotiationisonlysupportedwithclientssupportingthenewprotocolextension.Ifthisdirectiveisenabled,renegotiationwillbeallowedwithold(unpatched)clients,albeitinsecurely.

Securitywarning

Ifthisdirectiveisenabled,SSLconnectionswillbevulnerabletotheMan-in-the-MiddleprefixattackasdescribedinCVE-2009-3555.

ExampleSSLInsecureRenegotiationon

TheSSL_SECURE_RENEGenvironmentvariablecanbeusedfromanSSIorCGIscripttodeterminewhethersecurerenegotiationissupportedforagivenSSLconnection.

SSLMutexDirective

Description: Semaphoreforinternalmutualexclusionofoperations

Syntax: SSLMutextype

Default: SSLMutexnone

Context: serverconfigStatus: ExtensionModule: mod_ssl

ThisconfigurestheSSLengine'ssemaphore(aka.lock)whichisusedformutualexclusionofoperationswhichhavetobedoneinasynchronizedwaybetweenthepre-forkedApacheserverprocesses.Thisdirectivecanonlybeusedintheglobalservercontextbecauseit'sonlyusefultohaveoneglobalmutex.ThisdirectiveisdesignedtocloselymatchtheAcceptMutexdirective

ThefollowingMutextypesareavailable:

none|no

ThisisthedefaultwherenoMutexisusedatall.Useitatyourownrisk.ButbecausecurrentlytheMutexismainlyusedforsynchronizingwriteaccesstotheSSLSessionCacheyoucanlivewithoutitaslongasyouacceptasometimesgarbledSessionCache.Soit'snotrecommendedtoleavethisthedefault.InsteadconfigurearealMutex.

posixsem

ThisisanelegantMutexvariantwhereaPosixSemaphoreisusedwhenpossible.ItisonlyavailablewhentheunderlyingplatformandAPRsupportsit.

sysvsem

ThisisasomewhatelegantMutexvariantwhereaSystemVIPCSemaphoreisusedwhenpossible.Itispossibleto"leak"

SysVsemaphoresifprocessescrashbeforethesemaphoreisremoved.ItisonlyavailablewhentheunderlyingplatformandAPRsupportsit.

ThisdirectivetellstheSSLModuletopickthe"best"semaphoreimplementationavailabletoit,choosingbetweenPosixandSystemVIPC,inthatorder.ItisonlyavailablewhentheunderlyingplatformandAPRsupportsatleastoneofthe2.

pthread

ThisdirectivetellstheSSLModuletousePosixthreadmutexes.ItisonlyavailableiftheunderlyingplatformandAPRsupportsit.

fcntl:/path/to/mutex

ThisisaportableMutexvariantwhereaphysical(lock-)fileandthefcntl()fucntionareusedastheMutex.Alwaysusealocaldiskfilesystemfor/path/to/mutexandneverafileresidingonaNFS-orAFS-filesystem.ItisonlyavailablewhentheunderlyingplatformandAPRsupportsit.Note:Internally,theProcessID(PID)oftheApacheparentprocessisautomaticallyappendedto/path/to/mutextomakeitunique,soyoudon'thavetoworryaboutconflictsyourself.NoticethatthistypeofmutexisnotavailableundertheWin32environment.Thereyouhavetousethesemaphoremutex.

flock:/path/to/mutex

Thisissimilartothefcntl:/path/to/mutexmethodwiththeexceptionthattheflock()functionisusedtoprovidefilelocking.ItisonlyavailablewhentheunderlyingplatformandAPRsupportsit.

file:/path/to/mutex

ThisdirectivetellstheSSLModuletopickthe"best"filelockingimplementationavailabletoit,choosingbetweenfcntlandflock,inthatorder.ItisonlyavailablewhentheunderlyingplatformandAPRsupportsatleastoneofthe2.

default|yes

ThisdirectivetellstheSSLModuletopickthedefaultlockingimplementationasdeterminedbytheplatformandAPR.

ExampleSSLMutexfile:/usr/local/apache/logs/ssl_mutex

SSLOptionsDirective

Description: ConfigurevariousSSLenginerun-timeoptionsSyntax: SSLOptions[+|-]option...

Context: serverconfig,virtualhost,directory,.htaccessOverride: OptionsStatus: ExtensionModule: mod_ssl

Thisdirectivecanbeusedtocontrolvariousrun-timeoptionsonaper-directorybasis.Normally,ifmultipleSSLOptionscouldapplytoadirectory,thenthemostspecificoneistakencompletely;theoptionsarenotmerged.HoweverifalltheoptionsontheSSLOptionsdirectiveareprecededbyaplus(+)orminus(-)symbol,theoptionsaremerged.Anyoptionsprecededbya+areaddedtotheoptionscurrentlyinforce,andanyoptionsprecededbya-areremovedfromtheoptionscurrentlyinforce.

Theavailableoptionsare:

StdEnvVars

Whenthisoptionisenabled,thestandardsetofSSLrelatedCGI/SSIenvironmentvariablesarecreated.Thisperdefaultisdisabledforperformancereasons,becausetheinformationextractionstepisaratherexpensiveoperation.SooneusuallyenablesthisoptionforCGIandSSIrequestsonly.

CompatEnvVars

Whenthisoptionisenabled,additionalCGI/SSIenvironmentvariablesarecreatedforbackwardcompatibilitytootherApacheSSLsolutions.LookintheCompatibilitychapterfordetailsontheparticularvariablesgenerated.

ExportCertData

Whenthisoptionisenabled,additionalCGI/SSIenvironment

variablesarecreated:SSL_SERVER_CERT,SSL_CLIENT_CERTandSSL_CLIENT_CERT_CHAINn(withn=0,1,2,..).ThesecontainthePEM-encodedX.509CertificatesofserverandclientforthecurrentHTTPSconnectionandcanbeusedbyCGIscriptsfordeeperCertificatechecking.Additionallyallothercertificatesoftheclientcertificatechainareprovided,too.Thisbloatsuptheenvironmentalittlebitwhichiswhyyouhavetousethisoptiontoenableitondemand.

FakeBasicAuth

Whenthisoptionisenabled,theSubjectDistinguishedName(DN)oftheClientX509CertificateistranslatedintoaHTTPBasicAuthorizationusername.ThismeansthatthestandardApacheauthenticationmethodscanbeusedforaccesscontrol.TheusernameisjusttheSubjectoftheClient'sX509Certificate(canbedeterminedbyrunningOpenSSL'sopensslx509command:opensslx509-noout-subject-incertificate.crt).Notethatnopasswordisobtainedfromtheuser.Everyentryintheuserfileneedsthispassword:``xxj31ZMTZzkVA'',whichistheDES-encryptedversionoftheword`password''.ThosewholiveunderMD5-basedencryption(forinstanceunderFreeBSDorBSD/OS,etc.)shouldusethefollowingMD5hashofthesameword:``$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/''.

StrictRequire

ThisforcesforbiddenaccesswhenSSLRequireSSLorSSLRequiresuccessfullydecidedthataccessshouldbeforbidden.Usuallythedefaultisthatinthecasewherea``Satisfyany''directiveisused,andotheraccessrestrictionsarepassed,denialofaccessduetoSSLRequireSSLorSSLRequireisoverridden(becausethat'showtheApacheSatisfymechanismshouldwork.)

ButforstrictaccessrestrictionyoucanuseSSLRequireSSLand/orSSLRequireincombinationwithan``SSLOptions+StrictRequire''.Thenanadditional``SatisfyAny''hasnochanceoncemod_sslhasdecidedtodenyaccess.

OptRenegotiate

ThisenablesoptimizedSSLconnectionrenegotiationhandlingwhenSSLdirectivesareusedinper-directorycontext.Bydefaultastrictschemeisenabledwhereeveryper-directoryreconfigurationofSSLparameterscausesafullSSLrenegotiationhandshake.Whenthisoptionisusedmod_ssltriestoavoidunnecessaryhandshakesbydoingmoregranular(butstillsafe)parameterchecks.Neverthelessthesegranularcheckssometimesmaybenotwhattheuserexpects,soenablethisonaper-directorybasisonly,please.

ExampleSSLOptions+FakeBasicAuth-StrictRequire

<Files~"\.(cgi|shtml)$">

SSLOptions+StdEnvVars+CompatEnvVars-ExportCertData

<Files>

SSLPassPhraseDialogDirective

Description: Typeofpassphrasedialogforencryptedprivatekeys

Syntax: SSLPassPhraseDialogtype

Default: SSLPassPhraseDialogbuiltin

WhenApachestartsupithastoreadthevariousCertificate(seeSSLCertificateFile)andPrivateKey(seeSSLCertificateKeyFile)filesoftheSSL-enabledvirtualservers.BecauseforsecurityreasonsthePrivateKeyfilesareusuallyencrypted,mod_sslneedstoquerytheadministratorforaPassPhraseinordertodecryptthosefiles.Thisquerycanbedoneintwowayswhichcanbeconfiguredbytype:

builtin

ThisisthedefaultwhereaninteractiveterminaldialogoccursatstartuptimejustbeforeApachedetachesfromtheterminal.HeretheadministratorhastomanuallyenterthePassPhraseforeachencryptedPrivateKeyfile.BecausealotofSSL-enabledvirtualhostscanbeconfigured,thefollowingreuse-schemeisusedtominimizethedialog:WhenaPrivateKeyfileisencrypted,allknownPassPhrases(atthebeginningtherearenone,ofcourse)aretried.IfoneofthoseknownPassPhrasessucceedsnodialogpopsupforthisparticularPrivateKeyfile.Ifnonesucceeded,anotherPassPhraseisqueriedontheterminalandrememberedforthenextround(whereitperhapscanbereused).

Thisschemeallowsmod_ssltobemaximallyflexible(becauseforNencryptedPrivateKeyfilesyoucanuseNdifferentPassPhrases-butthenyouhavetoenterallof

them,ofcourse)whileminimizingtheterminaldialog(i.e.whenyouuseasinglePassPhraseforallNPrivateKeyfilesthisPassPhraseisqueriedonlyonce).

exec:/path/to/program

HereanexternalprogramisconfiguredwhichiscalledatstartupforeachencryptedPrivateKeyfile.Itiscalledwithtwoarguments(thefirstisoftheform``servername:portnumber'',thesecondiseither``RSA''or``DSA''),whichindicateforwhichserverandalgorithmithastoprintthecorrespondingPassPhrasetostdout.Theintentisthatthisexternalprogramfirstrunssecuritycheckstomakesurethatthesystemisnotcompromisedbyanattacker,andonlywhenthesecheckswerepassedsuccessfullyitprovidesthePassPhrase.

Boththesesecuritychecks,andthewaythePassPhraseisdetermined,canbeascomplexasyoulike.Mod_ssljustdefinestheinterface:anexecutableprogramwhichprovidesthePassPhraseonstdout.Nothingmoreorless!So,ifyou'rereallyparanoidaboutsecurity,hereisyourinterface.Anythingelsehastobeleftasanexercisetotheadministrator,becauselocalsecurityrequirementsaresodifferent.

Thereuse-algorithmaboveisusedhere,too.Inotherwords:TheexternalprogramiscalledonlyonceperuniquePassPhrase.

Example:

SSLPassPhraseDialogexec:/usr/local/apache/sbin/pp-filter

SSLProtocolDirective

Description: ConfigureusableSSLprotocolflavorsSyntax: SSLProtocol[+|-]protocol...

Default: SSLProtocolall

Context: serverconfig,virtualhostOverride: OptionsStatus: ExtensionModule: mod_ssl

ThisdirectivecanbeusedtocontroltheSSLprotocolflavorsmod_sslshouldusewhenestablishingitsserverenvironment.Clientsthencanonlyconnectwithoneoftheprovidedprotocols.

Theavailable(case-insensitive)protocolsare:

ThisistheSecureSocketsLayer(SSL)protocol,version2.0.ItistheoriginalSSLprotocolasdesignedbyNetscapeCorporation.

ThisistheSecureSocketsLayer(SSL)protocol,version3.0.ItisthesuccessortoSSLv2andthecurrently(asofFebruary1999)de-factostandardizedSSLprotocolfromNetscapeCorporation.It'ssupportedbyalmostallpopularbrowsers.

ThisistheTransportLayerSecurity(TLS)protocol,version1.0.ItisthesuccessortoSSLv3andcurrently(asofFebruary1999)stillunderconstructionbytheInternetEngineeringTaskForce(IETF).It'sstillnotsupportedbyanypopularbrowsers.

Thisisashortcutfor``+SSLv2+SSLv3+TLSv1''anda

convinientwayforenablingallprotocolsexceptonewhenusedincombinationwiththeminussignonaprotocolastheexampleaboveshows.

Example#enableSSLv3andTLSv1,butnotSSLv2

SSLProtocolall-SSLv2

SSLProxyCACertificateFileDirective

Description: FileofconcatenatedPEM-encodedCACertificatesforRemoteServerAuth

Syntax: SSLProxyCACertificateFilefile-path

Thisdirectivesetstheall-in-onefilewhereyoucanassembletheCertificatesofCertificationAuthorities(CA)whoseremoteserversyoudealwith.TheseareusedforRemoteServerAuthentication.SuchafileissimplytheconcatenationofthevariousPEM-encodedCertificatefiles,inorderofpreference.Thiscanbeusedalternativelyand/oradditionallytoSSLProxyCACertificatePath.

ExampleSSLProxyCACertificateFile/usr/local/apache2/conf/ssl.crt/ca-

bundle-remote-server.crt

SSLProxyCACertificatePathDirective

Description: DirectoryofPEM-encodedCACertificatesforRemoteServerAuth

Syntax: SSLProxyCACertificatePathdirectory-

ThisdirectivesetsthedirectorywhereyoukeeptheCertificatesofCertificationAuthorities(CAs)whoseremoteserversyoudealwith.TheseareusedtoverifytheremoteservercertificateonRemoteServerAuthentication.

ThefilesinthisdirectoryhavetobePEM-encodedandareaccessedthroughhashfilenames.Sousuallyyoucan'tjustplacetheCertificatefilesthere:youalsohavetocreatesymboliclinksnamedhash-value.N.Andyoushouldalwaysmakesurethisdirectorycontainstheappropriatesymboliclinks.UsetheMakefilewhichcomeswithmod_ssltoaccomplishthistask.

ExampleSSLProxyCACertificatePath/usr/local/apache2/conf/ssl.crt/

SSLProxyCARevocationFileDirective

Description: FileofconcatenatedPEM-encodedCACRLsforRemoteServerAuth

Syntax: SSLProxyCARevocationFilefile-path

Thisdirectivesetstheall-in-onefilewhereyoucanassembletheCertificateRevocationLists(CRL)ofCertificationAuthorities(CA)whoseremoteserversyoudealwith.TheseareusedforRemoteServerAuthentication.SuchafileissimplytheconcatenationofthevariousPEM-encodedCRLfiles,inorderofpreference.Thiscanbeusedalternativelyand/oradditionallytoSSLProxyCARevocationPath.

ExampleSSLProxyCARevocationFile/usr/local/apache2/conf/ssl.crl/ca-

bundle-remote-server.crl

SSLProxyCARevocationPathDirective

Description: DirectoryofPEM-encodedCACRLsforRemoteServerAuth

Syntax: SSLProxyCARevocationPathdirectory-

ThisdirectivesetsthedirectorywhereyoukeeptheCertificateRevocationLists(CRL)ofCertificationAuthorities(CAs)whoseremoteserversyoudealwith.TheseareusedtorevoketheremoteservercertificateonRemoteServerAuthentication.

ThefilesinthisdirectoryhavetobePEM-encodedandareaccessedthroughhashfilenames.SousuallyyouhavenotonlytoplacetheCRLfilesthere.Additionallyyouhavetocreatesymboliclinksnamedhash-value.rN.Andyoushouldalwaysmakesurethisdirectorycontainstheappropriatesymboliclinks.UsetheMakefilewhichcomeswithmod_ssltoaccomplishthistask.

ExampleSSLProxyCARevocationPath/usr/local/apache2/conf/ssl.crl/

SSLProxyCipherSuiteDirective

Description: CipherSuiteavailablefornegotiationinSSLproxyhandshakeSyntax: SSLProxyCipherSuitecipher-spec

Default: SSLProxyCipherSuite

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

EquivalenttoSSLCipherSuite,butfortheproxyconnection.PleaserefertoSSLCipherSuiteforadditionalinformation.

SSLProxyEngineDirective

Description: SSLProxyEngineOperationSwitchSyntax: SSLProxyEngineon|off

Default: SSLProxyEngineoff

ThisdirectivetogglestheusageoftheSSL/TLSProtocolEngineforproxy.Thisisusuallyusedinsidea<VirtualHost>sectiontoenableSSL/TLSforproxyusageinaparticularvirtualhost.BydefaulttheSSL/TLSProtocolEngineisdisabledforproxyimagebothforthemainserverandallconfiguredvirtualhosts.

Example<VirtualHost_default_:443>

SSLProxyEngineon

</VirtualHost>

SSLProxyMachineCertificateFileDirective

Description: FileofconcatenatedPEM-encodedclientcertificatesandkeystobeusedbytheproxy

Syntax: SSLProxyMachineCertificateFile

filename

Context: serverconfigOverride: NotapplicableStatus: ExtensionModule: mod_ssl

Thisdirectivesetstheall-in-onefilewhereyoukeepthecertificatesandkeysusedforauthenticationoftheproxyservertoremoteservers.

ThisreferencedfileissimplytheconcatenationofthevariousPEM-encodedcertificatefiles,inorderofpreference.UsethisdirectivealternativelyoradditionallytoSSLProxyMachineCertificatePath.

Currentlythereisnosupportforencryptedprivatekeys

Example:

SSLProxyMachineCertificateFile

/usr/local/apache2/conf/ssl.crt/proxy.pem

SSLProxyMachineCertificatePathDirective

Description: DirectoryofPEM-encodedclientcertificatesandkeystobeusedbytheproxy

Syntax: SSLProxyMachineCertificatePath

directory

Context: serverconfigOverride: NotapplicableStatus: ExtensionModule: mod_ssl

Thisdirectivesetsthedirectorywhereyoukeepthecertificatesandkeysusedforauthenticationoftheproxyservertoremoteservers.

ThefilesinthisdirectorymustbePEM-encodedandareaccessedthroughhashfilenames.Additionally,youmustcreatesymboliclinksnamedhash-value.N.Andyoushouldalwaysmakesurethisdirectorycontainstheappropriatesymboliclinks.UsetheMakefilewhichcomeswithmod_ssltoaccomplishthistask.

Currentlythereisnosupportforencryptedprivatekeys

Example:

SSLProxyMachineCertificatePath

/usr/local/apache2/conf/proxy.crt/

SSLProxyProtocolDirective

Description: ConfigureusableSSLprotocolflavorsforproxyusage

Syntax: SSLProxyProtocol[+|-]protocol...

Default: SSLProxyProtocolall

Context: serverconfig,virtualhostOverride: OptionsStatus: ExtensionModule: mod_ssl

ThisdirectivecanbeusedtocontroltheSSLprotocolflavorsmod_sslshouldusewhenestablishingitsserverenvironmentforproxy.Itwillonlyconnecttoserversusingoneoftheprovidedprotocols.

PleaserefertoSSLProtocolforadditionalinformation.

SSLProxyVerifyDirective

Description: TypeofremoteserverCertificateverificationSyntax: SSLProxyVerifylevel

Default: SSLProxyVerifynone

ThisdirectivesetstheCertificateverificationlevelfortheremoteserverAuthentication.Noticethatthisdirectivecanbeusedbothinper-serverandper-directorycontext.Inper-servercontextitappliestotheremoteserverauthenticationprocessusedinthestandardSSLhandshakewhenaconnectionisestablished.Inper-directorycontextitforcesaSSLrenegotationwiththereconfiguredremoteserververificationlevelaftertheHTTPrequestwasreadbutbeforetheHTTPresponseissent.

Thefollowinglevelsareavailableforlevel:

none:noremoteserverCertificateisrequiredatalloptional:theremoteservermaypresentavalidCertificaterequire:theremoteserverhastopresentavalidCertificateoptional_no_ca:theremoteservermaypresentavalidCertificatebutitneednottobe(successfully)verifiable.

Inpracticeonlylevelsnoneandrequirearereallyinteresting,becauseleveloptionaldoesn'tworkwithallserversandleveloptional_no_caisactuallyagainsttheideaofauthentication(butcanbeusedtoestablishSSLtestpages,etc.)

ExampleSSLProxyVerifyrequire

SSLProxyVerifyDepthDirective

Description: MaximumdepthofCACertificatesinRemoteServerCertificateverification

Syntax: SSLProxyVerifyDepthnumber

Default: SSLProxyVerifyDepth1

Thisdirectivesetshowdeeplymod_sslshouldverifybeforedecidingthattheremoteserverdoesnothaveavalidcertificate.Noticethatthisdirectivecanbeusedbothinper-serverandper-directorycontext.Inper-servercontextitappliestotheclientauthenticationprocessusedinthestandardSSLhandshakewhenaconnectionisestablished.Inper-directorycontextitforcesaSSLrenegotationwiththereconfiguredremoteserververificationdepthaftertheHTTPrequestwasreadbutbeforetheHTTPresponseissent.

Thedepthactuallyisthemaximumnumberofintermediatecertificateissuers,i.e.thenumberofCAcertificateswhicharemaxallowedtobefollowedwhileverifyingtheremoteservercertificate.Adepthof0meansthatself-signedremoteservercertificatesareacceptedonly,thedefaultdepthof1meanstheremoteservercertificatecanbeself-signedorhastobesignedbyaCAwhichisdirectlyknowntotheserver(i.e.theCA'scertificateisunderSSLProxyCACertificatePath),etc.

ExampleSSLProxyVerifyDepth10

SSLRandomSeedDirective

Description: PseudoRandomNumberGenerator(PRNG)seedingsource

Syntax: SSLRandomSeedcontextsource[bytes]

ThisconfiguresoneormoresourcesforseedingthePseudoRandomNumberGenerator(PRNG)inOpenSSLatstartuptime(contextisstartup)and/orjustbeforeanewSSLconnectionisestablished(contextisconnect).ThisdirectivecanonlybeusedintheglobalservercontextbecausethePRNGisaglobalfacility.

Thefollowingsourcevariantsareavailable:

builtin

Thisisthealwaysavailablebuiltinseedingsource.It'susageconsumesminimumCPUcyclesunderruntimeandhencecanbealwaysusedwithoutdrawbacks.ThesourceusedforseedingthePRNGcontainsofthecurrenttime,thecurrentprocessidand(whenapplicable)arandomlychoosen1KBextractoftheinter-processscoreboardstructureofApache.Thedrawbackisthatthisisnotreallyastrongsourceandatstartuptime(wherethescoreboardisstillnotavailable)thissourcejustproducesafewbytesofentropy.Soyoushouldalways,atleastforthestartup,useanadditionalseedingsource.

file:/path/to/source

Thisvariantusesanexternalfile/path/to/sourceasthesourceforseedingthePRNG.Whenbytesisspecified,onlythefirstbytesnumberofbytesofthefileformtheentropy(andbytesisgivento/path/to/sourceasthefirst

argument).Whenbytesisnotspecifiedthewholefileformstheentropy(and0isgivento/path/to/sourceasthefirstargument).Usethisespeciallyatstartuptime,forinstancewithanavailable/dev/randomand/or/dev/urandomdevices(whichusuallyexistonmodernUnixderivateslikeFreeBSDandLinux).

Butbecareful:Usually/dev/randomprovidesonlyasmuchentropydataasitactuallyhas,i.e.whenyourequest512bytesofentropy,butthedevicecurrentlyhasonly100bytesavailabletwothingscanhappen:Onsomeplatformsyoureceiveonlythe100byteswhileonotherplatformsthereadblocksuntilenoughbytesareavailable(whichcantakealongtime).Hereusinganexisting/dev/urandomisbetter,becauseitneverblocksandactuallygivestheamountofrequesteddata.Thedrawbackisjustthatthequalityofthereceiveddatamaynotbethebest.

OnsomeplatformslikeFreeBSDonecanevencontrolhowtheentropyisactuallygenerated,i.e.bywhichsysteminterrupts.Moredetailsonecanfindunderrndcontrol(8)onthoseplatforms.Alternatively,whenyoursystemlackssucharandomdevice,youcanusetoollikeEGD(EntropyGatheringDaemon)andrunit'sclientprogramwiththeexec:/path/to/program/variant(seebelow)oruseegd:/path/to/egd-socket(seebelow).

exec:/path/to/program

Thisvariantusesanexternalexecutable/path/to/programasthesourceforseedingthePRNG.Whenbytesisspecified,onlythefirstbytesnumberofbytesofitsstdoutcontentsformtheentropy.Whenbytesisnotspecified,theentiretyofthedataproducedonstdoutformtheentropy.Usethisonlyatstartuptimewhenyouneeda

verystrongseedingwiththehelpofanexternalprogram(forinstanceasintheexampleabovewiththetruerandutilityyoucanfindinthemod_ssldistributionwhichisbasedontheAT&Ttruerandlibrary).Usingthisintheconnectioncontextslowsdowntheservertoodramatically,ofcourse.Sousuallyyoushouldavoidusingexternalprogramsinthatcontext.

egd:/path/to/egd-socket(Unixonly)ThisvariantusestheUnixdomainsocketoftheexternalEntropyGatheringDaemon(EGD)(seehttp://www.lothar.com/tech/crypto/)toseedthePRNG.Usethisifnorandomdeviceexistsonyourplatform.

ExampleSSLRandomSeedstartupbuiltin

SSLRandomSeedstartupfile:/dev/random

SSLRandomSeedstartupfile:/dev/urandom1024

SSLRandomSeedstartupexec:/usr/local/bin/truerand16

SSLRandomSeedconnectbuiltin

SSLRandomSeedconnectfile:/dev/random

SSLRandomSeedconnectfile:/dev/urandom1024

SSLRequireDirective

Description: Allowaccessonlywhenanarbitrarilycomplexbooleanexpressionistrue

Syntax: SSLRequireexpression

Context: directory,.htaccessOverride: AuthConfigStatus: ExtensionModule: mod_ssl

Thisdirectivespecifiesageneralaccessrequirementwhichhastobefulfilledinordertoallowaccess.It'saverypowerfuldirectivebecausetherequirementspecificationisanarbitrarilycomplexbooleanexpressioncontaininganynumberofaccesschecks.

Theexpressionmustmatchthefollowingsyntax(givenasaBNFgrammarnotation):

expr::="true"|"false"

|"!"expr

|expr"&&"expr

|expr"||"expr

|"("expr")"

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

whileforvarnameanyvariablefromTable3canbeused.Finallyforfuncnamethefollowingfunctionsareavailable:

file(filename)Thisfunctiontakesonestringargumentandexpandstothecontentsofthefile.Thisisespeciallyusefulformatchingthiscontentsagainstaregularexpression,etc.

Noticethatexpressionisfirstparsedintoaninternalmachinerepresentationandthenevaluatedinasecondstep.Actually,inGlobalandPer-ServerClasscontextexpressionisparsedatstartuptimeandatruntimeonlythemachinerepresentationisexecuted.ForPer-Directorycontextthisisdifferent:hereexpressionhastobeparsedandimmediatelyexecutedforeveryrequest.

ExampleSSLRequire(%{SSL_CIPHER}!~m/^(EXP|NULL)-/\

and%{SSL_CLIENT_S_DN_O}eq"SnakeOil,Ltd."\

and%{SSL_CLIENT_S_DN_OU}in{"Staff","CA","Dev"}\

and%{TIME_WDAY}>=1and%{TIME_WDAY}<=5\

and%{TIME_HOUR}>=8and%{TIME_HOUR}<=20)\

or%{REMOTE_ADDR}=~m/^192\.76\.162\.[0-9]+$/

StandardCGI/1.0andApachevariables:

HTTP_USER_AGENTPATH_INFOAUTH_TYPE

HTTP_REFERERQUERY_STRINGSERVER_SOFTWARE

HTTP_COOKIEREMOTE_HOSTAPI_VERSION

HTTP_FORWARDEDREMOTE_IDENTTIME_YEAR

HTTP_HOSTIS_SUBREQTIME_MON

HTTP_PROXY_CONNECTIONDOCUMENT_ROOTTIME_DAY

HTTP_ACCEPTSERVER_ADMINTIME_HOUR

HTTP:headernameSERVER_NAMETIME_MIN

THE_REQUESTSERVER_PORTTIME_SEC

REQUEST_METHODSERVER_PROTOCOLTIME_WDAY

REQUEST_SCHEMEREMOTE_ADDRTIME

REQUEST_URIREMOTE_USERENV:variablename

REQUEST_FILENAME

SSL-relatedvariables:

HTTPSSSL_CLIENT_M_VERSIONSSL_SERVER_M_VERSION

SSL_CLIENT_M_SERIALSSL_SERVER_M_SERIAL

SSL_PROTOCOLSSL_CLIENT_V_STARTSSL_SERVER_V_START

SSL_SESSION_IDSSL_CLIENT_V_ENDSSL_SERVER_V_END

SSL_CIPHERSSL_CLIENT_S_DNSSL_SERVER_S_DN

SSL_CIPHER_EXPORTSSL_CLIENT_S_DN_CSSL_SERVER_S_DN_C

SSL_CIPHER_ALGKEYSIZESSL_CLIENT_S_DN_STSSL_SERVER_S_DN_ST

SSL_CIPHER_USEKEYSIZESSL_CLIENT_S_DN_LSSL_SERVER_S_DN_L

SSL_VERSION_LIBRARYSSL_CLIENT_S_DN_OSSL_SERVER_S_DN_O

SSL_VERSION_INTERFACESSL_CLIENT_S_DN_OUSSL_SERVER_S_DN_OU

SSL_CLIENT_S_DN_CNSSL_SERVER_S_DN_CN

SSL_CLIENT_S_DN_TSSL_SERVER_S_DN_T

SSL_CLIENT_S_DN_ISSL_SERVER_S_DN_I

SSL_CLIENT_S_DN_GSSL_SERVER_S_DN_G

SSL_CLIENT_S_DN_SSSL_SERVER_S_DN_S

SSL_CLIENT_S_DN_DSSL_SERVER_S_DN_D

SSL_CLIENT_S_DN_UIDSSL_SERVER_S_DN_UID

SSL_CLIENT_S_DN_EmailSSL_SERVER_S_DN_Email

SSL_CLIENT_I_DNSSL_SERVER_I_DN

SSL_CLIENT_I_DN_CSSL_SERVER_I_DN_C

SSL_CLIENT_I_DN_STSSL_SERVER_I_DN_ST

SSL_CLIENT_I_DN_LSSL_SERVER_I_DN_L

SSL_CLIENT_I_DN_OSSL_SERVER_I_DN_O

SSL_CLIENT_I_DN_OUSSL_SERVER_I_DN_OU

SSL_CLIENT_I_DN_CNSSL_SERVER_I_DN_CN

SSL_CLIENT_I_DN_TSSL_SERVER_I_DN_T

SSL_CLIENT_I_DN_ISSL_SERVER_I_DN_I

SSL_CLIENT_I_DN_GSSL_SERVER_I_DN_G

SSL_CLIENT_I_DN_SSSL_SERVER_I_DN_S

SSL_CLIENT_I_DN_DSSL_SERVER_I_DN_D

SSL_CLIENT_I_DN_UIDSSL_SERVER_I_DN_UID

SSL_CLIENT_I_DN_EmailSSL_SERVER_I_DN_Email

SSL_CLIENT_A_SIGSSL_SERVER_A_SIG

SSL_CLIENT_A_KEYSSL_SERVER_A_KEY

SSL_CLIENT_CERTSSL_SERVER_CERT

SSL_CLIENT_CERT_CHAINn

SSL_CLIENT_VERIFY

SSLRequireSSLDirective

Description: DenyaccesswhenSSLisnotusedfortheHTTPrequest

Syntax: SSLRequireSSL

Context: directory,.htaccessOverride: AuthConfigStatus: ExtensionModule: mod_ssl

ThisdirectiveforbidsaccessunlessHTTPoverSSL(i.e.HTTPS)isenabledforthecurrentconnection.ThisisveryhandyinsidetheSSL-enabledvirtualhostordirectoriesfordefendingagainstconfigurationerrorsthatexposestuffthatshouldbeprotected.WhenthisdirectiveispresentallrequestsaredeniedwhicharenotusingSSL.

ExampleSSLRequireSSL

SSLSessionCacheDirective

Description: Typeoftheglobal/inter-processSSLSessionCache

Syntax: SSLSessionCachetype

Default: SSLSessionCachenone

Thisconfiguresthestoragetypeoftheglobal/inter-processSSLSessionCache.Thiscacheisanoptionalfacilitywhichspeedsupparallelrequestprocessing.Forrequeststothesameserverprocess(viaHTTPkeep-alive),OpenSSLalreadycachestheSSLsessioninformationlocally.Butbecausemodernclientsrequestinlinedimagesandotherdataviaparallelrequests(usuallyuptofourparallelrequestsarecommon)thoserequestsareservedbydifferentpre-forkedserverprocesses.Hereaninter-processcachehelpstoavoidunneccessarysessionhandshakes.

Thefollowingtwostoragetypesarecurrentlysupported:

Thisisthedefaultandjustdisablestheglobal/inter-processSessionCache.Thereisnodrawbackinfunctionality,butanoticeablespeedpenaltycanbeobserved.

dbm:/path/to/datafile

ThismakesuseofaDBMhashfileonthelocaldisktosynchronizethelocalOpenSSLmemorycachesoftheserverprocesses.TheslightincreaseinI/Oontheserverresultsinavisiblerequestspeedupforyourclients,sothistypeofstorageisgenerallyrecommended.

shm:/path/to/datafile[(size)]

Thismakesuseofahigh-performancehashtable(approx.sizebytesinsize)insideasharedmemorysegmentinRAM(establishedvia/path/to/datafile)tosynchronizethelocalOpenSSLmemorycachesoftheserverprocesses.Thisstoragetypeisnotavailableonallplatforms.

ExamplesSSLSessionCachedbm:/usr/local/apache/logs/ssl_gcache_data

SSLSessionCache

shm:/usr/local/apache/logs/ssl_gcache_data(512000)

SSLSessionCacheTimeoutDirective

Description: NumberofsecondsbeforeanSSLsessionexpiresintheSessionCache

Syntax: SSLSessionCacheTimeoutseconds

Default: SSLSessionCacheTimeout300

Thisdirectivesetsthetimeoutinsecondsfortheinformationstoredintheglobal/inter-processSSLSessionCacheandtheOpenSSLinternalmemorycache.Itcanbesetaslowas15fortesting,butshouldbesettohighervalueslike300inreallife.

ExampleSSLSessionCacheTimeout600

SSLUserNameDirective

Description: VariablenametodetermineusernameSyntax: SSLUserNamevarname

Context: serverconfig,directory,.htaccessOverride: AuthConfigStatus: ExtensionModule: mod_sslCompatibility: AvailableinApache2.0.51andlater

Thisdirectivesetsthe"user"fieldintheApacherequestobject.Thisisusedbylowermodulestoidentifytheuserwithacharacterstring.Inparticular,thismaycausetheenvironmentvariableREMOTE_USERtobeset.ThevarnamecanbeanyoftheSSLenvironmentvariables.

ExampleSSLUserNameSSL_CLIENT_S_DN_CN

SSLVerifyClientDirective

Description: TypeofClientCertificateverificationSyntax: SSLVerifyClientlevel

Default: SSLVerifyClientnone

ThisdirectivesetstheCertificateverificationlevelfortheClientAuthentication.Noticethatthisdirectivecanbeusedbothinper-serverandper-directorycontext.Inper-servercontextitappliestotheclientauthenticationprocessusedinthestandardSSLhandshakewhenaconnectionisestablished.Inper-directorycontextitforcesaSSLrenegotationwiththereconfiguredclientverificationlevelaftertheHTTPrequestwasreadbutbeforetheHTTPresponseissent.

Thefollowinglevelsareavailableforlevel:

none:noclientCertificateisrequiredatalloptional:theclientmaypresentavalidCertificaterequire:theclienthastopresentavalidCertificateoptional_no_ca:theclientmaypresentavalidCertificatebutitneednottobe(successfully)verifiable.

Inpracticeonlylevelsnoneandrequirearereallyinteresting,becauseleveloptionaldoesn'tworkwithallbrowsersandleveloptional_no_caisactuallyagainsttheideaofauthentication(butcanbeusedtoestablishSSLtestpages,etc.)

ExampleSSLVerifyClientrequire

SSLVerifyDepthDirective

Description: MaximumdepthofCACertificatesinClientCertificateverification

Syntax: SSLVerifyDepthnumber

Default: SSLVerifyDepth1

Thisdirectivesetshowdeeplymod_sslshouldverifybeforedecidingthattheclientsdon'thaveavalidcertificate.Noticethatthisdirectivecanbeusedbothinper-serverandper-directorycontext.Inper-servercontextitappliestotheclientauthenticationprocessusedinthestandardSSLhandshakewhenaconnectionisestablished.Inper-directorycontextitforcesaSSLrenegotationwiththereconfiguredclientverificationdepthaftertheHTTPrequestwasreadbutbeforetheHTTPresponseissent.

Thedepthactuallyisthemaximumnumberofintermediatecertificateissuers,i.e.thenumberofCAcertificateswhicharemaxallowedtobefollowedwhileverifyingtheclientcertificate.Adepthof0meansthatself-signedclientcertificatesareacceptedonly,thedefaultdepthof1meanstheclientcertificatecanbeself-signedorhastobesignedbyaCAwhichisdirectlyknowntotheserver(i.e.theCA'scertificateisunderSSLCACertificatePath),etc.

ExampleSSLVerifyDepth10

||FAQ||

Apachemod_status

:: Base: status_module: mod_status.c

Status

(:) (*)(*)

11 (*)ApacheCPU(*)(*)

Status

foo.com

OrderDeny,Allow

Denyfromall

Allowfrom.foo.com

</Location>

http://your.server.name/server-status

Nstatus?refresh=N

http://your.server.name/server-status?auto Apache /support

mod_status

||FAQ||

ExtendedStatus

:: ExtendedStatusOn|Off

: ExtendedStatusOff

:: Base: mod_status: ExtendedStatusApache1.3.2

||FAQ||

Apachemod_suexec

: CGI: Extension: suexec_module: mod_suexec.c: Apache2.0

suexecCGI

SuEXEC

||FAQ||

SuexecUserGroup

: CGI: SuexecUserGroupUserGroup

: ,: Extension: mod_suexec: SuexecUserGroup2.0

SuexecUserGroupCGI CGI1.3VirtualHosts UserGroup

SuexecUserGroupnobodynogroup

||FAQ||

Apachemod_unique_id

: : Extension: unique_id_module: mod_unique_id.c

ApacheUnix

pid(ID) 32

Unix(UTC1970 11)16 (ip_addr,pid,time_stamp,counter)httpd 65536pid

httpd (÷10)modulo655360)

pidpid

rand()seed seed

? 500 1.5%

UTCNTP UTC

UNIQUE_ID112(32IP 32pid,3216 [A-Za-z0-9@-]MIMEbase6419base64 [A-Za-z0-9+/] + /URL

||FAQ||

:IPpid, UNIQUE_ID

UNIQUE_ID

WindowsNT)httpd ()

||FAQ||

Apachemod_userdir

:: Base: userdir_module: mod_userdir.c

http://example.com/~user/

URLpublic_html

UserDir

:: UserDirdirectory-filename

: UserDirpublic_html

: ,: Base: mod_userdir

UserDir

disabled enabled() disabled enabled

enabled disabled UserDir http://www.foo.com/~bob/one/two.html:

UserDirUserDirpublic_html ~bob/public_html/one/two.htmlUserDir/usr/web /usr/web/bob/one/two.htmlUserDir/home/*/www /home/bob/www/one/two.html

UserDirUserDirhttp://www.foo.com/users

http://www.foo.com/users/bob/one/two.html

UserDirhttp://www.foo.com/*/usr

http://www.foo.com/bob/usr/one/two.html

UserDirhttp://www.foo.com/~*/

http://www.foo.com/~bob/one/two.html

||FAQ||

; "UserDir./" "/~rootdisabledroot"

UserDir:

UserDirdisabled

UserDirenableduser1user2user3

UserDir:

UserDirenabled

UserDirdisableduser4user5user6

Userdirpublic_html/usr/webhttp://www.foo.com/

http://www.foo.com/~bob/one/two.html~bob/public_html/one/two.html/usr/web/bob/one/two.htmlhttp://www.foo.com/bob/one/two.html

Apache

public_html

ApacheModulemod_usertrack

Description: ClickstreamloggingofuseractivityonasiteStatus: ExtensionModuleIdentifier: usertrack_moduleSourceFile: mod_usertrack.c

SummaryPreviousreleasesofApachehaveincludedamodulewhichgeneratesa'clickstream'logofuseractivityonasiteusingcookies.Thiswascalledthe"cookies"module,mod_cookies.InApache1.2andlaterthismodulehasbeenrenamedthe"usertracking"module,mod_usertrack.Thismodulehasbeensimplifiedandnewdirectivesadded.

Logging

Previously,thecookiesmodule(nowtheusertrackingmodule)diditsownlogging,usingtheCookieLogdirective.Inthisrelease,thismoduledoesnologgingatall.Instead,aconfigurablelogformatfileshouldbeusedtologuserclick-streams.Thisispossiblebecausetheloggingmodulenowallowsmultiplelogfiles.Thecookieitselfisloggedbyusingthetext%{cookie}ninthelogfileformat.Forexample:

CustomLoglogs/clickstream"%{cookie}n%r%t"

ForbackwardcompatibilitytheconfigurablelogmoduleimplementstheoldCookieLogdirective,butthisshouldbeupgradedtotheaboveCustomLogdirective.

2-digitor4-digitdatesforcookies?

(thefollowingisfrommessage<022701bda43d$9d32bbb0$1201a8c0@christian.office.sane.com>inthenew-httpdarchives)

From:"ChristianAllen"<christian@sane.com>

Subject:Re:ApacheY2Kbuginmod_usertrack.c

Date:Tue,30Jun199811:41:56-0400

Didsomeworkwithcookiesanddugupsomeinfothatmightbeuseful.

True,NetscapeclaimsthatthecorrectformatNOWisfourdigitdates,and

fourdigitdatesdoinfactwork...forNetscape4.x(Communicator),that

is.However,3.xandbelowdoNOTacceptthem.ItseemsthatNetscape

originallyhada2-digitstandard,andthenwithalloftheY2Khypeand

probablyafewcomplaints,changedtoafourdigitdateforCommunicator.

Fortunately,4.xalsounderstandsthe2-digitformat,andsothebestwayto

ensurethatyourexpirationdateislegibletotheclient'sbrowseristo

use2-digitdates.

However,thisdoesnotlimitexpirationdatestotheyear2000;ifyouuse

anexpirationyearof"13",forexample,itisinterpretedas2013,NOT

1913!Infact,youcanuseanexpirationyearofupto"37",anditwillbe

understoodas"2037"bybothMSIEandNetscapeversions3.xandup(notsure

aboutversionsprevioustothose).NotsurewhyNetscapeusedthat

particularyearasitscut-offpoint,butmyguessisthatitwasinrespect

toUNIX's2038problem.Netscape/MSIE4.xseemtobeabletounderstand

2-digityearsbeyondthat,atleastuntil"50"forsure(Ithinkthey

understandupuntilabout"70",butnotforsure).

Summary:Mozilla3.xandupunderstandstwodigitdatesupuntil"37"

(2037).Mozilla4.xunderstandsupuntilatleast"50"(2050)in2-digit

form,butalsounderstands4-digityears,whichcanprobablyreachupuntil

9999.Yourbestbetforsendingalong-lifecookieistosenditforsome

timelateintheyear"37".

CookieDomainDirective

Description: ThedomaintowhichthetrackingcookieappliesSyntax: CookieDomaindomain

Context: serverconfig,virtualhost,directory,.htaccessOverride: FileInfoStatus: ExtensionModule: mod_usertrack

Thisdirectivecontrolsthesettingofthedomaintowhichthetrackingcookieapplies.Ifnotpresent,nodomainisincludedinthecookieheaderfield.

Thedomainstringmustbeginwithadot,andmustincludeatleastoneembeddeddot.Thatis,.foo.comislegal,butfoo.bar.comand.comarenot.

Mostbrowsersinusetodaywillnotallowcookiestobesetforatwo-parttopleveldomain,suchas.co.uk,althoughsuchadomainostensiblyfulfillstherequirementsabove.Thesedomainsareequivalenttotopleveldomainssuchas.com,andallowingsuchcookiesmaybeasecurityrisk.Thus,ifyouareunderatwo-parttopleveldomain,youshouldstilluseyouractualdomain,asyouwouldwithanyothertopleveldomain(forexample,use.foo.co.uk).

CookieExpiresDirective

Description: ExpirytimeforthetrackingcookieSyntax: CookieExpiresexpiry-period

Whenused,thisdirectivesetsanexpirytimeonthecookiegeneratedbytheusertrackmodule.Theexpiry-periodcanbegiveneitherasanumberofseconds,orintheformatsuchas"2weeks3days7hours".Validdenominationsare:years,months,weeks,days,hours,minutesandseconds.Iftheexpirytimeisinanyformatotherthanonenumberindicatingthenumberofseconds,itmustbeenclosedbydoublequotes.

Ifthisdirectiveisnotused,cookieslastonlyforthecurrentbrowsersession.

CookieNameDirective

Description: NameofthetrackingcookieSyntax: CookieNametoken

Default: CookieNameApache

Thisdirectiveallowsyoutochangethenameofthecookiethismoduleusesforitstrackingpurposes.Bydefaultthecookieisnamed"Apache".

Youmustspecifyavalidcookiename;resultsareunpredictableifyouuseanamecontainingunusualcharacters.ValidcharactersincludeA-Z,a-z,0-9,"_",and"-".

CookieStyleDirective

Description: FormatofthecookieheaderfieldSyntax: CookieStyle

Netscape|Cookie|Cookie2|RFC2109|RFC2965

Default: CookieStyleNetscape

Thisdirectivecontrolstheformatofthecookieheaderfield.Thethreeformatsallowedare:

Netscape,whichistheoriginalbutnowdeprecatedsyntax.Thisisthedefault,andthesyntaxApachehashistoricallyused.CookieorRFC2109,whichisthesyntaxthatsupersededtheNetscapesyntax.Cookie2orRFC2965,whichisthemostcurrentcookiesyntax.

Notallclientscanunderstandalloftheseformats.butyoushouldusethenewestonethatisgenerallyacceptabletoyourusers'browsers.Atthetimeofwriting,mostbrowsersonlyfullysupportCookieStyleNetscape.

CookieTrackingDirective

Description: EnablestrackingcookieSyntax: CookieTrackingon|off

Default: CookieTrackingoff

Whenmod_usertrackisloaded,andCookieTrackingonisset,Apachewillsendauser-trackingcookieforallnewrequests.Thisdirectivecanbeusedtoturnthisbehavioronoroffonaper-serverorper-directorybasis.Bydefault,enablingmod_usertrackwillnotactivatecookies.

||FAQ||

Apachemod_version

:: Extension: version_module: mod_version.c: 2.0.54

<IfVersion2.1.0>

#currenthttpdversionisexactly2.1.0

</IfVersion>

#usereallynewfeatures:-)

</IfVersion>

:: <IfVersion[[!]operator]version>...

</IfVersion>

: ,,,.htaccess: All: Extension: mod_version

<IfVersion> httpd major[.minor[.patch]] 2.1.0 2.2patch 0

operator= == httpd

> httpd

>= httpd

< httpd

<= httpd

#thishappensonlyinversionsgreateror

#equal2.1.0.

</IfVersion>

http :

||FAQ||

operator=or== version

/regex/~ version regex

<IfVersion=/^2.1.[01234]$/>

#e.g.workaroundforbuggyversions

</IfVersion>

<IfVersion!~^2.1.[01234]$>

#notforthoseversions

</IfVersion>

operator =

ApacheModulemod_vhost_alias

Description: Providesfordynamicallyconfiguredmassvirtualhosting

Status: ExtensionModuleIdentifier: vhost_alias_moduleSourceFile: mod_vhost_alias.c

SummaryThismodulecreatesdynamicallyconfiguredvirtualhosts,byallowingtheIPaddressand/ortheHost:headeroftheHTTPrequesttobeusedaspartofthepathnametodeterminewhatfilestoserve.Thisallowsforeasyuseofahugenumberofvirtualhostswithsimilarconfigurations.

Ifmod_aliasormod_userdirareusedfortranslatingURIstofilenames,theywilloverridethedirectivesofmod_vhost_aliasdescribedbelow.Forexample,thefollowingconfigurationwillmap/cgi-bin/script.plto/usr/local/apache2/cgi-bin/script.plinallcases:

ScriptAlias/cgi-bin//usr/local/apache2/cgi-bin/

VirtualScriptAlias/never/found/%0/cgi-bin/

SeealsoUseCanonicalName

Dynamicallyconfiguredmassvirtualhosting

DirectoryNameInterpolation

Allthedirectivesinthismoduleinterpolateastringintoapathname.Theinterpolatedstring(henceforthcalledthe"name")maybeeithertheservername(seetheUseCanonicalNamedirectivefordetailsonhowthisisdetermined)ortheIPaddressofthevirtualhostontheserverindotted-quadformat.Theinterpolationiscontrolledbyspecifiersinspiredbyprintfwhichhaveanumberofformats:

%% inserta%%p inserttheportnumberofthevirtualhost%N.M insert(partof)thename

NandMareusedtospecifysubstringsofthename.Nselectsfromthedot-separatedcomponentsofthename,andMselectscharacterswithinwhateverNhasselected.Misoptionalanddefaultstozeroifitisn'tpresent;thedotmustbepresentifandonlyifMispresent.Theinterpretationisasfollows:

0 thewholename1 thefirstpart2 thesecondpart-1 thelastpart-2 thepenultimatepart2+ thesecondandallsubsequentparts-2+ thepenultimateandallprecedingparts1+and-1+ thesameas0

IfNorMisgreaterthanthenumberofpartsavailableasingleunderscoreisinterpolated.

Examples

Forsimplename-basedvirtualhostsyoumightusethefollowingdirectivesinyourserverconfigurationfile:

UseCanonicalNameOff

VirtualDocumentRoot/usr/local/apache/vhosts/%0

Arequestforhttp://www.example.com/directory/file.htmlwillbesatisfiedbythefile/usr/local/apache/vhosts/www.example.com/directory/file.html

Foraverylargenumberofvirtualhostsitisagoodideatoarrangethefilestoreducethesizeofthevhostsdirectory.Todothisyoumightusethefollowinginyourconfigurationfile:

UseCanonicalNameOff

VirtualDocumentRoot

/usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2

Arequestforhttp://www.domain.example.com/directory/file.html

willbesatisfiedbythefile/usr/local/apache/vhosts/example.com/d/o/m/domain/directory/file.html

Amoreevenspreadoffilescanbeachievedbyhashingfromtheendofthename,forexample:

VirtualDocumentRoot

/usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2

Theexamplerequestwouldcomefrom/usr/local/apache/vhosts/example.com/n/i/a/domain/directory/file.html

Alternativelyyoumightuse:

VirtualDocumentRoot

/usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+

Theexamplerequestwouldcomefrom/usr/local/apache/vhosts/example.com/d/o/m/ain/directory/file.html

ForIP-basedvirtualhostingyoumightusethefollowinginyourconfigurationfile:

UseCanonicalNameDNS

VirtualDocumentRootIP/usr/local/apache/vhosts/%1/%2/%3/%4/docs

VirtualScriptAliasIP/usr/local/apache/vhosts/%1/%2/%3/%4/cgi-

wouldbesatisfiedbythefile/usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html

iftheIPaddressofwww.domain.example.comwere10.20.30.40.Arequestforhttp://www.domain.example.com/cgi-bin/script.pl

wouldbesatisfiedbyexecutingtheprogram/usr/local/apache/vhosts/10/20/30/40/cgi-

bin/script.pl.

Ifyouwanttoincludethe.characterinaVirtualDocumentRootdirective,butitclasheswitha%directive,youcanworkaroundtheprobleminthefollowingway:

VirtualDocumentRoot/usr/local/apache/vhosts/%2.0.%3.0

willbesatisfiedbythefile/usr/local/apache/vhosts/domain.example/directory/file.html

TheLogFormatdirectives%Vand%Aareusefulinconjunctionwiththismodule.

VirtualDocumentRootDirective

Description: Dynamicallyconfigurethelocationofthedocumentrootforagivenvirtualhost

Syntax: VirtualDocumentRootinterpolated-

directory|none

Default: VirtualDocumentRootnone

Context: serverconfig,virtualhostStatus: ExtensionModule: mod_vhost_alias

TheVirtualDocumentRootdirectiveallowsyoutodeterminewhereApachewillfindyourdocumentsbasedonthevalueoftheservername.Theresultofexpandinginterpolated-directoryisusedastherootofthedocumenttreeinasimilarmannertotheDocumentRootdirective'sargument.Ifinterpolated-directoryisnonethenVirtualDocumentRootisturnedoff.ThisdirectivecannotbeusedinthesamecontextasVirtualDocumentRootIP.

VirtualDocumentRootIPDirective

Description: Dynamicallyconfigurethelocationofthedocumentrootforagivenvirtualhost

Syntax: VirtualDocumentRootIPinterpolated-

directory|none

Default: VirtualDocumentRootIPnone

TheVirtualDocumentRootIPdirectiveisliketheVirtualDocumentRootdirective,exceptthatitusestheIPaddressoftheserverendoftheconnectionfordirectoryinterpolationinsteadoftheservername.

VirtualScriptAliasDirective

Description: DynamicallyconfigurethelocationoftheCGIdirectoryforagivenvirtualhost

Syntax: VirtualScriptAliasinterpolated-

directory|none

Default: VirtualScriptAliasnone

TheVirtualScriptAliasdirectiveallowsyoutodeterminewhereApachewillfindCGIscriptsinasimilarmannertoVirtualDocumentRootdoesforotherdocuments.ItmatchesrequestsforURIsstarting/cgi-bin/,muchlikeScriptAlias/cgi-bin/would.

VirtualScriptAliasIPDirective

Description: Dynamicallyconfigurethelocationofthecgidirectoryforagivenvirtualhost

Syntax: VirtualScriptAliasIPinterpolated-

directory|none

Default: VirtualScriptAliasIPnone

TheVirtualScriptAliasIPdirectiveisliketheVirtualScriptAliasdirective,exceptthatitusestheIPaddressoftheserverendoftheconnectionfordirectoryinterpolationinsteadoftheservername.

ApacheHTTPServerVersion2.0Apache>HTTPServer>Documentation>Version2.0>DeveloperDocumentation

Apache1.3APInotes

Warning

Thisdocumenthasnotbeenupdatedtotakeintoaccountchangesmadeinthe2.0versionoftheApacheHTTPServer.Someoftheinformationmaystillberelevant,butpleaseuseitwithcare.

ThesearesomenotesontheApacheAPIandthedatastructuresyouhavetodealwith,etc.Theyarenotyetnearlycomplete,buthopefully,theywillhelpyougetyourbearings.KeepinmindthattheAPIisstillsubjecttochangeaswegainexperiencewithit.(SeetheTODOfileforwhatmightbecoming).However,itwillbeeasytoadaptmodulestoanychangesthataremade.(Wehavemoremodulestoadaptthanyoudo).

Afewnotesongeneralpedagogicalstylehere.Intheinterestofconciseness,allstructuredeclarationshereareincomplete--therealoneshavemoreslotsthatI'mnottellingyouabout.Forthemostpart,thesearereservedtoonecomponentoftheservercoreoranother,andshouldbealteredbymoduleswithcaution.However,insomecases,theyreallyarethingsIjusthaven'tgottenaroundtoyet.Welcometothebleedingedge.

Finally,here'sanoutline,togiveyousomebareideaofwhat'scomingup,andinwhatorder:

Basicconcepts.Handlers,Modules,andRequestsAbrieftourofamodule

HowhandlersworkAbrieftouroftherequest_recWhererequest_recstructurescomefrom

Handlingrequests,declining,andreturningerrorcodesSpecialconsiderationsforresponsehandlersSpecialconsiderationsforauthenticationhandlersSpecialconsiderationsforlogginghandlers

ResourceallocationandresourcepoolsConfiguration,commandsandthelike

Per-directoryconfigurationstructuresCommandhandlingSidenotes---per-serverconfiguration,virtualservers,etc.

Basicconcepts

WebeginwithanoverviewofthebasicconceptsbehindtheAPI,andhowtheyaremanifestedinthecode.

Handlers,Modules,andRequestsApachebreaksdownrequesthandlingintoaseriesofsteps,moreorlessthesamewaytheNetscapeserverAPIdoes(althoughthisAPIhasafewmorestagesthanNetSitedoes,ashooksforstuffIthoughtmightbeusefulinthefuture).Theseare:

URI->FilenametranslationAuthIDchecking[istheuserwhotheysaytheyare?]Authaccesschecking[istheuserauthorizedhere?]AccesscheckingotherthanauthDeterminingMIMEtypeoftheobjectrequested`Fixups'--therearen'tanyoftheseyet,butthephaseisintendedasahookforpossibleextensionslikeSetEnv,whichdon'treallyfitwellelsewhere.Actuallysendingaresponsebacktotheclient.Loggingtherequest

Thesephasesarehandledbylookingateachofasuccessionofmodules,lookingtoseeifeachofthemhasahandlerforthephase,andattemptinginvokingitifso.Thehandlercantypicallydooneofthreethings:

Handletherequest,andindicatethatithasdonesobyreturningthemagicconstantOK.Declinetohandletherequest,byreturningthemagicintegerconstantDECLINED.Inthiscase,theserverbehavesinallrespectsasifthehandlersimplyhadn'tbeenthere.Signalanerror,byreturningoneoftheHTTPerrorcodes.Thisterminatesnormalhandlingoftherequest,althoughanErrorDocumentmaybeinvokedtotrytomopup,anditwillbe

loggedinanycase.

Mostphasesareterminatedbythefirstmodulethathandlesthem;however,forlogging,`fixups',andnon-accessauthenticationchecking,allhandlersalwaysrun(barringanerror).Also,theresponsephaseisuniqueinthatmodulesmaydeclaremultiplehandlersforit,viaadispatchtablekeyedontheMIMEtypeoftherequestedobject.Modulesmaydeclarearesponse-phasehandlerwhichcanhandleanyrequest,bygivingitthekey*/*(i.e.,awildcardMIMEtypespecification).However,wildcardhandlersareonlyinvokediftheserverhasalreadytriedandfailedtofindamorespecificresponsehandlerfortheMIMEtypeoftherequestedobject(eithernoneexisted,ortheyalldeclined).

Thehandlersthemselvesarefunctionsofoneargument(arequest_recstructure.videinfra),whichreturnsaninteger,asabove.

AbrieftourofamoduleAtthispoint,weneedtoexplainthestructureofamodule.Ourcandidatewillbeoneofthemessierones,theCGImodule--thishandlesbothCGIscriptsandtheScriptAliasconfigfilecommand.It'sactuallyagreatdealmorecomplicatedthanmostmodules,butifwe'regoingtohaveonlyoneexample,itmightaswellbetheonewithitsfingersineveryplace.

Let'sbeginwithhandlers.InordertohandletheCGIscripts,themoduledeclaresaresponsehandlerforthem.BecauseofScriptAlias,italsohashandlersforthenametranslationphase(torecognizeScriptAliasedURIs),thetype-checkingphase(anyScriptAliasedrequestistypedasaCGIscript).

Themoduleneedstomaintainsomeper(virtual)serverinformation,namely,theScriptAliasesineffect;themodule

structurethereforecontainspointerstoafunctionswhichbuildsthesestructures,andtoanotherwhichcombinestwoofthem(incasethemainserverandavirtualserverbothhaveScriptAliasesdeclared).

Finally,thismodulecontainscodetohandletheScriptAliascommanditself.Thisparticularmoduleonlydeclaresonecommand,buttherecouldbemore,somoduleshavecommandtableswhichdeclaretheircommands,anddescribewheretheyarepermitted,andhowtheyaretobeinvoked.

Afinalnoteonthedeclaredtypesoftheargumentsofsomeofthesecommands:apoolisapointertoaresourcepoolstructure;theseareusedbytheservertokeeptrackofthememorywhichhasbeenallocated,filesopened,etc.,eithertoserviceaparticularrequest,ortohandletheprocessofconfiguringitself.Thatway,whentherequestisover(or,fortheconfigurationpool,whentheserverisrestarting),thememorycanbefreed,andthefilesclosed,enmasse,withoutanyonehavingtowriteexplicitcodetotrackthemalldownanddisposeofthem.Also,acmd_parmsstructurecontainsvariousinformationabouttheconfigfilebeingread,andotherstatusinformation,whichissometimesofusetothefunctionwhichprocessesaconfig-filecommand(suchasScriptAlias).Withnofurtherado,themoduleitself:

/*Declarationsofhandlers.*/

inttranslate_scriptalias(request_rec*);

inttype_scriptalias(request_rec*);

intcgi_handler(request_rec*);

/*Subsidiarydispatchtableforresponse-phase

*handlers,byMIMEtype*/

handler_reccgi_handlers[]={

{"application/x-httpd-cgi",cgi_handler},

{NULL}

/*Declarationsofroutinestomanipulatethe

*module'sconfigurationinfo.Notethattheseare

*returned,andpassedin,asvoid*'s;theserver

*corekeepstrackofthem,butitdoesn't,andcan't,

*knowtheirinternalstructure.

void*make_cgi_server_config(pool*);

void*merge_cgi_server_config(pool*,void*,void*);

/*Declarationsofroutinestohandleconfig-filecommands*/

externchar*script_alias(cmd_parms*,void*per_dir_config,

char*fake,char*real);

command_reccgi_cmds[]={

{"ScriptAlias",script_alias,NULL,RSRC_CONF,TAKE2,

"afakenameandarealname"},

{NULL}

modulecgi_module={

STANDARD_MODULE_STUFF,

NULL,/*initializer*/

NULL,/*dirconfigcreator*/

NULL,/*dirmerger*/

make_cgi_server_config,/*serverconfig*/

merge_cgi_server_config,/*mergeserverconfig*/

cgi_cmds,/*commandtable*/

cgi_handlers,/*handlers*/

translate_scriptalias,/*filenametranslation*/

NULL,/*check_user_id*/

NULL,/*checkauth*/

NULL,/*checkaccess*/

type_scriptalias,/*type_checker*/

NULL,/*fixups*/

NULL,/*logger*/

NULL/*headerparser*/

Howhandlerswork

Thesoleargumenttohandlersisarequest_recstructure.Thisstructuredescribesaparticularrequestwhichhasbeenmadetotheserver,onbehalfofaclient.Inmostcases,eachconnectiontotheclientgeneratesonlyonerequest_recstructure.

Abrieftouroftherequest_recTherequest_reccontainspointerstoaresourcepoolwhichwillbeclearedwhentheserverisfinishedhandlingtherequest;tostructurescontainingper-serverandper-connectioninformation,andmostimportantly,informationontherequestitself.

Themostimportantsuchinformationisasmallsetofcharacterstringsdescribingattributesoftheobjectbeingrequested,includingitsURI,filename,content-typeandcontent-encoding(thesebeingfilledinbythetranslationandtype-checkhandlerswhichhandletherequest,respectively).

OthercommonlyuseddataitemsaretablesgivingtheMIMEheadersontheclient'soriginalrequest,MIMEheaderstobesentbackwiththeresponse(whichmodulescanaddtoatwill),andenvironmentvariablesforanysubprocesseswhicharespawnedoffinthecourseofservicingtherequest.Thesetablesaremanipulatedusingtheap_table_getandap_table_setroutines.

NotethattheContent-typeheadervaluecannotbesetbymodulecontent-handlersusingtheap_table_*()routines.Rather,itissetbypointingthecontent_typefieldintherequest_recstructuretoanappropriatestring.e.g.,

r->content_type="text/html";

Finally,therearepointerstotwodatastructureswhich,inturn,pointtoper-moduleconfigurationstructures.Specifically,theseholdpointerstothedatastructureswhichthemodulehasbuilttodescribethewayithasbeenconfiguredtooperateinagivendirectory(via.htaccessfilesor<Directory>sections),forprivatedataithasbuiltinthecourseofservicingtherequest(somodules'handlersforonephasecanpass`notes'totheirhandlersforotherphases).Thereisanothersuchconfigurationvectorintheserver_recdatastructurepointedtobytherequest_rec,whichcontainsper(virtual)serverconfigurationdata.

Hereisanabridgeddeclaration,givingthefieldsmostcommonlyused:

structrequest_rec{

pool*pool;

conn_rec*connection;

server_rec*server;

/*Whatobjectisbeingrequested*/

char*uri;

char*filename;

char*path_info;

char*args;/*QUERY_ARGS,ifany*/

structstatfinfo;/*Setbyservercore;

*st_modesettozeroifnosuchfile*/

char*content_type;

char*content_encoding;

/*MIMEheaderenvironments,inandout.Also,

*anarraycontainingenvironmentvariablesto

*bepassedtosubprocesses,sopeoplecanwrite

*modulestoaddtothatenvironment.

*Thedifferencebetweenheaders_outand

*err_headers_outisthatthelatterareprinted

*evenonerror,andpersistacrossinternal

*redirects(sotheheadersprintedfor

*ErrorDocumenthandlerswillhavethem).

table*headers_in;table*headers_out;table*err_headers_out;table*subprocess_env;

/*Infoabouttherequestitself...*/

intheader_only;/*HEADrequest,asopposedtoGET*/

char*protocol;/*Protocol,asgiventous,orHTTP/0.9*/

char*method;/*GET,HEAD,POST,etc.*/

intmethod_number;/*M_GET,M_POST,etc.*/

/*Infoforlogging*/

char*the_request;

intbytes_sent;

/*Aflagwhichmodulescanset,toindicatethat

*thedatabeingreturnedisvolatile,andclients

*shouldbetoldnottocacheit.

intno_cache;

/*Variousotherconfiginfowhichmaychange

*with.htaccessfiles

*Theseareconfigvectors,withonevoid*

*pointerforeachmodule(thethingpointed

*tobeingthemodule'sbusiness).

void*per_dir_config;/*Optionssetinconfigfiles,etc.*/

void*request_config;/*Noteson*this*request*/

Whererequest_recstructurescomefromMostrequest_recstructuresarebuiltbyreadinganHTTPrequestfromaclient,andfillinginthefields.However,thereareafewexceptions:

Iftherequestistoanimagemap,atypemap(i.e.,a*.varfile),oraCGIscriptwhichreturnedalocal`Location:',thentheresourcewhichtheuserrequestedisgoingtobeultimatelylocatedbysomeURIotherthanwhattheclientoriginallysupplied.Inthiscase,theserverdoesaninternalredirect,constructinganewrequest_recforthenewURI,andprocessingitalmostexactlyasiftheclienthadrequestedthenewURIdirectly.Ifsomehandlersignaledanerror,andanErrorDocumentisinscope,thesameinternalredirectmachinerycomesintoplay.Finally,ahandleroccasionallyneedstoinvestigate`whatwouldhappenif'someotherrequestwererun.Forinstance,thedirectoryindexingmoduleneedstoknowwhatMIMEtypewouldbeassignedtoarequestforeachdirectoryentry,inordertofigureoutwhaticontouse.

Suchhandlerscanconstructasub-request,usingthefunctionsap_sub_req_lookup_file,ap_sub_req_lookup_uri,andap_sub_req_method_uri;theseconstructanewrequest_recstructureandprocessesitasyouwouldexpect,uptobutnotincludingthepointofactuallysendingaresponse.(Thesefunctionsskipovertheaccesschecksifthesub-requestisforafileinthesamedirectoryastheoriginalrequest).

(Server-sideincludesworkbybuildingsub-requestsandthenactuallyinvokingtheresponsehandlerforthem,viathefunctionap_run_sub_req).

Handlingrequests,declining,andreturningerrorcodes

Asdiscussedabove,eachhandler,wheninvokedtohandleaparticularrequest_rec,hastoreturnaninttoindicatewhathappened.Thatcaneitherbe

OK--therequestwashandledsuccessfully.Thismayormaynotterminatethephase.DECLINED--noerroneousconditionexists,butthemoduledeclinestohandlethephase;theservertriestofindanother.anHTTPerrorcode,whichabortshandlingoftherequest.

NotethatiftheerrorcodereturnedisREDIRECT,thenthemoduleshouldputaLocationintherequest'sheaders_out,toindicatewheretheclientshouldberedirectedto.

SpecialconsiderationsforresponsehandlersHandlersformostphasesdotheirworkbysimplysettingafewfieldsintherequest_recstructure(or,inthecaseofaccesscheckers,simplybyreturningthecorrecterrorcode).However,responsehandlershavetoactuallysendarequestbacktotheclient.

TheyshouldbeginbysendinganHTTPresponseheader,usingthefunctionap_send_http_header.(Youdon'thavetodoanythingspecialtoskipsendingtheheaderforHTTP/0.9requests;thefunctionfiguresoutonitsownthatitshouldn'tdoanything).Iftherequestismarkedheader_only,that'salltheyshoulddo;theyshouldreturnafterthat,withoutattemptinganyfurtheroutput.

Otherwise,theyshouldproducearequestbodywhichrespondstotheclientasappropriate.Theprimitivesforthisareap_rputcandap_rprintf,forinternallygeneratedoutput,andap_send_fd,tocopythecontentsofsomeFILE*straighttotheclient.

Atthispoint,youshouldmoreorlessunderstandthefollowingpieceofcode,whichisthehandlerwhichhandlesGETrequestswhichhavenomorespecifichandler;italsoshowshowconditionalGETscanbehandled,ifit'sdesirabletodosoinaparticularresponsehandler--ap_set_last_modifiedchecksagainsttheIf-modified-sincevaluesuppliedbytheclient,ifany,andreturnsanappropriatecode(whichwill,ifnonzero,beUSE_LOCAL_COPY).Nosimilarconsiderationsapplyforap_set_content_length,butitreturnsanerrorcodeforsymmetry.

intdefault_handler(request_rec*r)

interrstatus;

FILE*f;

if(r->method_number!=M_GET)returnDECLINED;

if(r->finfo.st_mode==0)returnNOT_FOUND;

if((errstatus=ap_set_content_length(r,r-

>finfo.st_size))

||(errstatus=ap_set_last_modified(r,r-

>finfo.st_mtime)))

returnerrstatus;

f=fopen(r->filename,"r");

if(f==NULL){

log_reason("filepermissionsdenyserveraccess",r-

>filename,r);

returnFORBIDDEN;

register_timeout("send",r);

ap_send_http_header(r);

if(!r->header_only)send_fd(f,r);

ap_pfclose(r->pool,f);

returnOK;

Finally,ifallofthisistoomuchofachallenge,thereareafew

waysoutofit.Firstoff,asshownabove,aresponsehandlerwhichhasnotyetproducedanyoutputcansimplyreturnanerrorcode,inwhichcasetheserverwillautomaticallyproduceanerrorresponse.Secondly,itcanpunttosomeotherhandlerbyinvokingap_internal_redirect,whichishowtheinternalredirectionmachinerydiscussedaboveisinvoked.AresponsehandlerwhichhasinternallyredirectedshouldalwaysreturnOK.

(Invokingap_internal_redirectfromhandlerswhicharenotresponsehandlerswillleadtoseriousconfusion).

SpecialconsiderationsforauthenticationhandlersStuffthatshouldbediscussedhereindetail:

Authentication-phasehandlersnotinvokedunlessauthisconfiguredforthedirectory.Commonauthconfigurationstoredinthecoreper-dirconfiguration;ithasaccessorsap_auth_type,ap_auth_name,andap_requires.Commonroutines,tohandletheprotocolendofthings,atleastforHTTPbasicauthentication(ap_get_basic_auth_pw,whichsetstheconnection->userstructurefieldautomatically,andap_note_basic_auth_failure,whicharrangesfortheproperWWW-Authenticate:headertobesentback).

SpecialconsiderationsforlogginghandlersWhenarequesthasinternallyredirected,thereisthequestionofwhattolog.Apachehandlesthisbybundlingtheentirechainofredirectsintoalistofrequest_recstructureswhicharethreadedthroughther->prevandr->nextpointers.Therequest_recwhichispassedtothelogginghandlersinsuchcasesistheonewhichwasoriginallybuiltfortheinitialrequestfromtheclient;note

thatthebytes_sentfieldwillonlybecorrectinthelastrequestinthechain(theoneforwhicharesponsewasactuallysent).

Resourceallocationandresourcepools

Oneoftheproblemsofwritinganddesigningaserver-poolserveristhatofpreventingleakage,thatis,allocatingresources(memory,openfiles,etc.),withoutsubsequentlyreleasingthem.Theresourcepoolmachineryisdesignedtomakeiteasytopreventthisfromhappening,byallowingresourcetobeallocatedinsuchawaythattheyareautomaticallyreleasedwhentheserverisdonewiththem.

Thewaythisworksisasfollows:thememorywhichisallocated,fileopened,etc.,todealwithaparticularrequestaretiedtoaresourcepoolwhichisallocatedfortherequest.Thepoolisadatastructurewhichitselftrackstheresourcesinquestion.

Whentherequesthasbeenprocessed,thepooliscleared.Atthatpoint,allthememoryassociatedwithitisreleasedforreuse,allfilesassociatedwithitareclosed,andanyotherclean-upfunctionswhichareassociatedwiththepoolarerun.Whenthisisover,wecanbeconfidentthatalltheresourcetiedtothepoolhavebeenreleased,andthatnoneofthemhaveleaked.

Serverrestarts,andallocationofmemoryandresourcesforper-serverconfiguration,arehandledinasimilarway.Thereisaconfigurationpool,whichkeepstrackofresourceswhichwereallocatedwhilereadingtheserverconfigurationfiles,andhandlingthecommandstherein(forinstance,thememorythatwasallocatedforper-servermoduleconfiguration,logfilesandotherfilesthatwereopened,andsoforth).Whentheserverrestarts,andhastorereadtheconfigurationfiles,theconfigurationpooliscleared,andsothememoryandfiledescriptorswhichweretakenupbyreadingthemthelasttimearemadeavailableforreuse.

Itshouldbenotedthatuseofthepoolmachineryisn'tgenerallyobligatory,exceptforsituationslikelogginghandlers,whereyoureallyneedtoregistercleanupstomakesurethatthelogfilegets

closedwhentheserverrestarts(thisismosteasilydonebyusingthefunctionap_pfopen,whichalsoarrangesfortheunderlyingfiledescriptortobeclosedbeforeanychildprocesses,suchasforCGIscripts,areexeced),orincaseyouareusingthetimeoutmachinery(whichisn'tyetevendocumentedhere).However,therearetwobenefitstousingit:resourcesallocatedtoapoolneverleak(evenifyouallocateascratchstring,andjustforgetaboutit);also,formemoryallocation,ap_pallocisgenerallyfasterthanmalloc.

Webeginherebydescribinghowmemoryisallocatedtopools,andthendiscusshowotherresourcesaretrackedbytheresourcepoolmachinery.

AllocationofmemoryinpoolsMemoryisallocatedtopoolsbycallingthefunctionap_palloc,whichtakestwoarguments,onebeingapointertoaresourcepoolstructure,andtheotherbeingtheamountofmemorytoallocate(inchars).Withinhandlersforhandlingrequests,themostcommonwayofgettingaresourcepoolstructureisbylookingatthepoolslotoftherelevantrequest_rec;hencetherepeatedappearanceofthefollowingidiominmodulecode:

intmy_handler(request_rec*r)

structmy_structure*foo;

foo=(foo*)ap_palloc(r->pool,sizeof(my_structure));

Notethatthereisnoap_pfree--ap_pallocedmemoryisfreedonlywhentheassociatedresourcepooliscleared.Thismeansthatap_pallocdoesnothavetodoasmuchaccountingasmalloc();allitdoesinthetypicalcaseistoroundupthesize,

bumpapointer,anddoarangecheck.

(Italsoraisesthepossibilitythatheavyuseofap_palloccouldcauseaserverprocesstogrowexcessivelylarge.Therearetwowaystodealwiththis,whicharedealtwithbelow;briefly,youcanusemalloc,andtrytobesurethatallofthememorygetsexplicitlyfreed,oryoucanallocateasub-poolofthemainpool,allocateyourmemoryinthesub-pool,andclearitoutperiodically.Thelattertechniqueisdiscussedinthesectiononsub-poolsbelow,andisusedinthedirectory-indexingcode,inordertoavoidexcessivestorageallocationwhenlistingdirectorieswiththousandsoffiles).

AllocatinginitializedmemoryTherearefunctionswhichallocateinitializedmemory,andarefrequentlyuseful.Thefunctionap_pcallochasthesameinterfaceasap_palloc,butclearsoutthememoryitallocatesbeforeitreturnsit.Thefunctionap_pstrduptakesaresourcepoolandachar*asarguments,andallocatesmemoryforacopyofthestringthepointerpointsto,returningapointertothecopy.Finallyap_pstrcatisavarargs-stylefunction,whichtakesapointertoaresourcepool,andatleasttwochar*arguments,thelastofwhichmustbeNULL.Itallocatesenoughmemorytofitcopiesofeachofthestrings,asaunit;forinstance:

ap_pstrcat(r->pool,"foo","/","bar",NULL);

returnsapointerto8bytesworthofmemory,initializedto"foo/bar".

Commonly-usedpoolsintheApacheWebserverApoolisreallydefinedbyitslifetimemorethananythingelse.

Therearesomestaticpoolsinhttp_mainwhicharepassedtovariousnon-http_mainfunctionsasargumentsatopportunetimes.Heretheyare:

permanent_pool

neverpassedtoanythingelse,thisistheancestorofallpools

subpoolofpermanent_poolcreatedatthebeginningofaconfig"cycle";existsuntiltheserveristerminatedorrestarts;passedtoallconfig-timeroutines,eitherviacmd->pool,orasthe"pool*p"argumentonthosewhichdon'ttakepoolspassedtothemoduleinit()functions

sorryIlie,thispoolisn'tcalledthiscurrentlyin1.3,Irenameditthisinmypthreadsdevelopment.I'mreferringtotheuseofptransintheparent...contrastthiswiththelaterdefinitionofptransinthechild.subpoolofpermanent_poolcreatedatthebeginningofaconfig"cycle";existsuntiltheendofconfigparsing;passedtoconfig-timeroutinesviacmd->temp_pool.Somewhatofa"bastardchild"becauseitisn'tavailableeverywhere.Usedfortemporaryscratchspacewhichmaybeneededbysomeconfigroutinesbutwhichisdeletedattheendofconfig.

pchild

subpoolofpermanent_poolcreatedwhenachildisspawned(orathreadiscreated);livesuntilthatchild(thread)isdestroyedpassedtothemodulechild_initfunctionsdestructionhappensrightafterthechild_exitfunctionsarecalled...(whichmayexplainwhyIthinkchild_exitis

redundantandunneeded)

ptrans

shouldbeasubpoolofpchild,butcurrentlyisasubpoolofpermanent_pool,seeaboveclearedbythechildbeforegoingintotheaccept()looptoreceiveaconnectionusedasconnection->pool

r->pool

forthemainrequestthisisasubpoolofconnection->pool;forsubrequestsitisasubpooloftheparentrequest'spool.existsuntiltheendoftherequest(i.e.,ap_destroy_sub_req,orinchild_mainafterprocess_requesthasfinished)notethatritselfisallocatedfromr->pool;i.e.,r->poolisfirstcreatedandthenristhefirstthingpalloc()dfromit

Foralmosteverythingfolksdo,r->poolisthepooltouse.Butyoucanseehowotherlifetimes,suchaspchild,areusefultosomemodules...suchasmodulesthatneedtoopenadatabaseconnectiononceperchild,andwishtocleanitupwhenthechilddies.

Youcanalsoseehowsomebugshavemanifestedthemself,suchassettingconnection->usertoavaluefromr->pool--inthiscaseconnectionexistsforthelifetimeofptrans,whichislongerthanr->pool(especiallyifr->poolisasubrequest!).Sothecorrectthingtodoistoallocatefromconnection->pool.

Andtherewasanotherinterestingbuginmod_include/mod_cgi.You'llseeinthosethattheydothistesttodecideiftheyshoulduser->poolorr->main->pool.Inthiscasetheresourcethattheyareregisteringforcleanupisachildprocess.If

itwereregisteredinr->pool,thenthecodewouldwait()forthechildwhenthesubrequestfinishes.Withmod_includethiscouldbeanyold#include,andthedelaycanbeupto3seconds...andhappenedquitefrequently.Insteadthesubprocessisregisteredinr->main->poolwhichcausesittobecleanedupwhentheentirerequestisdone--i.e.,aftertheoutputhasbeensenttotheclientandlogginghashappened.

Trackingopenfiles,etc.Asindicatedabove,resourcepoolsarealsousedtotrackothersortsofresourcesbesidesmemory.Themostcommonareopenfiles.Theroutinewhichistypicallyusedforthisisap_pfopen,whichtakesaresourcepoolandtwostringsasarguments;thestringsarethesameasthetypicalargumentstofopen,e.g.,

FILE*f=ap_pfopen(r->pool,r->filename,"r");

if(f==NULL){...}else{...}

Thereisalsoaap_popenfroutine,whichparallelsthelower-levelopensystemcall.Bothoftheseroutinesarrangeforthefiletobeclosedwhentheresourcepoolinquestioniscleared.

Unlikethecaseformemory,therearefunctionstoclosefilesallocatedwithap_pfopen,andap_popenf,namelyap_pfcloseandap_pclosef.(Thisisbecause,onmanysystems,thenumberoffileswhichasingleprocesscanhaveopenisquitelimited).Itisimportanttousethesefunctionstoclosefilesallocatedwithap_pfopenandap_popenf,sincetodootherwisecouldcausefatalerrorsonsystemssuchasLinux,whichreactbadlyifthesameFILE*isclosedmorethanonce.

(Usingtheclosefunctionsisnotmandatory,sincethefilewill

eventuallybeclosedregardless,butyoushouldconsideritincaseswhereyourmoduleisopening,orcouldopen,alotoffiles).

Othersortsofresources--cleanupfunctionsMoretextgoeshere.Describethecleanupprimitivesintermsofwhichthefilestuffisimplemented;also,spawn_process.

Poolcleanupsliveuntilclear_pool()iscalled:clear_pool(a)recursivelycallsdestroy_pool()onallsubpoolsofa;thencallsallthecleanupsfora;thenreleasesallthememoryfora.destroy_pool(a)callsclear_pool(a)andthenreleasesthepoolstructureitself.i.e.,clear_pool(a)doesn'tdeletea,itjustfreesupalltheresourcesandyoucanstartusingitagainimmediately.

Finecontrol--creatinganddealingwithsub-pools,withanoteonsub-requestsOnrareoccasions,too-freeuseofap_palloc()andtheassociatedprimitivesmayresultinundesirablyprofligateresourceallocation.Youcandealwithsuchacasebycreatingasub-pool,allocatingwithinthesub-poolratherthanthemainpool,andclearingordestroyingthesub-pool,whichreleasestheresourceswhichwereassociatedwithit.(Thisreallyisararesituation;theonlycaseinwhichitcomesupinthestandardmodulesetisincaseoflistingdirectories,andthenonlywithverylargedirectories.Unnecessaryuseoftheprimitivesdiscussedherecanhairupyourcodequiteabit,withverylittlegain).

Theprimitiveforcreatingasub-poolisap_make_sub_pool,whichtakesanotherpool(theparentpool)asanargument.Whenthemainpooliscleared,thesub-poolwillbedestroyed.Thesub-poolmayalsobeclearedordestroyedatanytime,bycallingthefunctionsap_clear_poolandap_destroy_pool,respectively.

(Thedifferenceisthatap_clear_poolfreesresourcesassociatedwiththepool,whileap_destroy_poolalsodeallocatesthepoolitself.Intheformercase,youcanallocatenewresourceswithinthepool,andclearitagain,andsoforth;inthelattercase,itissimplygone).

Onefinalnote--sub-requestshavetheirownresourcepools,whicharesub-poolsoftheresourcepoolforthemainrequest.Thepolitewaytoreclaimtheresourcesassociatedwithasubrequestwhichyouhaveallocated(usingtheap_sub_req_...functions)isap_destroy_sub_req,whichfreestheresourcepool.Beforecallingthisfunction,besuretocopyanythingthatyoucareaboutwhichmightbeallocatedinthesub-request'sresourcepoolintosomeplacealittlelessvolatile(forinstance,thefilenameinitsrequest_recstructure).

(Again,undermostcircumstances,youshouldn'tfeelobligedtocallthisfunction;only2Kofmemoryorsoareallocatedforatypicalsubrequest,anditwillbefreedanywaywhenthemainrequestpooliscleared.Itisonlywhenyouareallocatingmany,manysub-requestsforasinglemainrequestthatyoushouldseriouslyconsidertheap_destroy_...functions).

Configuration,commandsandthelike

OneofthedesigngoalsforthisserverwastomaintainexternalcompatibilitywiththeNCSA1.3server---thatis,toreadthesameconfigurationfiles,toprocessallthedirectivesthereincorrectly,andingeneraltobeadrop-inreplacementforNCSA.Ontheotherhand,anotherdesigngoalwastomoveasmuchoftheserver'sfunctionalityintomoduleswhichhaveaslittleaspossibletodowiththemonolithicservercore.Theonlywaytoreconcilethesegoalsistomovethehandlingofmostcommandsfromthecentralserverintothemodules.

However,justgivingthemodulescommandtablesisnotenoughtodivorcethemcompletelyfromtheservercore.Theserverhastorememberthecommandsinordertoactonthemlater.Thatinvolvesmaintainingdatawhichisprivatetothemodules,andwhichcanbeeitherper-server,orper-directory.Mostthingsareper-directory,includinginparticularaccesscontrolandauthorizationinformation,butalsoinformationonhowtodeterminefiletypesfromsuffixes,whichcanbemodifiedbyAddTypeandDefaultTypedirectives,andsoforth.Ingeneral,thegoverningphilosophyisthatanythingwhichcanbemadeconfigurablebydirectoryshouldbe;per-serverinformationisgenerallyusedinthestandardsetofmodulesforinformationlikeAliasesandRedirectswhichcomeintoplaybeforetherequestistiedtoaparticularplaceintheunderlyingfilesystem.

AnotherrequirementforemulatingtheNCSAserverisbeingabletohandletheper-directoryconfigurationfiles,generallycalled.htaccessfiles,thoughevenintheNCSAservertheycancontaindirectiveswhichhavenothingatalltodowithaccesscontrol.Accordingly,afterURI->filenametranslation,butbeforeperforminganyotherphase,theserverwalksdownthedirectoryhierarchyoftheunderlyingfilesystem,followingthetranslatedpathname,toreadany.htaccessfileswhichmightbepresent.

Theinformationwhichisreadinthenhastobemergedwiththeapplicableinformationfromtheserver'sownconfigfiles(eitherfromthe<Directory>sectionsinaccess.conf,orfromdefaultsinsrm.conf,whichactuallybehavesformostpurposesalmostexactlylike<Directory/>).

Finally,afterhavingservedarequestwhichinvolvedreading.htaccessfiles,weneedtodiscardthestorageallocatedforhandlingthem.Thatissolvedthesamewayitissolvedwhereverelsesimilarproblemscomeup,bytyingthosestructurestotheper-transactionresourcepool.

Per-directoryconfigurationstructuresLet'slookouthowallofthisplaysoutinmod_mime.c,whichdefinesthefiletypinghandlerwhichemulatestheNCSAserver'sbehaviorofdeterminingfiletypesfromsuffixes.Whatwe'llbelookingat,here,isthecodewhichimplementstheAddTypeandAddEncodingcommands.Thesecommandscanappearin.htaccessfiles,sotheymustbehandledinthemodule'sprivateper-directorydata,whichinfact,consistsoftwoseparatetablesforMIMEtypesandencodinginformation,andisdeclaredasfollows:

typedefstruct{

table*forced_types;/*AdditionalAddTypedstuff*/

table*encoding_types;/*AddedwithAddEncoding...*/

}mime_dir_config;

Whentheserverisreadingaconfigurationfile,or<Directory>section,whichincludesoneoftheMIMEmodule'scommands,itneedstocreateamime_dir_configstructure,sothosecommandshavesomethingtoacton.Itdoesthisbyinvokingthefunctionitfindsinthemodule's`createper-dirconfigslot',withtwoarguments:thenameofthedirectorytowhichthisconfiguration

informationapplies(orNULLforsrm.conf),andapointertoaresourcepoolinwhichtheallocationshouldhappen.

(Ifwearereadinga.htaccessfile,thatresourcepoolistheper-requestresourcepoolfortherequest;otherwiseitisaresourcepoolwhichisusedforconfigurationdata,andclearedonrestarts.Eitherway,itisimportantforthestructurebeingcreatedtovanishwhenthepooliscleared,byregisteringacleanuponthepoolifnecessary).

FortheMIMEmodule,theper-dirconfigcreationfunctionjustap_pallocsthestructureabove,andacreatesacoupleoftablestofillit.Thatlookslikethis:

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

returnnew;

Now,supposewe'vejustreadina.htaccessfile.Wealreadyhavetheper-directoryconfigurationstructureforthenextdirectoryupinthehierarchy.Ifthe.htaccessfilewejustreadindidn'thaveanyAddTypeorAddEncodingcommands,itsper-directoryconfigstructurefortheMIMEmoduleisstillvalid,andwecanjustuseit.Otherwise,weneedtomergethetwostructuressomehow.

Todothat,theserverinvokesthemodule'sper-directoryconfigmergefunction,ifoneispresent.Thatfunctiontakesthreearguments:thetwostructuresbeingmerged,andaresourcepoolinwhichtoallocatetheresult.FortheMIMEmodule,allthatneeds

tobedoneisoverlaythetablesfromthenewper-directoryconfigstructurewiththosefromtheparent:

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

returnnew;

Asanote--ifthereisnoper-directorymergefunctionpresent,theserverwilljustusethesubdirectory'sconfigurationinfo,andignoretheparent's.Forsomemodules,thatworksjustfine(e.g.,fortheincludesmodule,whoseper-directoryconfigurationinformationconsistssolelyofthestateoftheXBITHACK),andforthosemodules,youcanjustnotdeclareone,andleavethecorrespondingstructureslotinthemoduleitselfNULL.

CommandhandlingNowthatwehavethesestructures,weneedtobeabletofigureouthowtofillthem.ThatinvolvesprocessingtheactualAddTypeandAddEncodingcommands.Tofindcommands,theserverlooksinthemodule'scommandtable.Thattablecontainsinformationonhowmanyargumentsthecommandstake,andinwhatformats,whereitispermitted,andsoforth.Thatinformationissufficienttoallowtheservertoinvokemostcommand-handlingfunctionswithpre-parsedarguments.Withoutfurtherado,let's

lookattheAddTypecommandhandler,whichlookslikethis(theAddEncodingcommandlooksbasicallythesame,andwon'tbeshownhere):

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

returnNULL;

Thiscommandhandlerisunusuallysimple.Asyoucansee,ittakesfourarguments,twoofwhicharepre-parsedarguments,thethirdbeingtheper-directoryconfigurationstructureforthemoduleinquestion,andthefourthbeingapointertoacmd_parmsstructure.Thatstructurecontainsabunchofargumentswhicharefrequentlyofusetosome,butnotall,commands,includingaresourcepool(fromwhichmemorycanbeallocated,andtowhichcleanupsshouldbetied),andthe(virtual)serverbeingconfigured,fromwhichthemodule'sper-serverconfigurationdatacanbeobtainedifrequired.

Anotherwayinwhichthisparticularcommandhandlerisunusuallysimpleisthattherearenoerrorconditionswhichitcanencounter.Iftherewere,itcouldreturnanerrormessageinsteadofNULL;thiscausesanerrortobeprintedoutontheserver'sstderr,followedbyaquickexit,ifitisinthemainconfigfiles;fora.htaccessfile,thesyntaxerrorisloggedintheservererrorlog(alongwithanindicationofwhereitcamefrom),andtherequestisbouncedwithaservererrorresponse(HTTPerrorstatus,code500).

TheMIMEmodule'scommandtablehasentriesforthesecommands,whichlooklikethis:

command_recmime_cmds[]={

{"AddType",add_type,NULL,OR_FILEINFO,TAKE2,

"amimetypefollowedbyafileextension"},

{"AddEncoding",add_encoding,NULL,OR_FILEINFO,TAKE2,

"anencoding(e.g.,gzip),followedbyafileextension"

{NULL}

Theentriesinthesetablesare:

ThenameofthecommandThefunctionwhichhandlesita(void*)pointer,whichispassedinthecmd_parmsstructuretothecommandhandler---thisisusefulincasemanysimilarcommandsarehandledbythesamefunction.Abitmaskindicatingwherethecommandmayappear.TherearemaskbitscorrespondingtoeachAllowOverrideoption,andanadditionalmaskbit,RSRC_CONF,indicatingthatthecommandmayappearintheserver'sownconfigfiles,butnotinany.htaccessfile.Aflagindicatinghowmanyargumentsthecommandhandlerwantspre-parsed,andhowtheyshouldbepassedin.TAKE2indicatestwopre-parsedarguments.OtheroptionsareTAKE1,whichindicatesonepre-parsedargument,FLAG,whichindicatesthattheargumentshouldbeOnorOff,andispassedinasabooleanflag,RAW_ARGS,whichcausestheservertogivethecommandtheraw,unparsedarguments(everythingbutthecommandnameitself).ThereisalsoITERATE,whichmeansthatthehandlerlooksthesameasTAKE1,butthatifmultipleargumentsarepresent,itshouldbecalledmultipletimes,andfinallyITERATE2,whichindicatesthatthecommandhandlerlookslikeaTAKE2,butifmoreargumentsarepresent,thenitshouldbecalledmultipletimes,holdingthefirstargumentconstant.

Finally,wehaveastringwhichdescribestheargumentsthatshouldbepresent.Iftheargumentsintheactualconfigfilearenotasrequired,thisstringwillbeusedtohelpgiveamorespecificerrormessage.(YoucansafelyleavethisNULL).

Finally,havingsetthisallup,wehavetouseit.Thisisultimatelydoneinthemodule'shandlers,specificallyforitsfile-typinghandler,whichlooksmoreorlesslikethis;notethattheper-directoryconfigurationstructureisextractedfromtherequest_rec'sper-directoryconfigurationvectorbyusingtheap_get_module_configfunction.

intfind_ct(request_rec*r)

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;

returnOK;

if((i=ap_rind(fn,'.'))<0)returnDECLINED;

if((type=ap_table_get(conf->encoding_types,&fn[i])))

r->content_encoding=type;

/*gobacktopreviousextensiontotrytouseitasa

type*/

fn[i-1]='\0';

if((i=ap_rind(fn,'.'))<0)returnOK;

if((type=ap_table_get(conf->forced_types,&fn[i])))

r->content_type=type;

returnOK;

Sidenotes--per-serverconfiguration,virtualservers,etc.Thebasicideasbehindper-servermoduleconfigurationarebasicallythesameasthoseforper-directoryconfiguration;thereisacreationfunctionandamergefunction,thelatterbeinginvokedwhereavirtualserverhaspartiallyoverriddenthebaseserverconfiguration,andacombinedstructuremustbecomputed.(Aswithper-directoryconfiguration,thedefaultifnomergefunctionisspecified,andamoduleisconfiguredinsomevirtualserver,isthatthebaseconfigurationissimplyignored).

Theonlysubstantialdifferenceisthatwhenacommandneedstoconfiguretheper-serverprivatemoduledata,itneedstogotothecmd_parmsdatatogetatit.Here'sanexample,fromthealiasmodule,whichalsoindicateshowasyntaxerrorcanbereturned(notethattheper-directoryconfigurationargumenttothecommandhandlerisdeclaredasadummy,sincethemoduledoesn'tactuallyhaveper-directoryconfigdata):

char*add_redirect(cmd_parms*cmd,void*dummy,char*f,char

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"Redirecttonon-URL";

new->fake=f;new->real=url;

returnNULL;

DebuggingMemoryAllocationinAPR

Theallocationmechanism'swithinAPRhaveanumberofdebuggingmodesthatcanbeusedtoassistinfindingmemoryproblems.Thisdocumentdescribesthemodesavailableandgivesinstructionsonactivatingthem.

Availabledebuggingoptions

AllocationDebugging-ALLOC_DEBUG

Debuggingsupport:Definethistoenablecodewhichhelpsdetectre-useoffree()dmemoryandothersuchnonsense.

Thetheoryissimple.TheFILL_BYTE(0xa5)iswrittenoverallmalloc'dmemoryaswereceiveit,andiswrittenovereverythingthatwefreeupduringaclear_pool.WecheckthatblocksonthefreelistalwayshavetheFILL_BYTEinthem,andwecheckduringpalloc()thatthebytesstillhaveFILL_BYTEinthem.IfyoueverseegarbageURLsorwhatnotcontaininglotsof0xa5sthenyouknowsomethinguseddatathat'sbeenfreedoruninitialized.

MallocSupport-ALLOC_USE_MALLOC

Ifdefinedallallocationswillbedonewithmalloc()andfree()dappropriatelyattheend.

ThisisintendedtobeusedwithsomethinglikeElectricFenceorPurifytohelpdetectmemoryproblems.Notethatifyou'reusingefencethenyoushouldalsoaddinALLOC_DEBUG.Butdon'taddinALLOC_DEBUGifyou'reusingPurifybecauseALLOC_DEBUGwouldhidealltheuninitializedreaderrorsthatPurifycandiagnose.

PoolDebugging-POOL_DEBUG

Thisisintendedtodetectcaseswherethewrongpoolisusedwhenassigningdatatoanobjectinanotherpool.

Inparticular,itcausesthetable_{set,add,merge}nroutinestocheckthattheirargumentsaresafefortheapr_table_tthey'rebeingplacedin.Itcurrentlyonlyworkswiththeunixmultiprocessmodel,butcouldbeextendedtoothers.

TableDebugging-MAKE_TABLE_PROFILE

Providediagnosticinformationaboutmake_table()callswhicharepossiblytoosmall.

Thisrequiresarecentgccwhichsupports__builtin_return_address().Theerror_logoutputwillbeamessagesuchas:

table_push:apr_table_tcreatedby0x804d874hitlimitof10

Usel*0x804d874tofindthesourcethatcorrespondsto.Itindicatesthataapr_table_tallocatedbyacallatthataddresshaspossiblytoosmallaninitialapr_table_tsizeguess.

AllocationStatistics-ALLOC_STATS

Providesomestatisticsonthecostofallocations.

Thisrequiresabitofanunderstandingofhowalloc.cworks.

AllowableCombinations

Notalltheoptionsoutlinedabovecanbeactivatedatthesametime.thefollowingtablegivesmoreinformation.

ALLOCDEBUG

ALLOCUSEMALLOC

POOLDEBUG

MAKETABLEPROFILE

ALLOCSTATS

ALLOCDEBUG

- No Yes Yes Yes

ALLOCUSEMALLOC

No - No No No

POOLDEBUG

Yes No - Yes Yes

MAKETABLEPROFILE

Yes No Yes - Yes

ALLOCSTATS

Yes No Yes Yes -

Additionallythedebuggingoptionsarenotsuitableformulti-threadedversionsoftheserver.Whentryingtodebugwiththeseoptionstheservershouldbestartedinsingleprocessmode.

ActivatingDebuggingOptions

Thevariousoptionsfordebuggingmemoryarenowenabledintheapr_general.hheaderfileinAPR.Thevariousoptionsareenabledbyuncommentingthedefinefortheoptionyouwishtouse.Thesectionofthecodecurrentlylookslikethis(containedinsrclib/apr/include/apr_pools.h)

#defineALLOC_DEBUG

#definePOOL_DEBUG

#defineALLOC_USE_MALLOC

#defineMAKE_TABLE_PROFILE

#defineALLOC_STATS

typedefstructap_pool_t{

unionblock_hdr*first;

unionblock_hdr*last;

structcleanup*cleanups;

structprocess_chain*subprocesses;

structap_pool_t*sub_pools;

structap_pool_t*sub_next;

structap_pool_t*sub_prev;

structap_pool_t*parent;

char*free_first_avail;

#ifdefALLOC_USE_MALLOC

void*allocation_list;

#endif

#ifdefPOOL_DEBUG

structap_pool_t*joined;

#endif

int(*apr_abort)(intretcode);

structdatastruct*prog_data;

}ap_pool_t;

Toenableallocationdebuggingsimplymovethe#defineALLOC_DEBUGabovethestartofthecommentsblockandrebuildtheserver.

Inordertousethevariousoptionstheservermustberebuiltaftereditingtheheaderfile.

DocumentingApache2.0

Apache2.0usesDoxygentodocumenttheAPIsandglobalvariablesinthecode.ThiswillexplainthebasicsofhowtodocumentusingDoxygen.

BriefDescription

Tostartadocumentationblock,use/**Toendadocumentationblock,use*/

Inthemiddleoftheblock,therearemultipletagswecanuse:

Descriptionofthisfunctionspurpose

@paramparameter_namedescription

@returndescription

@deffuncsignatureofthefunction

Thedeffuncisnotalwaysnecessary.DoxyGendoesnothaveafullparserinit,soanyprototypethatuseamacrointhereturntypedeclarationistoocomplexforscandoc.Thosefunctionsrequireadeffunc.Anexample(using>ratherthan>):

*returnthefinalelementofthepathname

*@parampathnameThepathtogetthefinalelementof

*@returnthefinalelementofthepath

*@tipExamples:

*<pre>

*"/foo/bar/gum"->"gum"

*"/foo/bar/gum/"->""

*"gum"->"gum"

*"wi\\n32\\stuff"->"stuff"

*</pre>

*@deffuncconstchar*ap_filename_of_pathname(constchar

*pathname)

Atthetopoftheheaderfile,alwaysinclude:

*@packageNameoflibraryheader

DoxygenusesanewHTMLfileforeachpackage.TheHTMLfilesarenamed{Name_of_library_header}.html,sotrytobeconcisewithyournames.

ForafurtherdiscussionofthepossibilitiespleaserefertotheDoxygensite.

Apache2.0HookFunctions

Warning

Thisdocumentisstillindevelopmentandmaybepartiallyoutofdate.

Ingeneral,ahookfunctionisonethatApachewillcallatsomepointduringtheprocessingofarequest.Modulescanprovidefunctionsthatarecalled,andspecifywhentheygetcalledincomparisontoothermodules.

Creatingahookfunction

Inordertocreateanewhook,fourthingsneedtobedone:

DeclarethehookfunctionUsetheAP_DECLARE_HOOKmacro,whichneedstobegiventhereturntypeofthehookfunction,thenameofthehook,andthearguments.Forexample,ifthehookreturnsanintandtakesarequest_rec*andanintandiscalleddo_something,thendeclareitlikethis:

AP_DECLARE_HOOK(int,do_something,(request_rec*r,intn))

Thisshouldgoinaheaderwhichmoduleswillincludeiftheywanttousethehook.

CreatethehookstructureEachsourcefilethatexportsahookhasaprivatestructurewhichisusedtorecordthemodulefunctionsthatusethehook.Thisisdeclaredasfollows:

APR_HOOK_STRUCT(

APR_HOOK_LINK(do_something)

ImplementthehookcallerThesourcefilethatexportsthehookhastoimplementafunctionthatwillcallthehook.Therearecurrentlythreepossiblewaystodothis.Inallcases,thecallingfunctioniscalledap_run_hookname().

VoidhooksIfthereturnvalueofahookisvoid,thenallthehooksarecalled,

andthecallerisimplementedlikethis:

AP_IMPLEMENT_HOOK_VOID(do_something,(request_rec*r,intn),

(r,n))

Thesecondandthirdargumentsarethedummyargumentdeclarationandthedummyargumentsastheywillbeusedwhencallingthehook.Inotherwords,thismacroexpandstosomethinglikethis:

voidap_run_do_something(request_rec*r,intn)

do_something(r,n);

HooksthatreturnavalueIfthehookreturnsavalue,thenitcaneitherberununtilthefirsthookthatdoessomethinginteresting,likeso:

AP_IMPLEMENT_HOOK_RUN_FIRST(int,do_something,(request_rec*r,

intn),(r,n),DECLINED)

ThefirsthookthatdoesnotreturnDECLINEDstopstheloopanditsreturnvalueisreturnedfromthehookcaller.NotethatDECLINEDisthetraditionApachehookreturnmeaning"Ididn'tdoanything",butitcanbewhateversuitsyou.

Alternatively,allhookscanberununtilanerroroccurs.Thisboilsdowntopermittingtworeturnvalues,oneofwhichmeans"Ididsomething,anditwasOK"andtheothermeaning"Ididnothing".Thefirstfunctionthatreturnsavalueotherthanoneofthosetwostopstheloop,anditsreturnisthereturnvalue.Declaretheselikeso:

AP_IMPLEMENT_HOOK_RUN_ALL(int,do_something,(request_rec*r,

intn),(r,n),OK,DECLINED)

Again,OKandDECLINEDarethetraditionalvalues.Youcanusewhatyouwant.

CallthehookcallersAtappropriatemomentsinthecode,callthehookcaller,likeso:

intn,ret;

request_rec*r;

ret=ap_run_do_something(r,n);

Hookingthehook

Amodulethatwantsahooktobecalledneedstodotwothings.

ImplementthehookfunctionIncludetheappropriateheader,anddefineastaticfunctionofthecorrecttype:

staticintmy_something_doer(request_rec*r,intn)

returnOK;

AddahookregisteringfunctionDuringinitialisation,Apachewillcalleachmoduleshookregisteringfunction,whichisincludedinthemodulestructure:

staticvoidmy_register_hooks()

ap_hook_do_something(my_something_doer,NULL,NULL,

HOOK_MIDDLE);

modeMODULE_VAR_EXPORTmy_module=

my_register_hooks/*registerhooks*/

ControllinghookcallingorderIntheexampleabove,wedidn'tusethethreeargumentsinthehookregistrationfunctionthatcontrolcallingorder.Therearetwomechanismsfordoingthis.Thefirst,rathercrude,method,allowsustospecifyroughlywherethehookisrunrelativetoothermodules.Thefinalargumentcontrolthis.Therearethreepossiblevalues:HOOK_FIRST,HOOK_MIDDLEandHOOK_LAST.

Allmodulesusinganyparticularvaluemayberuninanyorderrelativetoeachother,but,ofcourse,allmodulesusingHOOK_FIRSTwillberunbeforeHOOK_MIDDLEwhicharebeforeHOOK_LAST.Modulesthatdon'tcarewhentheyarerunshoulduseHOOK_MIDDLE.(IspacedtheseoutsopeoplecoulddostufflikeHOOK_FIRST-2togetinslightlyearlier,butisthiswise?-Ben)

Notethattherearetwomorevalues,HOOK_REALLY_FIRSTandHOOK_REALLY_LAST.Theseshouldonlybeusedbythehookexporter.

Theothermethodallowsfinercontrol.Whenamoduleknowsthatitmustberunbefore(orafter)someothermodules,itcanspecifythembyname.Thesecond(third)argumentisaNULL-terminatedarrayofstringsconsistingofthenamesofmodulesthatmustberunbefore(after)thecurrentmodule.Forexample,supposewewant"mod_xyz.c"and"mod_abc.c"torunbeforewedo,thenwe'dhookasfollows:

staticvoidregister_hooks()

staticconstchar*constaszPre[]={"mod_xyz.c",

"mod_abc.c",NULL};

ap_hook_do_something(my_something_doer,aszPre,NULL,

HOOK_MIDDLE);

Notethatthesortusedtoachievethisisstable,soorderingsetbyHOOK_ORDERispreserved,asfarasispossible.

BenLaurie,15thAugust1999

||FAQ||

ApacheHTTP2.0Apache>HTTP>>2.0 >DeveloperDocumentation

Apache1.3Apache2.0

mod_mmap_staticApache2.0

apr_status_t apr_status_tARP_SUCCESS

apr_pool_t*p

apr_pool_t*plog

apr_pool_t*ptemp

server_rec*s

poolbecomesapr_pool_ttablebecomesapr_table_t

mod_mmap_static:

staticvoidregister_hooks(void)

staticconstchar*constaszPre[]={"http_core.c",NULL};

ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE);

ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST);

post_config(?

ap_hook_phase_name(function_name,predecessors,successors,

position);

HOOK_FIRST

HOOK_MIDDLE

HOOK_LAST

mod_mmap_static post_configmmap_static_xlatcore aszPre

moduleMODULE_VAR_EXPORTmodule_name_module=

STANDARD_MODULE_STUFF,

/*initializer*/

/*dirconfigcreater*/

/*dirmerger---defaultistooverride*/

/*serverconfig*/

/*mergeserverconfig*/

/*commandhandlers*/

/*handlers*/

/*filenametranslation*/

/*check_user_id*/

/*checkauth*/

/*checkaccess*/

/*type_checker*/

/*fixups*/

/*logger*/

/*headerparser*/

/*child_init*/

/*child_exit*/

/*postread-request*/

moduleMODULE_VAR_EXPORTmodule_name_module=

STANDARD20_MODULE_STUFF,

/*createper-directoryconfigstructures*/

/*mergeper-directoryconfigstructures*/

/*createper-serverconfigstructures*/

/*mergeper-serverconfigstructures*/

/*commandhandlers*/

/*handlers*/

/*registerhooks*/

/*apr_table_t*/

ap_hook_post_config

( _init)

ap_hook_http_method

(HTTP())

ap_hook_open_logs

ap_hook_auth_checker

ap_hook_access_checker

ap_hook_check_user_id

ap_hook_default_port

ap_hook_pre_connection

(accept)

ap_hook_process_connection

||FAQ||

ap_hook_child_init

ap_hook_create_request

ap_hook_fixups

ap_hook_handler

ap_hook_header_parser

(post_read_request)

ap_hook_insert_filter

ap_hook_log_transaction

ap_hook_optional_fn_retrieve

ap_hook_post_read_request

ap_hook_quick_handler

ap_hook_translate_name

ap_hook_type_checker

RequestProcessinginApache2.0

Warning

Warning-thisisafirst(fast)draftthatneedsfurtherrevision!

SeveralchangesinApache2.0affecttheinternalrequestprocessingmechanics.Moduleauthorsneedtobeawareofthesechangessotheymaytakeadvantageoftheoptimizationsandsecurityenhancements.

Thefirstmajorchangeistothesubrequestandredirectmechanisms.TherewereanumberofdifferentcodepathsinApache1.3toattempttooptimizesubrequestorredirectbehavior.Aspatcheswereintroducedto2.0,theseoptimizations(andtheserverbehavior)werequicklybrokenduetothisduplicationofcode.Allduplicatecodehasbeenfoldedbackintoap_process_request_internal()topreventthecodefromfallingoutofsyncagain.

Thismeansthatmuchoftheexistingcodewas'unoptimized'.ItistheApacheHTTPProject'sfirstgoaltocreatearobustandcorrectimplementationoftheHTTPserverRFC.Additionalgoalsincludesecurity,scalabilityandoptimization.Newmethodsweresoughttooptimizetheserver(beyondtheperformanceofApache1.3)withoutintroducingfragileorinsecurecode.

TheRequestProcessingCycle

Allrequestspassthroughap_process_request_internal()inrequest.c,includingsubrequestsandredirects.Ifamoduledoesn'tpassgeneratedrequeststhroughthiscode,theauthoriscautionedthatthemodulemaybebrokenbyfuturechangestorequestprocessing.

Tostreamlinerequests,themoduleauthorcantakeadvantageofthehooksofferedtodropoutoftherequestcycleearly,ortobypasscoreApachehookswhichareirrelevant(andcostlyintermsofCPU.)

TheRequestParsingPhase

UnescapestheURLTherequest'sparsed_uripathisunescaped,onceandonlyonce,atthebeginningofinternalrequestprocessing.

Thisstepisbypassediftheproxyreqflagisset,ortheparsed_uri.pathelementisunset.Themodulehasnofurthercontrolofthisone-timeunescapeoperation,eitherfailingtounescapeormultiplyunescapingtheURLleadstosecurityreprecussions.

StripsParentandThisElementsfromtheURIAll/../and/./elementsareremovedbyap_getparents().Thishelpstoensurethepathis(nearly)absolutebeforetherequestprocessingcontinues.

Thisstepcannotbebypassed.

InitialURILocationWalkEveryrequestissubjecttoanap_location_walk()call.Thisensuresthat<Location>sectionsareconsistentlyenforcedforallrequests.Iftherequestisaninternalredirectorasub-request,itmayborrowsomeoralloftheprocessingfromthepreviousorparentrequest'sap_location_walk,sothisstepisgenerallyveryefficientafterprocessingthemainrequest.

translate_nameModulescandeterminethefilename,oralterthegivenURIinthisstep.Forexample,mod_vhost_aliaswilltranslatetheURI'spathintotheconfiguredvirtualhost,mod_aliaswilltranslatethepathtoanaliaspath,andiftherequestfallsbackonthecore,the

DocumentRootisprependedtotherequestresource.

IfallmodulesDECLINEthisphase,anerror500isreturnedtothebrowser,anda"couldn'ttranslatename"errorisloggedautomatically.

Hook:map_to_storageAfterthefileorcorrectURIwasdetermined,theappropriateper-dirconfigurationsaremergedtogether.Forexample,mod_proxycomparesandmergestheappropriate<Proxy>sections.IftheURIisnothingmorethanalocal(non-proxy)TRACErequest,thecorehandlestherequestandreturnsDONE.IfnomoduleanswersthishookwithOKorDONE,thecorewillruntherequestfilenameagainstthe<Directory>and<Files>sections.Iftherequest'filename'isn'tanabsolute,legalfilename,anoteissetforlatertermination.

URILocationWalkEveryrequestishardenedbyasecondap_location_walk()call.Thisreassuresthatatranslatedrequestisstillsubjectedtotheconfigured<Location>sections.Therequestagainborrowssomeoralloftheprocessingfromitspreviouslocation_walkabove,sothisstepisalmostalwaysveryefficientunlessthetranslatedURImappedtoasubstantiallydifferentpathorVirtualHost.

Hook:header_parserThemainrequestthenparsestheclient'sheaders.Thispreparestheremainingrequestprocessingstepstobetterservetheclient'srequest.

TheSecurityPhase

NeedsDocumentation.Codeis:

switch(ap_satisfies(r)){

caseSATISFY_ALL:

caseSATISFY_NOSPEC:

if((access_status=ap_run_access_checker(r))!=0){

returndecl_die(access_status,"checkaccess",r);

if(ap_some_auth_required(r)){

if(((access_status=ap_run_check_user_id(r))!=0)

||!ap_auth_type(r)){

returndecl_die(access_status,ap_auth_type(r)

?"checkuser.Nouserfile?"

:"performauthentication.AuthTypenotset!",

if(((access_status=ap_run_auth_checker(r))!=0)

?"checkaccess.Nogroupsfile?"

break;

caseSATISFY_ANY:

if(((access_status=ap_run_access_checker(r))!=0)){

if(!ap_some_auth_required(r)){

returndecl_die(access_status,"checkaccess",r);

if(((access_status=ap_run_check_user_id(r))!=0)

?"checkuser.Nouserfile?"

if(((access_status=ap_run_auth_checker(r))!=0)

?"checkaccess.Nogroupsfile?"

break;

ThePreparationPhase

Hook:type_checkerThemoduleshaveanopportunitytotesttheURIorfilenameagainstthetargetresource,andsetmimeinformationfortherequest.Bothmod_mimeandmod_mime_magicusethisphasetocomparethefilenameorcontentsagainsttheadministrator'sconfigurationandsetthecontenttype,language,charactersetandrequesthandler.Somemodulesmaysetuptheirfiltersorotherrequesthandlingparametersatthistime.

IfallmodulesDECLINEthisphase,anerror500isreturnedtothebrowser,anda"couldn'tfindtypes"errorisloggedautomatically.

Hook:fixupsManymodulesare'trounced'bysomephaseabove.Thefixupsphaseisusedbymodulesto'reassert'theirownershiporforcetherequest'sfieldstotheirappropriatevalues.Itisn'talwaysthecleanestmechanism,butoccasionallyit'stheonlyoption.

TheHandlerPhase

Thisphaseisnotpartoftheprocessinginap_process_request_internal().Manymodulesprepareoneormoresubrequestspriortocreatinganycontentatall.Afterthecore,oramodulecallsap_process_request_internal()itthencallsap_invoke_handler()togeneratetherequest.

Hook:insert_filterModulesthattransformthecontentinsomewaycaninserttheirvaluesandoverrideexistingfilters,suchthatiftheuserconfiguredamoreadvancedfilterout-of-order,thenthemodulecanmoveitsorderasneedbe.Thereisnoresultcode,soactionsinthishookbetterbetrustedtoalwayssucceed.

Hook:handlerThemodulefinallyhasachancetoservetherequestinitshandlerhook.Notethatnoteverypreparedrequestissenttothehandlerhook.Manymodules,suchasmod_autoindex,willcreatesubrequestsforagivenURI,andthenneverservethesubrequest,butsimplylistsitfortheuser.Remembernottoputrequiredteardownfromthehooksaboveintothismodule,butregisterpoolcleanupsagainsttherequestpooltofreeresourcesasrequired.

HowfiltersworkinApache2.0

Warning

Thisisacut'npastejobfromanemail(<022501c1c529$f63a9550$7f00000a@KOJ>)andonlyreformattedforbetterreadability.It'snotuptodatebutmaybeagoodstartforfurtherresearch.

FilterTypes

Therearethreebasicfiltertypes(eachoftheseisactuallybrokendownintotwocategories,butthatcomeslater).

CONNECTION

Filtersofthistypearevalidforthelifetimeofthisconnection.(AP_FTYPE_CONNECTION,AP_FTYPE_NETWORK)

PROTOCOL

Filtersofthistypearevalidforthelifetimeofthisrequestfromthepointofviewoftheclient,thismeansthattherequestisvalidfromthetimethattherequestissentuntilthetimethattheresponseisreceived.(AP_FTYPE_PROTOCOL,AP_FTYPE_TRANSCODE)

RESOURCE

Filtersofthistypearevalidforthetimethatthiscontentisusedtosatisfyarequest.Forsimplerequests,thisisidenticaltoPROTOCOL,butinternalredirectsandsub-requestscanchangethecontentwithoutendingtherequest.(AP_FTYPE_RESOURCE,AP_FTYPE_CONTENT_SET)

Itisimportanttomakethedistinctionbetweenaprotocolandaresourcefilter.Aresourcefilteristiedtoaspecificresource,itmayalsobetiedtoheaderinformation,butthemainbindingistoaresource.Ifyouarewritingafilterandyouwanttoknowifitisresourceorprotocol,thecorrectquestiontoaskis:"Canthisfilterberemovediftherequestisredirectedtoadifferentresource?"Iftheanswerisyes,thenitisaresourcefilter.Ifitisno,thenitismostlikelyaprotocolorconnectionfilter.Iwon'tgointoconnectionfilters,becausetheyseemtobewellunderstood.Withthisdefinition,afewexamplesmighthelp:

ByterangeWehavecodedittobeinsertedforallrequests,anditisremovedifnotused.Becausethisfilterisactiveatthe

beginningofallrequests,itcannotberemovedifitisredirected,sothisisaprotocolfilter.

http_headerThisfilteractuallywritestheheaderstothenetwork.Thisisobviouslyarequiredfilter(exceptintheasiscasewhichisspecialandwillbedealtwithbelow)andsoitisaprotocolfilter.

DeflateTheadministratorconfiguresthisfilterbasedonwhichfilehasbeenrequested.Ifwedoaninternalredirectfromanautoindexpagetoanindex.htmlpage,thedeflatefiltermaybeaddedorremovedbasedonconfig,sothisisaresourcefilter.

Thefurtherbreakdownofeachcategoryintotwomorefiltertypesisstrictlyforordering.Wecouldremoveit,andonlyallowforonefiltertype,buttheorderwouldtendtobewrong,andwewouldneedtohackthingstomakeitwork.Currently,theRESOURCEfiltersonlyhaveonefiltertype,butthatshouldchange.

Howarefiltersinserted?

Thisisactuallyrathersimpleintheory,butthecodeiscomplex.Firstofall,itisimportantthateverybodyrealizethattherearethreefilterlistsforeachrequest,buttheyareallconcatenatedtogether.So,thefirstlistisr->output_filters,thenr->proto_output_filters,andfinallyr->connection->output_filters.ThesecorrespondtotheRESOURCE,PROTOCOL,andCONNECTIONfiltersrespectively.Theproblempreviously,wasthatweusedasinglylinkedlisttocreatethefilterstack,andwestartedfromthe"correct"location.ThismeansthatifIhadaRESOURCEfilteronthestack,andIaddedaCONNECTIONfilter,theCONNECTIONfilterwouldbeignored.Thisshouldmakesense,becausewewouldinserttheconnectionfilteratthetopofthec->output_filterslist,buttheendofr->output_filterspointedtothefilterthatusedtobeatthefrontofc->output_filters.Thisisobviouslywrong.Thenewinsertioncodeusesadoublylinkedlist.Thishastheadvantagethatweneverloseafilterthathasbeeninserted.Unfortunately,itcomeswithaseparatesetofheadaches.

Theproblemisthatwehavetwodifferentcaseswereweusesubrequests.Thefirstistoinsertmoredataintoaresponse.Thesecondistoreplacetheexistingresponsewithaninternalredirect.Thesearetwodifferentcasesandneedtobetreatedassuch.

Inthefirstcase,wearecreatingthesubrequestfromwithinahandlerorfilter.Thismeansthatthenextfiltershouldbepassedtomake_sub_requestfunction,andthelastresourcefilterinthesub-requestwillpointtothenextfilterinthemainrequest.Thismakessense,becausethesub-request'sdataneedstoflowthroughthesamesetoffiltersasthemainrequest.Agraphicalrepresentationmighthelp:

Default_handler-->includes_filter-->byterange-->...

Iftheincludesfiltercreatesasubrequest,thenwedon'twantthedatafromthatsub-requesttogothroughtheincludesfilter,becauseitmightnotbeSSIdata.So,thesubrequestaddsthefollowing:

Default_handler-->includes_filter-/->byterange-->...

Default_handler-->sub_request_core

WhathappensifthesubrequestisSSIdata?Well,that'seasy,theincludes_filterisaresourcefilter,soitwillbeaddedtothesubrequestinbetweentheDefault_handlerandthesub_request_corefilter.

Thesecondcaseforsub-requestsiswhenonesub-requestisgoingtobecometherealrequest.Thishappenswheneverasub-requestiscreatedoutsideofahandlerorfilter,andNULLispassedasthenextfiltertothemake_sub_requestfunction.

Inthiscase,theresourcefiltersnolongermakesenseforthenewrequest,becausetheresourcehaschanged.So,insteadofstartingfromscratch,wesimplypointthefrontoftheresourcefiltersforthesub-requesttothefrontoftheprotocolfiltersfortheoldrequest.Thismeansthatwewon'tloseanyoftheprotocolfilters,neitherwillwetrytosendthisdatathroughafilterthatshouldn'tseeit.

Theproblemisthatweareusingadoubly-linkedlistforourfilterstacksnow.But,youshouldnoticethatitispossiblefortwoliststointersectinthismodel.So,youdoyouhandlethepreviouspointer?Thisisaverydifficultquestiontoanswer,becausethereisno"right"answer,eithermethodisequallyvalid.Ilookedatwhyweusethepreviouspointer.Theonlyreasonforitistoallowforeasieradditionofnewservers.Withthatbeingsaid,thesolutionI

chosewastomakethepreviouspointeralwaysstayontheoriginalrequest.

Thiscausessomemorecomplexlogic,butitworksforallcases.Myconcerninhavingitmovetothesub-request,isthatforthemorecommoncase(whereasub-requestisusedtoadddatatoaresponse),themainfilterchainwouldbewrong.Thatdidn'tseemlikeagoodideatome.

Thefinaltopic.:-)Mod_Asisisabitofahack,butthehandlerneedstoremoveallfiltersexceptforconnectionfilters,andsendthedata.Ifyouareusingmod_asis,allotherbetsareoff.

Explanations

Theabsolutelylastpointisthatthereasonthiscodewassohardtogetright,wasbecausewehadhackedsomuchtoforceittowork.Iwrotemostofthehacksoriginally,soIamverymuchtoblame.However,nowthatthecodeisright,Ihavestartedtoremovesomehacks.Mostpeopleshouldhaveseenthatthereset_filtersandadd_required_filtersfunctionsaregone.Thoseinsertedprotocollevelfiltersforerrorconditions,infact,bothfunctionsdidthesamething,oneaftertheother,itwasreallystrange.Becausewedon'tloseprotocolfiltersforerrorcasesanymore,thosehackswentaway.TheHTTP_HEADER,Content-length,andByterangefiltersarealladdedintheinsert_filtersphase,becauseiftheywereaddedearlier,wehadsomeinterestinginteractions.Now,thosecouldallbemovedtobeinsertedwiththeHTTP_IN,CORE,andCORE_INfilters.Thatwouldmakethecodeeasiertofollow.

Glossary

ThisglossarydefinessomeofthecommonterminologyrelatedtoApacheinparticular,andwebservingingeneral.Moreinformationoneachconceptisprovidedinthelinks.

Definitions

AccessControlTherestrictionofaccesstonetworkrealms.InanApachecontextusuallytherestrictionofaccesstocertainURLs.See:Authentication,Authorization,andAccessControl

AlgorithmAnunambiguousformulaorsetofrulesforsolvingaprobleminafinitenumberofsteps.AlgorithmsforencryptionareusuallycalledCiphers.

APacheeXtensionTool(apxs)Aperlscriptthataidsincompiling→modulesourcesintoDynamicSharedObjects(→DSOs)andhelpsinstallthemintheApacheWebserver.See:ManualPage:apxs

AuthenticationThepositiveidentificationofanetworkentitysuchasaserver,aclient,orauser.See:Authentication,Authorization,andAccessControl

CertificateAdatarecordusedforauthenticatingnetworkentitiessuchasaserveroraclient.AcertificatecontainsX.509informationpiecesaboutitsowner(calledthesubject)andthesigning→CertificationAuthority(calledtheissuer),plustheowner's→publickeyandthesignaturemadebytheCA.NetworkentitiesverifythesesignaturesusingCAcertificates.See:SSL/TLSEncryption

CertificateSigningRequest(CSR)Anunsigned→certificateforsubmissiontoa→CertificationAuthority,whichsignsitwiththe→PrivateKeyoftheirCACertificate.OncetheCSRissigned,itbecomesarealcertificate.See:SSL/TLSEncryption

CertificationAuthority(CA)Atrustedthirdpartywhosepurposeistosigncertificatesfornetworkentitiesithasauthenticatedusingsecuremeans.OthernetworkentitiescancheckthesignaturetoverifythataCAhasauthenticatedthebearerofacertificate.See:SSL/TLSEncryption

CipherAnalgorithmorsystemfordataencryption.ExamplesareDES,IDEA,RC4,etc.See:SSL/TLSEncryption

CiphertextTheresultafter→Plaintextispassedthrougha→Cipher.See:SSL/TLSEncryption

CommonGatewayInterface(CGI)Astandarddefinitionforaninterfacebetweenawebserverandanexternalprogramthatallowstheexternalprogramtoservicerequests.TheinterfacewasoriginallydefinedbyNCSAbutthereisalsoanRFCproject.See:DynamicContentwithCGI

ConfigurationDirectiveSee:→Directive

ConfigurationFileAtextfilecontaining→DirectivesthatcontroltheconfigurationofApache.See:ConfigurationFiles

CONNECTAnHTTP→methodforproxyingrawdatachannelsoverHTTP.Itcanbeusedtoencapsulateotherprotocols,suchastheSSLprotocol.

ContextAnareainthe→configurationfileswherecertaintypesof

→directivesareallowed.See:TermsUsedtoDescribeApacheDirectives

DigitalSignatureAnencryptedtextblockthatvalidatesacertificateorotherfile.A→CertificationAuthoritycreatesasignaturebygeneratingahashofthePublicKeyembeddedinaCertificate,thenencryptingthehashwithitsownPrivateKey.OnlytheCA'spublickeycandecryptthesignature,verifyingthattheCAhasauthenticatedthenetworkentitythatownstheCertificate.See:SSL/TLSEncryption

DirectiveAconfigurationcommandthatcontrolsoneormoreaspectsofApache'sbehavior.Directivesareplacedinthe→ConfigurationFileSee:DirectiveIndex

DynamicSharedObject(DSO)→ModulescompiledseparatelyfromtheApachehttpdbinarythatcanbeloadedon-demand.See:DynamicSharedObjectSupport

EnvironmentVariable(env-variable)Namedvariablesmanagedbytheoperatingsystemshellandusedtostoreinformationandcommunicatebetweenprograms.Apachealsocontainsinternalvariablesthatarereferredtoasenvironmentvariables,butarestoredininternalApachestructures,ratherthanintheshellenvironment.See:EnvironmentVariablesinApache

Export-CrippledDiminishedincryptographicstrength(andsecurity)inordertocomplywiththeUnitedStates'ExportAdministrationRegulations(EAR).Export-crippledcryptographicsoftwareislimitedtoasmallkeysize,resultinginCiphertextwhichusuallycanbedecryptedbybruteforce.

See:SSL/TLSEncryption

FilterAprocessthatisappliedtodatathatissentorreceivedbytheserver.Inputfiltersprocessdatasentbytheclienttotheserver,whileoutputfiltersprocessdocumentsontheserverbeforetheyaresenttotheclient.Forexample,theINCLUDESoutputfilterprocessesdocumentsfor→ServerSideIncludes.See:Filters

Fully-QualifiedDomain-Name(FQDN)Theuniquenameofanetworkentity,consistingofahostnameandadomainnamethatcanresolvetoanIPaddress.Forexample,wwwisahostname,example.comisadomainname,andwww.example.comisafully-qualifieddomainname.

HandlerAninternalApacherepresentationoftheactiontobeperformedwhenafileiscalled.Generally,fileshaveimplicithandlers,basedonthefiletype.Normally,allfilesaresimplyservedbytheserver,butcertainfiletypesare"handled"separately.Forexample,thecgi-scripthandlerdesignatesfilestobeprocessedas→CGIs.See:Apache'sHandlerUse

HashAmathematicalone-way,irreversablealgorithmgeneratingastringwithfixed-lengthfromanotherstringofanylength.Differentinputstringswillusuallyproducedifferenthashes(dependingonthehashfunction).

HeaderThepartofthe→HTTPrequestandresponsethatissentbeforetheactualcontent,andthatcontainsmeta-informationdescribingthecontent.

.htaccess

A→configurationfilethatisplacedinsidethewebtreeandappliesconfiguration→directivestothedirectorywhereitisplacedandallsub-directories.Despiteitsname,thisfilecanholdalmostanytypeofdirective,notjustaccess-controldirectives.See:ConfigurationFiles

httpd.confThemainApache→configurationfile.Thedefaultlocationis/usr/local/apache2/conf/httpd.conf,butitmaybemovedusingrun-timeorcompile-timeconfiguration.See:ConfigurationFiles

HyperTextTransferProtocol(HTTP)ThestandardtransmissionprotocolusedontheWorldWideWeb.Apacheimplementsversion1.1oftheprotocol,referredtoasHTTP/1.1anddefinedbyRFC2616.

HTTPSTheHyperTextTransferProtocol(Secure),thestandardencryptedcommunicationmechanismontheWorldWideWeb.ThisisactuallyjustHTTPover→SSL.See:SSL/TLSEncryption

MethodInthecontextof→HTTP,anactiontoperformonaresource,specifiedontherequestlinebytheclient.SomeofthemethodsavailableinHTTPareGET,POST,andPUT.

MessageDigestAhashofamessage,whichcanbeusedtoverifythatthecontentsofthemessagehavenotbeenalteredintransit.See:SSL/TLSEncryption

MIME-typeAwaytodescribethekindofdocumentbeingtransmitted.ItsnamecomesfromthatfactthatitsformatisborrowedfromtheMultipurposeInternetMailExtensions.Itconsistsofa

majortypeandaminortype,separatedbyaslash.Someexamplesaretext/html,image/gif,andapplication/octet-stream.InHTTP,theMIME-typeistransmittedintheContent-Type→header.See:mod_mime

ModuleAnindependentpartofaprogram.MuchofApache'sfunctionalityiscontainedinmodulesthatyoucanchoosetoincludeorexclude.ModulesthatarecompiledintotheApachehttpdbinaryarecalledstaticmodules,whilemodulesthatarestoredseparatelyandcanbeoptionallyloadedatrun-timearecalleddynamicmodulesor→DSOs.Modulesthatareincludedbydefaultarecalledbasemodules.ManymodulesareavailableforApachethatarenotdistributedaspartoftheApacheHTTPServer→tarball.Thesearereferredtoasthird-partymodules.See:ModuleIndex

ModuleMagicNumber(MMN)ModuleMagicNumberisaconstantdefinedintheApachesourcecodethatisassociatedwithbinarycompatibilityofmodules.ItischangedwheninternalApachestructures,functioncallsandothersignificantpartsofAPIchangeinsuchawaythatbinarycompatibilitycannotbeguaranteedanymore.OnMMNchange,allthirdpartymoduleshavetobeatleastrecompiled,sometimesevenslightlychangedinordertoworkwiththenewversionofApache.

OpenSSLTheOpenSourcetoolkitforSSL/TLSSeehttp://www.openssl.org/#

PassPhraseThewordorphrasethatprotectsprivatekeyfiles.Itpreventsunauthorizedusersfromencryptingthem.Usuallyit'sjustthe

secretencryption/decryptionkeyusedfor→Ciphers.See:SSL/TLSEncryption

PlaintextTheunencryptedtext.

PrivateKeyThesecretkeyina→PublicKeyCryptographysystem,usedtodecryptincomingmessagesandsignoutgoingones.See:SSL/TLSEncryption

ProxyAnintermediateserverthatsitsbetweentheclientandtheoriginserver.Itacceptsrequestsfromclients,transmitsthoserequestsontotheoriginserver,andthenreturnstheresponsefromtheoriginservertotheclient.Ifseveralclientsrequestthesamecontent,theproxycandeliverthatcontentfromitscache,ratherthanrequestingitfromtheoriginservereachtime,therebyreducingresponsetime.See:mod_proxy

PublicKeyThepubliclyavailablekeyina→PublicKeyCryptographysystem,usedtoencryptmessagesboundforitsownerandtodecryptsignaturesmadebyitsowner.See:SSL/TLSEncryption

PublicKeyCryptographyThestudyandapplicationofasymmetricencryptionsystems,whichuseonekeyforencryptionandanotherfordecryption.Acorrespondingpairofsuchkeysconstitutesakeypair.AlsocalledAsymmetricCryptography.See:SSL/TLSEncryption

RegularExpression(Regex)Awayofdescribingapatternintext-forexample,"allthewordsthatbeginwiththeletterA"or"every10-digitphonenumber"oreven"Everysentencewithtwocommasinit,and

nocapitalletterQ".RegularexpressionsareusefulinApachebecausetheyletyouapplycertainattributesagainstcollectionsoffilesorresourcesinveryflexibleways-forexample,all.gifand.jpgfilesunderany"images"directorycouldbewrittenas"/images/.*(jpg|gif)$".ApacheusesPerlCompatibleRegularExpressionsprovidedbythePCRElibrary.

ReverseProxyA→proxyserverthatappearstotheclientasifitisanoriginserver.Thisisusefultohidetherealoriginserverfromtheclientforsecurityreasons,ortoloadbalance.

SecureSocketsLayer(SSL)AprotocolcreatedbyNetscapeCommunicationsCorporationforgeneralcommunicationauthenticationandencryptionoverTCP/IPnetworks.ThemostpopularusageisHTTPS,i.e.theHyperTextTransferProtocol(HTTP)overSSL.See:SSL/TLSEncryption

ServerSideIncludes(SSI)AtechniqueforembeddingprocessingdirectivesinsideHTMLfiles.See:IntroductiontoServerSideIncludes

SessionThecontextinformationofacommunicationingeneral.

SSLeayTheoriginalSSL/TLSimplementationlibrarydevelopedbyEricA.Young

SymmetricCryptographyThestudyandapplicationofCiphersthatuseasinglesecretkeyforbothencryptionanddecryptionoperations.See:SSL/TLSEncryption

Tarball

Apackageoffilesgatheredtogetherusingthetarutility.Apachedistributionsarestoredincompressedtararchivesorusingpkzip.

TransportLayerSecurity(TLS)ThesuccessorprotocoltoSSL,createdbytheInternetEngineeringTaskForce(IETF)forgeneralcommunicationauthenticationandencryptionoverTCP/IPnetworks.TLSversion1isnearlyidenticalwithSSLversion3.See:SSL/TLSEncryption

UniformResourceLocator(URL)Thename/addressofaresourceontheInternet.Thisisthecommoninformaltermforwhatisformallycalleda→UniformResourceIdentifier.URLsareusuallymadeupofascheme,likehttporhttps,ahostname,andapath.AURLforthispageishttp://httpd.apache.org/docs/2.0/glossary.html

UniformResourceIdentifier(URI)Acompactstringofcharactersforidentifyinganabstractorphysicalresource.ItisformallydefinedbyRFC2396.URIsusedontheworld-widewebarecommonlyreferredtoas→URLs.

VirtualHostingServingmultiplewebsitesusingasingleinstanceofApache.IPvirtualhostingdifferentiatesbetweenwebsitesbasedontheirIPaddress,whilename-basedvirtualhostingusesonlythenameofthehostandcanthereforehostmanysitesonthesameIPaddress.See:ApacheVirtualHostdocumentation

X.509AnauthenticationcertificateschemerecommendedbytheInternationalTelecommunicationUnion(ITU-T)whichisusedforSSL/TLSauthentication.

See:SSL/TLSEncryption

||FAQ||

ApacheApache

A|B|C|D|E|F|G|H|I|K|L|M|N|O|P|R|S|T|U|V|W|X

AcceptMutexAcceptPathInfoAccessFileNameActionAddAltAddAltByEncodingAddAltByTypeAddCharsetAddDefaultCharsetAddDescriptionAddEncodingAddHandlerAddIconAddIconByEncodingAddIconByTypeAddInputFilterAddLanguageAddModuleInfoAddOutputFilterAddOutputFilterByTypeAddTypeAliasAliasMatchAllowAllowCONNECT

AllowEncodedSlashesAllowOverrideAnonymousAnonymous_AuthoritativeAnonymous_LogEmailAnonymous_MustGiveEmailAnonymous_NoUserIDAnonymous_VerifyEmailAssignUserIDAuthAuthoritativeAuthDBMAuthoritativeAuthDBMGroupFileAuthDBMTypeAuthDBMUserFileAuthDigestAlgorithmAuthDigestDomainAuthDigestFileAuthDigestGroupFileAuthDigestNcCheckAuthDigestNonceFormatAuthDigestNonceLifetimeAuthDigestQopAuthDigestShmemSizeAuthGroupFileAuthLDAPAuthoritativeAuthLDAPBindDNAuthLDAPBindPasswordAuthLDAPCharsetConfigAuthLDAPCompareDNOnServerAuthLDAPDereferenceAliasesAuthLDAPEnabledAuthLDAPFrontPageHackAuthLDAPGroupAttributeAuthLDAPGroupAttributeIsDN

AuthLDAPRemoteUserIsDNAuthLDAPUrlAuthNameAuthTypeAuthUserFileBrowserMatchBrowserMatchNoCaseBS2000AccountBufferedLogsCacheDefaultExpireCacheDirLengthCacheDirLevelsCacheDisableCacheEnableCacheExpiryCheckCacheFileCacheForceCompletionCacheGcCleanCacheGcDailyCacheGcIntervalCacheGcMemUsageCacheGcUnusedCacheIgnoreCacheControlCacheIgnoreHeadersCacheIgnoreNoLastModCacheLastModifiedFactorCacheMaxExpireCacheMaxFileSizeCacheMinFileSizeCacheNegotiatedDocsCacheRootCacheSizeCacheTimeMarginCGIMapExtension

CharsetDefaultCharsetOptionsCharsetSourceEncCheckSpellingChildPerUserIDContentDigestCookieDomainCookieExpiresCookieLogCookieNameCookieStyleCookieTrackingCoreDumpDirectoryCustomLogDavDavDepthInfinityDavLockDBDavMinTimeoutDefaultIconDefaultLanguageDefaultTypeDeflateBufferSizeDeflateCompressionLevelDeflateFilterNoteDeflateMemLevelDeflateWindowSizeDeny<Directory>DirectoryIndex<DirectoryMatch>DirectorySlashDocumentRootDumpIOInputDumpIOOutput

EnableExceptionHookEnableMMAPEnableSendfileErrorDocumentErrorLogExampleExpiresActiveExpiresByTypeExpiresDefaultExtendedStatusExtFilterDefineExtFilterOptionsFileETag<Files><FilesMatch>ForceLanguagePriorityForceTypeForensicLogGroupHeaderHeaderNameHostnameLookupsIdentityCheck<IfDefine><IfModule><IfVersion>ImapBaseImapDefaultImapMenuIncludeIndexIgnoreIndexOptionsIndexOrderDefaultISAPIAppendLogToErrors

ISAPIAppendLogToQueryISAPICacheFileISAPIFakeAsyncISAPILogNotSupportedISAPIReadAheadBufferKeepAliveKeepAliveTimeoutLanguagePriorityLDAPCacheEntriesLDAPCacheTTLLDAPConnectionTimeoutLDAPOpCacheEntriesLDAPOpCacheTTLLDAPSharedCacheFileLDAPSharedCacheSizeLDAPTrustedCALDAPTrustedCAType<Limit><LimitExcept>LimitInternalRecursionLimitRequestBodyLimitRequestFieldsLimitRequestFieldSizeLimitRequestLineLimitXMLRequestBodyListenListenBackLogLoadFileLoadModule<Location><LocationMatch>LockFileLogFormatLogLevel

MaxClientsMaxKeepAliveRequestsMaxMemFreeMaxRangesMaxRequestsPerChildMaxRequestsPerThreadMaxSpareServersMaxSpareThreadsMaxThreadsMaxThreadsPerChildMCacheMaxObjectCountMCacheMaxObjectSizeMCacheMaxStreamingBufferMCacheMinObjectSizeMCacheRemovalAlgorithmMCacheSizeMetaDirMetaFilesMetaSuffixMimeMagicFileMinSpareServersMinSpareThreadsMMapFileModMimeUsePathInfoMultiviewsMatchNameVirtualHostNoProxyNumServersNWSSLTrustedCertsNWSSLUpgradeableOptionsOrderPassEnvPidFile

ProtocolEcho<Proxy>ProxyBadHeaderProxyBlockProxyDomainProxyErrorOverrideProxyFtpDirCharsetProxyIOBufferSize<ProxyMatch>ProxyMaxForwardsProxyPassProxyPassReverseProxyPreserveHostProxyReceiveBufferSizeProxyRemoteProxyRemoteMatchProxyRequestsProxyTimeoutProxyViaReadmeNameReceiveBufferSizeRedirectRedirectMatchRedirectPermanentRedirectTempRemoveCharsetRemoveEncodingRemoveHandlerRemoveInputFilterRemoveLanguageRemoveOutputFilterRemoveTypeRequestHeaderRequire

RewriteBaseRewriteCondRewriteEngineRewriteLockRewriteLogRewriteLogLevelRewriteMapRewriteOptionsRewriteRuleRLimitCPURLimitMEMRLimitNPROCSatisfyScoreBoardFileScriptScriptAliasScriptAliasMatchScriptInterpreterSourceScriptLogScriptLogBufferScriptLogLengthScriptSockSecureListenSendBufferSizeServerAdminServerAliasServerLimitServerNameServerPathServerRootServerSignatureServerTokensSetEnvSetEnvIf

SetEnvIfNoCaseSetHandlerSetInputFilterSetOutputFilterSSIEndTagSSIErrorMsgSSIStartTagSSITimeFormatSSIUndefinedEchoSSLCACertificateFileSSLCACertificatePathSSLCARevocationFileSSLCARevocationPathSSLCertificateChainFileSSLCertificateFileSSLCertificateKeyFileSSLCipherSuiteSSLEngineSSLHonorCipherOrderSSLInsecureRenegotiationSSLMutexSSLOptionsSSLPassPhraseDialogSSLProtocolSSLProxyCACertificateFileSSLProxyCACertificatePathSSLProxyCARevocationFileSSLProxyCARevocationPathSSLProxyCipherSuiteSSLProxyEngineSSLProxyMachineCertificateFileSSLProxyMachineCertificatePathSSLProxyProtocolSSLProxyVerify

||FAQ||

SSLProxyVerifyDepthSSLRandomSeedSSLRequireSSLRequireSSLSSLSessionCacheSSLSessionCacheTimeoutSSLUserNameSSLVerifyClientSSLVerifyDepthStartServersStartThreadsSuexecUserGroupThreadLimitThreadsPerChildThreadStackSizeTimeOutTraceEnableTransferLogTypesConfigUnsetEnvUseCanonicalNameUserUserDirVirtualDocumentRootVirtualDocumentRootIP<VirtualHost>VirtualScriptAliasVirtualScriptAliasIPWin32DisableAcceptExXBitHack

||FAQ||

Apache

A|B|C|D|E|F|G|H|I|K|L|M|N|O|P|R|

S|T|U|V|W|X

h .htaccess

C CoreM MPMB BaseE ExtensionX Experimental

AcceptMutexdefault|method defaultacceptApache

AcceptPathInfoOn|Off|Default Default

AccessFileNamefilename[filename]... .htaccess

Actionaction-typecgi-scriptCGI

AddAltstringfile[file]...

AddAltByEncodingstringMIME-encoding[MIME-encoding]...MIME

AddAltByTypestringMIME-type[MIME-type]...MIME

AddCharsetcharsetextension[extension]...

AddDefaultCharsetOn|Off|charset Off

AddDescriptionstringfile[file]...

AddEncodingMIME-encextension[extension]...

AddHandlerhandler-nameextension[extension]...

AddIconiconname[name]...

AddIconByEncodingiconMIME-encoding[MIME-encoding]...MIME

AddIconByTypeiconMIME-type[MIME-type]...MIME

AddInputFilterfilter[;filter...]extension[extension]...

AddLanguageMIME-langextension[extension]...

AddModuleInfomodule-namestringserver-info

AddOutputFilterfilter[;filter...]extension[extension]...

AddOutputFilterByTypefilter[;filter...]MIME-type[MIME-type]...MIME-type

AddTypeMIME-typeextension[extension]...

AliasURL-pathfile-path|directory-pathURL

AliasMatchregexfile-path|directory-pathURL

Allowfromall|host|env=env-variable[host|env=env-variable]...

AllowCONNECTport[port]... 443563PortsthatareallowedtoCONNECTthroughtheproxy

AllowEncodedSlashesOn|Off OffURL

AllowOverrideAll|None|directive-type[directive-type]...

.htaccess

Anonymoususer[user]...SpecifiesuserIDsthatareallowedaccesswithoutpasswordverification

Anonymous_AuthoritativeOn|Off OffConfiguresifauthorizationwillfall-throughtoothermethods

Anonymous_LogEmailOn|Off OnSetswhetherthepasswordenteredwillbeloggedintheerrorlog

Anonymous_MustGiveEmailOn|Off OnSpecifieswhetherblankpasswordsareallowed

Anonymous_NoUserIDOn|Off OffSetswhethertheuserIDfieldmaybeempty

Anonymous_VerifyEmailOn|Off OffSetswhethertocheckthepasswordfieldforacorrectlyformattedemailaddress

AssignUserIDuser-idgroup-idTieavirtualhosttoauserandgroupID

AuthAuthoritativeOn|Off On

AuthDBMAuthoritativeOn|Off OnSetswhetherauthenticationandauthorizationwillbepassedontolowerlevelmodules

AuthDBMGroupFilefile-pathSetsthenameofthedatabasefilecontainingthelistofusergroupsforauthentication

AuthDBMType default

default|SDBM|GDBM|NDBM|DBSetsthetypeofdatabasefilethatisusedtostorepasswords

AuthDBMUserFilefile-pathSetsthenameofadatabasefilecontainingthelistofusersandpasswordsforauthentication

AuthDigestAlgorithmMD5|MD5-sess MD5Selectsthealgorithmusedtocalculatethechallengeandresponsehasesindigestauthentication

AuthDigestDomainURI[URI]...URIsthatareinthesameprotectionspacefordigestauthentication

AuthDigestFilefile-pathLocationofthetextfilecontainingthelistofusersandencodedpasswordsfordigestauthentication

AuthDigestGroupFilefile-pathNameofthetextfilecontainingthelistofgroupsfordigestauthentication

AuthDigestNcCheckOn|Off OffEnablesordisablescheckingofthenonce-countsentbytheserver

AuthDigestNonceFormatformatDetermineshowthenonceisgenerated

AuthDigestNonceLifetimeseconds 300Howlongtheservernonceisvalid

AuthDigestQopnone|auth|auth-int[auth|auth-int]

Determinesthequality-of-protectiontouseindigestauthentication

AuthDigestShmemSizesize 1000Theamountofsharedmemorytoallocateforkeepingtrackofclients

AuthGroupFilefile-path

AuthLDAPAuthoritativeon|off onPreventotherauthenticationmodulesfromauthenticatingtheuserifthisonefails

AuthLDAPBindDNdistinguished-nameOptionalDNtouseinbindingtotheLDAPserver

AuthLDAPBindPasswordpasswordPasswordusedinconjuctionwiththebindDN

AuthLDAPCharsetConfigfile-pathLanguagetocharsetconversionconfigurationfile

AuthLDAPCompareDNOnServeron|off onUsetheLDAPservertocomparetheDNs

AuthLDAPDereferenceAliasesnever|searching|finding|always

Always

Whenwillthemodulede-referencealiases

AuthLDAPEnabledon|off onTurnonoroffLDAPauthentication

AuthLDAPFrontPageHackon|off offAllowLDAPauthenticationtoworkwithMSFrontPage

AuthLDAPGroupAttributeattributeLDAPattributesusedtocheckforgroupmembership

AuthLDAPGroupAttributeIsDNon|off onUsetheDNoftheclientusernamewhencheckingforgroupmembership

AuthLDAPRemoteUserIsDNon|off offUsetheDNoftheclientusernametosettheREMOTE_USERenvironmentvariable

AuthLDAPUrlurlURLspecifyingtheLDAPsearchparameters

AuthNameauth-domainHTTP(:realm)

AuthTypeBasic|Digest

AuthUserFilefile-path

BrowserMatchregex[!]env-variable[=value][[!]env-variable[=value]]...HTTPUser-Agent

BrowserMatchNoCaseregex[!]env-variable[=value][[!]env-variable[=value]]...HTTPUser-Agent

BS2000AccountaccountBS2000

BufferedLogsOn|Off OffBufferlogentriesinmemorybeforewritingtodisk

CacheDefaultExpireseconds 3600(onehour)Thedefaultdurationtocacheadocumentwhennoexpirydateisspecified.

CacheDirLengthlength 2Thenumberofcharactersinsubdirectorynames

CacheDirLevelslevels 3Thenumberoflevelsofsubdirectoriesinthecache.

CacheDisableurl-stringDisablecachingofspecifiedURLs

CacheEnablecache_typeurl-stringEnablecachingofspecifiedURLsusingaspecifiedstoragemanager

CacheExpiryCheckOn|Off OnIndicatesifthecacheobservesExpiresdateswhenseekingfiles

CacheFilefile-path[file-path]...Cachealistoffilehandlesatstartuptime

CacheForceCompletionPercentage 60Percentageofdocumentserved,afterwhichtheserverwillcompletecachingthefileeveniftherequestiscancelled.

CacheGcCleanhoursurl-string ?ThetimetoretainunchangedcachedfilesthatmatchaURL

CacheGcDailytime ?Therecurringtimeeachdayforgarbagecollectiontoberun.(24hourclock)

CacheGcIntervalhoursTheintervalbetweengarbagecollectionattempts.

CacheGcMemUsageKBytes ?Themaximumkilobytesofmemoryusedforgarbagecollection

CacheGcUnusedhoursurl-string ?ThetimetoretainunreferencedcachedfilesthatmatchaURL.

CacheIgnoreCacheControlOn|Off OffIgnorethefactthattheclientrequestedthecontentnotbecached.

CacheIgnoreHeadersheader-string[header-string]...

DonotstorethegivenHTTPheader(s)inthecache.

CacheIgnoreNoLastModOn|Off OffIgnorethefactthataresponsehasnoLastModifiedheader.

CacheLastModifiedFactorfloat 0.1ThefactorusedtocomputeanexpirydatebasedontheLastModifieddate.

CacheMaxExpireseconds 86400(oneday)Themaximumtimeinsecondstocacheadocument

CacheMaxFileSizebytes 1000000

Themaximumsize(inbytes)ofadocumenttobeplacedinthecache

CacheMinFileSizebytes 1Theminimumsize(inbytes)ofadocumenttobeplacedinthecache

CacheNegotiatedDocsOn|Off Off

CacheRootdirectoryThedirectoryrootunderwhichcachefilesarestored

CacheSizeKBytes 1000000ThemaximumamountofdiskspacethatwillbeusedbythecacheinKBytes

CacheTimeMargin? ?Theminimumtimemargintocacheadocument

CGIMapExtensioncgi-path.extensionCGI

CharsetDefaultcharsetCharsettotranslateinto

CharsetOptionsoption[option]... DebugLevel=0NoImpl+Configurescharsettranslationbehavior

CharsetSourceEnccharsetSourcecharsetoffiles

CheckSpellingon|off Offspelling

ChildPerUserIDuser-idgroup-idnum-childrenSpecifyuserIDandgroupIDforanumberofchildprocesses

ContentDigestOn|Off OffContent-MD5HTTP

CookieDomaindomainThedomaintowhichthetrackingcookieapplies

CookieExpiresexpiry-periodExpirytimeforthetrackingcookie

CookieLogfilename

CookieNametoken ApacheNameofthetrackingcookie

CookieStyleNetscape|Cookie|Cookie2|RFC2109|RFC2965

Netscape

Formatofthecookieheaderfield

CookieTrackingon|off offEnablestrackingcookie

CoreDumpDirectorydirectoryApache

CustomLogfile|pipeformat|nickname[env=[!]environment-variable]

DavOn|Off|provider-name OffWebDAVHTTP

DavDepthInfinityon|off offPROPFIND,Depth:Infinity

DavLockDBfile-pathDAV

DavMinTimeoutseconds 0DAV

DefaultIconurl-path

DefaultLanguageMIME-lang

DefaultTypeMIME-type text/plainMIME

DeflateBufferSizevalue 8096zlib

DeflateCompressionLevelvalue

DeflateFilterNote[type]notename

DeflateMemLevelvalue 9zlib

DeflateWindowSizevalue 15Zlib

Denyfromall|host|env=env-variable[host|env=env-variable]...

<Directorydirectory-path>...</Directory>

DirectoryIndexlocal-url[local-url]... index.html

DirectorySlashOn|Off On

DocumentRootdirectory-path /usr/local/apache/h+

DumpIOInputOn|Off OffDumpallinputdatatotheerrorlog

DumpIOOutputOn|Off OffDumpalloutputdatatotheerrorlog

EnableExceptionHookOn|Off Off

EnableMMAPOn|Off On

EnableSendfileOn|Off Onsendfile

ErrorDocumenterror-codedocument

ErrorLogfile-path|syslog[:facility] logs/error_log(Uni+

ExampleDemonstrationdirectivetoillustratetheApachemoduleAPI

ExpiresActiveOn|OffExpires

ExpiresByTypeMIME-type<code>secondsMIME Expires

ExpiresDefault<code>seconds

ExtendedStatusOn|Off Off

ExtFilterDefinefilternameparameters

Defineanexternalfilter

ExtFilterOptionsoption[option]... DebugLevel=0NoLogS+

Configuremod_ext_filteroptions

FileETagcomponent... INodeMTimeSizeETagHTTP

ForceLanguagePriorityNone|Prefer|Fallback[Prefer|Fallback]

Prefer

ForceTypeMIME-type|NoneMIME

ForensicLogfilename|pipeSetsfilenameoftheforensiclog

Groupunix-group #-1

Header[condition]set|append|add|unset|echoheader[value][env=[!]variable]ConfigureHTTPresponseheaders

HeaderNamefilename

HostnameLookupsOn|Off|Double OffIPDNS

IdentityCheckOn|Off OffRFC1413

<IfDefine[!]parameter-name>...</IfDefine>

<IfModule[!]module-name>...</IfModule>

<IfVersion[[!]operator]version>...</IfVersion>

ImapBasemap|referer|URL http://servername/Defaultbaseforimagemapfiles

ImapDefaulterror|nocontent|map|referer|URL nocontentDefaultactionwhenanimagemapiscalledwithcoordinatesthatarenotexplicitlymapped

ImapMenunone|formatted|semiformatted|unformattedActionifnocoordinatesaregivenwhencallinganimagemap

Includefile-path|directory-path

IndexIgnorefile[file]...

IndexOptions[+|-]option[[+|-]option]...

IndexOrderDefaultAscending|DescendingName|Date|Size|Description

AscendingName

ISAPIAppendLogToErrorson|off offRecordHSE_APPEND_LOG_PARAMETERrequestsfromISAPIextensionstotheerrorlog

ISAPIAppendLogToQueryon|off onRecordHSE_APPEND_LOG_PARAMETERrequestsfromISAPIextensionstothequeryfield

ISAPICacheFilefile-path[file-path]...ISAPI.dllfilestobeloadedatstartup

ISAPIFakeAsyncon|off offFakeasynchronoussupportforISAPIcallbacks

ISAPILogNotSupportedon|off offLogunsupportedfeaturerequestsfromISAPIextensions

ISAPIReadAheadBuffersize 49152SizeoftheReadAheadBuffersenttoISAPIextensions

KeepAliveOn|Off OnHTTP

KeepAliveTimeoutseconds 15

LanguagePriorityMIME-lang[MIME-lang]...variant

LDAPCacheEntriesnumber 1024

MaximumnumberofentriesintheprimaryLDAPcache

LDAPCacheTTLseconds 600Timethatcacheditemsremainvalid

LDAPConnectionTimeoutsecondsSpecifiesthesocketconnectiontimeoutinseconds

LDAPOpCacheEntriesnumber 1024NumberofentriesusedtocacheLDAPcompareoperations

LDAPOpCacheTTLseconds 600Timethatentriesintheoperationcacheremainvalid

LDAPSharedCacheFiledirectory-path/filenameSetsthesharedmemorycachefile

LDAPSharedCacheSizebytes 102400Sizeinbytesoftheshared-memorycache

LDAPTrustedCAdirectory-path/filenameSetsthefilecontainingthetrustedCertificateAuthoritycertificateordatabase

LDAPTrustedCATypetypeSpecifiesthetypeoftheCertificateAuthorityfile

<Limitmethod[method]...>...</Limit>HTTP

<LimitExceptmethod[method]...>...</LimitExcept>HTTP

LimitInternalRecursionnumber[number] 10

LimitRequestBodybytes 0HTTP

LimitRequestFieldsnumber 100HTTP

LimitRequestFieldsizebytesHTTP

LimitRequestLinebytes 8190HTTP

LimitXMLRequestBodybytes 1000000XML

Listen[IP-address:]portnumberlistenIP

ListenBacklogbacklog

LoadFilefilename[filename]...

LoadModulemodulefilename

<LocationURL-path|URL>...</Location>URL

<LocationMatchregex>...</LocationMatch>URL

LockFilefilename logs/accept.lock

LogFormatformat|nickname[nickname] "%h%l%u%t\"%r\"+

LogLevellevel warnErrorLog

MaxClientsnumber

MaxKeepAliveRequestsnumber 100

MaxMemFreeKBytes 0free()

MaxRangesdefault|unlimited|none|number-of-ranges

Numberofrangesallowedbeforereturningthecompleteresource

MaxRequestsPerChildnumber 10000

MaxRequestsPerThreadnumber 0Limitonthenumberofrequeststhatanindividualthreadwillhandleduringitslife

MaxSpareServersnumber 10

MaxSpareThreadsnumber

MaxThreadsnumber 2048Setthemaximumnumberofworkerthreads

MaxThreadsPerChildnumber 64Maximumnumberofthreadsperchildprocess

MCacheMaxObjectCountvalue 1009

MCacheMaxObjectSizebytes 10000()

MCacheMaxStreamingBuffersize_in_bytes of100000MCacheM+

MCacheMinObjectSizebytes 0()

MCacheRemovalAlgorithmLRU|GDSF GDSF

MCacheSizeKBytes 100

MetaDirdirectory .webNameofthedirectorytofindCERN-stylemetainformationfiles

MetaFileson|off offActivatesCERNmeta-fileprocessing

MetaSuffixsuffix .metaFilenamesuffixforthefilecontaingCERN-stylemetainformation

MimeMagicFilefile-pathEnableMIME-typedeterminationbasedonfilecontentsusingthespecifiedmagicfile

MinSpareServersnumber 5

MinSpareThreadsnumber

MMapFilefile-path[file-path]...Mapalistoffilesintomemoryatstartuptime

ModMimeUsePathInfoOn|Off Offpath_infomod_mime

MultiviewsMatchAny|NegotiatedOnly|Filters|Handlers

NegotiatedOnly

[Handlers|Filters]MultiViews

NameVirtualHostaddr[:port]IP

NoProxyhost[host]...Hosts,domains,ornetworksthatwillbeconnectedtodirectly

NumServersnumber 2Totalnumberofchildrenaliveatthesametime

NWSSLTrustedCertsfilename[filename]...Listofadditionalclientcertificates

NWSSLUpgradeable[IP-address:]portnumberAllowsaconnectiontobeupgradedtoanSSLconnectionuponrequest

Options[+|-]option[[+|-]option]... All

Orderordering Deny,AllowAllow Deny

PassEnvenv-variable[env-variable]...

PidFilefilename logs/httpd.pidID

ProtocolEchoOn|Off

<Proxywildcard-url>...</Proxy>Containerfordirectivesappliedtoproxiedresources

ProxyBadHeaderIsError|Ignore|StartBody IsErrorDetermineshowtohandlebadheaderlinesinaresponse

ProxyDomainDomainDefaultdomainnameforproxiedrequests

ProxyErrorOverrideOn|Off OffOverrideerrorpagesforproxiedcontent

ProxyFtpDirCharsetcharacterset ISO-8859-1DefinethecharactersetforproxiedFTPlistings

ProxyIOBufferSizebytes 8192Determinesizeofinternaldatathroughputbuffer

<ProxyMatchregex>...</ProxyMatch>Containerfordirectivesappliedtoregular-expression-matchedproxiedresources

ProxyMaxForwardsnumber 10Maximiumnumberofproxiesthatarequestcanbeforwardedthrough

ProxyPass[path]!|urlMapsremoteserversintothelocalserverURL-space

ProxyPassReverse[path]urlAdjuststheURLinHTTPresponseheaderssentfromareverseproxiedserver

ProxyPreserveHostOn|Off OffUseincomingHostHTTPrequestheaderforproxyrequest

ProxyReceiveBufferSizebytes 0NetworkbuffersizeforproxiedHTTPandFTPconnections

ProxyRemotematchremote-serverRemoteproxyusedtohandlecertainrequests

ProxyRemoteMatchregexremote-serverRemoteproxyusedtohandlerequestsmatchedbyregularexpressions

ProxyRequestsOn|Off OffEnablesforward(standard)proxyrequests

ProxyTimeoutseconds 300Networktimeoutforproxiedrequests

ProxyViaOn|Off|Full|Block OffInformationprovidedintheViaHTTPresponseheaderforproxiedrequests

ReadmeNamefilename

ReceiveBufferSizebytes 0TCPreceivebuffersize

Redirect[status]URL-pathURLURL

RedirectMatch[status]regexURLURL

RedirectPermanentURL-pathURLURL

RedirectTempURL-pathURL

RemoveCharsetextension[extension]...

RemoveEncodingextension[extension]...

RemoveHandlerextension[extension]...

RemoveInputFilterextension[extension]...

RemoveLanguageextension[extension]...

RemoveOutputFilterextension[extension]...

RemoveTypeextension[extension]...

RequestHeaderset|append|add|unsetheader[value[env=[!]variable]]ConfigureHTTPrequestheaders

Requireentity-name[entity-name]...

RewriteBaseURL-pathSetsthebaseURLforper-directoryrewrites

RewriteCondTestStringCondPatternDefinesaconditionunderwhichrewritingwilltakeplace

RewriteEngineon|off offEnablesordisablesruntimerewritingengine

RewriteLockfile-pathSetsthenameofthelockfileusedforRewriteMapsynchronization

RewriteLogfile-pathSetsthenameofthefileusedforloggingrewriteengineprocessing

RewriteLogLevelLevel 0Setstheverbosityofthelogfileusedbytherewriteengine

RewriteMapMapNameMapType:MapSourceDefinesamappingfunctionforkey-lookup

RewriteOptionsOptions MaxRedirects=10

Setssomespecialoptionsfortherewriteengine

RewriteRulePatternSubstitutionDefinesrulesfortherewritingengine

RLimitCPUseconds|max[seconds|max]ApacheCPU

RLimitMEMbytes|max[bytes|max]Apache

RLimitNPROCnumber|max[number|max]Apache

SatisfyAny|All All

ScoreBoardFilefile-path logs/apache_status

Scriptmethodcgi-scriptCGI

ScriptAliasURL-pathfile-path|directory-pathURLCGI

ScriptAliasMatchregexfile-path|directory-pathURLCGI

ScriptInterpreterSourceRegistry|Registry-Strict|Script

Script

ScriptLogfile-pathCGI

ScriptLogBufferbytes 1024PUTPOST

ScriptLogLengthbytes 10385760CGI

ScriptSockfile-path logs/cgisockCGI

SecureListen[IP-address:]portnumberCertificate-Name[MUTUAL]EnablesSSLencryptionforthespecifiedport

SendBufferSizebytes 0TCP

ServerAdminemail-address

ServerAliashostname[hostname]...

ServerLimitnumber

ServerNamefully-qualified-domain-name[:port]

ServerPathURL-pathURL

ServerRootdirectory-path /usr/local/apache

ServerSignatureOn|Off|EMail Off

ServerHTTP

SetEnvenv-variablevalue

SetEnvIfattributeregex[!]env-variable[=value][[!]env-variable[=value]]...

SetEnvIfNoCaseattributeregex[!]env-variable[=value][[!]env-variable[=value]]...

SetHandlerhandler-name|None

SetInputFilterfilter[;filter...]POST

SetOutputFilterfilter[;filter...]

SSIEndTagtag "-->"include

SSIErrorMsgmessage "[anerroroccurred+

SSIStartTagtag "<!--#"include

SSITimeFormatformatstring "%A,%d-%b-%Y%H:%M+

SSIUndefinedEchostring "(none)"echo

SSLCACertificateFilefile-pathFileofconcatenatedPEM-encodedCACertificatesforClientAuth

SSLCACertificatePathdirectory-pathDirectoryofPEM-encodedCACertificatesforClientAuth

SSLCARevocationFilefile-pathFileofconcatenatedPEM-encodedCACRLsforClientAuth

SSLCARevocationPathdirectory-pathDirectoryofPEM-encodedCACRLsforClientAuth

SSLCertificateChainFilefile-pathFileofPEM-encodedServerCACertificates

SSLCertificateFilefile-pathServerPEM-encodedX.509Certificatefile

SSLCertificateKeyFilefile-pathServerPEM-encodedPrivateKeyfile

SSLCipherSuitecipher-spec ALL:!ADH:RC4+RSA:+H+

CipherSuiteavailablefornegotiationinSSLhandshake

SSLEngineon|off offSSLEngineOperationSwitch

SSLHonorCipherOrderflagOptiontoprefertheserver'scipherpreferenceorder

SSLInsecureRenegotiationflag offOptiontoenablesupportforinsecurerenegotiation

SSLMutextype noneSemaphoreforinternalmutualexclusionofoperations

SSLOptions[+|-]option...ConfigurevariousSSLenginerun-timeoptions

SSLPassPhraseDialogtype builtinTypeofpassphrasedialogforencryptedprivatekeys

SSLProtocol[+|-]protocol... allConfigureusableSSLprotocolflavors

SSLProxyCACertificateFilefile-pathFileofconcatenatedPEM-encodedCACertificatesforRemoteServerAuth

SSLProxyCACertificatePathdirectory-pathDirectoryofPEM-encodedCACertificatesforRemoteServerAuth

SSLProxyCARevocationFilefile-pathFileofconcatenatedPEM-encodedCACRLsforRemoteServerAuth

SSLProxyCARevocationPathdirectory-pathDirectoryofPEM-encodedCACRLsforRemoteServerAuth

SSLProxyCipherSuitecipher-spec ALL:!ADH:RC4+RSA:+H+

CipherSuiteavailablefornegotiationinSSLproxyhandshake

SSLProxyEngineon|off offSSLProxyEngineOperationSwitch

SSLProxyMachineCertificateFilefilenameFileofconcatenatedPEM-encodedclientcertificatesandkeystobeusedbytheproxy

SSLProxyMachineCertificatePathdirectoryDirectoryofPEM-encodedclientcertificatesandkeystobeusedbytheproxy

SSLProxyProtocol[+|-]protocol... allConfigureusableSSLprotocolflavorsforproxyusage

SSLProxyVerifylevel noneTypeofremoteserverCertificateverification

SSLProxyVerifyDepthnumber 1MaximumdepthofCACertificatesinRemoteServerCertificateverification

SSLRandomSeedcontextsource[bytes]PseudoRandomNumberGenerator(PRNG)seedingsource

SSLRequireexpressionAllowaccessonlywhenanarbitrarilycomplexbooleanexpressionistrue

SSLRequireSSLDenyaccesswhenSSLisnotusedfortheHTTPrequest

SSLSessionCachetype noneTypeoftheglobal/inter-processSSLSessionCache

SSLSessionCacheTimeoutseconds 300NumberofsecondsbeforeanSSLsessionexpiresintheSessionCache

SSLUserNamevarnameVariablenametodetermineusername

SSLVerifyClientlevel noneTypeofClientCertificateverification

SSLVerifyDepthnumber 1MaximumdepthofCACertificatesinClientCertificateverification

StartServersnumber

StartThreadsnumber

SuexecUserGroupUserGroupCGI

ThreadLimitnumber

ThreadsPerChildnumber

ThreadStackSizenumber 65536Determinethestacksizeforeachthread

TimeOutseconds 300

TraceEnable[on|off|extended] onDeterminesthebehaviouronTRACErequests

TransferLogfile|pipe

TypesConfigfile-path conf/mime.typesmime.types

UnsetEnvenv-variable[env-variable]...

UseCanonicalNameOn|Off|Dns On

Userunix-userid #-1ID

UserDirdirectory-filename public_html

||FAQ||

VirtualDocumentRootinterpolated-directory|none

Dynamicallyconfigurethelocationofthedocumentrootforagivenvirtualhost

VirtualDocumentRootIPinterpolated-directory|none

Dynamicallyconfigurethelocationofthedocumentrootforagivenvirtualhost

<VirtualHostaddr[:port][addr[:port]]...>...</VirtualHost>IP

VirtualScriptAliasinterpolated-directory|none noneDynamicallyconfigurethelocationoftheCGIdirectoryforagivenvirtualhost

VirtualScriptAliasIPinterpolated-directory|none

Dynamicallyconfigurethelocationofthecgidirectoryforagivenvirtualhost

Win32DisableAcceptExaccept()AcceptEx

XBitHackon|off|full offSSI

||FAQ||

Apache

(MPMs)

coreApacheHTTP

mpm_common(MPM)

beosThisMulti-ProcessingModuleisoptimizedforBeOS.

leaderAnexperimentalvariantofthestandardworkerMPM

mpm_netwareMulti-ProcessingModuleimplementinganexclusivelythreadedwebserveroptimizedforNovellNetWare

mpmt_os2Hybridmulti-process,multi-threadedMPMforOS/2

perchildMulti-ProcessingModuleallowingfordaemonprocessesservingrequeststobeassignedavarietyofdifferentuserids

preforkfork

threadpoolYetanotherexperimentalvariantofthestandardworkerMPM

mpm_winntWindowsNT

worker

A|C|D|E|F|H|I|L|M|N|P|R|S|U|V

mod_accessIP

mod_actionsCGI

mod_alias

mod_asisHTTP

mod_auth

mod_auth_anonAllows"anonymous"useraccesstoauthenticatedareas

mod_auth_dbmProvidesforuserauthenticationusingDBMfiles

mod_auth_digestUserauthenticationusingMD5DigestAuthentication.

mod_auth_ldapAllowsanLDAPdirectorytobeusedtostorethedatabaseforHTTPBasicauthentication.

mod_autoindexUnix ls Win32 dir

mod_cacheContentcachekeyedtoURIs.

mod_cern_metaCERNhttpdmetafilesemantics

mod_cgiCGI

mod_cgidCGICGI

mod_charset_liteSpecifycharactersettranslationorrecoding

mod_dav(WebDAV)

mod_dav_fsmod_dav

mod_deflate

mod_dir

mod_disk_cacheContentcachestoragemanagerkeyedtoURIs

mod_dumpioDumpsallI/Otoerrorlogasdesired.

mod_echo

mod_envCGISSI

mod_exampleIllustratestheApachemoduleAPI

mod_expires Expires Cache-ControlHTTP

mod_ext_filterPasstheresponsebodythroughanexternalprogrambeforedeliverytotheclient

mod_file_cacheCachesastaticlistoffilesinmemory

mod_headersCustomizationofHTTPrequestandresponseheaders

mod_imapServer-sideimagemapprocessing

mod_includehtml(ServerSideIncludes)

mod_info

mod_isapiISAPIExtensionswithinApacheforWindows

mod_ldapLDAPconnectionpoolingandresultcachingservicesforusebyotherLDAPmodules

mod_log_config

mod_log_forensicForensicLoggingoftherequestsmadetotheserver

mod_logio

mod_mem_cacheURI

mod_mime ()(MIME)

mod_mime_magicDeterminestheMIMEtypeofafilebylookingatafewbytesofitscontents

mod_negotiation

mod_nw_sslEnableSSLencryptionforNetWare

mod_proxyHTTP/1.1proxy/gatewayserver

mod_proxy_connectmod_proxyextensionforCONNECTrequesthandling

mod_proxy_ftpFTPsupportmoduleformod_proxy

mod_proxy_httpHTTPsupportmoduleformod_proxy

mod_rewriteProvidesarule-basedrewritingenginetorewriterequestedURLsonthefly

mod_setenvif

mod_so

mod_spelingURL

mod_sslStrongcryptographyusingtheSecureSocketsLayer(SSL)andTransportLayerSecurity(TLS)protocols

mod_status

mod_suexecCGI

mod_unique_id

||FAQ||

mod_userdir

mod_usertrackClickstreamloggingofuseractivityonasite

mod_version

mod_vhost_aliasProvidesfordynamicallyconfiguredmassvirtualhosting

FrequentlyAskedQuestions

ThelatestversionofthisFAQisalwaysavailablefromthemainApachewebsite,at<http://httpd.apache.org/docs/2.0/faq/>.Inaddition,youcanviewthisFAQallinonepageforeasysearchingandprinting.

SinceApache2.0isquitenew,wedon'tyetknowwhattheFrequentlyAskedQuestionswillbe.Whilethissectionfillsup,youshouldalsoconsulttheApache1.3FAQtoseeifyourquestionisansweredthere.

Topics

SupportWhatdoIdowhenIhaveproblems?

ErrorMessagesWhatdoesthiserrormessagemean?

||FAQ||

SiteMap

ApacheHTTP2.0

1.32.0Apache2.0ApacheLicense

ApacheHTTP

ApacheApache

Directory,Location,Files

Apache(MPM)ApacheApache

suEXEC

Apache

VirtualHost

DNSApache

Apache

ApacheSSL/TLS

SSL/TLS:SSL/TLS:SSL/TLS:SSL/TLS:FAQ

CGIServerSideIncludes.htaccess

Apache

MicrosoftWindowsApacheMicrosoftWindowsApacheNovellNetWareApacheHPUXEBCDICApache

ApacheHTTP

:httpd:ab:apachectl:apxs:configure:dbmmanage:htdigest:htpasswd:logresolve:rotatelogs:suexec

Apache

FIN_WAIT_2Apache

Apache

ApacheApache

ApacheApacheMPMApacheMPMbeosApacheMPMleaderApacheMPMnetwareApacheMPMos2ApacheMPMperchildApacheMPMpreforkApacheMPMthreadpoolApacheMPMwinntApacheMPMworker

Apachemod_accessApachemod_actionsApachemod_aliasApachemod_asisApachemod_authApachemod_auth_anonApachemod_auth_dbmApachemod_auth_digestApachemod_auth_ldapApachemod_autoindexApachemod_cacheApachemod_cern_metaApachemod_cgiApachemod_cgidApachemod_charset_liteApachemod_davApachemod_dav_fsApachemod_deflate

Apachemod_dirApachemod_disk_cacheApachemod_dumpioApachemod_echoApachemod_envApachemod_exampleApachemod_expiresApachemod_ext_filterApachemod_file_cacheApachemod_headersApachemod_imapApachemod_includeApachemod_infoApachemod_isapiApachemod_ldapApachemod_log_configApachemod_log_forensicApachemod_logioApachemod_mem_cacheApachemod_mimeApachemod_mime_magicApachemod_negotiationApachemod_nw_sslApachemod_proxyApachemod_proxy_connectApachemod_proxy_ftpApachemod_proxy_httpApachemod_rewriteApachemod_setenvifApachemod_soApachemod_spelingApachemod_sslApachemod_statusApachemod_suexec

Apachemod_unique_idApachemod_userdirApachemod_usertrackApachemod_versionApachemod_vhost_alias

ApacheAPIAPRApache2.0Apache2.0Apache1.3Apache2.0Apache2.0Apache2.0

||FAQ||

ServerandSupportingPrograms

ThispagedocumentsalltheexecutableprogramsincludedwiththeApacheHTTPServer.

Apachehypertexttransferprotocolserver

apachectl

ApacheHTTPservercontrolinterface

ApacheHTTPserverbenchmarkingtool

APacheeXtenSiontool

configure

Configurethesourcetree

dbmmanage

CreateandupdateuserauthenticationfilesinDBMformatforbasicauthentication

htdigest

Createandupdateuserauthenticationfilesfordigestauthentication

ManipulateDBMpassworddatabases.

htpasswd

Createandupdateuserauthenticationfilesforbasicauthentication

logresolve

ResolvehostnamesforIP-addressesinApachelogfiles

rotatelogs

RotateApachelogswithouthavingtokilltheserver

suexec

SwitchUserForExec

OtherPrograms

Supporttoolswithnoownmanualpage.

||FAQ||

ApacheSSL/TLS

ApacheHTTP mod_ssl OpenSSLSecureSocktsLayerTransportLayerSecurityRalfS.Engelschallmod_ssl

Documentation

How-To

||FAQ||

mod_ssl

||FAQ||

Apache

1 (www.company1.comandwww.company2.comIP IPIP

ApacheIP 1.1Apache

Apache1.3

mod_vhost_alias

(IP)IP(IP)

||FAQ||

NameVirtualHost

ServerName

ServerAlias

ServerPath

Apache -S

/usr/local/apache2/bin/httpd-S

Apache IP

DeveloperDocumentationforApache2.0

ManyofthedocumentsontheseDeveloperpagesareliftedfromApache1.3'sdocumentation.WhiletheyareallbeingupdatedtoApache2.0,theyareindifferentstagesofprogress.Pleasebepatient,andpointoutanydiscrepanciesorerrorsonthedeveloper/pagesdirectlytothedev@httpd.apache.orgmailinglist.

Topics

Apache1.3APINotesApache2.0HookFunctionsRequestProcessinginApache2.0HowfiltersworkinApache2.0ConvertingModulesfromApache1.3toApache2.0DebuggingMemoryAllocationinAPRDocumentingApache2.0Apache2.0ThreadSafetyIssues

ExternalResources

ToolsprovidedbyIanHolsman:Apache2crossreferenceAutogeneratedApache2codedocumentation

ModuleDevelopmentTutorialsbyKevinO'DonnellIntegratingamoduleintotheApachebuildsystemHandlingconfigurationdirectives

SomenotesonApachemoduledevelopmentbyRyanBloom

ApacheMiscellaneousDocumentation

BelowisalistofadditionaldocumentationpagesthatapplytotheApachewebserverdevelopmentproject.

Warning

Someofthedocumentsbelowhavenotbeenfullyupdatedtotakeintoaccountchangesmadeinthe2.0versionoftheApacheHTTPServer.Someoftheinformationmaystillberelevant,butpleaseuseitwithcare.

HowtouseXSSIandNegotiationforcustomErrorDocuments

DescribesasolutionwhichusesXSSIandnegotiationtocustom-tailortheApacheErrorDocumentstotaste,addingtheadvantageofreturninginternationalizedversionsoftheerrormessagesdependingontheclient'slanguagepreferences.

FileDescriptoruseinApache

DescribeshowApacheusesfiledescriptorsandtalksaboutvariouslimitsimposedonthenumberofdescriptorsavailablebyvariousoperatingsystems.

FIN_WAIT_2

AdescriptionofthecausesofApacheprocessesgoingintotheFIN_WAIT_2state,andwhatyoucandoaboutit.

KnownClientProblems

AlistofproblemsinHTTPclientswhichcanbemitigatedbyApache.

PerformanceNotes-ApacheTuning

Notesabouthowto(run-timeandcompile-time)configureApacheforhighestperformance.NotesexplainingwhyApachedoessomethings,andwhyitdoesn'tdootherthings(whichmakeitslower/faster).

SecurityTips

Some"do"s-and"don't"s-forkeepingyourApachewebsitesecure.

URLRewritingGuide

Thisdocumentsupplementsthemod_rewritereferencedocumentation.ItdescribeshowonecanuseApache'smod_rewritetosolvetypicalURL-basedproblemswebmastersareusuallyconfrontedwithinpractice.

ApacheTutorials

AlistofexternalresourceswhichhelptoaccomplishcommontaskswiththeApacheHTTPserver.

RelevantStandards

ThisdocumentactsasareferencepageformostoftherelevantstandardsthatApachefollows.

PlatformSpecificNotes

MicrosoftWindows

UsingApacheThisdocumentexplainshowtoinstall,configureandrunApache2.0underMicrosoftWindows.

See:UsingApachewithMicrosoftWindows

CompilingApacheTherearemanyimportantpointsbeforeyoubegincompilingApache.Thisdocumentexplainthem.

See:CompilingApacheforMicrosoftWindows

OtherPlatforms

NovellNetWareThisdocumentexplainshowtoinstall,configureandrunApache2.0underNovellNetWare5.1andabove.

See:UsingApacheWithNovellNetWare

EBCDICVersion1.3oftheApacheHTTPServeristhefirstversionwhichincludesaporttoa(non-ASCII)mainframemachinewhichusestheEBCDICcharactersetasitsnativecodeset.

Warning:Thisdocumenthasnotbeenupdatedtotakeintoaccountchangesmadeinthe2.0versionoftheApacheHTTPServer.Someoftheinformationmaystillberelevant,butpleaseuseitwithcare.

See:TheApacheEBCDICPort

suexec-Switchuserbeforeexecutingexternalprograms

suexecisusedbytheApacheHTTPServertoswitchtoanotheruserbeforeexecutingCGIprograms.Inordertoachievethis,itmustrunasroot.SincetheHTTPdaemonnormallydoesn'trunasroot,thesuexecexecutableneedsthesetuidbitsetandmustbeownedbyroot.Itshouldneverbewritableforanyotherpersonthanroot.

Forfurtherinformationabouttheconceptsandandthesecuritymodelofsuexecpleaserefertothesuexecdocumentation(http://httpd.apache.org/docs/2.0/suexec.html).

Synopsissuexec-V

Options

Ifyouareroot,thisoptiondisplaysthecompileoptionsofsuexec.Forsecurityreasonsallconfigurationoptionsarechangeableonlyatcompiletime.

||FAQ||

How-To/

||FAQ||

How-To/

CGICGI(CommonGatewayInterface) CGI Apache

: CGI:

.htaccess.htaccess

: .htaccess

ServerSideIncludesSSI(ServerSideIncludes)HTMLHTML

: ServerSideIncludes(SSI)

UserDir http://example.com/~username/ " username

UserDir

: ( public_html)

htdbm-ManipulateDBMpassworddatabases

htdbmisusedtomanipulatetheDBMformatfilesusedtostoreusernamesandpasswordforbasicauthenticationofHTTPusersviamod_auth_dbm.SeethedbmmanagedocumentationformoreinformationabouttheseDBMfiles.

Seealsohttpd

dbmmanage

mod_auth_dbm

Synopsishtdbm[-TDBTYPE][-c][-m|-d|-p|-s][

-t][-v][-x]filenameusername

htdbm-b[-TDBTYPE][-c][-m|-d|-p|-s

][-t][-v]filenameusernamepassword

htdbm-n[-c][-m|-d|-p|-s][-t][-v

]username

htdbm-nb[-c][-m|-d|-p|-s][-t][-

v]usernamepassword

htdbm-v[-TDBTYPE][-c][-m|-d|-p|-s

][-t][-v]filenameusername

htdbm-vb[-TDBTYPE][-c][-m|-d|-p|-s

][-t][-v]filenameusernamepassword

htdbm-x[-TDBTYPE][-m|-d|-p|-s]

filenameusername

htdbm-l[-TDBTYPE]

Options

Usebatchmode;i.e.,getthepasswordfromthecommandlineratherthanpromptingforit.Thisoptionshouldbeusedwithextremecare,sincethepasswordisclearlyvisibleonthecommandline.

Createthepasswdfile.Ifpasswdfilealreadyexists,itisrewrittenandtruncated.Thisoptioncannotbecombinedwiththe-noption.

Displaytheresultsonstandardoutputratherthanupdatingadatabase.Thisoptionchangesthesyntaxofthecommandline,sincethepasswdfileargument(usuallythefirstone)isomitted.Itcannotbecombinedwiththe-coption.

UseMD5encryptionforpasswords.OnWindows,NetwareandTPF,thisisthedefault.

Usecrypt()encryptionforpasswords.ThedefaultonallplatformsbutWindows,NetwareandTPF.Thoughpossiblysupportedbyhtdbmonallplatforms,itisnotsupportedbythehttpdserveronWindows,NetwareandTPF.

UseSHAencryptionforpasswords.Facilitatesmigrationfrom/toNetscapeserversusingtheLDAPDirectoryInterchangeFormat(ldif).

Useplaintextpasswords.Thoughhtdbmwillsupportcreationonallplatforms,thehttpddaemonwillonlyacceptplaintextpasswordsonWindows,NetwareandTPF.

Printeachoftheusernamesandcommentsfromthedatabaseonstdout.

Interpretthefinalparameterasacomment.Whenthisoptionisspecified,anadditionalstringcanbeappendedtothecommandline;thisstringwillbestoredinthe"Comment"fieldofthedatabase,associatedwiththespecifiedusername.

Verifytheusernameandpassword.Theprogramwillprintamessageindicatingwhetherthesuppliedpasswordisvalid.Ifthepasswordisinvalid,theprogramexitswitherrorcode3.

Deleteuser.IftheusernameexistsinthespecifiedDBMfile,itwillbedeleted.

filename

ThefilenameoftheDBMformatfile.Usuallywithouttheextension.db,.pag,or.dir.If-cisgiven,theDBMfileiscreatedifitdoesnotalreadyexist,orupdatedifitdoesexist.

username

Theusernametocreateorupdateinpasswdfile.Ifusernamedoesnotexistinthisfile,anentryisadded.Ifitdoesexist,thepasswordischanged.

password

TheplaintextpasswordtobeencryptedandstoredintheDBMfile.Usedonlywiththe-bflag.

-TDBTYPE

TypeofDBMfile(SDBM,GDBM,DB,or"default").

OneshouldbeawarethatthereareanumberofdifferentDBMfileformatsinexistence,andwithalllikelihood,librariesformorethanoneformatmayexistonyoursystem.ThethreeprimaryexamplesareSDBM,NDBM,GNUGDBM,andBerkeley/SleepycatDB2/3/4.Unfortunately,alltheselibrariesusedifferentfileformats,andyoumustmakesurethatthefileformatusedbyfilenameisthesameformatthathtdbmexpectstosee.htdbmcurrentlyhasnowayofdeterminingwhattypeofDBMfileitislookingat.Ifusedagainstthewrongformat,willsimplyreturnnothing,ormaycreateadifferentDBMfilewithadifferentname,oratworst,itmaycorrupttheDBMfileifyouwereattemptingtowritetoit.

OnecanusuallyusethefileprogramsuppliedwithmostUnixsystemstoseewhatformataDBMfileisin.

ExitStatus

htdbmreturnsazerostatus("true")iftheusernameandpasswordhavebeensuccessfullyaddedorupdatedintheDBMFile.htdbmreturns1ifitencounterssomeproblemaccessingfiles,2iftherewasasyntaxproblemwiththecommandline,3ifthepasswordwasenteredinteractivelyandtheverificationentrydidn'tmatch,4ifitsoperationwasinterrupted,5ifavalueistoolong(username,filename,password,orfinalcomputedrecord),6iftheusernamecontainsillegalcharacters(seetheRestrictionssection),and7ifthefileisnotavalidDBMpasswordfile.

Examples

htdbm/usr/local/etc/apache/.htdbm-usersjsmith

Addsormodifiesthepasswordforuserjsmith.Theuserispromptedforthepassword.IfexecutedonaWindowssystem,thepasswordwillbeencryptedusingthemodifiedApacheMD5algorithm;otherwise,thesystem'scrypt()routinewillbeused.Ifthefiledoesnotexist,htdbmwilldonothingexceptreturnanerror.

htdbm-c/home/doe/public_html/.htdbmjane

Createsanewfileandstoresarecordinitforuserjane.Theuserispromptedforthepassword.Ifthefileexistsandcannotberead,orcannotbewritten,itisnotalteredandhtdbmwilldisplayamessageandreturnanerrorstatus.

htdbm-mb/usr/web/.htdbm-alljonesPwd4Steve

Encryptsthepasswordfromthecommandline(Pwd4Steve)usingtheMD5algorithm,andstoresitinthespecifiedfile.

WebpasswordfilessuchasthosemanagedbyhtdbmshouldnotbewithintheWebserver'sURIspace--thatis,theyshouldnotbefetchablewithabrowser.

Theuseofthe-boptionisdiscouraged,sincewhenitisusedtheunencryptedpasswordappearsonthecommandline.

Restrictions

OntheWindowsandMPEplatforms,passwordsencryptedwithhtdbmarelimitedtonomorethan255charactersinlength.Longerpasswordswillbetruncatedto255characters.

TheMD5algorithmusedbyhtdbmisspecifictotheApachesoftware;passwordsencryptedusingitwillnotbeusablewithotherWebservers.

Usernamesarelimitedto255bytesandmaynotincludethecharacter:.

Apachemod_rewrite

``Thegreatthingaboutmod_rewriteisitgivesyoualltheconfigurabilityandflexibilityofSendmail.Thedownsidetomod_rewriteisthatitgivesyoualltheconfigurabilityandflexibilityofSendmail.''

--BrianBehlendorfApacheGroup

``Despitethetonsofexamplesanddocs,mod_rewriteisvoodoo.Damnedcoolvoodoo,butstillvoodoo.''

--BrianMoorebem@news.cmc.net

Welcometomod_rewrite,theSwissArmyKnifeofURLmanipulation!

Thismoduleusesarule-basedrewritingengine(basedonaregular-expressionparser)torewriterequestedURLsonthefly.ItsupportsanunlimitednumberofrulesandanunlimitednumberofattachedruleconditionsforeachruletoprovideareallyflexibleandpowerfulURLmanipulationmechanism.TheURLmanipulationscandependonvarioustests,forinstanceservervariables,environmentvariables,HTTPheaders,timestampsandevenexternaldatabaselookupsinvariousformatscanbeusedtoachievegranularURLmatching.

ThismoduleoperatesonthefullURLs(includingthepath-infopart)bothinper-servercontext(httpd.conf)andper-directorycontext(.htaccess)andcanevengeneratequery-stringpartsonresult.Therewrittenresultcanleadtointernalsub-processing,externalrequestredirectionoreventoaninternalproxythroughput.

Butallthisfunctionalityandflexibilityhasitsdrawback:complexity.Sodon'texpecttounderstandthisentiremoduleinjustoneday.

Documentation

IntroductionTechnicaldetailsPracticalsolutionstocommonproblemsGlossary

mod_rewrite

Extensivedocumentationonthedirectivesprovidedbythismoduleisprovidedinthemod_rewritereferencedocumentation.

URLRewritingGuide

Thisdocumentsupplementsthemod_rewritereferencedocumentation.ItdescribeshowonecanuseApache'smod_rewritetosolvetypicalURL-basedproblemswithwhichwebmastersarecommononyconfronted.WegivedetaileddescriptionsonhowtosolveeachproblembyconfiguringURLrewritingrulesets.

ATTENTION:Dependingonyourserverconfigurationitmaybenecessarytoslightlychangetheexamplesforyoursituation,e.g.addingthe[PT]flagwhenadditionallyusingmod_aliasandmod_userdir,etc.Orrewritingarulesettofitin.htaccesscontextinsteadofper-servercontext.Alwaystrytounderstandwhataparticularrulesetreallydoesbeforeyouuseit.Thisavoidsmanyproblems.

SeealsoModuledocumentationmod_rewriteintroductionTechnicaldetails

CanonicalURLs

Description:OnsomewebserverstherearemorethanoneURLforaresource.UsuallytherearecanonicalURLs(whichshouldbeactuallyusedanddistributed)andthosewhicharejustshortcuts,internalones,etc.IndependentofwhichURLtheusersuppliedwiththerequestheshouldfinallyseethecanonicaloneonly.

Solution:WedoanexternalHTTPredirectforallnon-canonicalURLstofixtheminthelocationviewoftheBrowserandforallsubsequentrequests.Intheexamplerulesetbelowwereplace/~userbythecanonical/u/userandfixamissingtrailingslashfor/u/user.

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

RewriteRule^/([uge])/([^/]+)$/$1/$2/[R]

CanonicalHostnames

Description:Thegoalofthisruleistoforcetheuseofaparticularhostname,inpreferencetootherhostnameswhichmaybeusedtoreachthesamesite.Forexample,ifyouwishtoforcetheuseofwww.example.cominsteadofexample.com,youmightuseavariantofthefollowingrecipe.

Solution:Forsitesrunningonaportotherthan80:

RewriteCond%{HTTP_HOST}!^fully\.qualified\.domain\.name[NC]

RewriteCond%{SERVER_PORT}!^80$

RewriteRule^/(.*)http://fully.qualified.domain.name:%{SERVER_PORT}/$1[L,R]

Andforasiterunningonport80

RewriteCond%{HTTP_HOST}!^fully\.qualified\.domain\.name[NC]

RewriteRule^/(.*)http://fully.qualified.domain.name/$1[L,R]

MovedDocumentRoot

Description:UsuallytheDocumentRootofthewebserverdirectlyrelatestotheURL"/".Butoftenthisdataisnotreallyoftop-levelpriority.Forexample,youmaywishforvisitors,onfirstenteringasite,togotoaparticularsubdirectory/about/.Thismaybeaccomplishedusingthefollowingruleset:

Solution:WeredirecttheURL/to/about/:

RewriteEngineon

RewriteRule^/$/about/[R]

NotethatthiscanalsobehandledusingtheRedirectMatchdirective:

RedirectMatch^/$http://example.com/e/www/

TrailingSlashProblem

Description:Thevastmajorityof"trailingslash"problemscanbedealtwithusingthetechniquesdiscussedintheFAQentry.However,occasionally,thereisaneedtousemod_rewritetohandleacasewhereamissingtrailingslashcausesaURLtofail.Thiscanhappen,forexample,afteraseriesofcomplexrewriterules.

Solution:Thesolutiontothissubtleproblemistolettheserveraddthetrailingslashautomatically.Todothiscorrectlywehavetouseanexternalredirect,sothebrowsercorrectlyrequestssubsequentimagesetc.Ifweonlydidainternalrewrite,thiswouldonlyworkforthedirectorypage,butwouldgowrongwhenanyimagesareincludedintothispagewithrelativeURLs,becausethebrowserwouldrequestanin-linedobject.Forinstance,arequestforimage.gifin/~quux/foo/index.htmlwouldbecome/~quux/image.gifwithouttheexternalredirect!

So,todothistrickwewrite:

RewriteEngineon

RewriteBase/~quux/

RewriteRule^foo$foo/[R]

Alternately,youcanputthefollowinginatop-level.htaccessfileinthecontentdirectory.Butnotethatthiscreatessomeprocessingoverhead.

RewriteEngineon

RewriteBase/~quux/

RewriteCond%{REQUEST_FILENAME}-d

RewriteRule^(.+[^/])$$1/[R]

MoveHomedirstoDifferentWebserver

Description:Manywebmastershaveaskedforasolutiontothefollowingsituation:Theywantedtoredirectjustallhomedirsonawebservertoanotherwebserver.Theyusuallyneedsuchthingswhenestablishinganewerwebserverwhichwillreplacetheoldoneovertime.

Solution:Thesolutionistrivialwithmod_rewrite.Ontheoldwebserverwejustredirectall/~user/anypathURLstohttp://newserver/~user/anypath.

RewriteEngineon

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

Searchpagesinmorethanonedirectory

Description:Sometimesitisnecessarytoletthewebserversearchforpagesinmorethanonedirectory.HereMultiViewsorothertechniquescannothelp.

Solution:Weprogramaexplicitrulesetwhichsearchesforthefilesinthedirectories.

RewriteEngineon

#firsttrytofinditincustom/...

#secondtrytofinditinpub/...

#elsegoonforotherAliasorScriptAliasdirectives,

RewriteRule^(.+)-[PT]

SetEnvironmentVariablesAccordingToURLParts

Description:PerhapsyouwanttokeepstatusinformationbetweenrequestsandusetheURLtoencodeit.Butyoudon'twanttouseaCGIwrapperforallpagesjusttostripoutthisinformation.

Solution:WeusearewriteruletostripoutthestatusinformationandrememberitviaanenvironmentvariablewhichcanbelaterdereferencedfromwithinXSSIorCGI.ThiswayaURL/foo/S=java/bar/getstranslatedto/foo/bar/andtheenvironmentvariablenamedSTATUSissettothevalue"java".

RewriteEngineon

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

VirtualUserHosts

Description:Assumethatyouwanttoprovidewww.username.host.domain.comforthehomepageofusernameviajustDNSArecordstothesamemachineandwithoutanyvirtualhostsonthismachine.

Solution:ForHTTP/1.0requeststhereisnosolution,butforHTTP/1.1requestswhichcontainaHost:HTTPheaderwecanusethefollowingrulesettorewritehttp://www.username.host.com/anypathinternallyto/home/username/anypath:

RewriteEngineon

RewriteCond%{HTTP_HOST}^www\.[^.]+\.host\.com$

RewriteRule^(.+)%{HTTP_HOST}$1[C]

RewriteRule^www\.([^.]+)\.host\.com(.*)/home/$1$2

RedirectHomedirsForForeigners

Description:WewanttoredirecthomedirURLstoanotherwebserverwww.somewhere.comwhentherequestinguserdoesnotstayinthelocaldomainourdomain.com.Thisissometimesusedinvirtualhostcontexts.

Solution:Justarewritecondition:

RewriteEngineon

RewriteCond%{REMOTE_HOST}!^.+\.ourdomain\.com$

RewriteRule^(/~.+)http://www.somewhere.com/$1[R,L]

RedirectingAnchors

Description:Bydefault,redirectingtoanHTMLanchordoesn'twork,becausemod_rewriteescapesthe#character,turningitinto%23.This,inturn,breakstheredirection.

Solution:Usethe[NE]flagontheRewriteRule.NEstandsforNoEscape.

Time-DependentRewriting

Description:Whentricksliketime-dependentcontentshouldhappenalotofwebmastersstilluseCGIscriptswhichdoforinstanceredirectstospecializedpages.Howcanitbedoneviamod_rewrite?

Solution:TherearealotofvariablesnamedTIME_xxxforrewriteconditions.Inconjunctionwiththespeciallexicographiccomparisonpatterns<STRING,>STRINGand=STRINGwecandotime-dependentredirects:

RewriteEngineon

RewriteCond%{TIME_HOUR}%{TIME_MIN}>0700

RewriteCond%{TIME_HOUR}%{TIME_MIN}<1900

RewriteRule^foo\.html$foo.day.html

RewriteRule^foo\.html$foo.night.html

Thisprovidesthecontentoffoo.day.htmlundertheURLfoo.htmlfrom07:00-19:00andattheremainingtimethecontentsoffoo.night.html.Justanicefeatureforahomepage...

BackwardCompatibilityforYYYYtoXXXXmigration

Description:HowcanwemakeURLsbackwardcompatible(stillexistingvirtually)aftermigratingdocument.YYYYtodocument.XXXX,e.g.aftertranslatingabunchof.htmlfilesto.phtml?

Solution:Wejustrewritethenametoitsbasenameandtestforexistenceofthenewextension.Ifitexists,wetakethatname,elsewerewritetheURLtoitsoriginalstate.

#backwardcompatibilityrulesetfor

#rewritingdocument.htmltodocument.phtml

#whenandonlywhendocument.phtmlexists

#butnolongerdocument.html

RewriteEngineon

RewriteBase/~quux/

#parseoutbasename,butrememberthefact

RewriteRule^(.*)\.html$$1[C,E=WasHTML:yes]

#rewritetodocument.phtmlifexists

RewriteCond%{REQUEST_FILENAME}.phtml-f

RewriteRule^(.*)$$1.phtml[S=1]

#elsereversethepreviousbasenamecutout

RewriteCond%{ENV:WasHTML}^yes$

RewriteRule^(.*)$$1.html

ContentHandling

FromOldtoNew(intern)Description:

Assumewehaverecentlyrenamedthepagefoo.htmltobar.htmlandnowwanttoprovidetheoldURLforbackwardcompatibility.ActuallywewantthatusersoftheoldURLevennotrecognizethatthepageswasrenamed.

Solution:WerewritetheoldURLtothenewoneinternallyviathefollowingrule:

RewriteEngineon

RewriteBase/~quux/

RewriteRule^foo\.html$bar.html

FromOldtoNew(extern)Description:

Assumeagainthatwehaverecentlyrenamedthepagefoo.htmltobar.htmlandnowwanttoprovidetheoldURLforbackwardcompatibility.ButthistimewewantthattheusersoftheoldURLgethintedtothenewone,i.e.theirbrowsersLocationfieldshouldchange,too.

Solution:WeforceaHTTPredirecttothenewURLwhichleadstoachangeofthebrowsersandthustheusersview:

RewriteEngineon

RewriteBase/~quux/

RewriteRule^foo\.html$bar.html[R]

FromStatictoDynamicDescription:

Howcanwetransformastaticpagefoo.htmlintoadynamicvariantfoo.cgiinaseamlessway,i.e.withoutnoticebythebrowser/user.

Solution:WejustrewritetheURLtotheCGI-scriptandforcethecorrectMIME-typesoitgetsreallyrunasaCGI-script.Thiswayarequestto/~quux/foo.htmlinternallyleadstotheinvocationof/~quux/foo.cgi.

RewriteEngineon

RewriteBase/~quux/

RewriteRule^foo\.html$foo.cgi[T=application/x-httpd-cgi

AccessRestriction

BlockingofRobotsDescription:

Howcanweblockareallyannoyingrobotfromretrievingpagesofaspecificwebarea?A/robots.txtfilecontainingentriesofthe"RobotExclusionProtocol"istypicallynotenoughtogetridofsucharobot.

Solution:WeusearulesetwhichforbidstheURLsofthewebarea/~quux/foo/arc/(perhapsaverydeepdirectoryindexedareawheretherobottraversalwouldcreatebigserverload).Wehavetomakesurethatweforbidaccessonlytotheparticularrobot,i.e.justforbiddingthehostwheretherobotrunsisnotenough.Thiswouldblockusersfromthishost,too.WeaccomplishthisbyalsomatchingtheUser-AgentHTTPheaderinformation.

RewriteCond%{HTTP_USER_AGENT}^NameOfBadRobot.*

RewriteCond%{REMOTE_ADDR}^123\.45\.67\.[8-9]$

RewriteRule^/~quux/foo/arc/.+-[F]

BlockedInline-ImagesDescription:

Assumewehaveunderhttp://www.quux-corp.de/~quux/somepageswithinlinedGIFgraphics.Thesegraphicsarenice,soothersdirectlyincorporatethemviahyperlinkstotheirpages.Wedon'tlikethispracticebecauseitaddsuselesstraffictoourserver.

Solution:Whilewecannot100%protecttheimagesfrominclusion,we

canatleastrestrictthecaseswherethebrowsersendsaHTTPRefererheader.

RewriteCond%{HTTP_REFERER}!^http://www.quux-corp.de/~quux/.*$[NC]

RewriteRule.*\.gif$-[F]

RewriteCond%{HTTP_REFERER}!.*/foo-with-gif\.html$

RewriteRule^inlined-in-foo\.gif$-[F]

ExternalRewritingEngineDescription:

AFAQ:HowcanwesolvetheFOO/BAR/QUUX/etc.problem?Thereseemsnosolutionbytheuseofmod_rewrite...

Solution:UseanexternalRewriteMap,i.e.aprogramwhichactslikeaRewriteMap.ItisrunonceonstartupofApachereceivestherequestedURLsonSTDINandhastoputtheresulting(usuallyrewritten)URLonSTDOUT(sameorder!).

RewriteEngineon

RewriteMapquux-mapprg:/path/to/map.quux.pl

RewriteRule^/~quux/(.*)$/~quux/${quux-map:$1}

#!/path/to/perl

#disablebufferedI/Owhichwouldlead

#todeadloopsfortheApacheserver

#readURLsoneperlinefromstdinand

#generatesubstitutionURLonstdout

while(<>){

s|^foo/|bar/|;

print$_;

Thisisademonstration-onlyexampleandjustrewritesallURLs/~quux/foo/...to/~quux/bar/....Actuallyyoucanprogramwhateveryoulike.Butnoticethatwhilesuch

mapscanbeusedalsobyanaverageuser,onlythesystemadministratorcandefineit.

URLRewritingGuide-Advancedtopics

Thisdocumentsupplementsthemod_rewritereferencedocumentation.ItdescribeshowonecanuseApache'smod_rewritetosolvetypicalURL-basedproblemswithwhichwebmastersarecommonlyconfronted.WegivedetaileddescriptionsonhowtosolveeachproblembyconfiguringURLrewritingrulesets.

ATTENTION:Dependingonyourserverconfigurationitmaybenecessarytoadjusttheexamplesforyoursituation,e.g.,addingthe[PT]flagifusingmod_aliasandmod_userdir,etc.Orrewritingarulesettoworkin.htaccesscontextinsteadofper-servercontext.Alwaystrytounderstandwhataparticularrulesetreallydoesbeforeyouuseit;thisavoidsmanyproblems.

SeealsoModuledocumentationmod_rewriteintroductionTechnicaldetails

WebClusterwithConsistentURLSpace

Description:WewanttocreateahomogeneousandconsistentURLlayoutacrossallWWWserversonanIntranetwebcluster,i.e.,allURLs(bydefinitionserver-localandthusserver-dependent!)becomeserverindependent!WhatwewantistogivetheWWWnamespaceasingleconsistentlayout:noURLshouldrefertoanyparticulartargetserver.Theclusteritselfshouldconnectusersautomaticallytoaphysicaltargethostasneeded,invisibly.

Solution:First,theknowledgeofthetargetserverscomesfrom(distributed)externalmapswhichcontaininformationonwhereourusers,groups,andentitiesreside.Theyhavetheform:

Weputthemintofilesmap.xxx-to-host.SecondweneedtoinstructallserverstoredirectURLsoftheforms:

/u/user/anypath

/g/group/anypath

/e/entity/anypath

http://physical-host/u/user/anypath

http://physical-host/g/group/anypath

http://physical-host/e/entity/anypath

whenanyURLpathneednotbevalidoneveryserver.Thefollowingrulesetdoesthisforuswiththehelpofthemapfiles(assumingthatserver0isadefaultserverwhichwillbeusedifauserhasnoentryinthemap):

RewriteEngineon

RewriteMapuser-to-hosttxt:/path/to/map.user-to-host

RewriteMapgroup-to-hosttxt:/path/to/map.group-to-host

RewriteMapentity-to-hosttxt:/path/to/map.entity-to-host

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

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

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

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

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

StructuredHomedirs

Description:Somesiteswiththousandsofusersuseastructuredhomedirlayout,i.e.eachhomedirisinasubdirectorywhichbegins(forinstance)withthefirstcharacteroftheusername.So,/~foo/anypathis/home/f/foo/.www/anypathwhile/~bar/anypathis/home/b/bar/.www/anypath.

Solution:WeusethefollowingrulesettoexpandthetildeURLsintotheabovelayout.

RewriteEngineon

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

FilesystemReorganization

Description:Thisreallyisahardcoreexample:akillerapplicationwhichheavilyusesper-directoryRewriteRulestogetasmoothlookandfeelontheWebwhileitsdatastructureisnevertouchedoradjusted.Background:net.swismyarchiveoffreelyavailableUnixsoftwarepackages,whichIstartedtocollectin1992.Itisbothmyhobbyandjobtodothis,becausewhileI'mstudyingcomputerscienceIhavealsoworkedformanyyearsasasystemandnetworkadministratorinmysparetime.EveryweekIneedsomesortofsoftwaresoIcreatedadeephierarchyofdirectorieswhereIstoredthepackages:

drwxrwxr-x2netswusers512Aug318:39Audio/

drwxrwxr-x2netswusers512Jul914:37Benchmark/

drwxrwxr-x12netswusers512Jul900:34Crypto/

drwxrwxr-x5netswusers512Jul900:41Database/

drwxrwxr-x4netswusers512Jul3019:25Dicts/

drwxrwxr-x10netswusers512Jul901:54Graphic/

drwxrwxr-x5netswusers512Jul901:58Hackers/

drwxrwxr-x8netswusers512Jul903:19InfoSys/

drwxrwxr-x3netswusers512Jul903:21Math/

drwxrwxr-x3netswusers512Jul903:24Misc/

drwxrwxr-x9netswusers512Aug116:33Network/

drwxrwxr-x2netswusers512Jul905:53Office/

drwxrwxr-x7netswusers512Jul909:24SoftEng/

drwxrwxr-x7netswusers512Jul912:17System/

drwxrwxr-x12netswusers512Aug320:15Typesetting/

drwxrwxr-x10netswusers512Jul914:08X11/

InJuly1996IdecidedtomakethisarchivepublictotheworldviaaniceWebinterface."Nice"meansthatIwantedtoofferaninterfacewhereyoucanbrowsedirectlythroughthe

archivehierarchy.And"nice"meansthatIdidn'twanttochangeanythinginsidethishierarchy-notevenbyputtingsomeCGIscriptsatthetopofit.Why?BecausetheabovestructureshouldlaterbeaccessibleviaFTPaswell,andIdidn'twantanyWeborCGIstuffmixedinthere.

Solution:Thesolutionhastwoparts:ThefirstisasetofCGIscriptswhichcreateallthepagesatalldirectorylevelson-the-fly.Iputthemunder/e/netsw/.www/asfollows:

-rw-r--r--1netswusers1318Aug118:10.wwwacl

drwxr-xr-x18netswusers512Aug515:51DATA/

-rw-rw-rw-1netswusers372982Aug516:35LOGFILE

-rw-r--r--1netswusers659Aug409:27TODO

-rw-r--r--1netswusers5697Aug118:01netsw-about.html

-rwxr-xr-x1netswusers579Aug210:33netsw-access.pl

-rwxr-xr-x1netswusers1532Aug117:35netsw-changes.cgi

-rwxr-xr-x1netswusers2866Aug514:49netsw-home.cgi

drwxr-xr-x2netswusers512Jul823:47netsw-img/

-rwxr-xr-x1netswusers24050Aug515:49netsw-lsdir.cgi

-rwxr-xr-x1netswusers1589Aug318:43netsw-search.cgi

-rwxr-xr-x1netswusers1885Aug117:41netsw-tree.cgi

-rw-r--r--1netswusers234Jul3016:35netsw-unlimit.lst

TheDATA/subdirectoryholdstheabovedirectorystructure,i.e.therealnet.swstuff,andgetsautomaticallyupdatedviardistfromtimetotime.Thesecondpartoftheproblemremains:howtolinkthesetwostructurestogetherintoonesmooth-lookingURLtree?WewanttohidetheDATA/directoryfromtheuserwhilerunningtheappropriateCGIscriptsforthevariousURLs.Hereisthesolution:firstIputthefollowingintotheper-directoryconfigurationfileintheDocumentRootoftheservertorewritethepublicURLpath

/net.sw/totheinternalpath/e/netsw:

RewriteRule^net.sw$net.sw/[R]

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

Thefirstruleisforrequestswhichmissthetrailingslash!Thesecondruledoestherealthing.Andthencomesthekillerconfigurationwhichstaysintheper-directoryconfigfile/e/netsw/.www/.wwwacl:

OptionsExecCGIFollowSymLinksIncludesMultiViews

RewriteEngineon

#wearereachedvia/net.sw/prefix

RewriteBase/net.sw/

#firstwerewritetherootdirto

#thehandlingcgiscript

RewriteRule^$netsw-home.cgi[L]

RewriteRule^index\.html$netsw-home.cgi[L]

#stripoutthesubdirswhen

#thebrowserrequestsusfromperdirpages

RewriteRule^.+/(netsw-[^/]+/.+)$$1[L]

#andnowbreaktherewritingforlocalfiles

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]

#anythingelseisasubdirwhichgetshandled

#byanothercgiscript

RewriteRule!^netsw-lsdir\.cgi.*-[C]

RewriteRule(.*)netsw-lsdir.cgi/$1

Somehintsforinterpretation:

1. NoticetheL(last)flagandnosubstitutionfield('-')inthefourthpart

2. Noticethe!(not)characterandtheC(chain)flagatthefirstruleinthelastpart

3. Noticethecatch-allpatterninthelastrule

RedirectFailingURLstoAnotherWebServer

Description:AtypicalFAQaboutURLrewritingishowtoredirectfailingrequestsonwebserverAtowebserverB.UsuallythisisdoneviaErrorDocumentCGIscriptsinPerl,butthereisalsoamod_rewritesolution.ButnotethatthisperformsmorepoorlythanusinganErrorDocumentCGIscript!

Solution:Thefirstsolutionhasthebestperformancebutlessflexibility,andislesssafe:

RewriteEngineon

RewriteCond/your/docroot/%{REQUEST_FILENAME}!-f

RewriteRule^(.+)http://webserverB

TheproblemhereisthatthiswillonlyworkforpagesinsidetheDocumentRoot.WhileyoucanaddmoreConditions(forinstancetoalsohandlehomedirs,etc.)thereisabettervariant:

RewriteEngineon

RewriteCond%{REQUEST_URI}!-U

RewriteRule^(.+)http://webserverB.dom/$1

ThisusestheURLlook-aheadfeatureofmod_rewrite.TheresultisthatthiswillworkforalltypesofURLsandissafe.Butitdoeshaveaperformanceimpactonthewebserver,becauseforeveryrequestthereisonemoreinternalsubrequest.So,ifyourwebserverrunsonapowerfulCPU,usethisone.Ifitisaslowmachine,usethefirstapproachorbetteranErrorDocumentCGIscript.

ArchiveAccessMultiplexer

Description:DoyouknowthegreatCPAN(ComprehensivePerlArchiveNetwork)underhttp://www.perl.com/CPAN?CPANautomaticallyredirectsbrowserstooneofmanyFTPserversaroundtheworld(generallyoneneartherequestingclient);eachservercarriesafullCPANmirror.ThisiseffectivelyanFTPaccessmultiplexingservice.CPANrunsviaCGIscripts,buthowcouldasimilarapproachbeimplementedviamod_rewrite?

Solution:Firstwenoticethatasofversion3.0.0,mod_rewritecanalsousethe"ftp:"schemeonredirects.Andsecond,thelocationapproximationcanbedonebyaRewriteMapoverthetop-leveldomainoftheclient.Withatrickychainedrulesetwecanusethistop-leveldomainasakeytoourmultiplexingmap.

RewriteEngineon

RewriteMapmultiplextxt:/path/to/map.cxan

RewriteRule^/CxAN/(.*)%{REMOTE_HOST}::$1[C]

RewriteRule^.+\.([a-zA-Z]+)::(.*)$${multiplex:$1|ftp.default.dom}$2[R,L]

##map.cxan--MultiplexingMapforCxAN

deftp://ftp.cxan.de/CxAN/

ukftp://ftp.cxan.uk/CxAN/

comftp://ftp.cxan.com/CxAN/

##EOF##

ContentHandling

BrowserDependentContentDescription:

Atleastforimportanttop-levelpagesitissometimesnecessarytoprovidetheoptimumofbrowserdependentcontent,i.e.,onehastoprovideoneversionforcurrentbrowsers,adifferentversionfortheLynxandtext-modebrowsers,andanotherforotherbrowsers.

Solution:Wecannotusecontentnegotiationbecausethebrowsersdonotprovidetheirtypeinthatform.InsteadwehavetoactontheHTTPheader"User-Agent".Thefollowingconfigdoesthefollowing:IftheHTTPheader"User-Agent"beginswith"Mozilla/3",thepagefoo.htmlisrewrittentofoo.NS.htmlandtherewritingstops.Ifthebrowseris"Lynx"or"Mozilla"ofversion1or2,theURLbecomesfoo.20.html.Allotherbrowsersreceivepagefoo.32.html.Thisisdonewiththefollowingruleset:

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]

DynamicMirrorDescription:

Assumetherearenicewebpagesonremotehostswewant

tobringintoournamespace.ForFTPserverswewouldusethemirrorprogramwhichactuallymaintainsanexplicitup-to-datecopyoftheremotedataonthelocalmachine.ForawebserverwecouldusetheprogramwebcopywhichrunsviaHTTP.Butbothtechniqueshaveamajordrawback:Thelocalcopyisalwaysonlyasup-to-dateasthelasttimewerantheprogram.Itwouldbemuchbetterifthemirrorwasnotastaticonewehavetoestablishexplicitly.Insteadwewantadynamicmirrorwithdatawhichgetsupdatedautomaticallyasneededontheremotehost(s).

RewriteEngineon

RewriteBase/~quux/

RewriteRule^hotsheet/(.*)$http://www.tstimpreso.com/hotsheet/

RewriteEngineon

RewriteBase/~quux/

RewriteRule^usa-news\.html$http://www.quux-corp.com/news/index.html

ReverseDynamicMirrorDescription:

Solution:

RewriteEngineon

RewriteCond/mirror/of/remotesite/$1-U

RewriteRule^http://www\.remotesite\.com/(.*)$/mirror/of/remotesite/$1

RetrieveMissingDatafromIntranetDescription:

Thisisatrickywayofvirtuallyrunningacorporate(external)Internetwebserver(www.quux-corp.dom),whileactuallykeepingandmaintainingitsdataonan(internal)Intranetwebserver(www2.quux-corp.dom)whichisprotectedbyafirewall.Thetrickisthattheexternalwebserverretrievestherequesteddataon-the-flyfromtheinternalone.

Solution:First,wemustmakesurethatourfirewallstillprotectstheinternalwebserverandonlytheexternalwebserverisallowedtoretrievedatafromit.Onapacket-filteringfirewall,forinstance,wecouldconfigureafirewallrulesetlikethefollowing:

ALLOWHostwww.quux-corp.domPort>1024-->Hostwww2.quux-corp.domPort

DENYHost*Port*-->Hostwww2.quux-corp.domPort

Justadjustittoyouractualconfigurationsyntax.Nowwecanestablishthemod_rewriteruleswhichrequestthemissingdatainthebackgroundthroughtheproxythroughputfeature:

RewriteRule^/~([^/]+)/?(.*)/home/$1/.www/$2

RewriteCond%{REQUEST_FILENAME}!-f

RewriteCond%{REQUEST_FILENAME}!-d

RewriteRule^/home/([^/]+)/.www/?(.*)http://www2.quux-corp.dom/~$1/pub/$2[

LoadBalancingDescription:

Supposewewanttoloadbalancethetraffictowww.foo.comoverwww[0-5].foo.com(atotalof6servers).Howcanthis

bedone?

Solution:Therearemanypossiblesolutionsforthisproblem.WewillfirstdiscussacommonDNS-basedmethod,andthenonebasedonmod_rewrite:

1. DNSRound-RobinThesimplestmethodforload-balancingistouseDNSround-robin.Hereyoujustconfigurewww[0-9].foo.comasusualinyourDNSwithA(address)records,e.g.,

www0INA1.2.3.1

www1INA1.2.3.2

www2INA1.2.3.3

www3INA1.2.3.4

www4INA1.2.3.5

www5INA1.2.3.6

Thenyouadditionallyaddthefollowingentries:

wwwINA1.2.3.1

wwwINA1.2.3.2

wwwINA1.2.3.3

wwwINA1.2.3.4

wwwINA1.2.3.5

Nowwhenwww.foo.comgetsresolved,BINDgivesoutwww0-www5-butinapermutated(rotated)ordereverytime.Thiswaytheclientsarespreadoverthevariousservers.Butnoticethatthisisnotaperfectloadbalancingscheme,becauseDNSresolutionsarecachedbyclientsandothernameservers,soonceaclienthas

resolvedwww.foo.comtoaparticularwwwN.foo.com,allitssubsequentrequestswillcontinuetogotothesameIP(andthusasingleserver),ratherthanbeingdistributedacrosstheotheravailableservers.Buttheoverallresultisokaybecausetherequestsarecollectivelyspreadoverthevariouswebservers.

2. DNSLoad-BalancingAsophisticatedDNS-basedmethodforload-balancingistousetheprogramlbnamedwhichcanbefoundathttp://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.htmlItisaPerl5programwhich,inconjunctionwithauxilliarytools,providesrealload-balancingviaDNS.

3. ProxyThroughputRound-RobinInthisvariantweusemod_rewriteanditsproxythroughputfeature.Firstwededicatewww0.foo.comtobeactuallywww.foo.combyusingasingle

entryintheDNS.Thenweconvertwww0.foo.comtoaproxy-onlyserver,i.e.,weconfigurethismachinesoallarrivingURLsaresimplypassedthroughitsinternalproxytooneofthe5otherservers(www1-www5).Toaccomplishthiswefirstestablisharulesetwhichcontactsaloadbalancingscriptlb.plforallURLs.

RewriteEngineon

RewriteMaplbprg:/path/to/lb.pl

RewriteRule^/(.+)$${lb:$1}[P,L]

Thenwewritelb.pl:

#!/path/to/perl

##lb.pl--loadbalancingscript

$name="www";#thehostnamebase

$first=1;#thefirstserver(not0here,because0ismyself)

$last=5;#thelastserverintheround-robin

$domain="foo.dom";#thedomainname

$cnt=0;

while(<STDIN>){

$cnt=(($cnt+1)%($last+1-$first));

$server=sprintf("%s%d.%s",$name,$cnt+$first,$domain);

print"http://$server/$_";

##EOF##

Alastnotice:Whyisthisuseful?Seemslikewww0.foo.comstillisoverloaded?Theanswerisyes,itisoverloaded,butwithplainproxythroughputrequests,only!AllSSI,CGI,ePerl,etc.processingishandleddoneontheothermachines.Foracomplicatedsite,thismayworkwell.Thebiggestriskhereisthatwww0isnowasinglepointoffailure--ifitcrashes,theotherserversareinaccessible.

4. DedicatedLoadBalancersTherearemoresophisticatedsolutions,aswell.Cisco,F5,andseveralothercompaniessellhardwareload

balancers(typicallyusedinpairsforredundancy),whichoffersophisticatedloadbalancingandauto-failoverfeatures.Therearesoftwarepackageswhichoffersimilarfeaturesoncommodityhardware,aswell.Ifyouhaveenoughmoneyorneed,checktheseout.Thelb-lmailinglistisagoodplacetoresearch.

NewMIME-type,NewServiceDescription:

OnthenettherearemanyniftyCGIprograms.Buttheirusageisusuallyboring,soalotofwebmastersdon'tusethem.EvenApache'sActionhandlerfeatureforMIME-typesisonlyappropriatewhentheCGIprogramsdon'tneedspecialURLs(actuallyPATH_INFOandQUERY_STRINGS)astheirinput.First,letusconfigureanewfiletypewithextension.scgi(forsecureCGI)whichwillbeprocessedbythepopularcgiwrapprogram.TheproblemhereisthatforinstanceifweuseaHomogeneousURLLayout(seeabove)afileinsidetheuserhomedirsmighthaveaURLlike/u/user/foo/bar.scgi,butcgiwrapneedsURLsintheform/~user/foo/bar.scgi/.Thefollowingrulesolvestheproblem:

RewriteRule^/[uge]/([^/]+)/\.www/(.+)\.scgi(.*)...

.../internal/cgi/user/cgiwrap/~$1/$2.scgi$3[NS,T=application/x-http-cgi

Orassumewehavesomemoreniftyprograms:wwwlog(whichdisplaystheaccess.logforaURLsubtree)andwwwidx(whichrunsGlimpseonaURLsubtree).WehavetoprovidetheURLareatotheseprogramssotheyknowwhichareatheyarereallyworkingwith.Butusuallythisiscomplicated,becausetheymaystillberequestedbythealternateURLform,i.e.,typicallywewouldruntheswwidx

programfromwithin/u/user/foo/viahyperlinkto

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

whichisugly,becausewehavetohard-codeboththelocationoftheareaandthelocationoftheCGIinsidethehyperlink.Whenwehavetoreorganize,wespendalotoftimechangingthevarioushyperlinks.

Solution:ThesolutionhereistoprovideaspecialnewURLformatwhichautomaticallyleadstotheproperCGIinvocation.Weconfigurethefollowing:

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

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

Nowthehyperlinktosearchat/u/user/foo/readsonly

HREF="*"

whichinternallygetsautomaticallytransformedto

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

ThesameapproachleadstoaninvocationfortheaccesslogCGIprogramwhenthehyperlink:loggetsused.

On-the-flyContent-RegenerationDescription:

Herecomesareallyesotericfeature:Dynamicallygeneratedbutstaticallyservedpages,i.e.,pagesshouldbedeliveredas

purestaticpages(readfromthefilesystemandjustpassedthrough),buttheyhavetobegenerateddynamicallybythewebserverifmissing.ThiswayyoucanhaveCGI-generatedpageswhicharestaticallyservedunlessanadmin(oracronjob)removesthestaticcontents.Thenthecontentsgetsrefreshed.

Solution:Thisisdoneviathefollowingruleset:

RewriteCond%{REQUEST_FILENAME}!-s

RewriteRule^page\.html$page.cgi[T=application/x-httpd-cgi,L]

Herearequestforpage.htmlleadstoaninternalrunofacorrespondingpage.cgiifpage.htmlismissingorhasfilesizenull.Thetrickhereisthatpage.cgiisaCGIscriptwhich(additionallytoitsSTDOUT)writesitsoutputtothefilepage.html.Onceithascompleted,theserversendsoutpage.html.Whenthewebmasterwantstoforcearefreshofthecontents,hejustremovespage.html(typicallyfromcron).

DocumentWithAutorefreshDescription:

Wouldn'titbenice,whilecreatingacomplexwebpage,ifthewebbrowserwouldautomaticallyrefreshthepageeverytimewesaveanewversionfromwithinoureditor?Impossible?

Solution:No!WejustcombinetheMIMEmultipartfeature,thewebserverNPHfeature,andtheURLmanipulationpowerofmod_rewrite.First,weestablishanewURLfeature:Addingjust:refreshtoanyURLcausesthe'page'toberefreshed

everytimeitisupdatedonthefilesystem.

RewriteRule^(/[uge]/[^/]+/?.*):refresh/internal/cgi/apache/nph-refresh?f=$1

NowwhenwereferencetheURL

/u/foo/bar/page.html:refresh

thisleadstotheinternalinvocationoftheURL

/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html

TheonlymissingpartistheNPH-CGIscript.Althoughonewouldusuallysay"leftasanexercisetothereader";-)Iwillprovidethis,too.

#!/sw/bin/perl

##nph-refresh--NPH/CGIscriptforautorefreshingpages

#splittheQUERY_STRINGvariable

@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=1if($QS_seq'');

$QS_n=3600if($QS_neq'');

if($QS_feq''){

print"<b>ERROR</b>:Nofilegiven\n";

exit(0);

if(!-f$QS_f){

print"<b>ERROR</b>:File$QS_fnotfound\n";

exit(0);

subprint_http_headers_multipart_begin{

$bound="ThisRandomString12345";

print"Content-type:multipart/x-mixed-replace;boundary=$bound\n";

subprint_http_headers_multipart_next{

print"\n--$bound\n";

subprint_http_headers_multipart_end{

print"\n--$bound--\n";

subdisplayhtml{

local($buffer)=@_;

$len=length($buffer);

print"Content-length:$len\n\n";

print$buffer;

subreadfile{

local($file)=@_;

local(*FP,$size,$buffer,$bytes);

($x,$x,$x,$x,$x,$x,$x,$size)=stat($file);

$size=sprintf("%d",$size);

open(FP,"<$file");

$bytes=sysread(FP,$buffer,$size);

close(FP);

return$buffer;

&print_http_headers_multipart_begin;

submystat{

local($file)=$_[0];

local($time);

($x,$x,$x,$x,$x,$x,$x,$x,$x,$mtime)=stat($file);

return$mtime;

$mtime=$mtime;

for($n=0;$n<$QS_n;$n++){

while(1){

$mtime=&mystat($QS_f);

if($mtimene$mtimeL){

$mtimeL=$mtime;

sleep(2);

sleep(5);

sleep($QS_s);

&print_http_headers_multipart_end;

exit(0);

##EOF##

MassVirtualHostingDescription:

The<VirtualHost>featureofApacheisniceandworksgreatwhenyoujusthaveafewdozenvirtualhosts.ButwhenyouareanISPandhavehundredsofvirtualhosts,thisfeatureissuboptimal.

Solution:ToprovidethisfeaturewemaptheremotewebpageoreventhecompleteremotewebareatoournamespaceusingtheProxyThroughputfeature(flag[P]):

##vhost.map

www.vhostN.dom:80/path/to/docroot/vhostN

##httpd.conf

#usethecanonicalhostnameonredirects,etc.

UseCanonicalNameon

#addthevirtualhostinfrontoftheCLF-format

CustomLog/path/to/access_log"%{VHOST}e%h%l%u%t\"%r\"%>s%b"

#enabletherewritingengineinthemainserver

RewriteEngineon

#definetwomaps:oneforfixingtheURLandonewhichdefines

#theavailablevirtualhostswiththeircorresponding

#DocumentRoot.

RewriteMapvhosttxt:/path/to/vhost.map

#Nowdotheactualvirtualhostmapping

#viaahugeandcomplicatedsinglerule:

#1.makesurewedon'tmapforcommonlocations

RewriteCond%{REQUEST_URI}!^/commonurlN/.*

#2.makesurewehaveaHostheader,because

#currentlyourapproachonlysupports

#virtualhostingthroughthisheader

#3.lowercasethehostname

RewriteCond${lowercase:%{HTTP_HOST}|NONE}^(.+)$

#4.lookupthishostnameinvhost.mapand

#rememberitonlywhenitisapath

#(andnot"NONE"fromabove)

#5.finallywecanmaptheURLtoitsdocrootlocation

#andrememberthevirtualhostforloggingpurposes

RewriteRule^/(.*)$%1/$1[E=VHOST:${lowercase:%{HTTP_HOST}}]

AccessRestriction

HostDenyDescription:

Howcanweforbidalistofexternallyconfiguredhostsfromusingourserver?

Solution:ForApache>=1.3b6:

RewriteEngineon

RewriteCond${hosts-deny:%{REMOTE_HOST}|NOT-FOUND}!=NOT-FOUND[OR]

RewriteCond${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND}!=NOT-FOUND

RewriteRule^/.*-[F]

ForApache<=1.3b6:

RewriteEngineon

RewriteRule^/(.*)$${hosts-deny:%{REMOTE_HOST}|NOT-FOUND}/$1

RewriteRule^NOT-FOUND/(.*)$${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND}/$1

RewriteRule^NOT-FOUND/(.*)$/$1

##hosts.deny

##ATTENTION!Thisisamap,notalist,evenwhenwetreatitassuch.

##mod_rewriteparsesitforkey/valuepairs,soatleasta

##dummyvalue"-"mustbepresentforeachentry.

193.102.180.41-

bsdti1.sdm.de-

192.76.162.40-

SpecialAuthenticationVariantDescription:

Sometimesveryspecialauthenticationisneeded,forinstanceauthenticationwhichchecksforasetofexplicitlyconfiguredusers.Onlytheseshouldreceiveaccessandwithoutexplicitprompting(whichwouldoccurwhenusingBasicAuthviamod_auth).

Solution:Weusealistofrewriteconditionstoexcludeallexceptourfriends:

RewriteRule^/~quux/only-for-friends/-[F]

Referer-basedDeflectorDescription:

HowcanweprogramaflexibleURLDeflectorwhichactsonthe"Referer"HTTPheaderandcanbeconfiguredwithasmanyreferringpagesaswelike?

Solution:Usethefollowingreallytrickyruleset...

RewriteMapdeflectortxt:/path/to/deflector.map

RewriteCond${deflector:%{HTTP_REFERER}}^-$

RewriteRule^.*%{HTTP_REFERER}[R,L]

RewriteCond${deflector:%{HTTP_REFERER}|NOT-FOUND}!=NOT-FOUND

RewriteRule^.*${deflector:%{HTTP_REFERER}}[R,L]

...inconjunctionwithacorrespondingrewritemap:

##deflector.map

http://www.badguys.com/bad/index.html-

http://www.badguys.com/bad/index2.html-

http://www.badguys.com/bad/index3.htmlhttp://somewhere.com/

Thisautomaticallyredirectstherequestbacktothereferringpage(when"-"isusedasthevalueinthemap)ortoaspecificURL(whenanURLisspecifiedinthemapasthesecondargument).

Apachemod_rewriteTechnicalDetails

Thisdocumentdiscussessomeofthetechnicaldetailsofmod_rewriteandURLmatching.

SeealsoModuledocumentationmod_rewriteintroductionPracticalsolutionstocommonproblems

InternalProcessing

Theinternalprocessingofthismoduleisverycomplexbutneedstobeexplainedonceeventotheaverageusertoavoidcommonmistakesandtoletyouexploititsfullfunctionality.

APIPhases

FirstyouhavetounderstandthatwhenApacheprocessesaHTTPrequestitdoesthisinphases.AhookforeachofthesephasesisprovidedbytheApacheAPI.Mod_rewriteusestwoofthesehooks:theURL-to-filenametranslationhookwhichisusedaftertheHTTPrequesthasbeenreadbutbeforeanyauthorizationstartsandtheFixuphookwhichistriggeredaftertheauthorizationphasesandaftertheper-directoryconfigfiles(.htaccess)havebeenread,butbeforethecontenthandlerisactivated.

So,afterarequestcomesinandApachehasdeterminedthecorrespondingserver(orvirtualserver)therewritingenginestartsprocessingofallmod_rewritedirectivesfromtheper-serverconfigurationintheURL-to-filenamephase.Afewstepslaterwhenthefinaldatadirectoriesarefound,theper-directoryconfigurationdirectivesofmod_rewritearetriggeredintheFixupphase.Inbothsituationsmod_rewriterewritesURLseithertonewURLsortofilenames,althoughthereisnoobviousdistinctionbetweenthem.ThisisausageoftheAPIwhichwasnotintendedtobethiswaywhentheAPIwasdesigned,butasofApache1.xthisistheonlywaymod_rewritecanoperate.Tomakethispointmoreclearrememberthefollowingtwopoints:

1. Althoughmod_rewriterewritesURLstoURLs,URLstofilenamesandevenfilenamestofilenames,theAPIcurrentlyprovidesonlyaURL-to-filenamehook.InApache2.0thetwomissinghookswillbeaddedtomaketheprocessingmoreclear.Butthispointhasnodrawbacksfortheuser,itisjustafactwhichshouldberemembered:ApachedoesmoreintheURL-to-filenamehookthantheAPIintendsforit.

2. Unbelievablymod_rewriteprovidesURLmanipulationsinper-directorycontext,i.e.,within.htaccessfiles,althoughthesearereachedaverylongtimeaftertheURLshavebeentranslatedtofilenames.Ithastobethiswaybecause

.htaccessfilesliveinthefilesystem,soprocessinghasalreadyreachedthisstage.Inotherwords:AccordingtotheAPIphasesatthistimeitistoolateforanyURLmanipulations.Toovercomethischickenandeggproblemmod_rewriteusesatrick:WhenyoumanipulateaURL/filenameinper-directorycontextmod_rewritefirstrewritesthefilenamebacktoitscorrespondingURL(whichisusuallyimpossible,butseetheRewriteBasedirectivebelowforthetricktoachievethis)andtheninitiatesanewinternalsub-requestwiththenewURL.ThisrestartsprocessingoftheAPIphases.Againmod_rewritetrieshardtomakethiscomplicatedsteptotallytransparenttotheuser,butyoushouldrememberhere:WhileURLmanipulationsinper-servercontextarereallyfastandefficient,per-directoryrewritesareslowandinefficientduetothischickenandeggproblem.Butontheotherhandthisistheonlywaymod_rewritecanprovide(locallyrestricted)URLmanipulationstotheaverageuser.

Don'tforgetthesetwopoints!

RulesetProcessing

Nowwhenmod_rewriteistriggeredinthesetwoAPIphases,itreadstheconfiguredrulesetsfromitsconfigurationstructure(whichitselfwaseithercreatedonstartupforper-servercontextorduringthedirectorywalkoftheApachekernelforper-directorycontext).ThentheURLrewritingengineisstartedwiththecontainedruleset(oneormorerulestogetherwiththeirconditions).TheoperationoftheURLrewritingengineitselfisexactlythesameforbothconfigurationcontexts.Onlythefinalresultprocessingisdifferent.

Theorderofrulesintherulesetisimportantbecausetherewritingengineprocessestheminaspecial(andnotveryobvious)order.Theruleisthis:Therewritingengineloopsthroughtherulesetrulebyrule(RewriteRuledirectives)andwhenaparticularrulematchesitoptionallyloopsthroughexistingcorrespondingconditions(RewriteConddirectives).Forhistoricalreasonstheconditionsaregivenfirst,andsothecontrolflowisalittlebitlong-winded.SeeFigure1formoredetails.

Figure1:Thecontrolflowthroughtherewritingruleset

Asyoucansee,firsttheURLismatchedagainstthePatternofeachrule.Whenitfailsmod_rewriteimmediatelystopsprocessingthisruleandcontinueswiththenextrule.IfthePatternmatches,mod_rewritelooksforcorrespondingruleconditions.Ifnonearepresent,itjustsubstitutestheURLwithanewvaluewhichisconstructedfromthestringSubstitutionandgoesonwithitsrule-looping.Butifconditionsexist,itstartsaninnerloopforprocessingthemintheorderthattheyarelisted.Forconditionsthelogicisdifferent:wedon'tmatchapatternagainstthecurrentURL.InsteadwefirstcreateastringTestStringbyexpandingvariables,back-references,maplookups,etc.andthenwetrytomatchCondPatternagainstit.Ifthepatterndoesn'tmatch,thecompletesetofconditionsandthecorrespondingrulefails.Ifthepatternmatches,thenthenextconditionisprocesseduntilnomoreconditionsareavailable.Ifallconditionsmatch,processingiscontinuedwiththesubstitutionoftheURLwithSubstitution.

FrequentlyAskedQuestions

ThelatestversionofthisFAQisalwaysavailablefromthemainApachewebsite,at<http://httpd.apache.org/docs/2.0/faq/>.

SinceApache2.0isquitenew,wedon'tyetknowwhattheFrequentlyAskedQuestionswillbe.Whilethissectionfillsup,youshouldalsoconsulttheApache1.3FAQtoseeifyourquestionisansweredthere.

Topics

SupportWhatdoIdowhenIhaveproblems?

ErrorMessagesWhatdoesthiserrormessagemean?

Support

"Whycan'tI...?Whywon't...work?"WhattodoincaseofproblemsWhomdoIcontactforsupport?

"Whycan'tI...?Whywon't...work?"WhattodoincaseofproblemsIfyouarehavingtroublewithyourApacheserversoftware,youshouldtakethefollowingsteps:

Checktheerrorlog!Apachetriestobehelpfulwhenitencountersaproblem.Inmanycases,itwillprovidesomedetailsbywritingoneormessagestotheservererrorlog.Sometimesthisisenoughforyoutodiagnose&fixtheproblemyourself(suchasfilepermissionsorthelike).Thedefaultlocationoftheerrorlogis/usr/local/apache2/logs/error_log,butseetheErrorLogdirectiveinyourconfigfilesforthelocationonyourserver.

ChecktheFAQ!ThelatestversionoftheApacheFrequently-AskedQuestionslistcanalwaysbefoundatthemainApachewebsite.

ChecktheApachebugdatabaseMostproblemsthatgetreportedtoTheApacheGrouparerecordedinthebugdatabase.Pleasechecktheexistingreports,openandclosed,beforeaddingone.Ifyoufindthatyourissuehasalreadybeenreported,pleasedon'tadda"me,too"report.Iftheoriginalreportisn'tclosedyet,wesuggestthatyoucheckitperiodically.Youmightalsoconsidercontactingtheoriginalsubmitter,becausetheremaybeanemailexchangegoingonabouttheissuethatisn'tgettingrecordedinthedatabase.

AskinausersupportforumApachehasanactivecommunityofuserswhoarewillingtosharetheirknowledge.Participatinginthiscommunityisusuallythebestandfastestwaytogetanswerstoyourquestionsandproblems.

Usersmailinglist

#httpdonFreenodeIRCisavailableforusersupportissues.

USENETnewsgroups:

comp.infosystems.www.servers.unix[news][google]comp.infosystems.www.servers.ms-windows[news][google]comp.infosystems.www.authoring.cgi[news][google]

Ifallelsefails,reporttheprobleminthebugdatabaseIfyou'vegonethroughthosestepsabovethatareappropriateandhaveobtainednorelief,thenpleasedoletthehttpddevelopersknowabouttheproblembyloggingabugreport.

Ifyourprobleminvolvestheservercrashingandgeneratingacoredump,pleaseincludeabacktrace(ifpossible).Asanexample,

#cdServerRoot

#dbxhttpdcore

(dbx)where

(SubstitutetheappropriatelocationsforyourServerRootandyourhttpdandcorefiles.Youmayhavetousegdbinsteadofdbx.)

WhomdoIcontactforsupport?

Withseveralmillionusersandfewerthanfortyvolunteerdevelopers,wecannotprovidepersonalsupportforApache.Forfreesupport,wesuggestparticipatinginauserforum.

ErrorMessages

Invalidargument:core_output_filter:writingdatatothenetworkAcceptExfailedPrematureendofscriptheaders

Invalidargument:core_output_filter:writingdatatothenetworkApacheusesthesendfilesyscallonplatformswhereitisavailableinordertospeedsendingofresponses.Unfortunately,onsomesystems,Apachewilldetectthepresenceofsendfileatcompile-time,evenwhenitdoesnotworkproperly.Thishappensmostfrequentlywhenusingnetworkorothernon-standardfile-system.

Symptomsofthisproblemincludetheabovemessageintheerrorlogandzero-lengthresponsestonon-zero-sizedfiles.Theproblemgenerallyoccursonlyforstaticfiles,sincedynamiccontentusuallydoesnotmakeuseofsendfile.

Tofixthisproblem,simplyusetheEnableSendfiledirectivetodisablesendfileforallorpartofyourserver.AlsoseetheEnableMMAP,whichcanhelpwithsimilarproblems.

AcceptExFailedIfyougeterrormessagesrelatedtotheAcceptExsyscallonwin32,seetheWin32DisableAcceptExdirective.

PrematureendofscriptheadersMostproblemswithCGIscriptsresultinthismessagewrittenintheerrorlogtogetherwithanInternalServerErrordeliveredtothebrowser.Aguidetohelpingdebugthistypeof

problemisavailableintheCGItutorial.

Apache2.0ThreadSafetyIssues

WhenusinganyofthethreadedmpmsinApache2.0itisimportantthateveryfunctioncalledfromApachebethreadsafe.Whenlinkingin3rdpartyextensionsitcanbedifficulttodeterminewhethertheresultingserverwillbethreadsafe.Casualtestinggenerallywon'ttellyouthiseitherasthreadsafetyproblemscanleadtosubtleraceconditonsthatmayonlyshowupincertainconditionsunderheavyload.

Globalandstaticvariables

Whenwritingyourmoduleorwhentryingtodetermineifamoduleor3rdpartylibraryisthreadsafetherearesomecommonthingstokeepinmind.

First,youneedtorecognizethatinathreadedmodeleachindividualthreadhasitsownprogramcounter,stackandregisters.Localvariablesliveonthestack,sothosearefine.Youneedtowatchoutforanystaticorglobalvariables.Thisdoesn'tmeanthatyouareabsolutelynotallowedtousestaticorglobalvariables.Therearetimeswhenyouactuallywantsomethingtoaffectallthreads,butgenerallyyouneedtoavoidusingthemifyouwantyourcodetobethreadsafe.

Inthecasewhereyouhaveaglobalvariablethatneedstobeglobalandaccessedbyallthreads,beverycarefulwhenyouupdateit.If,forexample,itisanincrementingcounter,youneedtoatomicallyincrementittoavoidraceconditionswithotherthreads.Youdothisusingamutex(mutualexclusion).Lockthemutex,readthecurrentvalue,incrementitandwriteitbackandthenunlockthemutex.Anyotherthreadthatwantstomodifythevaluehastofirstcheckthemutexandblockuntilitiscleared.

IfyouareusingAPR,havealookattheapr_atomic_*functionsandtheapr_thread_mutex_*functions.

Thisisacommonglobalvariablethatholdstheerrornumberofthelasterrorthatoccurred.Ifonethreadcallsalow-levelfunctionthatsetserrnoandthenanotherthreadchecksit,wearebleedingerrornumbersfromonethreadintoanother.Tosolvethis,makesureyourmoduleorlibrarydefines_REENTRANToriscompiledwith-D_REENTRANT.Thiswillmakeerrnoaper-threadvariableandshouldhopefullybetransparenttothecode.Itdoesthisbydoingsomethinglikethis:

#defineerrno(*(__errno_location()))

whichmeansthataccessingerrnowillcall__errno_location()whichisprovidedbythelibc.Setting_REENTRANTalsoforcesredefinitionofsomeotherfunctionstotheir*_requivalentsandsometimeschangesthecommongetc/putcmacrosintosaferfunctioncalls.Checkyourlibcdocumentationforspecifics.Insteadof,orinadditionto_REENTRANTthesymbolsthatmayaffectthisare_POSIX_C_SOURCE,_THREAD_SAFE,_SVID_SOURCE,and_BSD_SOURCE.

Commonstandardtroublesomefunctions

Notonlydothingshavetobethreadsafe,buttheyalsohavetobereentrant.strtok()isanobviousone.Youcallitthefirsttimewithyourdelimiterwhichitthenremembersandoneachsubsequentcallitreturnsthenexttoken.Obviouslyifmultiplethreadsarecallingityouwillhaveaproblem.Mostsystemshaveareentrantversionofofthefunctioncalledstrtok_r()whereyoupassinanextraargumentwhichcontainsanallocatedchar*whichthefunctionwilluseinsteadofitsownstaticstorageformaintainingthetokenizingstate.IfyouareusingAPRyoucanuseapr_strtok().

crypt()isanotherfunctionthattendstonotbereentrant,soifyourunacrosscallstothatfunctioninalibrary,watchout.Onsomesystemsitisreentrantthough,soitisnotalwaysaproblem.Ifyoursystemhascrypt_r()chancesareyoushouldbeusingthat,orifpossiblesimplyavoidthewholemessbyusingmd5instead.

Common3rdPartyLibraries

Thefollowingisalistofcommonlibrariesthatareusedby3rdpartyApachemodules.Youcanchecktoseeifyourmoduleisusingapotentiallyunsafelibrarybyusingtoolssuchasldd(1)andnm(1).ForPHP,forexample,trythis:

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

Inadditiontotheselibrariesyouwillneedtohavealookatanylibrarieslinkedstaticallyintothemodule.Youcanusenm(1)tolookforindividualsymbolsinthemodule.

LibraryList

Pleasedropanotetodev@httpd.apache.orgifyouhaveadditionsorcorrectionstothislist.

Library Version ThreadSafe?

ASpell/PSpell ?BerkeleyDB 3.x,4.x Yes Becarefulaboutsharingaconnectionacross

threads.bzip2 Yes Bothlow-levelandhigh-levelAPIsarethread-safe.

However,high-levelAPIrequiresthread-safeaccesstoerrno.

cdb ?C-Client Perhaps c-clientusesstrtok()andgethostbyname()

whicharenotthread-safeonmostCimplementations.c-client'sstaticdataismeanttobesharedacrossthreads.Ifstrtok()gethostbyname()arethread-safeonyourOS,c-clientmaybethread-safe.

cpdflib ?libcrypt ?Expat Yes NeedaseparateparserinstanceperthreadFreeTDS ?FreeType ?GD1.8.x ?GD2.0.x ?gdbm No Errorsreturnedviaastaticgdbm_error

ImageMagick 5.2.2 Yes ImageMagickdocsclaimitisthreadsafesinceversion5.2.2(seeChangelog).

Imlib2 ?libjpeg v6b ?

libmysqlclient Yes Usemysqlclient_rlibraryvarianttoensurethread-safety.Formoreinformation,pleasereadhttp://www.mysql.com/doc/en/Threaded_clients.html

Ming 0.2a ?Net-SNMP 5.0.x ?OpenLDAP 2.1.x Yes Useldap_rlibraryvarianttoensure

OpenSSL 0.9.6g Yes RequiresproperusageofCRYPTO_num_locksCRYPTO_set_locking_callback

CRYPTO_set_id_callback

liboci8(Oracle8+)

8.x,9.x ?

pdflib 5.0.x Yes PDFLibdocsclaimitisthreadsafe;changes.txtindicatesithasbeenpartiallythread-safesinceV1.91:http://www.pdflib.com/products/pdflib/index.html

libpng 1.0.x ?libpng 1.2.x ?libpq(PostgreSQL)

7.x Yes Don'tshareconnectionsacrossthreadsandwatchoutforcrypt()calls

Sablotron 0.95 ?zlib 1.1.4 Yes Reliesuponthread-safezallocandzfreefunctions

Defaultistouselibc'scalloc/freewhicharethread-safe.

Apachemod_rewriteIntroduction

Thisdocumentsupplementsthemod_rewritereferencedocumentation.Itdescribesthebasicconceptsnecessaryforuseofmod_rewrite.Otherdocumentsgointogreaterdetail,butthisdocshouldhelpthebeginnergettheirfeetwet.

SeealsoModuledocumentationTechnicaldetailsPracticalsolutionstocommonproblems

Introduction

TheApachemodulemod_rewriteisaverypowerfulandsophisticatedmodulewhichprovidesawaytodoURLmanipulations.Withit,youcandonearlyalltypesofURLrewritingthatyoumayneed.Itis,however,somewhatcomplex,andmaybeintimidatingtothebeginner.Thereisalsoatendencytotreatrewriterulesasmagicincantation,usingthemwithoutactuallyunderstandingwhattheydo.

Thisdocumentattemptstogivesufficientbackgroundsothatwhatfollowsisunderstood,ratherthanjustcopiedblindly.

RegularExpressions

Basicregexbuildingblocks

RewriteRulebasics

BasicanatomyofaRewriteRule,withexhaustivelyannotatedsimpleexamples.

RewriteFlags

DiscussionoftheflagstoRewriteRule,andwhenandwhyonemightusethem.

Rewriteconditions

DiscussionofRewriteCond,looping,andotherrelatedconcepts.

Rewritemaps

DiscussionofRewriteMap,includingsimple,butheavilyannotated,examples.

.htaccessfiles

Discussionofthedifferencesbetweenrewriterulesinhttpd.confandin.htaccessfiles.

Thismodulekeepstrackoftwoadditional(non-standard)CGI/SSIenvironmentvariablesnamedSCRIPT_URLandSCRIPT_URI.ThesecontainthelogicalWeb-viewtothecurrentresource,whilethestandardCGI/SSIvariablesSCRIPT_NAMEandSCRIPT_FILENAMEcontainthephysicalSystem-view.

Notice:ThesevariablesholdtheURI/URLastheywereinitiallyrequested,i.e.,beforeanyrewriting.ThisisimportantbecausetherewritingprocessisprimarilyusedtorewritelogicalURLstophysicalpathnames.

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

apache http 2 - documentation.help · .htaccess server side includes (ssi) (public_html) microsoft...

Documents

apache struts understanding how apache struts...

apache hivemall @ apache bigdata '17, miami

writing apache spark and apache flink applications using...

big data systeme recommendations - haw...

apache directory studio apache ds configuration

apache beam introduction to -...

apache big data - apache bahir - · pdf fileibm spark...

apache hadoop today & tomorrow - snia€¦ · apache hadoop...

apache activemq and apache servicemix

acute‑‑chronic liver failur:onsensus recommendations...

users.suse.comusers.suse.com/~meissner/updates/2010.txt ·...

integrating apache nifi and apache apex

apache stratos: the paas from apache

wordpress.com€¦ · chiricahua apache is a southern...

getting started guide -...

· apache kafka introduction to apache kafka apache kafka...

using apache spark, apache kafka and apache...

httpclient tutorial - apache httpcomponents - apache...

apache phoenix + apache hbase

oracle applications cloud licensing information release 13...