TheApacheTomcat5.5Servlet/JSPContainer

ApacheTomcatConfigurationReferenceTheHTTPConnector

TableofContentsIntroductionAttributes

1. CommonAttributes2. StandardImplementation

NestedComponentsSpecialFeatures

1. HTTP/1.1andHTTP/1.0Support2. ProxySupport3. SSLSupport

IntroductionTheHTTPConnectorelementrepresentsaConnectorcomponentthatsupportstheHTTP/1.1protocol.ItenablesCatalinatofunctionasastandalonewebserver,inadditiontoitsabilitytoexecuteservletsandJSPpages.AparticularinstanceofthiscomponentlistensforconnectionsonaspecificTCPportnumberontheserver.OneormoresuchConnectorscanbeconfiguredaspartofasingleService,eachforwardingtotheassociatedEnginetoperformrequestprocessingandcreatetheresponse.

IfyouwishtoconfiguretheConnectorthatisusedforconnectionstowebserversusingtheAJPprotocol(suchasthemod_jk 1.2.xconnectorforApache1.3),seehereinstead.

Atserverstartuptime,thisConnectorwillcreateanumberofrequestprocessingthreads(basedonthevalueconfiguredfortheminSpareThreadsattribute).Eachincomingrequestrequiresathreadforthedurationofthatrequest.Ifmoresimultaneousrequestsarereceivedthancanbehandledbythecurrentlyavailablerequestprocessingthreads,additionalthreadswillbecreateduptotheconfiguredmaximum(thevalueofthemaxThreadsattribute).Ifstillmoresimultaneousrequestsarereceived,theyarestackedupinsidetheserversocketcreatedbytheConnector,uptotheconfiguredmaximum(thevalueoftheacceptCountattribute).Anyfurthersimultaneousrequestswillreceive"connectionrefused"errors,untilresourcesareavailabletoprocessthem.

Attributes

CommonAttributesAllimplementationsofConnectorsupportthefollowingattributes:

Attribute Description

allowTraceAbooleanvaluewhichcanbeusedtoenableordisabletheTRACEHTTPmethod.Ifnotspecified,thisattributeissettofalse.

emptySessionPath

Ifsettotrue,allpathsforsessioncookieswillbesetto/.Thiscanbeusefulforportletspecificationimplementations,butwillgreatlyaffectperformanceifmanyapplicationsareaccessedonagivenserverbytheclient.Ifnotspecified,thisattributeissettofalse.

enableLookups

Settotrueifyouwantcallstorequest.getRemoteHost()toperformDNSlookupsinordertoreturntheactualhostnameoftheremoteclient.SettofalsetoskiptheDNSlookupandreturntheIPaddressinStringforminstead(therebyimprovingperformance).Bydefault,DNSlookupsareenabled.

maxParameterCount

Themaximumnumberofparameters(GETplusPOST)whichwillbeautomaticallyparsedbythecontainer.Avalueoflessthan0meansnolimit.Ifnotspecified,adefaultof10000isused.NotethatFailedRequestFilterfiltercanbeusedtorejectrequeststhathitthelimit.

maxPostSize

ThemaximumsizeinbytesofthePOSTwhichwillbehandledbythecontainerFORMURLparameterparsing.Thelimitcanbedisabledbysettingthisattributetoavaluelessthanorequalto0.Ifnotspecified,thisattributeissetto2097152(2megabytes).

maxSavePostSize

ThemaximumsizeinbytesofthePOSTwhichwillbesaved/bufferedbythecontainerduringFORMorCLIENTCERTauthentication.Forbothtypesofauthentication,thePOSTwillbesaved/bufferedbeforetheuserisauthenticated.ForCLIENTCERTauthentication,thePOSTisbufferedforthedurationoftheSSLhandshakeandthebufferemptiedwhentherequestisprocessed.ForFORMauthenticationthePOSTissavedwhilsttheuserisredirectedtotheloginformandisretaineduntiltheusersuccessfullyauthenticatesorthesessionassociatedwiththeauthenticationrequestexpires.Thelimitcanbedisabledbysettingthisattributeto1.SettingtheattributetozerowilldisablethesavingofPOSTdataduringauthentication.Ifnotspecified,thisattributeissetto4096(4kilobytes).

protocolThisattributevaluemustbeHTTP/1.1tousetheHTTPhandler,whichisthedefault.

proxyName

IfthisConnectorisbeingusedinaproxyconfiguration,configurethisattributetospecifytheservernametobereturnedforcallstorequest.getServerName().SeeProxySupportformoreinformation.

proxyPort

IfthisConnectorisbeingusedinaproxyconfiguration,configurethisattributetospecifytheserverporttobereturnedforcallstorequest.getServerPort().SeeProxySupportformoreinformation.

redirectPort

IfthisConnectorissupportingnonSSLrequests,andarequestisreceivedforwhichamatchingrequiresSSLtransport,Catalinawillautomaticallyredirecttherequesttotheportnumberspecifiedhere.

scheme

Setthisattributetothenameoftheprotocolyouwishtohavereturnedbycallstorequest.getScheme().Forexample,you

wouldsetthisattributeto"https"foranSSLConnector.Thedefaultvalueis"http".SeeSSLSupportformoreinformation.

secure

Setthisattributetotrueifyouwishtohavecallstorequest.isSecure()toreturntrueforrequestsreceivedbythisConnector(youwouldwantthisonanSSLConnector).Thedefaultvalueisfalse.

URIEncodingThisspecifiesthecharacterencodingusedtodecodetheURIbytes,after%xxdecodingtheURL.Ifnotspecified,ISO88591willbeused.

useBodyEncodingForURI

ThisspecifiesiftheencodingspecifiedincontentTypeshouldbeusedforURIqueryparameters,insteadofusingtheURIEncoding.ThissettingispresentforcompatibilitywithTomcat4.1.x,wheretheencodingspecifiedinthecontentType,orexplicitlysetusingRequest.setCharacterEncodingmethodwasalsousedfortheparametersfromtheURL.Thedefaultvalueisfalse.

useIPVHostsSetthisattributetotruetocauseTomcattousetheIPaddressthattherequestwasreceivedontodeterminetheHosttosendtherequestto.Thedefaultvalueisfalse.

xpoweredBySetthisattributetotruetocauseTomcattoadvertisesupportfortheServletspecificationusingtheheaderrecommendedinthespecification.Thedefaultvalueisfalse.

StandardImplementationHTTPsupportsthefollowingadditionalattributes(inadditiontothecommonattributeslistedabove):

Attribute Description

acceptCount

Themaximumqueuelengthforincomingconnectionrequestswhenallpossiblerequestprocessingthreadsareinuse.Anyrequestsreceivedwhenthequeueisfullwillberefused.Thedefaultvalueis100.

address

ForserverswithmorethanoneIPaddress,thisattributespecifieswhichaddresswillbeusedforlisteningonthespecifiedport.Bydefault,thisportwillbeusedonallIPaddressesassociatedwiththeserver.

bufferSizeThesize(inbytes)ofthebuffertobeprovidedforinputstreamscreatedbythisconnector.Bydefault,buffersof2048byteswillbeprovided.

compressableMimeTypeThevalueisacommaseparatedlistofMIMEtypesforwhichHTTPcompressionmaybeused.Thedefaultvalueistext/html,text/xml,text/plain.

compression

TheConnectormayuseHTTP/1.1GZIPcompressioninanattempttosaveserverbandwidth.Theacceptablevaluesfortheparameteris"off"(disablecompression),"on"(allowcompression,whichcausestextdatatobecompressed),"force"(forcescompressioninallcases),oranumericalintegervalue(whichisequivalentto"on",butspecifiesthe

minimumamountofdatabeforetheoutputiscompressed).Ifthecontentlengthisnotknownandcompressionissetto"on"ormoreaggressive,theoutputwillalsobecompressed.Ifnotspecified,thisattributeissetto"off".

connectionLingerThenumberofmillisecondsduringwhichthesocketsusedbythisConnectorwilllingerwhentheyareclosed.Thedefaultvalueis1(socketlingerisdisabled).

connectionTimeoutThenumberofmillisecondsthisConnectorwillwait,afteracceptingaconnection,fortherequestURIlinetobepresented.Thedefaultvalueis60000(i.e.60seconds).

disableUploadTimeout

Thisflagallowstheservletcontainertouseadifferent,longerconnectiontimeoutwhileaservletisbeingexecuted,whichintheendallowseithertheservletalongeramountoftimetocompleteitsexecution,oralongertimeoutduringdataupload.Ifnotspecified,thisattributeissetto"true".

maxHeaderCount

Themaximumnumberofheadersinarequestthatareallowedbythecontainer.Arequestthatcontainsmoreheadersthanthespecifiedlimitwillberejected.Avalueoflessthan0meansnolimit.Ifnotspecified,adefaultof100isused.

maxHttpHeaderSizeThemaximumsizeoftherequestandresponseHTTPheader,specifiedinbytes.Ifnotspecified,thisattributeissetto4096(4KB).

maxKeepAliveRequests

ThemaximumnumberofHTTPrequestswhichcanbepipelineduntiltheconnectionisclosedbytheserver.Settingthisattributeto1willdisableHTTP/1.0keepalive,aswellasHTTP/1.1keepaliveandpipelining.Settingthisto1willallowanunlimitedamountofpipelinedorkeepaliveHTTPrequests.Ifnotspecified,thisattributeissetto100.

maxSpareThreadsThemaximumnumberofunusedrequestprocessingthreadsthatwillbeallowedtoexistuntilthethreadpoolstartsstoppingtheunnecessarythreads.Thedefaultvalueis50.

maxThreads

ThemaximumnumberofrequestprocessingthreadstobecreatedbythisConnector,whichthereforedeterminesthemaximumnumberofsimultaneousrequeststhatcanbehandled.Ifnotspecified,thisattributeissetto200.

minSpareThreads

ThenumberofrequestprocessingthreadsthatwillbecreatedwhenthisConnectorisfirststarted.Theconnectorwillalsomakesureithasthespecifiednumberofidleprocessingthreadsavailable.ThisattributeshouldbesettoavaluesmallerthanthatsetformaxThreads.Thedefaultvalueis4.

noCompressionUserAgents

ThevalueisacommaseparatedlistofregularexpressionsmatchinguseragentsofHTTPclientsforwhichcompressionshouldnotbeused,becausetheseclients,althoughtheydoadvertisesupportforthefeature,haveabrokenimplementation.ThedefaultvalueisanemptyString(regexpmatchingdisabled).

portTheTCPportnumberonwhichthisConnectorwillcreateaserversocketandawaitincomingconnections.YouroperatingsystemwillallowonlyoneserverapplicationtolistentoaparticularportnumberonaparticularIPaddress.

restrictedUserAgents

ThevalueisacommaseparatedlistofregularexpressionsmatchinguseragentsofHTTPclientsforwhichHTTP/1.1orHTTP/1.0keepaliveshouldnotbeused,eveniftheclientsadvertisesupportforthesefeatures.ThedefaultvalueisanemptyString(regexpmatchingdisabled).

server

OverridestheServerheaderforthehttpresponse.Ifset,thevalueforthisattributeoverridestheTomcatdefaultandanyServerheadersetbyawebapplication.Ifnotset,anyvaluespecifiedbytheapplicationisused.IftheapplicationdoesnotspecifyavaluethenApache-Coyote/1.1isused.Unlessyouareparanoid,youwon'tneedthisfeature.

socketBufferThesize(inbytes)ofthebuffertobeprovidedforsocketoutputbuffering.1canbespecifiedtodisabletheuseofabuffer.Bydefault,abuffersof9000byteswillbeused.

strategy

Thethreadpoolingstrategywhichwillbeused.Thedefaultstrategydoesnotuseamasterthread,butamoreconventionalstrategyusingamasterlistenerthreadcanbeusedbysetting"ms"asthisattribute'svalue.ThemasterstrategywillworksignificantlybetterusingthethreadPriorityattribute,whichwillapplyonlytothethreadwhichlistensontheserversocket.Thisissettolfbydefault.

tcpNoDelayIfsettotrue,theTCP_NO_DELAYoptionwillbesetontheserversocket,whichimprovesperformanceundermostcircumstances.Thisissettotruebydefault.

threadPriority

ThepriorityoftherequestprocessingthreadswithintheJVM.Thedefaultvalueisjava.lang.Thread#NORM_PRIORITY.SeetheJavaDocforthejava.lang.Threadclassformoredetailsonwhatthisprioritymeans.

NestedComponentsNoneatthistime.

SpecialFeaturesHTTP/1.1andHTTP/1.0Support

ThisConnectorsupportsalloftherequiredfeaturesoftheHTTP/1.1protocol,asdescribedinRFC2616,includingpersistentconnections,pipelining,expectationsandchunkedencoding.Iftheclient(typicallyabrowser)supportsonlyHTTP/1.0,theConnectorwillgracefullyfallbacktosupportingthisprotocolaswell.Nospecialconfigurationisrequiredtoenablethissupport.TheConnectoralsosupportsHTTP/1.0keepalive.

RFC2616requiresthatHTTPserversalwaysbegintheirresponseswiththehighestHTTPversionthattheyclaimtosupport.Therefore,thisConnectorwillalwaysreturnHTTP/1.1atthebeginningofitsresponses.

ProxySupportTheproxyNameandproxyPortattributescanbeusedwhenTomcatisrunbehindaproxyserver.Theseattributesmodifythevaluesreturnedtowebapplicationsthatcalltherequest.getServerName()andrequest.getServerPort()methods,whichareoftenusedtoconstructabsoluteURLsforredirects.Withoutconfiguringtheseattributes,thevaluesreturnedwouldreflecttheservernameandportonwhichtheconnectionfromtheproxyserverwasreceived,ratherthantheservernameandporttowhomtheclientdirectedtheoriginalrequest.

Formoreinformation,seetheProxySupportHOWTO.

SSLSupportYoucanenableSSLsupportforaparticularinstanceofthisConnectorbysettingthesecureattributetotrue.Inaddition,youmayneedtoconfigurethefollowingattributes:

Attribute Description

algorithm

Thecertificateencodingalgorithmtobeused.ThisdefaultstotheSunimplementation(SunX509).ForIBMJVMsyoushouldusethevalueIbmX509.Forothervendors,consulttheJVMdocumentationforthecorrectvalue.

clientAuth

SettotrueifyouwanttheSSLstacktorequireavalidcertificatechainfromtheclientbeforeacceptingaconnection.SettowantifyouwanttheSSLstacktorequestaclientCertificate,butnotfailifoneisn'tpresented.Afalsevalue(whichisthedefault)willnotrequireacertificatechainunlesstheclientrequestsaresourceprotectedbyasecurityconstraintthatusesCLIENT-CERTauthentication.SeetheSSLHowToforanexample.ThatSSLHowToalsocontainstipsonusingperuserorpersessioncertificatebasedclientAuth.

keystoreFile

Thepathnameofthekeystorefilewhereyouhavestoredtheservercertificatetobeloaded.Bydefault,thepathnameisthefile".keystore"intheoperatingsystemhomedirectoryoftheuserthatisrunningTomcat.

keystorePassThepasswordusedtoaccesstheservercertificatefromthespecifiedkeystorefile.Thedefaultvalueis"changeit".

keystoreTypeThetypeofkeystorefiletobeusedfortheservercertificate.Ifnotspecified,thedefaultvalueis"JKS".

sslProtocol TheversionoftheSSLprotocoltouse.Ifnotspecified,thedefaultis"TLS".

ciphers

Thecommaseparatedlistofencryptionciphersthatthissocketisallowedtouse.Bydefault,thedefaultciphersfortheJVMwillbeused.Notethatthisusuallymeansthattheweakexportgradecipherswillbeincludedinthelistofavailableciphers.The

ciphersarespecifiedusingtheJSSEciphernamingconvention.

keyAliasThealiasusedtofortheservercertificateinthekeystore.Ifnotspecifiedthefirstkeyreadinthekeystorewillbeused.

truststoreFile

Thetruststorefiletousetovalidateclientcertificates.Thedefaultisthevalueofthejavax.net.ssl.trustStoresystemproperty.Ifneitherthisattributenorthedefaultsystempropertyisset,notruststorewillbeconfigured.

truststorePass

Thepasswordtoaccessthetruststore.Thedefaultisthevalueofthejavax.net.ssl.trustStorePasswordsystemproperty.Ifthatpropertyisnull,thevalueofkeystorePassisusedasthedefault.Ifneitherthisattribute,thedefaultsystempropertynorkeystorePassisset,notruststorewillbeconfigured.

truststoreType

Thetypeofkeystoreusedforthetruststore.Thedefaultisthevalueofthejavax.net.ssl.trustStoreTypesystemproperty.Ifthatpropertyisnull,thevalueofkeystoreTypeisusedasthedefault.

allowUnsafeLegacyRenegotiation

IsunsafelegacyTLSrenegotiationallowedwhichislikelytoexposeuserstoCVE20093555,amaninthemiddlevulnerabilityintheTLSprotocolthatallowsanattackertoinjectarbitrarydataintotheuser'srequest.Ifnotspecified,adefaultoffalseisused.ThisattributeonlyhasaneffectiftheJVMdoesnotsupportRFC5746asindicatedbythepresenceofthepseudociphersuiteTLS_EMPTY_RENEGOTIATION_INFO_SCSV.ThisisavailableJRE/JDK6update22onwards.WhereRFC5746issupportedtherenegotiationincludingsupportforunsafelegacyrenegotiationiscontrolledbytheJVMconfiguration.

Formoreinformation,seetheSSLConfigurationHOWTO.

Copyright19992012,ApacheSoftwareFoundation