1.1

1.2

1.3

1.4

1.5

1.6

1.7

1.8

1.9

1.10

1.11

1.12

1.13

1.14

TableofContentsIntroduction

RegularExpressions

URLMapping

RewriteLogging

RewriteRuleflags

RewriteCond

RewriteMap

Proxyingwithmod_rewrite

VirtualHostswithmod_rewrite

AccessControlwithmod_rewrite

If,andotherConfigurationConfiguration

ContentMungingModules

Recipes

Appendix

2

TableofContentsmod_rewriteAndFriendsAboutThisBook

HowthisbookisorganizedOtherSourcesofWisdomTechnicaldetailsContactinformation,anderratareportingAbouttheAuthorAcknowledgements

mod_rewriteAndFriends

mod_rewriteisoneofthemostpowerful,andleastunderstood,ofthemodulesthatareprovidedwiththeApacheHTTPServer.Itisfrequentlymisusedtodothingsthatcanbedonesomuchbetterotherways.

Thousandsofexamplesareposteddailyonvariouswebsites,showingbeginnershowtodothingswith mod_rewrite,and,unfortunately,thevastmajorityofthemarewronginvariousways,subtleorgrevious,duetomisunderstandingsofhowmod_rewriteworks,orhowregularexpressionswork.

Thisbookisintendedtohelpyouunderstand mod_rewritedeeply,sothatyouknowwhenandhowtouseit,aswellaswhennottouseit,andwhattouseinstead.

AboutThisBookThefirstincarnationofthisbook,[TheDefinitiveGuidetoApachemod_rewrite](http://drbacchus.com/book/rewrite/),waspublishedin2006.Sincethen,somuchhaschangedthatwhilethatbookisstilluseful,it’sfarfromcomplete.

InFebruaryof2012,Apachehttpdversion2.4wasreleased,withahugenumberofenhancementsandchanges.Manyofthethingsthatpeoplehavebeenusing mod_rewritefornowhavebettersolutions.Meanwhile, mod_rewriteitselfimprovedquiteabit,too,andcandomanynewthings.

Thisbookstillfocusesprimarilyon mod_rewrite,butwilltouchonmanyofthesurroundingtopicsandmodules.

Thatsaid,thescopeofthisbookhasexpanded(sincetheearlierincarnation)toincludenotmerelyURLrewriting,butalsomethodsformunging(modifying)content,anddynamicconditionalconfiguration.Inmanycases,thesetechniquesmakemod_rewriteunnecessary,or,atleast,provideeasieralternatives,sotheyfitthescopeofthebookverywell.

Thesetechniquesincludemod_substitute,mod_proxy_html,the Definedirective,the container, mod_macro,andmanymore.Alongtheway,we’llalsodiscussthevariouspartsofURLmapping,theunderstandingofwhichallowsyoutoavoidusingthesemorecomplicatedtechniques.

Howthisbookisorganized

Thisbookconsistsof14chapters.Dependingonyourlevelofexistingexpertise,someofthemcanbesafelyskipped.

Chapter1-RegularExpressions-Thischaptergivesanintroductiontoregularexpressions,whicharethelanguageofmod_rewrite.

Chapter2-URLMapping-URLrewritingisaportionofalargertopiccalledURLmapping-theprocessbywhichApachehttpdtranslatesarequestedURLintoanactualresourcethatitwillserve.

Chapter3-Anintroductionto mod_rewrite-coveringsomeoftheconfigurationdirectivesthatneedtobesetupbeforeyoustartrewriting.

Introduction

3

http://drbacchus.com/book/rewrite/

Chapter4-RewriteRule-The RewriteRuledirectiveistheoneyou’llbeusingmostoften.Thischaptercoversitssyntaxandusage.

Chapter5-RewriteLogging-Therewritelogisagreatdebuggingtool,andalsoagoodwaytolearnabouthow mod_rewritethinksaboutthings.

Chapter6-RewriteRuleflags-Flagsmodifythebehaviorof RewriteRule.They’vebeenintroducedinthepreviouschapter,butthischaptercoverseachflagindetail,withexamples.

Chapter7-RewriteCond- RewriteCondallowsyoutoputconditionsontherunningofaparticular RewriteRule.

Chapter8-RewriteMap-The RewriteMapdirectiveallowsyoutocraftyourown RewriteRulelogicandlookuptables.

Chapter9-Proxyingwithmod_rewrite- RewriteRule’s`[P]flagletsyoupassarequestthroughaproxy.Thischapterdigsintothatingreaterdetail.

Chapter10-Virtualhostswithmod_rewrite-Using RewriteRuletomanagevirtualhosts.

Chapter11-Accesscontrolwithmod_rewrite-Using RewriteRuletocontrolorrestrictaccesstoresources.

Chapter12-ConfigurableConfiguration-Newinversion2.4ofthewebserverisaclassofdirectivesthatletyouaddintelligenceandrequest-timedecisionstotheconfiguration.Thesetechniquesreplacemanyofthethingsthatpeopleusedtousemod_rewritefor.

Chapter13-ContentModificationModules-Inthischapter,wediscussrewritingcontentsenttotheclient,whichisnotsomethingthat mod_rewritedoes.

Chapter14-Recipes-Recipes,anddetaileddiscussionsofthem,addressingcommonproblemsandsolutions.

OtherSourcesofWisdom

Abriefwordaboutthedocumentation.Theofficialdocs,athttp://httpd.apache.org/docs/current,aregreat,andaretheworkofmanydedicatedpeople.I’moneofmany.Thisbookisintendedtoaugmentthosedocs,andnotreplacethem.IfitappearssometimesthatIhavecopiedshamelesslyfromthedocumentation,IhumblyaskyoutorememberthatIparticipatedinwritingthosedocs,andtheeditsflowedbothdirections — thatis,sometimesitwasthedocsthatshamelesslycopiedfromthebook.

ThisbookdoesnotattempttobeacomprehensivebookabouttheApachewebserver.Forthat,Iencourageyoutolookthedocumentationandalsoatmyotherbook,ApacheCookbook,ThirdEdition,byRichBowenandKenCoar,whichshouldbeavailablearoundthesametimethatthisbookispublished.

YoushouldalsoacquireacopyofJeffreyFriedl’sexcellentbook,MasteringRegularExpressions-http://shop.oreilly.com/product/9780596528126.doWhilethebookisseveralyearsold,itisstillthebestbookonthetopic.

Technicaldetails

ThisbookwaswritteninMarkdown,usingvim —  — andbuiltusinggitbook — https://toolchain.gitbook.com/.

PreviousincarnationswerewritteninLaTeX,ReStructuredText,AsciiDoc,andwhoknowswhatelse.Therealwaysseemstobeanewbookformatoutthere.It’sexhausting.

Youcanalwaysobtainthemostrecentversionofthebookathttp://mod-rewrite.org/,andyou’llusuallybeabletobuyafairlyrecentversionintheAmazonKindlestore.Someday,therewillhopefullybeaprintedversion,too.

Contactinformation,anderratareporting

Introduction

4

http://httpd.apache.org/docs/currenthttp://shop.oreilly.com/product/9780596528126.dohttps://www.vim.org/> — andhttps://toolchain.gitbook.com/http://mod-rewrite.org/

Ifyou’dliketogetinvolvedinthecreationofthisbook,orifyou’dliketotellmeaboutsomethingthatneedsfixed,GotoGitHub-https://github.com/rbowen/mod_rewrite_book-andeithersubmitpullrequestsoropenaticket.Ifyoudon’tknowwhatthatmeans,youarewelcometosubmiterratato,andsomedaytherewillbeahandywaytodothisonthewebsite.Nottoday.

Thisbookisaworkinprogress.Ifyoupurchasedthebookinelectronicform,youshouldbeeligibletoreceiveupdatesfromwhereveryouboughtit.Ifyou’renot,sendmeyouremailreceipt,andI’llsendyouanupdatedversion.

AbouttheAuthor

RichBowenhasbeeninvolvedontheApachehttpserverdocumentationsinceabout1998.HeisalsotheauthorofApacheCookbook,andTheDefinitiveGuidetoApachemod_rewrite.Youcanfrequentlyfindhimin\#httpd,on irc.freenode.net.underthenameof DrBacchusor rbowen.

RichworksatRedHat,intheOSAS(OpenSourceandStandards)group,whereheisanOpenSourceCommunityManager.Seehttp://community.redhat.com/fordetails.

HelivesinLexington,Kentucky,withhiswifeandkids.

Acknowledgements

Thanksto fajita,andtheotherregularson#httpd(onthe irc.freenode.netnetwork). fajitaismyresearchassistant,andknowsmorethaneveryoneelseonthechannelputtogether.Andthefolkson#ahdwhokeepmesane.Orinsane.Dependingonhowyoumeasure.Awarmhogtoeachofyou.

Noneofthiswouldbepossiblewithout mod_rewriteitself,soabigthankyoutoRalfEngelschallforcreatingit,andallthemanypeoplewhohaveworkedonthecodeanddocumentationsincethen.

Finally,athankyoutomymuses,Rhi,Z,andE.

AndtoMaria,whomakeseverythingbeautiful.Andsothatwasallright,BestBeloved.Doyousee?

Introduction

5

https://github.com/rbowen/mod_rewrite_bookmailto:rbowen@rcbowen.commailto:rbowen@rcbowen.comhttp://httpd.apache.org/docs-projecthttp://community.redhat.com/https://engelschall.com/

TableofContentsChapter1:RegularExpressions

TheBuildingBlocksMatchinganythingEscapingcharactersAnchoringtextMatchingoneormorecharactersMatchingzeroormorecharactersRepetitionquantifiersGreedyMatchingMakingamatchoptionalGroupingandcapturingBackreferencesCharacterClassesNegationRegexexamples

EmailaddressPhonenumberMatchingURIsMatchingthehomepageMatchingadirectoryMatchingafiletype

RegextoolsRegexCoachReggypcretestVisualRegexpRegularExpressionTesterOnlinetools

RewriteRulegeneratorsSummary

Chapter1:RegularExpressions

Inthehighandfar-offtimestheElephant,OBestBeloved,hadnotrunk.

—RudyardKiplingTheElephant'sChild

Muchofthecontentinthisbookrequiresthatyouhavesomemasteryofregularexpressions.Indeed,inmyyearsofteachingmod_rewrite,ithasbeenmyobservationthatmostpeopledon’tfind mod_rewritehardatall:they’rejustintimidatedbyregularexpressions.

Thereisoneexcellentbookaboutregularexpressions,andifyouwanttobecomearegularexpression(or"regex")guru,youshouldgetit.ThatbookisMasteringRegularExpressions —  — byJeffreyFriedl.

Ifyoujustwanttoknowenoughaboutregextomastermod_rewrite,readthischapterafewtimes,andthatshouldbesufficient.

Thegoalofthischapteristointroducethebuildingblocks-thebasicvocabulary-andthendiscusssomeofthearcanaofcraftingyourownregularexpressions,aswellasreadingthosethatothershavebequeathedtoyou.Ifyouarealreadyreasonablyfamiliarwithregexsyntax,youcansafelyskipthischapter.

RegularExpressions

6

http://regex.info/book.html> — by

TheBuildingBlocks

Regularexpressionsareameanstodescribeatextpattern, sothatyoucanlookforthatpatterninablockofdata.Thebestwaytoreadanyregularexpressionisonecharacteratatime,soyouneedtoknowwhateachcharacterrepresents.

Thesearethebasicbuildingblocksthatyouwillusewhenwritingregularexpressions.Ifyoudon’talreadyknowregexsyntax,you’llwanttostickabookmarkonthispage,sinceyou’llbereferringtoituntilyoubecomefamiliarwiththesecharacters.TheRegularExpressionVocabularytableisyourkeytotranslatingalineofseeminglyrandomcharactersintoameaningfulpattern.Thetablewillbefollowedbyfurtherexplanationsandexamplesforeachoftheitemsinthetable.

Table1.RegularExpressionVocabulary

Character Meaning

. Anycharacter

\

Escapesacharacterthathasaspecialmeaning.Thus, \.meansaliteral.character.Youcanmatchaliteral \characterbyusing \\.Additionally,placing \infrontofaregularcharactercanaddaspecialmeaningtothatcharacter.Forexample, \tmeansatabcharacter.SeeEscapingcharactersformoredetailonthat.

̂ Ananchorwhichinsiststhatthepatternstartatthebeginningofthestring. ̂ AmeansthatthestringmuststartwithA.

$Ananchorwhichinsiststhatthestringendswiththespecifiedpattern. X$meansthatthestringmustendwithX.

+Matchthepreviousthingoneormoretimes.So a+meansoneormorea’s.

*Matchthepreviousthingzeroormoretimes.Thisisthesameas+,exceptthatit’salsoacceptableifthethingwasn’tthereatall.

?Matchthepreviousthingzerooronetimes.Inotherwords,itmakesitoptional.Italsomakesthe *and +charactersnon-greedy.SeeGreedyMatching.

{n,m}Indicatesthatthepreviousthingshouldmatchatleastn,andnotmorethanmtimes.Forexample, a{2,7}matchesatleast2,andnotmorethan7,occurrencesofthelettera

()

Providesgroupingandcapturingfunctions.Groupingmeanstreatingmorethanonecharacterasthoughtheywereasingleunit.Youcanapplyrepetitioncharacterstoagroupcreatedinthisway.Capturingmeansrememberingthethingthatmatched,sothatwecanuseitagainlater.Thisiscalleda'backreference.'

[]Calleda"characterclass,"thismatchesonlyoneofthecontainedcharacters.Forexample, [abc]matchesasinglecharacterwhichiseitheraorborc.

̂

Negatesamatchwithinacharacterset.(Rememberthatoutsideofacharacterclass,itmeanssomethingelse.Seeabove.)Thus, [^abc]matchesasinglecharacterwhichisneitheranorbnorc.

[1]

RegularExpressions

7

! Placedonthefrontofaregularexpression,thismeans"NOT".Thatis,itnegatesthematch,andsosucceedsonlyifthestringdoesnotmatchthepattern.

That’snotallthereistoregularexpressions,butit’sareallygoodstartingpoint.Eachregularexpressionpresentedinthisbookwillhaveanexplanationofwhatit’sdoing,whichwillhelpyouseeinpracticalexampleswhateachoftheabovecharactersactuallyendsupmeaninginthewild.And,inmyexperience,regularexpressionsareunderstoodmuchmorequicklyviaexamplesratherthanvialectures.

Whatfollowsisamoredetailedexplanationofeachoftheitemsinthetableabove,withexamples.

Matchinganything

The .characterinaregularexpressionmatchesanycharacter.Forexample,considerthefollowingpattern:

a.c

Thatpatternmatchesastringcontaining a,followedbyanycharacter,followedby c.So,thatpatternmatchesthestrings"abc","ancient",and"warcraft",eachofwhichcontainthatpattern.Itdoesnotmatch"tragic",ontheotherhand,becausetherearetwocharactersbetweentheaandthec.Thatis,the .byitself,matchesasinglecharacteronly.

The .characterisveryfrequentlyusedinconnectionwith tomean"matcheverything".You’llseethe (.)patternappearingoftenthroughoutthisbook,andthroughoutexamplesthatyouseeonline.Andwhileit’softenwhatyouwant,it’sjustasoftenusedincorrectly.Rememberthatwhile (.*)matchesanystring,sowillthesimplerandfasterpattern ̂ becauseeverystringhasastart(evenanemptystring)andso ̂ matchesit.

It’sfaster,too,becausewhile (.)hastomatchallthewayouttotheendofthestring, ̂ onlyhastonotethatthestringhasabeginning,andthenitisdone.Notealsothatthepattern (.)hasparenthesisandthereforecapturesthematchedstringintothevariable $1.Ifyou’renotplanningtouse $1inalatersubstitution,thenthis,inadditiontobeingawasteofcomputationcycles,isawasteofmemory.

Whileconsiderationsofthiskindprobablywon’tsaveyouanoticeableamountoftime,gettingintothehabitofwritingefficientregularexpressionswill,inthelongrun,notonlysaveyouthesesmallamounts,butwillresultinrulesthatareeasiertounderstandandeasiertomaintain,becausetheymatchonlywhatyou’reinterestedin,andnothingmore.

Escapingcharacters

Thebackslash,orescapecharacter,eitheraddsspecialmeaningtoacharacter,orremovesit,dependingonthecontext.Forexample,you’vealreadybeentoldthatthe .characterhasspecialmeaning.Butifyouwanttomatchtheliteral .character,thenyouneedtoescapeitwiththebackslash.So,while .means"anycharacter," \.meansaliteral"."character.

Conversely,somecharactersgainspecialmeaningwhenprefixedbya \character.Forexample,whilesmeansaliteral"s"character, \smeansa"whitespace"character.Thatis,aspaceoratab.

TheMetacharactertablebelowlistsusefulescapecharactersthatyou’llseethroughoutthebookandcanbeusedasshorthandformoreverbosepatterns.

Table2.Metacharacters

Character Meaning

\d Matchanycharacterintherange0-9

\D MatchanycharacterNOTintherange0-9

RegularExpressions

8

\s Matchanywhitespacecharacters(space,tabetc.).

\S MatchanycharacterNOTwhitespace(space,tab).

\w Matchanycharacterintherange0-9,A-Zanda-z

\W MatchanycharacterNOTtherange0-9,A-Zanda-z

\bWordboundary.Matchanycharacter(s)atthebeginning( \babc)and/orend( abc\b)ofaword,thus \bcow\bwillmatchcowbutnotcows,but \bcowwillmatchcows.

\B

Notawordboundary.Matchanycharacter(s)NOTatthebeginning( \Babc)and/orend( cow\B)ofaword,thus\Bcow\Bwillmatchscowsbutnotcows,but cow\Bwillmatchcoward.

\t Matchatabcharacter

\n Matchanewlinecharacter

\xMatchesacharacterwithaparticularhexcode.Forexample, \x5AwouldmatchaZ,whichhasahexcodeof5A.

Theterm"metacharacter"isoftenalsoappliedtocharacterssuchas .and $whichhavespecialmeaningswithinregularexpressions.

Anchoringtext

Referredtoasanchorcharacters,theseensurethatastringstartswith,orendswith,aparticularcharacter,orsequenceofcharacters.Sincethisisaverycommonneed,theseareincludedinthisbasicvocabulary.Considertheexamplesinthe`anchorexamplestable`_

Table3.Anchorexamples

Example Meaning

̂ / Thismatchesanystringthatstartswithaslash

.jpg$ Thispatternmatchesanystringthatendswith.jpg.

/$Matchesastringthatstartswith,andendswith,aslash.Thatis,itwillonlymatchastringthatisasingleslash,andnothingelse.

̂ $Matchedanemptystring-thatis,astringthathasnothingbetweenitsstartanditsend.

Remember,asyoucraftyourregularexpressions,thattheyare,bydefault,asubstringmatch.Whichistosay,apatternof cowmatchescow,scow,coward,andpericowperitis,becausetheyallcontain"cow"somewhereinthem.Usingtheanchorcharactersallowyoutobemorespecificastowhatyouwantedtomatch.The \bmetacharacter,introducedabove,canalsobeusefulinsomecontexts,butperhapslesssowhenyou’redealingwithURLs.

Matchingoneormorecharacters

RegularExpressions

9

The+characterallowsapatternorcharactertomatchmorethanonce.Forexample,thefollowingpatternwillallowforcommonmisspellingsoftheword"giraffe".

giraf+e+

Thispatternwillallowoneormoref’s,aswellasoneormoree’s.Soitmatches"girafe","giraffe",and"giraffee".Itwillalsomatch"girafffffeeeeee".

Besuretouse +ratherthan *whenyouwanttoensurenon-emptymatches.

Matchingzeroormorecharacters

The *characterallowsthepreviouscharactertomatchzeroormoretimes.Thatistosay,it’sexactlythesameas+,exceptthatitalsoallowsforthepatterntonotmatchatall.Thisisoftenusedwhen+wasmeant,whichcanresultinsomeconfusionwhenitmatchesanemptystring.Asanexample,we’lluseaslightmodificationofthepatternusedintheabovesection:

giraf*e*

Thispatternmatchesthesamestringslistedabove("giraffe","girafe"and"giraffee")butwillalsomatchthestring"giraeeeee",whichcontainszero"f"characters,aswellasthestring"gira",whichcontainszero"f"charactersandzero"e"characters.

Mostcommonly,you’llseeitusedinconjunctionwiththe.character,meaning"matchanything."Frequently,inthatcase,thepersonusingithasforgottenthatregularexpressionsaresubstringmatches.Forexample,considerthispattern:

.*\.gif$

Theintentofthatpatternistomatchanystringendingin.gif.The $insiststhatitisattheendofthestring,andthe \beforethe.makesthataliteral.character,ratherthanthewildcard.character.Inthisparticularcase,the .*wastheretomean"startswithanything,"butiscompletelyunnecessary,andwillonlyservetoconsumetimeinthematchingprocess.

Amoreusefulexampleofthe *characterisonewhichchecksforacommentlineinanApacheconfigurationfile.Thefirstnon-spacecharacterneedstobea #,butthespacesareoptional:

^\s*#

Thispattern,then,matchesastringthatmight(butdoesn’thaveto)beginwithwhitespace,followedbya .Thisensuresthatthefirstnon-spacecharacterofthelineisa .

Repetitionquantifiers

Ifyouwanttomatchaparticularnumberoftimes,youcanusethe {n,m}quantifiertospecifytherangeoftimesyouwishtomatch.Thepossibilitiesofhowyoucanspecifythisareshowninthetablebelow.

Table4.Repitionquantifiers

Pattern Meaning

{n} Matchexactlyntimes

{n,} Matchatleastntimes

{n,m} Matchatleastntimes,butnotmorethanmtimes

RegularExpressions

10

Theserepititionquantifiersmaybeappliedtoasinglecharacter,ortoagrouping.Forexample:

\d{1,3}

willmatch1,2,or3digits.

[abc]{2,5}

Willmatchanywherefrom2to5instancesofa,b,orc.

GreedyMatching

Inthecaseofalloftherepetitioncharactersabove,matchingisgreedy.Thatis,theregularexpressionmatchesasmuchasitpossiblycan.Thatis,ifyouapplytheregularexpression a+tothestring aaaa,matchestheentirestring,andnotbesatisfiedbyjustthefirsta.Thisisparticularlyimportantwhenyouareusingthe .*syntax,whichcanoccasionallymatchmorethanyouthoughtitwould.I’llgivesomeexamplesofthisafterwe’vediscussedafewmoremetacharacters.

Ontheotherhand,ifyouwishformatchestonotbegreedy,youcanoffsetthegreedynatureoftherepetitioncharacterbyputtinga ?afterit.

Consider,forexample,ascenariowhereIwanttomatcheverythingbetweentwoslashesinaURL.I’llbeapplyingtheregularexpressiontotheURI /one/two/three/,andI’lltryagreedy,andnot-greedy,regularexpression.The`tableofgreedyexamples`_showstheresultsofthesepatterns.

Table5.Examplesofgreedymatching

Pattern Matches

/(.*)/ one/two/three

/(.*?)/ one

Thefirstregexisgreedy,andmatchesasmuchasitpossiblycan,goingouttothelastslash.Thesecondisnon-greedy,andsostopsasearlyasitcan,whenitencountersthesecondslash.

Makingamatchoptional

The ?charactermakesasinglecharactermatchoptional.Thisisextremelyusefulforcommonmisspellings,orelementsthatmay,ormaynot,appearinastring.Forexample,youmightuseitinawordwhenyou’renotsurewhetherit’ssupposedtobehyphenated:

e-?mail

Theabovepatternmatchesboth"email"and"e-mail",sothateitherspellingwillbeaccepted.Likewise,youcoulduse:

colou?r

tomatchthewordcolorbothasitisspelledintheUSA,andthewaythatitisspelledintherestoftheworld.

Additionally,the ?characterturnsoffthe"greedy"natureofthe +and characters.Thus,puttinga ?aftera +ora willmakeitmatchaslittleasitpossiblycan.SeeGreedyMatching.

Furtherexamplesofthegreedyvs.non-greedbehaviorwillfollowoncewehavelearnedaboutbackreferences.

RegularExpressions

11

Groupingandcapturing

Parenthesesallowyoutogroupseveralcharactersasaunit,andalsotocapturetheresultsofamatchforlateruse.Theabilitytotreatseveralcharactersasaunitisextremelyusefulinpatternmatching.Thinkofitascombiningseveralatomsintoasinglemolecule.Forexample,considerthisexample:

(abc)+

Thiswilllookforthesequence"abc"appearingoneormoretimes,andsowouldmatchthestring"abc"andthestring"abcabc".

Backreferences

Evenmoreusefulisthe"capturing"functionalityoftheparentheses.Onceapatternhasmatched,youoftenwanttoknowwhatmatched,sothatyoucanuseitlater.Thisisusuallyreferredtoas"backreferences."

Forexample,youmaybelookingfora.giffile,asintheexampleabove,andyoureallywanttoknowwhat.giffileyoumatched.Bycapturingthefilenamewithparentheses,youcanuseitlateron:

(.*\.gif)$

Intheeventthatthispatternmatches,wewillcapturethematchingvalueinaspecialvariable, $1.(Insomecontexts,thevariablemaybecalled %1instead.)Ifyouhavemorethanonesetofparentheses,thesecondonewillbecapturedtothevariable$2,thethirdto $3,andsoon.Onlyvaluesupthrough $9areavailable,however.Thereasonforthisisthat $10wouldbeambiguous.Itmightmean $1,followedbyaliteralzero(0),oritmightmean $10.Ratherthanprovidingadditionalsyntaxtodisambiguatethisterm,thedesignerofmod_rewriteinsteadchosetoonlyprovidebackreferencesthrough $9.

Theexactwayinwhichyoucanexploitthisfeaturewillbemoreobviouslater,oncewestartlookingattheRewriteRuledirectivein:ref:`RewriteRule`

Considerthesetwopatterns,appliedtothestring"canadian".

c(.*)nc(.*?)n

Thefirstpatternwillreturnwithavalueof"anadia"in $1,sinceitwillmatchasmuchasitpossiblycanbetweenthefirstcandthelastnitsees.Thesecond,ontheotherhand,willreturnwith $1setto"a",sinceitisnon-greedy,andsostopsatthefirstnitsees.

TODORecommendthecorrectregextool

ItisinstructivetoacquireatoolsuchasRegexCoach,orRebug,mentionedintheRegextoolssectionbelow,andfeedthemthesepatternsandstrings,towatchthemmatchthedifferentpartsofthestring.MasteringRegularExpressionsalsohasaverycompletetreatmentofbackreferences,greedymatching,andwhatactuallyhappensduringthematchingphase.

CharacterClasses

Acharacterclassallowsyoutodefineasetofcharacters,andmatchanyoneofthem.Thereareseveralbuilt-incharacterclasses,likethe \smetacharacterthatyousawabove.Usingthe []notationletsyoudefineyourowncustomcharacterclasses.Asaverysimpleexample,considerthefollowing:

[abc]

RegularExpressions

12

Thischaracterclassmatchesthelettera,ortheletterb,ortheletterc.Forexample,ifwewantedtomatchthesubsetofuserswhoseusernamesstartedwithoneofthoseletters,wemightlookforthepattern:

/home/([abc].*)

Thiscombinesseveralofthecharactersthathavebeendescribedabove.Itendsupmatchingadirectorypathforthatsubsetofusers,andtheusernameendsupinthe $1variable.Well,actually,notquite,aswe’llseeinaminute,butalmost.

Thecharacterclasssyntaxalsoallowsyoutospecifyarangeofcharactersfairlyeasily.Forexample,ifyouwantedtomatchanumberbetween1and5,youcanusethecharacterclass [1-5].

Withinacharacterclass,the ̂ characterhasspecialmeaning,ifitisthefirstcharacterintheclass.Thecharacterclass [^abc]istheoppositeofthecharacterclass [abc].Thatis,itmatchesanycharacterwhichisnota,b,orc.

Whichbringsusbacktotheexampleabove,whereweareattemptingtomatchausernamestartingwitha,b,orc.Theproblemwiththeexampleisthatthe *characterisgreedy,meaningthatitattemptstomatchasmuchasitpossiblycan.Ifwewanttoforceittostopmatchingwhenitreachesaslash,weneedtomatchonly"notslash"characters:

/home/([abc][^/]+)

I’vereplacedthe .with [^/]+whichhastheeffectthat,ratherthanmatchinganycharacter,itmatchesonlynot-slashcharacters.Inotherwords,itwillonlymatchuptoaslash,ortheendofthestring,whichevercomesfirst.Also,I’veused +insteadof ,sinceone-characterusernamesaretypicallynotpermitted.Now, $1willcontaintheusername,whereas,before,itcouldpossiblyhavecontainedotherdirectorypathcomponentsaftertheusername.

Negation

a. index::Negation

b. index::!

Finally,ifyouwishtonegateanentireregularexpressionmatch,prefixitwith!.Thisisnotconsistentacrossallregularexpressionimplementations,butcanbeusedinanumberofthem.Averycommonuseofthisinthecontextofrewriteruleswillbetoindicatethatyouwantapatterntoapplytoalldirectoriesexceptforone.So,forexample,ifwewantedtoexcludethe/imagesdirectoryfromconsideration,wewouldmatchthe/imagesdirectory,butthennegatethematch,thus:

!^/images

Thismatchesanypathnotstartingwith /images.We’llseemoreofthiskindofpatternmatchespeciallyinthechapter:ref:`Proxyingwithmod_rewrite`.

Regexexamples

a. index::Examples

b. index::Regexexamples

Afewexamplesmaybeinstructiveinyourunderstandingofhowregularexpressionswork.We’llstartwithafewofthecasesthatyoumayfrequentlyencounter,andsuggestafewalternatesolutionstoeach.

Emailaddress

a. index::Emailaddress

We’llstartwithacommonfavorite.Youwanttocraftaregularexpressionthatmatchesanemailaddress.Thegeneralformatofanemailaddressis"something@somethingdotsomething".Whenyouarecraftingaregularexpressionfromscratch,it’sgoodtoexpressthepatterntoyourselfintermslikethis,becauseit’sagoodstarttowardswritingtheexpressionitself.

RegularExpressions

13

Toexpressthisasaregularexpression,let’stakethecomponentparts.Thecatchall"something"partcanlikelybeexpressedas.*andthe .and @partsareliteralcharacters.So,thisgivesusastartingpointof:

.*@.*\..*

Thisisagoodstart,andmatchesmostemailaddresses.Itwillprobablymatchallemailaddresses.However,itwillalsomatchalotofstuffthatisn’temailaddresses,like"@@@.@","@.com",and"Thisisn’tanem@iladdress."Sowehavetotrysomethingalittlemorespecific.

Wewanttorequirethatthe"something"beforethe@signisnotzerolength,andcontainscertaintypesofcharacters.Forexample,itshouldbealpha-numeric,butmayalsocontaincertainotherspecialcharacters,likedot,underscore,ordash.

Fortunately,PCREprovidesuswithaconvenientwaytosay"alpha-numericcharacters,",usinganamedcharacterclass.Therearequiteanumberofthese,suchas [:alpha:]tomatchletters, [:digit:]tomatchnumbers0through9,and [:alnum:]tomatchalpha-numericcharacters.

Next,wewanttoensurethatthedomainnamepartofthepatternisalphanumerictoo,exceptthatthetopleveldomain(tld),i.e.,thelastpartofthedomainname,mustbeletters.

Andwewanttoallowanarbitrarynumberofdotsinthehostname,sothat"a.com"and"mail.s.ms.uky.edu"arebothvalidhostnameportionsofanemailaddress.Sowecansaytheabovedescriptionas:

^[:alnum:]._-]@(\.)[:alpha:]+$

Thisisfarmorespecific,andwillmatchmostvalidemailaddresses.However,itwillalsoexcludeafewedge-cases,aswellasallowingsomethingsthatarenotvalidaddresses,suchasinvaliddomainnames.

Youshouldnotethatthiswassomethingofafool’serrand-theredoesnotexistaregularexpressionthatmatchesallpossibleemailaddresses.Indeed,Istartedwiththisexampletogiveyouaflavorforjusthowcomplicateditcanbetocraftapatternforsomethingthatisnotwelldefined.

Formorediscussionofwritingregularexpressionstomatchemailaddresses,simplysearchfor emailregexinyourfavoritesearchengine,andyou’llfindmany,manyarticlesabouthowandwhyitisimpossible.

Phonenumber

a. index::Phonenumber

Nextwe’llconsidertheproblemofmatchingaphonenumber.Thisismuchharderthanitwouldatfirstappear.We’llassume,forthesakeofsimplicity,thatwe’rejusttryingtomatchUSphonenumbers,whichare10numbers.

Thenumberconsistsofthreenumbers,thenthreemore,thenfourmore.Thesenumbersmay,ormaynot,beseparatedbyavarietyofthings.Thefirstthreemayormaynotbeenclosedinparentheses.Sowe’lltrysomethinglikethis:

\(?\d{3}\)?[-.]?\d{3}[-.]?\d{4}

ThispatternmatchesmostUSphonenumbers,inmostoftheordinaryformats.Thefirstthreenumbersmayormaynotbeinparentheses,andtheblocksofnumbersmayormaynotbeseparatedbydashes(-),dots(.)orspaces.

Itisstillfarfromfoolproof,becauseuserswillcomeupwithwaystosubmitdatainunexpectedformat.

Let’sgothoughtheruleonepieceatatime:

\(?-Thissub-patternrepresentsanoptionalopeningparenthesis.Thebackslashisnecessarybecauseparenthesesalreadyhavespecialmeaninginregularexpressions.Wewanttoremovethatspecialmeaning,andhavealiteralopeningparenthesis.Thequestionmarkmakesthischaracteroptional.Thatis,thepersonenteringthedatamayormaynotenclosethefirstthreenumberswithparenthesis,andwewanttoensurethateitheroneisacceptable.

RegularExpressions

14

\d{3}- \dmeansadigit.(Remember:dfordigit.)Thiscanalsobewrittenas [:digit:],butthe \dnotationtendstobemorecommon,forthesimplereasonthatit’slesstotype.The {3}followingthe \dindicatesthatwewanttomatchthecharacterexactlythreetimes.Thatis,werequirethreedigitsinthisportionofthematch,oritwillreturnfailure.

SeethesectionRepetitionquantifiersforthevarioussyntaxesyoucanusetoindicatethenumberofrepetitionsyouwant.

\)?-Liketheopeningparenthesiswestartedwith,thisisanoptionalclosingparenthesis.

[-.]?-Anotheroptionalcharacter,thisallows,butdoesnotrequire,adash,adot,oraspace,toappearbetweenthefirstthreenumbersandthenextthreenumbers.

Ifyoudiscoverthatyourusersareseparatingblockswith,say,anunderscore,youcouldmodifythispartofthepatterntobe [-._]instead,toincludethisnewcharacter.

Therestoftheexpressionisexactlythesameaswhatwehavealreadydone,exceptthatthelastblockofnumberscontains4numbers,ratherthanthree.

Thenextstepincraftingaregularexpressionistothinkofthewaysinwhichyourpatternwillbreak,andwhetheritisworththeadditionalworktocatchtheseedgecases.Forexample,someuserswillentera1beforetheentirenumber.Somephonenumberswillhaveanextensionnumberontheend.Andthatonehard-to-pleaseuserwillinsistonseparatingthenumberswithaslashratherthanoneofthecharacterswehavespecified.Thesecanprobablybesolvedwithamorecomplexregex,buttheincreasedcomplexitycomesatthepriceofspeed,aswellasalossofreadability.Ittookapagetoexplainwhatthecurrentregexdoes,andthat’satleastsomeindicationofhowmuchtimeitwouldtakeyoutodecipheraregexwhenyoucomebacktoitinafewmonthsandhaveforgottenwhatitissupposedtobedoing.

MatchingURIs

Finally,sincethisis,afterall,abookaboutmod_rewrite,itseemsreasonabletogivesomeexamplesofmatchingURIs,asthatiswhatyouwillprimarilybedoingfortherestofthebook.

Mostofthedirectivesthatwewilldiscussintheremainderofthebook,takeregularexpressionsasoneoftheirarguments.And,muchofthetime,thoseregularexpressionswilldescribeaURI,whichisthetechnicaltermfortheresourcethatwasrequestedfromyourserver.Andmostofthetime,thatmeanseverythingafterthehttp://www.domain.compartofthewebaddress.

I’llgiveseveralcommonexamplesofthingsthatyoumightwanttomatch.

Matchingthehomepage

Veryfrequently,peoplewillwanttomatchthehomepageofthewebsite.Typically,thatmeansthattherequestedURIiseithernothingatall,oris/,orissomeindexpagesuchas/index.htmlor/index.php.Thecasewhereitisnothingatallwouldbewhentherequestedaddresswashttp://www.example.comwithnotrailingslash.

First,I’llconsiderthecasewheretheyrequesteitherhttp://www.example.comorhttp://www.example.com/(ie,withorwithoutthetrailingslash,butwithnofilerequested).Inotherwords,wewanttomatchanoptionalslash.

Asyouprobablyrememberfromearlier,youusethe ?charactertomakeamatchoptional.Thus,wehave: ̂ /?$

Thismatchesastringthatstartswith,andendswith,anoptionalslash.Or,stateddifferently,itmatcheseithersomethingthatstartsendswithaslash,orsomethingthatstartsandendswithnothing.

Next,weintroducetheadditionalcomplexityofthefilename.Thatis,wewanttomatchanyofthefollowingfourstrings:

Theemptystring-thatis,theyrequestedhttp://www.example.comwithnotrailingslash.

/-theyrequestedhttp://www.example.com/withatrailingslash.

/index.html

/index.php

RegularExpressions

15

http://www.domain.comhttp://www.example.comhttp://www.example.comhttp://www.example.com/http://www.example.comhttp://www.example.com/

We’llbuildontheregexthatwehadlasttime,addingtheseadditionalrequirements:

^/?(index\.(html|php))?$

Thisisn’tquiteright,asyou’llseeinamoment,butit’smostlyright.Itdoes,however,introduceanewsyntaxthathasn’tbeenmentionedheretofore.Thatisthe |syntax,whichhasthefancynameof"alternation"andmeans"oneortheother."So(html|php)means"either'html'or'php'."

So,we’vegotaregexthatmeansastringthatstartswithaslash(optional)followedbyindex.,followedbyeither htmlor php,andthatentirestring(startingwiththeindex)isalsooptional,andthenthestringends.

Theoneproblemwiththisregexisthatitalsomatchesthestrings'index.php'and'index.html',withoutaleadingslash.While,strictlyspeaking,thisisincorrect,intheactualcontextofmatchingaURI,itisprobablyfine,inmostscenarios,toignorethatparticulartechnicality.Note,however,thattherearelotsofpeoplewhospendalotoftimetryingtofigureouthowtoexploittechnicalitieslikethis,sobecareful.

Matchingadirectory

a. index::Directory

IfyouwantedtofindoutwhatdirectoryaparticularrequestedURIwasin,or,perhaps,whatkeyworditstartedwith,youneedtomatcheverythinguptothefirstslash.Thiswilllooksomethinglikethefollowing:

/]+)

Thisregexhasanumberofcomponents.First,there’sthestandard ̂ /whichwe’llseealot,meaning"startswithaslash."Followingthat,wehavethecharacterclass [^/],whichwillmatchany"notslash"character.Thisisfollowedbya+indicatingthatwewantoneormoreofthem,andenclosedinparenthesessothatwecanhavethevalueforlaterobservation,in $1.

Matchingafiletype

Forthethirdexample,we’lltrytomatcheverythingthathasaparticularfileextension.This,too,isaverycommonneed.Forexample,wewanttomatcheverythingthatisanimagefile.Thefollowingregexwilldothat,forthemostcommonimagetypes:

\.(jpg|gif|png)$

Lateron,you’llseehowtomakethiscaseinsensitive,sothatfileswithupper-casefileextensionsarealsomatched.

Regextools

TODOEnsurethatthesetoolsallstillexist.

Ifyou’regoingtospendmorethanjustalittletimemessingwithregexes,you’reeventuallygoingtowantatoolthathelpsyouvisualizewhat’sgoingon.Thereareanumberofthemavailable,eachofwhichhasdifferentstrengthsandweaknesses.You’llfindthatmostofthereallygoodtoolsforregularexpressiondevelopmentcomeoutofthePerlcommunity,whereregularexpressionsareparticularlypopular,andtendtogetusedinalmosteveryprogram.

RegexCoach

RegexCoachisavailableforWindowsandLinux,andcanbedownloadedfromhttp://www.weitz.de/regex-coach.RegexCoachallowsyoutostepthrougharegularexpressionandwatchwhatitdoesanddoesnotmatch.Thiscanbeextremelyinstructiveinlearningtowriteyourownregularexpressions.

TODO

/([

RegularExpressions

16

http://www.weitz.de/regex-coach

SCREENSHOT

RegexCoachisfree,butitisnotOpenSource.

Reggy

ReggyisaMacOSXapplicationthatprovidesasimpleinterfaceforcraftingandtestingregularexpressions.Itwillidentifywhatpartsofastringarematchedbyyourregularexpression.

Reggyisavailableathttp://code.google.com/p/reggy/andislicensedundertheGPL.

TODOSCREENSHOT

pcretest

pcretestisacommand-lineregularexpressiontesterthatisavailableonmostdistributionsofLinux,whereitisusuallyinstalledbydefault.

Inadditiontosimplytellingyouwhetheraparticularstringmatchedornot,itwillalsotellyouwhateachofthevariousbackreferenceswillbesetto.

IntheSCREENSHOTyoucanseewhateachofthevariousbackreferenceswillbesettooncetheregularexpressionhasbeenevaluated.

TODO:Screenshot

VisualRegexp

VisualRegexp,availableathttp://laurent.riesterer.free.fr/regexp/,hasmorefeaturesthantheoptionslistedabove,andmightbeagoodoptiononceyouhavemasteredthebasicsofregularexpressionsandarereadytomoveontosomethingalittlemoresophisticated.Itshowsbackreferences,andoffersawidevarietyofsuggestionstohelpbuildaregex.

VisualRegexpisavailableasaWindowsexecutableorasaTcl/Tkscript.

TODOSCREENSHOT

RegularExpressionTester

Ratherthanbeingastand-aloneapplicationliketheotherslistedabove,thisisaFirefoxplugin.It’savailableathttps://addons.mozilla.org/en-US/firefox/addon/2077,and,ofcourse,requiresFirefoxtowork.

Onlinetools

a. index::Onlineregextesters

Inadditiontothesetools,therearemanyonlinetools,whichyoucanusewithouthavingtodownloadorinstallanything.Theseareofawidevarietyoffeaturesetsandquality,soI’dencourageyoutoshoparoundalittletofindonethatseemstoworkwell.Theseappearanddisappearonaweeklybasis,andsoIcan’tpromisethatthesesiteswillstillbeavailableatthetimethatyoureadthis,butherearesomethatareworthmentioningatthetimeofwriting:

RegExr

a. index::RegExr

RegularExpressions

17

http://code.google.com/p/reggy/http://laurent.riesterer.free.fr/regexp/https://addons.mozilla.org/en-US/firefox/addon/2077http://gskinner.com/RegExr/

http://gskinner.com/RegExr/-Includesavarietyofpre-definedcharacterclasses,andtheabilitytosaveyourregularexpressionsforlaterreference.RequiresJavascripttouse.

RegexPal

a. index::RegexPal

http://regexpal.com/-Lessfull-featuredthanRegExr,butsufficientforthepurposeofcraftingandtestingregularexpressionsforthepurposeofmod_rewrite,whichdoesn’trequirereplacefunctionalityormulti-linematches.

RewriteRulegenerators

YoumayfindvariouswebsitesthatpurporttobeRewriteRulegenerators.Istronglyencourageyoutoavoidthese,andinsteadtolearnhowtocraftyourownrules.I’veevaluatedseveralofthesesites,andeveryonehasresultedinRewriteRuledirectivesthatwereeitherenormouslyinefficient,orcompletelywrong.

Summary

HavingagoodgraspofRegularExpressionsisanecessaryprerequisitetoworkingwithmod_rewrite.Alltoooften,peopletrytobuildregularexpressionsbythebrute-forcemethod,tryingvariousdifferentcombinationsatrandomuntilsomethingseemstomostlywork.Thisresultsinexpressionsthatareinefficientandfragile,aswellasagreatwasteoftime,andmuchfrustration.

Keepabookmarkinthischapter,andreferbacktoitwhenyou’retryingtofigureoutwhataparticularregexisdoing.

OtherrecommendedreferencesourcesincludethePerlregularexpressiondocumentation,whichyoucanfindonlineathttp://www.perldoc.com/perl5.8.0/pod/perlre.htmlorbytyping perldocperlreatyourcommandline,andthePCREdocumentation,whichyoucanfindonlineathttp://pcre.org/pcre.txt.Thisisusefulevenifyou’reusingregexinotherimplementations(like mod_rewrite,forexample),sincethesyntaxislargelythesameacrossimplementations.

1.technically,it’sanydata,butinthecontextofApachehttpd,we’reprimarilyinterestedintextasitappearsinURLs

RegularExpressions

18

http://regexpal.com/http://www.perldoc.com/perl5.8.0/pod/perlre.htmlhttp://pcre.org/pcre.txt

TableofContentsChapter2:URLMapping

mod_rewriteDocumentRootAutomaticdirectorylistingsAliasRedirectLocationVirtualHostsProxyingmod_actionsmod_imagemapmod_negotiationFilenotfound

Chapter2:URLMapping

Inthischapter,we’lldiscussthevariouswaysthattheApachehttpserverhandlesURLMapping.

WhentheApachehttpserverreceivesarequest,itisprocessedinavarietyofwaystoseewhatresourceitrepresents.ThisprocessiscalledURLMapping.

mod_rewriteispartofthisprocess,butwillbehandledseparately,sinceitisalargeportionofthecontentsofthisbook.

Theexactorderinwhichthesestepsareappliedmayvaryfromoneconfigurationtoanother,soitisimportanttounderstandnotonlythesteps,butthewayinwhichyouhaveconfiguredyourparticularserver.

mod_rewrite

mod_rewriteisperhapsthemostpowerfulpartofthisprocess.Thatis,ofcourse,whyitfeaturesprominentlyinthenameofthisbook.Indeed,mod_rewritespansseveralchaptersofthisbook,andhasanentirePartallitsown,partmod_rewrite.

Fornow,we’lljustsaythatmod_rewritefillsavarietyofdifferentrolesintheURLmappingprocess.Itcan,amongotherthings,modifyaURLonceitisreceived,inmanydifferentways.

WhilethisusuallyhappensbeforetheotherpartsofURLmapping,incertaincircumstances,itcanalsoperformthatrewritinglateronintheprocess.

This,andmuchmore,willberevealedinthecomingchapters.

DocumentRoot

TheDocumentRootdirectivespecifiesthefilesystemdirectoryfromwhichstaticcontentwillbeserved.It’shelpfultothinkofthisasthedefaultbehavioroftheApachehttpserverwhennoothercontentsourceisfound.

Consideraconfigurationofthefollowing:

DocumentRoot/var/www/html

Withthatsettinginplace,arequestforhttp://example.com/one/two/three.htmlwillresultinthefile/var/www/html/one/two/three.htmlbeingservedtotheclientwithaMIMEtypederivedfromthefilename-inthiscase,text/html.

TheDirectoryIndexdirectivespecifieswhatfile,orfiles,willbeservedintheeventthatadirectoryisrequested.Forexample,ifyouhavetheconfiguration:

URLMapping

19

http://example.com/one/two/three.html

TheDirectoryIndexdirectivespecifieswhatfile,orfiles,willbeservedintheeventthatadirectoryisrequested.Forexample,ifyouhavetheconfiguration:

DocumentRoot/var/www/htmlDirectoryIndexindex.htmlindex.php

ThenwhentheURLhttp://example.com/one/two/isrequested,Apachehttpdwillattempttoservethefile/var/www/html/index.htmland,ifit’snotabletofindthat,willattempttoservethefile/var/www/html/index.php.

Ifneitherofthosefilesisavailable,thenextthingitwilltrytodoisserveadirectoryindex.

Automaticdirectorylistings

Themodulemod_autoindexservesafilelistingforanydirectorythatdoesn’tcontainaDirectoryIndexfile.(SeeDirectoryIndex.)

Topermitdirectorylistings,youmustenabletheIndexessettingoftheOptionsdirective:

Options+Indexes

SeethedocumentationoftheOptionshttp://httpd.apache.org/docs/current/mod/core.html#optionsforfurtherdiscussionofthatdirective.

IftheIndexesoptionison,thenadirectorylistingwillbedisplayed,withwhateverfeaturesareenabledbytheIndexOptionsdirective.

Typically,adirectorywilllookliketheexampleshownbelow.

Forfurtherdiscussionoftheautoindexfunctionality,consultthemod_autoindexdocumentationathttp://httpd.apache.org/docs/current/mod/mod_autoindex.html.

URLMapping

20

http://example.com/one/two/http://httpd.apache.org/docs/current/mod/core.html#optionshttp://httpd.apache.org/docs/current/mod/mod_autoindex.html

Futureversionsofthisbookwillincludemoredetailedinformationaboutdirectorylistings.

Alias

TheAliasdirectiveisusedtomapaURLtoadirectorypathoutsideofyourDocumentRootdirectory.

Alias/icons/var/www/icons

AnAliasisusuallyaccompaniedbyastanzagrantinghttpdpermissiontolookinthatdirectory.InthecaseoftheaboveAlias,forexample,addthefollowing:

Requireallgranted

Or,ifyou’reusinghttpd2.2orearlier:

Orderallow,denyAllowfromall

There’saspecialformoftheAliasdirective-ScriptAlias-whichhastheadditionalpropertythatanyfilefoundinthereferenceddirectorywillbeassumedtobeaCGIprogram,andhttpdwillattempttoexecuteitandsenttheoutputtotheclient.

CGIprogrammingisoutsideofthescopeofthisbook.Youmayreadmoreaboutitathttp://httpd.apache.org/docs/current/howto/cgi.html

Redirect

ThepurposeoftheRedirectdirectiveistocausearequestedURLtoresultinaredirectiontoadifferentresource,eitheronthesamewebsiteoronadifferentserverentirely.

TheRedirectdirectiveresultsinaLocationheader,anda30xstatuscode,beingsenttotheclient,whichwillthenmakeanewrequestforthespecifiedresource.

Theexactvalueofthe30xstatuscodewillinfluencewhattheclientdoeswiththisinformation,asindicatedinthetablebelow:

Code Meaning

300 MultipleChoice-Severaloptionsareavailable

301 MovedPermanently

302 TemporaryRedirect

304 NotModified-usewhateverversionyouhavecached

Other30xstatusesareavailable,butthesearetheonlyoneswe’llconcernourselveswithatthemoment.

ThesyntaxoftheRedirectdirectiveisasfollows:

Redirect[status]RequestedURLTargetUrl

URLMapping

21

http://httpd.apache.org/docs/current/howto/cgi.html

Location

ThedirectivelimitsthescopeoftheencloseddirectivesbyURL.Itissimilartothedirective,andstartsasubsectionwhichisterminatedwithadirective.sectionsareprocessedintheordertheyappearintheconfigurationfile,afterthesectionsand.htaccessfilesareread,andafterthesections.

sectionsoperatecompletelyoutsidethefilesystem.Thishasseveralconsequences.Mostimportantly,directivesshouldnotbeusedtocontrolaccesstofilesystemlocations.SinceseveraldifferentURLsmaymaptothesamefilesystemlocation,suchaccesscontrolsmaybycircumvented.

TheencloseddirectiveswillbeappliedtotherequestifthepathcomponentoftheURLmeetsanyofthefollowingcriteria:

ThespecifiedlocationmatchesexactlythepathcomponentoftheURL.Thespecifiedlocation,whichendsinaforwardslash,isaprefixofthepathcomponentoftheURL(treatedasacontextroot).Thespecifiedlocation,withtheadditionofatrailingslash,isaprefixofthepathcomponentoftheURL(alsotreatedasacontextroot).Intheexamplebelow,wherenotrailingslashisused,requeststo/private1,/private1/and/private1/file.txtwillhavetheencloseddirectivesapplied,but/private1otherwouldnot.

#...

Intheexamplebelow,whereatrailingslashisused,requeststo/private2/and/private2/file.txtwillhavetheencloseddirectivesapplied,but/private2and/private2otherwouldnot.

#...

WhentouseUsetoapplydirectivestocontentthatlivesoutsidethefilesystem.Forcontentthatlivesinthefilesystem,useand.Anexceptionis,whichisaneasywaytoapplyaconfigurationtotheentireserver.Forallorigin(non-proxy)requests,theURLtobematchedisaURL-pathoftheform/path/.Noscheme,hostname,port,orquerystringmaybeincluded.Forproxyrequests,theURLtobematchedisoftheformscheme://servername/path,andyoumustincludetheprefix.

TheURLmayusewildcards.Inawild-cardstring, ?matchesanysinglecharacter,and *matchesanysequencesofcharacters.Neitherwildcardcharactermatchesa/intheURL-path.

Regularexpressionscanalsobeused,withtheadditionofthe~character.Forexample:

#...

wouldmatchURLsthatcontainedthesubstring/extra/dataor/special/data.Thedirectivebehavesidenticallytotheregexversionof,andispreferred,forthesimplereasonthat~ishardtodistinguishfrom-inmanyfonts,leadingtoconfigurationerrorswhenyou’refollowingexamples.

#...+

URLMapping

22

ThefunctionalityisespeciallyusefulwhencombinedwiththeSetHandlerdirective.Forexample,toenablestatusrequests,butallowthemonlyfrombrowsersatexample.com,youmightuse:

SetHandlerserver-statusRequirehostexample.com

VirtualHosts

Ratherthanrunningaseparatephysicalserver,orseparateinstanceofhttpd,foreachwebsite,itiscommonpracticerunsitesviavirtualhosts.Virtualhostingreferstorunningmorethanonewebsiteonthesamewebserver.

Virtualhostscanbename-based-thatis,multiplehostnamesresolvingtothesameIPaddress-orIPbased-thatis,adedicatedIPaddressforeachsite-dependingonvariousfactorsincludingavailabilityofIPaddressesandpreference.Name-basedvirtualhostingismorecommon,buttherearescenariosinwhichIP-basedhostingmaybepreferred.

Proxying

TODO

mod_actions

TODO

mod_imagemap

TODO

mod_negotiation

TODO

Filenotfound

Intheeventthatarequestedresourceisnotavailable,afteralloftheabovementionedmethodsareattemptedtofindit…

TODO

URLMapping

23

TableofContentsChapter5:RewriteLogging

Chapter5:RewriteLogging

Exactlyhowyouturnonloggingformod_rewritewilldependonwhatversionoftheApachehttpserveryouarerunning.Logginggotsomeupdatesinthe2.4releaseoftheserver,andtherewritelogwasoneofthechangesthathappenedatthattime.

Ifyou’renotsurewhatversionyou’rerunning,youcangetthe httpdbinarytotellyouwiththe -vflag:

httpd-v

Aswithanyotherlogging,thelogfileisopenedwhentheserverisstartedup,beforetheserverrelinquishesitsrootprivileges.Forthisreason,the RewriteLogdirectivemaynotbeusedin .htaccessfiles,butmayonlybeinvokedintheserverconfigurationfile.

2.2andearlier

Priortohttpd2.4,thewaytoenablemod_rewriteloggingiswiththe RewriteLogand RewriteLogLeveldirectives.

The RewriteLogdirectiveshouldbesettothelocationofyourrewritelogfile,andthe RewriteLogLevelissettoavaluefrom0to5toindicatethedesiredverbosityofthelogfile,with0beingnologentries,and5beingtologeverytimemod_rewriteeventhinksaboutdoingsomething.

You’lloftenfindadviceonlinesuggestingthat RewriteLogLevelbesetto9formaximumverbosity.Numbershigherthan5don’tmakeitmoreverbose,buttheyalsodon’tharmanything.

RewriteLoglogs/rewrite.logRewriteLogLevel5

2.4andlater

Inthe2.4versionoftheserver,manychangesweremadetothewaythatloggingworks.Oneofthesechangeswastheadditionofper-modulelogconfigurations.Thisrenderedthe RewriteLogdirectivesuperfluous.So,from2.4on,rewriteloggingisenabledusingthe LogLeveldirective,specifyinga traceloglevelformod_rewrite.

LogLevelinforewrite:trace6

Rewritelogentrieswillnowshowupinthemainerrorlogfile,asspecifiedbythe ErrorLogdirective.

What’sintheRewritelog?-Anexample

Thebestwaytotalkaboutwhat’sintherewritelogistoshowyousomeexamplesofthekindsofthingsthatmod_rewritelogs.

Considerasimplerewritescenariosuchasfollows:

RewriteEngineOnRewriteCond%{REQUEST_URI}!index.phpRewriteRule./index.php[PT,L]

LogLevelinforewrite:trace6

#Or,in2.2

RewriteLogging

24

#RewriteLogLevel5#RewriteLog/var/log/httpd/rewrite.log

Thisrulesetsays"Ifit’snotalready index.php,rewriteitto index.php.

Now,we’llmakearequestfortheURLhttp://localhost/exampleandseewhatgetslogged:

[ThuSep1220:22:13.3634632013][rewrite:trace2][pid11879]mod_rewrite.c(468):[client127.0.0.1:56623]127.0.0.1--[localhost/sid#7f985f445348][rid#7f985f949040/initial]initrewriteenginewithrequesteduri/example

[ThuSep1220:22:13.3635102013][rewrite:trace3][pid11879]mod_rewrite.c(468):[client127.0.0.1:56623]127.0.0.1--[localhost/sid#7f985f445348][rid#7f985f949040/initial]applyingpattern'.'touri'/example'

[ThuSep1220:22:13.3635252013][rewrite:trace4][pid11879]mod_rewrite.c(468):[client127.0.0.1:56623]127.0.0.1--[localhost/sid#7f985f445348][rid#7f985f949040/initial]RewriteCond:input='/example'pattern='!index.php'=>matched

[ThuSep1220:22:13.3635332013][rewrite:trace2][pid11879]mod_rewrite.c(468):[client127.0.0.1:56623]127.0.0.1--[localhost/sid#7f985f445348][rid#7f985f949040/initial]rewrite'/example'->'index.php'

[ThuSep1220:22:13.3635422013][rewrite:trace2][pid11879]mod_rewrite.c(468):[client127.0.0.1:56623]127.0.0.1--[localhost/sid#7f985f445348][rid#7f985f949040/initial]localpathresult:index.php

[ThuSep1220:22:13.5758772013][rewrite:trace2][pid11881]mod_rewrite.c(468):[client127.0.0.1:56624]127.0.0.1--[localhost/sid#7f985f445348][rid#7f985f949040/initial]initrewriteenginewithrequesteduri/favicon.ico

[ThuSep1220:22:13.5759202013][rewrite:trace3][pid11881]mod_rewrite.c(468):[client127.0.0.1:56624]127.0.0.1--[localhost/sid#7f985f445348][rid#7f985f949040/initial]applyingpattern'.'touri'/favicon.ico'

[ThuSep1220:22:13.5759352013][rewrite:trace4][pid11881]mod_rewrite.c(468):[client127.0.0.1:56624]127.0.0.1--[localhost/sid#7f985f445348][rid#7f985f949040/initial]RewriteCond:input='/favicon.ico'pattern='!index.php'=>matched

[ThuSep1220:22:13.5759432013][rewrite:trace2][pid11881]mod_rewrite.c(468):[client127.0.0.1:56624]127.0.0.1--[localhost/sid#7f985f445348][rid#7f985f949040/initial]rewrite'/favicon.ico'->'index.php'

RewriteLogging

25

http://localhost/example

[ThuSep1220:22:13.5759552013][rewrite:trace2][pid11881]mod_rewrite.c(468):[client127.0.0.1:56624]127.0.0.1--[localhost/sid#7f985f445348][rid#7f985f949040/initial]localpathresult:index.php

Thisisanentryfroma2.4server,andcontainsafewelementsthatwillbemissingfromrewritelogentriesfor2.2andearlier.

NotethatI’veinsertedlinebreaksbetweeneachlogentryforlegibility.Andspeakingoflegibility,let’sconsideronesinglelogentrytoseewhatthevariouscomponentsmeanbeforewegoanyfurther.

Let’slookatthefirstlogentry.

:

[ThuSep1220:22:13.3634632013][rewrite:trace2][pid11879]mod_rewrite.c(468):[client127.0.0.1:56623]127.0.0.1--[localhost/sid#7f985f445348][rid#7f985f949040/initial]initrewriteenginewithrequesteduri/example

That’salottoprocessallatonce,sowe’llbreakitdownonefieldatatime.

[ThuSep1220:22:13.3634632013]

Thedateandtimewhentheeventoccurred.

[rewrite:trace2]

Thenameofthemodulelogging,andtheloglevelatwhichitislogging.Thisis2.4-specific

[pid1879]

Theprocessidofthehttpdprocesshandlingthisrequest.Thiswillbethesameacrossagivenrequest.Notethatinthisexampletherearetwoseparaterequestsbeinghandled,asyou’llseeinamoment.

mod_rewrite.c(468):

Forin-depthdebugging,thisisthelinenumberinthemodulesourcecodewhichishandlingthecurrentrewrite.

[client127.0.0.1:56623]

TheclientIPaddress,andTCPportnumberonwhichtherequestconnectionwasmade.

-

Thisfieldcontainstheclient’susernameintheeventthattherequestwasauthenticated.Inthisexampletherequestwasnotauthenticated,soablankvalueislogged.

-

Intheeventthattherequestsentidentinformation,thiswillbeloggedhere.Thishardlyeverhappens,andsothisfieldwillalmostalwaysbe -.

[localhost/sid#7f985f445348][rid#7f985f949040/initial]

Thisistheuniqueidentifierfortherequest.

initrewriteenginewithrequesteduri/example

Ahah!Finally!Theactuallogmessagefrommod_rewrite!

Nowthatyouknowwhatallofthevariousfieldsareinthelogentry,let’sjustlookattheonesweactuallycareabout.Here’sthelogfileagain,withalotofthesuperfluousinformationremoved:

initrewriteenginewithrequesteduri/exampleapplyingpattern'.'touri'/example'RewriteCond:input='/example'pattern='!index.php'=>matchedrewrite'/example'->'index.php'

[1]

RewriteLogging

26

localpathresult:index.php

initrewriteenginewithrequesteduri/favicon.icoapplyingpattern'.'touri'/favicon.ico'RewriteCond:input='/favicon.ico'pattern='!index.php'=>matchedrewrite'/favicon.ico'->'index.php'localpathresult:index.php

I’veremovedtheextraneousinformation,andsplitthelogentriesintotwologicalchunks.

Inthefirstbit,therequestedURL /exampleisrunthroughtherulesetandendsupgettingrewrittento /index.php,asdesired.

Inthesecondbit,thebrowserrequeststheURL /favicon.icoasasideeffectoftheinitialrequest. faviconistheiconthatappearsinyourbrowseraddressbarnexttotheURL,andisanautomaticfeatureofmostbrowsers.Assuch,you’relikelytoseementionof favicon.icoinyourlogfilesfromtimetotime,andit’snothingtoworrytoomuchabout.Youcanreadmoreaboutfaviconsathttp://en.wikipedia.org/wiki/Favicon.

Followthroughtheloglinesforthefirstofthetworequests.

First,therewriteengineismadeawarethatitneedstoconsideraURL,andthe initrewriteenginelogentryismade.

Next,the RewriteRulepattern .isappliedtotherequestedURI /example,andthiscomparisonislogged.Inyourconfigurationfile,the RewriteRuleappearsafterthe RewriteCond,butatrequesttime,the RewriteRulepatternisappliedfirst.

Sincethepatterndoesmatch,inthiscase,wecontinuetothe RewriteCond,andthepattern !index.phpisappliedtothestring/example.Boththepatternandthestringitisbeingappliedtoarelogged,whichcanbeveryusefullateronindebuggingrulesthataren’tbehavingquiteasyouintended.Thisloglinealsotellsyouthatthepattern matched.

Sincethe RewriteRulepatternandthe RewriteCondbothmatched,wecontinueontotherighthandsideofthe RewriteRuleandapplytherewrite,and /exampleisrewrittento index.php,whichisalsologged.Afinallogentrytellsuswhatthelocalpathresultendsupbeingafterthisprocess,whichis index.php.

Thiskindofdetailedlogtrailtellsyouveryspecificallywhat’sgoingon,andwhathappenedateachstep.

RewriteRulesin.htaccessfiles-Anexample

We’vepreviouslydiscussedusingmod_rewritein.htaccessfiles,butit’stimetoseewhatthisactuallylookslikeinpractice.Let’sreplacetheconfigurationfileentryabovewitha.htaccessfileinstead,placedintherootdocumentdirectoryofourwebsite.So,I’mgoingtocommentoutseverallinesintheserverconfiguration:

#RewriteEngineOn#RewriteCond%{REQUEST_URI}!index.php#RewriteRule./index.php[PT,L]

LogLevelinforewrite:trace6

#Or,in2.2#RewriteLogLevel5#RewriteLog/var/log/httpd/rewrite.log

Andinstead,I’mgoingtoplacethefollowing.htaccessfile:

RewriteEngineOnRewriteCond%{REQUEST_URI}!index.php

[2]

RewriteLogging

27

http://en.wikipedia.org/wiki/Favicon

RewriteRule./index.php[PT,L]

Now,seewhatthelogfilelookslike:

Forthesakeofbrevity,let’slookatjusttheactuallogmessages,andignorealloftheextrainformation:

[perdir/var/www/html/]stripper-dirprefix:/var/www/html/example->example[perdir/var/www/html/]applyingpattern'.'touri'example'[perdir/var/www/html/]input='/example'pattern='!index.php'=>matched[perdir/var/www/html/]rewrite'example'->'/index.php'[perdir/var/www/html/]forcing'/index.php'togetpassedthroughtonextAPIURI-to-filenamehandler[perdir/var/www/html/]internalredirectwith/index.php[INTERNALREDIRECT][perdir/var/www/html/]stripper-dirprefix:/var/www/html/index.php->index.php[perdir/var/www/html/]applyingpattern'.'touri'index.php'[perdir/var/www/html/]RewriteCond:input='/index.php'pattern='!index.php'=>not-matched[perdir/var/www/html/]passthrough/var/www/html/index.php

Thefirstthingyou’llnotice,ofcourse,isthatthisismuchlongerthanwhatwehadbefore.Runningrewriterulesin.htaccessfilesgenerallytakesseveralmorestepsthanwhentherulesareintheserverconfigurationfile,whichisoneofseveralreasonsthatusing.htaccessfilesissomuchlessefficient(i.e.,slower)thanusingtheserverconfigurationfile.

Wheneverpossible,youshouldusetheserverconfigurationfileratherthan.htaccessfiles.(Thereareotherreasonsforthis,too.)

Next,you’llnoticethateachlogentrycontainsthepreface:

[perdir/var/www/html]

perdirreferstorewritedirectivesthatoccurinperdirectorycontext-i.e.,.htaccessfilesor blocks.Theyaretreatedspecialinafewdifferentways,aswe’llsee.

Thefirstoftheseisshowninthefirstlogentry:

stripper-dirprefix:/var/www/html/example->example

Whatthatmeansisthatinperdircontext,thedirectorypathisremovedfromanystringbeforetheyareconsideredinthepatternmatch.Thus,ratherthanconsideringthestring /example,aswedidthefirsttimethrough,nowwe’relookingatthestringexample.Whilethismayseemtrivialatthispoint,asweproceedtomorecomplexexamples,thatleadingslashwillbethedifferencebetweenapatternmatchingandnotmatching,soyouneedtobeawareofthiseverytimeyouuse .htaccessfiles.

Thenextfewlinesofthelogproceedasbefore,exceptthatwe’relookingat exampleratherthan /exampleineachline.Carefullycomparethelogentriesfromthefirsttimethroughtotheonesthistime.

Whathappensnextisasurprisetomostfirst-timeusersofmod_rewrite.TherequestedURI exampleisredirectedtotheURI/index.php,andthewholeprocessstartsoveragainwiththatnewURL.Thisisbecause,inperdircontext,oncearewritehasbeenexecuted,thattargetURLmustgetpassedbacktotheURLmappingprocesstodeterminewhatthatURLmapsto…whichmayincludeinvokinga.htaccessfile.

Inthiscase,thiscausestherulesettobeexecutedalloveragain,withtherewrittenURL /index.php.

RewriteLogging

28

Theremainderofthelogshouldlookveryfamiliar.It’sthesameaswhatwesawbefore,with /index.phpgettingstrippedtoindex.phpandrunthroughthepaces.Thistimearound,however,the RewriteConddoesnotmatch,andsotherequestispassedthroughunchanged.

1.Futureeditionsofthisbookwillcontainfullexamplesfroma2.2server,forthosestillrunningthatversion.2.Futureeditionsofthisbookwillcontainanappendixinwhichseverallogtracesareexplainedinexhaustivedetail.Icanhardlywait.

RewriteLogging

29

TableofContentsChapter6:RewriteRuleFlags

B-escapebackreferencesC-chainCO-cookie

DomainLifetimePathSecurehttponlyExample

DPI-discardpathE-envENDF-forbiddenG-goneH-handlerL-lastN-nextNC-nocaseNE-noescapeNS-nosubreqP-proxyPT-passthroughQSA-qsappendQSD-qsdiscardR-redirectS-skipT-type

Chapter6:RewriteRuleFlags

Flagsmodifythebehavioroftherule.Youmayhavezeroormoreflags,andtheeffectiscumulative.Flagsmayberepeatedwhereappropriate.Forexample,youmaysetseveralenvironmentvariablesbyusingseveral [E]flags,orsetseveralcookieswithmultiple [CO]flags.Flagsareseparatedwithcommas:

[B,C,NC,PT,L]

TODORewriteFlagsshouldbeaseparatechapter

Therearealotofflags.Heretheyare:

B-escapebackreferences

The[B]flaginstructsRewriteRuletoescapenon-alphanumericcharactersbeforeapplyingthetransformation.

mod_rewritehastounescapeURLsbeforemappingthem,sobackreferencesareunescapedatthetimetheyareapplied.UsingtheBflag,non-alphanumericcharactersinbackreferenceswillbeescaped.(Seebackreferencesfordiscussionofbackreferences.)Forexample,considertherule:

RewriteRule^search/(.*)$/search.php?term=$1

RewriteRuleflags

30

Givenasearchtermof 'x&y/z',abrowserwillencodeitas 'x%20%26%20y%2Fz',makingtherequest'search/x%20%26%20y%2Fz'.WithouttheBflag,thisrewriterulewillmapto 'search.php?term=x&y/z',whichisn’tavalidURL,andsowouldbeencodedas search.php?term=x%20&y%2Fz=,whichisnotwhatwasintended.

WiththeBflagsetonthissamerule,theparametersarere-encodedbeforebeingpassedontotheoutputURL,resultinginacorrectmappingto /search.php?term=x%20%26%20y%2Fz.

Notethatyoumayalsoneedtoset AllowEncodedSlashesto Ontogetthisparticularexampletowork,ashttpddoesnotallowencodedslashesinURLs,andreturnsa404ifitseesone.

Thisescapingisparticularlynecessaryinaproxysituation,whenthebackendmaybreakifpresentedwithanunescapedURL.

C-chain

The [C]or [chain]flagindicatesthattheRewriteRuleischainedtothenextrule.Thatis,iftherulematches,thenitisprocessedasusualandcontrolmovesontothenextrule.However,ifitdoesnotmatch,thenthenextrule,andanyotherrulesthatarechainedtogether,willbeskipped.

CO-cookie

The [CO],or [cookie]flag,allowsyoutosetacookiewhenaparticularRewriteRulematches.Theargumentconsistsofthreerequiredfieldsandfouroptionalfields.

Thefullsyntaxfortheflag,includingallattributes,isasfollows:

[CO=NAME:VALUE:DOMAIN:lifetime:path:secure:httponly]

Youmustdeclareaname,avalue,andadomainforthecookietobeset.

Domain

Thedomainforwhichyouwantthecookietobevalid.Thismaybeahostname,suchaswww.example.com,oritmaybeadomain,suchas.example.com.Itmustbeatleasttwopartsseparatedbyadot.Thatis,itmaynotbemerely.comor.net.Cookiesofthatkindareforbiddenbythecookiesecuritymodel.Youmayoptionallyalsosetthefollowingvalues:

Lifetime

Thetimeforwhichthecookiewillpersist,inminutes.Avalueof0indicatesthatthecookiewillpersistonlyforthecurrentbrowsersession.Thisisthedefaultvalueifnoneisspecified.

Path

Thepath,onthecurrentwebsite,forwhichthecookieisvalid,suchas /customers/or /files/download/.Bydefault,thisissetto /-thatis,theentirewebsite.

Secure

Ifsettosecure,true,or1,thecookiewillonlybepermittedtobetranslatedviasecure(https)connections.

httponly

RewriteRuleflags

31

IfsettoHttpOnly,true,or1,thecookiewillhavetheHttpOnlyflagset,whichmeansthatthecookiewillbeinaccessibletoJavaScriptcodeonbrowsersthatsupportthisfeature.

Example

Considerthisexample:

RewriteEngineOnRewriteRule^/index\.html-[CO=frontdoor:yes:.example.com:1440:/]

Intheexamplegive,theruledoesn’trewritetherequest.The'-'rewritetargettellsmod_rewritetopasstherequestthroughunchanged.Instead,itsetsacookiecalled'frontdoor'toavalueof'yes'.Thecookieisvalidforanyhostinthe.example.comdomain.Itwillbesettoexpirein1440minutes(24hours)andwillbereturnedforallURIs(i.e.,forthepath'/').

DPI-discardpath

TheDPIflagcausesthe PATH_INFOportionoftherewrittenURItobediscarded.

Thisflagisavailableinversion2.2.12andlater.

Inper-directorycontext,theURIeach RewriteRulecomparesagainstistheconcatenationofthecurrentvaluesoftheURIandPATH_INFO.

ThecurrentURIcanbetheinitialURIasrequestedbytheclient,theresultofapreviousroundofmod_rewriteprocessing,ortheresultofapriorruleinthecurrentroundofmod_rewriteprocessing.

Incontrast,the PATH_INFOthatisappendedtotheURIbeforeeachrulereflectsonlythevalueof PATH_INFObeforethisroundofmod_rewriteprocessing.Asaconsequence,iflargeportionsoftheURIarematchedandcopiedintoasubstitutioninmultipleRewriteRuledirectives,withoutregardforwhichpartsoftheURIcamefromthecurrent PATH_INFO,thefinalURImayhavemultiplecopiesof PATH_INFOappendedtoit.

Usethisflagonanysubstitutionwherethe PATH_INFOthatresultedfromthepreviousmappingofthisrequesttothefilesystemisnotofinterest.Thisflagpermanentlyforgetsthe PATH_INFOestablishedbeforethisroundofmod_rewriteprocessingbegan.PATH_INFOwillnotberecalculateduntilthecurrentroundofmod_rewriteprocessingcompletes.Subsequentrulesduringthisroundofprocessingwillseeonlythedirectresultofsubstitutions,withoutany PATH_INFOappended.

E-env

Withthe [E],or [env]flag,youcansetthevalueofanenvironmentvariable.Notethatsomeenvironmentvariablesmaybesetaftertheruleisrun,thusunsettingwhatyouhaveset.

Thefullsyntaxforthisflagis:

[E=VAR:VAL][E=!VAR]

VALmaycontainbackreferences(Seesectionbackreferences)( $Nor %N)whichwillbeexpanded.

Usingtheshortform

[E=VAR]

youcansettheenvironmentvariablenamedVARtoanemptyvalue.

RewriteRuleflags

32

Theform

[E=!VAR]

allowstounsetapreviouslysetenvironmentvariablenamedVAR.

Environmentvariablescanthenbeusedinavarietyofcontexts,includingCGIprograms,otherRewriteRuledirectives,orCustomLogdirectives.

Thefollowingexamplesetsanenvironmentvariablecalled'image'toavalueof'1'iftherequestedURIisanimagefile.Then,thatenvironmentvariableisusedtoexcludethoserequestsfromtheaccesslog.

RewriteRule\.(png|gif|jpg)$-[E=image:1]CustomLoglogs/access_logcombinedenv=!image

NotethatthissameeffectcanbeobtainedusingSetEnvIf.Thistechniqueisofferedasanexample,notasarecommendation.

The [E]flagmayberepeatedifyouwanttosetmorethanoneenvironmentvariableatthesametime:

RewriteRule\.pdf$[E=document:1,E=pdf:1,E=done]

END

Althoughtheflagsarepresentedhereinalphabeticalorder,itmakesmoresensetogoreadthesectionabouttheLflagfirst(ref{lflag})andthencomebackhere.

Usingthe [END]flagterminatesnotonlythecurrentroundofrewriteprocessing(like [L])butalsopreventsanysubsequentrewriteprocessingfromoccurringinper-directory(htaccess)context.

Thisdoesnotapplytonewrequestsresultingfromexternalredirects.

F-forbidden

Usingthe [F]flagcausestheservertoreturna403Forbiddenstatuscodetotheclient.WhilethesamebehaviorcanbeaccomplishedusingtheDenydirective,thisallowsmoreflexibilityinassigningaForbiddenstatus.

Thefollowingrulewillforbid .exefilesfrombeingdownloadedfromyourserver.

RewriteRule\.exe-[F]

Thisexampleusesthe"-"syntaxfortherewritetarget,whichmeansthattherequestedURIisnotmodified.There’snoreasontorewritetoanotherURI,ifyou’regoingtoforbidtherequest.

Whenusing [F],an [L]isimplied-thatis,theresponseisreturnedimmediately,andnofurtherrulesareevaluated.

G-gone

The [G]flagforcestheservertoreturna410Gonestatuswiththeresponse.Thisindicatesthataresourceusedtobeavailable,butisnolongeravailable.

Aswiththe [F]flag,youwilltypicallyusethe"-"syntaxfortherewritetargetwhenusingthe [G]flag:

RewriteRuleoldproduct-[G,NC]

RewriteRuleflags

33

Whenusing [G],an [L]isimplied-thatis,theresponseisreturnedimmediately,andnofurtherrulesareevaluated.

H-handler

Forcestheresultingrequesttobehandledwiththespecifiedhandler.Forexample,onemightusethistoforceallfileswithoutafileextensiontobeparsedbythephphandler:

RewriteRule!\.-[H=application/x-httpd-php]

Theregularexpressionabove- !\.-willmatchanyrequestthatdoesnotcontaintheliteral.character.

Thiscanbealsousedtoforcethehandlerbasedonsomeconditions.Forexample,thefollowingsnippetusedinper-servercontextallows.phpfilestobedisplayedbymod_phpiftheyarerequestedwiththe.phpsextension:

RewriteRule^(/source/.+\.php)s$$1[H=application/x-httpd-php-source]

Theregularexpressionabove- ̂ (/source/.+\.php)s$-willmatchanyrequestthatstartswith /source/followedby1orncharactersfollowedby .phpsliterally.Thebackreference $1referrerstothecapturedmatchwithinparenthesisoftheregularexpression.

L-last

The [L]flagcausesmod_rewritetostopprocessingtheruleset.Inmostcontexts,thismeansthatiftherulematches,nofurtherruleswillbeprocessed.ThiscorrespondstothelastcommandinPerl,orthebreakcommandinC.Usethisflagtoindicatethatthecurrentruleshouldbeappliedimmediatelywithoutconsideringfurtherrules.

Ifyouareusing RewriteRuleineither.htaccessfilesorin sections,itisimportanttohavesomeunderstandingofhowtherulesareprocessed.Thesimplifiedformofthisisthatoncetheruleshavebeenprocessed,therewrittenrequestishandedbacktotheURLparsingenginetodowhatitmaywithit.Itispossiblethatastherewrittenrequestishandled,the.htaccessfileorsectionmaybeencounteredagain,andthustherulesetmayberunagainfromthestart.Mostcommonlythiswillhappenifoneoftherulescausesaredirect-eitherinternalorexternal-causingtherequestprocesstostartover.

Itisthereforeimportant,ifyouareusing RewriteRuledirectivesinoneofthesecontexts,thatyoutakeexplicitstepstoavoidruleslooping,andnotcountsolelyonthe [L]flagtoterminateexecutionofaseriesofrules,asshownbelow.

Analternativeflag, [END],canbeusedtoterminatenotonlythecurrentroundofrewriteprocessingbutpreventanysubsequentrewriteprocessingfromoccurringinper-directory(htaccess)context.Thisdoesnotapplytonewrequestsresultingfromexternalredirects.

Theexamplegivenherewillrewriteanyrequesttoindex.php,givingtheoriginalrequestasaquerystringargumenttoindex.php,however,the RewriteCondensuresthatiftherequestisalreadyforindex.php,the RewriteRulewillbeskipped.

RewriteBase/RewriteCond%{REQUEST_URI}!=/index.phpRewriteRule^(.*)/index.php?req=$1[L,PT]

SeetheRewriteCondchapterforfurtherdiscussionoftheRewriteConddirective.

N-next

The [N]flagcausestherulesettostartoveragainfromthetop,usingtheresultoftherulesetsofarasastartingpoint.Usewithextremecaution,asitmayresultinloop.

RewriteRuleflags

34

The [N]flagcouldbeused,forexample,ifyouwishedtoreplaceacertainstringorletterrepeatedlyinarequest.TheexampleshownherewillreplaceAwithBeverywhereinarequest,andwillcontinuedoingsountiltherearenomoreAstobereplaced.

RewriteRule(.*)A(.*)$1B$2[N]

Youcanthinkofthisasawhileloop:Whilethispatternstillmatches(i.e.,whiletheURIstillcontainsanA),performthissubstitution(i.e.,replacetheAwithaB).

NC-nocase

Useofthe [NC]flagcausesthe RewriteRuletobematchedinacase-insensitivemanner.Thatis,itdoesn’tcarewhetherlettersappearasupper-caseorlower-caseinthematchedURI.

Intheexamplebelow,anyrequestforanimagefilewillbeproxiedtoyourdedicatedimageserver.Thematchiscase-insensitive,sothat.jpgand.JPGfilesarebothacceptable,forexample.

RewriteRule(.*\.(jpg|gif|png))$http://images.example.com$1[P,NC]

NE-noescape

Bydefault,specialcharacters,suchas \&and ?,forexample,willbeconvertedtotheirhexcodeequivalent.Usingthe [NE]flagpreventsthatfromhappening.

RewriteRule^/anchor/(.+)/bigpage.html#$1[NE,R]

Theaboveexamplewillredirect /anchor/xyzto /bigpage.html#xyz.Omittingthe [NE]willresultinthe #beingconvertedtoitshexcodeequivalent, %23,whichwillthenresultina404NotFounderrorcondition.

NS-nosubreq

Useofthe [NS]flagpreventstherulefrombeingusedonsubrequests.Forexample,apagewhichisincludedusinganSSI(ServerSideInclude)isasubrequest,andyoumaywanttoavoidrewriteshappeningonthosesubrequests.Also,whenmod_dirtriestofindoutinformationaboutpossibledirectorydefaultfiles(suchasindex.htmlfiles),thisisaninternalsubrequest,andyouoftenwanttoavoidrewritesonsuchsubrequests.Onsubrequests,itisnotalwaysuseful,andcanevencauseerrors,ifthecompletesetofrulesareapplied.Usethisflagtoexcludeproblematicrules.

Todecidewhetherornottousethisrule:ifyouprefixURLswithCGI-scripts,toforcethemtobeprocessedbytheCGI-script,it’slikelythatyouwillrunintoproblems(orsignificantoverhead)onsub-requests.Inthesecases,usethisflag.

Images,javascriptfiles,orcssfiles,loadedaspartofanHTMLpage,arenotsubrequests-thebrowserrequeststhemasseparateHTTPrequests.

P-proxy

Useofthe [P]flagcausestherequesttobehandledbymod_proxy,andhandledviaaproxyrequest.Forexample,ifyouwantedallimagerequeststobehandledbyaback-endimageserver,youmightdosomethinglikethefollowing:

RewriteRule/(.*)\.(jpg|gif|png)$http://images.example.com/$1.$2[P]

Useofthe [P]flagimplies [L].Thatis,therequestisimmediatelypushedthroughtheproxy,andanyfollowingruleswillnotbeconsidered.

RewriteRuleflags

35

YoumustmakesurethatthesubstitutionstringisavalidURI(typicallystartingwith)whichcanbehandledbythemod_proxy.Ifnot,youwillgetanerrorfromtheproxymodule.Usethisflagtoachieveamorepowerfulimplementationofthe ProxyPassdirective,tomapremotecontentintothenamespaceofthelocalserver.

SecurityWarning

TakecarewhenconstructingthetargetURLoftherule,consideringthesecurityimpactfromallowingtheclientinfluenceoverthesetofURLstowhichyourserverwillactasaproxy.EnsurethattheschemeandhostnamepartoftheURLiseitherfixed,ordoesnotallowtheclientundueinfluence.

Performancewarning

Usingthisflagtriggerstheuseofmod_proxy,withouthandlingofpersistentconnections.Thismeanstheperformanceofyourproxywillbebetterifyousetitupwith ProxyPassor ProxyPassMatch.

Thisisbecausethisflagtriggerstheuseofthedefaultworker,whichdoesnothandleconnectionpooling.Avoidusingthisflagandpreferthosedirectives,wheneveryoucan.

Note:mod_proxymustbeenabledinordertousethisflag.

SeeChapterref{chapter_proxy}foramorethoroughtreatmentofproxying.

PT-passthrough

Thetarget(orsubstitutionstring)ina RewriteRuleisassumedtobeafilepath,bydefault.Theuseofthe [PT]flagcausesittobetreatedasaURIinstead.Thatistosay,theuseofthe [PT]flagcausestheresultofthe RewriteRuletobepassedbackthroughURLmapping,sothatlocation-basedmappings,suchas Alias, Redirect,or ScriptAlias,forexample,mighthaveachancetotakeeffect.

If,forexample,youhavean Aliasfor /icons,andhavea RewriteRulepointingthere,youshouldusethe [PT]flagtoensurethatthe Aliasisevaluated.

Alias/icons/usr/local/apache/iconsRewriteRule/pics/(.+)\.jpg$/icons/$1.gif[PT]

Omissionofthe [PT]flaginthiscasewillcausethe Aliastobeignored,resultingina'Filenotfound'errorbeingreturned.

The [PT]flagimpliesthe [L]flag:rewritingwillbestoppedinordertopasstherequesttothenextphaseofprocessing.

Notethatthe [PT]flagisimpliedinper-directorycontextssuchas sectionsorin.htaccessfiles.Theonlywaytocircumventthatistorewriteto-.

QSA-qsappend

WhenthereplacementURIcontainsaquerystring,thedefaultbehaviorofRewriteRuleistodiscardtheexistingquerystring,andreplaceitwiththenewlygeneratedone.Usingthe [QSA]flagcausesthequerystringstobecombined.

Considerthefollowingrule:

RewriteRule/pages/(.+)/page.php?page=$1[QSA]

Withthe [QSA]flag,arequestfor /pages/123?one=twowillbemappedto /page.php?page=123&one=two.Withoutthe[QSA]flag,thatsamerequestwillbemappedto /page.php?page=123-thatis,theexistingquerystringwillbediscarded.

QSD-qsdiscard

RewriteRuleflags

36

http://hostname>

WhentherequestedURIcontainsaquerystring,andthetargetURIdoesnot,thedefaultbehaviorof RewriteRuleistocopythatquerystringtothetargetURI.Usingthe [QSD]flagcausesthequerystringtobediscarded.

Thisflagisavailableinversion2.4.0andlater.

Using [QSD]and [QSA]togetherwillresultin [QSD]takingprecedence.

IfthetargetURIhasaquerystring,thedefaultbehaviorwillbeobserved-thatis,theoriginalquerystringwillbediscardedandreplacedwiththequerystringinthe RewriteRuletargetURI.

R-redirect

Useofthe [R]flagcausesaHTTPredirecttobeissuedtothebrowser.Ifafully-qualifiedURLisspecified(thatis,including)thenaredirectwillbeissuedtothatlocation.Otherwise,thecurrentprotocol,servername,andportnumberwillbeusedtogeneratetheURLsentwiththeredirect.

AnyvalidHTTPresponsestatuscodemaybespecified,usingthesyntax [R=305],witha302statuscodebeingusedbydefaultifnoneisspecified.Thestatuscodespecifiedneednotnecessarilybearedirect(3xx)statuscode.However,ifastatuscodeisoutsidetheredirectrange(300-399)thenthesubstitutionstringisdroppedentirely,andrewritingisstoppedasiftheLwereused.

Inadditiontoresponsestatuscodes,youmayalsospecifyredirectstatususingtheirsymbolicnames:temp(default),permanent,orseeother.

Youwillalmostalwayswanttouse [R]inconjunctionwith [L](thatis,use [R,L])becauseonitsown,the [R]flagprependshttp://thishost%5B:thisport%5DtotheURI,butthenpassesthisontothenextruleintheruleset,whichcanoftenresultin'InvalidURIinrequest'warnings.

S-skip

The [S]flagisusedtoskiprulesthatyoudon’twanttorun.Thesyntaxoftheskipflagis [S=N],whereNsignifiesthenumberofrulestoskip(providedtheRewriteRuleandanyprecedingRewriteConddirectivesmatch).Thiscanbethoughtofasagotostatementinyourrewriteruleset.Inthefollowingexample,weonlywanttoruntheRewriteRuleiftherequestedURIdoesn’tcorrespondwithanactualfile.

#Istherequestforanon-existentfile?RewriteCond%{REQUEST_FILENAME}!-fRewriteCond%{REQUEST_FILENAME}!-d

#Ifso,skipthesetwoRewriteRulesRewriteRule.?-[S=2]

RewriteRule(.*\.gif)images.php?$1RewriteRule(.*\.html)docs.php?$1

Thistechniqueisusefulbecausea RewriteCondonlyappliestothe RewriteRuleimmediatelyfollowingit.Thus,ifyouwanttomakea RewriteCondapplytoseveral RewriteRule`s,onepossibletechniqueistonegatethoseconditionsandadda`RewriteRulewitha [Skip]flag.Youcanusethistomakepseudoif-then-elseconstructs:Thelastruleofthethen-clausebecomesskip=N,whereNisthenumberofrulesintheelse-clause:

#Doesthefileexist?RewriteCond%{REQUEST_FILENAME}!-fRewriteCond%{REQUEST_FILENAME}!-d

#Createanif-then-elseconstructbyskipping3linesifwemeanttogotothe

RewriteRuleflags

37

http://servername/>http://thishost%5B:thisport%5D

"else"stanza.RewriteRule.?-[S=3]

#IFthefileexists,then:RewriteRule(.*\.gif)images.php?$1RewriteRule(.*\.html)docs.php?$1#Skippastthe"else"stanza.RewriteRule.?-[S=1]#ELSE...RewriteRule(.*)404.php?file=$1#END

Itisprobablyeasiertoaccomplishthiskindofconfigurationusingthe , ,and directivesinstead.(2.4andlater-Seeref{if}.)

T-type

SetstheMIMEtypewithwhichtheresultingresponsewillbesent.Thishasthesameeffectasthe AddTypedirective.

Forexample,youmightusethefollowingtechniquetoservePerlsourcecodeasplaintext,ifrequestedinaparticularway:

#Serve.plfilesasplaintextRewriteRule\.pl$-[T=text/plain]

Or,perhaps,ifyouhaveacamerathatproducesjpegimageswithoutfileextensions,youcouldforcethoseimagestobeservedwiththecorrectMIMEtypebyvirtueoftheirfilenames:

#Fileswith'IMG'inthenamearejpgimages.RewriteRuleIMG-[T=image/jpg]

Pleasenotethatthisisatrivialexample,andcouldbebetterdoneusing instead.Alwaysconsiderthealternatesolutionstoaproblembeforeresortingtorewrite,whichwillinvariablybealessefficientsolutionthanthealternatives.

Ifusedinper-directorycontext,useonly-(dash)asthesubstitutionfortheentireroundofmod_rewriteprocessing,otherwisetheMIME-typesetwiththisflagislostduetoaninternalre-processing(includingsubsequentroundsofmod_rewriteprocessing).TheLflagcanbeusefulinthiscontexttoendthecurrentroundofmod_rewriteprocessing.

RewriteRuleflags

38

TableofContentsChapter7:RewriteCond

Chapter7:RewriteCond

The RewriteConddirectiveattachesadditionalconditionsona RewriteRule,andmayalsosetbackreferencesthatmaybeusedintherewritetarget.

Oneormore RewriteConddirectivesmayprecedea RewriteRuledirective.That RewriteRuleisthenappliedonlyifthecurrentstateoftheURImatchesitspattern,andalloftheseconditionsaremet.

The RewriteConddirectivehasthefollowingsyntax:

RewriteCondTestStringCondPattern[Flag]

Theargumentshavethefollowingmeaning:

TestStringAnystringorvariabletobetestedforamatch.

CondPatternAregularexpressionorotherotherexpressiontobecomparedagainsttheTestString.

FlagOneormoreflagswhichmodifythebehaviorofthecondition.

Thesedefinitionswillbeexpandedinthesectionsbelow.

TestString

TestStringisastringwhichcancontainthefollowingexpandedconstructsinadditiontoplaintext:

RewriteRulebackreferencesThesearebackreferencesoftheform$N(0⇐N⇐9).$1to$9provideaccesstothegroupedparts(inparentheses)ofthepattern,fromtheRewriteRulewhichissubjecttothecurrentsetofRewriteCondconditions.$0providesaccesstothewholestringmatchedbythatpattern.

RewriteCondbackreferencesThesearebackreferencesoftheform%N(0⇐N⇐9).%1to%9provideaccesstothegroupedparts(again,inparentheses)ofthepattern,fromthelastmatchedRewriteCondinthecurrentsetofconditions.%0providesaccesstothewholestringmatchedbythatpattern.

RewriteMapexpansionsTheseareexpansionsoftheform$\{mapname:key|default}.SeethedocumentationforRewriteMapformoredetails.

Server-VariablesThesearevariablesoftheform%\{NAME_OF_VARIABLE}whereNAME_OF_VARIABLEcanbeastringtakenfromthefollowinglist:

HTTPheaders:

HTTP_USER_AGENTHTTP_REFERERHTTP_COOKIEHTTP_FORWARDEDHTTP_HOSTHTTP_PROXY_CONNECTIONHTTP_ACCEPT

connection&request:

REMOTE_ADDRREMOTE_HOSTREMOTE_PORTREMOTE_USERREMOTE_IDENTREQUEST_METHODSCRIPT_FILENAMEPATH_INFOQUERY_STRINGAUTH_TYPE

RewriteCond

39

serverinternals:

DOCUMENT_ROOTSERVER_ADMINSERVER_NAMESERVER_ADDRSERVER_PORTSERVER_PROTOCOLSERVER_SOFTWARE

dateandtime:

TIME_YEARTIME_MONTIME_DAYTIME_HOURTIME_MINTIME_SECTIME_WDAYTIME

specials:

API_VERSIONTHE_REQUESTREQUEST_URIREQUEST_FILENAMEIS_SUBREQHTTPSREQUEST_SCHEME

ThesevariablesallcorrespondtothesimilarlynamedHTTPMIME-headers,CvariablesoftheApacheHTTPServerorstructtmfieldsoftheUnixsystem.MostaredocumentedelsewhereintheManualorintheCGIspecification.

SERVER_NAMEandSERVER_PORTdependonthevaluesofUseCanonicalNameandUseCanonicalPhysicalPortrespectively.

Thosethatarespecialtomod_rewriteincludethosebelow.

IS_SUBREQWillcontainthetext"true"iftherequestcurrentlybeingprocessedisasub-request,"false"otherwise.Sub-requestsmaybegeneratedbymodulesthatneedtoresolveadditionalfilesorURIsinordertocompletetheirtasks.

API_VERSIONThisistheversionoftheApachehttpdmoduleAPI(theinternalinterfacebetweenserverandmodule)inthecurrenthttpdbuild,asdefinedininclude/ap_mmn.h.ThemoduleAPIversioncorrespondstotheversionofApachehttpdinuse(inthereleaseversionofApachehttpd1.3.14,forinstance,itis19990320:10),butismainlyofinteresttomoduleauthors.

THE_REQUESTThefullHTTPrequestlinesentbythebrowsertotheserver(e.g.,"GET/index.htmlHTTP/1.1").Thisdoesnotincludeanyadditionalheaderssentbythebrowser.Thisvaluehasnotbeenunescaped(decoded),unlikemostothervariablesbelow.

REQUEST_URIThepathcomponentoftherequestedURI,suchas"/index.html".ThisnotablyexcludesthequerystringwhichisavailableasasitsownvariablenamedQUERY_STRING.

REQUEST_FILENAMEThefulllocalfilesystempathtothefileorscriptmatchingtherequest,ifthishasalreadybeendeterminedbytheserveratthetimeREQUEST_FILENAMEisreferenced.Otherwise,suchaswhenusedinvirtualhostcontext,thesamevalueasREQUEST_URI.DependingonthevalueofAcceptPathInfo,theservermayhaveonlyusedsomeleadingcomponentsoftheREQUEST_URItomaptherequesttoafile.

HTTPSWillcontainthetext"on"iftheconnectionisusingSSL/TLS,or"off"otherwise.(Thisvariablecanbesafelyusedregardlessofwhetherornotmod_sslisloaded).

REQUEST_SCHEMEWillcontaintheschemeoftherequest(usually"http"or"https").ThisvaluecanbeinfluencedwithServerName.

IftheTestStringhasthespecialvalueexpr,theCondPatternwillbetreatedasanap_expr.HTTPheadersreferencedintheexpressionwillbeaddedtotheVaryheaderifthenovaryflagisnotgiven.

Otherthingsyoushouldbeawareof:

ThevariablesSCRIPT_FILENAMEandREQUEST_FILENAMEcontainthesamevalue-thevalueofthefilenamefieldoftheinternalrequest_recstructureoftheApacheHTTPServer.ThefirstnameisthecommonlyknownCGIvariablenamewhilethesecondistheappropriatecounterpartofREQUEST_URI(whichcontainsthevalueoftheurifieldofrequest_rec).

Ifasubstitutionoccurredandtherewritingcontinues,thevalueofbothvariableswillbeupdatedaccordingly.

RewriteCond

40

Ifusedinper-servercontext(i.e.,beforetherequestismappedtothefilesystem)SCRIPT_FILENAMEandREQUEST_FILENAMEcannotcontainthefulllocalfilesystempathsincethepathisunknownatthisstageofprocessing.BothvariableswillinitiallycontainthevalueofREQUEST_URIinthatcase.Inordertoobtainthefulllocalfilesystempathoftherequestinper-servercontext,useanURL-basedlook-ahead %{LA-U:REQUEST_FILENAME}todeterminethefinalvalueofREQUEST_FILENAME.

%{ENV:variable},wherevariablecanbeanyenvironmentvariable,isalsoavailable.Thisislooked-upviainternalApachehttpdstructuresand(ifnotfoundthere)viagetenv()fromtheApachehttpdserverprocess.

%{SSL:variable},wherevariableisthenameofanSSLenvironmentvariable,canbeusedwhetherornotmod_sslisloaded,butwillalwaysexpandtotheemptystringifitisnot.Example: %{SSL:SSL_CIPHER_USEKEYSIZE}mayexpandto128.

%{HTTP:header},whereheadercanbeanyHTTPMIME-headername,canalwaysbeusedtoobtainthevalueofaheadersentintheHTTPrequest.Example: %{HTTP:Proxy-Connection}isthevalueoftheHTTPheaderProxy-Connection:.

IfaHTTPheaderisusedinaconditionthisheaderisaddedtotheVaryheaderoftheresponseincasetheconditionevaluatestototruefortherequest.Itisnotaddediftheconditionevaluatestofalsefortherequest.AddingtheHTTPheadertotheVaryheaderoftheresponseisneededforpropercaching.

Ithastobekeptinmindthatconditionsfollowashortcircuitlogicinthecaseofthe'ornext|OR'flagsothatcertainconditionsmightnotbeevaluatedatall.

%{LA-U:variable}canbeusedforlook-aheadswhichperformaninternal(URL-based)sub-requesttodeterminethefinalvalueofvariable.Thiscanbeusedtoaccessvariableforrewritingwhichisnotavailableatthecurrentstage,butwillbesetinalaterphase.

Forinstance,torewriteaccordingtotheREMOTE_USERvariablefromwithintheper-servercontext(httpd.conffile)youmustuse %{LA-U:REMOTE_USER}-thisvariableissetbytheauthorizationphases,whichcomeaftertheURLtranslationphase(duringwhichmod_rewriteoperates).

Ontheotherhand,becausemod_rewriteimplementsitsper-directorycontext(.htaccessfile)viatheFixupphaseoftheAPIandbecausetheauthorizationphasescomebeforethisphase,youjustcanuse %{REMOTE_USER}inthatcontext.

%{LA-F:variable}canbeusedtoperformaninternal(filename-based)sub-request,todeterminethefinalvalueofvariable.Mostofthetime,thisisthesameasLA-Uabove.

CondPattern

CondPatternistheconditionpattern,aregularexpressionwhichisappliedtothecurrentinstanceoftheTestString.TestStringisfirstevaluated,beforebeingmatchedagainstCondPattern.

CondPatternisusuallyaperlcompatibleregularexpression,butthereisadditionalsyntaxavailabletoperformotherusefultestsagainsttheTeststring:

Youcanprefixthepatternstringwitha'!'character(exclamationmark)tospecifyanon-matchingpattern.

Youcanperformlexicographicalstringcomparisons:

'CondPattern'(lexicographicallyfollows)TreatstheCondPatternasaplainstringandcomparesitlexicographicallytoTestString.TrueifTestStringlexicographicallyfollowsCondPattern.

'=CondPattern'(lexicographicallyequal)

RewriteCond

41

TreatstheCondPatternasaplainstringandcomparesitlexicographicallytoTestString.TrueifTestStringislexicographicallyequaltoCondPattern(thetwostringsareexactlyequal,characterforcharacter).IfCondPatternis""(twoquotationmarks)thiscomparesTestStringtotheemptystring.

'⇐CondPattern'(lexicographicallylessthanorequalto)TreatstheCondPatternasaplainstringandcomparesitlexicographicallytoTestString.TrueifTestStringlexicographicallyprecedesCondPattern,orisequaltoCondPattern(thetwostringsareequal,characterforcharacter).

'>=CondPattern'(lexicographicallygreaterthanorequalto)TreatstheCondPatternasaplainstringandcomparesitlexicographicallytoTestString.TrueifTestStringlexicographicallyfollowsCondPattern,orisequaltoCondPattern(thetwostringsareequal,characterforcharacter).

Youcanperformintegercomparisons:

'-eq'(isnumericallyequalto)TheTestStringistreatedasaninteger,andisnumericallycomparedtotheCondPattern.Trueifthetwoarenumericallyequal.

'-ge'(isnumericallygreaterthanorequalto)TheTestStringistreatedasaninteger,andisnumericallycomparedtotheCondPattern.TrueiftheTestStringisnumericallygreaterthanorequaltotheCondPattern.

'-gt'(isnumericallygreaterthan)TheTestStringistreatedasaninteger,andisnumericallycomparedtotheCondPattern.TrueiftheTestStringisnumericallygreaterthantheCondPattern.

'-le'(isnumericallylessthanorequalto)TheTestStringistreatedasaninteger,andisnumericallycomparedtotheCondPattern.TrueiftheTestStringisnumericallylessthanorequaltotheCondPattern.Avoidconfusionwiththe-lbyusingthe-Lor-hvariant.

'-lt'(isnumericallylessthan)TheTestStringistreatedasaninteger,andisnumericallycomparedtotheCondPattern.TrueiftheTestStringisnumericallylessthantheCondPattern.Avoidconfusionwiththe-lbyusingthe-Lor-hvariant.

Youcanperformvariousfileattributetests:

'-d'(isdirectory)TreatstheTestStringasapathnameandtestswhetherornotitexists,andisadirectory.

'-f'(is