Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 37 ยท Configuration

Connectors and Thread Pools

Configure Tomcat connectors: HTTP/1.1 and AJP, port, protocol, maxThreads, acceptCount, maxConnections, timeouts, compression, HTTP/2 and shared Executors, with Java stand-ins that model queues.

The Connector is the door through which traffic enters Tomcat. It decides which port to listen on, which protocol to speak (HTTP/1.1, HTTP/2, AJP), how many connections to hold and how many threads to run your code on. Almost every Tomcat performance conversation begins here, so it is worth understanding what each number means rather than copying values from a forum.

This lesson explains the main attributes, the three queues a request can wait in, the shared Executor and the model "how many threads do I need". The XML is read-only; the stand-ins are plain Java models you can run and change.

A connector in server.xml

XML
<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443"
           maxThreads="200"
           minSpareThreads="10"
           acceptCount="100"
           maxConnections="8192"
           maxKeepAliveRequests="100"
           keepAliveTimeout="20000"
           compression="on"
           compressionMinSize="2048"
           compressibleMimeType="text/html,text/css,application/json,application/javascript"
           URIEncoding="UTF-8" />

protocol="HTTP/1.1" selects the default implementation, which is NIO (non-blocking I/O with a poller) on current versions. Older versions offered BIO and APR; use NIO, or NIO2 for a variant based on asynchronous channels. For TLS the connector uses the same protocol with SSLEnabled="true" (TLS lessons in the security chapter).

Three limits on the way in

maxConnections Open sockets the connector manages
acceptCount Waiting queue when that is full
maxThreads Threads that run your code

Past all three, clients are refused.

1 / 2

The attributes that matter

Attribute Default Meaning
port none TCP port. 0 picks a free one (useful for tests). Ports below 1024 need privileges on Unix; use a proxy or port redirection instead of running as root.
address all interfaces Bind to one IP, e.g. 127.0.0.1 when a proxy on the same host is the only client.
maxThreads 200 Maximum request-processing threads.
minSpareThreads 10 Threads kept ready.
maxConnections 8192 (NIO) Connections the server accepts and keeps open at once.
acceptCount 100 Operating-system queue length for new connections once maxConnections is reached.
connectionTimeout 60000 (server.xml ships 20000) Milliseconds to wait for the request after accepting the connection.
keepAliveTimeout same as connectionTimeout How long an idle keep-alive connection stays open.
maxKeepAliveRequests 100 Requests per connection before closing; -1 is unlimited.
maxPostSize 2 MB Limit for form-encoded POST bodies parsed by the container.
maxParameterCount 10000 Cap on parameters, to blunt hash-collision attacks.
redirectPort none Where to redirect when a constraint requires CONFIDENTIAL transport.
proxyName, proxyPort, scheme, secure Tell Tomcat the public identity when behind a proxy.

Header size limits (the connector rejects overly large request lines or headers with 400) are controlled by maxHttpHeaderSize (8 KB default; the newest releases renamed it to maxHttpRequestHeaderSize and added a separate response limit), which matters for applications that store large cookies or tokens.

Where does a request wait?

flowchart LR
    C["Client"] --> A["OS accept queue<br/>acceptCount"]
    A --> P["Poller and connections<br/>maxConnections"]
    P --> Q["Executor task queue"]
    Q --> T["Worker threads<br/>maxThreads"]
    T --> S["Your servlet"]

Think of it as a funnel. A full stage pushes back on the one before it.

When all worker threads are busy, requests wait in the executor's queue. When maxConnections sockets are in use, new connections wait in the OS backlog (acceptCount). When that fills too, the OS refuses or ignores connection attempts and clients see timeouts or "connection refused". The numbers form a funnel: it only makes sense for maxConnections to be much bigger than maxThreads, because idle keep-alive connections cost memory but not threads.

The stand-in models the first and last stages with a ThreadPoolExecutor: two workers and a queue of three. Eight slow "requests" arrive at once; the pool runs two, queues three and rejects three (the "connection refused" case):

Java Workers, queue and rejection (simplified model)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

How many threads do you need?

A useful rule is Little's Law: the average number of requests in the system equals the arrival rate times the average time each takes. If you receive 400 requests per second and each takes 150 ms on a worker thread, you need about 400 * 0.150 = 60 threads busy on average, and you want headroom for bursts, so perhaps 100 to 150. A value of 200 (the default) is plenty for most applications; raising maxThreads to 2000 rarely helps and often hurts, because more threads mean more memory (each stack), more context switching and more simultaneous load on the database.

The real bottleneck is usually downstream: a database pool of 20 connections limits you to roughly 20 concurrent queries no matter how many Tomcat threads you have. Size the layers together.

Java Thread sizing with Little's Law (stand-in calculator)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

A shared Executor

Instead of each connector owning its threads, define one Executor in the Service and let connectors share it (HTTP and HTTPS then draw from the same pool):

XML
<Service name="Catalina">
  <Executor name="tomcatThreadPool" namePrefix="catalina-exec-"
            maxThreads="150" minSpareThreads="4" maxIdleTime="60000" />

  <Connector port="8080" protocol="HTTP/1.1" executor="tomcatThreadPool"
             connectionTimeout="20000" redirectPort="8443" />
  <Connector port="8443" protocol="HTTP/1.1" executor="tomcatThreadPool"
             SSLEnabled="true" scheme="https" secure="true">
    <SSLHostConfig>
      <Certificate certificateKeystoreFile="conf/keystore.p12" type="RSA" />
    </SSLHostConfig>
  </Connector>
  ...
</Service>

With a named executor, the connector's own maxThreads is ignored, and thread names follow namePrefix (catalina-exec-1...). Thread names are useful in thread dumps.

HTTP/2 and compression

HTTP/2 multiplexes many requests over one connection. In Tomcat you add an upgrade protocol inside the connector; browsers only use it over TLS:

XML
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true" scheme="https" secure="true">
  <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
  <SSLHostConfig>...</SSLHostConfig>
</Connector>

compression="on" makes Tomcat gzip responses of the listed MIME types larger than compressionMinSize. If an Nginx proxy in front already compresses, turn it off in one of the two places so you do not compress twice.

AJP: usually off

The AJP connector connected Apache httpd to Tomcat with a binary protocol. Since the 2020 "Ghostcat" vulnerability it requires a secret (Tomcat 9.0.31 and later; the requiredSecret attribute) and is disabled in new default configurations. Prefer plain HTTP between proxy and Tomcat, bound to a private address.

Common mistakes

  • Raising maxThreads to 5000 hoping to fix slowness caused by a slow database.
  • Setting acceptCount high and maxConnections low, so requests wait invisibly in the OS queue.
  • Using a very small connectionTimeout, which drops clients on slow mobile links; or -1 (infinite), which lets idle sockets pile up.
  • Leaving maxPostSize and parameter limits at defaults for a public upload form, or setting them to unlimited.
  • Forgetting proxyName, scheme or RemoteIpValve behind a proxy, so redirects point to http://localhost:8080.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does maxThreads control?

    maxThreads (default 200) caps how many requests are executed in parallel by the connector or its executor.
  2. 2. When all maxConnections slots are in use, where do new connection attempts wait?

    acceptCount is the backlog of pending connections; beyond it clients are refused or time out.
  3. 3. At 200 requests per second and 0.25 s per request, how many threads are busy on average (Little's Law)?

    200 x 0.25 = 50 concurrent requests on average. Add headroom for bursts.
  4. 4. Why is a shared Executor useful?

    A named executor in the Service is referenced by several connectors, giving one limit and recognizable thread names.

Summary

  • A <Connector> sets port, protocol (NIO by default), timeouts and limits for incoming traffic.
  • Requests pass three limits: maxConnections, acceptCount and maxThreads.
  • Size threads with Little's Law and match the database pool; more threads are not automatically faster.
  • A named <Executor> lets connectors share a pool; HTTP/2 uses UpgradeProtocol; AJP is optional and needs a secret.
  • Set proxy-related attributes when Tomcat sits behind Nginx or httpd.

Next: web.xml and URL mapping