Apache HTTP Server Version 2 · Apache > HTTP Server > Documentation > Version 2.0. Upgrading to...

Modules|Directives|FAQ|Glossary|Sitemap

ApacheHTTPServerVersion2.0Apache>HTTPServer>Documentation

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

ApacheHTTPServerVersion2.0Documentation

GoogleSearch

ReleaseNotes

NewfeatureswithApache2.0Upgradingto2.0from1.3ApacheLicense

ReferenceManual

CompilingandInstallingStartingStoppingorRestartingRun-timeConfigurationDirectivesDirectiveQuick-ReferenceModulesMulti-ProcessingModules(MPMs)FiltersHandlersServerandSupportingProgramsGlossary

Users'Guide

BindingConfigurationFilesConfigurationSectionsContentNegotiationDynamicSharedObjects(DSO)EnvironmentVariablesLogFilesMappingURLstotheFilesystemPerformanceTuningSecurityTipsServer-WideConfigurationSSL/TLSEncryptionSuexecExecutionforCGIURLRewritingGuideVirtualHosts

How-To/Tutorials

Authentication,Authorization,andAccessControlCGI:DynamicContent.htaccessfilesServerSideIncludes(SSI)Per-userWebDirectories(public_html)

PlatformSpecificNotes

MicrosoftWindowsNovellNetWareEBCDICPort

Copyright2013TheApacheSoftwareFoundation.LicensedundertheApacheLicense,Version2.0.


OtherTopics

FrequentlyAskedQuestionsSitemapDocumentationforDevelopersOtherNotes

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


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

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

Upgradingto2.0from1.3

Inordertoassistfolksupgrading,wemaintainadocumentdescribinginformationcriticaltoexistingApacheusers.Theseareintendedtobebriefnotes,andyoushouldbeabletofindmoreinformationineithertheNewFeaturesdocument,orinthesrc/CHANGESfile.

SeealsoOverviewofnewfeaturesinApache2.0

Compile-TimeConfigurationChanges

Apachenowusesanautoconfandlibtoolsystemforconfiguringthebuildprocesses.Usingthissystemissimilarto,butnotthesameas,usingtheAPACIsysteminApache1.3.Inadditiontotheusualselectionofmoduleswhichyoucanchoosetocompile,Apache2.0hasmovedthemainpartofrequestprocessingintoMulti-ProcessingModules(MPMs).

Run-TimeConfigurationChanges

ManydirectivesthatwereinthecoreserverinApache1.3arenowintheMPMs.IfyouwishthebehavioroftheservertobeassimilaraspossibletothebehaviorofApache1.3,youshouldselectthepreforkMPM.OtherMPMswillhavedifferentdirectivestocontrolprocesscreationandrequestprocessing.TheproxymodulehasbeenrevampedtobringituptoHTTP/1.1.Amongtheimportantchanges,proxyaccesscontrolisnowplacedinsideablockratherthanablock.ThehandlingofPATH_INFO(trailingpathinformationafterthetruefilename)haschangedforsomemodules.ModulesthatwerepreviouslyimplementedasahandlerbutarenowimplementedasafiltermaynolongeracceptrequestswithPATH_INFO.FilterssuchasINCLUDESorPHPareimplementedontopofthecorehandler,andthereforerejectrequestswithPATH_INFO.YoucanusetheAcceptPathInfodirectivetoforcethecorehandlertoacceptrequestswithPATH_INFOandtherebyrestoretheabilitytousePATH_INFOinserver-sideincludes.TheCacheNegotiatedDocsdirectivenowtakestheargumentonoroff.ExistinginstancesofCacheNegotiatedDocsshouldbereplacedwithCacheNegotiatedDocson.TheErrorDocumentdirectivenolongerusesaquoteatthebeginningoftheargumenttoindicateatextmessage.Instead,youshouldenclosethemessageindoublequotes.Forexample,existinginstancesof

ErrorDocument403"SomeMessage

shouldbereplacedwith

http://www.php.net/

ErrorDocument403"SomeMessage"

AslongasthesecondargumentisnotavalidURLorpathname,itwillbetreatedasatextmessage.TheAccessConfigandResourceConfigdirectivesnolongerexist.ExistinginstancesofthesedirectivescanbereplacedwiththeIncludedirectivewhichhasequivalentfunctionality.Ifyouweremakinguseofthedefaultvaluesofthesedirectiveswithoutincludingthemintheconfigurationfiles,youmayneedtoaddIncludeconf/access.confandIncludeconf/srm.conftoyourhttpd.conf.InordertoassurethatApachereadstheconfigurationfilesinthesameorderaswasimpliedbytheolderdirectives,theIncludedirectivesshouldbeplacedattheendofhttpd.conf,withtheoneforsrm.confprecedingtheoneforaccess.conf.TheBindAddressandPortdirectivesnolongerexist.EquivalentfunctionalityisprovidedwiththemoreflexibleListendirective.AnotheruseofthePortdirectiveinApache-1.3wassettingtheportnumbertobeusedinself-referentialURL's.TheApache-2.0equivalentisthenewServerNamesyntax:ithasbeenchangedtoallowspecifyingboththehostnameandtheportnumberforself-referentialURL'sinonedirective.TheServerTypedirectivenolongerexists.ThemethodusedtoserverequestsisnowdeterminedbytheselectionofMPM.ThereiscurrentlynoMPMdesignedtobelaunchedbyinetd.Themod_log_agentandmod_log_referermoduleswhichprovidedtheAgentLog,RefererLogandRefererIgnoredirectiveshavebeenremoved.AgentandrefererlogsarestillavailableusingtheCustomLogdirectiveofmod_log_config.

TheAddModuleandClearModuleListdirectivesnolongerexist.Thesedirectiveswereusedtoensurethatmodulescouldbeenabledinthecorrectorder.ThenewApache2.0APIallowsmodulestoexplicitlyspecifytheirordering,eliminatingtheneedforthesedirectives.TheFancyIndexingdirectivehasbeenremoved.ThesamefunctionalityisavailablethroughtheFancyIndexingoptiontotheIndexOptionsdirective.TheMultiViewscontent-negotiationtechniqueprovidedbymod_negotiationhasbecomemorestrictinitsdefaultfilematching.Itwillselectonlyfromnegotiablefiles.TheoldbehaviorcanberestoredusingtheMultiviewsMatchdirective.(sinceversion2.0.51)ThefunctionalityoftheErrorHeaderdirectivewasputtogetherwiththeHeaderdirective,sinceitwasamisnomer.Use

Headeralwayssetfoobar

insteadtogetthedesiredbehaviour.

MiscChanges

Themodulemod_auth_digest,whichwasexperimentalinApache1.3,isnowastandardmodule.Themod_mmap_staticmodule,whichwasexperimentalinApache1.3,hasbeenreplacedwithmod_file_cache.Thedistributionhasbeencompletelyreorganizedsothatitnolongercontainsanindependentsrcdirectory.Instead,thesourcesarelogicallyorganizedunderthemaindistributiondirectory,andinstallationsofthecompiledservershouldbedirectedtoaseparatedirectory.



ThirdPartyModules

ExtensivechangesweremadetotheserverAPIinApache2.0.ExistingmodulesdesignedfortheApache1.3APIwillnotworkinApache2.0withoutmodification.Detailsareprovidedinthedeveloperdocumentation.


OverviewofnewfeaturesinApache2.0

Thisdocumentdescribessomeofthemajorchangesbetweenthe1.3and2.0versionsoftheApacheHTTPServer.

SeealsoUpgradingto2.0from1.3

CoreEnhancements

UnixThreadingOnUnixsystemswithPOSIXthreadssupport,Apachecannowruninahybridmultiprocess,multithreadedmode.Thisimprovesscalabilityformany,butnotallconfigurations.

NewBuildSystemThebuildsystemhasbeenrewrittenfromscratchtobebasedonautoconfandlibtool.ThismakesApache'sconfigurationsystemmoresimilartothatofotherpackages.

MultiprotocolSupportApachenowhassomeoftheinfrastructureinplacetosupportservingmultipleprotocols.mod_echohasbeenwrittenasanexample.

Bettersupportfornon-UnixplatformsApache2.0isfasterandmorestableonnon-UnixplatformssuchasBeOS,OS/2,andWindows.Withtheintroductionofplatform-specificmulti-processingmodules(MPMs)andtheApachePortableRuntime(APR),theseplatformsarenowimplementedintheirnativeAPI,avoidingtheoftenbuggyandpoorlyperformingPOSIX-emulationlayers.

NewApacheAPITheAPIformoduleshaschangedsignificantlyfor2.0.Manyofthemodule-ordering/-priorityproblemsfrom1.3shouldbegone.2.0doesmuchofthisautomatically,andmoduleorderingisnowdoneper-hooktoallowmoreflexibility.Also,newcallshavebeenaddedthatprovideadditionalmodulecapabilitieswithoutpatchingthecoreApacheserver.

IPv6SupportOnsystemswhereIPv6issupportedbytheunderlyingApachePortableRuntimelibrary,ApachegetsIPv6listeningsocketsbydefault.Additionally,theListen,NameVirtualHost,andVirtualHostdirectivessupport

IPv6numericaddressstrings(e.g.,"Listen[2001:db8::1]:8080").

FilteringApachemodulesmaynowbewrittenasfilterswhichactonthestreamofcontentasitisdeliveredtoorfromtheserver.Thisallows,forexample,theoutputofCGIscriptstobeparsedforServerSideIncludedirectivesusingtheINCLUDESfilterinmod_include.Themodulemod_ext_filterallowsexternalprogramstoactasfiltersinmuchthesamewaythatCGIprogramscanactashandlers.

MultilanguageErrorResponsesErrorresponsemessagestothebrowserarenowprovidedinseverallanguages,usingSSIdocuments.Theymaybecustomizedbytheadministratortoachieveaconsistentlookandfeel.

SimplifiedconfigurationManyconfusingdirectiveshavebeensimplified.TheoftenconfusingPortandBindAddressdirectivesaregone;onlytheListendirectiveisusedforIPaddressbinding;theServerNamedirectivespecifiestheservernameandportnumberonlyforredirectionandvhostrecognition.

NativeWindowsNTUnicodeSupportApache2.0onWindowsNTnowusesutf-8forallfilenameencodings.ThesedirectlytranslatetotheunderlyingUnicodefilesystem,providingmultilanguagesupportforallWindowsNT-basedinstallations,includingWindows2000andWindowsXP.ThissupportdoesnotextendtoWindows95,98orME,whichcontinuetousethemachine'slocalcodepageforfilesystemaccess.

RegularExpressionLibraryUpdatedApache2.0includesthePerlCompatibleRegularExpressionLibrary(PCRE).Allregularexpressionevaluationnowuses

http://www.pcre.org/

themorepowerfulPerl5syntax.

ModuleEnhancements

mod_sslNewmoduleinApache2.0.ThismoduleisaninterfacetotheSSL/TLSencryptionprotocolsprovidedbyOpenSSL.

mod_davNewmoduleinApache2.0.ThismoduleimplementstheHTTPDistributedAuthoringandVersioning(DAV)specificationforpostingandmaintainingwebcontent.

mod_deflateNewmoduleinApache2.0.Thismoduleallowssupportingbrowserstorequestthatcontentbecompressedbeforedelivery,savingnetworkbandwidth.

mod_auth_ldapNewmoduleinApache2.0.41.ThismoduleallowsanLDAPdatabasetobeusedtostorecredentialsforHTTPBasicAuthentication.Acompanionmodule,mod_ldapprovidesconnectionpoolingandresultscaching.

mod_auth_digestIncludesadditionalsupportforsessioncachingacrossprocessesusingsharedmemory.

mod_charset_liteNewmoduleinApache2.0.Thisexperimentalmoduleallowsforcharactersettranslationorrecoding.

mod_file_cacheNewmoduleinApache2.0.Thismoduleincludesthefunctionalityofmod_mmap_staticinApache1.3,plusaddsfurthercachingabilities.

mod_headersThismoduleismuchmoreflexibleinApache2.0.Itcannowmodifyrequestheadersusedbymod_proxy,anditcanconditionallysetresponseheaders.

mod_proxyTheproxymodulehasbeencompletelyrewrittentotakeadvantageofthenewfilterinfrastructureandtoimplementamorereliable,HTTP/1.1compliantproxy.Inaddition,newconfigurationsectionsprovidemorereadable(andinternallyfaster)controlofproxiedsites;overloadedconfigurationarenotsupported.Themoduleisnowdividedintospecificprotocolsupportmodulesincludingproxy_connect,proxy_ftpandproxy_http.

mod_negotiationAnewForceLanguagePrioritydirectivecanbeusedtoassurethattheclientreceivesasingledocumentinallcases,ratherthanNOTACCEPTABLEorMULTIPLECHOICESresponses.Inaddition,thenegotiationandMultiViewsalgorithmshavebeencleaneduptoprovidemoreconsistentresultsandanewformoftypemapthatcanincludedocumentcontentisprovided.

mod_autoindexAutoindex'eddirectorylistingscannowbeconfiguredtouseHTMLtablesforcleanerformatting,andallowfiner-grainedcontrolofsorting,includingversion-sorting,andwildcardfilteringofthedirectorylisting.

mod_includeNewdirectivesallowthedefaultstartandendtagsforSSIelementstobechangedandallowforerrorandtimeformatconfigurationtotakeplaceinthemainconfigurationfileratherthanintheSSIdocument.Resultsfromregularexpressionparsingandgrouping(nowbasedonPerl'sregularexpressionsyntax)canberetrievedusingmod_include'svariables$0..$9.

mod_auth_dbm



NowsupportsmultipletypesofDBM-likedatabasesusingtheAuthDBMTypedirective.


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,softwaredistributedundertheLicenseisdistributedonan"ASIS"BASIS,WITHOUTWARRANTIESORCONDITIONSOFANYKIND,eitherexpressorimplied.SeetheLicenseforthespecificlanguagegoverningpermissionsandlimitationsundertheLicense.


CompilingandInstalling

ThisdocumentcoverscompilationandinstallationofApacheonUnixandUnix-likesystemsonly.ForcompilingandinstallationonWindows,seeUsingApachewithMicrosoftWindows.Forotherplatforms,seetheplatformdocumentation.

Apache2.0'sconfigurationandinstallationenvironmenthaschangedcompletelyfromApache1.3.Apache1.3usedacustomsetofscriptstoachieveeasyinstallation.Apache2.0nowuseslibtoolandautoconftocreateanenvironmentthatlookslikemanyotherOpenSourceprojects.

Ifyouareupgradingfromoneminorversiontothenext(forexample,2.0.50to2.0.51),pleaseskipdowntotheupgradingsection.

SeealsoConfigurethesourcetreeStartingApacheStoppingandRestarting

Overviewfortheimpatient

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

Extract $gzip-dhttpd-2_0_NN.tar.gz$tarxvfhttpd-2_0_NN.tar

Configure $./configure--prefix=PREFIXCompile $makeInstall $makeinstallCustomize $viPREFIX/conf/httpd.confTest $PREFIX/bin/apachectlstart

NNmustbereplacedwiththecurrentminorversionnumber,andPREFIXmustbereplacedwiththefilesystempathunderwhichtheservershouldbeinstalled.IfPREFIXisnotspecified,itdefaultsto/usr/local/apache2.

Eachsectionofthecompilationandinstallationprocessisdescribedinmoredetailbelow,beginningwiththerequirementsforcompilingandinstallingApacheHTTPD.

Requirements

ThefollowingrequirementsexistforbuildingApache:

DiskSpaceMakesureyouhaveatleast50MBoftemporaryfreediskspaceavailable.AfterinstallationApacheoccupiesapproximately10MBofdiskspace.Theactualdiskspacerequirementswillvaryconsiderablybasedonyourchosenconfigurationoptionsandanythird-partymodules.

ANSI-CCompilerandBuildSystemMakesureyouhaveanANSI-Ccompilerinstalled.TheGNUCcompiler(GCC)fromtheFreeSoftwareFoundation(FSF)isrecommended(version2.7.2isfine).Ifyoudon'thaveGCCthenatleastmakesureyourvendor'scompilerisANSIcompliant.Inaddition,yourPATHmustcontainbasicbuildtoolssuchasmake.

AccuratetimekeepingElementsoftheHTTPprotocolareexpressedasthetimeofday.So,it'stimetoinvestigatesettingsometimesynchronizationfacilityonyoursystem.UsuallythentpdateorxntpdprogramsareusedforthispurposewhicharebasedontheNetworkTimeProtocol(NTP).SeetheUsenetnewsgroupcomp.protocols.time.ntpandtheNTPhomepageformoredetailsaboutNTPsoftwareandpublictimeservers.

Perl5[OPTIONAL]Forsomeofthesupportscriptslikeapxsordbmmanage(whicharewritteninPerl)thePerl5interpreterisrequired(versions5.003orneweraresufficient).IfyouhavemultiplePerlinterpreters(forexample,asystemwideinstallofPerl4,andyourowninstallofPerl5),youareadvisedtousethe--with-perloption(seebelow)tomakesurethecorrectoneisusedbyconfigure.IfnoPerl5interpreterisfoundbytheconfigurescript,youwillnotbeabletousetheaffected

http://www.gnu.org/software/gcc/gcc.htmlhttp://www.gnu.org/news:comp.protocols.time.ntphttp://www.ntp.orghttp://www.perl.org/

supportscripts.Ofcourse,youwillstillbeabletobuildanduseApache2.0.

Download

ApachecanbedownloadedfromtheApacheHTTPServerdownloadsitewhichlistsseveralmirrors.MostusersofApacheonunix-likesystemswillbebetteroffdownloadingandcompilingasourceversion.Thebuildprocess(describedbelow)iseasy,anditallowsyoutocustomizeyourservertosuityourneeds.Inaddition,binaryreleasesareoftennotuptodatewiththelatestsourcereleases.Ifyoudodownloadabinary,followtheinstructionsintheINSTALL.bindistfileinsidethedistribution.

Afterdownloading,itisimportanttoverifythatyouhaveacompleteandunmodifiedversionoftheApacheHTTPServer.ThiscanbeaccomplishedbytestingthedownloadedtarballagainstthePGPsignature.DetailsonhowtodothisareavailableonthedownloadpageandanextendedexampleisavailabledescribingtheuseofPGP.

http://httpd.apache.org/download.cgihttp://httpd.apache.org/download.cgi#verifyhttp://httpd.apache.org/dev/verification.html

Extract

ExtractingthesourcefromtheApacheHTTPDtarballisasimplematterofuncompressing,andthenuntarring:

$gzip-dhttpd-2_0_NN.tar.gz$tarxvfhttpd-2_0_NN.tar

Thiswillcreateanewdirectoryunderthecurrentdirectorycontainingthesourcecodeforthedistribution.Youshouldcdintothatdirectorybeforeproceedingwithcompilingtheserver.

Configuringthesourcetree

ThenextstepistoconfiguretheApachesourcetreeforyourparticularplatformandpersonalrequirements.Thisisdoneusingthescriptconfigureincludedintherootdirectoryofthedistribution.(DevelopersdownloadingtheCVSversionoftheApachesourcetreewillneedtohaveautoconfandlibtoolinstalledandwillneedtorunbuildconfbeforeproceedingwiththenextsteps.Thisisnotnecessaryforofficialreleases.)

Toconfigurethesourcetreeusingallthedefaultoptions,simplytype./configure.Tochangethedefaultoptions,configureacceptsavarietyofvariablesandcommandlineoptions.

Themostimportantoptionisthelocation--prefixwhereApacheistobeinstalledlater,becauseApachehastobeconfiguredforthislocationtoworkcorrectly.Morefine-tunedcontrolofthelocationoffilesispossiblewithadditionalconfigureoptions.

Alsoatthispoint,youcanspecifywhichfeaturesyouwantincludedinApachebyenablinganddisablingmodules.ApachecomeswithaBasesetofmodulesincludedbydefault.Othermodulesareenabledusingthe--enable-moduleoption,wheremoduleisthenameofthemodulewiththemod_stringremovedandwithanyunderscoreconvertedtoadash.Youcanalsochoosetocompilemodulesassharedobjects(DSOs)--whichcanbeloadedorunloadedatruntime--byusingtheoption--enable-module=shared.Similarly,youcandisableBasemoduleswiththe--disable-moduleoption.Becarefulwhenusingtheseoptions,sinceconfigurecannotwarnyouifthemoduleyouspecifydoesnotexist;itwillsimplyignoretheoption.

Inaddition,itissometimesnecessarytoprovidetheconfigurescriptwithextrainformationaboutthelocationofyourcompiler,

libraries,orheaderfiles.Thisisdonebypassingeitherenvironmentvariablesorcommandlineoptionstoconfigure.Formoreinformation,seetheconfiguremanualpage.

Forashortimpressionofwhatpossibilitiesyouhave,hereisatypicalexamplewhichcompilesApachefortheinstallationtree/sw/pkg/apachewithaparticularcompilerandflagsplusthetwoadditionalmodulesmod_rewriteandmod_spelingforlaterloadingthroughtheDSOmechanism:

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

WhenconfigureisrunitwilltakeseveralminutestotestfortheavailabilityoffeaturesonyoursystemandbuildMakefileswhichwilllaterbeusedtocompiletheserver.

Detailsonallthedifferentconfigureoptionsareavailableontheconfiguremanualpage.

Build

NowyoucanbuildthevariouspartswhichformtheApachepackagebysimplyrunningthecommand:

$make

Pleasebepatienthere,sinceabaseconfigurationtakesapproximately3minutestocompileunderaPentiumIII/Linux2.2system,butthiswillvarywidelydependingonyourhardwareandthenumberofmoduleswhichyouhaveenabled.

Install

Nowit'stimetoinstallthepackageundertheconfiguredinstallationPREFIX(see--prefixoptionabove)byrunning:

$makeinstall

Ifyouareupgrading,theinstallationwillnotoverwriteyourconfigurationfilesordocuments.

Customize

Next,youcancustomizeyourApacheHTTPserverbyeditingtheconfigurationfilesunderPREFIX/conf/.

$viPREFIX/conf/httpd.conf

HavealookattheApachemanualunderdocs/manual/orconsulthttp://httpd.apache.org/docs/2.0/forthemostrecentversionofthismanualandacompletereferenceofavailableconfigurationdirectives.

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

Test

NowyoucanstartyourApacheHTTPserverbyimmediatelyrunning:

$PREFIX/bin/apachectlstart

andthenyoushouldbeabletorequestyourfirstdocumentviaURLhttp://localhost/.ThewebpageyouseeislocatedundertheDocumentRootwhichwillusuallybePREFIX/htdocs/.Thenstoptheserveragainbyrunning:

$PREFIX/bin/apachectlstop

Upgrading

ThefirststepinupgradingistoreadthereleaseannouncementandthefileCHANGESinthesourcedistributiontofindanychangesthatmayaffectyoursite.Whenchangingbetweenmajorreleases(forexample,from1.3to2.0orfrom2.0to2.2),therewilllikelybemajordifferencesinthecompile-timeandrun-timeconfigurationthatwillrequiremanualadjustments.AllmoduleswillalsoneedtobeupgradedtoaccomodatechangesinthemoduleAPI.

Upgradingfromoneminorversiontothenext(forexample,from2.0.55to2.0.57)iseasier.Themakeinstallprocesswillnotoverwriteanyofyourexistingdocuments,logfiles,orconfigurationfiles.Inaddition,thedevelopersmakeeveryefforttoavoidincompatiblechangesintheconfigureoptions,run-timeconfiguration,orthemoduleAPIbetweenminorversions.Inmostcasesyoushouldbeabletouseanidenticalconfigurecommandline,anidenticalconfigurationfile,andallofyourmodulesshouldcontinuetowork.(Thisisonlyvalidforversionsafter2.0.41;earlierversionshaveincompatiblechanges.)

Toupgradeacrossminorversions,startbyfindingthefileconfig.niceinthebuilddirectoryofyourinstalledserverorattherootofthesourcetreeforyouroldinstall.Thiswillcontaintheexactconfigurecommandlinethatyouusedtoconfigurethesourcetree.Thentoupgradefromoneversiontothenext,youneedonlycopytheconfig.nicefiletothesourcetreeofthenewversion,editittomakeanydesiredchanges,andthenrun:

$./config.nice$make$makeinstall$PREFIX/bin/apachectlstop$PREFIX/bin/apachectlstart

Youshouldalwaystestanynewversioninyourenvironment



beforeputtingitintoproduction.Forexample,youcaninstallandrunthenewversionalongsidetheoldonebyusingadifferent--prefixandadifferentport(byadjustingtheListendirective)totestforanyincompatibilitiesbeforedoingthefinalupgrade.


StartingApache

OnWindows,ApacheisnormallyrunasaserviceonWindowsNT,2000andXP,orasaconsoleapplicationonWindows9xandME.Fordetails,seeRunningApacheasaServiceandRunningApacheasaConsoleApplication.

OnUnix,thehttpdprogramisrunasadaemonthatexecutescontinuouslyinthebackgroundtohandlerequests.Thisdocumentdescribeshowtoinvokehttpd.

SeealsoStoppingandRestartinghttpdapachectl

HowApacheStarts

IftheListenspecifiedintheconfigurationfileisdefaultof80(oranyotherportbelow1024),thenitisnecessarytohaverootprivilegesinordertostartapache,sothatitcanbindtothisprivilegedport.Oncetheserverhasstartedandperformedafewpreliminaryactivitiessuchasopeningitslogfiles,itwilllaunchseveralchildprocesseswhichdotheworkoflisteningforandansweringrequestsfromclients.Themainhttpdprocesscontinuestorunastherootuser,butthechildprocessesrunasalessprivilegeduser.ThisiscontrolledbytheselectedMulti-ProcessingModule.

Therecommendedmethodofinvokingthehttpdexecutableistousetheapachectlcontrolscript.Thisscriptsetscertainenvironmentvariablesthatarenecessaryforhttpdtofunctioncorrectlyundersomeoperatingsystems,andtheninvokesthehttpdbinary.apachectlwillpassthroughanycommandlinearguments,soanyhttpdoptionsmayalsobeusedwithapachectl.YoumayalsodirectlyedittheapachectlscriptbychangingtheHTTPDvariablenearthetoptospecifythecorrectlocationofthehttpdbinaryandanycommand-lineargumentsthatyouwishtobealwayspresent.

Thefirstthingthathttpddoeswhenitisinvokedistolocateandreadtheconfigurationfilehttpd.conf.Thelocationofthisfileissetatcompile-time,butitispossibletospecifyitslocationatruntimeusingthe-fcommand-lineoptionasin

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

Ifallgoeswellduringstartup,theserverwilldetachfromtheterminalandthecommandpromptwillreturnalmostimmediately.Thisindicatesthattheserverisupandrunning.Youcanthenuse

yourbrowsertoconnecttotheserverandviewthetestpageintheDocumentRootdirectoryandthelocalcopyofthedocumentationlinkedfromthatpage.

ErrorsDuringStart-up

IfApachesuffersafatalproblemduringstartup,itwillwriteamessagedescribingtheproblemeithertotheconsoleortotheErrorLogbeforeexiting.Oneofthemostcommonerrormessagesis"UnabletobindtoPort...".Thismessageisusuallycausedbyeither:

Tryingtostarttheserveronaprivilegedportwhennotloggedinastherootuser;orTryingtostarttheserverwhenthereisanotherinstanceofApacheorsomeotherwebserveralreadyboundtothesamePort.

Forfurthertrouble-shootinginstructions,consulttheApacheFAQ.

StartingatBoot-Time

Ifyouwantyourservertocontinuerunningafterasystemreboot,youshouldaddacalltoapachectltoyoursystemstartupfiles(typicallyrc.localorafileinanrc.Ndirectory).ThiswillstartApacheasroot.Beforedoingthisensurethatyourserverisproperlyconfiguredforsecurityandaccessrestrictions.

TheapachectlscriptisdesignedtoactlikeastandardSysVinitscript;itcantaketheargumentsstart,restart,andstopandtranslatethemintotheappropriatesignalstohttpd.Soyoucanoftensimplylinkapachectlintotheappropriateinitdirectory.Butbesuretochecktheexactrequirementsofyoursystem.



AdditionalInformation

Additionalinformationaboutthecommand-lineoptionsofhttpdandapachectlaswellasothersupportprogramsincludedwiththeserverisavailableontheServerandSupportingProgramspage.ThereisalsodocumentationonallthemodulesincludedwiththeApachedistributionandthedirectivesthattheyprovide.


StoppingandRestarting

ThisdocumentcoversstoppingandrestartingApacheonUnix-likesystems.WindowsNT,2000andXPusersshouldseeRunningApacheasaServiceandWindows9xandMEusersshouldseeRunningApacheasaConsoleApplicationforinformationonhowtocontrolApacheonthoseplatforms.

SeealsohttpdapachectlStarting

Introduction

InordertostoporrestartApache,youmustsendasignaltotherunninghttpdprocesses.Therearetwowaystosendthesignals.First,youcanusetheunixkillcommandtodirectlysendsignalstotheprocesses.Youwillnoticemanyhttpdexecutablesrunningonyoursystem,butyoushouldnotsendsignalstoanyofthemexcepttheparent,whosepidisinthePidFile.Thatistosayyoushouldn'teverneedtosendsignalstoanyprocessexcepttheparent.Therearethreesignalsthatyoucansendtheparent:TERM,HUP,andUSR1,whichwillbedescribedinamoment.

Tosendasignaltotheparentyoushouldissueacommandsuchas:

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

Thesecondmethodofsignalingthehttpdprocessesistousethe-kcommandlineoptions:stop,restart,andgraceful,asdescribedbelow.Theseareargumentstothehttpdbinary,butwerecommendthatyousendthemusingtheapachectlcontrolscript,whichwillpassthemthroughtohttpd.

Afteryouhavesignaledhttpd,youcanreadaboutitsprogressbyissuing:

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

ModifythoseexamplestomatchyourServerRootandPidFilesettings.

StopNow

Signal:TERMapachectl-kstop

SendingtheTERMorstopsignaltotheparentcausesittoimmediatelyattempttokilloffallofitschildren.Itmaytakeitseveralsecondstocompletekillingoffitschildren.Thentheparentitselfexits.Anyrequestsinprogressareterminated,andnofurtherrequestsareserved.

GracefulRestart

Signal:USR1apachectl-kgraceful

TheUSR1orgracefulsignalcausestheparentprocesstoadvisethechildrentoexitaftertheircurrentrequest(ortoexitimmediatelyifthey'renotservinganything).Theparentre-readsitsconfigurationfilesandre-opensitslogfiles.Aseachchilddiesofftheparentreplacesitwithachildfromthenewgenerationoftheconfiguration,whichbeginsservingnewrequestsimmediately.

OncertainplatformsthatdonotallowUSR1tobeusedforagracefulrestart,analternativesignalmaybeused(suchasWINCH).Thecommandapachectlgracefulwillsendtherightsignalforyourplatform.

ThiscodeisdesignedtoalwaysrespecttheprocesscontroldirectiveoftheMPMs,sothenumberofprocessesandthreadsavailabletoserveclientswillbemaintainedattheappropriatevaluesthroughouttherestartprocess.Furthermore,itrespectsStartServersinthefollowingmanner:ifafteronesecondatleastStartServersnewchildrenhavenotbeencreated,thencreateenoughtopickuptheslack.Hencethecodetriestomaintainboththenumberofchildrenappropriateforthecurrentloadontheserver,andrespectyourwisheswiththeStartServersparameter.

Usersofmod_statuswillnoticethattheserverstatisticsarenotsettozerowhenaUSR1issent.Thecodewaswrittentobothminimizethetimeinwhichtheserverisunabletoservenewrequests(theywillbequeuedupbytheoperatingsystem,sothey'renotlostinanyevent)andtorespectyourtuningparameters.Inordertodothisithastokeepthescoreboardusedtokeeptrackofallchildrenacrossgenerations.

ThestatusmodulewillalsouseaGtoindicatethosechildrenwhicharestillservingrequestsstartedbeforethegracefulrestartwasgiven.

AtpresentthereisnowayforalogrotationscriptusingUSR1toknowforcertainthatallchildrenwritingthepre-restartloghavefinished.WesuggestthatyouuseasuitabledelayaftersendingtheUSR1signalbeforeyoudoanythingwiththeoldlog.Forexampleifmostofyourhitstakelessthan10minutestocompleteforusersonlowbandwidthlinksthenyoucouldwait15minutesbeforedoinganythingwiththeoldlog.

Ifyourconfigurationfilehaserrorsinitwhenyouissuearestartthenyourparentwillnotrestart,itwillexitwithanerror.Inthecaseofgracefulrestartsitwillalsoleavechildrenrunningwhenitexits.(Thesearethechildrenwhichare"gracefullyexiting"byhandlingtheirlastrequest.)Thiswillcauseproblemsifyouattempttorestarttheserver--itwillnotbeabletobindtoitslisteningports.Beforedoingarestart,youcancheckthesyntaxoftheconfigurationfileswiththe-tcommandlineargument(seehttpd).Thisstillwillnotguaranteethattheserverwillrestartcorrectly.Tocheckthesemanticsoftheconfigurationfilesaswellasthesyntax,youcantrystartinghttpdasanon-rootuser.Iftherearenoerrorsitwillattempttoopenitssocketsandlogsandfailbecauseit'snotroot(orbecausethecurrentlyrunninghttpdalreadyhasthoseportsbound).Ifitfailsforanyotherreasonthenit'sprobablyaconfigfileerrorandtheerrorshouldbefixedbeforeissuingthegracefulrestart.

RestartNow

Signal:HUPapachectl-krestart

SendingtheHUPorrestartsignaltotheparentcausesittokilloffitschildrenlikeinTERM,buttheparentdoesn'texit.Itre-readsitsconfigurationfiles,andre-opensanylogfiles.Thenitspawnsanewsetofchildrenandcontinuesservinghits.

Usersofmod_statuswillnoticethattheserverstatisticsaresettozerowhenaHUPissent.

Ifyourconfigurationfilehaserrorsinitwhenyouissuearestartthenyourparentwillnotrestart,itwillexitwithanerror.Seeaboveforamethodofavoidingthis.


Appendix:signalsandraceconditions

PriortoApache1.2b9therewereseveralraceconditionsinvolvingtherestartanddiesignals(asimplyput,araceconditionisatime-sensitiveproblem-ifsomethinghappensatjustthewrongtimeorthingshappeninthewrongorder,undesiredbehaviourwillresult.Ifthesamethinghappensattherighttime,allwillbewell).Forthosearchitecturesthathavethe"right"featuresetwehaveeliminatedasmanyaswecan.Butitshouldbenotedthatraceconditionsdostillexistoncertainarchitectures.

Architecturesthatuseanon-diskScoreBoardFilecanpotentiallyhavetheirscoreboardscorrupted.Thiscanresultinthe"bind:Addressalreadyinuse"(afterHUP)or"longlostchildcamehome!"(afterUSR1).Theformerisafatalerror,whilethelatterjustcausestheservertoloseascoreboardslot.Soitmaybeadvisabletousegracefulrestarts,withanoccasionalhardrestart.Theseproblemsareverydifficulttoworkaround,butfortunatelymostarchitecturesdonotrequireascoreboardfile.SeetheScoreBoardFiledocumentationforarchitecturewhichusesit.

AllarchitectureshaveasmallraceconditionineachchildinvolvingthesecondandsubsequentrequestsonapersistentHTTPconnection(KeepAlive).Itmayexitafterreadingtherequestlinebutbeforereadinganyoftherequestheaders.Thereisafixthatwasdiscoveredtoolatetomake1.2.Intheorythisisn'tanissuebecausetheKeepAliveclienthastoexpecttheseeventsbecauseofnetworklatenciesandservertimeouts.Inpracticeitdoesn'tseemtoaffectanythingeither--inatestcasetheserverwasrestartedtwentytimespersecondandclientssuccessfullybrowsedthesitewithoutgettingbrokenimagesoremptydocuments.


ConfigurationFiles

ThisdocumentdescribesthefilesusedtoconfiguretheApacheHTTPserver.

MainConfigurationFiles

RelatedModules RelatedDirectivesmod_mime

IncludeTypesConfig

Apacheisconfiguredbyplacingdirectivesinplaintextconfigurationfiles.Themainconfigurationfileisusuallycalledhttpd.conf.Thelocationofthisfileissetatcompile-time,butmaybeoverriddenwiththe-fcommandlineflag.Inaddition,otherconfigurationfilesmaybeaddedusingtheIncludedirective,andwildcardscanbeusedtoincludemanyconfigurationfiles.Anydirectivemaybeplacedinanyoftheseconfigurationfiles.ChangestothemainconfigurationfilesareonlyrecognizedbyApachewhenitisstartedorrestarted.

Theserveralsoreadsafilecontainingmimedocumenttypes;thefilenameissetbytheTypesConfigdirective,andismime.typesbydefault.

SyntaxoftheConfigurationFiles

Apacheconfigurationfilescontainonedirectiveperline.Thebackslash"\"maybeusedasthelastcharacteronalinetoindicatethatthedirectivecontinuesontothenextline.Theremustbenoothercharactersorwhitespacebetweenthebackslashandtheendoftheline.

Directivesintheconfigurationfilesarecase-insensitive,butargumentstodirectivesareoftencasesensitive.Linesthatbeginwiththehashcharacter"#"areconsideredcomments,andareignored.Commentsmaynotbeincludedonalineafteraconfigurationdirective.Blanklinesandwhitespaceoccurringbeforeadirectiveareignored,soyoumayindentdirectivesforclarity.

Youcancheckyourconfigurationfilesforsyntaxerrorswithoutstartingtheserverbyusingapachectlconfigtestorthe-tcommandlineoption.

Modules

RelatedModules RelatedDirectivesmod_so

LoadModule

Apacheisamodularserver.Thisimpliesthatonlythemostbasicfunctionalityisincludedinthecoreserver.ExtendedfeaturesareavailablethroughmoduleswhichcanbeloadedintoApache.Bydefault,abasesetofmodulesisincludedintheserveratcompile-time.Iftheserveriscompiledtousedynamicallyloadedmodules,thenmodulescanbecompiledseparatelyandaddedatanytimeusingtheLoadModuledirective.Otherwise,Apachemustberecompiledtoaddorremovemodules.Configurationdirectivesmaybeincludedconditionalonapresenceofaparticularmodulebyenclosingtheminanblock.

Toseewhichmodulesarecurrentlycompiledintotheserver,youcanusethe-lcommandlineoption.

ScopeofDirectives

RelatedModules RelatedDirectives

Directivesplacedinthemainconfigurationfilesapplytotheentireserver.Ifyouwishtochangetheconfigurationforonlyapartoftheserver,youcanscopeyourdirectivesbyplacingthemin,,,,,andsections.ThesesectionslimittheapplicationofthedirectiveswhichtheyenclosetoparticularfilesystemlocationsorURLs.Theycanalsobenested,allowingforveryfinegrainedconfiguration.

Apachehasthecapabilitytoservemanydifferentwebsitessimultaneously.ThisiscalledVirtualHosting.Directivescanalsobescopedbyplacingtheminsidesections,sothattheywillonlyapplytorequestsforaparticularwebsite.

Althoughmostdirectivescanbeplacedinanyofthesesections,somedirectivesdonotmakesenseinsomecontexts.Forexample,directivescontrollingprocesscreationcanonlybeplacedinthemainservercontext.Tofindwhichdirectivescanbeplacedinwhichsections,checktheContextofthedirective.Forfurtherinformation,weprovidedetailsonHowDirectory,LocationandFilessectionswork.



.htaccessFiles

RelatedModules RelatedDirectivesAccessFileNameAllowOverride

Apacheallowsfordecentralizedmanagementofconfigurationviaspecialfilesplacedinsidethewebtree.Thespecialfilesareusuallycalled.htaccess,butanynamecanbespecifiedintheAccessFileNamedirective.Directivesplacedin.htaccessfilesapplytothedirectorywhereyouplacethefile,andallsub-directories.The.htaccessfilesfollowthesamesyntaxasthemainconfigurationfiles.Since.htaccessfilesarereadoneveryrequest,changesmadeinthesefilestakeimmediateeffect.

Tofindwhichdirectivescanbeplacedin.htaccessfiles,checktheContextofthedirective.Theserveradministratorfurthercontrolswhatdirectivesmaybeplacedin.htaccessfilesbyconfiguringtheAllowOverridedirectiveinthemainconfigurationfiles.

Formoreinformationon.htaccessfiles,seethe.htaccesstutorial.


ConfigurationSections

Directivesintheconfigurationfilesmayapplytotheentireserver,ortheymayberestrictedtoapplyonlytoparticulardirectories,files,hosts,orURLs.Thisdocumentdescribeshowtouseconfigurationsectioncontainersor.htaccessfilestochangethescopeofotherconfigurationdirectives.

TypesofConfigurationSectionContainers

RelatedModules RelatedDirectivescoremod_proxy

Therearetwobasictypesofcontainers.Mostcontainersareevaluatedforeachrequest.Theencloseddirectivesareappliedonlyforthoserequeststhatmatchthecontainers.Theandcontainers,ontheotherhand,areevaluatedonlyatserverstartupandrestart.Iftheirconditionsaretrueatstartup,thentheencloseddirectiveswillapplytoallrequests.Iftheconditionsarenottrue,theencloseddirectiveswillbeignored.

Thedirectiveenclosesdirectivesthatwillonlybeappliedifanappropriateparameterisdefinedonthehttpdcommandline.Forexample,withthefollowingconfiguration,allrequestswillberedirectedtoanothersiteonlyiftheserverisstartedusinghttpd-DClosedForNow:

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

Thedirectiveisverysimilar,exceptitenclosesdirectivesthatwillonlybeappliedifaparticularmoduleisavailableintheserver.Themodulemusteitherbestaticallycompiledintheserver,oritmustbedynamicallycompiledanditsLoadModulelinemustbeearlierintheconfigurationfile.Thisdirectiveshouldonlybeusedifyouneedyourconfigurationfiletoworkwhetherornotcertainmodulesareinstalled.Itshouldnotbeusedtoenclosedirectivesthatyouwanttoworkallthetime,becauseitcansuppressusefulerrormessagesaboutmissingmodules.

Inthefollowingexample,theMimeMagicFilesdirectivewillbeappliedonlyifmod_mime_magicisavailable.

MimeMagicFileconf/magic

Bothandcanapplynegativeconditionsbyprecedingtheirtestwith"!".Also,thesesectionscanbenestedtoachievemorecomplexrestrictions.

FilesystemandWebspace

Themostcommonlyusedconfigurationsectioncontainersaretheonesthatchangetheconfigurationofparticularplacesinthefilesystemorwebspace.First,itisimportanttounderstandthedifferencebetweenthetwo.Thefilesystemistheviewofyourdisksasseenbyyouroperatingsystem.Forexample,inadefaultinstall,Apacheresidesat/usr/local/apache2intheUnixfilesystemor"c:/ProgramFiles/ApacheGroup/Apache2"intheWindowsfilesystem.(NotethatforwardslashesshouldalwaysbeusedasthepathseparatorinApache,evenforWindows.)Incontrast,thewebspaceistheviewofyoursiteasdeliveredbythewebserverandseenbytheclient.Sothepath/dir/inthewebspacecorrespondstothepath/usr/local/apache2/htdocs/dir/inthefilesystemofadefaultApacheinstallonUnix.Thewebspaceneednotmapdirectlytothefilesystem,sincewebpagesmaybegenerateddynamicallyfromdatabasesorotherlocations.

FilesystemContainersTheanddirectives,alongwiththeirregexcounterparts,applydirectivestopartsofthefilesystem.Directivesenclosedinasectionapplytothenamedfilesystemdirectoryandallsubdirectoriesofthatdirectory.Thesameeffectcanbeobtainedusing.htaccessfiles.Forexample,inthefollowingconfiguration,directoryindexeswillbeenabledforthe/var/web/dir1directoryandallsubdirectories.

Options+Indexes

Directivesenclosedinasectionapplytoanyfilewiththespecifiedname,regardlessofwhatdirectoryitliesin.Soforexample,thefollowingconfigurationdirectiveswill,whenplacedin

themainsectionoftheconfigurationfile,denyaccesstoanyfilenamedprivate.htmlregardlessofwhereitisfound.

Orderallow,denyDenyfromall

Toaddressfilesfoundinaparticularpartofthefilesystem,theandsectionscanbecombined.Forexample,thefollowingconfigurationwilldenyaccessto/var/web/dir1/private.html,/var/web/dir1/subdir2/private.html,/var/web/dir1/subdir3/private.html,andanyotherinstanceofprivate.htmlfoundunderthe/var/web/dir1/directory.


WebspaceContainersThedirectiveanditsregexcounterpart,ontheotherhand,changetheconfigurationforcontentinthewebspace.Forexample,thefollowingconfigurationpreventsaccesstoanyURL-paththatbeginsin/private.Inparticular,itwillapplytorequestsforhttp://yoursite.example.com/private,http://yoursite.example.com/private123,andhttp://yoursite.example.com/private/dir/file.htmlaswellasanyotherrequestsstartingwiththe/privatestring.

OrderAllow,Deny

Denyfromall

Thedirectiveneednothaveanythingtodowiththefilesystem.Forexample,thefollowingexampleshowshowtomapaparticularURLtoaninternalApachehandlerprovidedbymod_status.Nofilecalledserver-statusneedstoexistinthefilesystem.

SetHandlerserver-status

WildcardsandRegularExpressionsThe,,anddirectivescaneachuseshell-stylewildcardcharactersasinfnmatchfromtheCstandardlibrary.Thecharacter"*"matchesanysequenceofcharacters,"?"matchesanysinglecharacter,and"[seq]"matchesanycharacterinseq.The"/"characterwillnotbematchedbyanywildcard;itmustbespecifiedexplicitly.

Ifevenmoreflexiblematchingisrequired,eachcontainerhasaregular-expression(regex)counterpart,,andthatallowperl-compatibleregularexpressionstobeusedinchoosingthematches.Butseethesectionbelowonconfigurationmergingtofindouthowusingregexsectionswillchangehowdirectivesareapplied.

Anon-regexwildcardsectionthatchangestheconfigurationofalluserdirectoriescouldlookasfollows:

OptionsIndexes

Usingregexsections,wecandenyaccesstomanytypesofimagefilesatonce:


WhattouseWhenChoosingbetweenfilesystemcontainersandwebspacecontainersisactuallyquiteeasy.Whenapplyingdirectivestoobjectsthatresideinthefilesystemalwaysuseor.Whenapplyingdirectivestoobjectsthatdonotresideinthefilesystem(suchasawebpagegeneratedfromadatabase),use.

Itisimportanttoneverusewhentryingtorestrictaccesstoobjectsinthefilesystem.Thisisbecausemanydifferentwebspacelocations(URLs)couldmaptothesamefilesystemlocation,allowingyourrestrictionstobecircumvented.Forexample,considerthefollowingconfiguration:


Thisworksfineiftherequestisforhttp://yoursite.example.com/dir/.Butwhatifyouareonacase-insensitivefilesystem?Thenyourrestrictioncouldbeeasilycircumventedbyrequestinghttp://yoursite.example.com/DIR/.Thedirective,incontrast,willapplytoanycontentservedfromthatlocation,regardlessofhowitiscalled.(Anexceptionisfilesystemlinks.Thesamedirectorycanbeplacedinmorethanonepartof

thefilesystemusingsymboliclinks.Thedirectivewillfollowthesymboliclinkwithoutresettingthepathname.Therefore,forthehighestlevelofsecurity,symboliclinksshouldbedisabledwiththeappropriateOptionsdirective.)

Ifyouare,perhaps,thinkingthatnoneofthisappliestoyoubecauseyouuseacase-sensitivefilesystem,rememberthattherearemanyotherwaystomapmultiplewebspacelocationstothesamefilesystemlocation.Thereforeyoushouldalwaysusethefilesystemcontainerswhenyoucan.Thereis,however,oneexceptiontothisrule.PuttingconfigurationrestrictionsinasectionisperfectlysafebecausethissectionwillapplytoallrequestsregardlessofthespecificURL.

VirtualHosts

Thecontainerenclosesdirectivesthatapplytospecifichosts.Thisisusefulwhenservingmultiplehostsfromthesamemachinewithadifferentconfigurationforeach.Formoreinformation,seetheVirtualHostDocumentation.

Proxy

Theandcontainersapplyenclosedconfigurationdirectivesonlytositesaccessedthroughmod_proxy'sproxyserverthatmatchthespecifiedURL.Forexample,thefollowingconfigurationwillpreventtheproxyserverfrombeingusedtoaccessthecnn.comwebsite.


WhatDirectivesareAllowed?

Tofindoutwhatdirectivesareallowedinwhattypesofconfigurationsections,checktheContextofthedirective.Everythingthatisallowedinsectionsisalsosyntacticallyallowedin,,,,,,andsections.Therearesomeexceptions,however:

TheAllowOverridedirectiveworksonlyinsections.TheFollowSymLinksandSymLinksIfOwnerMatchOptionsworkonlyinsectionsor.htaccessfiles.TheOptionsdirectivecannotbeusedinandsections.

Howthesectionsaremerged

Theconfigurationsectionsareappliedinaveryparticularorder.Sincethiscanhaveimportanteffectsonhowconfigurationdirectivesareinterpreted,itisimportanttounderstandhowthisworks.

Theorderofmergingis:

1. (exceptregularexpressions)and.htaccessdonesimultaneously(with.htaccess,ifallowed,overriding)

2. (and)

3. anddonesimultaneously

4. anddonesimultaneously

Apartfrom,eachgroupisprocessedintheorderthattheyappearintheconfigurationfiles.(group1above)isprocessedintheordershortestdirectorycomponenttolongest.Soforexample,willbeprocessedbefore.Ifmultiplesectionsapplytothesamedirectorytheyareprocessedintheconfigurationfileorder.ConfigurationsincludedviatheIncludedirectivewillbetreatedasiftheywereinsidetheincludingfileatthelocationoftheIncludedirective.

Sectionsinsidesectionsareappliedafterthecorrespondingsectionsoutsidethevirtualhostdefinition.Thisallowsvirtualhoststooverridethemainserverconfiguration.

Latersectionsoverrideearlierones.

TechnicalNoteThereisactuallya/sequence

performedjustbeforethenametranslationphase(whereAliasesandDocumentRootsareusedtomapURLstofilenames).Theresultsofthissequencearecompletelythrownawayafterthetranslationhascompleted.

SomeExamplesBelowisanartificialexampletoshowtheorderofmerging.Assumingtheyallapplytotherequest,thedirectivesinthisexamplewillbeappliedintheorderA>B>C>D>E.

E

D

B

C

A

Foramoreconcreteexample,considerthefollowing.Regardlessofanyaccessrestrictionsplacedinsections,thesectionwillbeevaluatedlastandwillallowunrestrictedaccesstotheserver.Inotherwords,orderofmergingisimportant,sobecareful!



Orderdeny,allowAllowfromall

#Woops!Thissectionwillhavenoeffect

Orderallow,denyAllowfromallDenyfrombadguy.example.com


Server-WideConfiguration

Thisdocumentexplainssomeofthedirectivesprovidedbythecoreserverwhichareusedtoconfigurethebasicoperationsoftheserver.

ServerIdentification

RelatedModules RelatedDirectivesServerNameServerAdminServerSignatureServerTokensUseCanonicalName

TheServerAdminandServerTokensdirectivescontrolwhatinformationabouttheserverwillbepresentedinserver-generateddocumentssuchaserrormessages.TheServerTokensdirectivesetsthevalueoftheServerHTTPresponseheaderfield.

TheServerNameandUseCanonicalNamedirectivesareusedbytheservertodeterminehowtoconstructself-referentialURLs.Forexample,whenaclientrequestsadirectory,butdoesnotincludethetrailingslashinthedirectoryname,Apachemustredirecttheclienttothefullnameincludingthetrailingslashsothattheclientwillcorrectlyresolverelativereferencesinthedocument.

FileLocations

RelatedModules RelatedDirectivesCoreDumpDirectoryDocumentRootErrorLogLockFilePidFileScoreBoardFileServerRoot

ThesedirectivescontrolthelocationsofthevariousfilesthatApacheneedsforproperoperation.Whenthepathnameuseddoesnotbeginwithaslash(/),thefilesarelocatedrelativetotheServerRoot.Becarefulaboutlocatingfilesinpathswhicharewritablebynon-rootusers.Seethesecuritytipsdocumentationformoredetails.



LimitingResourceUsage

RelatedModules RelatedDirectivesLimitRequestBodyLimitRequestFieldsLimitRequestFieldsizeLimitRequestLineRLimitCPURLimitMEMRLimitNPROCThreadStackSize

TheLimitRequest*directivesareusedtoplacelimitsontheamountofresourcesApachewilluseinreadingrequestsfromclients.Bylimitingthesevalues,somekindsofdenialofserviceattackscanbemitigated.

TheRLimit*directivesareusedtolimittheamountofresourceswhichcanbeusedbyprocessesforkedofffromtheApachechildren.Inparticular,thiswillcontrolresourcesusedbyCGIscriptsandSSIexeccommands.

TheThreadStackSizedirectiveisusedonlyonNetwaretocontrolthestacksize.


LogFiles

Inordertoeffectivelymanageawebserver,itisnecessarytogetfeedbackabouttheactivityandperformanceoftheserveraswellasanyproblemsthatmaybeoccurring.TheApacheHTTPServerprovidesverycomprehensiveandflexibleloggingcapabilities.Thisdocumentdescribeshowtoconfigureitsloggingcapabilities,andhowtounderstandwhatthelogscontain.

SecurityWarning

AnyonewhocanwritetothedirectorywhereApacheiswritingalogfilecanalmostcertainlygainaccesstotheuidthattheserverisstartedas,whichisnormallyroot.DoNOTgivepeoplewriteaccesstothedirectorythelogsarestoredinwithoutbeingawareoftheconsequences;seethesecuritytipsdocumentfordetails.

Inaddition,logfilesmaycontaininformationsupplieddirectlybytheclient,withoutescaping.Therefore,itispossibleformaliciousclientstoinsertcontrol-charactersinthelogfiles,socaremustbetakenindealingwithrawlogs.

ErrorLog

RelatedModules RelatedDirectivesErrorLogLogLevel

Theservererrorlog,whosenameandlocationissetbytheErrorLogdirective,isthemostimportantlogfile.ThisistheplacewhereApachehttpdwillsenddiagnosticinformationandrecordanyerrorsthatitencountersinprocessingrequests.Itisthefirstplacetolookwhenaproblemoccurswithstartingtheserverorwiththeoperationoftheserver,sinceitwilloftencontaindetailsofwhatwentwrongandhowtofixit.

Theerrorlogisusuallywrittentoafile(typicallyerror_logonUnixsystemsanderror.logonWindowsandOS/2).OnUnixsystemsitisalsopossibletohavetheserversenderrorstosyslogorpipethemtoaprogram.

Theformatoftheerrorlogisrelativelyfree-formanddescriptive.Butthereiscertaininformationthatiscontainedinmosterrorlogentries.Forexample,hereisatypicalmessage.

[WedOct1114:32:522000][error][client127.0.0.1]clientdeniedbyserverconfiguration:/export/home/live/ap/htdocs/test

Thefirstiteminthelogentryisthedateandtimeofthemessage.Theseconditemliststheseverityoftheerrorbeingreported.TheLogLeveldirectiveisusedtocontrolthetypesoferrorsthataresenttotheerrorlogbyrestrictingtheseveritylevel.ThethirditemgivestheIPaddressoftheclientthatgeneratedtheerror.Beyondthatisthemessageitself,whichinthiscaseindicatesthattheserverhasbeenconfiguredtodenytheclientaccess.Theserverreportsthefile-systempath(asopposedtothewebpath)ofthe

requesteddocument.

Averywidevarietyofdifferentmessagescanappearintheerrorlog.Mostlooksimilartotheexampleabove.TheerrorlogwillalsocontaindebuggingoutputfromCGIscripts.AnyinformationwrittentostderrbyaCGIscriptwillbecopieddirectlytotheerrorlog.

Itisnotpossibletocustomizetheerrorlogbyaddingorremovinginformation.However,errorlogentriesdealingwithparticularrequestshavecorrespondingentriesintheaccesslog.Forexample,theaboveexampleentrycorrespondstoanaccesslogentrywithstatuscode403.Sinceitispossibletocustomizetheaccesslog,youcanobtainmoreinformationabouterrorconditionsusingthatlogfile.

Duringtesting,itisoftenusefultocontinuouslymonitortheerrorlogforanyproblems.OnUnixsystems,youcanaccomplishthisusing:

tail-ferror_log

AccessLog

RelatedModules RelatedDirectivesmod_log_configmod_setenvif

CustomLogLogFormatSetEnvIf

Theserveraccesslogrecordsallrequestsprocessedbytheserver.ThelocationandcontentoftheaccesslogarecontrolledbytheCustomLogdirective.TheLogFormatdirectivecanbeusedtosimplifytheselectionofthecontentsofthelogs.Thissectiondescribeshowtoconfiguretheservertorecordinformationintheaccesslog.

Ofcourse,storingtheinformationintheaccesslogisonlythestartoflogmanagement.Thenextstepistoanalyzethisinformationtoproduceusefulstatistics.Loganalysisingeneralisbeyondthescopeofthisdocument,andnotreallypartofthejobofthewebserveritself.Formoreinformationaboutthistopic,andforapplicationswhichperformloganalysis,checktheOpenDirectoryorYahoo.

VariousversionsofApachehttpdhaveusedothermodulesanddirectivestocontrolaccesslogging,includingmod_log_referer,mod_log_agent,andtheTransferLogdirective.TheCustomLogdirectivenowsubsumesthefunctionalityofalltheolderdirectives.

Theformatoftheaccesslogishighlyconfigurable.TheformatisspecifiedusingaformatstringthatlooksmuchlikeaC-styleprintf(1)formatstring.Someexamplesarepresentedinthenextsections.Foracompletelistofthepossiblecontentsoftheformatstring,seethemod_log_configformatstrings.

CommonLogFormat

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/

Atypicalconfigurationfortheaccesslogmightlookasfollows.

LogFormat"%h%l%u%t\"%r\"%>s%b"commonCustomLoglogs/access_logcommon

Thisdefinesthenicknamecommonandassociatesitwithaparticularlogformatstring.Theformatstringconsistsofpercentdirectives,eachofwhichtelltheservertologaparticularpieceofinformation.Literalcharactersmayalsobeplacedintheformatstringandwillbecopieddirectlyintothelogoutput.Thequotecharacter(")mustbeescapedbyplacingabackslashbeforeittopreventitfrombeinginterpretedastheendoftheformatstring.Theformatstringmayalsocontainthespecialcontrolcharacters"\n"fornew-lineand"\t"fortab.

TheCustomLogdirectivesetsupanewlogfileusingthedefinednickname.ThefilenamefortheaccesslogisrelativetotheServerRootunlessitbeginswithaslash.

TheaboveconfigurationwillwritelogentriesinaformatknownastheCommonLogFormat(CLF).Thisstandardformatcanbeproducedbymanydifferentwebserversandreadbymanyloganalysisprograms.ThelogfileentriesproducedinCLFwilllooksomethinglikethis:

127.0.0.1-frank[10/Oct/2000:13:55:36-0700]"GET/apache_pb.gifHTTP/1.0"2002326

Eachpartofthislogentryisdescribedbelow.

127.0.0.1(%h)ThisistheIPaddressoftheclient(remotehost)whichmadetherequesttotheserver.IfHostnameLookupsissettoOn,thentheserverwilltrytodeterminethehostnameandlogitinplaceoftheIPaddress.However,thisconfigurationisnot

recommendedsinceitcansignificantlyslowtheserver.Instead,itisbesttousealogpost-processorsuchaslogresolvetodeterminethehostnames.TheIPaddressreportedhereisnotnecessarilytheaddressofthemachineatwhichtheuserissitting.Ifaproxyserverexistsbetweentheuserandtheserver,thisaddresswillbetheaddressoftheproxy,ratherthantheoriginatingmachine.

-(%l)The"hyphen"intheoutputindicatesthattherequestedpieceofinformationisnotavailable.Inthiscase,theinformationthatisnotavailableistheRFC1413identityoftheclientdeterminedbyidentdontheclientsmachine.Thisinformationishighlyunreliableandshouldalmostneverbeusedexceptontightlycontrolledinternalnetworks.ApachehttpdwillnotevenattempttodeterminethisinformationunlessIdentityCheckissettoOn.

frank(%u)ThisistheuseridofthepersonrequestingthedocumentasdeterminedbyHTTPauthentication.ThesamevalueistypicallyprovidedtoCGIscriptsintheREMOTE_USERenvironmentvariable.Ifthestatuscodefortherequest(seebelow)is401,thenthisvalueshouldnotbetrustedbecausetheuserisnotyetauthenticated.Ifthedocumentisnotpasswordprotected,thispartwillbe"-"justlikethepreviousone.

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

[day/month/year:hour:minute:secondzone]day=2*digitmonth=3*letteryear=4*digithour=2*digit

minute=2*digitsecond=2*digitzone=(`+'|`-')4*digit

Itispossibletohavethetimedisplayedinanotherformatbyspecifying%{format}tinthelogformatstring,whereformatisasinstrftime(3)fromtheCstandardlibrary.

"GET/apache_pb.gifHTTP/1.0"(\"%r\")Therequestlinefromtheclientisgivenindoublequotes.Therequestlinecontainsagreatdealofusefulinformation.First,themethodusedbytheclientisGET.Second,theclientrequestedtheresource/apache_pb.gif,andthird,theclientusedtheprotocolHTTP/1.0.Itisalsopossibletologoneormorepartsoftherequestlineindependently.Forexample,theformatstring"%m%U%q%H"willlogthemethod,path,query-string,andprotocol,resultinginexactlythesameoutputas"%r".

200(%>s)Thisisthestatuscodethattheserversendsbacktotheclient.Thisinformationisveryvaluable,becauseitrevealswhethertherequestresultedinasuccessfulresponse(codesbeginningin2),aredirection(codesbeginningin3),anerrorcausedbytheclient(codesbeginningin4),oranerrorintheserver(codesbeginningin5).ThefulllistofpossiblestatuscodescanbefoundintheHTTPspecification(RFC2616section10).

2326(%b)Thelastpartindicatesthesizeoftheobjectreturnedtotheclient,notincludingtheresponseheaders.Ifnocontentwasreturnedtotheclient,thisvaluewillbe"-".Tolog"0"fornocontent,use%Binstead.

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

CombinedLogFormatAnothercommonlyusedformatstringiscalledtheCombinedLogFormat.Itcanbeusedasfollows.

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

ThisformatisexactlythesameastheCommonLogFormat,withtheadditionoftwomorefields.Eachoftheadditionalfieldsusesthepercent-directive%{header}i,whereheadercanbeanyHTTPrequestheader.Theaccesslogunderthisformatwilllooklike:

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

Theadditionalfieldsare:

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

The"Referer"(sic)HTTPrequestheader.Thisgivesthesitethattheclientreportshavingbeenreferredfrom.(Thisshouldbethepagethatlinkstoorincludes/apache_pb.gif).

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

TheUser-AgentHTTPrequestheader.Thisistheidentifyinginformationthattheclientbrowserreportsaboutitself.

MultipleAccessLogsMultipleaccesslogscanbecreatedsimplybyspecifyingmultipleCustomLogdirectivesintheconfigurationfile.Forexample,the

followingdirectiveswillcreatethreeaccesslogs.ThefirstcontainsthebasicCLFinformation,whilethesecondandthirdcontainrefererandbrowserinformation.ThelasttwoCustomLoglinesshowhowtomimictheeffectsoftheReferLogandAgentLogdirectives.

LogFormat"%h%l%u%t\"%r\"%>s%b"commonCustomLoglogs/access_logcommonCustomLoglogs/referer_log"%{Referer}i->%U"CustomLoglogs/agent_log"%{User-agent}i"

ThisexamplealsoshowsthatitisnotnecessarytodefineanicknamewiththeLogFormatdirective.Instead,thelogformatcanbespecifieddirectlyintheCustomLogdirective.

ConditionalLogsTherearetimeswhenitisconvenienttoexcludecertainentriesfromtheaccesslogsbasedoncharacteristicsoftheclientrequest.Thisiseasilyaccomplishedwiththehelpofenvironmentvariables.First,anenvironmentvariablemustbesettoindicatethattherequestmeetscertainconditions.ThisisusuallyaccomplishedwithSetEnvIf.Thentheenv=clauseoftheCustomLogdirectiveisusedtoincludeorexcluderequestswheretheenvironmentvariableisset.Someexamples:

#Markrequestsfromtheloop-backinterfaceSetEnvIfRemote_Addr"127\.0\.0\.1"dontlog#Markrequestsfortherobots.txtfileSetEnvIfRequest_URI"^/robots\.txt$"dontlog#LogwhatremainsCustomLoglogs/access_logcommonenv=!dontlog

Asanotherexample,considerloggingrequestsfromenglish-speakerstoonelogfile,andnon-englishspeakerstoadifferentlogfile.

SetEnvIfAccept-Language"en"englishCustomLoglogs/english_logcommonenv=englishCustomLoglogs/non_english_logcommonenv=!english

Althoughwehavejustshownthatconditionalloggingisverypowerfulandflexible,itisnottheonlywaytocontrolthecontentsofthelogs.Logfilesaremoreusefulwhentheycontainacompleterecordofserveractivity.Itisofteneasiertosimplypost-processthelogfilestoremoverequeststhatyoudonotwanttoconsider.

LogRotation

Onevenamoderatelybusyserver,thequantityofinformationstoredinthelogfilesisverylarge.Theaccesslogfiletypicallygrows1MBormoreper10,000requests.Itwillconsequentlybenecessarytoperiodicallyrotatethelogfilesbymovingordeletingtheexistinglogs.Thiscannotbedonewhiletheserverisrunning,becauseApachewillcontinuewritingtotheoldlogfileaslongasitholdsthefileopen.Instead,theservermustberestartedafterthelogfilesaremovedordeletedsothatitwillopennewlogfiles.

Byusingagracefulrestart,theservercanbeinstructedtoopennewlogfileswithoutlosinganyexistingorpendingconnectionsfromclients.However,inordertoaccomplishthis,theservermustcontinuetowritetotheoldlogfileswhileitfinishesservingoldrequests.Itisthereforenecessarytowaitforsometimeaftertherestartbeforedoinganyprocessingonthelogfiles.Atypicalscenariothatsimplyrotatesthelogsandcompressestheoldlogstosavespaceis:

mvaccess_logaccess_log.oldmverror_logerror_log.oldapachectlgracefulsleep600gzipaccess_log.olderror_log.old

Anotherwaytoperformlogrotationisusingpipedlogsasdiscussedinthenextsection.

PipedLogs

Apachehttpdiscapableofwritingerrorandaccesslogfilesthroughapipetoanotherprocess,ratherthandirectlytoafile.Thiscapabilitydramaticallyincreasestheflexibilityoflogging,withoutaddingcodetothemainserver.Inordertowritelogstoapipe,simplyreplacethefilenamewiththepipecharacter"|",followedbythenameoftheexecutablewhichshouldacceptlogentriesonitsstandardinput.Apachewillstartthepiped-logprocesswhentheserverstarts,andwillrestartitifitcrasheswhiletheserverisrunning.(Thislastfeatureiswhywecanrefertothistechniqueas"reliablepipedlogging".)

PipedlogprocessesarespawnedbytheparentApachehttpdprocess,andinherittheuseridofthatprocess.Thismeansthatpipedlogprogramsusuallyrunasroot.Itisthereforeveryimportanttokeeptheprogramssimpleandsecure.

Oneimportantuseofpipedlogsistoallowlogrotationwithouthavingtorestarttheserver.TheApacheHTTPServerincludesasimpleprogramcalledrotatelogsforthispurpose.Forexample,torotatethelogsevery24hours,youcanuse:

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

Noticethatquotesareusedtoenclosetheentirecommandthatwillbecalledforthepipe.Althoughtheseexamplesarefortheaccesslog,thesametechniquecanbeusedfortheerrorlog.

Asimilarbutmuchmoreflexiblelogrotationprogramcalledcronologisavailableatanexternalsite.

Aswithconditionallogging,pipedlogsareaverypowerfultool,buttheyshouldnotbeusedwhereasimplersolutionlikeoff-linepost-processingisavailable.

http://www.cronolog.org/

VirtualHosts

Whenrunningaserverwithmanyvirtualhosts,thereareseveraloptionsfordealingwithlogfiles.First,itispossibletouselogsexactlyasinasingle-hostserver.Simplybyplacingtheloggingdirectivesoutsidethesectionsinthemainservercontext,itispossibletologallrequestsinthesameaccessloganderrorlog.Thistechniquedoesnotallowforeasycollectionofstatisticsonindividualvirtualhosts.

IfCustomLogorErrorLogdirectivesareplacedinsideasection,allrequestsorerrorsforthatvirtualhostwillbeloggedonlytothespecifiedfile.Anyvirtualhostwhichdoesnothaveloggingdirectiveswillstillhaveitsrequestssenttothemainserverlogs.Thistechniqueisveryusefulforasmallnumberofvirtualhosts,butifthenumberofhostsisverylarge,itcanbecomplicatedtomanage.Inaddition,itcanoftencreateproblemswithinsufficientfiledescriptors.

Fortheaccesslog,thereisaverygoodcompromise.Byaddinginformationonthevirtualhosttothelogformatstring,itispossibletologallhoststothesamelog,andlatersplitthelogintoindividualfiles.Forexample,considerthefollowingdirectives.

LogFormat"%v%l%u%t\"%r\"%>s%b"comonvhostCustomLoglogs/access_logcomonvhost

The%visusedtologthenameofthevirtualhostthatisservingtherequest.Thenaprogramlikesplit-logfilecanbeusedtopost-processtheaccessloginordertosplititintoonefilepervirtualhost.

OtherLogFiles

RelatedModules RelatedDirectivesmod_cgimod_rewrite

PidFileRewriteLogRewriteLogLevelScriptLogScriptLogBufferScriptLogLength

PIDFileOnstartup,Apachehttpdsavestheprocessidoftheparenthttpdprocesstothefilelogs/httpd.pid.ThisfilenamecanbechangedwiththePidFiledirective.Theprocess-idisforusebytheadministratorinrestartingandterminatingthedaemonbysendingsignalstotheparentprocess;onWindows,usethe-kcommandlineoptioninstead.FormoreinformationseetheStoppingandRestartingpage.

ScriptLogInordertoaidindebugging,theScriptLogdirectiveallowsyoutorecordtheinputtoandoutputfromCGIscripts.Thisshouldonlybeusedintesting-notforliveservers.Moreinformationisavailableinthemod_cgidocumentation.

RewriteLogWhenusingthepowerfulandcomplexfeaturesofmod_rewrite,itisalmostalwaysnecessarytousetheRewriteLogtohelpindebugging.Thislogfileproducesadetailedanalysisofhowtherewritingenginetransformsrequests.ThelevelofdetailiscontrolledbytheRewriteLogLeveldirective.

MappingURLstoFilesystemLocations

ThisdocumentexplainshowApacheusestheURLofarequesttodeterminethefilesystemlocationfromwhichtoserveafile.

RelatedModulesandDirectives

RelatedModules RelatedDirectivesmod_aliasmod_proxymod_rewritemod_userdirmod_spelingmod_vhost_alias

AliasAliasMatchCheckSpellingDocumentRootErrorDocumentOptionsProxyPassProxyPassReverseRedirectRedirectMatchRewriteCondRewriteMatchScriptAliasScriptAliasMatchUserDir

DocumentRoot

Indecidingwhatfiletoserveforagivenrequest,Apache'sdefaultbehavioristotaketheURL-Pathfortherequest(thepartoftheURLfollowingthehostnameandport)andaddittotheendoftheDocumentRootspecifiedinyourconfigurationfiles.Therefore,thefilesanddirectoriesunderneaththeDocumentRootmakeupthebasicdocumenttreewhichwillbevisiblefromtheweb.

ApacheisalsocapableofVirtualHosting,wheretheserverreceivesrequestsformorethanonehost.Inthiscase,adifferentDocumentRootcanbespecifiedforeachvirtualhost,oralternatively,thedirectivesprovidedbythemodulemod_vhost_aliascanbeusedtodynamicallydeterminetheappropriateplacefromwhichtoservecontentbasedontherequestedIPaddressorhostname.

FilesOutsidetheDocumentRoot

TherearefrequentlycircumstanceswhereitisnecessarytoallowwebaccesstopartsofthefilesystemthatarenotstrictlyunderneaththeDocumentRoot.Apacheoffersseveraldifferentwaystoaccomplishthis.OnUnixsystems,symboliclinkscanbringotherpartsofthefilesystemundertheDocumentRoot.Forsecurityreasons,ApachewillfollowsymboliclinksonlyiftheOptionssettingfortherelevantdirectoryincludesFollowSymLinksorSymLinksIfOwnerMatch.

Alternatively,theAliasdirectivewillmapanypartofthefilesystemintothewebspace.Forexample,with

Alias/docs/var/web

theURLhttp://www.example.com/docs/dir/file.htmlwillbeservedfrom/var/web/dir/file.html.TheScriptAliasdirectiveworksthesameway,withtheadditionaleffectthatallcontentlocatedatthetargetpathistreatedasCGIscripts.

Forsituationswhereyourequireadditionalflexibility,youcanusetheAliasMatchandScriptAliasMatchdirectivestodopowerfulregular-expressionbasedmatchingandsubstitution.Forexample,

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

willmaparequesttohttp://example.com/~user/cgi-bin/script.cgitothepath/home/user/cgi-bin/script.cgiandwilltreattheresultingfileasaCGIscript.

UserDirectories

TraditionallyonUnixsystems,thehomedirectoryofaparticularusercanbereferredtoas~user/.Themodulemod_userdirextendsthisideatothewebbyallowingfilesundereachuser'shomedirectorytobeaccessedusingURLssuchasthefollowing.

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

Forsecurityreasons,itisinappropriatetogivedirectaccesstoauser'shomedirectoryfromtheweb.Therefore,theUserDirdirectivespecifiesadirectoryunderneaththeuser'shomedirectorywherewebfilesarelocated.UsingthedefaultsettingofUserdirpublic_html,theaboveURLmapstoafileatadirectorylike/home/user/public_html/file.htmlwhere/home/user/istheuser'shomedirectoryasspecifiedin/etc/passwd.

TherearealsoseveralotherformsoftheUserdirdirectivewhichyoucanuseonsystemswhere/etc/passwddoesnotcontainthelocationofthehomedirectory.

Somepeoplefindthe"~"symbol(whichisoftenencodedonthewebas%7e)tobeawkwardandprefertouseanalternatestringtorepresentuserdirectories.Thisfunctionalityisnotsupportedbymod_userdir.However,ifusers'homedirectoriesarestructuredinaregularway,thenitispossibletousetheAliasMatchdirectivetoachievethedesiredeffect.Forexample,tomakehttp://www.example.com/upages/user/file.htmlmapto/home/user/public_html/file.html,usethefollowingAliasMatchdirective:

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

URLRedirection

TheconfigurationdirectivesdiscussedintheabovesectionstellApachetogetcontentfromaspecificplaceinthefilesystemandreturnittotheclient.Sometimes,itisdesirableinsteadtoinformtheclientthattherequestedcontentislocatedatadifferentURL,andinstructtheclienttomakeanewrequestwiththenewURL.ThisiscalledredirectionandisimplementedbytheRedirectdirective.Forexample,ifthecontentsofthedirectory/foo/undertheDocumentRootaremovedtothenewdirectory/bar/,youcaninstructclientstorequestthecontentatthenewlocationasfollows:

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

ThiswillredirectanyURL-Pathstartingin/foo/tothesameURLpathonthewww.example.comserverwith/bar/substitutedfor/foo/.Youcanredirectclientstoanyserver,notonlytheoriginserver.

ApachealsoprovidesaRedirectMatchdirectiveformorecomplicatedrewritingproblems.Forexample,toredirectrequestsforthesitehomepagetoadifferentsite,butleaveallotherrequestsalone,usethefollowingconfiguration:

RedirectMatchpermanent^/$http://www.example.com/startpage.html

Alternatively,totemporarilyredirectallpagesononesitetoaparticularpageonanothersite,usethefollowing:

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

ReverseProxy

ApachealsoallowsyoutobringremotedocumentsintotheURLspaceofthelocalserver.Thistechniqueiscalledreverseproxyingbecausethewebserveractslikeaproxyserverbyfetchingthedocumentsfromaremoteserverandreturningthemtotheclient.Itisdifferentfromnormalproxyingbecause,totheclient,itappearsthedocumentsoriginateatthereverseproxyserver.

Inthefollowingexample,whenclientsrequestdocumentsunderthe/foo/directory,theserverfetchesthosedocumentsfromthe/bar/directoryoninternal.example.comandreturnsthemtotheclientasiftheywerefromthelocalserver.

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

TheProxyPassconfigurestheservertofetchtheappropriatedocuments,whiletheProxyPassReversedirectiverewritesredirectsoriginatingatinternal.example.comsothattheytargettheappropriatedirectoryonthelocalserver.Itisimportanttonote,however,thatlinksinsidethedocumentswillnotberewritten.Soanyabsolutelinksoninternal.example.comwillresultintheclientbreakingoutoftheproxyserverandrequestingdirectlyfrominternal.example.com.

RewritingEngine

Whenevenmorepowerfulsubstitutionisrequired,therewritingengineprovidedbymod_rewritecanbeuseful.ThedirectivesprovidedbythismoduleusecharacteristicsoftherequestsuchasbrowsertypeorsourceIPaddressindecidingfromwheretoservecontent.Inaddition,mod_rewritecanuseexternaldatabasefilesorprogramstodeterminehowtohandlearequest.Therewritingengineiscapableofperformingallthreetypesofmappingsdiscussedabove:internalredirects(aliases),externalredirects,andproxying.Manypracticalexamplesemployingmod_rewritearediscussedintheURLRewritingGuide.

Copyright2013TheApacheSoftwareFoundation.

FileNotFound

Inevitably,URLswillberequestedforwhichnomatchingfilecanbefoundinthefilesystem.Thiscanhappenforseveralreasons.Insomecases,itcanbearesultofmovingdocumentsfromonelocationtoanother.Inthiscase,itisbesttouseURLredirectiontoinformclientsofthenewlocationoftheresource.Inthisway,youcanassurethatoldbookmarksandlinkswillcontinuetowork,eventhoughtheresourceisatanewlocation.

Anothercommoncauseof"FileNotFound"errorsisaccidentalmistypingofURLs,eitherdirectlyinthebrowser,orinHTMLlinks.Apacheprovidesthemodulemod_speling(sic)tohelpwiththisproblem.Whenthismoduleisactivated,itwillintercept"FileNotFound"errorsandlookforaresourcewithasimilarfilename.Ifonesuchfileisfound,mod_spelingwillsendanHTTPredirecttotheclientinformingitofthecorrectlocation.Ifseveral"close"filesarefound,alistofavailablealternativeswillbepresentedtotheclient.

Anespeciallyusefulfeatureofmod_speling,isthatitwillcomparefilenameswithoutrespecttocase.Thiscanhelpsystemswhereusersareunawareofthecase-sensitivenatureofURLsandtheunixfilesystem.Butusingmod_spelingforanythingmorethantheoccasionalURLcorrectioncanplaceadditionalloadontheserver,sinceeach"incorrect"requestisfollowedbyaURLredirectionandanewrequestfromtheclient.

Ifallattemptstolocatethecontentfail,ApachereturnsanerrorpagewithHTTPstatuscode404(filenotfound).TheappearanceofthispageiscontrolledwiththeErrorDocumentdirectiveandcanbecustomizedinaflexiblemannerasdiscussedintheCustomerrorresponsesandInternationalServerErrorResponsesdocuments.

LicensedundertheApacheLicense,Version2.0.




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/apachecd/usr/local/apachemkdirbinconflogschown0.binconflogschgrp0.binconflogschmod755.binconflogs

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

cphttpd/usr/local/apache/binchown0/usr/local/apache/bin/httpdchgrp0/usr/local/apache/bin/httpdchmod511/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.NotethatusersmaystillusetoexecuteCGIscriptsifthesescriptsareindirectoriesdesignatedbyaScriptAliasdirective.

CGIinGeneral

Firstofall,youalwayshavetorememberthatyoumusttrustthewritersoftheCGIscripts/programsoryourabilitytospotpotentialsecurityholesinCGI,whethertheyweredeliberateoraccidental.CGIscriptscanrunessentiallyarbitrarycommandsonyoursystemwiththepermissionsofthewebserveruserandcanthereforebeextremelydangerousiftheyarenotcarefullychecked.

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

http://cgiwrap.unixtools.org/

Apache HTTP Server Version 2 · Apache > HTTP Server > Documentation > Version 2.0. Upgrading to...

Documents

Transcript of Apache HTTP Server Version 2 · Apache > HTTP Server > Documentation > Version 2.0. Upgrading to...