ApacheHTTPServerVersion2.

4
Upgradingto2.4from2.2
Inordertoassistfolksupgrading,wemaintainadocumentdescribinginformationcriticaltoexistingApacheHTTP
Serverusers.Theseareintendedtobebriefnotes,andyoushouldbeabletofindmoreinformationineitherthe
NewFeatures(new_features_2_4.html)document,orinthesrc/CHANGESfile.Applicationandmodule
developerscanfindasummaryofAPIchangesintheAPIupdates(developer/new_api_2_4.html)overview.

Thisdocumentdescribeschangesinserverbehaviorthatmightrequireyoutochangeyourconfigurationorhowyou
usetheserverinordertocontinueusing2.4asyouarecurrentlyusing2.2.Totakeadvantageofnewfeaturesin2.4,
seetheNewFeaturesdocument.

Thisdocumentdescribesonlythechangesfrom2.2to2.4.Ifyouareupgradingfromversion2.0,youshouldalso
consultthe2.0to2.2upgradingdocument.(http://httpd.apache.org/docs/2.2/upgrading.html)

CompileTimeConfigurationChanges
RunTimeConfigurationChanges
MiscChanges
ThirdPartyModules
Commonproblemswhenupgrading

Seealso
OverviewofnewfeaturesinApacheHTTPServer2.4
Comments

CompileTimeConfigurationChanges
Thecompilationprocessisverysimilartotheoneusedinversion2.2.Youroldconfigurecommandline(as
foundinbuild/config.niceintheinstalledserverdirectory)canbeusedinmostcases.Therearesome
changesinthedefaultsettings.Somedetailsofchanges:

Thesemoduleshavebeenremoved:mod_authn_default,mod_authz_default,mod_mem_cache.Ifyouwere
usingmod_mem_cachein2.2,lookatmod_cache_diskin2.4.
Allloadbalancingimplementationshavebeenmovedtoindividual,selfcontainedmod_proxysubmodules,
e.g.mod_lbmethod_bybusyness.Youmightneedtobuildandloadanyofthesethatyourconfiguration
uses.
PlatformsupporthasbeenremovedforBeOS,TPF,andevenolderplatformssuchasA/UX,Next,and
Tandem.Thesewerebelievedtobebrokenanyway.
configure:dynamicmodules(DSO)arebuiltbydefault
configure:Bydefault,onlyabasicsetofmodulesisloaded.TheotherLoadModuledirectivesare
commentedoutintheconfigurationfile.
configure:the"most"modulesetgetsbuiltbydefault
configure:the"reallyall"modulesetaddsdevelopermodulestothe"all"set

RunTimeConfigurationChanges
Therehavebeensignificantchangesinauthorizationconfiguration,andotherminorconfigurationchanges,that
couldrequirechangestoyour2.2configurationfilesbeforeusingthemfor2.4.

Authorization
Anyconfigurationfilethatusesauthorizationwilllikelyneedchanges.

YoushouldreviewtheAuthentication,AuthorizationandAccessControlHowto(howto/auth.html),especially
thesectionBeyondjustauthorization(howto/auth.html#beyond)whichexplainsthenewmechanismsfor
controllingtheorderinwhichtheauthorizationdirectivesareapplied.

Directivesthatcontrolhowauthorizationmodulesrespondwhentheydon'tmatchtheauthenticateduserhavebeen
removed:ThisincludesAuthzLDAPAuthoritative,AuthzDBDAuthoritative,AuthzDBMAuthoritative,
AuthzGroupFileAuthoritative,AuthzUserAuthoritative,andAuthzOwnerAuthoritative.Thesedirectiveshavebeen
replacedbythemoreexpressiveRequireAny,RequireNone,andRequireAll.

Ifyouusemod_authz_dbm,youmustportyourconfigurationtouseRequiredbmgroup...inplaceof
Requiregroup....

Accesscontrol
In2.2,accesscontrolbasedonclienthostname,IPaddress,andothercharacteristicsofclientrequestswasdone
usingthedirectivesOrder,Allow,Deny,andSatisfy.

In2.4,suchaccesscontrolisdoneinthesamewayasotherauthorizationchecks,usingthenewmodule
mod_authz_host.Theoldaccesscontrolidiomsshouldbereplacedbythenewauthenticationmechanisms,
althoughforcompatibilitywitholdconfigurations,thenewmodulemod_access_compatisprovided.

Mixingoldandnewdirectives
MixingolddirectiveslikeOrder,AlloworDenywithnewoneslikeRequireistechnicallypossible
butdiscouraged.mod_access_compatwascreatedtosupportconfigurationscontainingonlyold
directivestofacilitatethe2.4upgrade.Pleasechecktheexamplesbelowtogetabetterideaaboutissues
thatmightarise.

Herearesomeexamplesofoldandnewwaystodothesameaccesscontrol.

Inthisexample,allrequestsaredenied.

2.2configuration:
Orderdeny,allow
Denyfromall

2.4configuration:
Requirealldenied

Inthisexample,allrequestsareallowed.

2.2configuration:
Orderallow,deny
Allowfromall

2.4configuration:
Requireallgranted

Inthefollowingexample,allhostsintheexample.orgdomainareallowedaccessallotherhostsaredeniedaccess.
 2.2configuration:
OrderDeny,Allow
Denyfromall
Allowfromexample.org

2.4configuration:
Requirehostexample.org

Inthefollowingexample,mixingoldandnewdirectivesleadstounexpectedresults.

Mixingoldandnewdirectives:NOTWORKINGASEXPECTED
DocumentRoot"/var/www/html"

<Directory"/">
AllowOverrideNone
Orderdeny,allow
Denyfromall
</Directory>

<Location"/serverstatus">
SetHandlerserverstatus
Require127.0.0.1
</Location>

access.logGET/serverstatus403127.0.0.1
error.logAH01797:clientdeniedbyserverconfiguration:/var/www/html/serverstatus

Whyhttpddeniesaccesstoserversstatuseveniftheconfigurationseemstoallowit?Because
mod_access_compatdirectivestakeprecedenceoverthemod_authz_hostoneinthisconfigurationmerge
(sections.html#merging)scenario.

Thisexampleconverselyworksasexpected:

Mixingoldandnewdirectives:WORKINGASEXPECTED
DocumentRoot"/var/www/html"

<Directory"/">
AllowOverrideNone
Requirealldenied
</Directory>

<Location"/serverstatus">
SetHandlerserverstatus
Orderdeny,allow
Denyfromall
AllowFrom127.0.0.1
</Location>

access.logGET/serverstatus200127.0.0.1
Soevenifmixingconfigurationisstillpossible,pleasetrytoavoiditwhenupgrading:eitherkeepolddirectivesand
thenmigratetothenewonesonalaterstageorjustmigrateeverythinginbulk.

Otherconfigurationchanges
Someothersmalladjustmentsmaybenecessaryforparticularconfigurationsasdiscussedbelow.

MaxRequestsPerChildhasbeenrenamedtoMaxConnectionsPerChild,describesmore
accuratelywhatitdoes.Theoldnameisstillsupported.
MaxClientshasbeenrenamedtoMaxRequestWorkers,whichdescribesmoreaccuratelywhatit
does.ForasyncMPMs,likeevent,themaximumnumberofclientsisnotequivalentthanthenumberof
workerthreads.Theoldnameisstillsupported.
TheDefaultTypedirectivenolongerhasanyeffect,otherthantoemitawarningifit'susedwithany
valueotherthannone.Youneedtouseotherconfigurationsettingstoreplaceitin2.4.
AllowOverridenowdefaultstoNone.
EnableSendfilenowdefaultstoOff.
FileETagnowdefaultsto"MTimeSize"(withoutINode).
mod_dav_fs:TheformatoftheDavLockDBfilehaschangedforsystemswithinodes.Theold
DavLockDBfilemustbedeletedonupgrade.
KeepAliveonlyacceptsvaluesofOnorOff.Previously,anyvalueotherthan"Off"or"0"wastreatedas
"On".
DirectivesAcceptMutex,LockFile,RewriteLock,SSLMutex,SSLStaplingMutex,andWatchdogMutexPath
havebeenreplacedwithasingleMutexdirective.Youwillneedtoevaluateanyuseoftheseremoved
directivesinyour2.2configurationtodetermineiftheycanjustbedeletedorwillneedtobereplacedusing
Mutex.
mod_cache:CacheIgnoreURLSessionIdentifiersnowdoesanexactmatchagainstthequery
stringinsteadofapartialmatch.Ifyourconfigurationwasusingpartialstrings,e.g.usingsessionidto
match/someapplication/image.gifjsessionid=123456789,thenyouwillneedtochange
tothefullstringjsessionid.
mod_cache:ThesecondparametertoCacheEnableonlymatchesforwardproxycontentifitbeginswith
thecorrectprotocol.In2.2andearlier,aparameterof'/'matchedallcontent.
mod_ldap:LDAPTrustedClientCertisnowconsistentlyaperdirectorysettingonly.Ifyouusethis
directive,reviewyourconfigurationtomakesureitispresentinallthenecessarydirectorycontexts.
mod_filter:FilterProvidersyntaxhaschangedandnowusesabooleanexpressiontodetermineif
afilterisapplied.
mod_include:
The#ifexprelementnowusesthenewexpressionparser.Theoldsyntaxcanberestoredwiththe
newdirectiveSSILegacyExprParser.
AnSSI*configdirectiveindirectoryscopenolongercausesallotherperdirectorySSI*directivesto
beresettotheirdefaultvalues.

mod_charset_lite:TheDebugLeveloptionhasbeenremovedinfavourofpermoduleLogLevel
configuration.
mod_ext_filter:TheDebugLeveloptionhasbeenremovedinfavourofpermoduleLogLevel
configuration.
mod_proxy_scgi:ThedefaultsettingforPATH_INFOhaschangedfromhttpd2.2,andsomeweb
applicationswillnolongeroperateproperlywiththenewPATH_INFOsetting.Theprevioussettingcanbe
restoredbyconfiguringtheproxyscgipathinfovariable.
mod_ssl:CRLbasedrevocationcheckingnowneedstobeexplicitlyconfiguredthrough
SSLCARevocationCheck.
mod_substitute:Themaximumlinelengthisnowlimitedto1MB.
mod_reqtimeout:Ifthemoduleisloaded,itwillnowsetsomedefaulttimeouts.
mod_dumpio:DumpIOLogLevelisnolongersupported.DataisalwaysloggedatLogLeveltrace7.
OnUnixplatforms,pipedloggingcommandsconfiguredusingeitherErrorLogorCustomLogwere
invokedusing/bin/shcin2.2andearlier.In2.4andlater,pipedloggingcommandsareexecuted
 directly.Torestoretheoldbehaviour,seethepipedloggingdocumentation.

MiscChanges
mod_autoindex:willnowextracttitlesanddisplaydescriptionsfor.xhtmlfiles,whichwerepreviously
ignored.
mod_ssl:Thedefaultformatofthe*_DNvariableshaschanged.Theoldformatcanstillbeusedwiththe
newLegacyDNStringFormatargumenttoSSLOptions.TheSSLv2protocolisnolongersupported.
SSLProxyCheckPeerCNandSSLProxyCheckPeerExpirenowdefaulttoOn,causingproxy
requeststoHTTPShostswithbadoroutdatedcertificatestofailwitha502statuscode(Badgateway)
htpasswdnowusesMD5hashbydefaultonallplatforms.
TheNameVirtualHostdirectivenolongerhasanyeffect,otherthantoemitawarning.Anyaddress/port
combinationappearinginmultiplevirtualhostsisimplicitlytreatedasanamebasedvirtualhost.
mod_deflatewillnowskipcompressionifitknowsthatthesizeoverheadaddedbythecompressionis
largerthanthedatatobecompressed.
Multilanguageerrordocumentsfrom2.2.xmaynotworkunlesstheyareadjustedtothenewsyntaxof
mod_include's#ifexpr=elementorthedirectiveSSILegacyExprParserisenabledforthe
directorycontainingtheerrordocuments.
Thefunctionalityprovidedbymod_authn_aliasinpreviousversions(i.e.,the
AuthnProviderAliasdirective)hasbeenmovedintomod_authn_core.
TheRewriteLogandRewriteLogLeveldirectiveshavebeenremoved.Thisfunctionalityisnowprovidedby
configuringtheappropriatelevelofloggingforthemod_rewritemoduleusingtheLogLeveldirective.
Seealsothemod_rewriteloggingsection.

ThirdPartyModules
Allmodulesmustberecompiledfor2.4beforebeingloaded.

Manythirdpartymodulesdesignedforversion2.2willotherwiseworkunchangedwiththeApacheHTTPServer
version2.4.SomewillrequirechangesseetheAPIupdate(developer/new_api_2_4.html)overview.

Commonproblemswhenupgrading
Startuperrors:
Invalidcommand'User',perhapsmisspelledordefinedbyamodule
notincludedintheserverconfigurationloadmodulemod_unixd
Invalidcommand'Require',perhapsmisspelledordefinedbyamodule
notincludedintheserverconfiguration,orInvalidcommand'Order',
perhapsmisspelledordefinedbyamodulenotincludedintheserver
configurationloadmodulemod_access_compat,orupdateconfigurationto2.4
authorizationdirectives.
IgnoringdeprecateduseofDefaultTypeinlineNNof
/path/to/httpd.confremoveDefaultTypeandreplacewithotherconfigurationsettings.
Invalidcommand'AddOutputFilterByType',perhapsmisspelledor
definedbyamodulenotincludedintheserverconfiguration
AddOutputFilterByTypehasmovedfromthecoretomod_filter,whichmustbeloaded.

Errorsservingrequests:
configurationerror:couldn'tcheckuser:/pathloadmodule
mod_authn_core.
.htaccessfilesaren'tbeingprocessedCheckforanappropriateAllowOverridedirectivethe
defaultchangedtoNonein2.4.
Comments

Notice:
ThisisnotaQ&Asection.Commentsplacedhereshouldbepointedtowardssuggestionsonimprovingthe
documentationorserver,andmayberemovedagainbyourmoderatorsiftheyareeitherimplementedor
consideredinvalid/offtopic.QuestionsonhowtomanagetheApacheHTTPServershouldbedirectedat
eitherourIRCchannel,#httpd,onFreenode,orsenttoourmailinglists.

RSSLogin/register

Ayush14daysagoRating:0(registeranaccountinordertoratecomments)

Whatarethestepstobefollowedtoupgradetheapachefrom2.2to2.4.Pleasesharethe
procedurewithstepfromstarttoend.
Thisdocumentmentionsaboutnewchangesandfeaturesinthenewversion,buthowtoupgradeina
machinewhereapache2.2.isalreadyinstalled,nowherementioned.

CO'Donnel194daysagoRating:0(registeranaccountinordertoratecomments)

ARewriteMapdirectivedefinedinserverconfigusedtobevisiblefromwithinaVirtualHost
section.

2.4requirestheadditionof"RewriteOptionsInherit"withintheVirtualHostsectioninordertocontinueto
seeamapdefinedatserverlevel.

DanielFerradal245daysagoRating:0(registeranaccountinordertoratecomments)

Acommentsaying404Filenotfounderrorsarenotloggedinerror.loganymoreunlessyou
specifyatleastLoglevel...core:infowouldbeappreciated,oratleastitisanoticeable
changein2.4andthereisnomentionofithere.

Nirgal503daysagoRating:0(registeranaccountinordertoratecomments)

Hi

Itshouldbementionedthatimagemapmodulewasremovedin2.4,unlessexplicitlyrequestedduring
compilationconfiguration:

https://svn.apache.org/viewvc/httpd/httpd/trunk/modules/mappers/config9.m4?r1=808722&r2=1146227

Sergiy673daysagoRating:0(registeranaccountinordertoratecomments)

Itwouldbenicetohaveclarificationhowtoavoid"SSLMutex"andprobabltyotherdirectivesmentionedin
thedocumentationnearSSLMutex.E.g.exampleinApache2.2withSSLMutexand
correspondingdirectiveinApache2.4withMutex.

joe712daysagoRating:0(registeranaccountinordertoratecomments)

TheAddEncodingdirectiveofmod_mimehaschangedbehaviourinApache2.2(andpretty
muchanyprecedingversion)wasdescribedlikefollows:

"TheAddEncodingdirectivemapsthegivenfilenameextensionstothespecifiedencodingtype.MIMEenc
istheMIMEencodingtousefordocumentscontainingtheextension.Thismappingisaddedtoany
alreadyinforce,overridinganymappingsthatalreadyexistforthesameextension."

whileonapache2.4thedescription(andbehaviour!)isdifferent:

"TheAddEncodingdirectivemapsthegivenfilenameextensionstothespecifiedHTTPcontentencoding.
encodingistheHTTPcontentcodingtoappendtothevalueoftheContentEncodingheaderfieldfor
documentsnamedwiththeextension.Thismappingisaddedtoanyalreadyinforce,overridingany
mappingsthatalreadyexistforthesameextension."

so,onapache2.4ifyouhave

AddEncodingxcompress.Z

thiswilladd"ContentEncoding:xcompress"to_any_urlendingin.Z,whichisprobablynotwhatyou
intendedtodo.

covener712daysagoRating:0(registeranaccountinordertoratecomments)

Thatdocchangeisnotassociatedwithafunctionalchange,otherthanthe
removalofDefaultType.

"thiswilladd"ContentEncoding:xcompress"to_any_urlendingin.Z,whichisprobablynot
whatyouintendedtodo."

Whatelsecouldyouexpectittodowhenyoucodethatdirective?

arock788daysagoRating:0(registeranaccountinordertoratecomments)

Duringapacheupgradeto2.4,facingissueswithmod_mellon.somodule.Doesitneedto
recompiledduringtheupgradeorneedtoberedonefromthescratch.Thereisnomention
ofthechangesrequiredinthemoduleafterupgradeintherelatedREADME.Cananyonehelp?
Errorwhenapacheisstartedafterupgrade:
./bin/httpdctlstart
httpd:Syntaxerroronline3of/netappusers/afwg/webtools/apache/bta3/httpsbtasni2/conf/httpd.conf:
Syntaxerroronline14of/afwg/webtools/apache/bta3/httpsbtasni2/conf/vhosts/_httpsd.conf:Cannotload
/afwg/webtools/apache/bta3/httpd2.4/modules/mod_auth_mellon.sointoserver:
/afwg/webtools/apache/bta3/httpd2.4/modules/mod_auth_mellon.so:undefinedsymbol:ap_log_error
ServerstartFAILED
 covener788daysagoRating:0(registeranaccountinordertoratecomments)

mod_mellonisn'tpartofthehttpddistribution.Anymodulethatyouwereusing
in2.2needstoberecompiledfor2.4whetherbyyouorwhoeverprovidesthe
combinationtoyou.

Starkos796daysagoRating:0(registeranaccountinordertoratecomments)

Itwouldbenicetohaveapointertothe"otherconfigurationsettings"forDefaultType.

Michele1102daysagoRating:0(registeranaccountinordertoratecomments)

Thedefaultoperationonhowpipedlogprocessesarespawnedwaschanged.

Gennady1520daysagoRating:0(registeranaccountinordertoratecomments)

Apache2.4willnotstartwithaddedSSLsupportonwindowsuntiladditionalmodule
(comparetoApache2.2configuration)wasenabled:socache_shmcb_module

Thisadditionalinfoisatthebeginningofthehttpdssl.conf,butittakestimetoreadit:)

#Requiredmodules:mod_log_config,mod_setenvif,mod_ssl,socache_shmcb_module(fordefaultvalue
ofSSLSessionCache)

Copyright2016TheApacheSoftwareFoundation.
LicensedundertheApacheLicense,Version2.0.