Apache HTTP 2 - documentation.help · .htaccess Server Side Includes (SSI) (public_html) Microsoft Windows Novell NetWare ... Apache 2.0 Apache autoconf libtool Apache 1.3 APACI Apache

||FAQ||

ApacheHTTP2.0Apache>HTTP>

http://httpd.apache.org/docs-project/

http://www.apache.org/

http://httpd.apache.org/

http://httpd.apache.org/docs/

ApacheHTTP2.0

GoogleSearch

Apache2.01.32.0Apache

(MPM)

(DSO)

URL

SSL/TLSCGISuexecURLRewriting

How-To/

CGI:.htaccessServerSideIncludes(SSI) (public_html)

MicrosoftWindowsNovellNetWareEBCDIC

Copyright2013TheApacheSoftwareFoundation.LicensedundertheApacheLicense,Version2.0.

||FAQ||

(FAQ)

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

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

http://www.php.net/

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

SSI

vhost

WindowsNTUnicode

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

Apache2.0 Perl(PCRE) Perl5

http://www.pcre.org/

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

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

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


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

$make

$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

http://www.gnu.org/

http://www.gnu.org/software/gcc/gcc.html

news:comp.protocols.time.ntp

http://www.ntp.org

http://www.perl.org/

Apache ApacheHTTP

ApacheHTTP

http://httpd.apache.org/download.cgi

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

DSO :

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

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

--enable-rewrite=shared\

--enable-speling=shared

configure Makefile

configure configure

Apache :

$make

PentiumIII/Linux2.2 3

PREFIX( --prefix)

$makeinstall

PREFIX/conf/ ApacheHTTP

$viPREFIX/conf/httpd.conf

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

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

ApacheHTTP :


URLhttp://localhost/ PREFIX/htdocs/ :

$PREFIX/bin/apachectlstop


||FAQ||

API

(2.0.552.0.57) configure API (2.0.41

$./config.nice

$make

$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

root

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)

MPM

mod_status USR1

status

USR1

(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

MIME

Apache11 "\"

"#"

apachectlconfigtest

mod_so <IfModule>

LoadModule

Apache LoadModule Apache

-l

<Directory>

<DirectoryMatch>

<Files>

<FilesMatch>

<Location>

<LocationMatch>

<VirtualHost>

<FilesMatch>,<Location>,<LocationMatch>

Apache


||FAQ||

.htaccess

AccessFileName

AllowOverride

Apache .htaccess

.htaccess

.htaccess .htaccess


||FAQ||






URL .htaccess

core

mod_proxy

<Directory>

<DirectoryMatch>

<Files>

<FilesMatch>

<IfDefine>

<IfModule>

<Location>

<LocationMatch>

<Proxy>

<ProxyMatch>

<VirtualHost>

<IfDefine> <IfModule>

<IfDefine>httpd httpd-DClosedForNow:

<IfDefineClosedForNow>

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

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

<Directory/var/web/dir1>

<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

<Location/private>

OrderAllow,Deny

Denyfromall

</Location>

<Location>URL mod_statusApacheserver-status

<Location/server-status>

SetHandlerserver-status

</Location>

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

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

regex

<Directory/home/*/public_html>

OptionsIndexes

</Directory>

regex

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

Orderallow,deny

Denyfromall

</FilesMatch>

<Directory> <Files>()<Location>

<Location>(URL)

<Location/dir/>

Orderallow,deny

Denyfromall

</Location>

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

<Location/>URL

<VirtualHost>

<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

<VirtualHost>

(URL Alias<Location>/<LocationMatch>

A>B>C>D>E

<Location/>

E

</Location>

<Filesf.html>

D

</Files>

<VirtualHost*>

<Directory/a/b>


||FAQ||

B

</Directory>

</VirtualHost>

<DirectoryMatch"^.*b$">

C

</DirectoryMatch>

<Directory/a/b>

A

</Directory>

<Directory> <Location>

<Location/>

Orderdeny,allow

Allowfromall

</Location>

#Woops!This<Directory>sectionwillhavenoeffect

<Directory/>

Orderallow,deny

Allowfromall

Denyfrombadguy.example.com

</Directory>


||FAQ||





core

ID

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

CGI

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)

() IP

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

http://www.w3.org/Protocols/rfc2616/rfc2616.txt

:

#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

http://dmoz.org/Computers/Software/Internet/Site_Management/Log_analysis/

http://dir.yahoo.com/Computers_and_Internet/Software/Internet/World_Wide_Web/Servers/Log_Analysis_Tools/

10,000open open

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

http://www.cronolog.org/

>CustomLog ErrorLog <VirtualHost>

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

CustomLoglogs/access_logcomonvhost

%v


||FAQ||

mod_cgi

mod_rewrite

PidFile

RewriteLog

RewriteLogLevel

ScriptLog

ScriptLogBuffer

ScriptLogLength

PIDApachehttpdID logs/httpd.pidPidFile ID

ScriptLog CGI

mod_rewrite RewriteLogLevel


||FAQ||





URL

ApacheURL

mod_alias

mod_proxy

mod_rewrite

mod_userdir

mod_speling

mod_vhost_alias

Alias

AliasMatch

CheckSpelling

DocumentRoot

ErrorDocument

Options

ProxyPass

ProxyPassReverse

Redirect

RedirectMatch

RewriteCond

RewriteMatch

ScriptAlias

ScriptAliasMatch

UserDir

DocumentRoot

ApacheURL-Path(URL DocumentRoot

Apache IP

DocumentRoot

DocumentRootDocumentRoot SymLinksIfOwnerMatch

Alias

Alias/docs/var/web

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

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

AliasMatch ScriptAliasMatch

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

bin/$2

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

Unix user ~user/ mod_userdir

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

URL

Apache DocumentRoot /foo/ /bar/

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

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

/foo/

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

URL

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

http://httpd.apache.org/lists.html#http-announce

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.

http://cgiwrap.unixtools.org/

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

<Directory/>

AllowOverrideNone

</Directory>

Thispreventstheuseof.htaccessfilesinalldirectoriesapartfromthosespecificallyenabled.

ProtectServerFilesbyDefault

OneaspectofApachewhichisoccasionallymisunderstoodisthefeatureofdefaultaccess.Thatis,unlessyoutakestepstochangeit,iftheservercanfinditswaytoafilethroughnormalURLmappingrules,itcanserveittoclients.

Forinstance,considerthefollowingexample:

#cd/;ln-s/public_html

Accessinghttp://localhost/~root/

Thiswouldallowclientstowalkthroughtheentirefilesystem.Toworkaroundthis,addthefollowingblocktoyourserver'sconfiguration:

<Directory/>

OrderDeny,Allow

Denyfromall

</Directory>

Thiswillforbiddefaultaccesstofilesystemlocations.AddappropriateDirectoryblockstoallowaccessonlyinthoseareasyouwish.Forexample,

<Directory/usr/users/*/public_html>

OrderDeny,Allow

Allowfromall

</Directory>

<Directory/usr/local/httpd>

OrderDeny,Allow

Allowfromall

</Directory>

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

AlsobewaryofplayinggameswiththeUserDirdirective;setting

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

UserDirdisabledroot

Copyright2013TheApacheSoftwareFoundation.

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>

http://online.securityfocus.com/bid/4876/info/

LicensedundertheApacheLicense,Version2.0.



||FAQ||





(DSO)


ApacheHTTP SharedObject)(DSO) 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 (

DSO

1998DSO :Perl5(XSDnaLoaderApache

ApacheDSO


||FAQ||

DSO:

configureApache (SSL[mod_perl,PHP3] Apache

Apache DSO/ apxsApacheapxs-i apachectlrestart

DSO:

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

1.0()

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

http://ppewww.ph.gla.ac.uk/~flavell/www/lang-neg.html


||FAQ||





Apache

"500ServerError"

NCSAhttpd1.3/

1. NCSA

2. URL

3. URL

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

CGI

HTTP_USER_AGENT REDIRECT_HTTP_USER_AGENT

Apache REDIRECT_URL

URL

ErrorDocumentCGI ErrorDocumentPerl

...

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

printf"Status:%sConditionIntercepted\n",

$ENV{"REDIRECT_STATUS"};

...

404NotFound


||FAQ||






Apache

DNS

core

mpm_common

<VirtualHost>

Listen

Apache IPApache

Listen Listen listen

808000

Listen80

Listen8000

Listen192.170.2.1:80

Listen192.170.2.5:8000

IPv6

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

IPv6

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





(MPM)


ApacheHTTP

ApacheHTTP

Apache2.0

:

Apache Apache1.3POSIX (perchild)

MPMApache MPM

MPM

MPM MPMApache

MPM./configure --with-mpm=NAMEMPM

MPM ./httpd-l


||FAQ||

MPM

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 (:'_')

http://cgi-spec.golux.com

mod_access

mod_cgi

mod_ext_filter

mod_headers

mod_include

mod_log_config

mod_rewrite

Allow

CustomLog

Deny

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

<Directory/web/images>


||FAQ||

OrderDeny,Allow

Denyfromall

Allowfromenv=local_referal

</Directory>

ApacheToday KeepingYourImagesfromAdorningOtherSites

http://apachetoday.com/news_story.php3?ltsn=2000-06-14-002-01-ps


||FAQ||





Apache

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

<Directory/web/htdocs/asis>

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

2

3 suEXECsuEXEC ApachesuEXEC

4suEXECApache suEXECsuEXEC suEXEC

?!

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)

5. ?

?

6. ?

?

7. ?

suEXEC rootCGI/SSI

8. IDID ?

ID CGI/SSIID

9. ?

suEXEC'root'CGI/SSI

10. IDID ?

ID CGI/SSI

11. wrapper?

setuidsetgid

12. CGI/SSI (changedirectory)?

13. Apache?

suEXEC?(suEXEC)

14. ?

15. CGI/SSI?

16. CGI/SSI

CGI/SSI

17. CGI/SSIsetuidsetgid ?

UID/GID

18. / /?

?

19. ?

suEXEC ()

20. CGI/SSIexec?

suEXEC

suEXECwrapper

suEXEC

suEXEC

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

http://httpd.apache.org/docs/2.0/suexec.html







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

<Directory/>

OptionsSymLinksIfOwnerMatch

</Directory>

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

likethis:


<Directory/>

OptionsFollowSymLinks

</Directory>

<Directory/www/htdocs>

Options-FollowSymLinks+SymLinksIfOwnerMatch

</Directory>

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

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


<Directory/>

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.

http://www.research.digital.com/wrl/techreports/abstracts/95.4.html

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(;;){

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


http://bugs.apache.org/index/full/467

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


}

}


}

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

http://www.ics.uci.edu/pub/ietf/http/draft-ietf-http-connection-00.txt

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

http://www.w3.org/Protocols/HTTP/Performance/Pipeline.html

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<[email protected]>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

to

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îndex\.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,

#etc.

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

##Copyright(c)1997RalfS.Engelschall,AllRightsReserved.

##

$|=1;

$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ânyurlxredirect:news:newsgroup

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

ArchiveAccessMultiplexerDescription:

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

http://www.perl.com/CPAN

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

http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html

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

Thenwewritelb.pl:

#!/path/to/perl

##

##lb.pl--loadbalancingscript

##

$|=1;

$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


##

$|=1;

#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);


last;

}

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înlined-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}!^[email protected]\.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).

Other

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

$|=1;

#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

IP

IP IP

IPDNS IP

SSL SSL IP

core DocumentRoot

NameVirtualHost

ServerAlias

ServerName

ServerPath

VirtualHost

<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

<VirtualHost>

ServerAliasdomain.tld*.domain.tld

domain.tld www.domain.tldServerName ServerAlias

<VirtualHost> (<VirtualHost>)

<NameVirtualHost>IP<VirtualHost> ServerName ServerAlias

IP

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>

[email protected]

DocumentRoot/groups/smallco/www

ServerNamewww.smallco.com

ErrorLog/groups/smallco/logs/error_log

TransferLog/groups/smallco/logs/access_log

</VirtualHost>

<VirtualHostwww.baygroup.org>

[email protected]

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

<Directory/www/commercial>


AllowOverrideAll

</Directory>

<Directory/www/homepages>


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


<Directory/www/hosts>

#ExecCGIisneededherebecausewecan'tforce

#CGIexecutioninthewaythatScriptAliasdoes

OptionsFollowSymLinksExecCGI

</Directory>

#nowforthehardbit

RewriteEngineOn

#aServerNamederivedfromaHost:headermaybeanycaseat

all


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

Note

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.

Note

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



#etc...

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

Theaboveconfigurationiswhatyouwillwanttouseinalmostallname-basedvirtualhostingsituations.Theonlythingthatthisconfigurationwillnotworkfor,infact,iswhenyouareservingdifferentcontentbasedondifferingIPaddressesorports.

Name-basedhostsonmorethanoneIPaddress.

Note

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.

Note:

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>




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




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



Tips

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)

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

.log


||FAQ||





DNSApache


Apache DNSApache

<VirtualHostwww.abc.dom>

[email protected]

DocumentRoot/www/abc

</VirtualHost>

Apache ApacheDNS www.abc.dom DNS1.2)

www.abc.dom10.0.0.1


[email protected]


</VirtualHost>

ApacheDNS ServerName

IP URLURL


ServerNamewww.abc.dom

[email protected]


</VirtualHost>

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

<VirtualHostwww.abc.dom>

[email protected]


</VirtualHost>

<VirtualHostwww.def.dom>

[email protected]

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 )

IPDNS

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.

http://httpd.apache.org/docs/2.0/faq/

http://httpd.apache.org/bug_report.html

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?

http://httpd.apache.org/userslist.html

irc://irc.freenode.net/#httpd

http://freenode.net

news:comp.infosystems.www.servers.unix

http://groups.google.com/groups?group=comp.infosystems.www.servers.unix

news:comp.infosystems.www.servers.ms-windows

http://groups.google.com/groups?group=comp.infosystems.www.servers.ms-windows

news:comp.infosystems.www.authoring.cgi

http://groups.google.com/groups?group=comp.infosystems.www.authoring.cgi




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

http://home.earthlink.net/~fjhirsch/

http://home.earthlink.net/~fjhirsch/Papers/wwwj/article.html

http://www.ora.com/catalog/wjsum97/

mailto:[email protected]



SSL(:)([ AC96])

()

()

(CertificateAuthorityCA)(certificate)(authentication)

1

1:

() ( 2)

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

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

(CA)

Thawte VeriSign :

CRL)

http://www.thawte.com/

http://www.verisign.com/

SecureSocketsLayer(SSL)

SecureSocketsLayer(TCP/IP)(HTTP)SSL

SSL

4: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]

1

SSL

1:SSL

:

1.

2.

3.

4.

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

2 SSL

2:SSL

SSL

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.

http://www.counterpane.com/

http://www.itu.int/rec/recommendation.asp?type=items&lang=e&parent=T-REC-X.208-198811-I

http://www.itu.int/rec/recommendation.asp?type=folders&lang=e&parent=T-REC-X.509

http://www.rsasecurity.com/rsalabs/pkcs/

http://ietf.org/rfc/rfc2045.txt

http://www.netscape.com/eng/security/SSL_2.html

http://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.

http://www.apache-ssl.org/

http://www.redhat.com/products/product-details.phtml?id=rhsa

http://raven.covalent.net/

http://www.c2.net/products/stronghold/

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

dir-

SSLProxyCACertificateFile

file-

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

<Directory/usr/local/apache2/htdocs>

#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

<Location/strong/area>

#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


<Location/secure/area>


SSLVerifyDepth1

</Location>

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

Thefirstmethod:


<Directory/usr/local/apache2/htdocs/secure/area>


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:


<Directory/usr/local/apache2/htdocs/secure/area>


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

<Directory/usr/local/apache2/htdocs>

#OutsidethesubareaonlyIntranetaccessisgranted

Orderdeny,allow

Denyfromall

Allowfrom192.168.1.0/24

</Directory>



<Directory/usr/local/apache2/htdocs/subarea>

#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



http://www.apache-ssl.org/

http://www.wassenaar.org/

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

http://curl.haxx.se/

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://digitalid.verisign.com/server/apacheNotice.htm


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:


http://www.certisign.com.br

http://www.iks-jena.de/leistungen/ca/

http://www.uptimecommerce.com

http://www.belsign.be

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òpensslx509-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`ÀDH''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

http://httpd.apache.org/docs/2.0/ssl/ssl_faq.html

http://www.modssl.org/support/

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`ÒPTIM="-g-ggdb3"''togetthis.Onotherplatformsatleast`ÒPTIM="-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

Allow

AuthGroupFile

AuthName

AuthType

AuthUserFile

Deny

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"

Realm

AuthUserFile htpasswd mod_auth_dbm AuthDBMUserFileApache

Require

http://modules.apache.org/

( 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

Basic

?

Allow Deny

Allowfromaddress

addressIP (IP)

Denyfrom205.252.46.165

IP

Denyfromhost.example.com

Denyfrom192.101.205

Denyfromcyberthugs.commoreidiots.com

Denyfromke

Order Deny Allow

Orderdeny,allow

Denyfromall

Allowfromdev.example.com

Allow


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

<Directory/usr/local/apache2/htdocs/somedir>

Options+ExecCGI

</Directory>

CGI ApacheCGIplCGI :

AddHandlercgi-script.cgi.pl

.htaccessfiles

.htaccess httpd.confCGI

User.cgiCGI

<Directory/home/*/public_html>

Options+ExecCGI

AddHandlercgi-script.cgi

</Directory>

cgi-bin CGI

<Directory/home/*/public_html/cgi-bin>

OptionsExecCGI

SetHandlercgi-script

</Directory>

CGI

CGI

CGIMIME-type


HTML

CGI

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 :

CGI!

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

CGI WebSite)CGI

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

CGI

http://hoohoo.ncsa.uiuc.edu/cgi/env.html

CGI/

CGI

PerlCGI CPAN

CCGI

http://www.cpan.org/

http://www.boutell.com/cgic/


||FAQ||

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

CGI

CGI

Apache CGIApache


http://www.hwg.org/lists/hwg-servers/

http://hoohoo.ncsa.uiuc.edu/cgi/interface.html


||FAQ||





Apache:ServerSideIncludes

HTML

mod_include

mod_cgi

mod_expires

Options

XBitHack

AddType

SetOutputFilter

BrowserMatchNoCase

SSIServerSideIncludes SSISSI

SSISSI

SSI?

SSI(ServerSideIncludes)HTML HTML

SSI

SSI

SSI httpd.conf .htaccess:

Options+Includes

SSI ApacheOptions

SSI Apache

AddTypetext/html.shtml

AddOutputFilterINCLUDES.shtml

SSI

XBitHack:

XBitHackon

XBitHack SSIApachechmod

chmod+xpagename.html

.htmlSSIApacheXBitHack SSI

Windows

ApacheSSI HTTP

1. XBitHackFull

2. mod_expires

SSI

SSI:



HTMLSSI

element



echo CGI

config timefmt



Todayis

Thisdocumentlastmodified

timefmt

CGI``'' CGISSI



SSIHTML

? SSI



Thisfilelastmodified

ssi.shtml



Thisfilelastmodified

timefmt strftime

file/



LAST_MODIFIED

?

config config

SSI

[anerroroccurredwhileprocessingthisdirective]

config errmsg:



SSI

config sizefmt abbrev

CGISSI Win32DOS)

<pre>



</pre>

Windows

<pre>



</pre>

Windows

exec ``''IncludesNOEXEC SSI exec

SSI

ApacheSSI

Apache1.2 Apache1.2

set



( LAST_MODIFIED



($)





endif

:









test_condition ``''

:

BrowserMatchNoCasemacintoshMac

BrowserMatchNoCaseMSIEInternetExplorer

Macintosh

SSI:



Apologetictextgoeshere



CoolJavaScriptcodegoeshere



MacIE JavaScriptMacIE

( )


||FAQ||

SSICGI


||FAQ||





Apache:.htaccess


.htaccess

.htaccess

core

mod_auth

mod_cgi

mod_include

mod_mime

AccessFileName

AllowOverride

Options

AddHandler

SetHandler

AuthType

AuthName

AuthUserFile

AuthGroupFile

Require

.htaccess/

.htaccess()

:

.htaccess AccessFileName:

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

.htaccess

"AllowOverrideAuthConfig"

.htaccess:

AuthTypeBasic

AuthName"PasswordRequired"

AuthUserFile/www/passwords/password.file

AuthGroupFile/www/passwords/group.file

RequireGroupadmins

AllowOverrideAuthConfig

SSI

.htaccess SSI

Options+Includes

AddTypetext/htmlshtml

AddHandlerserver-parsedshtml

AllowOverrideOptions

SSI SSI

CGI

CGI :

Options+ExecCGI

AddHandlercgi-scriptcgipl

CGI :

Options+ExecCGI


AllowOverrideOptions

CGI CGI


||FAQ||

.htaccess

AllowOverride.htaccess

Apache


||FAQ||





UserDir "username" UserDir

URL

mod_userdir UserDir

DirectoryMatch

AllowOverride

UserDir

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

cgi-bin <Directory>CGI

<Directory/home/*/public_html/cgi-bin/>

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)

http://apachetoday.com/news_story.php3?ltsn=2000-06-1-001-01-NW-DP-LF

http://apachetoday.com/news_story.php3?ltsn=2000-07-10-001-01-NW-LF-SW

http://www.onlamp.com/pub/a/apache/2000/02/24/installing_apache.html

http://www.builder.com/Servers/Apache/ss01.html

http://www.devshed.com/Server_Side/Administration/APACHE/

BasicConfiguration

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

http://www.onlamp.com/pub/a/apache/2000/03/02/configuring_apache.html


http://apachetoday.com/news_story.php3?ltsn=2000-07-17-001-01-PS

http://www.builder.com/Servers/Apache/ss02.html

http://www.devshed.com/Server_Side/Administration/MoreApache/

Security

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

http://www.linuxplanet.com/linuxplanet/tutorials/1527/1/

http://www.apacheweek.com/features/userauth

http://www.apacheweek.com/features/dbmauth

http://linux.com/security/newsitem.phtml?sid=12&aid=3549

http://linux.com/security/newsitem.phtml?sid=12&aid=3667


http://apachetoday.com/news_story.php3?ltsn=2000-07-31-001-01-NW-DP-LF



http://apachetoday.com/news_story.php3?ltsn=2000-11-13-003-01-SC-LF-SW

Logging

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

http://www.onlamp.com/pub/a/apache/2000/03/10/log_rhythms.html

http://www.apacheweek.com/features/logfiles






CGIandSSI

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


http://www.cpan.org/doc/FAQs/cgi/idiots-guide.html

http://www.linuxplanet.com/linuxplanet/tutorials/1445/1/

http://www.htmlhelp.org/faq/cgifaq.html




http://www.builder.com/Servers/ApacheFiles/082400/



OtherFeatures

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

Ifyouhaveapointertoanaccurateandwell-writtentutorialnotincludedhere,pleaseletusknowbysubmittingittotheApacheBugDatabase.

http://www.apacheweek.com/features/negotiation

http://www.apacheweek.com/features/imagemaps


http://ppewww.ph.gla.ac.uk/~flavell/www/lang-neg.html

http://bugs.apache.org/



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.

http://www.microsoft.com/windows95/downloads/contents/WUAdminTools/S_WUNetworkingTools/W95Sockets2/Default.asp

DownloadingApacheforWindows

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

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

http://httpd.apache.org/download.cgi

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

http://www.microsoft.com/downloads/release.asp?ReleaseID=32831

http://www.microsoft.com/downloads/release.asp?ReleaseID=32832

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

or

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:

httpd

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:

c:

cd"\ProgramFiles\ApacheGroup\Apache2\bin"

httpd

ThenwaitforApachetostop,orpressControl-C.Thenenterthefollowing:

cd..\logs

more<error.log

WhenworkingwithApacheitisimportanttoknowhowitwillfindtheconfigurationfile.Youcanspecifyaconfigurationfileonthecommandlineintwoways:

-fspecifiesanabsoluteorrelativepathtoaparticularconfigurationfile:

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

or

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.

http://msdn.microsoft.com/downloads/sdks/platform/platform.asp

http://cm.bell-labs.com/cm/cs/who/bwk/

http://cm.bell-labs.com/cm/cs/who/bwk/awk95.exe

http://www.cygwin.com/

[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

http://www.openssl.org/source/

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.

http://www.zlib.net/

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.


news://developer-forums.novell.com/novell.devsup.webserver

Requirements

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

NetWareservicepacksareavailablehere.

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

http://developer.novell.com/ndk/libc.htm

http://support.novell.com/misc/patlst.htm#nw


DownloadingApacheforNetWare

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


http://www.apache.org/dist/httpd/binaries/netware

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

or

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:

http://developer.novell.com/ndk/cwpdk.htm


http://developer.novell.com/ndk/cldap.htm

http://www.gzip.org/zlib/

http://developer.novell.com/ndk/apache.htm

http://developer.novell.com/ndk/apache.htm

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<[email protected]>

Reply-To:[email protected]

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.



ftp://ftp.cup.hp.com/dist/networking/tools/connhist

http://www.specbench.org/

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

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

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.

http://www.siemens.de/servers/bs2osd/osdbc_us.htm

http://dev.apache.org/

http://www.w3.org/Daemon/

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

http://java.apache.org/

http://www.php.net/

http://hpwww.ec-lyon.fr/~vincent/apache/mod_put.html

ftp://hachiman.vidya.com/pub/apache/



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

-X]

OnWindowssystems,thefollowingadditionalargumentsareavailable:

httpd[-kinstall|config|uninstall][-nname]

[-w]

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.

-h

Outputashortsummaryofavailablecommandlineoptions.

-l

Outputalistofmodulescompiledintotheserver.ThiswillnotlistdynamicallyloadedmodulesincludedusingtheLoadModuledirective.

-L

Outputalistofdirectivestogetherwithexpectedargumentsandplaceswherethedirectiveisvalid.

-S

Showthesettingsasparsedfromtheconfigfile(currentlyonlyshowsthevirtualhostsettings).

-t

Runsyntaxtestsforconfigurationfilesonly.Theprogramimmediatelyexitsafterthesesyntaxparsingtestswitheitherareturncodeof0(SyntaxOK)orreturncodenotequalto0(SyntaxError).If-DDUMP_VHOSTSisalsoset,detailsofthevirtualhostconfigurationwillbeprinted.

-v

Printtheversionofhttpd,andthenexit.

-V

Printtheversionandbuildparametersofhttpd,andthenexit.

-X

Runhttpdindebugmode.Onlyoneworkerwillbestartedandtheserverwillnotdetachfromtheconsole.

ThefollowingargumentsareavailableonlyontheWindowsplatform:



-kinstall|config|uninstall

InstallApacheasaWindowsNTservice;changestartupoptionsfortheApacheservice;anduninstalltheApacheservice.

-nname

ThenameoftheApacheservicetosignal.

-w

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.

-d

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.

-h

Displayusageinformation.

-Hcustom-header

Appendextraheaderstotherequest.Theargumentis

typicallyintheformofavalidheaderline,containingacolon-separatedfield-valuepair(i.e.,"Accept-Encoding:zip/zop;8bit").

-i

DoHEADrequestsinsteadofGET.

-k

EnabletheHTTPKeepAlivefeature,i.e.,performmultiplerequestswithinoneHTTPsession.DefaultisnoKeepAlive.

-nrequests

Numberofrequeststoperformforthebenchmarkingsession.Thedefaultistojustperformasinglerequestwhichusuallyleadstonon-representativebenchmarkingresults.

-pPOST-file

FilecontainingdatatoPOST.

-Pproxy-auth-username:password

SupplyBASICAuthenticationcredentialstoaproxyen-route.Theusernameandpasswordareseparatedbyasingle:andsentonthewirebase64encoded.Thestringissentregardlessofwhethertheproxyneedsit(i.e.,hassentan407proxyauthenticationneeded).

-q

Whenprocessingmorethan150requests,aboutputsaprogresscountonstderrevery10%or100requestsorso.The-qflagwillsuppressthesemessages.

-s

Whencompiledin(ab-hwillshowyou)usetheSSLprotectedhttpsratherthanthehttpprotocol.Thisfeatureisexperimentalandveryrudimentary.Youprobablydonotwanttouseit.

-S

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.

-V

Displayversionnumberandexit.

-w

PrintoutresultsinHTMLtables.Defaulttableistwocolumnswide,withawhitebackground.

-x<table>-attributes

Stringtouseasattributesfor<table>.Attributesareinserted<tablehere>.

-Xproxy[:port]

Useaproxyserverfortherequests.

-y<tr>-attributes

Stringtouseasattributesfor<tr>.

-z<td>-attributes

Stringtouseasattributesfor<td>.



Bugs

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.

start

StarttheApachehttpddaemon.Givesanerrorifitisalreadyrunning.Thisisequivalenttoapachectl-kstart.

stop

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

httpd

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àpxs-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.

-a

ThisactivatesthemodulebyautomaticallyaddingacorrespondingLoadModulelinetoApache'shttpd.confconfigurationfile,orbyenablingitifitalreadyexists.

-A

Sameasoption-abutthecreatedLoadModuledirectiveisprefixedwithahashsign(#),i.e.,themoduleisjustpreparedforlateractivationbutinitiallydisabled.

-e

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.

-C

--config-cache

Thisisanaliasfor--cache-file=config.cache

--cache-file=FILE

ThetestresultswillbecachedinfileFILE.Thisoptionisdisabledbydefault.

-h

--help[short|recursive]

Outputthehelpandexit.Withtheargumentshortonlyoptionsspecifictothispackagewilldisplayed.Theargumentrecursivedisplaystheshorthelpofalltheincludedpackages.

-n

--no-create

Theconfigurescriptisrunnormallybutdoesnotcreateoutputfiles.Thisisusefultocheckthetestresultsbeforegeneratingmakefilesforcompilation.

-q

--quiet

Donotprintchecking...messagesduringtheconfigure

process.

--srcdir=DIR

DefinesdirectoryDIRtobethesourcefiledirectory.Defaultisthedirectory,whereconfigureislocated,ortheparentdirectory...

--silent

Sameas--quiet

-V

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

Note

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.

Note

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.

CC

DefinetheCcompilercommandtobeusedforcompilation.

CFLAGS

SetCcompilerflagsyouwanttouseforcompilation.

CPP

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.

group

Agroup,whichtheuserismemberof.Agroupnamemaynotcontainacolon(:).Youmayuseahyphen(-)ifyoudon'twanttoassigntheusertoagroup,butfillinthecommentfield.Additionallywhenusingtheupdatecommand,aperiod(.)keepstheoriginalgroupsuntouched.

comment

Thisistheplaceforyouropaquecommentsabouttheuser,likerealname,mailaddressorsuchthings.Theserverwillignorethisfield.

Encodings-d

cryptencryption(default,exceptonWin32,Netware)

-m

MD5encryption(defaultonWin32,Netware)

-s

SHA1encryption

-p

plaintext(notrecommended)

Commandsadd

Addsanentryforusernametofilenameusingtheencryptedpasswordencpasswd.

dbmmanagepasswords.dataddrbowenfoKntnEF3KSXA

adduser

Asksforapasswordandthenaddsanentryforusernametofilename.

dbmmanagepasswords.datadduserkrietz

check

Asksforapasswordandthenchecksifusernameisinfilenameandifit'spasswordmatchesthespecifiedone.

dbmmanagepasswords.datcheckrbowen

delete

Deletestheusernameentryfromfilename.

dbmmanagepasswords.datdeleterbowen

import

Readsusername:passwordentries(oneperline)fromSTDINandaddsthemtofilename.Thepasswordsalreadyhavetobecrypted.

update

Sameastheaddusercommand,exceptthatitmakessureusernamealreadyexistsinfilename.

dbmmanagepasswords.datupdaterbowen

view

JustdisplaysthecontentsoftheDBMfile.Ifyouspecifyausername,itdisplaystheparticularrecordonly.

dbmmanagepasswords.datview



Bugs

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

-c

Createthepasswdfile.Ifpasswdfilealreadyexists,itisdeletedfirst.

passwdfile

Nameofthefiletocontaintheusername,realmandpassword.If-cisgiven,thisfileiscreatedifitdoesnotalreadyexist,ordeletedandrecreatedifitdoesexist.

realm

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.

http://httpd.apache.org

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

-b

Usebatchmode;i.e.,getthepasswordfromthecommandlineratherthanpromptingforit.Thisoptionshouldbeusedwithextremecare,sincethepasswordisclearlyvisibleonthecommandline.

-c

Createthepasswdfile.Ifpasswdfilealreadyexists,itisrewrittenandtruncated.Thisoptioncannotbecombinedwiththe-noption.

-n

Displaytheresultsonstandardoutputratherthanupdatingafile.ThisisusefulforgeneratingpasswordrecordsacceptabletoApacheforinclusioninnon-textdatastores.Thisoptionchangesthesyntaxofthecommandline,sincethepasswdfileargument(usuallythefirstone)isomitted.Itcannotbecombinedwiththe-coption.

-m

UseMD5encryptionforpasswords.OnWindows,NetwareandTPF,thisisthedefault.

-d

Usecrypt()encryptionforpasswords.ThedefaultonallplatformsbutWindows,NetwareandTPF.Thoughpossiblysupportedbyhtpasswdonallplatforms,itisnotsupportedbythehttpdserveronWindows,NetwareandTPF.

-s

UseSHAencryptionforpasswords.Facilitatesmigrationfrom/toNetscapeserversusingtheLDAPDirectoryInterchangeFormat(ldif).

-p

Useplaintextpasswords.Thoughhtpasswdwillsupport

creationonallplatforms,thehttpddaemonwillonlyacceptplaintextpasswordsonWindows,NetwareandTPF.

-D

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.

-c

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

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

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

do

ln-s$f`basename$f.en`

done

CustomizingProxyErrorMessages

AsofApache-1.3,itispossibletousetheErrorDocumentmechanismforproxyerrormessagesaswell(previousversionsalwaysreturnedfixedpredefinederrormessages).

Mostproxyerrorsreturnanerrorcodeof[500InternalServerError].Tofindoutwhetheraparticularerrordocumentwasinvokedonbehalfofaproxyerrororbecauseofsomeotherservererror,andwhatthereasonforthefailurewas,youcancheckthecontentsofthenewERROR_NOTESCGIenvironmentvariable:ifinvokedforaproxyerror,thisvariablewillcontaintheactualproxyerrormessagetextinHTMLform.

ThefollowingexcerptdemonstrateshowtoexploittheERROR_NOTESvariablewithinanerrordocument:



<p>

Theserverencounteredanunexpectedcondition

whichpreventeditfromfulfillingtherequest.

</p>

<p>

<ahref="mailto:"

SUBJECT="Errormessage[]

for's

WebMaster</a>;itincludesusefuldebugginginformation

about

theRequestwhichcausedtheerror.

<pre></pre>

</p>







HTMLListingoftheDiscussedExample

So,tosummarizeourexample,here'sthecompletelistingofthe400.shtml.endocument.Youwillnoticethatitcontainsalmostnothingbuttheerrortext(withconditionaladditions).Startingwiththisexample,youwillfinditeasytoaddmoreerrordocuments,ortotranslatetheerrordocumentstodifferentlanguages.





<p>

Yourbrowsersentarequestthatthisservercouldnot

understand:

<blockquote>

<strong></strong>

</blockquote>

Therequestcouldnotbeunderstoodbytheserverdueto

malformed

syntax.Theclientshouldnotrepeattherequestwithout

modifications.

</p>

<p>



Pleaseinformtheownerof

<ahref="">thereferring

page</a>about

themalformedlink.



Pleasecheckyourrequestfortypingerrorsandretry.



</p>



Hereisthecompletehead.shtml.enfile(thefunnylinebreaksavoidemptylinesinthedocumentafterSSIprocessing).Notetheconfigurationsectionattop.That'swhereyouconfiguretheimagesandlogosaswellastheapachedocumentationdirectory.Lookhowthisfiledisplaystwodifferentlogosdependingonthe

contentofthevirtualhostname($SERVER_NAME),andthatananimatedapachelogoisshownifthebrowserappearstosupportit(thelatterrequiresserverconfigurationlinesoftheform

BrowserMatch"^Mozilla/[2-4]"anigif

forbrowsertypeswhichsupportanimatedGIFs).





























<!DOCTYPEHTMLPUBLIC"-//IETF//DTDHTML//EN">

<html>

<head>

<title>

[]

</title>

</head>

<bodybgcolor="white"background="]

<imgsrc=""

alt=""align="right">

</h1>

<hr/>

<div>

andthisisthefoot.shtml.enfile:

</div>

<hr/>

<divalign="right">

<small>LocalServertime:

</small>

</div>

<divalign="center">

<ahref="">

<imgsrc=""border="0"

align="bottom"

alt="Poweredby">

</a>

<br/>

<small>

</small>

</div>

<p>Iftheindicatederrorlookslikeamisconfiguration,

pleaseinform

<ahref="mailto:"

subject="FeedbackaboutErrormessage[]

,req='sWebMaster</a>.

</p>

</body>

</html>



Ifyouhavetipstocontribute,[email protected]








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.

ftp://ds.internic.net/rfc/rfc793.txt

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

http://www.freebsd.org/

http://www.netbsd.org/

http://www.openbsd.org/

http://www.bsdi.com/

ftp://ftp.bsdi.com/bsdi/patches/patches-2.1/K210-027

http://www.sun.com/

http://www.linux.org/

http://www.hp.com/

http://www.sgi.com/

http://www.ncr.com/

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

http://www.sequent.com

http://www.sun.com/

http://www.apache.org/dist/httpd/contrib/patches/1.2/fin_wait_2.patch

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

http://www.apache.org/dist/httpd/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch

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.

http://www.apache.org/dist/httpd/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch

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.

http://www.arctic.org/~dgaudet/patches/apache-1.2-gif89-expires-hack.patch

http://www.arctic.org/~dgaudet/patches/apache-1.3-gif89-expires-hack.patch

POSTwithoutContent-Length

IncertainsituationsNavigator3.01through3.03appeartoincorrectlyissueaPOSTwithouttherequestbody.Thereisnoknownworkaround.IthasbeenfixedinNavigator3.04,Netscapesprovidessomeinformation.There'salsosomeinformationabouttheactualproblem.

http://help.netscape.com/kb/client/971014-42.html

http://www.arctic.org/~dgaudet/apache/no-content-length/

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

http://bugs.apache.org/index/full/4118







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.

Linux

BydefaultLinuxhasakernelmaximumof256opendescriptorsperprocess.Thereareseveralpatchesavailableforthe2.0.xserieswhichraisethisto1024andbeyond,andyoucanfindtheminthe"unofficialpatches"sectionoftheLinuxInformationHQ.Noneofthesepatchesareperfect,andanentirelydifferentapproachislikelytobetakenduringthe2.1.xdevelopment.ApplyingthesepatcheswillraisetheFD_SETSIZEusedtocompileallprograms,andunlessyourebuildallyourlibrariesyoushouldavoidrunninganyotherprogramwithasoftdescriptorlimitabove256.Asofthiswritingthepatchesavailableforincreasingthenumberofdescriptorsdonottakethisintoaccount.Onadedicatedwebserveryouprobablywon'trunintotrouble.

http://www.linuxhq.com/

Solaristhrough2.5.1

Solarishasakernelhardlimitof1024(maybelowerinearlierversions).Butithasalimitationthatfilesusingthestdiolibrarycannothaveadescriptorabove255.ApacheusesthestdiolibraryfortheErrorLogdirective.Whenyouhavemorethanapproximately110virtualhosts(withanerrorlogandanaccesslogeach)youwillneedtobuildApachewith-DHIGH_SLACK_LINE=256addedtoEXTRA_CFLAGS.Youwillbelimitedtoapproximately240errorlogsifyoudothis.

AIX

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.

http://purl.org/NET/http-errata

http://www.rfc-editor.org/errata.html

http://ftp.ics.uci.edu/pub/ietf/http/#RFC

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.

http://www.rfc-editor.org/rfc/rfc1945.txt



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.


http://www.w3.org/TR/html401

http://www.w3.org/MarkUp/html4-updates/errata

http://www.w3.org/TR/REC-html32

http://www.w3.org/TR/xhtml11/

http://www.w3.org/2001/04/REC-xhtml-modularization-20010410-errata

http://www.w3.org/TR/xhtml1

http://www.w3.org/2002/08/REC-xhtml1-20020801-errata

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.

http://www.loc.gov/standards/iso639-2/

http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/index.html

http://www.rfc-editor.org/rfc/bcp/bcp47.txt




||FAQ||





Apache

Apache

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

<VirtualHost>

<Directory>,<Location>,<Files>Location,Files

.htaccess.htaccess

(:BoolenOR)httpd.conf .htaccess <Directory>

<VirtualHost>

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

Off

On

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

<Directory/>

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

<Location/cgi-bin/>

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>

<DirectoryMatch> <Files>

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


MIME

DefaultTypeimage/gif

.gif GIF

ForceType MIME

<Directory>

: : <Directorydirectory-path>...</Directory>

: ,: Core: core

pathUnix ?1 /home/user/public_html <Directory

/*/public_html> <Directory

/home/*/public_html> :

<Directory/usr/local/httpd/htdocs>

OptionsIndexesFollowSymLinks

</Directory>

directory-path:Apache <Directory>

~ :

<Directory~"^/www/.*/[0-9]{3}">

/www/ 3

() <Directory> ()

<Directory/>

AllowOverrideNone

</Directory>

<Directory/home/>

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

<Directory/>

OrderDeny,Allow

DenyfromAll

</Directory>

httpd.conf <Directory><LimitExcept>

<DirectoryMatch>

: : <DirectoryMatchregex>...</DirectoryMatch>

: ,: Core: core

<Directory> <DirectoryMatch> </DirectoryMatch>

<DirectoryMatch"^/www/.*/[0-9]{3}">

/www/3

<Directory> <Directory>

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

URL

EnableMMAP

: : EnableMMAPOn|Off

: EnableMMAPOn


httpd

httpdNFS DocumentRoot httpd

:

EnableMMAPOff

NFS :

<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

2.

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

<Directory/web/docs>

ErrorDocument404default

</Directory>

URL( http) ErrorDocumentApache

ErrorDocument401URL 401ErrorDocument401

MicrosoftInternetExplorer(MSIE)MSIE Microsoft

2.0

http://support.microsoft.com/default.aspx?scid=kb;en-us;Q294807

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

:

Unix

LogLevel

Apache

FileETag

: ETagHTTP: FileETagcomponent...

: FileETagINodeMTimeSize


FileETag ETag

ETag inode,(mtime)

INodeinode

MTime

Size

All

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

<FilesMatch>

: : <FilesMatchregex>...</FilesMatch>


<FilesMatch> <Files>

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

<Location/images>

ForceTypeimage/gif

</Location>

#butnormalmime-typeassociationshere:

<Location/images/mixed>

ForceTypeNone

</Location>

HostnameLookups

: IPDNS: HostnameLookupsOn|Off|Double

: HostnameLookupsOff

: ,,: Core: core

DNS IP

mod_access 2Double 2 REMOTE_HOST

bin

IdentityCheck

: RFC1413: IdentityCheckOn|Off

: IdentityCheckOff

: ,,: Core: core

identd

<IfDefine>

: : <IfDefine[!]parameter-name>...</IfDefine>


<IfDefinetest>...</IfDefine> test test

<IfDefine> test :

parameter-name!parameter-name

parameter-name

parameter-name httpd -Dparameter-

<IfDefine>

httpd-DReverseProxy...

#httpd.conf

<IfDefineReverseProxy>

LoadModulerewrite_modulemodules/mod_rewrite.so

LoadModuleproxy_modulemodules/libproxy.so

</IfDefine>

<IfModule>

: : <IfModule[!]module-name>...</IfModule>


<IfModuletest>...</IfModule>test test

<IfModule> test

modulename!modulename

modulename Apache (modulename

modulename mod_rewrite.c

STANDARD20_MODULE_STUFF

<IfModule>

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 :

<LimitPOSTPUTDELETE>

Requirevalid-user

</Limit>

: GET,POST,PUT,PROPFIND,PROPPATCH,MKCOL,COPY,MOVE,LOCK,UNLOCK.

GET HEAD TRACE

<Limit> <LimitExcept>

<LimitExcept>

: HTTP: <LimitExceptmethod[method]...>...

</LimitExcept>


<LimitExcept> </LimitExcept> HTTP<Limit>

:

<LimitExceptPOSTGET>

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

100K

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

<Location>

: URL: <LocationURL-path|URL>...</Location>

: ,: Core: core

<Location> URL <Location><Files>

<Location>

<Location>

<Location> <Location/>

() URL /path/ http://servername

scheme://servername/path

URL ? *

~ :

<Location~"/(extra|special)/data">

URL /extra/data /special/data<LocationMatch> <Location>

<Location> SetHandler

<Location/status>


OrderDeny,Allow

Denyfromall

Allowfrom.foo.com

</Location>

/()

URL <LocationMatch> <Location>

<LocationMatch^/abc> /abcURLURL () <Location><Location>proxy /abc//def

<LocationMatch>

: 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..."(...)

crit

:

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)


IPV6:

NameVirtualHost[2001:db8::a00:20ff:fea7:ccea]:8080

*

NameVirtualHost*

<VirtualHost>

<VirtualHost> NameVirtualHost



#...

</VirtualHost>

Options

:: Options[+|-]option[[+|-]option]...

: OptionsAll

: ,,,.htaccess: Options: Core: core

Options

option None 1

All

MultiViews

ExecCGI

mod_cgiCGI

FollowSymLinks

<Directory>

<Location>

Includes

mod_includeSSI

IncludesNOEXEC

SSI #exec #execCGIvirtual ScriptAlias CGI

Indexes

URL DirectoryIndex

mod_autoindex

MultiViews

mod_negotiation "MultiViews"

SymLinksIfOwnerMatch

ID

<Location>

Options +

+ -:



</Directory>

<Directory/web/docs/spec>

OptionsIncludes

</Directory>

/web/docs/spec Includes 2 -:



</Directory>

<Directory/web/docs/spec>

Options+Includes-Indexes

</Directory>

/web/docs/spec FollowSymLinks Includes

-IncludesNOEXEC -Includes SSI

All

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

CPU

RLimitMEM

RLimitNPROC

RLimitMEM

: Apache: RLimitMEMbytes|max[bytes|max]



RLimitCPU

RLimitNPROC

RLimitNPROC

: Apache: RLimitNPROCnumber|max[number|max]



CGIID

RLimitMEM

RLimitCPU

Satisfy

:: SatisfyAny|All

: SatisfyAll

: ,.htaccess: AuthConfig: Core: core: 2.0.51 <Limit>

<LimitExcept>

Allow Require Any

Requirevalid-user

Allowfrom192.168.1

SatisfyAny

2.0.51 <Limit> <LimitExcept>

Allow

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

[email protected]

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

ServerTokens

: ServerHTTP: ServerTokens

Major|Minor|Min[imal]|Prod[uctOnly]|OS|Full

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


</Location>

None SetHandler

AddHandler

SetInputFilter

: POST: SetInputFilterfilter[;filter...]


SetInputFilter POST

SetOutputFilter

:: SetOutputFilterfilter[;filter...]


SetOutputFilter

/www/data/ SSI

<Directory/www/data/>


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

http://httpd.apache.org/docs/misc/FAQ.html#prompted-twice

<VirtualHost>

: IP: <VirtualHostaddr[:port][addr[:port]]...>

...</VirtualHost>

:: Core: core

<VirtualHost> </VirtualHost> <VirtualHost> Addr:

IPIPNameVirtualHost* IPIPIP


[email protected]

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

[email protected]

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 )

:port )

ApacheDNSApacheApache


||FAQ||





ApacheMPM


: (MPM)

: MPM

AcceptMutex

: acceptApache: AcceptMutexdefault|method

: AcceptMutexdefault

:: MPM: leader,perchild,prefork,threadpool,worker

AcceptMutex accept

Default

flock

LockFile flock(2)

fcntl

LockFile fcntl(2)

posixsem

POSIX

pthread

POSIXThreads(PThreads) POSIX

sysvsem

SySV

LogLevel

BS2000Account

: BS2000: BS2000Accountaccount

:: MPM: perchild,prefork: BS2000

BS2000Account BS2000 Apache(BS2000POSIX(sub-LOGON BS2000) SYSROOT

Note

BS2000Account

ApacheEBCDICport

CoreDumpDirectory

: Apache: CoreDumpDirectorydirectory

::: MPM: beos,leader,mpm_winnt,perchild,prefork,

threadpool,worker

Apache

Linux

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

http://www.apache.org/~trawick/exception_hook.html

Group

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

IPv6

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

MPM

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

MPM

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



TCP

0OS

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

mpm_winnt ThreadsPerChild 64 25

Copyright2013TheApacheSoftwareFoundation. ||FAQ||

User

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

Note:

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.

http://deuce.doc.wustl.edu/doc/pspdfs/lf.pdf







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)

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

Allow

:: Allowfromall|host|env=env-variable

[host|env=env-variable]...

: ,.htaccess: Limit: Base: mod_access

Allow

from Allowfromall

()

:Allowfromapache.org

Apache HostnameLookupsIPIPDNS

IP

:Allowfrom10.1.2.3

IP

IP

:

Allowfrom10.1

IP

/

:Allowfrom10.1.0.0/255.255.0.0

a.b.c.dw.x.y.z

/nnnCIDR

:Allowfrom10.1.0.0/16

nnn1

:

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

<Directory/docroot>

OrderDeny,Allow

Denyfromall

Allowfromenv=let_me_in

</Directory>

user-agent KnockKnock/2.0

Deny

:: Denyfromall|host|env=env-variable

[host|env=env-variable]...


IP

Order

: Allow Deny: Orderordering

: OrderDeny,Allow


Order Allow Deny

Deny,Allow

Deny Allow

Allow,Deny

Allow Deny

Mutual-failure

Allow Deny

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

<Directory/www>

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

URL

AliasRedirect ( <VirtualHost>)AliasRedirect

AliasRedirect Redirect RedirectMatchAliasAliasRedirect

:

Alias/foo/bar/baz

Alias/foo/gaq

/fooAlias /foo/barAlias

Alias

: 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

<Directory> ( <Location>

Alias DocumentRoot

Alias/image/ftp/pub/image

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

path


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.

</h1>

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

ID

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

ID

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>

Note

DigestauthenticationprovidesamoresecurepasswordsystemthanBasicauthentication,butonlyworkswithsupportingbrowsers.AsofNovember2002,themajorbrowsersthatsupportdigestauthenticationareOpera,MSInternetExplorer(failswhenusedwithaquerystring-see"WorkingwithMSInternetExplorer"belowforaworkaround),Amaya,MozillaandNetscapesinceversion7.Sincedigestauthenticationisnotaswidelyimplementedasbasicauthentication,youshoulduseitonlyincontrolledenvironments.

http://www.opera.com/

http://www.microsoft.com/windows/ie/

http://www.w3.org/Amaya/

http://www.mozilla.org

http://channels.netscape.com/ns/browsers/download.jsp

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

http://www.openldap.org/


http://www.iplanet.com/downloads/developer/

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?

cn"

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

0

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

<Directory/foo>

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.

http://www.ietf.org/rfc/rfc2616.txt

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>

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

TE

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

http://www.w3.org/pub/WWW/Daemon/User/Config/General.html#MetaDir

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

http://hoohoo.ncsa.uiuc.edu/cgi/

CGI

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

http://hoohoo.ncsa.uiuc.edu/cgi/

CGI

CGI ()

CGICGI CGICGI

%%[time]request-line

%%HTTP-statusCGI-script-filename

CGI 2:

%%error

error-message

()

%request

HTTP

()POSTPUT

%response

CGI

%stdout

CGI

%stderr

CGI

( %stdout%stderr)

ScriptLog

: CGI: ScriptLogfile-path

: ,: Base: mod_cgi,mod_cgid

ScriptLogCGIServerRoot

ScriptLoglogs/cgi_log

User

CGI

ScriptLogBuffer

: PUTPOST: ScriptLogBufferbytes

: ScriptLogBuffer1024


PUTPOST


||FAQ||

ScriptLogLength

: CGI: ScriptLogLengthbytes

: ScriptLogLength10385760


ScriptLogLengthCGI CGI


||FAQ||





Apachemod_cgid

: CGICGI

: Base: cgid_module: mod_cgid.c: Unix

MPM

ScriptSock mod_cgid mod_cgiCGI mod_cgi

Unix fork unix

MPM mod_cgiCGI

mod_cgi

CGIID


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

http://www.webdav.org/

http://www.webdav.org

http://www.webdav.org

EnablingWebDAV

mod_dav httpd.conf:

DavOn

DAVDAV

DAV DavLockDB httd.conf

DavLockDB/usr/local/apache2/var/DavLock

Apache User

<Limit> <Location>DAVLimitXMLRequestBody

DavLockDB/usr/local/apache2/var/DavLock

<Location/foo>

DavOn

AuthTypeBasic

AuthNameDAV

AuthUserFileuser.passwd

<LimitExceptGETOPTIONS>

requireuseradmin

</LimitExcept>

</Location>

mod_davGregStein Apache1.3mod_dav

http://www.webdav.org/mod_dav/

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

<Location/php-source>

DAVOn

ForceTypetext/plain

</Location>

http://example.com/phpareaPHPhttp://example.com/php-sourceDAV

Dav

: WebDAVHTTP: DavOn|Off|provider-name

: DavOff

:: Extension: mod_dav

WebDAVHTTP

<Location/foo>

DavOn

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

DAV

DavMinTimeout

(600)

<Location/MSWord>

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

SDBM

DavLockDBlogs/DavLock


||FAQ||





Apachemod_deflate

:: Extension: deflate_module: mod_deflate.c

mod_deflate DEFLATE

Filters

AddOutputFilterByTypeDEFLATEtext/htmltext/plaintext/xml

<Location/>

#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

<Location/dav-area>

SetInputFilterDEFLATE

</Location>

Content-Encoding:gzip

Content-Length

Content-Length Content-Length

Proxy

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

Input

Output

Ratio

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

/ URL

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!

<Location/some/path>

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.

Note:

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:

<Location/example-info>

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

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9

ExpiresDefault ExpiresByType :

ExpiresDefault"<base>[plus]{<num><type>}*"

ExpiresByTypetype/encoding"<base>[plus]{<num><type>}*"

<base>:

access

now('access')modification

plus<num> ( atoi()) <type>:

years

months

weeks

days

hours

minutes

seconds

1 :

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)

M

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

<Location/gzipped>

#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

<Location/>

#coredirectivetocausetheslowdownfilterto

#berunseveraltimesonoutput

#

SetOutputFilterslowdown;slowdown;slowdown

</Location>

Usingsedtoreplacetextintheresponse

#mod_ext_filterdirectivetodefineafilterwhich

#replacestextintheresponse

#

ExtFilterDefinefixtextmode=outputintype=text/html\

cmd="/bin/seds/verdana/arial/g"

<Location/>

#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

<Directory/usr/local/docs>

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.

Note

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:

set

Theresponseheaderisset,replacinganypreviousheaderwiththisname.Thevaluemaybeaformatstring.

append

Theresponseheaderisappendedtoanyexistingheaderofthesamename.Whenanewvalueismergedontoanexistingheaderitisseparatedfromtheexistingheaderwithacomma.ThisistheHTTPstandardwayofgivingaheader

multiplevalues.

add

Theresponseheaderisaddedtotheexistingsetofheaders,evenifthisheaderalreadyexists.Thiscanresultintwo(ormore)headershavingthesamename.Thiscanleadtounforeseenconsequences,andingeneral"append"shouldbeusedinstead.

unset

Theresponseheaderofthisnameisremoved,ifitexists.Iftherearemultipleheadersofthesamename,allwillberemoved.

echo

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:

set

Therequestheaderisset,replacinganypreviousheaderwiththisname

append

Therequestheaderisappendedtoanyexistingheaderofthesamename.Whenanewvalueismergedontoanexistingheaderitisseparatedfromtheexistingheaderwithacomma.ThisistheHTTPstandardwayofgivingaheadermultiplevalues.

add

Therequestheaderisaddedtotheexistingsetofheaders,evenifthisheaderalreadyexists.Thiscanresultintwo(ormore)headershavingthesamename.Thiscanleadtounforeseenconsequences,andingeneralappendshouldbeusedinstead.

unset

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.

map

EquivalenttotheURLoftheimagemapfileitself.No

coordinatesaresentwiththis,soamenuwillbegeneratedunlessImapMenuissettonone.

menu

Synonymouswithmap.

referer

EquivalenttotheURLofthereferringdocument.Defaultstohttp://servername/ifnoReferer:headerwaspresent.

nocontent

Sendsastatuscodeof204NoContent,tellingtheclienttokeepthesamepagedisplayed.Validforallbutbase.

error

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:[email protected],150200,0"Bugs?"

Referencingyourmapfile

HTMLexample<ahref="/maps/imagemap1.map">

<imgismapsrc="/images/imagemap1.gif">

</a>

XHTMLexample<ahref="/maps/imagemap1.map">

<imgismap="ismap"src="/images/imagemap1.gif"/>

</a>

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.

none

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

SSI

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

var

encoding

echo entityencoding encoding

encoding var ISO-8859-1

execexecCGI mod_cgi

cgi

(%-)URL (/)(ScriptAlias OptionExecCGI)CGI

CGI PATH_INFO( CGIinclude



Location: HTML()

execcgi includevirtualCGI

cgi includevirtual



cmd

/bin/sh CGI include

#includevirtual #execcgi #execcmd( #includevirtual)Apache

Win32 suexecunix execunixsuexec Win32suexecunix:



fsize sizefmt

file

virtual

(%)URL-path(/)

flastmod timefmt

include (text/plain,text/html)

include

file

../

virtual

(%)URL URL

URLURL

URLCGI



HTMLCGI includevirtual

printenvApache1.3.12 (



set

var

value



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"



infoo



inbar



inneither











if if

elif else test_condition

endif if

test_condition:

string

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"

http://www.perl.com

"20"

(test_condition)

test_condition

!test_condition

test_condition

test_condition1&&test_condition2

test_condition1 test_condition2

test_condition1||test_condition2

test_condition1 test_condition2

"="" !="" &&" " !" :





&& ||

:

string1string2 string1string2

'string1string2' string1string2

http://www.pcre.org

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"

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

off

on

text/htmlhtml

full

on

CGI #include


||FAQ||





Apachemod_info


:: Extension: info_module: mod_info.c

mod_info httpd.conf

<Location/server-info>

SetHandlerserver-info

</Location>

<Location> <Limit>

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.

Usage

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.



http://www.iplanet.com/downloads/developer/

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

<Location/ldap-status>

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/server/cache-info>


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

<Location/ldap-status>


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

%...D

%...

{FOOBAR}e

FOOBAR

%...f

%...h

%...H

%...

{Foobar}i

Foobar:

%...l (identd) IdentityCheck

-%...m

%...

{Foobar}n

Foobar

%...

{Foobar}o

Foobar:

%...p

%...P ID%...

{format}P IDID format2.0.46 )

%...q ( ? )%...r

%...s ---%...t CLF()%...

{format}t

formatformat strftime(3)

%...T

%...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:

"<"">"

%>s

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

httpd

Unix

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.

Note

Whenenteringafilepathonnon-Unixplatforms,careshouldbetakentomakesurethatonlyforwardslashedareusedeventhoughtheplatformmayallowtheuseofbackslashes.Ingeneralitisagoodideatoalwaysuseforwardslashesthroughouttheconfigurationfiles.


||FAQ||





Apachemod_logio

:: Extension: logio_module: mod_logio.c

mod_log_config

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

URI

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

.bak

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

http://www.isi.edu/in-notes/iana/assignments/media-types/media-types







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.

Notes

Thefollowingnotesapplytothemod_mime_magicmoduleandareincludedhereforcompliancewithcontributors'copyrightrestrictionsthatrequiretheiracknowledgment.

mod_mime_magic:MIMEtypelookupviafilemagicnumbersCopyright(c)1996-1997CiscoSystems,Inc.

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:

MIME

level

text/html2

qs

variant 0.01.0 ASCIIASCII

Content-Type:image/jpeg;qs=0.8

URI:

()variant uri.

Body:

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

http://www.squid-cache.org/

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

Note

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.

<Location/buggyappserver/>

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.

Note

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

Note

AnIPAddrdoesnotneedtoberesolvedbytheDNSsystem,soitcanresultinmoreeffectiveapacheperformance.

HostnameAHostnameisafullyqualifiedDNSdomainnamewhichcanberesolvedtooneormoreIPAddrsviatheDNSdomainnameservice.Itrepresentsalogicalhost(incontrasttoDomains,seeabove)andmustberesolvabletoatleastoneIPAddr(oroftentoalistofhostswithdifferentIPAddrs).

Examplesprep.ai.mit.edu

www.apache.org

Note

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.

Note

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

http://www.webthing.com/software/mod_proxy_html/

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ôldstuff\.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.

HTTPS

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!

Note

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`Ùser-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`òr''.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

file.

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

$|=1;

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.

http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-3368

http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-4317

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:

Text:

.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:`ìfthecurrentURLdoesNOTmatchthispattern''.Thiscanbeusedforexceptionalcases,whereitiseasiertomatchthenegativepattern,orasalastdefaultrule.

NoteWhenusingtheNOTcharactertonegateapattern,youcannotincludegroupedwildcardpartsinthatpattern.Thisisbecause,whenthepatterndoesNOTmatch(ie,thenegationmatches),therearenocontentsforthegroups.Thus,ifnegatedpatternsareused,youcannotuse$Ninthesubstitutionstring!

Thesubstitutionofarewriteruleisthestringwhichissubstituted

http://perldoc.perl.org/perlre.html

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`ÒptionsFollowSymLinks''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

2. :

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

Base

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

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.

http://www.openssl.org/


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`òpensslciphers-v''commandwhichprovidesanicewaytosuccessivelycreatethecorrectcipher-specstring.Thedefault

cipher-specstringis`ÀLL:!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

DES-

CBC3-MD5

SSLv2 RSA RSA 3DES(168) MD5

IDEA-

CBC-SHA

SSLv3 RSA RSA IDEA(128) SHA1

RC4-SHA SSLv3 RSA RSA RC4(128) SHA1

RC4-MD5 SSLv3 RSA RSA RC4(128) MD5

IDEA-

CBC-MD5

SSLv2 RSA RSA IDEA(128) MD5

RC2-CBC-

MD5

SSLv2 RSA RSA RC2(128) MD5

RC4-MD5 SSLv2 RSA RSA RC4(128) MD5DES-CBC-

SHA

SSLv3 RSA RSA DES(56) SHA1

RC4-64-

MD5

SSLv2 RSA RSA RC4(64) MD5

DES-CBC-

MD5

SSLv2 RSA RSA DES(56) MD5

EXP-DES-

CBC-SHA

SSLv3 RSA(512) RSA DES(40) SHA1 export

EXP-RC2-

CBC-MD5

SSLv3 RSA(512) RSA RC2(40) MD5 export

EXP-RC4-

MD5


EXP-RC2-

CBC-MD5


EXP-RC4-

MD5


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-

MD5

SSLv3 DH None RC4(128) MD5

EDH-RSA-

DES-

CBC3-SHA

SSLv3 DH RSA 3DES(168) SHA1

EDH-DSS-

DES-

CBC3-SHA

SSLv3 DH DSS 3DES(168) SHA1

EDH-RSA-

DES-CBC-

SHA

SSLv3 DH RSA DES(56) SHA1

EDH-DSS-

DES-CBC-

SHA

SSLv3 DH DSS DES(56) SHA1

EXP-EDH-

RSA-DES-

CBC-SHA

SSLv3 DH(512) RSA DES(40) SHA1 export

EXP-EDH-

DSS-DES-

CBC-SHA

SSLv3 DH(512) DSS DES(40) SHA1 export

EXP-ADH-

DES-CBC-

SHA

SSLv3 DH(512) None DES(40) SHA1 export

EXP-ADH-

RC4-MD5

SSLv3 DH(512) None RC4(40) MD5 export

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

http://cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2009-3555

http://cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2009-3555

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"

http://httpd.apache.org/docs/2.0/mod/mpm_common.html#acceptmutex

SysVsemaphoresifprocessescrashbeforethesemaphoreisremoved.ItisonlyavailablewhentheunderlyingplatformandAPRsupportsit.

sem

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:

SSLv2

ThisistheSecureSocketsLayer(SSL)protocol,version2.0.ItistheoriginalSSLprotocolasdesignedbyNetscapeCorporation.

SSLv3

ThisistheSecureSocketsLayer(SSL)protocol,version3.0.ItisthesuccessortoSSLv2andthecurrently(asofFebruary1999)de-factostandardizedSSLprotocolfromNetscapeCorporation.It'ssupportedbyalmostallpopularbrowsers.

TLSv1

ThisistheTransportLayerSecurity(TLS)protocol,version1.0.ItisthesuccessortoSSLv3andcurrently(asofFebruary1999)stillunderconstructionbytheInternetEngineeringTaskForce(IETF).It'sstillnotsupportedbyanypopularbrowsers.

All

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-

path


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-

path


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

http://www.lothar.com/tech/crypto/

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

http://www.lothar.com/tech/crypto/

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

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:

none

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

<Location/server-status>


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

(NTP)

NTPIP

pid(ID) 32

httpd

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<[email protected]>inthenew-httpdarchives)

From:"ChristianAllen"<[email protected]>

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

httpd

<IfVersion2.1.0>

#currenthttpdversionisexactly2.1.0

</IfVersion>

<IfVersion>=2.2>

#usereallynewfeatures:-)

</IfVersion>

<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

<IfVersion>=2.1>

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

Note

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-

bin


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

pconf

subpoolofpermanent_poolcreatedatthebeginningofaconfig"cycle";existsuntiltheserveristerminatedorrestarts;passedtoallconfig-timeroutines,eitherviacmd->pool,orasthe"pool*p"argumentonthosewhichdon'ttakepoolspassedtothemoduleinit()functions

ptemp

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)

{

inti;

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;

++i;

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;

++i;

}

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

*url)

{

server_rec*s=cmd->server;

alias_server_conf*conf=(alias_server_conf*)

ap_get_module_config(s->module_config,&alias_module);

alias_entry*new=ap_push_array(conf->redirects);

if(!ap_is_url(url))return"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.

Note

Inordertousethevariousoptionstheservermustberebuiltaftereditingtheheaderfile.









DocumentingApache2.0

Apache2.0usesDoxygentodocumenttheAPIsandglobalvariablesinthecode.ThiswillexplainthebasicsofhowtodocumentusingDoxygen.

http://www.doxygen.org/

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.

http://www.doxygen.org/







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

APR

poolbecomesapr_pool_ttablebecomesapr_table_t

http://apr.apache.org/

…

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

(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

(URI)

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

r);

}

if(((access_status=ap_run_auth_checker(r))!=0)



?"checkaccess.Nogroupsfile?"


r);

}

}

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


r);

}

if(((access_status=ap_run_auth_checker(r))!=0)



?"checkaccess.Nogroupsfile?"


r);

}

}

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.

Asis

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

http://hoohoo.ncsa.uiuc.edu/cgi/overview.html

http://cgi-spec.golux.com/

→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

1 2()

3,4

A|B|C|D|E|F|G|H|I|K|L|M|N|O|P|R|

S|T|U|V|W|X

s

v

d

h .htaccess

C 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]...

All

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

auth

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

None

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

<DirectoryMatchregex>...</DirectoryMatch>

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

<Filesfilename>...</Files>

<FilesMatchregex>...</FilesMatch>

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

200

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

ProxyBlock*|word|host|domain[word|host|domain]...Words,hosts,ordomainsthatarebannedfrombeingproxied

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

URL

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

CGI

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

ServerTokensMajor|Minor|Min[imal]|Prod[uctOnly]|OS|Full

Full

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+

SSI

SSIStartTagtag "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:

http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html

#!/path/to/perl

##

##lb.pl--loadbalancingscript

##

$|=1;

$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

http://vegan.net/lb/

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


##

$|=1;

#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);


last;

}

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.


http://httpd.apache.org/docs/misc/FAQ.html

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?

http://httpd.apache.org/userslist.html

irc://irc.freenode.net/#httpd

http://freenode.net


http://groups.google.com/groups?group=comp.infosystems.www.servers.unix

news:comp.infosystems.www.servers.ms-windows

http://groups.google.com/groups?group=comp.infosystems.www.servers.ms-windows


http://groups.google.com/groups?group=comp.infosystems.www.authoring.cgi


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.


errno

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.

http://www.php.net/

LibraryList

Pleasedropanotetodev@httpd.apache.orgifyouhaveadditionsorcorrectionstothislist.

Library Version ThreadSafe?

Notes

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 ?

http://httpd.apache.org/lists.html#http-dev

http://aspell.sourceforge.net/

http://www.sleepycat.com/

http://sources.redhat.com/bzip2/index.html

http://cr.yp.to/cdb.html

http://www.washington.edu/imap/

http://www.fastio.com/

http://www.ijg.org/files/

http://expat.sourceforge.net/

http://www.freetds.org/

http://www.freetype.org/

http://www.boutell.com/gd/

http://www.boutell.com/gd/

http://www.gnu.org/software/gdbm/gdbm.html

http://www.imagemagick.org/

http://www.cise.ufl.edu/depot/www/ImageMagick/www/Changelog.html

http://www.enlightenment.org/pages/imlib2.html

http://www.ijg.org/files/



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.

http://mysql.com

http://www.mysql.com/doc/en/Threaded_clients.html

http://www.opaque.net/ming/

http://net-snmp.sourceforge.net/



http://www.oracle.com/

http://pdflib.com/

http://www.pdflib.com/products/pdflib/index.html

http://www.libpng.org/pub/png/libpng.html

http://www.libpng.org/pub/png/libpng.html

http://www.postgresql.org/idocs/index.php?libpq-threading.html

http://www.gingerall.com/charlie/ga/xml/p_sab.xml

http://www.gzip.org/zlib/







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/