TheApache

Tomcat5.5
Servlet/JSP
Container
ApacheTomcatConfigurationReference
TheHTTPConnector
TableofContents
Introduction
Attributes
1. CommonAttributes
2. StandardImplementation
NestedComponents
SpecialFeatures
1. HTTP/1.1andHTTP/1.0Support
2. ProxySupport
3. SSLSupport
Introduction
TheHTTPConnectorelementrepresentsaConnectorcomponentthatsupportstheHTTP/1.1protocol.It
enablesCatalinatofunctionasastandalonewebserver,inadditiontoitsabilitytoexecuteservletsandJSP
pages.AparticularinstanceofthiscomponentlistensforconnectionsonaspecificTCPportnumberonthe
server.OneormoresuchConnectorscanbeconfiguredaspartofasingleService,eachforwardingtothe
associatedEnginetoperformrequestprocessingandcreatetheresponse.
IfyouwishtoconfiguretheConnectorthatisusedforconnectionstowebserversusingtheAJPprotocol
(suchasthemod_jk 1.2.xconnectorforApache1.3),seehereinstead.
Atserverstartuptime,thisConnectorwillcreateanumberofrequestprocessingthreads(basedonthevalue
configuredfortheminSpareThreadsattribute).Eachincomingrequestrequiresathreadforthedurationof
thatrequest.Ifmoresimultaneousrequestsarereceivedthancanbehandledbythecurrentlyavailable
requestprocessingthreads,additionalthreadswillbecreateduptotheconfiguredmaximum(thevalueofthe
maxThreadsattribute).Ifstillmoresimultaneousrequestsarereceived,theyarestackedupinsidetheserver
socketcreatedbytheConnector,uptotheconfiguredmaximum(thevalueoftheacceptCountattribute).
Anyfurthersimultaneousrequestswillreceive"connectionrefused"errors,untilresourcesareavailableto
processthem.
Attributes
CommonAttributes
AllimplementationsofConnectorsupportthefollowingattributes:
Attribute Description
allowTrace
Abooleanvaluewhichcanbeusedtoenableordisablethe
TRACEHTTPmethod.Ifnotspecified,thisattributeissetto
false.
emptySessionPath
Ifsettotrue,allpathsforsessioncookieswillbesetto/.This
canbeusefulforportletspecificationimplementations,butwill
greatlyaffectperformanceifmanyapplicationsareaccessedon
agivenserverbytheclient.Ifnotspecified,thisattributeisset
tofalse.
enableLookups
Settotrueifyouwantcallstorequest.getRemoteHost()to
performDNSlookupsinordertoreturntheactualhostnameof
theremoteclient.SettofalsetoskiptheDNSlookupand
returntheIPaddressinStringforminstead(therebyimproving
performance).Bydefault,DNSlookupsareenabled.
maxParameterCount
Themaximumnumberofparameters(GETplusPOST)which
willbeautomaticallyparsedbythecontainer.Avalueofless
than0meansnolimit.Ifnotspecified,adefaultof10000is
used.NotethatFailedRequestFilterfiltercanbeusedto
rejectrequeststhathitthelimit.
maxPostSize
ThemaximumsizeinbytesofthePOSTwhichwillbehandled
bythecontainerFORMURLparameterparsing.Thelimitcan
bedisabledbysettingthisattributetoavaluelessthanorequal
to0.Ifnotspecified,thisattributeissetto2097152(2
megabytes).
maxSavePostSize
ThemaximumsizeinbytesofthePOSTwhichwillbe
saved/bufferedbythecontainerduringFORMorCLIENT
CERTauthentication.Forbothtypesofauthentication,the
POSTwillbesaved/bufferedbeforetheuserisauthenticated.
ForCLIENTCERTauthentication,thePOSTisbufferedfor
thedurationoftheSSLhandshakeandthebufferemptiedwhen
therequestisprocessed.ForFORMauthenticationthePOSTis
savedwhilsttheuserisredirectedtotheloginformandis
retaineduntiltheusersuccessfullyauthenticatesorthesession
associatedwiththeauthenticationrequestexpires.Thelimitcan
bedisabledbysettingthisattributeto1.Settingtheattributeto
zerowilldisablethesavingofPOSTdataduringauthentication
.Ifnotspecified,thisattributeissetto4096(4kilobytes).
protocol
ThisattributevaluemustbeHTTP/1.1tousetheHTTP
handler,whichisthedefault.
proxyName
IfthisConnectorisbeingusedinaproxyconfiguration,
configurethisattributetospecifytheservernametobereturned
forcallstorequest.getServerName().SeeProxySupportfor
moreinformation.
proxyPort
IfthisConnectorisbeingusedinaproxyconfiguration,
configurethisattributetospecifytheserverporttobereturned
forcallstorequest.getServerPort().SeeProxySupportfor
moreinformation.
redirectPort
IfthisConnectorissupportingnonSSLrequests,andarequest
isreceivedforwhichamatching<security-constraint>
requiresSSLtransport,Catalinawillautomaticallyredirectthe
requesttotheportnumberspecifiedhere.
scheme
Setthisattributetothenameoftheprotocolyouwishtohave
returnedbycallstorequest.getScheme().Forexample,you
wouldsetthisattributeto"https"foranSSLConnector.The
defaultvalueis"http".SeeSSLSupportformoreinformation.
secure
Setthisattributetotrueifyouwishtohavecallsto
request.isSecure()toreturntrueforrequestsreceivedby
thisConnector(youwouldwantthisonanSSLConnector).
Thedefaultvalueisfalse.
URIEncoding
ThisspecifiesthecharacterencodingusedtodecodetheURI
bytes,after%xxdecodingtheURL.Ifnotspecified,ISO8859
1willbeused.
useBodyEncodingForURI
ThisspecifiesiftheencodingspecifiedincontentTypeshould
beusedforURIqueryparameters,insteadofusingthe
URIEncoding.Thissettingispresentforcompatibilitywith
Tomcat4.1.x,wheretheencodingspecifiedinthecontentType,
orexplicitlysetusingRequest.setCharacterEncodingmethod
wasalsousedfortheparametersfromtheURL.Thedefault
valueisfalse.
useIPVHosts
SetthisattributetotruetocauseTomcattousetheIPaddress
thattherequestwasreceivedontodeterminetheHosttosend
therequestto.Thedefaultvalueisfalse.
xpoweredBy
SetthisattributetotruetocauseTomcattoadvertisesupport
fortheServletspecificationusingtheheaderrecommendedin
thespecification.Thedefaultvalueisfalse.
StandardImplementation
HTTPsupportsthefollowingadditionalattributes(inadditiontothecommonattributeslisted
above):
Attribute Description
acceptCount
Themaximumqueuelengthforincomingconnection
requestswhenallpossiblerequestprocessingthreadsarein
use.Anyrequestsreceivedwhenthequeueisfullwillbe
refused.Thedefaultvalueis100.
address
ForserverswithmorethanoneIPaddress,thisattribute
specifieswhichaddresswillbeusedforlisteningonthe
specifiedport.Bydefault,thisportwillbeusedonallIP
addressesassociatedwiththeserver.
bufferSize
Thesize(inbytes)ofthebuffertobeprovidedforinput
streamscreatedbythisconnector.Bydefault,buffersof2048
byteswillbeprovided.
compressableMimeType
ThevalueisacommaseparatedlistofMIMEtypesfor
whichHTTPcompressionmaybeused.Thedefaultvalueis
text/html,text/xml,text/plain.
compression
TheConnectormayuseHTTP/1.1GZIPcompressioninan
attempttosaveserverbandwidth.Theacceptablevaluesfor
theparameteris"off"(disablecompression),"on"(allow
compression,whichcausestextdatatobecompressed),
"force"(forcescompressioninallcases),oranumerical
integervalue(whichisequivalentto"on",butspecifiesthe
minimumamountofdatabeforetheoutputiscompressed).If
thecontentlengthisnotknownandcompressionissetto
"on"ormoreaggressive,theoutputwillalsobecompressed.
Ifnotspecified,thisattributeissetto"off".
connectionLinger
Thenumberofmillisecondsduringwhichthesocketsused
bythisConnectorwilllingerwhentheyareclosed.The
defaultvalueis1(socketlingerisdisabled).
connectionTimeout
ThenumberofmillisecondsthisConnectorwillwait,after
acceptingaconnection,fortherequestURIlinetobe
presented.Thedefaultvalueis60000(i.e.60seconds).
disableUploadTimeout
Thisflagallowstheservletcontainertouseadifferent,longer
connectiontimeoutwhileaservletisbeingexecuted,which
intheendallowseithertheservletalongeramountoftimeto
completeitsexecution,oralongertimeoutduringdata
upload.Ifnotspecified,thisattributeissetto"true".
maxHeaderCount
Themaximumnumberofheadersinarequestthatare
allowedbythecontainer.Arequestthatcontainsmore
headersthanthespecifiedlimitwillberejected.Avalueof
lessthan0meansnolimit.Ifnotspecified,adefaultof100is
used.
maxHttpHeaderSize
ThemaximumsizeoftherequestandresponseHTTP
header,specifiedinbytes.Ifnotspecified,thisattributeisset
to4096(4KB).
maxKeepAliveRequests
ThemaximumnumberofHTTPrequestswhichcanbe
pipelineduntiltheconnectionisclosedbytheserver.Setting
thisattributeto1willdisableHTTP/1.0keepalive,aswellas
HTTP/1.1keepaliveandpipelining.Settingthisto1will
allowanunlimitedamountofpipelinedorkeepaliveHTTP
requests.Ifnotspecified,thisattributeissetto100.
maxSpareThreads
Themaximumnumberofunusedrequestprocessingthreads
thatwillbeallowedtoexistuntilthethreadpoolstarts
stoppingtheunnecessarythreads.Thedefaultvalueis50.
maxThreads
Themaximumnumberofrequestprocessingthreadstobe
createdbythisConnector,whichthereforedeterminesthe
maximumnumberofsimultaneousrequeststhatcanbe
handled.Ifnotspecified,thisattributeissetto200.
minSpareThreads
Thenumberofrequestprocessingthreadsthatwillbecreated
whenthisConnectorisfirststarted.Theconnectorwillalso
makesureithasthespecifiednumberofidleprocessing
threadsavailable.Thisattributeshouldbesettoavalue
smallerthanthatsetformaxThreads.Thedefaultvalueis4.
noCompressionUserAgents
Thevalueisacommaseparatedlistofregularexpressions
matchinguseragentsofHTTPclientsforwhichcompression
shouldnotbeused,becausetheseclients,althoughtheydo
advertisesupportforthefeature,haveabroken
implementation.ThedefaultvalueisanemptyString(regexp
matchingdisabled).
port
TheTCPportnumberonwhichthisConnectorwillcreatea
serversocketandawaitincomingconnections.Your
operatingsystemwillallowonlyoneserverapplicationto
listentoaparticularportnumberonaparticularIPaddress.
restrictedUserAgents
Thevalueisacommaseparatedlistofregularexpressions
matchinguseragentsofHTTPclientsforwhichHTTP/1.1
orHTTP/1.0keepaliveshouldnotbeused,evenifthe
clientsadvertisesupportforthesefeatures.Thedefaultvalue
isanemptyString(regexpmatchingdisabled).
server
OverridestheServerheaderforthehttpresponse.Ifset,the
valueforthisattributeoverridestheTomcatdefaultandany
Serverheadersetbyawebapplication.Ifnotset,anyvalue
specifiedbytheapplicationisused.Iftheapplicationdoes
notspecifyavaluethenApache-Coyote/1.1isused.Unless
youareparanoid,youwon'tneedthisfeature.
socketBuffer
Thesize(inbytes)ofthebuffertobeprovidedforsocket
outputbuffering.1canbespecifiedtodisabletheuseofa
buffer.Bydefault,abuffersof9000byteswillbeused.
strategy
Thethreadpoolingstrategywhichwillbeused.Thedefault
strategydoesnotuseamasterthread,butamore
conventionalstrategyusingamasterlistenerthreadcanbe
usedbysetting"ms"asthisattribute'svalue.Themaster
strategywillworksignificantlybetterusingthethreadPriority
attribute,whichwillapplyonlytothethreadwhichlistenson
theserversocket.Thisissettolfbydefault.
tcpNoDelay
Ifsettotrue,theTCP_NO_DELAYoptionwillbeseton
theserversocket,whichimprovesperformanceundermost
circumstances.Thisissettotruebydefault.
threadPriority
Thepriorityoftherequestprocessingthreadswithinthe
JVM.Thedefaultvalueis
java.lang.Thread#NORM_PRIORITY.SeetheJavaDocfor
thejava.lang.Threadclassformoredetailsonwhatthis
prioritymeans.
NestedComponents
Noneatthistime.
SpecialFeatures
HTTP/1.1andHTTP/1.0Support
ThisConnectorsupportsalloftherequiredfeaturesoftheHTTP/1.1protocol,asdescribedin
RFC2616,includingpersistentconnections,pipelining,expectationsandchunkedencoding.If
theclient(typicallyabrowser)supportsonlyHTTP/1.0,theConnectorwillgracefullyfall
backtosupportingthisprotocolaswell.Nospecialconfigurationisrequiredtoenablethis
support.TheConnectoralsosupportsHTTP/1.0keepalive.
RFC2616requiresthatHTTPserversalwaysbegintheirresponseswiththehighestHTTP
versionthattheyclaimtosupport.Therefore,thisConnectorwillalwaysreturnHTTP/1.1at
thebeginningofitsresponses.
ProxySupport
TheproxyNameandproxyPortattributescanbeusedwhenTomcatisrunbehindaproxy
server.Theseattributesmodifythevaluesreturnedtowebapplicationsthatcallthe
request.getServerName()andrequest.getServerPort()methods,whichareoftenused
toconstructabsoluteURLsforredirects.Withoutconfiguringtheseattributes,thevalues
returnedwouldreflecttheservernameandportonwhichtheconnectionfromtheproxyserver
wasreceived,ratherthantheservernameandporttowhomtheclientdirectedtheoriginal
request.
Formoreinformation,seetheProxySupportHOWTO.
SSLSupport
YoucanenableSSLsupportforaparticularinstanceofthisConnectorbysettingthesecure
attributetotrue.Inaddition,youmayneedtoconfigurethefollowingattributes:
Attribute Description
algorithm
Thecertificateencodingalgorithmtobeused.This
defaultstotheSunimplementation(SunX509).For
IBMJVMsyoushouldusethevalueIbmX509.For
othervendors,consulttheJVMdocumentationfor
thecorrectvalue.
clientAuth
SettotrueifyouwanttheSSLstacktorequirea
validcertificatechainfromtheclientbefore
acceptingaconnection.Settowantifyouwantthe
SSLstacktorequestaclientCertificate,butnotfail
ifoneisn'tpresented.Afalsevalue(whichisthe
default)willnotrequireacertificatechainunlessthe
clientrequestsaresourceprotectedbyasecurity
constraintthatusesCLIENT-CERTauthentication.
SeetheSSLHowToforanexample.ThatSSL
HowToalsocontainstipsonusingperuserorper
sessioncertificatebasedclientAuth.
keystoreFile
Thepathnameofthekeystorefilewhereyouhave
storedtheservercertificatetobeloaded.Bydefault,
thepathnameisthefile".keystore"inthe
operatingsystemhomedirectoryoftheuserthatis
runningTomcat.
keystorePass
Thepasswordusedtoaccesstheservercertificate
fromthespecifiedkeystorefile.Thedefaultvalueis
"changeit".
keystoreType
Thetypeofkeystorefiletobeusedfortheserver
certificate.Ifnotspecified,thedefaultvalueis
"JKS".
sslProtocol
TheversionoftheSSLprotocoltouse.Ifnot
specified,thedefaultis"TLS".
ciphers
Thecommaseparatedlistofencryptionciphersthat
thissocketisallowedtouse.Bydefault,thedefault
ciphersfortheJVMwillbeused.Notethatthis
usuallymeansthattheweakexportgradeciphers
willbeincludedinthelistofavailableciphers.The
ciphersarespecifiedusingtheJSSEciphernaming
convention.
keyAlias
Thealiasusedtofortheservercertificateinthe
keystore.Ifnotspecifiedthefirstkeyreadinthe
keystorewillbeused.
truststoreFile
Thetruststorefiletousetovalidateclient
certificates.Thedefaultisthevalueofthe
javax.net.ssl.trustStoresystemproperty.If
neitherthisattributenorthedefaultsystemproperty
isset,notruststorewillbeconfigured.
truststorePass
Thepasswordtoaccessthetruststore.Thedefaultis
thevalueofthe
javax.net.ssl.trustStorePasswordsystem
property.Ifthatpropertyisnull,thevalueof
keystorePassisusedasthedefault.Ifneitherthis
attribute,thedefaultsystempropertynor
keystorePassisset,notruststorewillbe
configured.
truststoreType
Thetypeofkeystoreusedforthetruststore.The
defaultisthevalueofthe
javax.net.ssl.trustStoreTypesystemproperty.
Ifthatpropertyisnull,thevalueofkeystoreTypeis
usedasthedefault.
allowUnsafeLegacyRenegotiation
IsunsafelegacyTLSrenegotiationallowedwhichis
likelytoexposeuserstoCVE20093555,amanin
themiddlevulnerabilityintheTLSprotocolthat
allowsanattackertoinjectarbitrarydataintothe
user'srequest.Ifnotspecified,adefaultoffalseis
used.ThisattributeonlyhasaneffectiftheJVM
doesnotsupportRFC5746asindicatedbythe
presenceofthepseudociphersuite
TLS_EMPTY_RENEGOTIATION_INFO_SCSV.
ThisisavailableJRE/JDK6update22onwards.
WhereRFC5746issupportedtherenegotiation
includingsupportforunsafelegacyrenegotiationis
controlledbytheJVMconfiguration.
Formoreinformation,seetheSSLConfigurationHOWTO.
Copyright19992012,ApacheSoftwareFoundation